Fehlerbehebung

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

Befehlsabfolge

Führen Sie die Befehle in dieser Reihenfolge aus:

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

Signale für einen fehlerfreien Zustand:

• openclaw gateway status zeigt Runtime: running, Connectivity probe: ok und eine Capability: ...-Zeile.
• openclaw doctor meldet keine blockierenden Konfigurations- oder Dienstprobleme.
• openclaw channels status --probe zeigt den aktuellen Transportstatus pro Konto und, sofern unterstützt, works oder audit ok.

Nach einem Update

Verwenden Sie dies, wenn ein Update abgeschlossen ist, der Gateway jedoch nicht verfügbar ist, keine Kanäle angezeigt werden oder Modellaufrufe mit 401-Fehlern fehlschlagen.

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. Ausstehende oder fehlgeschlagene Übergaben enthalten den als Nächstes auszuführenden Befehl.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix unter „Kanäle“: Die Kanalkonfiguration ist noch vorhanden, aber die Plugin-Registrierung ist fehlgeschlagen, bevor der Kanal geladen werden konnte.
• Provider-401-Fehler nach erneuter Authentifizierung: openclaw doctor --fix sucht nach veralteten agentenspezifischen OAuth-Authentifizierungsschatten und entfernt alte Kopien, damit alle Agenten das aktuelle gemeinsame Profil auflösen.

Uneinheitliche Installationen und Schutz vor neuerer Konfiguration

Verwenden Sie dies, wenn ein Gateway-Dienst nach einem Update unerwartet beendet wird oder die Protokolle zeigen, dass eine openclaw-Binärdatei älter als die Version ist, die zuletzt openclaw.json geschrieben hat.

OpenClaw kennzeichnet Konfigurationsschreibvorgänge mit meta.lastTouchedVersion. Schreibgeschützte Befehle können eine von einer neueren OpenClaw-Version geschriebene Konfiguration prüfen, Prozess- und Dienständerungen werden von einer älteren Binärdatei jedoch verweigert. Blockierte Aktionen: Starten, Beenden, Neustarten oder Deinstallieren des Gateway-Dienstes, erzwungene Neuinstallation des Dienstes, Starten des Gateways im Dienstmodus und gateway --force-Portbereinigung.

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

openclaw gateway install --forceopenclaw gateway restart

Protokollabweichung nach einem Rollback

Verwenden Sie dies, wenn die Protokolle nach einem Downgrade oder Rollback weiterhin protocol mismatch ausgeben. Ein älterer Gateway wird ausgeführt, aber ein neuerer lokaler Clientprozess versucht weiterhin, mit einem Protokollbereich, den der ältere Gateway nicht unterstützt, erneut eine Verbindung herzustellen.

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.
• Ein Clientprozess, dessen Befehlszeile auf die neuere OpenClaw-Installation oder den Wrapper verweist, von dem das Rollback durchgeführt wurde.

Behebung:

1. Beenden Sie den von gateway status --deep angezeigten veralteten OpenClaw-Clientprozess oder starten Sie ihn neu.
2. Starten Sie Apps oder Wrapper neu, die OpenClaw einbetten: lokale Dashboards, Editoren, App-Server-Hilfsprogramme oder langlebige openclaw logs --follow-Shells.
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. Protokollversionssprünge schützen den Übertragungsvertrag; die Wiederherstellung nach einem Rollback erfordert die Bereinigung von Prozessen und Versionen.

Skill-Symlink wegen Pfadüberschreitung übersprungen

Verwenden Sie dies, wenn die Protokolle Folgendes enthalten:

Übersprungener Skill-Pfad außerhalb seines konfigurierten Stammverzeichnisses: ... reason=symlink-escape

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

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 der Skills-Watcher die Daten aktualisiert. Starten Sie den Gateway neu, wenn der laufende Prozess bereits 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 das Anwenden in Skill Workshop auch über diese vertrauenswürdigen, per Symlink eingebundenen Workspace-Skill-Pfade schreiben soll, aktivieren Sie skills.workshop.allowSymlinkTargetWrites. Lassen Sie diese Option für schreibgeschützte gemeinsame Skill-Stammverzeichnisse deaktiviert.

Verwandte Themen:

• Skills-Konfiguration
• Konfigurationsbeispiele

Für Anthropic 429 ist bei langem Kontext zusätzliche Nutzung erforderlich

Verwenden Sie dies, wenn Protokolle oder Fehler HTTP 429: rate_limit_error: Extra usage is required for long context requests enthalten.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Achten Sie auf Folgendes:

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

Behebungsoptionen:

Verwandte Themen:

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

Blockierte 403-Antworten von Upstream-Diensten

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

Gehen Sie nicht davon aus, dass dies immer ein Konfigurationsproblem von OpenClaw 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 schlagen auf dieselbe Weise fehl.
• HTML oder generischer Sicherheitstext anstelle eines normalen Provider-API-Fehlers.
• Providerseitige Sicherheitsereignisse zum selben Anfragezeitpunkt.
• Eine sehr kleine direkte curl-Prüfung ist erfolgreich, während normale SDK-förmige Anfragen fehlschlagen.

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

Verwandte Themen:

• OpenAI-kompatible Endpunkte
• Provider-Konfiguration
• Protokolle

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

Verwenden Sie dies, wenn:

• curl ... /v1/models funktioniert.
• Sehr kleine direkte /v1/chat/completions-Aufrufe funktionieren.
• OpenClaw-Modellläufe schlagen nur bei normalen Agentenzügen fehl.

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, OpenClaw-Läufe schlagen jedoch nur bei größeren Prompts fehl.
• model_not_found- oder 404-Fehler, obwohl direktes /v1/chat/completions mit derselben unveränderten Modell-ID funktioniert.
• Backend-Fehler, laut denen messages[].content eine Zeichenfolge erwartet.
• Zeitweilige incomplete turn detected ... stopReason=stop payloads=0-Warnungen bei einem OpenAI-kompatiblen lokalen 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 Kanäle aktiv sind, aber keine Antwort erfolgt, prüfen Sie Routing und Richtlinien, bevor Sie irgendetwas 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ähnungssperre in Gruppen (requireMention, mentionPatterns).
• Nicht übereinstimmende Kanal-/Gruppen-Zulassungslisten.

Häufige Meldungen:

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

Verwandte Themen:

• Fehlerbehebung für Kanäle
• Gruppen
• Pairing

Konnektivität der Dashboard-Steuerungsoberfläche

Wenn das Dashboard bzw. die Steuerungsoberfläche keine Verbindung herstellt, prüfen Sie URL, Authentifizierungsmodus und 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 einer Aktualisierung 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 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 weiterläuft, 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 verbindenden Client und überprüfen Sie ihn:

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

• Sitzungen mit Token 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-Scopes anfordern, über die die Aufrufersitzung bereits verfügt.

Verwandte Themen:

• Konfiguration (Gateway-Authentifizierungsmodi)
• Steuerungsoberfläche
• Geräte
• Remotezugriff
• Authentifizierung über vertrauenswürdigen Proxy

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 Dienste auf Systemebene prüfen

Achten Sie auf:

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

Verwandte Themen:

• Hintergrundausführung und Prozesswerkzeug
• Konfiguration
• Doctor

Das macOS-Gateway reagiert ohne Meldung nicht mehr und setzt den Betrieb fort, sobald Sie das Dashboard verwenden

Verwenden Sie dies, wenn Kanäle (Telegram, WhatsApp usw.) auf einem macOS-Host minuten- bis stundenlang verstummen und der Gateway scheinbar genau dann wieder aktiv wird, 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 der Gateway bereits wieder aktiv ist, sobald Sie nachsehen.

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

• Ein oder mehrere *-uncaught_exception.json-Bundles in ~/.openclaw/logs/stability/, bei denen error.code auf einen vorübergehenden 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 Abstürzen ü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 wenn der Host ansonsten über vollständige Netzwerkkonnektivität verfügt.
• launchctl print-Ausgabe, die state = not running mit mehreren kürzlichen runs und einem Exit-Code zeigt, insbesondere wenn zwischen dem Absturz und dem nächsten Start etwa eine Stunde statt nur wenige Sekunden liegt. macOS launchd wendet nach einer Serie von Abstürzen eine undokumentierte Schutzsperre für Neustarts 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 die Sperre wieder aktiviert.

Häufige Merkmale:

• Ein Stabilitäts-Bundle, dessen error.code den Wert ENETDOWN oder einen verwandten Code enthält und dessen Aufrufstapel auf Node net lookupAndConnect / Socket.connect verweist. OpenClaw 2026.5.26 und neuere Versionen klassifizieren diese als harmlose vorübergehende Netzwerkfehler, sodass sie nicht mehr bis zum obersten Handler für nicht abgefangene Fehler weitergegeben werden. Wenn Sie eine ältere Version verwenden, führen Sie zuerst ein Upgrade durch.
• Lange Ruhephasen, die in dem Moment enden, in dem Sie eine Verbindung zur Control UI herstellen oder sich per SSH am Host anmelden: Die für Benutzer sichtbare Aktivität reaktiviert die Neustartsperre von launchd, nicht eine Aktion des Dashboards am Gateway.
• Der Zähler runs steigt im Laufe des Tages, ohne dass eine entsprechende received SIG*; shutting down-Zeile in ~/Library/Logs/openclaw/gateway.log vorhanden ist: Bei ordnungsgemäßem Herunterfahren 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 Aktivität des Wartungsruhezustands auf Mac-mini-/Desktop-Hosts, die als dauerhaft verfügbare Server betrieben werden sollen:

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

   Dadurch wird die zugrunde liegende Treiberunterbrechung deutlich reduziert, jedoch nicht vollständig beseitigt. Unabhängig von diesen Flags kann das System weiterhin einige Wartungsruhezustände für TCP-Keepalive und die mDNS-Wartung ausführen.

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

   # Beispiel für eine launchd-fähige Verfügbarkeitsprü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 Neustartsperre extern zu reaktivieren. KeepAlive=true allein reicht unter macOS nach einer Absturzserie nicht aus.

Verwandte Themen:

• Hinweise zur macOS-Plattform
• Protokollierung
• Doctor

macOS-launchd-Supervisorschleife mit doppelten Gateway-/Node-LaunchAgents

Verwenden Sie dies, wenn eine macOS-Installation alle paar Sekunden neu startet, openclaw Integritätsprüfungen zwischen „fehlerfrei“ und „nicht verfügbar“ wechseln und die Kanalauslieferung stockt, obwohl der Dienst scheinbar ausgeführt wird.

Dies wurde bei älteren Installationen beobachtet, bei denen sowohl ai.openclaw.gateway als auch ai.openclaw.node als LaunchAgents aktiv waren und jeweils 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 Folgendes:

• Mehr als eine Gateway-PID während 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 persistenten Gateway-Wrapper, der die geerbten launchd- Markierungen löscht, bevor OpenClaw gestartet wird. Verwenden Sie die unterstützte Option --wrapper; bearbeiten Sie nicht die generierte Datei unter ~/.openclaw/service-env/, da diese Datei bei der Neuinstallation des Dienstes, bei Updates und bei Reparaturen 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 behält den Wrapper-Pfad über erzwungene Neuinstallationen, Updates und Reparaturen durch Doctor hinweg bei.

3. Überprüfen Sie, ob der Gateway stabil ist und RPC bereitstellt, statt lediglich auf Verbindungen zu warten:

   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 einzelnen stabilen Prozess statt einer wechselnden Gruppe von PIDs zeigen, und die eingehende Kanalauslieferung sollte fortgesetzt werden.

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

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

Verwandte Themen:

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

Gateway wird bei hoher Speicherauslastung beendet

Verwenden Sie dies, wenn der Gateway unter Last verschwindet, der Supervisor einen Neustart nach Art eines OOM meldet oder die Protokolle critical memory pressure bundle written erwähnen.

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

Achten Sie auf Folgendes:

• 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 der Gateway in einem Container oder einem Dienst mit Speicherbegrenzung ausgeführt wird.

Häufige Merkmale:

• critical memory pressure bundle written erscheint kurz vor dem Neustart → OpenClaw hat vor dem OOM ein Stabilitäts-Bundle erfasst. Untersuchen Sie es mit openclaw gateway stability --bundle latest.
• memory pressure: level=critical erscheint in den Gateway-Protokollen → OpenClaw hat kritischen Speicherdruck erkannt und die verfügbaren prozessinternen Speicherdaten aufgezeichnet.
• Largest session files: verweist auf einen sehr großen, redigierten Transkriptpfad → Reduzieren Sie den gespeicherten Sitzungsverlauf, untersuchen Sie das Sitzungswachstum oder verschieben Sie alte Transkripte aus dem aktiven Speicher, bevor Sie neu starten.
• Die von V8 heap: verwendeten Bytes liegen nahe am Heap-Limit → Reduzieren Sie zuerst den Prompt-/Sitzungsdruck oder die Anzahl gleichzeitiger Aufgaben. Prüfen Sie bei einem verwalteten Dienst Gateway heap: in openclaw gateway status. Wenn dort not set angegeben ist, generieren Sie alte Dienstmetadaten mit openclaw gateway install --force neu. NODE_OPTIONS aus der Shell-Umgebung wird absichtlich ignoriert. Verwenden Sie eine explizite Heap-Überschreibung auf Supervisor-Ebene erst, nachdem Sie die dauerhafte Arbeitslast bestätigt und ausreichend Spielraum für nativen Speicher eingeplant haben.
• Memory pressure: critical/rss_growth → Der Speicher ist innerhalb eines einzelnen Abtastintervalls schnell angewachsen. Prüfen Sie die neuesten Protokolle auf einen großen Import, unkontrollierte Tool-Ausgaben, wiederholte Wiederholungsversuche oder eine Reihe in die Warteschlange gestellter Agentenaufgaben.
• In den Protokollen erscheint kritischer Speicherdruck, aber es ist kein Bundle vorhanden → Erfassen Sie nach dem Ereignis openclaw gateway diagnostics export, um die verfügbaren Betriebsnachweise zu sichern.

Das Stabilitäts-Bundle enthält keine Nutzdaten. Es enthält betriebliche Speichernachweise und redigierte 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.

Verwandte Themen:

• Gateway-Integrität
• Diagnoseexport
• Sitzungen

Gateway hat eine ungültige Konfiguration abgelehnt

Verwenden Sie dies, wenn der Start des Gateways mit Invalid config fehlschlägt oder die Protokolle des Hot Reload angeben, dass eine ungültige Änderung übersprungen wurde.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Achten Sie auf Folgendes:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• Eine mit einem Zeitstempel versehene openclaw.json.rejected.*-Datei neben der aktiven Konfiguration.
• Eine mit einem Zeitstempel versehene openclaw.json.clobbered.*-Datei, wenn doctor --fix eine fehlerhafte direkte Bearbeitung repariert hat.
• OpenClaw behält für jeden Konfigurationspfad die neuesten 32 .clobbered.*-Dateien bei und rotiert ältere Dateien.

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

Verwandte Themen:

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

Warnungen bei Gateway-Prüfungen

Verwenden Sie dies, wenn openclaw gateway probe etwas erreicht, aber weiterhin 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 Anzeichen:

• SSH tunnel failed to start; falling back to direct probes. → Die SSH-Einrichtung ist fehlgeschlagen, der Befehl hat jedoch weiterhin direkte konfigurierte bzw. Loopback-Ziele versucht.
• multiple reachable gateway identities detected → Verschiedene Gateways haben geantwortet oder OpenClaw konnte nicht nachweisen, dass es sich bei den erreichbaren Zielen um dasselbe Gateway handelt. 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 der 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 → Die Verbindung wurde hergestellt, aber für den vollständigen Satz diagnostischer RPCs trat eine Zeitüberschreitung oder ein Fehler auf. Behandeln Sie dies als erreichbares Gateway mit eingeschränkter Diagnosefunktion; 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 weiterhin gekoppelt bzw. genehmigt werden, bevor ein normaler Bedienerzugriff möglich ist.
• Nicht aufgelöster gateway.auth.*- / gateway.remote.*-SecretRef-Warntext → Das Authentifizierungsmaterial war in diesem Befehlspfad für das fehlgeschlagene Ziel nicht verfügbar.

Verwandte Themen:

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

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

Häufige Anzeichen:

• mention required → Die Nachricht wurde aufgrund der Richtlinie für Gruppenerwähnungen ignoriert.
• pairing / Spuren ausstehender Genehmigungen → Der Absender ist nicht genehmigt.
• missing_scope, not_in_channel, Forbidden, 401/403 → Problem mit der Kanalauthentifizierung oder den Kanalberechtigungen.

Verwandte Themen:

• Fehlerbehebung für Kanäle
• Discord
• Telegram
• WhatsApp

Cron- und Heartbeat-Zustellung

Wenn Cron oder Heartbeat nicht ausgeführt oder nicht zugestellt wurde, überprü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 Heartbeats (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file).

Verwandte Themen:

• Heartbeat
• Geplante Aufgaben
• Geplante Aufgaben: Fehlerbehebung

Node gekoppelt, Tool schlägt fehl

Wenn eine Node gekoppelt ist, aber Tools 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:

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

Häufige Anzeichen:

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

Verwandte Themen:

• Ausführungsgenehmigungen
• Fehlerbehebung für 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.
• Gültiger Pfad zur ausführbaren Browserdatei.
• Erreichbarkeit des CDP-Profils.
• Lokale Chrome-Verfügbarkeit für existing-session- / user-Profile.

Verwandte Themen:

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

Wenn nach einem Upgrade plötzlich etwas nicht mehr funktioniert

Die meisten Probleme nach einem Upgrade entstehen durch Konfigurationsabweichungen oder dadurch, dass strengere Standardwerte nun 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 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 Prozesswerkzeug
• Node-Kopplung

Verwandte Themen

• Doctor
• Häufig gestellte Fragen
• Gateway-Betriebshandbuch