OpenClaw Doctor: Probleme systematisch diagnostizieren

Wenn OpenClaw keine Nachrichten mehr verarbeitet, Modellaufrufe mit 401 beantwortet oder der Gateway nach einem Update nicht startet, ist ein Neustart noch keine Diagnose. Sinnvoller ist eine feste Reihenfolge: Version und Gesamtzustand erfassen, Gateway prüfen, den Fehler in den Logs reproduzieren, Doctor ausführen und erst danach einzelne Kanäle testen.

Diese Reihenfolge verhindert, dass du am sichtbaren Symptom arbeitest, während die Ursache eine Ebene tiefer liegt. Ein stiller Messenger kann am Transport hängen – oder an einem gestoppten Gateway, einer beschädigten Plugin-Registrierung oder einem veralteten Anmeldeprofil.

Für die Einordnung der zentralen Laufzeit hilft der Guide zum OpenClaw-Gateway und seiner Konfiguration. Wenn der Fehler erst nach einem Versionswechsel auftaucht, ergänzt der Beitrag zu Backups und sicheren OpenClaw-Updates den Diagnosepfad.

Den Fehler in fünf Schritten eingrenzen

Halte zuerst die tatsächlich ausgeführte Version fest und beginne dann mit dieser Diagnoseleiter:

openclaw --version
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

openclaw status liefert den Überblick. Danach zeigt openclaw gateway status, ob die zentrale Laufzeit erreichbar ist. Die aktuelle Troubleshooting-Referenz nennt Runtime: running, Connectivity probe: ok und eine Capability: ...-Zeile als gesunde Signale. Der genaue Wortlaut kann sich zwischen Versionen und Installationsarten ändern; entscheidend sind eine laufende Runtime und eine erfolgreiche Verbindungsprobe. Fehlen diese Hinweise, untersuche zunächst den Gateway und ändere noch nicht die Konfiguration eines einzelnen Kanals.

Mit openclaw logs --follow beobachtest du anschließend einen neuen Verbindungs- oder Nachrichtenversuch. Der zeitliche Zusammenhang zählt: Eine Meldung, die exakt beim Test erscheint, ist meist aussagekräftiger als eine ältere Warnung ohne Bezug zum aktuellen Ausfall.

Danach bündelt openclaw doctor bekannte Probleme in Konfiguration, Diensten und lokalem Zustand. openclaw channels status --probe prüft Accounts und Transporte live, soweit der jeweilige Kanal das unterstützt. Meldungen wie works oder audit ok helfen dabei, einen grundsätzlich funktionierenden Gateway von einem isolierten Kanalfehler zu unterscheiden.

Doctor ohne Reparatur starten

Starte Doctor zunächst ohne Reparaturoption:

openclaw doctor

Doctor prüft unter anderem Gateway, Kanäle, Plugins, Skills, Modell-Routing, lokalen Zustand und notwendige Konfigurationsmigrationen. Der normale Aufruf liefert lesbare Befunde und kann durch Rückfragen führen.

Änderungen erlaubt diese Variante:

openclaw doctor --fix

--fix wendet unterstützte Reparaturen an und kann bei einzelnen Prüfungen Rückfragen stellen. Für einen promptfreien Lauf gibt es eine enger begrenzte Variante:

openclaw doctor --fix --non-interactive

Sie beschränkt sich auf sichere Migrationen und nicht-servicebezogene Reparaturen. Installationen oder Änderungen am Gateway-Dienst benötigen weiterhin eine ausdrückliche Bestätigung oder einen passenden Gateway-Befehl. Für mich ist die Grenze klar: --fix gehört auf produktiven Systemen erst hinter einen gesicherten Befund. Halte mindestens Version, Statusausgabe und die Logmeldung des reproduzierten Fehlers fest und sichere deine Konfiguration, bevor du Zustand veränderst.

Für automatisierte Prüfungen gibt es außerdem:

openclaw doctor --lint
openclaw doctor --lint --json

Die aktuelle Doctor-CLI dokumentiert --lint als Nur-Lese-Modus für CI, Preflight-Prüfungen und Review-Gates. --json liefert in Verbindung mit --lint maschinenlesbare Findings. Ein nacktes openclaw doctor --json ist dagegen kein allgemeiner JSON-Modus; die Option ist an unterstützte Doctor-Posturen gebunden. Bei älteren OpenClaw-Versionen solltest du vor dem Einsatz die lokale Hilfe mit openclaw doctor --help prüfen.

Ausfälle nach einem Update untersuchen

Beginnt die Störung unmittelbar nach einem Update, erweitere zunächst die Nur-Lese-Diagnose:

openclaw status --all
openclaw update status --json
openclaw gateway status --deep

Die ausführliche Statusansicht kann auf einen ausstehenden oder fehlgeschlagenen Update restart hinweisen. openclaw update status --json liefert den Update-Zustand maschinenlesbar, während openclaw gateway status --deep zusätzlich nach weiteren Gateway-Installationen und Versionskonflikten sucht.

Wenn das Kernpaket bereits aktualisiert wurde, aber Doctor-Reparatur, Plugin-Synchronisierung oder Registry-Konvergenz nicht abgeschlossen wurden, dokumentiert die Update-CLI diesen Recovery-Pfad:

openclaw update repair --json

openclaw update repair installiert keine neue Core-Version und startet den Gateway nicht neu. Der Befehl wiederholt die Finalisierung des bereits erfolgten Updates. Prüfe danach erneut:

openclaw status --all
openclaw gateway status

Falls die Update-Reparatur erfolgreich war, der Dienst aber weiterhin nicht läuft oder noch auf eine alte Installation zeigt, kann anschließend ein bewusster Neustart nötig sein:

openclaw gateway restart
openclaw gateway status

Der Neustart unterbricht den Dienst kurzzeitig und gehört deshalb nicht an den Anfang des Diagnosepfads.

Die aktuelle Troubleshooting-Dokumentation nennt als mögliches Fehlermuster einen abgebrochenen Plugin-Load wegen eines beschädigten Dependency Tree. In diesem Fall kann die Kanal-Konfiguration noch vorhanden sein, obwohl die Plugin-Registrierung bereits vor dem Laden des Kanals scheitert. Nach einem unvollständigen Update solltest du zuerst prüfen, ob openclaw update repair den gesamten Finalisierungspfad wiederherstellt. Bei einem isolierten Doctor-Befund bleibt openclaw doctor --fix die gezielte Reparatur.

Bei Provider-401-Fehlern nach einer erneuten Anmeldung solltest du außerdem das verwendete OAuth-Profil prüfen. Für aktuelle Releases beschreibt die Troubleshooting-Referenz, dass openclaw doctor --fix veraltete agentenspezifische OAuth-Kopien bereinigen kann, damit Agenten wieder das gemeinsame Profil verwenden. Prüfe bei älteren Versionen zuerst die lokale Doctor-Hilfe und den konkreten Befund.

Auch unterschiedliche Installationsstände können Reparaturen blockieren. Die aktuelle Troubleshooting-Dokumentation beschreibt dafür meta.lastTouchedVersion: Eine ältere Binary darf eine von einer neueren Version geschriebene Konfiguration lesen, verweigert aber bestimmte Änderungen an Prozessen und Diensten. Diese Befehle machen den Versionskonflikt greifbar:

which openclaw
openclaw --version
openclaw config get meta.lastTouchedVersion
openclaw gateway status --deep

Vergleiche damit die Binary deines Terminals, den letzten Konfigurationsschreiber und die tatsächlich gestarteten Gateway-Dienste.

SecretRef-Warnungen und Dead Letters getrennt behandeln

Doctor kann Probleme mit SecretRef-Eigentümern als Secret runtime degradation melden. Der Befund enthält den betroffenen Konfigurationspfad, einen redigierten Grund und verweist für einen erneuten Ladeversuch auf openclaw secrets reload. Die Redigierung schützt Zugangsdaten davor, unmaskiert in Logs oder Tickets zu landen.

Für verworfene eingehende Kanalereignisse zeigt Doctor den betroffenen Account. Neuere Fassungen der Online-Dokumentation beschreiben dafür einen eigenen channels dead-letters-Unterbefehl:

openclaw channels dead-letters list --channel <kanal> --account <account>
openclaw channels dead-letters resubmit <event-id> --channel <kanal> --account <account>

Führe diese Befehle auf dem Gateway-Host aus, damit sie dieselbe Zustandsdatenbank wie die Kanallaufzeit verwenden. Die installierte CLI kann der Online-Dokumentation allerdings hinterherlaufen. Prüfe deshalb zuerst die tatsächlich verfügbare Befehlsoberfläche:

openclaw channels --help
openclaw channels logs --channel <kanal>

Wenn deine lokale Hilfe dead-letters aufführt, liste das Ereignis zunächst nur auf und inspiziere den Fehler. Ein späteres Resubmit verändert den Verarbeitungszustand und kann das Ereignis erneut auslösen; führe es erst nach Behebung der Ursache aus. Fehlt der Unterbefehl, arbeite mit dem von Doctor genannten Account und den Kanallogs weiter, statt einen nicht verfügbaren Befehl zu kopieren. Dead Letters bilden einen eigenen Fehlerpfad: Ein Kanal kann erreichbar wirken, obwohl einzelne Ereignisse nach einem Verarbeitungsfehler zurückgestellt wurden.

Reality Check

• Getestet: Die Diagnoseleiter und ihre Optionen wurden gegen die aktuelle offizielle Dokumentation abgeglichen. Die mögliche Versionsabweichung beim Dead-Letter-Unterbefehl ist oben ausdrücklich markiert; Live-Ausgaben bleiben systemabhängig.
• Geeignet für: Gateway-Ausfälle, isolierte Kanalprobleme, Update-Folgen, Provider-401 und bekannte Zustandsfehler.
• Grenzen: Ein nicht erreichbarer Host, externe Provider-Ausfälle oder Fehler außerhalb der OpenClaw-Prüfungen benötigen zusätzliche Diagnostik.
• Nicht abgedeckt: Unterschiede zwischen konkreten Messenger- und Betriebssystemvarianten.
• Eingriffsrisiko: Diagnosebefehle sind vergleichsweise unkritisch; doctor --fix, update repair, Dead-Letter-Resubmits und Gateway-Neustarts verändern produktiven Zustand.
• Aufwand: niedrig für die Eingrenzung, höher für Reparatur und Ursachenprüfung.

Was du dokumentieren solltest

Eine belastbare Diagnose endet nicht bei „läuft wieder“. Notiere die ausgeführte OpenClaw-Version, welcher Status vom erwarteten Zustand abwich, welche Logzeile beim reproduzierten Fehler erschien und welche einzelne Maßnahme das Verhalten änderte. Prüfe nach jeder Reparatur denselben Status und reproduziere denselben Testfall erneut. Bleibt die Störung bestehen, hast du damit einen verwertbaren Befund – und keine Sammlung undokumentierter Neustarts.