​

Gateway-Fehlerbehebung

​

Befehlsabfolge

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-/Serviceprobleme.
• openclaw channels status --probe zeigt den Live-Transportstatus pro Konto und, wo unterstützt, Probe-/Audit-Ergebnisse wie works oder audit ok.

​

Anthropic 429 zusätzlicher Verbrauch 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 aktuelle Anthropic-Anmeldung ist nicht für die Nutzung mit langem Kontext berechtigt.
• Anfragen schlagen nur bei langen Sitzungen/Modelläufen fehl, die den 1M-Beta-Pfad benötigen.

1. Deaktivieren Sie context1m für dieses Modell, um auf das normale Kontextfenster zurückzufallen.
2. Verwenden Sie eine Anthropic-Anmeldung, die für Anfragen mit langem Kontext berechtigt ist, oder wechseln Sie zu einem Anthropic-API-Schlüssel.
3. Konfigurieren Sie Fallback-Modelle, 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

​

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

• curl ... /v1/models funktioniert
• kleine direkte /v1/chat/completions-Aufrufe funktionieren
• OpenClaw-Modellä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

• Direkte kleine Aufrufe sind erfolgreich, aber OpenClaw-Läufe schlagen nur bei größeren Prompts fehl
• Backend-Fehler, bei denen messages[].content einen String erwartet
• Backend-Abstürze, die nur bei größeren Prompt-Token-Zahlen oder vollständigen Agent- Laufzeit-Prompts auftreten

• messages[...].content: invalid type: sequence, expected a string → das Backend lehnt strukturierte Chat-Completions-Inhaltsteile ab. Behebung: setzen Sie models.providers.<provider>.models[].compat.requiresStringContent: true.
• Direkte kleine Anfragen sind erfolgreich, aber OpenClaw-Agent-Läufe schlagen mit Backend-/Modell- Abstürzen fehl (zum Beispiel Gemma auf einigen inferrs-Builds) → der OpenClaw-Transport ist wahrscheinlich bereits korrekt; das Backend scheitert an der größeren Agent-Laufzeit- Prompt-Form.
• Die Fehler nehmen ab, nachdem Tools deaktiviert wurden, verschwinden aber nicht → Tool-Schemas waren Teil des Drucks, aber das verbleibende Problem ist weiterhin eine vorgelagerte Modell-/Server-Kapazität oder ein Backend-Fehler.

1. Setzen Sie compat.requiresStringContent: true für Chat-Completions-Backends, die nur Strings unterstützen.
2. Setzen Sie compat.supportsTools: false für Modelle/Backends, die die OpenClaw-Tool-Schema-Oberfläche nicht zuverlässig verarbeiten können.
3. Reduzieren Sie den Prompt-Druck, wo möglich: kleinerer Workspace-Bootstrap, kürzere Sitzungshistorie, leichteres lokales Modell oder ein Backend mit stärkerer Unterstützung für langen Kontext.
4. Wenn direkte kleine Anfragen weiterhin erfolgreich sind, während OpenClaw-Agent-Turns im Backend trotzdem abstürzen, behandeln Sie dies als vorgelagerte Server-/Modellbeschränkung und reichen Sie dort eine Reproduktion mit der akzeptierten Payload-Form ein.

• /gateway/local-models
• /gateway/configuration#models
• /gateway/configuration-reference#openai-compatible-endpoints

​

Keine Antworten

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

• Pairing steht für DM-Absender aus.
• Gating für Gruppenerwähnungen (requireMention, mentionPatterns).
• Nichtübereinstimmungen bei der Channel-/Gruppen-Allowlist.

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

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

​

Dashboard-Control-UI-Konnektivität

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

• Korrekte Probe-URL und Dashboard-URL.
• Nichtübereinstimmung bei 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 enthalten (oder Sie verbinden sich von einer Browser-Origin, die nicht loopback ist, ohne explizite Allowlist).
• device nonce required / device nonce mismatch → der Client schließt den herausforderungsbasierten Geräteauthentifizierungsablauf nicht ab (connect.challenge + device.nonce).
• 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 zwischengespeichertem Gerätetoken ausführen.
• Dieser Wiederholungsversuch mit zwischengespeichertem Token verwendet erneut die zwischengespeicherte Scope-Menge, die mit dem gekoppelten Gerätetoken gespeichert wurde. Aufrufer mit explizitem deviceToken / expliziten scopes behalten stattdessen ihre angeforderte Scope-Menge bei.
• Außerhalb dieses Wiederholungswegs ist die Priorität für die Verbindungsauthentifizierung explizit 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 fehlerhafte gleichzeitige Wiederholungsversuche desselben Clients können daher beim zweiten Versuch retry later statt zweier einfacher Nichtübereinstimmungen auslösen.
• too many failed authentication attempts (retry later) von einem loopback-Client mit Browser-Origin → wiederholte Fehler von derselben normalisierten Origin werden vorübergehend ausgesperrt; eine andere localhost-Origin verwendet einen separaten Bucket.
• Wiederholtes unauthorized nach diesem Wiederholungsversuch → Drift zwischen gemeinsamem Token/Gerätetoken; aktualisieren Sie die Token-Konfiguration und genehmigen/rotieren Sie das Gerätetoken bei Bedarf erneut.
• gateway connect failed: → falscher Host/Port/falsches URL-Ziel.

​

Schnelle Zuordnung von Auth-Detailcodes

openclaw --version
openclaw doctor
openclaw gateway status

1. auf connect.challenge wartet
2. 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, es sei denn, 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-Service 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übereinstimmung bei der Service-Konfiguration (Config (cli) vs Config (service)).
• Port-/Listener-Konflikte.
• Zusätzliche launchd-/systemd-/schtasks-Installationen bei Verwendung von --deep.
• Bereinigungshinweise für 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 ü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 Konfiguration für den lokalen Modus wiederherzustellen. Wenn Sie OpenClaw über Podman ausführen, ist der Standard-Konfigurationspfad ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → Nicht-loopback-Bind ohne gültigen Gateway-Auth-Pfad (Token/Passwort oder Trusted-Proxy, sofern konfiguriert).
• 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 tatsächlich 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. → die SSH-Einrichtung ist fehlgeschlagen, aber der Befehl hat trotzdem direkte konfigurierte/loopback-Ziele versucht.
• multiple reachable gateways detected → mehr als ein Ziel hat geantwortet. Das bedeutet normalerweise ein beabsichtigtes Multi-Gateway-Setup oder veraltete/duplizierte Listener.
• Probe diagnostics are limited by gateway scopes (missing operator.read) → die Verbindung hat funktioniert, aber die Detail-RPC ist durch Scopes eingeschränkt; koppeln Sie die Geräteidentität oder verwenden Sie Anmeldedaten mit operator.read.
• nicht aufgelöster SecretRef-Warntext zu gateway.auth.* / gateway.remote.* → Auth-Material war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar.

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

​

Channel 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 Anforderungen an Erwähnungen.
• Fehlende Channel-API-Berechtigungen/-Scopes.

• mention required → Nachricht wird durch die Gruppen-Erwähnungsrichtlinie ignoriert.
• pairing / ausstehende Genehmigungsspuren → der Absender ist nicht genehmigt.
• missing_scope, not_in_channel, Forbidden, 401/403 → Problem mit Channel-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 die nächste Aufweckzeit ist vorhanden.
• Status des Job-Ausführungsverlaufs (ok, skipped, error).
• Heartbeat-Überspringgründe (quiet-hours, requests-in-flight, alerts-disabled, empty-heartbeat-file, no-tasks-due).

• cron: scheduler disabled; jobs will not run automatically → Cron ist deaktiviert.
• cron: timer tick failed → Scheduler-Tick ist fehlgeschlagen; prüfen Sie Datei-/Log-/Laufzeitfehler.
• heartbeat skipped mit reason=quiet-hours → außerhalb des Zeitfensters für aktive Stunden.
• heartbeat skipped mit reason=empty-heartbeat-file → HEARTBEAT.md existiert, enthält aber nur Leerzeilen / 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 → das Heartbeat-Ziel wurde in ein Ziel im DM-Stil aufgelöst, während agents.defaults.heartbeat.directPolicy (oder die agentenspezifische Überschreibung) auf block gesetzt ist.

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

​

Gekoppeltes Node-Tool 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.
• OS-Berechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
• Exec-Genehmigungen und Allowlist-Status.

• NODE_BACKGROUND_UNAVAILABLE → die Node-App muss im Vordergrund sein.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → fehlende OS-Berechtigung.
• SYSTEM_RUN_DENIED: approval required → Exec-Genehmigung steht aus.
• SYSTEM_RUN_DENIED: allowlist miss → Befehl wurde durch die 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 existing-session-/user-Profile.

• unknown command "browser" oder unknown command 'browser' → das gebündelte Browser-Plugin ist durch plugins.allow ausgeschlossen.
• Browser-Tool fehlt / ist 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 → 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 fehlerhaften oder ungültigen Port.
• No Chrome tabs found for profile="user" → das Chrome-MCP-Attach-Profil 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 → das Attach-only-Profil hat kein erreichbares Ziel, oder der HTTP-Endpunkt hat geantwortet, aber der CDP-WebSocket konnte trotzdem nicht geöffnet werden.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → der aktuelle Gateway-Install enthält nicht das vollständige Playwright-Paket; ARIA-Snapshots und einfache Seitenscreenshots können weiterhin funktionieren, aber Navigation, AI-Snapshots, Element-Screenshots per CSS-Selektor 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 einen 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. → senden Sie bei Chrome-MCP-Profilen einen Upload pro Aufruf.
• existing-session dialog handling does not support timeoutMs. → Dialog-Hooks auf 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 / Gebietsschema / Offline-Modus auf 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 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, können CLI-Aufrufe auf remote zielen, während Ihr lokaler Service in Ordnung ist.
• Explizite --url-Aufrufe greifen nicht auf gespeicherte Anmeldedaten zurück.

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

​

2) Bind- und Auth-Schutzmechanismen 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-Binds (lan, tailnet, custom) benötigen einen gültigen Gateway-Auth-Pfad: gemeinsame Token-/Passwort-Authentifizierung oder eine korrekt konfigurierte nicht-loopback-trusted-proxy-Bereitstellung.
• Alte Schlüssel wie gateway.token ersetzen gateway.auth.token nicht.

• refusing to bind gateway ... without auth → Nicht-loopback-Bind 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 zugänglich.

​

3) Pairing- und Geräteidentitätsstatus haben 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 Richtlinien- oder Identitätsänderungen.

• device identity required → Geräteauthentifizierung ist 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