Fehlerbehebung

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

Befehlsleiter

Führen Sie diese zuerst in dieser Reihenfolge aus:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

Erwartete gesunde 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.

Nach einem Update

Verwenden Sie dies, wenn ein Update abgeschlossen ist, der Gateway aber nicht läuft, Channels leer sind oder Modellaufrufe mit 401-Fehlern fehlschlagen.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

Achten Sie auf:

• Update restart in openclaw status / openclaw status --all. Ausstehende oder fehlgeschlagene Übergaben enthalten den nächsten auszuführenden Befehl.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix unter Channels. Das bedeutet, dass die Channel-Konfiguration noch vorhanden ist, die Plugin- Registrierung aber fehlgeschlagen ist, bevor der Channel geladen werden konnte.
• Provider-401-Fehler nach erneuter Authentifizierung. openclaw doctor --fix prüft auf veraltete OAuth-Auth-Schatten pro Agent und entfernt die alten Kopien, sodass alle Agents das aktuelle gemeinsame Profil auflösen.

Split-Brain-Installationen und Schutz für neuere Konfigurationen

Verwenden Sie dies, wenn ein Gateway-Dienst nach einem Update unerwartet stoppt oder Logs zeigen, dass ein openclaw-Binary ä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 Konfiguration prüfen, die von einem neueren OpenClaw geschrieben wurde, aber Prozess- und Dienstmutationen verweigern die Fortsetzung mit einem älteren Binary. Blockierte Aktionen umfassen Start, Stopp, Neustart und Deinstallation des Gateway-Dienstes, erzwungene Dienstneuinstallation, Gateway-Start im Dienstmodus und gateway --force-Portbereinigung.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

Protokollkonflikt nach Rollback

Verwenden Sie dies, wenn Logs nach einem Downgrade oder Rollback von OpenClaw weiterhin protocol mismatch ausgeben. Das bedeutet, dass ein älterer Gateway läuft, aber ein neuerer lokaler Clientprozess weiterhin versucht, sich mit einem Protokollbereich neu zu verbinden, den der ältere Gateway nicht sprechen kann.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

Achten Sie auf:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> in Gateway-Logs.
• Established clients: in openclaw gateway status --deep oder Gateway clients in openclaw doctor --deep. Dies listet aktive TCP-Clients auf, die mit dem Gateway-Port verbunden sind, einschließlich PIDs und Befehlszeilen, wenn das Betriebssystem dies erlaubt.
• Einen Clientprozess, dessen Befehlszeile auf die neuere OpenClaw-Installation oder den Wrapper zeigt, von der bzw. dem Sie zurückgerollt haben.

Behebung:

1. Stoppen oder starten Sie den veralteten OpenClaw-Clientprozess neu, der von gateway status --deep angezeigt wird.
2. Starten Sie Apps oder Wrapper neu, die OpenClaw einbetten, etwa lokale Dashboards, Editoren, App-Server-Helfer oder lange laufende openclaw logs --follow-Shells.
3. Führen Sie openclaw gateway status --deep oder openclaw doctor --deep erneut aus und bestätigen Sie, dass die veraltete Client-PID verschwunden ist.

Bringen Sie einen älteren Gateway nicht dazu, ein neueres inkompatibles Protokoll zu akzeptieren. Protokoll-Bumps schützen den Wire-Vertrag; Rollback-Wiederherstellung ist ein Prozess-/Versionsbereinigungsproblem.

Skill-Symlink wegen Pfad-Ausbruch übersprungen

Verwenden Sie dies, wenn Logs Folgendes enthalten:

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

OpenClaw behandelt jeden Skill-Root als Containment-Grenze. Ein Symlink unter ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills oder ~/.openclaw/skills wird übersprungen, wenn sein reales Ziel außerhalb dieses Roots aufgelöst wird, es sei denn, das Ziel ist ausdrücklich vertrauenswürdig.

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 erlaubte 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. Starten Sie den Gateway neu, wenn der laufende Prozess älter als die Konfigurationsänderung ist.

Verwenden Sie keine breiten Ziele wie ~, / oder einen ganzen synchronisierten Projektordner. Halten Sie allowSymlinkTargets auf den realen Skill-Root beschränkt, der vertrauenswürdige SKILL.md-Verzeichnisse enthält.

Wenn Skill Workshop apply ebenfalls durch diese vertrauenswürdigen symlinkten Workspace-Skill-Pfade schreiben soll, aktivieren Sie skills.workshop.allowSymlinkTargetWrites. Lassen Sie es für schreibgeschützte gemeinsame Skill-Roots deaktiviert.

Verwandt:

• Skills-Konfiguration
• Konfigurationsbeispiele

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 --followopenclaw models statusopenclaw config get agents.defaults.models

Achten Sie auf:

• Das ausgewählte Anthropic-Modell ist ein GA-fähiges 1M-Claude-4.x-Modell, oder das Modell hat das veraltete params.context1m: true.
• Die aktuellen Anthropic-Anmeldedaten sind nicht für Long-Context-Nutzung berechtigt.
• Anfragen schlagen nur bei langen Sitzungen/Modellläufen fehl, die den 1M-Kontextpfad benötigen.

Behebungsoptionen:

Verwandt:

• Anthropic
• Token-Nutzung und Kosten
• Warum sehe ich HTTP 429 von Anthropic?

Upstream-403-blockierte Antworten

Verwenden Sie dies, wenn ein Upstream-LLM-Provider ein generisches 403 zurückgibt, etwa Your request was blocked.

Gehen Sie nicht davon aus, dass dies immer ein OpenClaw-Konfigurationsproblem ist. Die Antwort kann von einer Upstream-Sicherheitsschicht stammen, etwa einem CDN, einer WAF, einer Bot-Management-Regel oder einem Reverse Proxy vor einem OpenAI-kompatiblen Endpunkt.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Achten Sie auf:

• mehrere Modelle unter demselben Provider schlagen auf die gleiche Weise fehl
• HTML oder generischer Sicherheitstext statt eines normalen Provider-API-Fehlers
• Provider-seitige Sicherheitsereignisse zur gleichen Anfragezeit
• eine winzige direkte curl-Probe ist erfolgreich, während normale SDK-förmige Anfragen fehlschlagen

Beheben Sie zuerst die Provider-seitige Filterung, wenn die Belege auf eine WAF-/CDN- Blockierung hindeuten. Bevorzugen Sie eine eng begrenzte Allow- oder Skip-Regel für den API-Pfad, den OpenClaw verwendet, und vermeiden Sie es, den Schutz für die ganze Site zu deaktivieren.

Verwandt:

• OpenAI-kompatible Endpunkte
• Provider-Konfiguration
• Logs

Lokales OpenAI-kompatibles Backend besteht direkte Proben, 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/modelscurl 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" --jsonopenclaw logs --follow

Achten Sie auf:

• 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 nackten Modell-ID funktionieren
• Backend-Fehler darüber, dass messages[].content einen String erwartet
• sporadische 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

Verwandt:

• Konfiguration
• Lokale Modelle
• OpenAI-kompatible Endpunkte

Keine Antworten

Wenn Channels aktiv sind, aber nichts antwortet, prüfen Sie Routing und Richtlinien, bevor Sie etwas neu verbinden.

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

Achten Sie auf:

• Ausstehendes Pairing für DM-Absender.
• Erwähnungs-Gating in Gruppen (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:

• Channel-Fehlerbehebung
• Gruppen
• Pairing

Dashboard-Control-UI-Konnektivität

Wenn Dashboard/Control UI keine Verbindung herstellt, prüfen Sie URL, Auth-Modus und Annahmen zum sicheren Kontext.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

Achten Sie auf:

• Korrekte Probe-URL und Dashboard-URL.
• Abweichung von Auth-Modus/Token zwischen Client und Gateway.
• HTTP-Nutzung, obwohl Geräteidentität erforderlich ist.

Wenn ein lokaler Browser nach einem Update keine Verbindung zu 127.0.0.1:18789 herstellen kann, stellen Sie zuerst den lokalen Gateway-Dienst wieder her und bestätigen Sie, dass er das Dashboard bereitstellt:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

Wenn curl OpenClaw-HTML zurückgibt, funktioniert der Gateway, und das verbleibende Problem ist wahrscheinlich Browser-Cache, ein alter Deep Link oder veralteter Tab-Zustand. Öffnen Sie http://127.0.0.1:18789 direkt und navigieren Sie vom Dashboard aus. Wenn der Dienst nach einem Neustart nicht weiterläuft, führen Sie openclaw gateway start aus und prüfen Sie openclaw gateway status erneut.

Schnellübersicht der Auth-Detailcodes

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

Prüfung der Geräte-Auth-v2-Migration:

openclaw --versionopenclaw doctoropenclaw gateway status

Wenn Logs Nonce-/Signaturfehler anzeigen, aktualisieren Sie den verbindenden Client und prüfen Sie ihn:

Wenn openclaw devices rotate / revoke / remove unerwartet verweigert wird:

• Sitzungen mit gekoppeltem Geräte-Token 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 Aufrufer-Sitzung bereits besitzt

Verwandt:

• Konfiguration (Gateway-Auth-Modi)
• Control UI
• Geräte
• Remote-Zugriff
• Trusted-Proxy-Auth

Gateway-Dienst läuft nicht

Verwenden Sie dies, wenn der Dienst installiert ist, der Prozess aber nicht aktiv bleibt.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # also scan system-level services

Achten Sie auf:

• Runtime: stopped mit Exit-Hinweisen.
• Abweichung der Dienstkonfiguration (Config (cli) vs Config (service)).
• Port-/Listener-Konflikte.
• Zusätzliche launchd-/systemd-/schtasks-Installationen, wenn --deep verwendet wird.
• Bereinigungshinweise zu Other gateway-like services detected (best effort).

Verwandt:

• Hintergrundausführung und Prozesstool
• Konfiguration
• Doctor

macOS-Gateway antwortet ohne Meldung nicht mehr und setzt fort, wenn Sie das Dashboard berühren

Verwenden Sie dies, wenn Channels (Telegram, WhatsApp usw.) auf einem macOS-Host für Minuten bis Stunden stumm bleiben und der Gateway scheinbar genau in dem Moment zurückkommt, in dem Sie die Control UI öffnen, sich per SSH anmelden oder anderweitig mit dem Host interagieren. In openclaw status gibt es normalerweise kein offensichtliches Symptom, weil der Gateway zu dem Zeitpunkt, an dem Sie nachsehen, wieder aktiv ist.

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

Achten Sie auf:

• Ein oder mehrere *-uncaught_exception.json-Bundles in ~/.openclaw/logs/stability/, bei denen error.code auf einen transienten Netzwerkcode wie ENETDOWN, ENETUNREACH, EHOSTUNREACH oder ECONNREFUSED gesetzt ist.
• pmset -g log-Zeilen wie Entering Sleep state due to 'Maintenance Sleep' oder en0 driver is slow (msg: WillChangeState to 0), die zeitlich mit den Absturz-Zeitstempeln übereinstimmen. Power Nap / Maintenance Sleep versetzt den WLAN-Treiber kurzzeitig in Zustand 0; jeder ausgehende connect(), der in dieses Zeitfenster fällt, kann mit ENETDOWN fehlschlagen, selbst auf einem Host, der ansonsten vollständige Netzwerkverbindung hat.
• launchctl print-Ausgabe mit state = not running, mehreren aktuellen runs und einem Exit-Code, insbesondere wenn die Lücke zwischen Absturz und nächstem Start eher in der Größenordnung einer Stunde als weniger Sekunden liegt. macOS launchd wendet nach einer Absturzserie eine nicht dokumentierte Respawn-Schutzsperre an, die dazu führen kann, dass KeepAlive=true nicht mehr beachtet wird, bis ein externer Auslöser wie interaktive Anmeldung, Dashboard-Verbindung oder launchctl kickstart sie wieder aktiviert.

Häufige Signaturen:

• Ein Stabilitäts-Bundle, dessen error.code ENETDOWN oder ein verwandter Code ist, wobei der Callstack in Node net lookupAndConnect / Socket.connect zeigt. OpenClaw 2026.5.26 und neuer klassifizieren diese als harmlose transiente Netzwerkfehler, sodass sie nicht mehr bis zum obersten Handler für nicht abgefangene Ausnahmen propagieren; wenn Sie eine ältere Version verwenden, aktualisieren Sie zuerst.
• Lange ruhige Phasen, die in dem Moment enden, in dem Sie eine Verbindung zur Control UI herstellen oder sich per SSH beim Host anmelden: Die benutzersichtbare Aktivität aktiviert die Respawn-Sperre von launchd wieder, nicht etwas, das das Dashboard mit dem Gateway macht.
• runs-Zähler steigt im Tagesverlauf, ohne entsprechende Zeile received SIG*; shutting down in ~/Library/Logs/openclaw/gateway.log: Saubere Beendigungen protokollieren ein Signal; transiente Abstürze nicht.

Was zu tun ist:

1. Aktualisieren Sie das Gateway, wenn Sie eine Version vor 2026.5.26 verwenden. Nach dem Upgrade werden zukünftige ENETDOWN-Fehler als Warnungen protokolliert, statt den Prozess zu beenden.

2. Reduzieren Sie Wartungs-Ruhezustandsaktivität auf Mac mini- / Desktop-Hosts, die als dauerhaft laufende Server gedacht sind:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   Dies reduziert das zugrunde liegende Treiberflattern deutlich, beseitigt es aber nicht vollständig. Das System kann unabhängig von diesen Flags weiterhin einige Wartungs-Ruhezustände für TCP-Keepalive und mDNS-Pflege ausführen.

3. Fügen Sie einen Liveness-Watchdog hinzu, damit eine zukünftige Absturzserie, die von launchd geparkt wird, schnell erkannt wird:

   # Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgentstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   Ziel ist es, die Respawn-Sperre extern wieder zu aktivieren; KeepAlive=true allein reicht unter macOS nach einer Absturzserie nicht aus.

Verwandt:

• macOS-Plattformhinweise
• Logging
• Doctor

Gateway wird bei hoher Speichernutzung beendet

Verwenden Sie dies, wenn das Gateway unter Last verschwindet, der Supervisor einen OOM-artigen Neustart meldet oder Logs critical memory pressure bundle written erwähnen.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

Achten Sie auf:

• Reason: diagnostic.memory.pressure.critical im neuesten Stabilitäts-Bundle.
• Memory pressure: mit critical/rss_threshold, critical/heap_threshold oder critical/rss_growth.
• V8 heap:-Werte nahe am Heap-Limit.
• Largest session files:-Einträge wie agents/<agent>/sessions/<session>.jsonl oder sessions/<session>.jsonl.
• Linux-cgroup-Speicherzähler, wenn das Gateway in einem Container oder einem speicherbegrenzten Dienst läuft.

Häufige Signaturen:

• critical memory pressure bundle written erscheint kurz vor dem Neustart → OpenClaw hat ein Prä-OOM-Stabilitäts-Bundle erfasst. Prüfen Sie es mit openclaw gateway stability --bundle latest.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled erscheint in Gateway-Logs → OpenClaw hat kritischen Speicherdruck erkannt, aber der Prä-OOM-Stabilitäts-Snapshot ist deaktiviert.
• Largest session files: verweist auf einen sehr großen redigierten Transkriptpfad → reduzieren Sie die aufbewahrte Sitzungsverlaufshistorie, prüfen Sie das Sitzungswachstum oder verschieben Sie alte Transkripte vor dem Neustart aus dem aktiven Speicher.
• Verwendete Bytes bei V8 heap: liegen nahe am Heap-Limit → senken Sie Prompt-/Sitzungsdruck, reduzieren Sie gleichzeitige Arbeit oder erhöhen Sie das Node-Heap-Limit erst, nachdem bestätigt wurde, dass die Arbeitslast erwartet ist.
• Memory pressure: critical/rss_growth → Speicher ist innerhalb eines Sampling-Fensters schnell gewachsen. Prüfen Sie die neuesten Logs auf einen großen Import, ausufernde Tool-Ausgabe, wiederholte Retries oder einen Stapel wartender Agent-Arbeit.
• Kritischer Speicherdruck erscheint in Logs, aber es existiert kein Bundle → dies ist die Standardeinstellung. Setzen Sie diagnostics.memoryPressureSnapshot: true, um das Prä-OOM-Stabilitäts-Bundle bei zukünftigen Ereignissen mit kritischem Speicherdruck zu erfassen.

Das Stabilitäts-Bundle enthält keine Payloads. Es enthält operative Speicherhinweise und redigierte relative Dateipfade, aber keine Nachrichtentexte, Webhook-Bodys, Zugangsdaten, Tokens, Cookies oder rohen Sitzungs-IDs. Hängen Sie den Diagnoseexport an Fehlerberichte an, statt rohe Logs zu kopieren.

Verwandt:

• Gateway-Zustand
• Diagnoseexport
• Sitzungen

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 --followopenclaw config fileopenclaw config validateopenclaw 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 defekte direkte Bearbeitung repariert hat
• OpenClaw behält die neuesten 32 .clobbered.*-Dateien für jeden Konfigurationspfad und rotiert ältere

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

Verwandt:

• Konfiguration
• Konfiguration: Hot Reload
• Konfiguration: strikte Validierung
• Doctor

Gateway-Probe-Warnungen

Verwenden Sie dies, wenn openclaw gateway probe etwas erreicht, aber trotzdem einen Warnungsblock ausgibt.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

Achten Sie auf:

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

Häufige Signaturen:

• SSH tunnel failed to start; falling back to direct probes. → SSH-Einrichtung ist fehlgeschlagen, aber der Befehl hat trotzdem direkte konfigurierte/Loopback-Ziele versucht.
• multiple reachable gateway identities detected → unterschiedliche Gateways haben geantwortet, oder OpenClaw konnte nicht nachweisen, dass erreichbare Ziele dasselbe Gateway sind. Ein SSH-Tunnel, eine Proxy-URL oder eine konfigurierte Remote-URL zum selben Gateway wird als ein Gateway mit mehreren Transporten behandelt, selbst wenn sich Transport-Ports unterscheiden.
• 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 zeitüberschritten 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 weiterhin Pairing/Genehmigung vor normalem Operator-Zugriff.
• nicht aufgelöster gateway.auth.*- / gateway.remote.*-SecretRef-Warnungstext → Auth-Material war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar.

Verwandt:

• Gateway
• Mehrere Gateways auf demselben Host
• Remote-Zugriff

Channel verbunden, Nachrichten fließen nicht

Wenn der Channel-Status verbunden ist, aber der Nachrichtenfluss tot ist, konzentrieren Sie sich auf Policy, Berechtigungen und channelspezifische Zustellregeln.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

Achten Sie auf:

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

Häufige Signaturen:

• mention required → Nachricht wurde durch Gruppen-Erwähnungs-Policy ignoriert.
• pairing / Spuren ausstehender Genehmigung → Absender ist nicht genehmigt.
• missing_scope, not_in_channel, Forbidden, 401/403 → Channel-Auth-/Berechtigungsproblem.

Verwandt:

• Channel-Fehlerbehebung
• Discord
• Telegram
• WhatsApp

Cron- und Heartbeat-Zustellung

Wenn Cron oder Heartbeat nicht gelaufen ist oder nicht zugestellt wurde, prüfen Sie zuerst den Scheduler-Zustand und dann das Zustellziel.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

Achten Sie auf:

• Cron aktiviert und nächstes Aufwachen vorhanden.
• Status des Jobausfü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).

Verwandt:

• Heartbeat
• Geplante Aufgaben
• Geplante Aufgaben: Fehlerbehebung

Node gekoppelt, Tool schlägt fehl

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

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

Achten Sie auf:

• Node online mit erwarteten Fähigkeiten.
• OS-Berechtigungsfreigaben 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:

• Exec-Genehmigungen
• Node-Fehlerbehebung
• Nodes

Browser-Tool schlägt fehl

Verwenden Sie dies, wenn Browser-Tool-Aktionen fehlschlagen, obwohl der Gateway selbst fehlerfrei ist.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

Achten Sie auf:

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

Verwandt:

• Browser (von OpenClaw verwaltet)
• Browser-Fehlerbehebung

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

Die meisten Probleme nach einem Upgrade entstehen durch Konfigurationsabweichungen oder dadurch, dass strengere Standardwerte jetzt durchgesetzt werden.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

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

Wenn Dienstkonfiguration und Runtime nach den Prüfungen weiterhin voneinander abweichen, installieren Sie die Dienstmetadaten aus demselben Profil-/Statusverzeichnis neu:

openclaw gateway install --forceopenclaw gateway restart

Verwandt:

• Authentifizierung
• Hintergrundausführung und Prozesstool
• Gateway-eigenes Pairing

Verwandt

• Doctor
• FAQ
• Gateway-Runbook