​

Gateway-Fehlerbehebung

​

Befehlsleiter

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

• openclaw gateway status zeigt Runtime: running und RPC probe: ok.
• openclaw doctor meldet keine blockierenden Konfigurations-/Dienstprobleme.
• openclaw channels status --probe zeigt den Live-Transportstatus pro Konto und, wo unterstützt, Prüf-/Audit-Ergebnisse wie works oder audit ok.

​

Anthropic 429: Extra Usage für langen Kontext erforderlich

openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models

• Das ausgewählte Anthropic-Opus-/Sonnet-Modell hat params.context1m: true.
• Die aktuellen Anthropic-Anmeldedaten sind nicht für die Nutzung mit langem Kontext geeignet.
• Anfragen schlagen nur bei langen Sitzungen/Modelläufen fehl, die den 1M-Beta-Pfad benötigen.

1. context1m für dieses Modell deaktivieren, um auf das normale Kontextfenster zurückzufallen.
2. Einen Anthropic-API-Schlüssel mit Abrechnung verwenden oder Anthropic Extra Usage für das Anthropic-OAuth-/Abonnementkonto aktivieren.
3. Fallback-Modelle konfigurieren, damit Läufe fortgesetzt werden, wenn Anthropic-Anfragen mit langem Kontext abgelehnt werden.

• /providers/anthropic
• /reference/token-use
• /help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic

​

Keine Antworten

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

• Ausstehendes Pairing für DM-Absender.
• Erwähnungs-Gating in Gruppen (requireMention, mentionPatterns).
• Nicht übereinstimmende Kanal-/Gruppen-Allowlists.

• drop guild message (mention required → Gruppennachricht wird ignoriert, bis eine Erwähnung erfolgt.
• pairing request → der Absender benötigt eine Genehmigung.
• blocked / allowlist → Absender/Kanal wurde durch die Richtlinie gefiltert.

• /channels/troubleshooting
• /channels/pairing
• /channels/groups

​

Konnektivität von Dashboard / Control UI

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

• Korrekte Probe-URL und Dashboard-URL.
• Nicht übereinstimmender Auth-Modus/Token zwischen Client und Gateway.
• HTTP-Nutzung, wo Geräteidentität erforderlich ist.

• device identity required → unsicherer Kontext oder fehlende Geräteauthentifizierung.
• origin not allowed → Browser-Origin ist nicht in gateway.controlUi.allowedOrigins (oder Sie verbinden sich von einem Browser-Origin außerhalb von Loopback ohne explizite Allowlist).
• device nonce required / device nonce mismatch → der Client schließt den challenge-basierten Geräteauthentifizierungsablauf (connect.challenge + device.nonce) nicht ab.
• device signature invalid / device signature expired → der Client hat die falsche Payload (oder einen veralteten Zeitstempel) für den aktuellen Handshake signiert.
• AUTH_TOKEN_MISMATCH mit canRetryWithDeviceToken=true → der Client kann einen vertrauenswürdigen Wiederholungsversuch mit einem zwischengespeicherten Gerätetoken durchführen.
• Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet erneut die mit dem gekoppelten Gerätetoken gespeicherte Scope-Menge. Aufrufer mit explizitem deviceToken / expliziten scopes behalten stattdessen ihre angeforderte Scope-Menge.
• Außerhalb dieses Wiederholungsversuchs hat Connect-Auth folgende Vorrangreihenfolge: explizites gemeinsames Token/Passwort zuerst, dann explizites deviceToken, dann gespeichertes Gerätetoken, dann Bootstrap-Token.
• Auf dem asynchronen Tailscale-Serve-Control-UI-Pfad werden fehlgeschlagene Versuche für dieselbe {scope, ip} serialisiert, bevor der Limiter den Fehler erfasst. Zwei schlechte gleichzeitige Wiederholungsversuche desselben Clients können daher beim zweiten Versuch retry later ausgeben statt zwei einfacher Nichtübereinstimmungen.
• too many failed authentication attempts (retry later) von einem Loopback-Client mit Browser-Origin → wiederholte Fehler aus demselben normalisierten Origin werden vorübergehend ausgesperrt; ein anderer localhost-Origin verwendet einen separaten Bucket.
• wiederholtes unauthorized nach diesem Wiederholungsversuch → Drift zwischen gemeinsamem Token und Gerätetoken; Token-Konfiguration aktualisieren und Gerätetoken bei Bedarf erneut genehmigen/rotieren.
• gateway connect failed: → falsches Ziel für Host/Port/URL.

​

Schnellzuordnung der Auth-Detailcodes

openclaw --version
openclaw doctor
openclaw gateway status

1. auf connect.challenge wartet
2. die an die Challenge gebundene Payload signiert
3. connect.params.device.nonce mit derselben Challenge-Nonce sendet

• Sitzungen mit gekoppeltem Gerätetoken können nur ihr eigenes Gerät verwalten, außer der Aufrufer hat zusätzlich operator.admin
• openclaw devices rotate --scope ... kann nur Operator-Scopes anfordern, die die Aufrufer-Sitzung bereits besitzt

• /web/control-ui
• /gateway/configuration (Gateway-Auth-Modi)
• /gateway/trusted-proxy-auth
• /gateway/remote
• /cli/devices

​

Gateway-Dienst läuft nicht

openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # scannt auch Dienste auf Systemebene

• Runtime: stopped mit Hinweisen zum Beenden.
• Nicht übereinstimmende Dienstkonfiguration (Config (cli) vs Config (service)).
• Port-/Listener-Konflikte.
• Zusätzliche launchd-/systemd-/schtasks-Installationen bei Verwendung von --deep.
• Bereinigungshinweise unter Other gateway-like services detected (best effort).

• Gateway start blocked: set gateway.mode=local oder existing config is missing gateway.mode → der lokale Gateway-Modus ist nicht aktiviert, oder die Konfigurationsdatei wurde beschädigt und hat gateway.mode verloren. Behebung: gateway.mode="local" in Ihrer Konfiguration setzen oder openclaw onboard --mode local / openclaw setup erneut ausführen, um die erwartete Konfiguration für den lokalen Modus wiederherzustellen. Wenn Sie OpenClaw über Podman ausführen, ist der Standardpfad für die Konfiguration ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → Nicht-Loopback-Binding ohne gültigen Gateway-Auth-Pfad (Token/Passwort oder, wo konfiguriert, trusted-proxy).
• another gateway instance is already listening / EADDRINUSE → Portkonflikt.
• Other gateway-like services detected (best effort) → veraltete oder parallele launchd-/systemd-/schtasks-Units existieren. Die meisten Setups sollten ein Gateway pro Maschine beibehalten; wenn Sie mehr als eines benötigen, isolieren Sie Ports + Konfiguration/Status/Workspace. Siehe /gateway#multiple-gateways-same-host.

• /gateway/background-process
• /gateway/configuration
• /gateway/doctor

​

Gateway-Probe-Warnungen

openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host

• warnings[].code und primaryTargetId in der JSON-Ausgabe.
• Ob sich die Warnung auf SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Auth-Refs bezieht.

• SSH tunnel failed to start; falling back to direct probes. → das SSH-Setup ist fehlgeschlagen, aber der Befehl hat trotzdem direkte konfigurierte/Loopback-Ziele versucht.
• multiple reachable gateways detected → mehr als ein Ziel hat geantwortet. Normalerweise bedeutet das ein absichtliches Multi-Gateway-Setup oder veraltete/doppelte Listener.
• Probe diagnostics are limited by gateway scopes (missing operator.read) → Verbindung hat funktioniert, aber Detail-RPC ist durch Scopes eingeschränkt; Geräteidentität pairen oder Anmeldedaten mit operator.read verwenden.
• nicht aufgelöster Warntext zu gateway.auth.* / gateway.remote.* SecretRef → Auth-Material war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar.

• /cli/gateway
• /gateway#multiple-gateways-same-host
• /gateway/remote

​

Kanal verbunden, aber Nachrichten fließen nicht

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

• DM-Richtlinie (pairing, allowlist, open, disabled).
• Gruppen-Allowlist und Erwähnungsanforderungen.
• Fehlende API-Berechtigungen/Scopes des Kanals.

• mention required → Nachricht wird durch die Erwähnungsrichtlinie für Gruppen ignoriert.
• pairing / ausstehende Genehmigungsspuren → Absender ist nicht genehmigt.
• missing_scope, not_in_channel, Forbidden, 401/403 → Problem mit Kanal-Auth/Berechtigungen.

• /channels/troubleshooting
• /channels/whatsapp
• /channels/telegram
• /channels/discord

​

Cron- und Heartbeat-Zustellung

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

• Cron ist aktiviert und der nächste Wake ist vorhanden.
• Status des Job-Ausführungsverlaufs (ok, skipped, error).
• Gründe für das Überspringen des Heartbeats (quiet-hours, requests-in-flight, 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; prüfen Sie Datei-/Log-/Laufzeitfehler.
• heartbeat skipped mit reason=quiet-hours → außerhalb des Fensters aktiver Stunden.
• heartbeat skipped mit reason=empty-heartbeat-file → HEARTBEAT.md existiert, enthält aber nur leere Zeilen / Markdown-Header, daher überspringt OpenClaw den Modellaufruf.
• heartbeat skipped mit reason=no-tasks-due → HEARTBEAT.md enthält einen Block tasks:, aber bei diesem Tick ist keine der Aufgaben fällig.
• heartbeat: unknown accountId → ungültige accountId für das Zustellungsziel des Heartbeats.
• heartbeat skipped mit reason=dm-blocked → das Heartbeat-Ziel wurde zu einem Ziel im DM-Stil aufgelöst, während agents.defaults.heartbeat.directPolicy (oder eine Überschreibung pro Agent) auf block gesetzt ist.

• /automation/cron-jobs#troubleshooting
• /automation/cron-jobs
• /gateway/heartbeat

​

Tool eines gekoppelten Nodes schlägt fehl

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

• Node ist online und hat die erwarteten Fähigkeiten.
• Vom Betriebssystem gewährte Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
• Exec-Genehmigungen und Allowlist-Status.

• NODE_BACKGROUND_UNAVAILABLE → Node-App muss im Vordergrund sein.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → fehlende Betriebssystemberechtigung.
• SYSTEM_RUN_DENIED: approval required → Exec-Genehmigung ausstehend.
• SYSTEM_RUN_DENIED: allowlist miss → Befehl durch Allowlist blockiert.

• /nodes/troubleshooting
• /nodes/index
• /tools/exec-approvals

​

Browser-Tool schlägt fehl

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

• Ob plugins.allow gesetzt ist und browser enthält.
• Gültiger Pfad zur Browser-Executable.
• Erreichbarkeit des CDP-Profils.
• Verfügbarkeit von lokalem Chrome für Profile existing-session / user.

• unknown command "browser" oder unknown command 'browser' → das gebündelte Browser-Plugin wird durch plugins.allow ausgeschlossen.
• Browser-Tool fehlt / ist nicht verfügbar, obwohl browser.enabled=true gesetzt ist → plugins.allow schließt browser aus, sodass das Plugin nie geladen wurde.
• Failed to start Chrome CDP on port → Browser-Prozess konnte nicht gestartet werden.
• browser.executablePath not found → der konfigurierte 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.
• No Chrome tabs found for profile="user" → das Chrome-MCP-Attach-Profil hat keine offenen lokalen Chrome-Tabs.
• Remote CDP for profile "<name>" is not reachable → der konfigurierte entfernte 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 → das Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber das CDP-WebSocket konnte trotzdem nicht geöffnet werden.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → die aktuelle Gateway-Installation enthält nicht das vollständige Playwright-Paket; ARIA-Snapshots und einfache Seitenscreenshots können weiterhin funktionieren, aber Navigation, KI-Snapshots, Element-Screenshots über CSS-Selektoren und PDF-Export bleiben nicht verfügbar.
• fullPage is not supported for element screenshots → die Screenshot-Anfrage hat --full-page mit --ref oder --element kombiniert.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → Screenshot-Aufrufe von Chrome MCP / existing-session müssen Seitenerfassung oder ein Snapshot---ref verwenden, nicht CSS---element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → Upload-Hooks von Chrome MCP benötigen Snapshot-Refs, keine CSS-Selektoren.
• existing-session file uploads currently support one file at a time. → bei Chrome-MCP-Profilen einen Upload pro Aufruf senden.
• existing-session dialog handling does not support timeoutMs. → Dialog-Hooks bei Chrome-MCP-Profilen unterstützen keine Timeout-Überschreibungen.
• response body is not supported for existing-session profiles yet. → responsebody erfordert weiterhin einen verwalteten Browser oder ein rohes CDP-Profil.
• veraltete Überschreibungen für Viewport / Dark Mode / Locale / Offline in Attach-only- oder entfernten CDP-Profilen → openclaw browser stop --browser-profile <name> ausführen, um die aktive Steuersitzung zu schließen und den Emulationszustand von Playwright/CDP freizugeben, ohne das gesamte Gateway neu zu starten.

• /tools/browser-linux-troubleshooting
• /tools/browser

​

Wenn Sie ein Upgrade durchgeführt haben und plötzlich etwas nicht mehr funktioniert

​

1) Verhalten von Auth und URL-Überschreibungen hat sich geändert

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

• Wenn gateway.mode=remote gesetzt ist, können CLI-Aufrufe remote zielen, während Ihr lokaler Dienst in Ordnung ist.
• Explizite Aufrufe mit --url greifen nicht auf gespeicherte Anmeldedaten zurück.

• gateway connect failed: → falsches URL-Ziel.
• unauthorized → Endpunkt erreichbar, aber falsche Auth.

​

2) Guardrails für Bind und Auth sind strenger

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

• Nicht-Loopback-Bindings (lan, tailnet, custom) benötigen einen gültigen Gateway-Auth-Pfad: Auth mit gemeinsamem Token/Passwort oder eine korrekt konfigurierte Bereitstellung von trusted-proxy außerhalb von Loopback.
• Alte Schlüssel wie gateway.token ersetzen gateway.auth.token nicht.

• refusing to bind gateway ... without auth → Nicht-Loopback-Binding ohne gültigen Gateway-Auth-Pfad.
• RPC probe: failed während die Runtime läuft → Gateway lebt, ist aber mit der aktuellen Auth/URL nicht erreichbar.

​

3) Pairing- und Geräteidentitätsstatus hat sich geändert

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

• Ausstehende Gerätegenehmigungen für Dashboard/Nodes.
• Ausstehende DM-Pairing-Genehmigungen nach Änderungen an Richtlinie oder Identität.

• device identity required → Geräteauthentifizierung nicht erfüllt.
• pairing required → Absender/Gerät muss genehmigt werden.

openclaw gateway install --force
openclaw gateway restart

• /gateway/pairing
• /gateway/authentication
• /gateway/background-process