Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Diese Seite ist das ausführliche Runbook. Beginnen Sie bei /help/troubleshooting, wenn Sie zuerst den schnellen Triage-Ablauf möchten.

​
Befehlsabfolge

Führen Sie diese zuerst in dieser Reihenfolge aus: 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Erwartete fehlerfreie Signale:
  • openclaw gateway status zeigt Runtime: running, Connectivity probe: ok und eine Zeile Capability: ....
  • openclaw doctor meldet keine blockierenden Konfigurations- oder Dienstprobleme.
  • openclaw channels status --probe zeigt den Live-Transportstatus pro Konto und, sofern unterstützt, Probe-/Audit-Ergebnisse wie works oder audit ok.

​
Split-Brain-Installationen und Schutz vor neuerer Konfiguration

Verwenden Sie dies, wenn ein Gateway-Dienst nach einem Update unerwartet stoppt oder Logs zeigen, dass eine openclaw-Binärdatei älter ist als die Version, die zuletzt openclaw.json geschrieben hat. OpenClaw versieht Konfigurationsschreibvorgänge mit meta.lastTouchedVersion. Schreibgeschützte Befehle können weiterhin eine von einer neueren OpenClaw-Version geschriebene Konfiguration prüfen, aber Prozess- und Dienständerungen verweigern mit einer älteren Binärdatei die Fortsetzung. Blockierte Aktionen umfassen Start, Stopp, Neustart und Deinstallation des Gateway-Dienstes, erzwungene Dienst-Neuinstallation, Gateway-Start im Dienstmodus und gateway --force-Portbereinigung. 
which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion
1

PATH korrigieren

Korrigieren Sie PATH, sodass openclaw auf die neuere Installation verweist, und führen Sie die Aktion dann erneut aus.
2

Gateway-Dienst neu installieren

Installieren Sie den vorgesehenen Gateway-Dienst aus der neueren Installation neu:
openclaw gateway install --force
openclaw gateway restart
3

Veraltete Wrapper entfernen

Entfernen Sie veraltete Systempaket- oder alte Wrapper-Einträge, die weiterhin auf eine alte openclaw-Binärdatei zeigen.
Nur für bewusstes Downgrade oder Notfallwiederherstellung: Setzen Sie OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1 für den einzelnen Befehl. Lassen Sie es für den normalen Betrieb nicht gesetzt.
Verwenden Sie dies, wenn Logs Folgendes enthalten: 
Skipping escaped skill path outside its configured root: ... reason=symlink-escape
OpenClaw behandelt jeden Skill-Root als Begrenzung. Ein Symlink unter ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills oder ~/.openclaw/skills wird übersprungen, wenn sein tatsächliches Ziel außerhalb dieses Roots aufgelöst wird, sofern das Ziel nicht ausdrücklich als vertrauenswürdig eingestuft ist. Prüfen Sie den Link: 
ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
openclaw config get skills.load
Wenn das Ziel beabsichtigt ist, konfigurieren Sie sowohl den direkten Skill-Root als auch das zugelassene Symlink-Ziel: 
{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}
Starten Sie anschließend eine neue Sitzung oder warten Sie, bis der Skills-Watcher aktualisiert wurde. Starten Sie das Gateway neu, wenn der laufende Prozess vor der Konfigurationsänderung gestartet wurde. Verwenden Sie keine breiten Ziele wie ~, / oder einen ganzen synchronisierten Projektordner. Beschränken Sie allowSymlinkTargets auf den tatsächlichen Skill-Root, der vertrauenswürdige SKILL.md-Verzeichnisse enthält. Verwandt:

​
Anthropic 429: zusätzliche Nutzung für langen Kontext erforderlich

Verwenden Sie dies, wenn Logs/Fehler Folgendes enthalten: HTTP 429: rate_limit_error: Extra usage is required for long context requests. 
openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models
Achten Sie auf Folgendes:
  • Für das ausgewählte Anthropic Opus-/Sonnet-Modell ist params.context1m: true gesetzt.
  • Die aktuelle Anthropic-Anmeldedatenberechtigung ist nicht für die Nutzung von langem Kontext berechtigt.
  • Anfragen schlagen nur bei langen Sitzungen/Modellläufen fehl, die den 1M-Beta-Pfad benötigen.
Behebungsoptionen:
1

context1m deaktivieren

Deaktivieren Sie context1m für dieses Modell, um auf das normale Kontextfenster zurückzufallen.
2

Berechtigte Anmeldedaten verwenden

Verwenden Sie Anthropic-Anmeldedaten, die für Anfragen mit langem Kontext berechtigt sind, oder wechseln Sie zu einem Anthropic-API-Schlüssel.
3

Fallback-Modelle konfigurieren

Konfigurieren Sie Fallback-Modelle, damit Läufe fortgesetzt werden, wenn Anthropic-Anfragen mit langem Kontext abgelehnt werden.
Verwandt:

​
Lokales OpenAI-kompatibles Backend besteht direkte Probes, aber Agent-Läufe schlagen fehl

Verwenden Sie dies, wenn:
  • curl ... /v1/models funktioniert
  • winzige direkte /v1/chat/completions-Aufrufe funktionieren
  • OpenClaw-Modellläufe nur bei normalen Agent-Turns fehlschlagen
curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow
Achten Sie auf Folgendes:
  • direkte winzige Aufrufe sind erfolgreich, aber OpenClaw-Läufe schlagen nur bei größeren Prompts fehl
  • model_not_found- oder 404-Fehler, obwohl direkte /v1/chat/completions mit derselben einfachen Modell-ID funktionieren
  • Backend-Fehler dazu, dass messages[].content eine Zeichenfolge erwartet
  • zeitweise Warnungen incomplete turn detected ... stopReason=stop payloads=0 mit einem OpenAI-kompatiblen lokalen Backend
  • Backend-Abstürze, die nur bei größeren Prompt-Token-Zahlen oder vollständigen Agent-Runtime-Prompts auftreten
  • model_not_found mit einem lokalen MLX-/vLLM-artigen Server → prüfen Sie, dass baseUrl /v1 enthält, api für /v1/chat/completions-Backends "openai-completions" ist und models.providers.<provider>.models[].id die einfache provider-lokale ID ist. Wählen Sie sie einmal mit dem Provider-Präfix aus, zum Beispiel mlx/mlx-community/Qwen3-30B-A3B-6bit; behalten Sie den Katalogeintrag als mlx-community/Qwen3-30B-A3B-6bit.
  • messages[...].content: invalid type: sequence, expected a string → Backend lehnt strukturierte Chat-Completions-Inhaltsteile ab. Behebung: models.providers.<provider>.models[].compat.requiresStringContent: true setzen.
  • validation.keys oder erlaubte Nachrichtenschlüssel wie ["role","content"] → Backend lehnt OpenAI-artige Replay-Metadaten in Chat-Completions-Nachrichten ab. Behebung: models.providers.<provider>.models[].compat.strictMessageKeys: true setzen.
  • incomplete turn detected ... stopReason=stop payloads=0 → Das Backend hat die Chat-Completions-Anfrage abgeschlossen, aber für diesen Turn keinen für den Benutzer sichtbaren Assistant-Text zurückgegeben. OpenClaw wiederholt replay-sichere leere OpenAI-kompatible Turns einmal; anhaltende Fehler bedeuten in der Regel, dass das Backend leeren/nicht-textuellen Inhalt ausgibt oder finalen Antworttext unterdrückt.
  • Direkte winzige Anfragen sind erfolgreich, aber OpenClaw-Agent-Läufe schlagen mit Backend-/Modellabstürzen fehl (zum Beispiel Gemma auf einigen inferrs-Builds) → Der OpenClaw-Transport ist wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Agent-Runtime-Prompt-Form.
  • Fehler werden nach dem Deaktivieren von Tools kleiner, verschwinden aber nicht → Tool-Schemas waren Teil des Drucks, aber das verbleibende Problem liegt weiterhin bei der Kapazität des Upstream-Modells/-Servers oder einem Backend-Fehler.
  1. Setzen Sie compat.requiresStringContent: true für reine Zeichenfolgen-Chat-Completions-Backends.
  2. Setzen Sie compat.strictMessageKeys: true für strikte Chat-Completions-Backends, die pro Nachricht nur role und content akzeptieren.
  3. Setzen Sie compat.supportsTools: false für Modelle/Backends, die die Tool-Schema-Oberfläche von OpenClaw nicht zuverlässig verarbeiten können.
  4. Verringern Sie nach Möglichkeit den Prompt-Druck: kleinerer Workspace-Bootstrap, kürzerer Sitzungsverlauf, leichteres lokales Modell oder ein Backend mit stärkerer Unterstützung für langen Kontext.
  5. Wenn winzige direkte Anfragen weiterhin bestehen, während OpenClaw-Agent-Turns im Backend abstürzen, behandeln Sie dies als Upstream-Server-/Modellbeschränkung und melden Sie dort eine Reproduktion mit der akzeptierten Payload-Form.
Verwandt:

​
Keine Antworten

Wenn Channels verfügbar sind, aber nichts antwortet, prüfen Sie Routing und Richtlinie, bevor Sie etwas neu verbinden. 
openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow
Achten Sie auf Folgendes:
  • Pairing für DM-Absender ausstehend.
  • Gruppen-Erwähnungs-Gating (requireMention, mentionPatterns).
  • Abweichungen bei Channel-/Gruppen-Allowlists.
Häufige Signaturen:
  • drop guild message (mention required → Gruppennachricht wird bis zur Erwähnung ignoriert.
  • pairing request → Absender benötigt Genehmigung.
  • blocked / allowlist → Absender/Channel wurde durch Richtlinie gefiltert.
Verwandt:

​
Konnektivität der Dashboard-Steuerungs-UI

Wenn die Dashboard-/Steuerungs-UI keine Verbindung herstellt, validieren Sie URL, Auth-Modus und Annahmen zum sicheren Kontext. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json
Achten Sie auf Folgendes:
  • Korrekte Probe-URL und Dashboard-URL.
  • Abweichung bei Auth-Modus/Token zwischen Client und Gateway.
  • HTTP-Nutzung, obwohl Geräteidentität erforderlich ist.
  • device identity required → unsicherer Kontext oder fehlende Geräte-Auth.
  • origin not allowed → Browser-Origin ist nicht in gateway.controlUi.allowedOrigins enthalten (oder Sie verbinden sich von einem Browser-Origin außerhalb von Loopback ohne ausdrückliche Allowlist).
  • device nonce required / device nonce mismatch → Client schließt den challenge-basierten Geräte-Auth-Flow nicht ab (connect.challenge + device.nonce).
  • device signature invalid / device signature expired → Client hat die falsche Payload (oder einen veralteten Zeitstempel) für den aktuellen Handshake signiert.
  • AUTH_TOKEN_MISMATCH mit canRetryWithDeviceToken=true → Client kann einen vertrauenswürdigen Wiederholungsversuch mit zwischengespeichertem Gerätetoken durchführen.
  • Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet die zwischengespeicherte Scope-Menge, die mit dem gepairten Gerätetoken gespeichert ist. Aufrufer mit explizitem deviceToken / expliziten scopes behalten stattdessen ihre angeforderte Scope-Menge.
  • AUTH_SCOPE_MISMATCH → Das Gerätetoken wurde erkannt, aber seine genehmigten Scopes decken diese Verbindungsanfrage nicht ab; pairen Sie erneut oder genehmigen Sie den angeforderten Scope-Vertrag, statt ein gemeinsam genutztes Gateway-Token zu rotieren.
  • Außerhalb dieses Wiederholungspfads lautet die Connect-Auth-Priorität: zuerst explizites gemeinsames Token/Passwort, dann explizites deviceToken, dann gespeichertes Gerätetoken, dann Bootstrap-Token.
  • Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dasselbe {scope, ip} serialisiert, bevor der Limiter den Fehler erfasst. Zwei fehlerhafte gleichzeitige Wiederholungen vom selben Client können daher beim zweiten Versuch retry later statt zweier einfacher Abweichungen anzeigen.
  • too many failed authentication attempts (retry later) von einem Browser-Origin-Loopback-Client → wiederholte Fehler von demselben normalisierten Origin werden vorübergehend ausgesperrt; ein anderer localhost-Origin verwendet einen separaten Bucket.
  • wiederholtes unauthorized nach diesem Wiederholungsversuch → Drift bei gemeinsamem Token/Gerätetoken; aktualisieren Sie die Token-Konfiguration und genehmigen/rotieren Sie das Gerätetoken bei Bedarf erneut.
  • gateway connect failed: → falsches Host-/Port-/URL-Ziel.

​
Schnellzuordnung für Auth-Detailcodes

Verwenden Sie error.details.code aus der fehlgeschlagenen connect-Antwort, um die nächste Aktion auszuwählen:
DetailcodeBedeutungEmpfohlene Aktion
AUTH_TOKEN_MISSINGClient hat ein erforderliches gemeinsames Token nicht gesendet.Token im Client einfügen/festlegen und erneut versuchen. Für Dashboard-Pfade: openclaw config get gateway.auth.token und dann in die Einstellungen der Control UI einfügen.
AUTH_TOKEN_MISMATCHGemeinsames Token stimmte nicht mit dem Auth-Token des Gateway überein.Wenn canRetryWithDeviceToken=true ist, erlauben Sie einen vertrauenswürdigen erneuten Versuch. Wiederholungen mit zwischengespeichertem Token verwenden gespeicherte genehmigte Scopes erneut; Aufrufer mit explizitem deviceToken / scopes behalten angeforderte Scopes bei. Wenn der Fehler weiterhin auftritt, führen Sie die Checkliste zur Wiederherstellung bei Token-Drift aus.
AUTH_DEVICE_TOKEN_MISMATCHZwischengespeichertes gerätespezifisches Token ist veraltet oder widerrufen.Gerätetoken mit der Geräte-CLI rotieren/erneut genehmigen, dann erneut verbinden.
AUTH_SCOPE_MISMATCHGerätetoken ist gültig, aber seine genehmigte Rolle/seine genehmigten Scopes decken diese Verbindungsanforderung nicht ab.Koppeln Sie das Gerät erneut oder genehmigen Sie den angeforderten Scope-Vertrag; behandeln Sie dies nicht als Drift des gemeinsamen Tokens.
PAIRING_REQUIREDGeräteidentität benötigt Genehmigung. Prüfen Sie error.details.reason auf not-paired, scope-upgrade, role-upgrade oder metadata-upgrade, und verwenden Sie requestId / remediationHint, wenn vorhanden.Ausstehende Anforderung genehmigen: openclaw devices list, dann openclaw devices approve <requestId>. Scope-/Rollen-Upgrades verwenden denselben Ablauf, nachdem Sie den angeforderten Zugriff geprüft haben.
Direkte loopback-Backend-RPCs, die mit dem gemeinsamen Gateway-Token/Passwort authentifiziert sind, sollten nicht von der Scope-Basislinie der gekoppelten Geräte der CLI abhängen. Wenn Subagents oder andere interne Aufrufe weiterhin mit scope-upgrade fehlschlagen, prüfen Sie, ob der Aufrufer client.id: "gateway-client" und client.mode: "backend" verwendet und kein explizites deviceIdentity oder Gerätetoken erzwingt.
Migrationsprüfung für Geräteauthentifizierung v2: 
openclaw --version
openclaw doctor
openclaw gateway status
Wenn Logs Nonce-/Signaturfehler anzeigen, aktualisieren Sie den verbindenden Client und prüfen Sie ihn:
1

Auf connect.challenge warten

Client wartet auf das vom Gateway ausgegebene connect.challenge.
2

Payload signieren

Client signiert die an die Challenge gebundene Payload.
3

Geräte-Nonce senden

Client sendet connect.params.device.nonce mit derselben Challenge-Nonce.
Wenn openclaw devices rotate / revoke / remove unerwartet verweigert wird:
  • Sitzungen mit gekoppeltem Gerätetoken können nur ihr eigenes Gerät verwalten, sofern der Aufrufer nicht auch operator.admin hat
  • openclaw devices rotate --scope ... kann nur Operator-Scopes anfordern, die die Aufrufersitzung bereits besitzt
Verwandt:

​
Gateway-Dienst läuft nicht

Verwenden Sie dies, wenn der Dienst installiert ist, der Prozess aber nicht aktiv bleibt. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # also scan system-level services
Achten Sie auf:
  • Runtime: stopped mit Exit-Hinweisen.
  • Abweichung in der Dienstkonfiguration (Config (cli) gegenüber Config (service)).
  • Port-/Listener-Konflikte.
  • Zusätzliche launchd-/systemd-/schtasks-Installationen, wenn --deep verwendet wird.
  • Bereinigungshinweise zu Other gateway-like services detected (best effort).
  • Gateway start blocked: set gateway.mode=local oder existing config is missing gateway.mode → lokaler Gateway-Modus ist nicht aktiviert, oder die Konfigurationsdatei wurde überschrieben und hat gateway.mode verloren. Behebung: Setzen Sie gateway.mode="local" in Ihrer Konfiguration, oder führen Sie openclaw onboard --mode local / openclaw setup erneut aus, um die erwartete lokale Moduskonfiguration neu zu stempeln. Wenn Sie OpenClaw über Podman ausführen, ist der Standardkonfigurationspfad ~/.openclaw/openclaw.json.
  • refusing to bind gateway ... without auth → Nicht-loopback-Bindung ohne gültigen Gateway-Auth-Pfad (Token/Passwort oder trusted-proxy, wenn konfiguriert).
  • another gateway instance is already listening / EADDRINUSE → Portkonflikt.
  • Other gateway-like services detected (best effort) → veraltete oder parallele launchd-/systemd-/schtasks-Einheiten existieren. Die meisten Setups sollten ein Gateway pro Maschine behalten; wenn Sie mehr als eines benötigen, isolieren Sie Ports + Konfiguration/Zustand/Workspace. Siehe /gateway#multiple-gateways-same-host.
  • System-level OpenClaw gateway service detected von doctor → eine systemd-Systemeinheit existiert, während der Dienst auf Benutzerebene fehlt. Entfernen oder deaktivieren Sie das Duplikat, bevor Sie doctor erlauben, einen Benutzerdienst zu installieren, oder setzen Sie OPENCLAW_SERVICE_REPAIR_POLICY=external, wenn die Systemeinheit der beabsichtigte Supervisor ist.
  • Gateway service port does not match current gateway config → der installierte Supervisor pinnt weiterhin den alten --port. Führen Sie openclaw doctor --fix oder openclaw gateway install --force aus, und starten Sie dann den Gateway-Dienst neu.
Verwandt:

​
Gateway hat ungültige Konfiguration abgelehnt

Verwenden Sie dies, wenn der Gateway-Start mit Invalid config fehlschlägt oder Hot-Reload-Logs melden, dass eine ungültige Bearbeitung übersprungen wurde. 
openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor
Achten Sie auf:
  • Invalid config at ...
  • config reload skipped (invalid config): ...
  • Config write rejected: ...
  • Eine mit Zeitstempel versehene Datei openclaw.json.rejected.* neben der aktiven Konfiguration
  • Eine mit Zeitstempel versehene Datei openclaw.json.clobbered.*, wenn doctor --fix eine fehlerhafte direkte Bearbeitung repariert hat
  • Die Konfiguration wurde beim Start, beim Hot Reload oder bei einem OpenClaw-eigenen Schreibvorgang nicht validiert.
  • Gateway-Start schlägt geschlossen fehl, statt openclaw.json neu zu schreiben.
  • Hot Reload überspringt ungültige externe Bearbeitungen und hält die aktuelle Laufzeitkonfiguration aktiv.
  • OpenClaw-eigene Schreibvorgänge lehnen ungültige/destruktive Payloads vor dem Commit ab und speichern .rejected.*.
  • openclaw doctor --fix besitzt die Reparatur. Es kann Nicht-JSON-Präfixe entfernen oder die letzte als gut bekannte Kopie wiederherstellen, während die abgelehnte Payload als .clobbered.* erhalten bleibt.
CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor
  • .clobbered.* existiert → doctor hat eine fehlerhafte externe Bearbeitung erhalten, während die aktive Konfiguration repariert wurde.
  • .rejected.* existiert → ein OpenClaw-eigener Konfigurationsschreibvorgang ist vor dem Commit an Schema- oder Clobber-Prüfungen gescheitert.
  • Config write rejected: → der Schreibvorgang versuchte, erforderliche Struktur zu entfernen, die Datei stark zu verkleinern oder ungültige Konfiguration zu persistieren.
  • config reload skipped (invalid config): → eine direkte Bearbeitung ist an der Validierung gescheitert und wurde vom laufenden Gateway ignoriert.
  • Invalid config at ... → Start ist fehlgeschlagen, bevor Gateway-Dienste gestartet wurden.
  • missing-meta-vs-last-good, gateway-mode-missing-vs-last-good oder size-drop-vs-last-good:* → ein OpenClaw-eigener Schreibvorgang wurde abgelehnt, weil er Felder oder Größe im Vergleich zum Last-known-good-Backup verloren hat.
  • Config last-known-good promotion skipped → der Kandidat enthielt redigierte Secret-Platzhalter wie ***.
  1. Führen Sie openclaw doctor --fix aus, damit doctor eine Konfiguration mit Präfix/Clobber repariert oder Last-known-good wiederherstellt.
  2. Kopieren Sie nur die beabsichtigten Schlüssel aus .clobbered.* oder .rejected.*, und wenden Sie sie dann mit openclaw config set oder config.patch an.
  3. Führen Sie openclaw config validate vor dem Neustart aus.
  4. Wenn Sie von Hand bearbeiten, behalten Sie die vollständige JSON5-Konfiguration bei, nicht nur das Teilobjekt, das Sie ändern wollten.
Verwandt:

​
Gateway-Probe-Warnungen

Verwenden Sie dies, wenn openclaw gateway probe etwas erreicht, aber trotzdem einen Warnungsblock ausgibt. 
openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host
Achten Sie auf:
  • warnings[].code und primaryTargetId in der JSON-Ausgabe.
  • Ob sich die Warnung auf SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Auth-Referenzen bezieht.
Häufige Signaturen:
  • SSH tunnel failed to start; falling back to direct probes. → SSH-Einrichtung ist fehlgeschlagen, aber der Befehl hat weiterhin direkte konfigurierte/loopback-Ziele versucht.
  • multiple reachable gateways detected → mehr als ein Ziel hat geantwortet. Normalerweise bedeutet dies ein beabsichtigtes Multi-Gateway-Setup oder veraltete/duplizierte Listener.
  • Read-probe diagnostics are limited by gateway scopes (missing operator.read) → Verbindung hat funktioniert, aber Detail-RPC ist durch Scopes eingeschränkt; koppeln Sie die Geräteidentität oder verwenden Sie Zugangsdaten mit operator.read.
  • Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → Verbindung hat funktioniert, aber der vollständige Diagnose-RPC-Satz ist abgelaufen oder fehlgeschlagen. Behandeln Sie dies als erreichbares Gateway mit eingeschränkter Diagnose; vergleichen Sie connect.ok und connect.rpcOk in der --json-Ausgabe.
  • Capability: pairing-pending oder gateway closed (1008): pairing required → das Gateway hat geantwortet, aber dieser Client benötigt vor normalem Operator-Zugriff noch Kopplung/Genehmigung.
  • nicht aufgelöster gateway.auth.* / gateway.remote.* SecretRef-Warnungstext → Auth-Material war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar.
Verwandt:

​
Kanal verbunden, Nachrichten fließen nicht

Wenn der Kanalstatus verbunden ist, aber der Nachrichtenfluss nicht funktioniert, konzentrieren Sie sich auf Richtlinien, Berechtigungen und kanalspezifische Zustellregeln. 
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels
Achten Sie auf:
  • DM-Richtlinie (pairing, allowlist, open, disabled).
  • Gruppen-Allowlist und Erwähnungsanforderungen.
  • Fehlende Kanal-API-Berechtigungen/-Scopes.
Häufige Signaturen:
  • mention required → Nachricht durch Gruppen-Erwähnungsrichtlinie ignoriert.
  • pairing / Spuren ausstehender Genehmigung → Absender ist nicht genehmigt.
  • missing_scope, not_in_channel, Forbidden, 401/403 → Problem mit Kanal-Authentifizierung/-Berechtigungen.
Verwandt:

​
Cron- und Heartbeat-Zustellung

Wenn Cron oder Heartbeat nicht ausgeführt oder nicht zugestellt wurde, prüfen Sie zuerst den Scheduler-Status und dann das Zustellziel. 
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
Achten Sie auf:
  • Cron aktiviert und nächste Ausführung vorhanden.
  • Status des Job-Ausführungsverlaufs (ok, skipped, error).
  • Heartbeat-Überspringgründe (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).
  • cron: scheduler disabled; jobs will not run automatically → Cron deaktiviert.
  • cron: timer tick failed → Scheduler-Tick fehlgeschlagen; Datei-/Log-/Laufzeitfehler prüfen.
  • heartbeat skipped mit reason=quiet-hours → außerhalb des aktiven Zeitfensters.
  • heartbeat skipped mit reason=empty-heartbeat-file → HEARTBEAT.md existiert, enthält aber nur leere Zeilen / Markdown-Überschriften, daher überspringt OpenClaw den Modellaufruf.
  • heartbeat skipped mit reason=no-tasks-due → HEARTBEAT.md enthält einen tasks:-Block, aber keine der Aufgaben ist bei diesem Tick fällig.
  • heartbeat: unknown accountId → ungültige Konto-ID für das Heartbeat-Zustellziel.
  • heartbeat skipped mit reason=dm-blocked → Heartbeat-Ziel wurde als DM-artiges Ziel aufgelöst, während agents.defaults.heartbeat.directPolicy (oder eine agentenspezifische Überschreibung) auf block gesetzt ist.
Verwandt:

​
Node gekoppelt, Tool schlägt fehl

Wenn eine Node gekoppelt ist, aber Tools fehlschlagen, isolieren Sie Vordergrund-, Berechtigungs- und Genehmigungsstatus. 
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status
Achten Sie auf:
  • Node online mit erwarteten Fähigkeiten.
  • Betriebssystem-Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
  • Exec-Genehmigungen und Allowlist-Status.
Häufige Signaturen:
  • NODE_BACKGROUND_UNAVAILABLE → Node-App muss im Vordergrund sein.
  • *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → fehlende Betriebssystem-Berechtigung.
  • SYSTEM_RUN_DENIED: approval required → Exec-Genehmigung ausstehend.
  • SYSTEM_RUN_DENIED: allowlist miss → Befehl durch Allowlist blockiert.
Verwandt:

​
Browser-Tool schlägt fehl

Verwenden Sie dies, wenn Browser-Tool-Aktionen fehlschlagen, obwohl der Gateway selbst fehlerfrei ist. 
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor
Achten Sie auf:
  • Ob plugins.allow gesetzt ist und browser enthält.
  • Gültigen Pfad zur Browser-Executable.
  • Erreichbarkeit des CDP-Profils.
  • Lokale Chrome-Verfügbarkeit für existing-session- / user-Profile.
  • unknown command "browser" oder unknown command 'browser' → das gebündelte Browser-Plugin ist durch plugins.allow ausgeschlossen.
  • Browser-Tool fehlt / nicht verfügbar, obwohl browser.enabled=true → plugins.allow schließt browser aus, daher wurde das Plugin nie geladen.
  • Failed to start Chrome CDP on port → Browser-Prozess konnte nicht gestartet werden.
  • browser.executablePath not found → konfigurierter Pfad ist ungültig.
  • browser.cdpUrl must be http(s) or ws(s) → die konfigurierte CDP-URL verwendet ein nicht unterstütztes Schema wie file: oder ftp:.
  • browser.cdpUrl has invalid port → die konfigurierte CDP-URL hat einen ungültigen oder außerhalb des Bereichs liegenden Port.
  • Playwright is not available in this gateway build; '<feature>' is unsupported. → der aktuellen Gateway-Installation fehlt die zentrale Browser-Laufzeitabhängigkeit; installieren oder aktualisieren Sie OpenClaw erneut und starten Sie dann den Gateway neu. ARIA-Snapshots und einfache Seiten-Screenshots können weiterhin funktionieren, aber Navigation, KI-Snapshots, Element-Screenshots per CSS-Selektor und PDF-Export bleiben nicht verfügbar.
  • Could not find DevToolsActivePort for chrome → Chrome-MCP-Existing-Session konnte noch nicht an das ausgewählte Browser-Datenverzeichnis anhängen. Öffnen Sie die Browser-Inspektionsseite, aktivieren Sie Remote-Debugging, lassen Sie den Browser geöffnet, genehmigen Sie die erste Anhängeaufforderung und versuchen Sie es erneut. Wenn ein angemeldeter Zustand nicht erforderlich ist, bevorzugen Sie das verwaltete Profil openclaw.
  • No Chrome tabs found for profile="user" → das Chrome-MCP-Anhängeprofil hat keine geöffneten lokalen Chrome-Tabs.
  • Remote CDP for profile "<name>" is not reachable → der konfigurierte Remote-CDP-Endpunkt ist vom Gateway-Host aus nicht erreichbar.
  • Browser attachOnly is enabled ... not reachable oder Browser attachOnly is enabled and CDP websocket ... is not reachable → Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber der CDP-WebSocket konnte dennoch nicht geöffnet werden.
  • fullPage is not supported for element screenshots → Screenshot-Anfrage hat --full-page mit --ref oder --element kombiniert.
  • element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome-MCP- / existing-session-Screenshot-Aufrufe müssen Seitenerfassung oder ein Snapshot---ref verwenden, nicht CSS---element.
  • existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome-MCP-Upload-Hooks benötigen Snapshot-Refs, keine CSS-Selektoren.
  • existing-session file uploads currently support one file at a time. → senden Sie bei Chrome-MCP-Profilen einen Upload pro Aufruf.
  • existing-session dialog handling does not support timeoutMs. → Dialog-Hooks bei Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen.
  • existing-session type does not support timeoutMs overrides. → lassen Sie timeoutMs für act:type bei profile="user"- / Chrome-MCP-Existing-Session-Profilen weg, oder verwenden Sie ein verwaltetes/CDP-Browserprofil, wenn ein benutzerdefiniertes Timeout erforderlich ist.
  • existing-session evaluate does not support timeoutMs overrides. → lassen Sie timeoutMs für act:evaluate bei profile="user"- / Chrome-MCP-Existing-Session-Profilen weg, oder verwenden Sie ein verwaltetes/CDP-Browserprofil, wenn ein benutzerdefiniertes Timeout erforderlich ist.
  • response body is not supported for existing-session profiles yet. → responsebody erfordert weiterhin einen verwalteten Browser oder ein Raw-CDP-Profil.
  • veraltete Viewport- / Dark-Mode- / Locale- / Offline-Überschreibungen bei Attach-only- oder Remote-CDP-Profilen → führen Sie openclaw browser stop --browser-profile <name> aus, um die aktive Steuersitzung zu schließen und den Playwright-/CDP-Emulationsstatus freizugeben, ohne den gesamten Gateway neu zu starten.
Verwandt:

​
Wenn Sie aktualisiert haben und plötzlich etwas nicht mehr funktioniert

Die meisten Ausfälle nach einem Upgrade sind Konfigurationsdrift oder strengere Defaults, die jetzt durchgesetzt werden. 
openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
Was zu prüfen ist:
  • Wenn gateway.mode=remote, zielen CLI-Aufrufe möglicherweise auf remote, während Ihr lokaler Dienst in Ordnung ist.
  • Explizite --url-Aufrufe fallen nicht auf gespeicherte Zugangsdaten zurück.
Häufige Signaturen:
  • gateway connect failed: → falsches URL-Ziel.
  • unauthorized → Endpunkt erreichbar, aber falsche Authentifizierung.
openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow
Was zu prüfen ist:
  • Nicht-Loopback-Binds (lan, tailnet, custom) benötigen einen gültigen Gateway-Authentifizierungspfad: gemeinsame Token-/Passwort-Authentifizierung oder eine korrekt konfigurierte Nicht-Loopback-trusted-proxy-Bereitstellung.
  • Alte Schlüssel wie gateway.token ersetzen gateway.auth.token nicht.
Häufige Signaturen:
  • refusing to bind gateway ... without auth → Nicht-Loopback-Bind ohne gültigen Gateway-Authentifizierungspfad.
  • Connectivity probe: failed, während die Laufzeit ausgeführt wird → Gateway läuft, ist aber mit aktueller Authentifizierung/URL nicht zugänglich.
openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor
Was zu prüfen ist:
  • Ausstehende Gerätegenehmigungen für Dashboard/Nodes.
  • Ausstehende DM-Kopplungsgenehmigungen nach Richtlinien- oder Identitätsänderungen.
Häufige Signaturen:
  • device identity required → Geräteauthentifizierung nicht erfüllt.
  • pairing required → Absender/Gerät muss genehmigt werden.
Wenn Dienstkonfiguration und Laufzeit nach den Prüfungen weiterhin voneinander abweichen, installieren Sie die Dienstmetadaten aus demselben Profil-/Statusverzeichnis erneut: 
openclaw gateway install --force
openclaw gateway restart
Verwandt:

​
Verwandt