Gateway-Fehlerbehebung

Diese Seite ist das ausführliche Runbook. Beginne bei /help/troubleshooting, wenn du zuerst den schnellen Triage-Flow möchtest.

Befehlsleiter

Führe diese zuerst in dieser Reihenfolge aus:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

Erwartete gesunde Signale:

openclaw gateway status zeigt Runtime: running und RPC probe: ok.
openclaw doctor meldet keine blockierenden Config-/Service-Probleme.
openclaw channels status --probe zeigt verbundene/bereite Channels.

Anthropic 429 Extra Usage für langen Kontext

Nutze dies, wenn Logs/Fehler 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

Suche nach:

Das ausgewählte Anthropic-Opus-/Sonnet-Modell hat params.context1m: true.
Das aktuelle Anthropic-Credential ist nicht für Long-Context-Nutzung berechtigt.
Anfragen schlagen nur bei langen Sessions/Modell-Runs fehl, die den 1M-Beta-Pfad brauchen.

Lösungsmöglichkeiten:

Deaktiviere context1m für dieses Modell, um auf das normale Kontextfenster zurückzufallen.
Verwende einen Anthropic-API-Key mit Billing oder aktiviere Anthropic Extra Usage im Abo-Konto.
Konfiguriere Fallback-Modelle, damit Runs weiterlaufen, wenn Anthropic-Long-Context-Anfragen abgelehnt werden.

Verwandt:

Keine Antworten

Wenn Channels oben sind, aber nichts antwortet, prüfe Routing und Policy vor dem Neuverbinden.

openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow

Suche nach:

Ausstehende Kopplung für DM-Absender.
Gruppen-Mention-Gating (requireMention, mentionPatterns).
Channel-/Gruppen-Allowlist-Diskrepanzen.

Häufige Signaturen:

drop guild message (mention required -> Gruppennachricht wird bis zur Erwähnung ignoriert.
pairing request -> Absender braucht Genehmigung.
blocked / allowlist -> Absender/Channel wurde durch Policy gefiltert.

Verwandt:

Dashboard-Control-UI-Konnektivität

Wenn das Dashboard/die Control-UI nicht verbinden kann, validiere URL, Auth-Modus und Secure-Context-Annahmen.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json

Suche nach:

Korrekte Probe-URL und Dashboard-URL.
Auth-Modus/Token-Diskrepanz zwischen Client und Gateway.
HTTP-Nutzung wo Device-Identität erforderlich ist.

Häufige Signaturen:

device identity required -> Kein sicherer Kontext oder fehlende Device-Auth.
device nonce required / device nonce mismatch -> Client vervollständigt den Challenge-basierten Device-Auth-Flow nicht (connect.challenge + device.nonce).
device signature invalid / device signature expired -> Client hat den falschen Payload (oder veralteten Zeitstempel) für den aktuellen Handshake signiert.
AUTH_TOKEN_MISMATCH mit canRetryWithDeviceToken=true -> Client kann einen vertrauenswürdigen Retry mit gecachtem Device-Token machen.
Wiederholtes unauthorized nach diesem Retry -> Shared-Token/Device-Token-Drift; Token-Konfiguration aktualisieren und Device-Token bei Bedarf neu genehmigen/rotieren.
gateway connect failed: -> Falsches Host/Port/URL-Ziel.

Auth-Detailcode-Schnellübersicht

Verwende error.details.code aus der fehlgeschlagenen connect-Antwort, um die nächste Aktion auszuwählen:

Detailcode	Bedeutung	Empfohlene Aktion
`AUTH_TOKEN_MISSING`	Client hat kein erforderliches Shared-Token gesendet.	Token im Client einfügen/setzen und erneut versuchen. Für Dashboard-Pfade: `openclaw config get gateway.auth.token`, dann in Control-UI-Einstellungen einfügen.
`AUTH_TOKEN_MISMATCH`	Shared-Token stimmt nicht mit Gateway-Auth-Token überein.	Wenn `canRetryWithDeviceToken=true`, einen vertrauenswürdigen Retry erlauben. Falls weiterhin fehlschlagend, die Token-Drift-Recovery-Checkliste durchgehen.
`AUTH_DEVICE_TOKEN_MISMATCH`	Gecachtes Per-Device-Token ist veraltet oder widerrufen.	Device-Token über die Devices-CLI rotieren/neu genehmigen, dann erneut verbinden.
`PAIRING_REQUIRED`	Device-Identität ist bekannt, aber nicht für diese Rolle genehmigt.	Ausstehende Anfrage genehmigen: `openclaw devices list`, dann `openclaw devices approve <requestId>`.

Device-Auth-v2-Migrationsprüfung:

openclaw --version
openclaw doctor
openclaw gateway status

Wenn die Logs Nonce-/Signatur-Fehler zeigen, aktualisiere den verbindenden Client und stelle sicher, dass er:

auf connect.challenge wartet
den Challenge-gebundenen Payload signiert
connect.params.device.nonce mit derselben Challenge-Nonce sendet

Verwandt:

Gateway-Service läuft nicht

Nutze dies, wenn der Service installiert ist, aber der Prozess nicht dauerhaft läuft.

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep

Suche nach:

Runtime: stopped mit Exit-Hinweisen.
Service-Config-Diskrepanz (Config (cli) vs Config (service)).
Port-/Listener-Konflikte.

Häufige Signaturen:

Gateway start blocked: set gateway.mode=local -> Lokaler Gateway-Modus ist nicht aktiviert. Fix: Setze gateway.mode="local" in deiner Konfiguration (oder führe openclaw configure aus). Wenn du OpenClaw via Podman mit dem dedizierten openclaw-Benutzer betreibst, liegt die Konfiguration unter ~openclaw/.openclaw/openclaw.json.
refusing to bind gateway ... without auth -> Nicht-Loopback-Bind ohne Token/Passwort.
another gateway instance is already listening / EADDRINUSE -> Port-Konflikt.

Verwandt:

Channel verbunden, Nachrichten fließen nicht

Wenn der Channel-Status verbunden ist, aber der Nachrichtenfluss tot ist, fokussiere auf Policy, Berechtigungen und Channel-spezifische Zustellungsregeln.

openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels

Suche nach:

DM-Policy (pairing, allowlist, open, disabled).
Gruppen-Allowlist und Mention-Anforderungen.
Fehlende Channel-API-Berechtigungen/Scopes.

Häufige Signaturen:

mention required -> Nachricht wird durch Gruppen-Mention-Policy ignoriert.
pairing / Pending-Approval-Traces -> Absender ist nicht genehmigt.
missing_scope, not_in_channel, Forbidden, 401/403 -> Channel-Auth-/Berechtigungsproblem.

Verwandt:

Cron und Heartbeat-Zustellung

Wenn Cron oder Heartbeat nicht gelaufen ist oder nicht zugestellt hat, überprüfe zuerst den Scheduler-Zustand, dann das Zustellungsziel.

openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow

Suche nach:

Cron aktiviert und nächstes Aufwachen vorhanden.
Job-Run-Verlauf-Status (ok, skipped, error).
Heartbeat-Übersprungsgründe (quiet-hours, requests-in-flight, alerts-disabled).

Häufige Signaturen:

cron: scheduler disabled; jobs will not run automatically -> Cron deaktiviert.
cron: timer tick failed -> Scheduler-Tick fehlgeschlagen; Runtime-/Log-Fehler prüfen.
heartbeat skipped mit reason=quiet-hours -> Außerhalb des aktiven Zeitfensters.
heartbeat: unknown accountId -> Ungültige Account-ID für Heartbeat-Zustellungsziel.
heartbeat skipped mit reason=dm-blocked -> Heartbeat-Ziel wurde auf ein DM-ähnliches Ziel aufgelöst, während agents.defaults.heartbeat.directPolicy (oder per-Agent-Override) auf block steht.

Verwandt:

Gekoppeltes Node-Tool schlägt fehl

Wenn ein Node gekoppelt ist, aber Tools fehlschlagen, isoliere Vordergrund-, Berechtigungs- und Genehmigungsstatus.

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status

Suche nach:

Node online mit erwarteten Fähigkeiten.
OS-Berechtigungserteilungen 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 OS-Berechtigung.
SYSTEM_RUN_DENIED: approval required -> Exec-Genehmigung ausstehend.
SYSTEM_RUN_DENIED: allowlist miss -> Befehl durch Allowlist blockiert.

Verwandt:

Browser-Tool schlägt fehl

Nutze dies, wenn Browser-Tool-Aktionen fehlschlagen, obwohl das Gateway selbst gesund ist.

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor

Suche nach:

Gültigem Browser-Executable-Pfad.
CDP-Profil-Erreichbarkeit.
Extension-Relay-Tab-Anbindung für profile="chrome".

Häufige Signaturen:

Failed to start Chrome CDP on port -> Browser-Prozess konnte nicht gestartet werden.
browser.executablePath not found -> Konfigurierter Pfad ist ungültig.
Chrome extension relay is running, but no tab is connected -> Extension-Relay nicht angebunden.
Browser attachOnly is enabled ... not reachable -> Attach-only-Profil hat kein erreichbares Ziel.

Verwandt:

Nach einem Upgrade ist etwas plötzlich kaputt

Die meisten Post-Upgrade-Probleme sind Config-Drift oder jetzt strenger erzwungene Standardwerte.

1) Auth- und URL-Override-Verhalten hat sich geändert

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

Was prüfen:

Wenn gateway.mode=remote, zielen CLI-Aufrufe möglicherweise auf Remote, während dein lokaler Service in Ordnung ist.
Explizite --url-Aufrufe fallen nicht auf gespeicherte Credentials zurück.

Häufige Signaturen:

gateway connect failed: -> Falsches URL-Ziel.
unauthorized -> Endpunkt erreichbar, aber falsche Auth.

2) Bind- und Auth-Sicherungen sind strenger

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

Was prüfen:

Nicht-Loopback-Bindungen (lan, tailnet, custom) brauchen konfigurierte Auth.
Alte Keys wie gateway.token ersetzen nicht gateway.auth.token.

Häufige Signaturen:

refusing to bind gateway ... without auth -> Bind+Auth-Diskrepanz.
RPC probe: failed während Runtime läuft -> Gateway aktiv, aber mit aktueller Auth/URL nicht erreichbar.

3) Pairing- und Device-Identity-Status hat sich geändert

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

Was prüfen:

Ausstehende Device-Genehmigungen für Dashboard/Nodes.
Ausstehende DM-Pairing-Genehmigungen nach Policy- oder Identitätsänderungen.

Häufige Signaturen:

device identity required -> Device-Auth nicht erfüllt.
pairing required -> Absender/Gerät muss genehmigt werden.

Wenn Service-Konfiguration und Runtime nach den Prüfungen immer noch nicht übereinstimmen, installiere die Service-Metadaten aus demselben Profil-/State-Verzeichnis neu:

openclaw gateway install --force
openclaw gateway restart

Verwandt: