Zum Hauptinhalt springen

​
Gateway-Fehlerbehebung

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

​
Befehlsleiter

Führen Sie diese zuerst aus, in dieser Reihenfolge: 
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 Konfigurations-/Dienstprobleme.
  • openclaw channels status --probe zeigt verbundene/bereite Kanäle.

​
Keine Antworten

Wenn Kanäle aktiv sind, aber nichts antwortet, prüfen Sie Routing und Richtlinien, bevor Sie irgendetwas neu verbinden. 
openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw config get channels
openclaw logs --follow
Achten Sie auf:
  • Ausstehende Kopplung für DM-Absender.
  • Gruppen-Erwähnungs-Gating (requireMention, mentionPatterns).
  • Abweichungen in der Kanal-/Gruppen-Allowlist.
Häufige Signaturen:
  • drop guild message (mention required → Gruppen-Nachricht wird ignoriert, bis eine Erwähnung erfolgt.
  • pairing request → Absender benötigt Freigabe.
  • blocked / allowlist → Absender/Kanal wurde durch Richtlinie gefiltert.
Verwandt:

​
Dashboard-/Control-UI-Konnektivität

Wenn das Dashboard/die Control-UI keine Verbindung herstellt, validieren Sie URL, Authentifizierungsmodus und Annahmen zum sicheren Kontext. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json
Achten Sie auf:
  • Korrekte Probe-URL und Dashboard-URL.
  • Abweichungen beim Authentifizierungsmodus/Token zwischen Client und Gateway.
  • HTTP-Nutzung, wo Geräteidentität erforderlich ist.
Häufige Signaturen:
  • device identity required → unsicherer Kontext oder fehlende Geräteauthentifizierung.
  • unauthorized / Reconnect-Schleife → Token-/Passwortabweichung.
  • gateway connect failed: → falsches Host/Port/URL-Ziel.
Verwandt:

​
Gateway-Dienst läuft nicht

Verwenden Sie dies, wenn der Dienst installiert ist, der Prozess aber nicht stabil läuft. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep
Achten Sie auf:
  • Runtime: stopped mit Exit-Hinweisen.
  • Abweichende Dienstkonfiguration (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: Setzen Sie gateway.mode="local" in Ihrer Konfiguration (oder führen Sie openclaw configure aus). Wenn Sie OpenClaw über Podman mit dem dedizierten Benutzer openclaw ausführen, befindet sich die Konfiguration unter ~openclaw/.openclaw/openclaw.json.
  • refusing to bind gateway ... without auth → Nicht-Loopback-Bindung ohne Token/Passwort.
  • another gateway instance is already listening / EADDRINUSE → Portkonflikt.
Verwandt:

​
Kanal verbunden, Nachrichten fließen nicht

Wenn der Kanalstatus „verbunden“ ist, der Nachrichtenfluss jedoch ausbleibt, konzentrieren Sie sich auf Richtlinien, Berechtigungen und kanalspezifische Zustellregeln. 
openclaw channels status --probe
openclaw pairing list <channel>
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 wird durch Gruppen-Erwähnungsrichtlinie ignoriert.
  • pairing / Spuren ausstehender Freigaben → Absender ist nicht freigegeben.
  • missing_scope, not_in_channel, Forbidden, 401/403 → Kanal-Auth-/Berechtigungsproblem.
Verwandt:

​
Cron- und Heartbeat-Zustellung

Wenn Cron oder Heartbeat nicht ausgeführt wurde oder nicht zugestellt hat, prüfen Sie zuerst den Scheduler-Status, 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ächstes Aufwachen vorhanden.
  • Status der Job-Ausführungshistorie (ok, skipped, error).
  • Gründe für Heartbeat-Überspringen (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; prüfen Sie Datei-/Log-/Runtime-Fehler.
  • heartbeat skipped mit reason=quiet-hours → außerhalb des Zeitfensters aktiver Stunden.
  • heartbeat: unknown accountId → ungültige Konto-ID für das Heartbeat-Zustellziel.
Verwandt:

​
Gekoppeltes Node-Werkzeug schlägt fehl

Wenn ein Node gekoppelt ist, Werkzeuge jedoch fehlschlagen, isolieren Sie Vordergrund-, Berechtigungs- und Freigabestatus. 
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.
  • OS-Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
  • Exec-Freigaben 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-Freigabe ausstehend.
  • SYSTEM_RUN_DENIED: allowlist miss → Befehl durch Allowlist blockiert.
Verwandt:

​
Browser-Werkzeug schlägt fehl

Verwenden Sie dies, wenn Aktionen des Browser-Werkzeugs fehlschlagen, obwohl das Gateway selbst gesund ist. 
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor
Achten Sie auf:
  • Gültigen Pfad zur Browser-Executable.
  • Erreichbarkeit des CDP-Profils.
  • Anbindung des Extension-Relay-Tabs 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 → reines Attach-Profil hat kein erreichbares Ziel.
Verwandt:

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

Die meisten Probleme nach einem Upgrade sind Konfigurationsdrift oder nun durchgesetzte strengere Standardwerte.

​
1. Verhalten bei Authentifizierung und URL-Overrides geändert

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, können CLI-Aufrufe auf „remote“ zielen, während Ihr lokaler Dienst in Ordnung ist.
  • Explizite --url-Aufrufe fallen nicht auf gespeicherte Anmeldedaten zurück.
Häufige Signaturen:
  • gateway connect failed: → falsches URL-Ziel.
  • unauthorized → Endpunkt erreichbar, aber falsche Authentifizierung.

​
2. Bind- und Auth-Guardrails sind strenger

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow
Was zu prüfen ist:
  • Nicht-Loopback-Bindungen (lan, tailnet, custom) erfordern konfigurierte Authentifizierung.
  • Alte Schlüssel wie gateway.token ersetzen nicht gateway.auth.token.
Häufige Signaturen:
  • refusing to bind gateway ... without auth → Bind+Auth-Abweichung.
  • RPC probe: failed während die Runtime läuft → Gateway lebt, ist aber mit aktueller Auth/URL nicht erreichbar.

​
3. Kopplungs- und Geräteidentitätsstatus geändert

openclaw devices list
openclaw pairing list <channel>
openclaw logs --follow
openclaw doctor
Was zu prüfen ist:
  • Ausstehende Gerätefreigaben für Dashboard/Nodes.
  • Ausstehende DM-Kopplungsfreigaben nach Richtlinien- oder Identitätsänderungen.
Häufige Signaturen:
  • device identity required → Geräteauthentifizierung nicht erfüllt.
  • pairing required → Absender/Gerät muss freigegeben werden.
Wenn Dienstkonfiguration und Runtime nach den Prüfungen weiterhin nicht übereinstimmen, installieren Sie die Dienstmetadaten aus demselben Profil-/Statusverzeichnis neu: 
openclaw gateway install --force
openclaw gateway restart
Verwandt: