Troubleshooting 🔧

Wenn OpenClaw nicht richtig funktioniert, findest du hier die Lösung.

Schau dir zuerst die ersten 60 Sekunden im FAQ an, wenn du eine schnelle Triage-Anleitung brauchst. Diese Seite geht tiefer auf Runtime-Fehler und Diagnose ein.

Provider-spezifische Shortcuts: /channels/troubleshooting

Status & Diagnostics

Schnelle Triage-Befehle (in dieser Reihenfolge):

Befehl	Was er dir zeigt	Wann du ihn brauchst
`openclaw status`	Lokale Zusammenfassung: OS + Update, Gateway-Erreichbarkeit/Modus, Service, Agents/Sessions, Provider-Config-Status	Erste Prüfung, schneller Überblick
`openclaw status --all`	Vollständige lokale Diagnose (read-only, einfügbar, relativ sicher) inkl. Log-Tail	Wenn du einen Debug-Report teilen musst
`openclaw status --deep`	Führt Gateway-Health-Checks aus (inkl. Provider-Probes; erfordert erreichbares Gateway)	Wenn “konfiguriert” nicht “funktioniert” bedeutet
`openclaw gateway probe`	Gateway-Discovery + Erreichbarkeit (lokale + Remote-Ziele)	Wenn du vermutest, dass du das falsche Gateway prüfst
`openclaw channels status --probe`	Fragt das laufende Gateway nach Channel-Status (und prüft optional)	Wenn Gateway erreichbar ist, aber Channels nicht funktionieren
`openclaw gateway status`	Supervisor-Status (launchd/systemd/schtasks), Runtime-PID/Exit, letzter Gateway-Fehler	Wenn der Service “geladen aussieht”, aber nichts läuft
`openclaw logs --follow`	Live-Logs (bestes Signal für Runtime-Probleme)	Wenn du den tatsächlichen Fehlergrund brauchst

Output teilen: Nutze am besten openclaw status --all (es schwärzt Tokens). Wenn du openclaw status einfügst, setze vorher OPENCLAW_SHOW_SECRETS=0 (Token-Vorschauen).

Siehe auch: Health checks und Logging.

Common Issues

No API key found for provider “anthropic”

Das bedeutet, dass der Auth-Store des Agents leer ist oder Anthropic-Credentials fehlen. Auth ist pro Agent, also erbt ein neuer Agent nicht die Keys des Haupt-Agents.

Lösungen:

Führe das Onboarding erneut aus und wähle Anthropic für diesen Agent.

Oder füge ein Setup-Token auf dem Gateway-Host ein:

openclaw models auth setup-token --provider anthropic

Oder kopiere auth-profiles.json vom Haupt-Agent-Verzeichnis ins neue Agent-Verzeichnis.

Prüfen:

openclaw models status

OAuth token refresh failed (Anthropic Claude subscription)

Das bedeutet, dass das gespeicherte Anthropic OAuth-Token abgelaufen ist und die Aktualisierung fehlgeschlagen ist. Wenn du ein Claude-Abo hast (kein API-Key), ist die zuverlässigste Lösung, auf ein Claude Code Setup-Token zu wechseln und es auf dem Gateway-Host einzufügen.

Empfohlen (Setup-Token):

# Auf dem Gateway-Host ausführen (Setup-Token einfügen)
openclaw models auth setup-token --provider anthropic
openclaw models status

Wenn du das Token woanders generiert hast:

openclaw models auth paste-token --provider anthropic
openclaw models status

Mehr Details: Anthropic und OAuth.

Control UI fails on HTTP (“device identity required” / “connect failed”)

Wenn du das Dashboard über reines HTTP öffnest (z. B. http://<lan-ip>:18789/ oder http://<tailscale-ip>:18789/), läuft der Browser in einem nicht-sicheren Kontext und blockiert WebCrypto, sodass keine Device-Identity generiert werden kann.

Lösung:

Nutze HTTPS über Tailscale Serve.
Oder öffne es lokal auf dem Gateway-Host: http://127.0.0.1:18789/.
Wenn du bei HTTP bleiben musst, aktiviere gateway.controlUi.allowInsecureAuth: true und nutze ein Gateway-Token (nur Token; keine Device-Identity/Pairing). Siehe Control UI.

CI Secrets Scan Failed

Das bedeutet, dass detect-secrets neue Kandidaten gefunden hat, die noch nicht in der Baseline sind. Folge Secret scanning.

Service Installed but Nothing is Running

Wenn der Gateway-Service installiert ist, aber der Prozess sofort beendet wird, kann der Service “geladen” aussehen, während nichts läuft.

Prüfen:

openclaw gateway status
openclaw doctor

Doctor/Service zeigt den Runtime-Status (PID/letzter Exit) und Log-Hinweise.

Logs:

Bevorzugt: openclaw logs --follow
Datei-Logs (immer): /tmp/openclaw/openclaw-YYYY-MM-DD.log (oder dein konfiguriertes logging.file)
macOS LaunchAgent (falls installiert): $OPENCLAW_STATE_DIR/logs/gateway.log und gateway.err.log
Linux systemd (falls installiert): journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

Mehr Logging aktivieren:

Datei-Log-Detail erhöhen (persistiertes JSONL):
```
{ "logging": { "level": "debug" } }
```

Console-Verbosity erhöhen (nur TTY-Output):

{ "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }

Schneller Tipp: --verbose betrifft nur Console-Output. Datei-Logs werden weiterhin von logging.level gesteuert.

Siehe /logging für einen vollständigen Überblick über Formate, Config und Zugriff.

”Gateway start blocked: set gateway.mode=local”

Das bedeutet, dass die Config existiert, aber gateway.mode nicht gesetzt ist (oder nicht local), sodass das Gateway sich weigert zu starten.

Lösung (empfohlen):

Führe den Wizard aus und setze den Gateway-Run-Modus auf Local:
```
openclaw configure
```
Oder setze es direkt:
```
openclaw config set gateway.mode local
```

Wenn du stattdessen ein Remote-Gateway ausführen wolltest:

Setze eine Remote-URL und behalte gateway.mode=remote:

openclaw config set gateway.mode remote
openclaw config set gateway.remote.url "wss://gateway.example.com"

Nur ad-hoc/dev: Übergib --allow-unconfigured, um das Gateway ohne gateway.mode=local zu starten.

Noch keine Config-Datei? Führe openclaw setup aus, um eine Starter-Config zu erstellen, und starte dann das Gateway neu.

Service Environment (PATH + runtime)

Der Gateway-Service läuft mit einem minimalen PATH, um Shell/Manager-Cruft zu vermeiden:

macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
Linux: /usr/local/bin, /usr/bin, /bin

Das schließt absichtlich Version-Manager (nvm/fnm/volta/asdf) und Package-Manager (pnpm/npm) aus, weil der Service deine Shell-Init nicht lädt. Runtime-Variablen wie DISPLAY sollten in ~/.openclaw/.env liegen (wird früh vom Gateway geladen). Exec-Runs auf host=gateway mergen deinen Login-Shell-PATH in die Exec-Umgebung, sodass fehlende Tools normalerweise bedeuten, dass deine Shell-Init sie nicht exportiert (oder setze tools.exec.pathPrepend). Siehe /tools/exec.

WhatsApp + Telegram Channels benötigen Node; Bun wird nicht unterstützt. Wenn dein Service mit Bun oder einem version-managed Node-Pfad installiert wurde, führe openclaw doctor aus, um auf eine System-Node-Installation zu migrieren.

Skill missing API key in sandbox

Symptom: Skill funktioniert auf dem Host, schlägt aber in der Sandbox mit fehlendem API-Key fehl.

Warum: Sandboxed Exec läuft in Docker und erbt nicht das Host-process.env.

Lösung:

Setze agents.defaults.sandbox.docker.env (oder pro Agent agents.list[].sandbox.docker.env)
Oder backe den Key in dein Custom-Sandbox-Image ein
Dann führe openclaw sandbox recreate --agent <id> (oder --all) aus

Service Running but Port Not Listening

Wenn der Service als running gemeldet wird, aber nichts auf dem Gateway-Port lauscht, hat das Gateway wahrscheinlich das Binding verweigert.

Was “running” hier bedeutet

Runtime: running bedeutet, dass dein Supervisor (launchd/systemd/schtasks) denkt, der Prozess läuft.
RPC probe bedeutet, dass die CLI tatsächlich zum Gateway-WebSocket verbinden und status aufrufen konnte.
Vertraue immer Probe target: + Config (service): als die “was haben wir tatsächlich versucht?”-Zeilen.

Prüfen:

gateway.mode muss local sein für openclaw gateway und den Service.
Wenn du gateway.mode=remote setzt, nutzt die CLI standardmäßig eine Remote-URL. Der Service kann trotzdem lokal laufen, aber deine CLI prüft möglicherweise den falschen Ort. Nutze openclaw gateway status, um den aufgelösten Port + Probe-Target des Services zu sehen (oder übergib --url).
openclaw gateway status und openclaw doctor zeigen den letzten Gateway-Fehler aus den Logs, wenn der Service läuft, aber der Port geschlossen ist.
Non-Loopback-Binds (lan/tailnet/custom, oder auto wenn Loopback nicht verfügbar ist) benötigen Auth: gateway.auth.token (oder OPENCLAW_GATEWAY_TOKEN).
gateway.remote.token ist nur für Remote-CLI-Calls; es aktiviert nicht lokale Auth.
gateway.token wird ignoriert; nutze gateway.auth.token.

Wenn openclaw gateway status einen Config-Mismatch zeigt

Config (cli): ... und Config (service): ... sollten normalerweise übereinstimmen.
Wenn nicht, bearbeitest du fast sicher eine Config, während der Service eine andere ausführt.
Lösung: Führe openclaw gateway install --force vom selben --profile / OPENCLAW_STATE_DIR aus, das der Service nutzen soll.

Wenn openclaw gateway status Service-Config-Probleme meldet

Die Supervisor-Config (launchd/systemd/schtasks) fehlen aktuelle Defaults.
Lösung: Führe openclaw doctor aus, um sie zu aktualisieren (oder openclaw gateway install --force für ein vollständiges Rewrite).

Wenn Last gateway error: “refusing to bind … without auth” erwähnt

Du hast gateway.bind auf einen Non-Loopback-Modus (lan/tailnet/custom, oder auto wenn Loopback nicht verfügbar ist) gesetzt, aber keine Auth konfiguriert.
Lösung: Setze gateway.auth.mode + gateway.auth.token (oder exportiere OPENCLAW_GATEWAY_TOKEN) und starte den Service neu.

Wenn openclaw gateway status sagt bind=tailnet, aber kein Tailnet-Interface gefunden wurde

Das Gateway versuchte, an eine Tailscale-IP (100.64.0.0/10) zu binden, aber keine wurde auf dem Host erkannt.
Lösung: Starte Tailscale auf dieser Maschine (oder ändere gateway.bind zu loopback/lan).

Wenn Probe note: sagt, dass der Probe Loopback nutzt

Das ist für bind=lan erwartet: Das Gateway lauscht auf 0.0.0.0 (alle Interfaces), und Loopback sollte trotzdem lokal verbinden.
Für Remote-Clients nutze eine echte LAN-IP (nicht 0.0.0.0) plus Port und stelle sicher, dass Auth konfiguriert ist.

Address Already in Use (Port 18789)

Das bedeutet, dass etwas bereits auf dem Gateway-Port lauscht.

Prüfen:

openclaw gateway status

Es zeigt die Listener und wahrscheinliche Ursachen (Gateway läuft bereits, SSH-Tunnel). Falls nötig, stoppe den Service oder wähle einen anderen Port.

Extra Workspace Folders Detected

Wenn du von älteren Installationen upgradest, hast du möglicherweise noch ~/openclaw auf der Festplatte. Mehrere Workspace-Verzeichnisse können verwirrende Auth- oder State-Drift verursachen, weil nur ein Workspace aktiv ist.

Lösung: Behalte einen einzigen aktiven Workspace und archiviere/entferne den Rest. Siehe Agent workspace.

Main chat running in a sandbox workspace

Symptome: pwd oder File-Tools zeigen ~/.openclaw/sandboxes/..., obwohl du den Host-Workspace erwartet hast.

Warum: agents.defaults.sandbox.mode: "non-main" orientiert sich an session.mainKey (Standard "main"). Group/Channel-Sessions nutzen ihre eigenen Keys, werden also als non-main behandelt und bekommen Sandbox-Workspaces.

Lösungen:

Wenn du Host-Workspaces für einen Agent willst: Setze agents.list[].sandbox.mode: "off".
Wenn du Host-Workspace-Zugriff innerhalb der Sandbox willst: Setze workspaceAccess: "rw" für diesen Agent.

”Agent was aborted”

Der Agent wurde mitten in der Antwort unterbrochen.

Ursachen:

User hat stop, abort, esc, wait oder exit gesendet
Timeout überschritten
Prozess abgestürzt

Lösung: Sende einfach eine weitere Nachricht. Die Session läuft weiter.

”Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5”

OpenClaw lehnt absichtlich ältere/unsichere Modelle ab (besonders solche, die anfälliger für Prompt-Injection sind). Wenn du diesen Fehler siehst, wird der Modellname nicht mehr unterstützt.

Lösung:

Wähle ein aktuelles Modell für den Provider und aktualisiere deine Config oder deinen Model-Alias.
Wenn du unsicher bist, welche Modelle verfügbar sind, führe openclaw models list oder openclaw models scan aus und wähle ein unterstütztes.
Prüfe die Gateway-Logs für den detaillierten Fehlergrund.

Siehe auch: Models CLI und Model providers.

Messages Not Triggering

Check 1: Ist der Sender auf der Allowlist?

openclaw status

Suche nach AllowFrom: ... im Output.

Check 2: Für Gruppenchats, ist Mention erforderlich?

# Die Nachricht muss mentionPatterns oder explizite Mentions matchen; Defaults leben in Channel-Groups/Guilds.
# Multi-Agent: `agents.list[].groupChat.mentionPatterns` überschreibt globale Patterns.
grep -n "agents\\|groupChat\\|mentionPatterns\\|channels\\.whatsapp\\.groups\\|channels\\.telegram\\.groups\\|channels\\.imessage\\.groups\\|channels\\.discord\\.guilds" \
  "${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"

Check 3: Prüfe die Logs

openclaw logs --follow
# oder wenn du schnelle Filter willst:
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"

Pairing Code Not Arriving

Wenn dmPolicy auf pairing steht, sollten unbekannte Sender einen Code erhalten und ihre Nachricht wird ignoriert, bis sie genehmigt sind.

Check 1: Wartet bereits eine ausstehende Anfrage?

openclaw pairing list <channel>

Ausstehende DM-Pairing-Anfragen sind standardmäßig auf 3 pro Channel begrenzt. Wenn die Liste voll ist, generieren neue Anfragen keinen Code, bis eine genehmigt wird oder abläuft.

Check 2: Wurde die Anfrage erstellt, aber keine Antwort gesendet?

openclaw logs --follow | grep "pairing request"

Check 3: Bestätige, dass dmPolicy nicht open/allowlist für diesen Channel ist.

Image + Mention Not Working

Bekanntes Problem: Wenn du ein Bild mit NUR einer Mention sendest (kein anderer Text), enthält WhatsApp manchmal nicht die Mention-Metadaten.

Workaround: Füge etwas Text mit der Mention hinzu:

❌ @openclaw + Bild
✅ @openclaw check this + Bild

Session Not Resuming

Check 1: Ist die Session-Datei da?

ls -la ~/.openclaw/agents/<agentId>/sessions/

Check 2: Ist das Reset-Fenster zu kurz?

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 10080 // 7 Tage
    }
  }
}

Check 3: Hat jemand /new, /reset oder einen Reset-Trigger gesendet?

Agent Timing Out

Standard-Timeout ist 30 Minuten. Für lange Tasks:

{
  "reply": {
    "timeoutSeconds": 3600 // 1 Stunde
  }
}

Oder nutze das process-Tool, um lange Befehle im Hintergrund laufen zu lassen.

WhatsApp Disconnected

# Lokalen Status prüfen (Creds, Sessions, Queued Events)
openclaw status
# Gateway + Channels prüfen (WA-Connect + Telegram + Discord APIs)
openclaw status --deep

# Letzte Connection-Events anzeigen
openclaw logs --limit 200 | grep "connection\\|disconnect\\|logout"

Lösung: Verbindet sich normalerweise automatisch neu, sobald das Gateway läuft. Wenn du feststeckst, starte den Gateway-Prozess neu (wie auch immer du ihn überwachst), oder führe ihn manuell mit verbose Output aus:

openclaw gateway --verbose

Wenn du ausgeloggt / unlinked bist:

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # falls Logout nicht alles sauber entfernen kann
openclaw channels login --verbose       # QR erneut scannen

Media Send Failing

Check 1: Ist der Dateipfad gültig?

ls -la /path/to/your/image.jpg

Check 2: Ist die Datei zu groß?

Bilder: max 6MB
Audio/Video: max 16MB
Dokumente: max 100MB

Check 3: Prüfe Media-Logs

grep "media\\|fetch\\|download" "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | tail -20

High Memory Usage

OpenClaw hält die Conversation-History im Speicher.

Lösung: Starte regelmäßig neu oder setze Session-Limits:

{
  "session": {
    "historyLimit": 100 // Max Messages zum Behalten
  }
}

Common troubleshooting

”Gateway won’t start — configuration invalid”

OpenClaw weigert sich jetzt zu starten, wenn die Config unbekannte Keys, fehlerhafte Werte oder ungültige Typen enthält. Das ist absichtlich aus Sicherheitsgründen.

Behebe es mit Doctor:

openclaw doctor
openclaw doctor --fix

Hinweise:

openclaw doctor meldet jeden ungültigen Eintrag.
openclaw doctor --fix wendet Migrationen/Reparaturen an und schreibt die Config neu.
Diagnose-Befehle wie openclaw logs, openclaw health, openclaw status, openclaw gateway status und openclaw gateway probe laufen trotzdem, auch wenn die Config ungültig ist.

”All models failed” — what should I check first?

Credentials vorhanden für die Provider, die versucht werden (Auth-Profiles + Env-Vars).
Model-Routing: Bestätige, dass agents.defaults.model.primary und Fallbacks Modelle sind, auf die du Zugriff hast.
Gateway-Logs in /tmp/openclaw/… für den genauen Provider-Fehler.
Model-Status: Nutze /model status (Chat) oder openclaw models status (CLI).

I’m running on my personal WhatsApp number — why is self-chat weird?

Aktiviere Self-Chat-Modus und setze deine eigene Nummer auf die Allowlist:

{
  channels: {
    whatsapp: {
      selfChatMode: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123"],
    },
  },
}

Siehe WhatsApp setup.

WhatsApp logged me out. How do I re‑auth?

Führe den Login-Befehl erneut aus und scanne den QR-Code:

openclaw channels login

Build errors on `main` — what’s the standard fix path?

git pull origin main && pnpm install
openclaw doctor
Prüfe GitHub Issues oder Discord
Temporärer Workaround: Checke einen älteren Commit aus

npm install fails (allow-build-scripts / missing tar or yargs). What now?

Wenn du aus dem Source laufen lässt, nutze den Package-Manager des Repos: pnpm (bevorzugt). Das Repo deklariert packageManager: "pnpm@…".

Typische Wiederherstellung:

git status   # stelle sicher, dass du im Repo-Root bist
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

Warum: pnpm ist der konfigurierte Package-Manager für dieses Repo.

How do I switch between git installs and npm installs?

Nutze den Website-Installer und wähle die Install-Methode mit einem Flag. Er upgraded in-place und schreibt den Gateway-Service neu, um auf die neue Installation zu zeigen.

Wechsel zu Git-Install:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

Wechsel zu npm global:

curl -fsSL https://openclaw.ai/install.sh | bash

Hinweise:

Der Git-Flow rebaset nur, wenn das Repo sauber ist. Committe oder stashe Änderungen zuerst.

Nach dem Wechsel führe aus:

openclaw doctor
openclaw gateway restart

Telegram block streaming isn’t splitting text between tool calls. Why?

Block-Streaming sendet nur abgeschlossene Textblöcke. Häufige Gründe, warum du eine einzelne Nachricht siehst:

agents.defaults.blockStreamingDefault ist noch "off".
channels.telegram.blockStreaming ist auf false gesetzt.
channels.telegram.streamMode ist partial oder block und Draft-Streaming ist aktiv (Private-Chat + Topics). Draft-Streaming deaktiviert Block-Streaming in diesem Fall.
Deine minChars / Coalesce-Einstellungen sind zu hoch, sodass Chunks gemerged werden.
Das Modell gibt einen großen Textblock aus (keine Mid-Reply-Flush-Points).

Fix-Checkliste:

Setze Block-Streaming-Einstellungen unter agents.defaults, nicht im Root.
Setze channels.telegram.streamMode: "off", wenn du echte Multi-Message-Block-Replies willst.
Nutze kleinere Chunk/Coalesce-Schwellenwerte beim Debuggen.

Siehe Streaming.

Discord doesn’t reply in my server even with `requireMention: false`. Why?

requireMention kontrolliert nur Mention-Gating nachdem der Channel die Allowlists passiert hat. Standardmäßig ist channels.discord.groupPolicy allowlist, sodass Guilds explizit aktiviert werden müssen. Wenn du channels.discord.guilds.<guildId>.channels setzt, sind nur die gelisteten Channels erlaubt; lass es weg, um alle Channels in der Guild zu erlauben.

Fix-Checkliste:

Setze channels.discord.groupPolicy: "open" oder füge einen Guild-Allowlist-Eintrag hinzu (und optional eine Channel-Allowlist).
Nutze numerische Channel-IDs in channels.discord.guilds.<guildId>.channels.
Setze requireMention: false unter channels.discord.guilds (global oder pro Channel). Top-Level channels.discord.requireMention ist kein unterstützter Key.
Stelle sicher, dass der Bot Message Content Intent und Channel-Permissions hat.
Führe openclaw channels status --probe für Audit-Hinweise aus.

Docs: Discord, Channels troubleshooting.

Cloud Code Assist API error: invalid tool schema (400). What now?

Das ist fast immer ein Tool-Schema-Kompatibilitäts-Problem. Der Cloud Code Assist Endpoint akzeptiert eine strikte Teilmenge von JSON Schema. OpenClaw bereinigt/normalisiert Tool-Schemas im aktuellen main, aber der Fix ist noch nicht im letzten Release (Stand 13. Januar 2026).

Fix-Checkliste:

Update OpenClaw:
- Wenn du aus dem Source laufen lassen kannst, pull main und starte das Gateway neu.
- Ansonsten warte auf das nächste Release, das den Schema-Scrubber enthält.
Vermeide nicht unterstützte Keywords wie anyOf/oneOf/allOf, patternProperties, additionalProperties, minLength, maxLength, format, etc.
Wenn du Custom-Tools definierst, halte das Top-Level-Schema als type: "object" mit properties und einfachen Enums.

Siehe Tools und TypeBox schemas.

macOS Specific Issues

App Crashes when Granting Permissions (Speech/Mic)

Wenn die App verschwindet oder “Abort trap 6” zeigt, wenn du bei einem Privacy-Prompt auf “Allow” klickst:

Fix 1: TCC-Cache zurücksetzen

tccutil reset All bot.molt.mac.debug

Fix 2: Neue Bundle-ID erzwingen Wenn das Zurücksetzen nicht funktioniert, ändere die BUNDLE_ID in scripts/package-mac-app.sh (z. B. füge ein .test-Suffix hinzu) und rebuilde. Das zwingt macOS, es als neue App zu behandeln.

Gateway stuck on “Starting…”

Die App verbindet sich mit einem lokalen Gateway auf Port 18789. Wenn sie hängen bleibt:

Fix 1: Supervisor stoppen (bevorzugt) Wenn das Gateway von launchd überwacht wird, spawnt das Killen der PID es nur neu. Stoppe zuerst den Supervisor:

openclaw gateway status
openclaw gateway stop
# Oder: launchctl bootout gui/$UID/bot.molt.gateway (ersetze mit bot.molt.<profile>; legacy com.openclaw.* funktioniert noch)

Fix 2: Port ist belegt (finde den Listener)

lsof -nP -iTCP:18789 -sTCP:LISTEN

Wenn es ein nicht überwachter Prozess ist, versuche zuerst einen graceful Stop, dann eskaliere:

kill -TERM <PID>
sleep 1
kill -9 <PID> # letzter Ausweg

Fix 3: CLI-Installation prüfen Stelle sicher, dass die globale openclaw-CLI installiert ist und mit der App-Version übereinstimmt:

openclaw --version
npm install -g openclaw@<version>

Debug Mode

Verbose Logging aktivieren:

# Trace-Logging in der Config aktivieren:
#   ${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json} -> { logging: { level: "trace" } }
#
# Dann verbose Befehle ausführen, um Debug-Output auf stdout zu spiegeln:
openclaw gateway --verbose
openclaw channels login --verbose

Log Locations

Log	Ort
Gateway-Datei-Logs (strukturiert)	`/tmp/openclaw/openclaw-YYYY-MM-DD.log` (oder `logging.file`)
Gateway-Service-Logs (Supervisor)	macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` + `gateway.err.log` (Standard: `~/.openclaw/logs/...`; Profile nutzen `~/.openclaw-<profile>/logs/...`) Linux: `journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager` Windows: `schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST`
Session-Dateien	`$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`
Media-Cache	`$OPENCLAW_STATE_DIR/media/`
Credentials	`$OPENCLAW_STATE_DIR/credentials/`

Health Check

# Supervisor + Probe-Target + Config-Pfade
openclaw gateway status
# System-Level-Scans einbeziehen (Legacy/Extra-Services, Port-Listener)
openclaw gateway status --deep

# Ist das Gateway erreichbar?
openclaw health --json
# Falls es fehlschlägt, mit Verbindungsdetails erneut ausführen:
openclaw health --verbose

# Lauscht etwas auf dem Standard-Port?
lsof -nP -iTCP:18789 -sTCP:LISTEN

# Letzte Aktivität (RPC-Log-Tail)
openclaw logs --follow
# Fallback, wenn RPC down ist
tail -20 /tmp/openclaw/openclaw-*.log

Reset Everything

Nukleare Option:

openclaw gateway stop
# Wenn du einen Service installiert hast und eine saubere Installation willst:
# openclaw gateway uninstall

trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login         # WhatsApp erneut pairen
openclaw gateway restart           # oder: openclaw gateway

⚠️ Das verliert alle Sessions und erfordert erneutes WhatsApp-Pairing.

Getting Help

Prüfe zuerst die Logs: /tmp/openclaw/ (Standard: openclaw-YYYY-MM-DD.log, oder dein konfiguriertes logging.file)
Suche nach existierenden Issues auf GitHub
Öffne ein neues Issue mit:
- OpenClaw-Version
- Relevanten Log-Snippets
- Schritten zur Reproduktion
- Deiner Config (schwärze Secrets!)

“Have you tried turning it off and on again?” — Jeder IT-Mensch jemals

🦞🔧

Browser Not Starting (Linux)

Wenn du "Failed to start Chrome CDP on port 18800" siehst:

Wahrscheinlichste Ursache: Snap-gepacktes Chromium auf Ubuntu.

Schnelle Lösung: Installiere stattdessen Google Chrome:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

Dann setze in der Config:

{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}

Vollständige Anleitung: Siehe browser-linux-troubleshooting

Troubleshooting 🔧

Status & Diagnostics

Common Issues

No API key found for provider “anthropic”

OAuth token refresh failed (Anthropic Claude subscription)

Control UI fails on HTTP (“device identity required” / “connect failed”)

CI Secrets Scan Failed

Service Installed but Nothing is Running

”Gateway start blocked: set gateway.mode=local”

Service Environment (PATH + runtime)

Skill missing API key in sandbox

Service Running but Port Not Listening

Address Already in Use (Port 18789)

Extra Workspace Folders Detected

Main chat running in a sandbox workspace

”Agent was aborted”

”Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5”

Messages Not Triggering

Pairing Code Not Arriving

Image + Mention Not Working

Session Not Resuming

Agent Timing Out

WhatsApp Disconnected

Media Send Failing

High Memory Usage

Common troubleshooting

”Gateway won’t start — configuration invalid”

”All models failed” — what should I check first?

I’m running on my personal WhatsApp number — why is self-chat weird?

WhatsApp logged me out. How do I re‑auth?

Build errors on main — what’s the standard fix path?

npm install fails (allow-build-scripts / missing tar or yargs). What now?

How do I switch between git installs and npm installs?

Telegram block streaming isn’t splitting text between tool calls. Why?

Discord doesn’t reply in my server even with requireMention: false. Why?

Cloud Code Assist API error: invalid tool schema (400). What now?

macOS Specific Issues

App Crashes when Granting Permissions (Speech/Mic)

Gateway stuck on “Starting…”

Debug Mode

Log Locations

Health Check

Reset Everything

Getting Help

Browser Not Starting (Linux)

Build errors on `main` — what’s the standard fix path?

Discord doesn’t reply in my server even with `requireMention: false`. Why?