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 Capability: ...-Zeile an.
• 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 an.

Nach einer Aktualisierung

Verwenden Sie dies, wenn eine Aktualisierung 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 nächsten 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 Schattenkopien der OAuth-Authentifizierung und entfernt alte Kopien, damit alle Agenten das aktuelle gemeinsame Profil auflösen.

Getrennte Installationen und Schutz vor neuerer Konfiguration

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

OpenClaw versieht 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 jedoch bei Ausführung über eine ältere Binärdatei verweigert. Blockierte Aktionen: Starten/Stoppen/Neustarten/Deinstallieren des Gateway-Dienstes, erzwungene Neuinstallation des Dienstes, Gateway-Start 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 einer Herabstufung oder einem Rollback weiterhin protocol mismatch ausgeben. Ein älterer Gateway wird ausgeführt, aber ein neuerer lokaler Clientprozess versucht weiterhin, sich mit einem Protokollbereich zu verbinden, 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.
• Ein Clientprozess, dessen Befehlszeile auf die neuere OpenClaw-Installation oder den Wrapper verweist, von dem Sie das Rollback durchgeführt haben.

Behebung:

1. Stoppen 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 openclaw logs --follow-Shells.
3. Führen Sie openclaw gateway status --deep oder openclaw doctor --deep erneut aus und bestätigen Sie, 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 Übertragungsvertrag; bei der Wiederherstellung nach einem Rollback müssen Prozesse und Versionen bereinigt werden.

Skill-Symlink wegen Pfadüberschreitung übersprungen

Verwenden Sie dies, wenn die Protokolle Folgendes enthalten:

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

Jedes Skill-Stammverzeichnis stellt eine Begrenzungsgrenze dar. 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 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 aktualisiert wurde. 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 vollständigen synchronisierten Projektordner. Beschränken Sie allowSymlinkTargets auf das tatsächliche Skill-Stammverzeichnis, das vertrauenswürdige SKILL.md-Verzeichnisse enthält.

Wenn die Anwendung von Skill Workshop auch über diese vertrauenswürdigen, per Symlink eingebundenen Skill-Pfade im Arbeitsbereich 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 zusätzliche Nutzung für langen Kontext 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 GA-fähiges Claude-4.x-Modell mit 1M Kontext (Opus 4.6/4.7/4.8, Sonnet 4.6), oder die Modellkonfiguration enthält weiterhin das veraltete params.context1m: true.
• Die aktuellen Anthropic-Anmeldedaten sind nicht für die Nutzung eines langen Kontexts 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 wird mir HTTP 429 von Anthropic angezeigt?

Blockierte Upstream-Antworten mit 403

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

Gehen Sie nicht davon aus, dass es sich dabei immer um ein OpenClaw-Konfigurationsproblem handelt. Die Antwort kann von einer vorgeschalteten Sicherheitsebene stammen, etwa von 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 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 minimale direkte curl-Prüfung ist erfolgreich, während normale SDK-förmige Anfragen fehlschlagen.

Beheben Sie zunächst die providerseitige Filterung, wenn die Hinweise 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.
• Minimale direkte /v1/chat/completions-Aufrufe funktionieren.
• OpenClaw-Modellläufe schlagen nur bei normalen Agenteninteraktionen 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:

• Direkte minimale 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 reinen 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-Token oder vollständigen Prompts der Agentenlaufzeit auftreten.

Verwandte Themen:

• Konfiguration
• Lokale Modelle
• OpenAI-kompatible Endpunkte

Keine Antworten

Wenn die Kanäle aktiv sind, aber nichts antwortet, prüfen Sie Routing und Richtlinien, bevor Sie Verbindungen neu 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 Absender von Direktnachrichten.
• Erwähnungsbeschränkung für Gruppen (requireMention, mentionPatterns).
• Abweichungen bei 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 die Dashboard-/Steuerungsoberfläche keine Verbindung herstellt, überprü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 einem Update keine Verbindung zu 127.0.0.1:18789 herstellen kann, stellen Sie zunächst 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 liegt wahrscheinlich am Browser-Cache, einem alten Deep Link oder einem veralteten 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 verbindenden Client und überprüfen Sie ihn:

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

• Sitzungen mit Token eines gekoppelten Geräts 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 aufrufende Sitzung bereits verfügt.

Verwandte Themen:

• Konfiguration (Gateway-Authentifizierungsmodi)
• Steuerungsoberfläche
• Geräte
• Remote-Zugriff
• Authentifizierung über vertrauenswürdige Proxys

Gateway-Dienst wird nicht ausgeführt

Verwenden Sie diesen Abschnitt, 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 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

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

Verwenden Sie dies, wenn Kanäle (Telegram, WhatsApp usw.) auf einem macOS-Host immer wieder für Minuten bis Stunden verstummen und der Gateway anscheinend genau dann wieder verfügbar ist, 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 erkennen, da der Gateway bereits wieder aktiv ist, wenn 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ü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 Absturzserie eine undokumentierte Schutzsperre gegen erneutes Starten 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 erneut aktiviert.

Häufige Merkmale:

• Ein Stabilitäts-Bundle, dessen error.code den Wert ENETDOWN oder einen verwandten Code aufweist und dessen Aufrufstack auf Node net lookupAndConnect / Socket.connect verweist. OpenClaw 2026.5.26 und neuere Versionen klassifizieren diese als unbedenkliche vorübergehende Netzwerkfehler, sodass sie nicht mehr an den 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 sofort enden, sobald Sie eine Verbindung zur Control UI herstellen oder sich per SSH am Host anmelden: Die für den Benutzer sichtbare Aktivität aktiviert die Schutzsperre von launchd gegen erneutes Starten, nicht etwa eine Aktion des Dashboards am Gateway.
• Die Anzahl von runs steigt im Tagesverlauf, ohne dass eine entsprechende received SIG*; shutting down-Zeile in ~/Library/Logs/openclaw/gateway.log erscheint: 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 ständig verfügbare Server dienen sollen:

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

   Dies reduziert die zugrunde liegende Treiberinstabilität erheblich, beseitigt sie jedoch nicht vollständig. Unabhängig von diesen Flags kann das System weiterhin einige Wartungsruhezustände für TCP-Keepalive und die Pflege von mDNS ausführen.

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

   # Beispiel für eine launchd-kompatible 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 Schutzsperre gegen erneutes Starten extern wieder zu aktivieren; KeepAlive=true allein reicht unter macOS nach einer Absturzserie nicht aus.

Verwandte Themen:

• macOS-Plattformhinweise
• Protokollierung
• Doctor

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

Verwenden Sie dies, wenn eine macOS-Installation alle paar Sekunden neu startet, openclaw-Integritätsprüfungen zwischen verfügbar und nicht verfügbar wechseln und die Kanalzustellung ins Stocken gerät, obwohl der Dienst anscheinend ausgeführt wird.

Dies wurde bei älteren Installationen beobachtet, bei denen sowohl der LaunchAgent ai.openclaw.gateway als auch ai.openclaw.node aktiv waren und beide OPENCLAW_LAUNCHD_LABEL einfügten. 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 dauerhaften Gateway-Wrapper, der die geerbten launchd-Markierungen entfernt, bevor OpenClaw gestartet wird. Verwenden Sie die unterstützte Option --wrapper; bearbeiten Sie nicht die generierte Datei unter ~/.openclaw/service-env/, da sie 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 behält den Wrapper-Pfad über erzwungene Neuinstallationen, Aktualisierungen 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 stabilen Prozess statt einer wechselnden Gruppe von PIDs zeigen, und die Zustellung eingehender Kanalnachrichten sollte fortgesetzt werden.

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

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

Verwandte Themen:

• macOS-Plattformhinweise
• Doctor
• Gateway-CLI

Gateway wird bei hoher Speicherauslastung beendet

Verwenden Sie dies, wenn der Gateway unter Last verschwindet, der Supervisor einen OOM-ähnlichen Neustart meldet oder 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 ein Stabilitäts-Bundle vor dem OOM 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 Speicherinformationen aufgezeichnet.
• Largest session files: verweist auf einen sehr großen redigierten Transkriptpfad → Reduzieren Sie den beibehaltenen Sitzungsverlauf, untersuchen Sie das Sitzungswachstum oder verschieben Sie alte Transkripte vor dem Neustart aus dem aktiven Speicher.
• Die verwendeten Bytes von V8 heap: liegen nahe am Heap-Limit → Reduzieren Sie zuerst die Prompt-/Sitzungsbelastung oder die Anzahl gleichzeitig ausgeführter Arbeiten. Prüfen Sie bei einem verwalteten Dienst Gateway heap: in openclaw gateway status; wenn dort not set steht, 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 genügend Spielraum für nativen Speicher eingeplant haben.
• Memory pressure: critical/rss_growth → Der Speicher ist innerhalb eines Abtastintervalls schnell angewachsen. Prüfen Sie die neuesten Protokolle auf einen großen Import, unkontrollierte Tool-Ausgaben, wiederholte Versuche oder eine Gruppe in die Warteschlange gestellter Agent-Arbeiten.
• Kritischer Speicherdruck erscheint in den Protokollen, aber es ist kein Bundle vorhanden → Erfassen Sie nach dem Ereignis openclaw gateway diagnostics export, um die verfügbaren Betriebsnachweise zu erhalten.

Das Stabilitäts-Bundle enthält keine Nutzdaten. Es umfasst betriebliche Speicherinformationen 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 zum Hot Reload melden, 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, falls doctor --fix eine fehlerhafte direkte Bearbeitung repariert hat.
• OpenClaw behält für jeden Konfigurationspfad die neuesten 32 .clobbered.*-Dateien 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 Signaturen:

• SSH tunnel failed to start; falling back to direct probes. → Die SSH-Einrichtung schlug fehl, der Befehl versuchte jedoch weiterhin, die direkt konfigurierten bzw. Loopback-Ziele zu erreichen.
• 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, auch wenn sich die Transportports unterscheiden.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → Die Verbindung wurde hergestellt, der Detail-RPC ist jedoch durch den Scope 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 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 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 vor dem regulären Operatorzugriff noch gekoppelt/genehmigt werden.
• 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
• 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 Zustellregeln.

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

• mention required → Die Nachricht wurde aufgrund der Richtlinie für Gruppenerwähnungen ignoriert.
• pairing / Spuren 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 für Kanäle
• Discord
• Telegram
• WhatsApp

Cron- und Heartbeat-Zustellung

Wenn Cron oder Heartbeat nicht ausgeführt oder nicht zugestellt wurde, prüfen Sie zuerst den Schedulerstatus 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 die nächste Aktivierung 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).

Verwandte Themen:

• 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 ist online und verfügt über die erwarteten Funktionen.
• Betriebssystemberechtigungen für Kamera/Mikrofon/Standort/Bildschirm.
• Ausführungsgenehmigungen und Status der Zulassungsliste.

Häufige Signaturen:

• NODE_BACKGROUND_UNAVAILABLE → Die Node-App muss sich im Vordergrund befinden.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → Fehlende Betriebssystemberechtigung.
• SYSTEM_RUN_DENIED: approval required → 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 gesetzt ist und browser enthält.
• Gültiger Pfad zur ausführbaren Browserdatei.
• Erreichbarkeit des CDP-Profils.
• Lokale Verfügbarkeit von Chrome 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 Abweichungen in der Konfiguration oder durch strengere Standardwerte, die 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 den 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
• Häufig gestellte Fragen
• Gateway-Betriebshandbuch