Doctor

openclaw doctor ist das Reparatur- und Migrations-Tool für OpenClaw. Es behebt veraltete Konfiguration/State, prüft die Gesundheit und liefert umsetzbare Reparatur-Schritte.

Schnellstart


openclaw doctor

Headless / Automation


openclaw doctor --yes

Standardwerte ohne Abfrage akzeptieren (inkl. Neustart-/Dienst-/Sandbox-Reparatur, wenn zutreffend).


openclaw doctor --repair

Empfohlene Reparaturen ohne Abfrage anwenden (Reparaturen + Neustarts, wo sicher).


openclaw doctor --repair --force

Auch aggressive Reparaturen anwenden (überschreibt benutzerdefinierte Supervisor-Konfigurationen).


openclaw doctor --non-interactive

Ohne Abfragen laufen und nur sichere Migrationen anwenden (Konfig-Normalisierung + State-Verschiebungen auf Disk). Überspringt Neustart-/Dienst-/Sandbox-Aktionen, die Bestätigung erfordern. Veraltete State-Migrationen laufen automatisch, wenn erkannt.


openclaw doctor --deep

Systemdienste nach weiteren Gateway-Installationen durchsuchen (launchd/systemd/schtasks). Wenn Sie Änderungen vor dem Schreiben prüfen möchten, zuerst die Konfigurationsdatei öffnen:


cat ~/.clawdbot/openclaw.json

Was es tut (Zusammenfassung)

Optionales Pre-Flight-Update für Git-Installationen (nur interaktiv).
UI-Protokoll-Aktualitätsprüfung (baut Control-UI neu, wenn das Protokoll-Schema neuer ist).
Health-Check + Neustart-Aufforderung.
Skills-Status-Zusammenfassung (geeignet/fehlend/blockiert).
Konfig-Normalisierung für veraltete Werte.
OpenCode-Zen-Provider-Override-Warnungen (models.providers.opencode).
Veraltete State-Migration auf Disk (Sitzungen/Agent-Verzeichnis/WhatsApp-Auth).
State-Integritäts- und Berechtigungsprüfungen (Sitzungen, Transkripte, State-Verzeichnis).
Konfig-Dateiberechtigungen (chmod 600) bei lokaler Ausführung.
Model-Auth-Gesundheit: prüft OAuth-Ablauf, kann ablaufende Tokens erneuern und meldet Cooldown/Deaktiviert-Status von Auth-Profilen.
Erkennung zusätzlicher Workspace-Verzeichnisse (~/openclaw).
Sandbox-Image-Reparatur bei aktivierter Sandbox.
Veraltete Dienst-Migration und Erkennung weiterer Gateways.
Gateway-Laufzeitprüfungen (Dienst installiert, aber nicht laufend; gecachtes launchd-Label).
Kanal-Status-Warnungen (vom laufenden Gateway abgefragt).
Supervisor-Konfig-Audit (launchd/systemd/schtasks) mit optionaler Reparatur.
Gateway-Laufzeit-Best-Practice-Prüfungen (Node vs. Bun, Version-Manager-Pfade).
Gateway-Port-Kollisionsdiagnostik (Standard 18789).
Sicherheitswarnungen bei offenen DM-Richtlinien.
Gateway-Auth-Warnungen, wenn kein gateway.auth.token gesetzt ist (lokaler Modus; bietet Token-Erzeugung an).
systemd-Linger-Check unter Linux.
Quell-Installations-Checks (pnpm-Workspace-Abweichung, fehlende UI-Assets, fehlende tsx-Binary).
Schreibt aktualisierte Konfig + Wizard-Metadaten.

Detailliertes Verhalten und Begründung

0) Optionales Update (Git-Installationen)

Bei einer Git-Installation und interaktivem Doctor-Lauf wird vor dem Doctor-Lauf ein Update (fetch/rebase/build) angeboten.

1) Konfig-Normalisierung

Enthält die Konfiguration veraltete Wertformen (z. B. messages.ackReaction ohne kanalspezifische Override), normalisiert Doctor sie ins aktuelle Schema.

2) Veraltete Konfig-Schlüssel-Migrationen

Enthält die Konfiguration veraltete Schlüssel, verweigern andere Befehle die Ausführung und bitten um openclaw doctor. Doctor wird:

Erklären, welche veralteten Schlüssel gefunden wurden.
Die angewendete Migration anzeigen.
~/.clawdbot/openclaw.json mit dem aktualisierten Schema überschreiben.

Der Gateway führt Doctor-Migrationen beim Start ebenfalls automatisch aus, wenn ein veraltetes Konfig-Format erkannt wird, sodass veraltete Konfigurationen ohne manuellen Eingriff repariert werden. Aktuelle Migrationen:

routing.allowFrom → channels.whatsapp.allowFrom
routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
routing.groupChat.historyLimit → messages.groupChat.historyLimit
routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
routing.queue → messages.queue
routing.bindings → Top-Level bindings
routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
routing.agentToAgent → tools.agentToAgent
routing.transcribeAudio → tools.media.audio.models
bindings[].match.accountID → bindings[].match.accountId
identity → agents.list[].identity
agent.* → agents.defaults + tools.* (tools/elevated/exec/sandbox/subagents)
agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks

2b) OpenCode-Zen-Provider-Overrides

Wenn Sie models.providers.opencode (oder opencode-zen) manuell hinzugefügt haben, überschreibt es den eingebauten OpenCode-Zen-Katalog von @mariozechner/pi-ai. Das kann alle Modelle auf eine einzige API zwingen oder Kosten auf null setzen. Doctor warnt, damit Sie den Override entfernen und pro-Modell-API-Routing + Kosten wiederherstellen können.

3) Veraltete State-Migrationen (Disk-Layout)

Doctor kann ältere On-Disk-Layouts in die aktuelle Struktur migrieren:

Sitzungsspeicher + Transkripte: von ~/.clawdbot/sessions/ nach ~/.clawdbot/agents/<agentId>/sessions/
Agent-Verzeichnis: von ~/.clawdbot/agent/ nach ~/.clawdbot/agents/<agentId>/agent/
WhatsApp-Auth-State (Baileys): von veraltet ~/.clawdbot/credentials/*.json (außer oauth.json) nach ~/.clawdbot/credentials/whatsapp/<accountId>/... (Standard-Account-ID: default)

Diese Migrationen sind Best-Effort und idempotent; Doctor gibt Warnungen aus, wenn es veraltete Ordner als Backups zurücklässt. Gateway/CLI migrieren veraltete Sitzungen + Agent-Verzeichnis beim Start ebenfalls automatisch, sodass Verlauf/Auth/Models ohne manuellen Doctor-Lauf im per-Agent-Pfad landen. WhatsApp-Auth wird bewusst nur über openclaw doctor migriert.

4) State-Integritätsprüfungen (Sitzungspersistenz, Routing, Sicherheit)

Das State-Verzeichnis ist das operative Rückgrat. Verschwindet es, gehen Sitzungen, Credentials, Logs und Konfiguration verloren (außer Sie haben Backups woanders). Doctor prüft:

State-Verzeichnis fehlt: warnt vor katastrophalem State-Verlust, fordert zur Neuerstellung auf und erinnert daran, dass fehlende Daten nicht wiederhergestellt werden können.
State-Verzeichnis-Berechtigungen: prüft Schreibbarkeit; bietet Reparatur der Berechtigungen an (und gibt einen chown-Hinweis aus, wenn Besitzer/Gruppe nicht übereinstimmen).
Sitzungsverzeichnisse fehlen: sessions/ und das Sitzungsspeicher-Verzeichnis sind nötig, um Verlauf zu persistieren und ENOENT-Abstürze zu vermeiden.
Transkript-Abweichung: warnt, wenn aktuelle Sitzungseinträge fehlende Transkript-Dateien haben.
Hauptsitzung „1-Zeile-JSONL“: meldet, wenn das Haupttranskript nur eine Zeile hat (Verlauf sammelt sich nicht an).
Mehrere State-Verzeichnisse: warnt, wenn mehrere ~/.clawdbot-Ordner über Home-Verzeichnisse hinweg existieren oder CLAWDBOT_STATE_DIR woanders zeigt (Verlauf kann zwischen Installationen geteilt sein).
Remote-Modus-Hinweis: bei gateway.mode=remote erinnert Doctor daran, es auf dem Remote-Host auszuführen (der State liegt dort).
Konfig-Dateiberechtigungen: warnt, wenn ~/.clawdbot/openclaw.json gruppen-/weltlesbar ist, und bietet an, auf 600 zu verschärfen.

5) Model-Auth-Gesundheit (OAuth-Ablauf)

Doctor prüft OAuth-Profile im Auth-Store, warnt bei ablaufenden/abgelaufenen Tokens und kann sie bei Sicherheit erneuern. Ist das Anthropic-Claude-Code-Profil veraltet, schlägt es claude setup-token vor (oder Einfügen eines Setup-Tokens). Erneuerungs-Aufforderungen erscheinen nur bei interaktiver Ausführung (TTY); --non-interactive überspringt Erneuerungsversuche. Doctor meldet auch Auth-Profile, die vorübergehend wegen kurzer Cooldowns (Rate-Limits/Timeouts/Auth-Fehler) oder längerer Deaktivierung (Billing/Credit-Fehler) unnutzbar sind.

6) Hooks-Modell-Validierung

Ist hooks.gmail.model gesetzt, validiert Doctor die Modellreferenz gegen Katalog und Allowlist und warnt, wenn sie nicht auflösbar oder nicht erlaubt ist.

7) Sandbox-Image-Reparatur

Bei aktivierter Sandbox prüft Doctor Docker-Images und bietet Build oder Wechsel zu veralteten Namen an, wenn das aktuelle Image fehlt.

8) Gateway-Dienst-Migrationen und Aufräum-Hinweise

Doctor erkennt veraltete Gateway-Dienste (launchd/systemd/schtasks) und bietet an, sie zu entfernen und den OpenClaw-Dienst mit dem aktuellen Gateway-Port zu installieren. Es kann auch nach weiteren gateway-ähnlichen Diensten suchen und Aufräum-Hinweise ausgeben. Profilbenannte OpenClaw-Gateway-Dienste gelten als First-Class und werden nicht als „extra“ markiert.

9) Sicherheitswarnungen

Doctor gibt Warnungen aus, wenn ein Provider für DMs ohne Allowlist offen ist oder eine Richtlinie gefährlich konfiguriert ist.

10) systemd Linger (Linux)

Bei Ausführung als systemd-User-Service stellt Doctor sicher, dass Linger aktiviert ist, damit der Gateway nach Abmeldung weiterläuft.

11) Skills-Status

Doctor gibt eine kurze Zusammenfassung geeigneter/fehlender/blockierter Skills für den aktuellen Workspace aus.

12) Gateway-Auth-Prüfungen (lokaler Token)

Doctor warnt, wenn gateway.auth bei einem lokalen Gateway fehlt, und bietet Token-Erzeugung an. openclaw doctor --generate-gateway-token erzwingt Token-Erzeugung in der Automation.

13) Gateway-Health-Check + Neustart

Doctor führt einen Health-Check durch und bietet einen Gateway-Neustart an, wenn der Zustand ungesund wirkt.

14) Kanal-Status-Warnungen

Ist der Gateway gesund, führt Doctor eine Kanal-Status-Probe durch und meldet Warnungen mit vorgeschlagenen Behebungen.

15) Supervisor-Konfig-Audit + Reparatur

Doctor prüft die installierte Supervisor-Konfiguration (launchd/systemd/schtasks) auf fehlende oder veraltete Defaults (z. B. systemd network-online-Abhängigkeiten und Restart-Delay). Bei Abweichung empfiehlt es ein Update und kann die Service-Datei/den Task auf die aktuellen Defaults zurückschreiben. Hinweise:

openclaw doctor fragt vor dem Überschreiben der Supervisor-Konfiguration nach.
openclaw doctor --yes akzeptiert die Standard-Reparatur-Aufforderungen.
openclaw doctor --repair wendet empfohlene Fixes ohne Abfrage an.
openclaw doctor --repair --force überschreibt benutzerdefinierte Supervisor-Konfigurationen.
Ein vollständiges Neuschreiben kann immer mit openclaw gateway install --force erzwungen werden.

16) Gateway-Laufzeit + Port-Diagnostik

Doctor prüft die Dienst-Laufzeit (PID, letzter Exit-Status) und warnt, wenn der Dienst installiert, aber nicht tatsächlich laufend ist. Es prüft auch Port-Kollisionen am Gateway-Port (Standard 18789) und meldet wahrscheinliche Ursachen (Gateway bereits laufend, SSH-Tunnel).

17) Gateway-Laufzeit-Best-Practices

Doctor warnt, wenn der Gateway-Dienst unter Bun oder einem versionierten Node-Pfad (nvm, fnm, volta, asdf usw.) läuft. WhatsApp- und Telegram-Kanäle benötigen Node, und Version-Manager-Pfade können nach Upgrades brechen, weil der Dienst Ihre Shell-Init nicht lädt. Doctor bietet die Migration zu einer System-Node-Installation an, wenn verfügbar (Homebrew/apt/choco).

18) Konfig-Schreiben + Wizard-Metadaten

Doctor speichert Konfigurationsänderungen und stempelt Wizard-Metadaten, um den Doctor-Lauf zu protokollieren.

19) Workspace-Tipps (Backup + Memory-System)

Doctor schlägt ein Workspace-Memory-System vor, wenn fehlend, und gibt einen Backup-Tipp aus, wenn der Workspace noch nicht unter Git liegt. Vollständige Anleitung zu Workspace-Struktur und Git-Backup (empfohlen: privates GitHub oder GitLab): Agent-Workspace.