Fehlerbehebung

Dies ist das ausführliche Runbook. Beginnen Sie zunächst unter /help/troubleshooting mit dem schnellen Triage-Ablauf.

Befehlsabfolge

Führen Sie die Befehle in dieser Reihenfolge aus:

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

Anzeichen für einen fehlerfreien Zustand:

• 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 aktuellen Transportstatus für jedes Konto und, sofern unterstützt, works oder audit ok.

Nach einer Aktualisierung

Verwenden Sie diese Schritte, wenn eine Aktualisierung abgeschlossen ist, der Gateway jedoch nicht läuft, keine Channels angezeigt werden oder Modellaufrufe mit 401-Fehlern scheitern.

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

Achten Sie auf Folgendes:

• Update restart in openclaw status / openclaw status --all. Bei ausstehenden oder fehlgeschlagenen Übergaben wird der als Nächstes auszuführende Befehl angegeben.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix unter „Channels“: Die Channel-Konfiguration ist weiterhin vorhanden, aber die Plugin-Registrierung ist fehlgeschlagen, bevor der Channel geladen werden konnte.
• Provider-401-Fehler nach erneuter Authentifizierung: openclaw doctor --fix sucht nach veralteten agentenspezifischen Schattenkopien der OAuth-Authentifizierung und entfernt alte Kopien, damit alle Agenten das aktuelle gemeinsame Profil verwenden.

Parallele Installationen und Schutz vor neuerer Konfiguration

Verwenden Sie diese Schritte, wenn ein Gateway-Dienst nach einer Aktualisierung unerwartet beendet wird oder die Protokolle zeigen, dass ein openclaw-Programm älter ist als die Version, die openclaw.json zuletzt geschrieben hat.

OpenClaw versieht Konfigurationsschreibvorgänge mit meta.lastTouchedVersion. Schreibgeschützte Befehle können eine von einer neueren OpenClaw-Version geschriebene Konfiguration untersuchen, aber Prozess- und Dienständerungen werden von einem älteren Programm nicht ausgeführt. Folgende Aktionen werden blockiert: Starten, Beenden, Neustarten und Deinstallieren des Gateway-Dienstes, erzwungene Neuinstallation des Dienstes, Starten des Gateways im Dienstmodus sowie die Portbereinigung mit gateway --force.

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

openclaw gateway install --forceopenclaw gateway restart

Protokollabweichung nach einem Rollback

Verwenden Sie diese Schritte, wenn die Protokolle nach einer Herabstufung oder einem Rollback weiterhin protocol mismatch ausgeben. Ein älterer Gateway läuft, aber ein neuerer lokaler Clientprozess stellt weiterhin Verbindungen mit einem Protokollbereich her, den der ältere Gateway nicht unterstützt.

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

Achten Sie auf Folgendes:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> in den Gateway-Protokollen.
• Established clients: in openclaw gateway status --deep oder Gateway clients in openclaw doctor --deep: aktive TCP-Clients, die mit dem Gateway-Port verbunden sind, einschließlich PIDs und Befehlszeilen, sofern das Betriebssystem dies zulässt.
• Einen Clientprozess, dessen Befehlszeile auf die neuere OpenClaw-Installation oder den Wrapper verweist, von dem Sie das Rollback durchgeführt haben.

Behebung:

1. Beenden Sie den von gateway status --deep angezeigten veralteten OpenClaw-Clientprozess oder starten Sie ihn neu.
2. Starten Sie Anwendungen oder Wrapper neu, die OpenClaw einbetten: lokale Dashboards, Editoren, App-Server-Hilfsprogramme oder langlebige Shells mit openclaw logs --follow.
3. Führen Sie openclaw gateway status --deep oder openclaw doctor --deep erneut aus und vergewissern Sie sich, dass die PID des veralteten Clients nicht mehr vorhanden ist.

Versuchen Sie nicht, einen älteren Gateway zur Annahme eines neueren inkompatiblen Protokolls zu veranlassen. Protokollaktualisierungen schützen den Kommunikationsvertrag; die Wiederherstellung nach einem Rollback erfordert eine Bereinigung von Prozessen und Versionen.

Skill-Symlink wegen Pfadüberschreitung übersprungen

Verwenden Sie diese Schritte, wenn die Protokolle Folgendes enthalten:

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

Jedes Skill-Stammverzeichnis bildet eine Begrenzung. Ein Symlink unter ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills oder ~/.openclaw/skills wird übersprungen, wenn sein tatsächliches Ziel außerhalb dieses Stammverzeichnisses liegt, sofern das Ziel nicht ausdrücklich als vertrauenswürdig eingestuft wurde.

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 das direkte Skill-Stammverzeichnis als auch das zulässige Symlink-Ziel:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

Starten Sie anschließend eine neue Sitzung oder warten Sie, bis die Skill-Überwachung die Daten aktualisiert. Starten Sie den Gateway neu, wenn der laufende Prozess vor der Konfigurationsänderung gestartet wurde.

Verwenden Sie keine weit gefassten Ziele wie ~, / oder einen gesamten synchronisierten Projektordner. Beschränken Sie allowSymlinkTargets auf das tatsächliche Skill-Stammverzeichnis, das vertrauenswürdige SKILL.md-Verzeichnisse enthält.

Wenn „Skill Workshop apply“ auch über diese vertrauenswürdigen, per Symlink eingebundenen Workspace-Skill-Pfade schreiben soll, aktivieren Sie skills.workshop.allowSymlinkTargetWrites. Lassen Sie die Option für schreibgeschützte gemeinsame Skill-Stammverzeichnisse deaktiviert.

Verwandte Themen:

• Skills-Konfiguration
• Konfigurationsbeispiele

Anthropic 429: Zusätzliche Nutzung für langen Kontext erforderlich

Verwenden Sie diese Schritte, wenn Protokolle oder 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 Folgendes:

• Das ausgewählte Anthropic-Modell ist ein allgemein verfügbares, 1M-fähiges Claude-4.x-Modell (Opus 4.6/4.7/4.8, Sonnet 4.6), oder die Modellkonfiguration enthält noch den veralteten Wert params.context1m: true.
• Die aktuellen Anthropic-Anmeldedaten sind nicht für die Nutzung langer Kontexte berechtigt.
• Anfragen scheitern nur bei langen Sitzungen oder Modellläufen, die den 1M-Kontextpfad benötigen.

Behebungsoptionen:

Verwandte Themen:

• Anthropic
• Token-Nutzung und Kosten
• Warum wird HTTP 429 von Anthropic angezeigt?

Vom Upstream blockierte 403-Antworten

Verwenden Sie diese Schritte, wenn ein vorgelagerter LLM-Provider einen generischen 403-Fehler wie Your request was blocked zurückgibt.

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

openclaw statusopenclaw gateway statusopenclaw logs --follow

Achten Sie auf Folgendes:

• Mehrere Modelle desselben Providers scheitern auf dieselbe Weise.
• HTML oder generischer Sicherheitstext anstelle eines normalen Provider-API-Fehlers.
• Providerseitige Sicherheitsereignisse zum selben Anfragezeitpunkt.
• Eine minimale direkte curl-Prüfung ist erfolgreich, während normale SDK-förmige Anfragen scheitern.

Beheben Sie zuerst die providerseitige Filterung, wenn die Hinweise auf eine WAF-/CDN-Blockierung hindeuten. Bevorzugen Sie eine eng begrenzte Zulassungs- oder Überspringungsregel für den von OpenClaw verwendeten API-Pfad, und deaktivieren Sie den Schutz nicht für die gesamte Website.

Verwandte Themen:

• OpenAI-kompatible Endpunkte
• Provider-Konfiguration
• Protokolle

Lokales OpenAI-kompatibles Backend besteht direkte Prüfungen, aber Agentenläufe scheitern

Verwenden Sie diese Schritte, wenn:

• curl ... /v1/models funktioniert.
• Kleine direkte Aufrufe von /v1/chat/completions funktionieren.
• OpenClaw-Modellläufe nur bei normalen Agentendurchläufen scheitern.

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 Folgendes:

• Kleine direkte Aufrufe sind erfolgreich, aber OpenClaw-Läufe scheitern nur bei größeren Prompts.
• model_not_found- oder 404-Fehler, obwohl direkte Aufrufe von /v1/chat/completions mit derselben reinen Modell-ID funktionieren.
• Backend-Fehler, laut denen messages[].content eine Zeichenfolge sein muss.
• Sporadische Warnungen incomplete turn detected ... stopReason=stop payloads=0 bei einem lokalen OpenAI-kompatiblen Backend.
• Backend-Abstürze, die nur bei einer größeren Anzahl von Prompt-Tokens oder vollständigen Prompts der Agentenlaufzeit auftreten.

Verwandte Themen:

• Konfiguration
• Lokale Modelle
• OpenAI-kompatible Endpunkte

Keine Antworten

Wenn die Channels aktiv sind, aber keine Antworten eingehen, prüfen Sie Routing und Richtlinien, bevor Sie eine erneute Verbindung herstellen.

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ähnungsbeschränkung in Gruppen (requireMention, mentionPatterns).
• Abweichungen bei Channel-/Gruppen-Zulassungslisten.

Häufige Signaturen:

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

Verwandte Themen:

• Fehlerbehebung für Channels
• Gruppen
• Pairing

Konnektivität der Dashboard-Control-UI

Wenn die Dashboard-/Control-UI keine Verbindung herstellt, überprüfen Sie die URL, den Authentifizierungsmodus und die Annahmen zum sicheren Kontext.

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

Achten Sie auf:

• Korrekte Prüf-URL und Dashboard-URL.
• Nicht übereinstimmender Authentifizierungsmodus bzw. Token zwischen Client und Gateway.
• Verwendung von HTTP, obwohl eine 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 vergewissern Sie sich, dass er das Dashboard bereitstellt:

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

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

Schnellübersicht der Authentifizierungsdetailcodes

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

Prüfung der Migration auf Geräteauthentifizierung v2:

openclaw --versionopenclaw doctoropenclaw gateway status

Wenn die Protokolle Nonce-/Signaturfehler anzeigen, aktualisieren Sie den verbindungsherstellenden Client und überprüfen Sie ihn:

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

• Sitzungen mit Tokens gekoppelter Geräte können nur ihr eigenes Gerät verwalten, sofern der Aufrufer nicht zusätzlich über operator.admin verfügt.
• openclaw devices rotate --scope ... kann nur Operator-Berechtigungen anfordern, über die die Sitzung des Aufrufers bereits verfügt.

Verwandte Themen:

• Konfiguration (Gateway-Authentifizierungsmodi)
• Control-UI
• Geräte
• Remotezugriff
• Authentifizierung über vertrauenswürdige Proxys

Gateway-Dienst wird nicht ausgeführt

Verwenden Sie diesen Abschnitt, wenn der Dienst installiert ist, der Prozess jedoch nicht aktiv bleibt.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # auch systemweite Dienste prüfen

Achten Sie auf:

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

Verwandte Themen:

• Hintergrundausführung und Prozesswerkzeug
• Konfiguration
• Doctor

macOS-Gateway reagiert unbemerkt nicht mehr und setzt den Betrieb fort, wenn Sie das Dashboard verwenden

Verwenden Sie diesen Abschnitt, wenn Channels (Telegram, WhatsApp usw.) auf einem macOS-Host für jeweils mehrere Minuten bis Stunden verstummen und das Gateway offenbar genau dann zurückkehrt, wenn Sie die Control-UI öffnen, sich per SSH anmelden oder anderweitig mit dem Host interagieren. In openclaw status ist normalerweise kein offensichtliches Symptom zu sehen, da das Gateway zu dem Zeitpunkt, an dem Sie nachsehen, bereits 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-Pakete in ~/.openclaw/logs/stability/, bei denen error.code auf einen vorübergehenden Netzwerkcode wie ENETDOWN, ENETUNREACH, EHOSTUNREACH oder ECONNREFUSED gesetzt ist.
• Zeilen aus pmset -g log wie Entering Sleep state due to 'Maintenance Sleep' oder en0 driver is slow (msg: WillChangeState to 0), die zeitlich mit den Abstürzen übereinstimmen. Power Nap / Maintenance Sleep versetzt den WLAN-Treiber kurzzeitig in Zustand 0; jeder ausgehende connect()-Aufruf, der in dieses Zeitfenster fällt, kann mit ENETDOWN fehlschlagen, selbst wenn der Host ansonsten über vollständige Netzwerkkonnektivität verfügt.
• Eine Ausgabe von launchctl print, die state = not running mit mehreren kürzlich erfolgten runs und einem Exit-Code zeigt, insbesondere wenn zwischen dem Absturz und dem nächsten Start ungefähr eine Stunde statt nur weniger Sekunden liegt. macOS launchd wendet nach einer Serie von Abstürzen eine undokumentierte Schutzsperre gegen wiederholte Starts an, durch die KeepAlive=true möglicherweise nicht mehr berücksichtigt wird, bis ein externer Auslöser wie eine interaktive Anmeldung, eine Dashboard-Verbindung oder launchctl kickstart den Mechanismus wieder aktiviert.

Häufige Anzeichen:

• Ein Stabilitätspaket, dessen error.code den Wert ENETDOWN oder einen verwandten Code enthält und dessen Aufruf-Stack auf lookupAndConnect / Socket.connect in Node net verweist. OpenClaw 2026.5.26 und neuer stuft diese Fehler als harmlose vorübergehende Netzwerkfehler ein, sodass sie nicht mehr bis zum unbehandelten Handler auf oberster Ebene weitergegeben werden; wenn Sie eine ältere Version verwenden, führen Sie zuerst ein Upgrade durch.
• Lange Ruhephasen, die genau dann enden, wenn Sie sich mit der Control UI verbinden oder per SSH beim Host anmelden: Die für den Benutzer sichtbare Aktivität aktiviert die Schutzsperre für erneute Starts von launchd wieder, nicht eine Aktion des Dashboards am Gateway.
• Ein im Tagesverlauf steigender runs-Zähler ohne entsprechende Zeile received SIG*; shutting down in ~/Library/Logs/openclaw/gateway.log: Bei ordnungsgemäßen Beendigungen wird ein Signal protokolliert, bei vorübergehenden Abstürzen nicht.

Vorgehensweise:

1. Führen Sie ein Upgrade des Gateways durch, 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 die Maintenance-Sleep-Aktivität auf Mac-mini-/Desktop-Hosts, die als ständig verfügbare Server betrieben werden sollen:

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

   Dadurch wird das zugrunde liegende kurzzeitige Aussetzen des Treibers deutlich reduziert, jedoch nicht vollständig verhindert. Unabhängig von diesen Flags kann das System weiterhin einige Maintenance-Sleep-Vorgänge für TCP-Keepalive und die mDNS-Wartung durchführen.

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

   # Beispiel für eine launchd-fähige Liveness-Prüfung, geeignet für einen 5-minütigen Cron oder 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 Schutzsperre für erneute Starts extern wieder zu aktivieren; KeepAlive=true allein reicht unter macOS nach einer Absturzserie nicht aus.

Weiterführende Informationen:

• Hinweise zur macOS-Plattform
• Protokollierung
• Doctor

macOS-launchd-Supervisor-Schleife mit doppelten Gateway-/Node-LaunchAgents

Verwenden Sie diesen Abschnitt, wenn eine macOS-Installation alle paar Sekunden neu startet, die openclaw-Integritätsprüfungen zwischen verfügbar und nicht verfügbar wechseln und der Kanalversand stockt, obwohl der Dienst anscheinend ausgeführt wird.

Dies wurde bei älteren Installationen beobachtet, auf denen sowohl die LaunchAgents ai.openclaw.gateway als auch ai.openclaw.node aktiv waren und beide OPENCLAW_LAUNCHD_LABEL einschleusten. In diesem Zustand kann OpenClaw die Überwachung durch launchd erkennen, versuchen, den Neustart wieder an launchd zu übergeben, und statt eines stabilen Gateway-Prozesses in eine schnelle EADDRINUSE-/Neustartschleife geraten.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

Achten Sie auf:

• Mehr als eine Gateway-PID innerhalb der 30-sekündigen Stichprobe statt eines stabilen Prozesses.
• EADDRINUSE, another gateway instance is already listening oder wiederholte Neustart-/Übergabezeilen in gateway.log.
• Sowohl ~/Library/LaunchAgents/ai.openclaw.gateway.plist als auch ~/Library/LaunchAgents/ai.openclaw.node.plist sind gleichzeitig auf einem Host geladen, auf dem nur ein verwalteter Gateway-Dienst ausgeführt werden sollte.

Vorgehensweise:

1. Wenn auf diesem Host nur der Gateway-Dienst ausgeführt werden soll, entfernen Sie den verwalteten Node-Dienst über OpenClaw. Überspringen Sie diesen Schritt, wenn Sie den Node-Dienst aktiv für Remote-Node-Funktionen verwenden; durch seine Deinstallation werden diese Funktionen auf diesem Host beendet:

   openclaw node uninstall

2. Installieren Sie einen dauerhaften Gateway-Wrapper, der die geerbten launchd-Markierungen vor dem Start von OpenClaw entfernt. Verwenden Sie die unterstützte Option --wrapper; bearbeiten Sie nicht die generierte Datei unter ~/.openclaw/service-env/, da diese Datei bei einer Neuinstallation oder Aktualisierung des Dienstes sowie bei einer Reparatur durch Doctor neu generiert wird:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install speichert den Wrapper-Pfad dauerhaft über erzwungene Neuinstallationen, Aktualisierungen und Reparaturen durch Doctor hinweg.

3. Überprüfen Sie, ob das Gateway stabil ist und RPC bereitstellt, statt lediglich Verbindungen anzunehmen:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   Die PID-Stichprobe sollte einen stabilen Prozess statt einer wechselnden Gruppe von PIDs zeigen, und der eingehende Kanalversand sollte wieder funktionieren.

4. Entfernen Sie nach dem Upgrade auf eine Version, in der die zugrunde liegende Schleife aus zwei LaunchAgents behoben ist, die Problemumgehung und installieren Sie den normalen verwalteten Dienst neu:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

Weiterführende Informationen:

• Hinweise zur macOS-Plattform
• Doctor
• Gateway-CLI

Gateway wird bei hoher Speicherauslastung beendet

Verwenden Sie diesen Abschnitt, wenn das Gateway unter Last verschwindet, der Supervisor einen Neustart nach Art eines OOM-Ereignisses meldet oder in den Protokollen critical memory pressure bundle written erwähnt wird.

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

Achten Sie auf:

• Reason: diagnostic.memory.pressure.critical im neuesten Stabilitätspaket.
• Memory pressure: mit critical/rss_threshold, critical/heap_threshold oder critical/rss_growth.
• V8 heap:-Werte nahe der Heap-Grenze.
• Einträge unter Largest session files: wie agents/<agent>/sessions/<session>.jsonl oder sessions/<session>.jsonl.
• Linux-cgroup-Speicherzähler, wenn das Gateway in einem Container oder einem Dienst mit Speicherbegrenzung ausgeführt wird.

Häufige Anzeichen:

• critical memory pressure bundle written erscheint kurz vor dem Neustart → OpenClaw hat ein Stabilitätspaket vor dem OOM-Ereignis erfasst. Untersuchen Sie es mit openclaw gateway stability --bundle latest.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled erscheint in den Gateway-Protokollen → OpenClaw hat einen kritischen Speicherdruck erkannt, aber die Stabilitätsmomentaufnahme vor dem OOM-Ereignis ist deaktiviert.
• Largest session files: verweist auf einen sehr großen bereinigten Transkriptpfad → Reduzieren Sie den beibehaltenen Sitzungsverlauf, untersuchen Sie das Wachstum der Sitzung oder verschieben Sie alte Transkripte vor dem Neustart aus dem aktiven Speicher.
• Die belegten Bytes unter V8 heap: liegen nahe der Heap-Grenze → Reduzieren Sie den Prompt-/Sitzungsdruck und die Anzahl gleichzeitiger Aufgaben oder erhöhen Sie die Node-Heap-Grenze erst, nachdem Sie bestätigt haben, dass die Arbeitslast zu erwarten ist.
• Memory pressure: critical/rss_growth → Der Speicherverbrauch ist innerhalb eines Abtastintervalls schnell gestiegen. Prüfen Sie die neuesten Protokolle auf einen großen Import, außer Kontrolle geratene Werkzeugausgaben, wiederholte Versuche oder eine Reihe in die Warteschlange eingereihter Agent-Aufgaben.
• In den Protokollen erscheint kritischer Speicherdruck, aber es ist kein Paket vorhanden → Dies ist die Standardeinstellung. Setzen Sie diagnostics.memoryPressureSnapshot: true, um bei zukünftigen Ereignissen mit kritischem Speicherdruck ein Stabilitätspaket vor dem OOM-Ereignis zu erfassen.

Das Stabilitätspaket enthält keine Nutzdaten. Es umfasst betriebliche Speicherinformationen und bereinigte relative Dateipfade, jedoch keine Nachrichtentexte, Webhook-Inhalte, Anmeldedaten, Token, Cookies oder unverarbeiteten Sitzungs-IDs. Hängen Sie den Diagnoseexport an Fehlerberichte an, statt unverarbeitete Protokolle zu kopieren.

Weiterführende Informationen:

• Gateway-Integrität
• Diagnoseexport
• Sitzungen

Gateway hat eine ungültige Konfiguration abgelehnt

Verwenden Sie diesen Abschnitt, wenn der Gateway-Start mit Invalid config fehlschlägt oder die Hot-Reload-Protokolle melden, dass eine ungültige Änderung ü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 einem Zeitstempel versehene Datei openclaw.json.rejected.* neben der aktiven Konfiguration.
• Eine mit einem Zeitstempel versehene Datei openclaw.json.clobbered.*, wenn doctor --fix eine fehlerhafte direkte Bearbeitung repariert hat.
• OpenClaw behält für jeden Konfigurationspfad die neuesten 32 .clobbered.*-Dateien und entfernt ältere bei der Rotation.

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

Weiterführende Informationen:

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

Gateway-Probe-Warnungen

Verwenden Sie dies, wenn openclaw gateway probe etwas erreicht, aber dennoch 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 sich die Warnung auf den SSH-Fallback, mehrere Gateways, fehlende Scopes oder nicht aufgelöste Authentifizierungsreferenzen bezieht.

Häufige Meldungen:

• SSH tunnel failed to start; falling back to direct probes. → Die SSH-Einrichtung ist fehlgeschlagen, der Befehl hat jedoch weiterhin direkte konfigurierte Ziele bzw. Loopback-Ziele geprüft.
• multiple reachable gateway identities detected → Unterschiedliche Gateways haben geantwortet oder OpenClaw konnte nicht nachweisen, dass die erreichbaren Ziele dasselbe Gateway sind. Ein SSH-Tunnel, eine Proxy-URL oder eine konfigurierte Remote-URL zum selben Gateway wird als ein Gateway mit mehreren Transportwegen behandelt, selbst wenn sich die Transport-Ports unterscheiden.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → Die Verbindung wurde hergestellt, aber Detail-RPCs sind durch Scopes eingeschränkt; koppeln Sie die Geräteidentität oder verwenden Sie Anmeldedaten mit operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → Die Verbindung wurde hergestellt, aber der vollständige Satz diagnostischer RPCs ist wegen Zeitüberschreitung fehlgeschlagen oder anderweitig fehlgeschlagen. Behandeln Sie dies als erreichbares Gateway mit eingeschränkter Diagnose; vergleichen Sie connect.ok und connect.rpcOk in der Ausgabe von --json.
• Capability: pairing-pending oder gateway closed (1008): pairing required → Das Gateway hat geantwortet, aber dieser Client muss noch gekoppelt bzw. genehmigt werden, bevor der normale Operatorzugriff möglich ist.
• Nicht aufgelöster SecretRef-Warntext zu gateway.auth.* / gateway.remote.* → Für das fehlgeschlagene Ziel war in diesem Befehlspfad kein Authentifizierungsmaterial verfügbar.

Verwandte Themen:

• Gateway
• Mehrere Gateways auf demselben Host
• Remotezugriff

Kanal verbunden, aber Nachrichten werden nicht übertragen

Wenn der Kanalstatus „verbunden“ lautet, aber keine Nachrichten übertragen werden, konzentrieren Sie sich auf Richtlinien, Berechtigungen und kanalspezifische Zustellungsregeln.

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

Achten Sie auf:

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

Häufige Meldungen:

• mention required → Die Nachricht wurde aufgrund der Richtlinie für Gruppenerwähnungen ignoriert.
• pairing / Ablaufspuren einer ausstehenden Genehmigung → Der Absender ist nicht genehmigt.
• missing_scope, not_in_channel, Forbidden, 401/403 → Problem mit der Authentifizierung oder den Berechtigungen des Kanals.

Verwandte Themen:

• Fehlerbehebung bei Kanälen
• Discord
• Telegram
• WhatsApp

Cron- und Heartbeat-Zustellung

Wenn Cron oder Heartbeat nicht ausgeführt oder nicht zugestellt wurde, prüfen Sie zuerst den Scheduler-Status und anschließend das Zustellungsziel.

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

Achten Sie auf:

• Cron ist aktiviert und der nächste Aktivierungszeitpunkt ist vorhanden.
• Status im Verlauf der Auftragsausführungen (ok, skipped, error).
• Gründe für das Überspringen des Heartbeat (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

Verwandte Themen:

• Heartbeat
• Geplante Aufgaben
• Geplante Aufgaben: Fehlerbehebung

Node gekoppelt, Tool schlägt fehl

Wenn ein Node gekoppelt ist, Tools jedoch fehlschlagen, grenzen Sie den Vordergrund-, Berechtigungs- und Genehmigungsstatus ein.

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

Achten Sie auf:

• Der Node ist mit den erwarteten Funktionen online.
• Betriebssystemberechtigungen für Kamera, Mikrofon, Standort und Bildschirm.
• Status der Ausführungsgenehmigungen und der Zulassungsliste.

Häufige Meldungen:

• NODE_BACKGROUND_UNAVAILABLE → Die Node-App muss sich im Vordergrund befinden.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → Eine Betriebssystemberechtigung fehlt.
• SYSTEM_RUN_DENIED: approval required → Die Ausführungsgenehmigung steht noch aus.
• SYSTEM_RUN_DENIED: allowlist miss → Der Befehl wurde durch die Zulassungsliste blockiert.

Verwandte Themen:

• Ausführungsgenehmigungen
• Fehlerbehebung bei Nodes
• Nodes

Browser-Tool schlägt fehl

Verwenden Sie dies, wenn Aktionen des Browser-Tools fehlschlagen, obwohl das Gateway selbst fehlerfrei funktioniert.

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

Achten Sie auf:

• Ob plugins.allow festgelegt ist und browser enthält.
• Einen gültigen Pfad zur ausführbaren Browserdatei.
• Erreichbarkeit des CDP-Profils.
• Lokale Verfügbarkeit von Chrome für die Profile existing-session / user.

Verwandte Themen:

• Browser (von OpenClaw verwaltet)
• Fehlerbehebung für Browser

Wenn nach einem Upgrade plötzlich etwas nicht mehr funktioniert

Die meisten Fehler nach einem Upgrade werden durch abweichende Konfigurationen oder nun durchgesetzte strengere Standardwerte verursacht.

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 Laufzeit nach diesen Prüfungen weiterhin voneinander abweichen, installieren Sie die Dienstmetadaten aus demselben Profil-/Statusverzeichnis neu:

openclaw gateway install --forceopenclaw gateway restart

Verwandte Themen:

• Authentifizierung
• Hintergrundausführung und Prozess-Tool
• Node-Kopplung

Verwandte Themen

• Doctor
• FAQ
• Gateway-Betriebshandbuch