Doctor

openclaw doctor ist das Reparatur- und Migrationstool für OpenClaw. Es behebt veraltete Konfigurationen/Zustände, prüft die Systemgesundheit und liefert umsetzbare Reparaturschritte.

Schnellstart

openclaw doctor

Headless / Automatisierung

openclaw doctor --yes

Akzeptiert Standardeinstellungen ohne Rückfrage (einschließlich Neustart-/Service-/Sandbox-Reparaturschritte, wenn anwendbar).

openclaw doctor --repair

Wendet empfohlene Reparaturen ohne Rückfrage an (Reparaturen + Neustarts, wenn sicher).

openclaw doctor --repair --force

Wendet auch aggressive Reparaturen an (überschreibt benutzerdefinierte Supervisor-Konfigurationen).

openclaw doctor --non-interactive

Läuft ohne Rückfragen und wendet nur sichere Migrationen an (Konfigurations-Normalisierung + Verschiebung von On-Disk-State). Überspringt Neustart-/Service-/Sandbox-Aktionen, die menschliche Bestätigung erfordern. Legacy-State-Migrationen laufen automatisch, wenn sie erkannt werden.

openclaw doctor --deep

Durchsucht Systemdienste nach zusätzlichen Gateway-Installationen (launchd/systemd/schtasks).

Um Änderungen vor dem Schreiben zu überprüfen, öffne zuerst die Konfigurationsdatei:

cat ~/.openclaw/openclaw.json

Was es macht (Zusammenfassung)

• Optionaler Pre-Flight-Update für Git-Installationen (nur interaktiv).
• UI-Protokoll-Aktualitätsprüfung (baut Control UI neu, wenn das Protokoll-Schema neuer ist).
• Gesundheitsprüfung + Neustart-Aufforderung.
• Skills-Status-Zusammenfassung (berechtigt/fehlend/blockiert).
• Konfigurations-Normalisierung für Legacy-Werte.
• OpenCode-Provider-Override-Warnungen (models.providers.opencode / models.providers.opencode-go).
• Legacy-On-Disk-State-Migration (Sessions/Agent-Verzeichnis/WhatsApp-Auth).
• Legacy-Cron-Store-Migration (jobId, schedule.cron, Top-Level-Delivery/Payload-Felder, Payload provider, einfache notify: true Webhook-Fallback-Jobs).
• State-Integritäts- und Berechtigungsprüfungen (Sessions, Transkripte, State-Verzeichnis).
• Konfigurations-Dateiberechtigungsprüfungen (chmod 600) bei lokalem Betrieb.
• Modell-Auth-Gesundheit: prüft OAuth-Ablauf, kann ablaufende Token erneuern und meldet Auth-Profil-Cooldown-/Disabled-Zustände.
• Erkennung zusätzlicher Workspace-Verzeichnisse (~/openclaw).
• Sandbox-Image-Reparatur wenn Sandboxing aktiviert ist.
• Legacy-Service-Migration und Erkennung zusätzlicher Gateways.
• Gateway-Laufzeitprüfungen (Service installiert aber nicht laufend; gecachtes launchd-Label).
• Kanal-Status-Warnungen (vom laufenden Gateway abgefragt).
• Supervisor-Konfigurations-Audit (launchd/systemd/schtasks) mit optionaler Reparatur.
• Gateway-Laufzeit-Best-Practice-Prüfungen (Node vs. Bun, Version-Manager-Pfade).
• Gateway-Port-Kollisionsdiagnose (Standard 18789).
• Sicherheitswarnungen für offene DM-Policies.
• Gateway-Auth-Prüfungen für lokalen Token-Modus (bietet Token-Generierung an, wenn keine Token-Quelle existiert; überschreibt keine Token-SecretRef-Konfigurationen).
• systemd-Linger-Prüfung unter Linux.
• Source-Install-Prüfungen (pnpm-Workspace-Mismatch, fehlende UI-Assets, fehlende tsx-Binary).
• Schreibt aktualisierte Konfiguration + Wizard-Metadaten.

Detailliertes Verhalten und Begründung

0) Optionales Update (Git-Installationen)

Wenn es sich um einen Git-Checkout handelt und doctor interaktiv läuft, bietet es an, vor dem Doctor-Lauf zu aktualisieren (fetch/rebase/build).

1) Konfigurations-Normalisierung

Falls die Konfiguration Legacy-Wertformen enthält (z. B. messages.ackReaction ohne kanalspezifischen Override), normalisiert doctor diese in das aktuelle Schema.

2) Legacy-Konfigurations-Key-Migrationen

Wenn die Konfiguration veraltete Schlüssel enthält, verweigern andere Befehle die Ausführung und bitten dich, openclaw doctor auszuführen.

Doctor wird:

• Erklären, welche Legacy-Schlüssel gefunden wurden.
• Die angewandte Migration anzeigen.
• ~/.openclaw/openclaw.json mit dem aktualisierten Schema neu schreiben.

Das Gateway führt Doctor-Migrationen auch automatisch beim Start aus, wenn es ein Legacy-Konfigurationsformat erkennt, sodass veraltete Konfigurationen ohne manuelles Eingreifen 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
• Für Kanäle mit benannten accounts aber fehlendem accounts.default werden kontobezogene Top-Level-Einzelkonto-Kanalwerte bei Vorhandensein nach channels.<channel>.accounts.default verschoben
• 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
• browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork

Doctor-Warnungen enthalten auch Account-Default-Hinweise für Multi-Account-Kanäle:

• Wenn zwei oder mehr channels.<channel>.accounts-Einträge konfiguriert sind, ohne dass channels.<channel>.defaultAccount oder accounts.default gesetzt ist, warnt doctor, dass Fallback-Routing ein unerwartetes Konto wählen kann.
• Wenn channels.<channel>.defaultAccount auf eine unbekannte Account-ID gesetzt ist, warnt doctor und listet die konfigurierten Account-IDs auf.

2b) OpenCode-Provider-Overrides

Wenn du models.providers.opencode, opencode-zen oder opencode-go manuell hinzugefügt hast, überschreibt das den eingebauten OpenCode-Katalog von @mariozechner/pi-ai. Das kann Modelle auf die falsche API zwingen oder Kosten auf Null setzen. Doctor warnt, damit du den Override entfernen und das Pro-Modell-API-Routing + Kosten wiederherstellen kannst.

3) Legacy-State-Migrationen (Disk-Layout)

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

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

Diese Migrationen sind Best-Effort und idempotent; doctor gibt Warnungen aus, wenn Legacy-Ordner als Backups zurückbleiben. Gateway/CLI migrieren automatisch den Legacy-Sessions- + Agent-Ordner beim Start, sodass History/Auth/Models im Per-Agent-Pfad landen, ohne einen manuellen Doctor-Lauf. WhatsApp-Auth wird absichtlich nur über openclaw doctor migriert.

3b) Legacy-Cron-Store-Migrationen

Doctor prüft auch den Cron-Job-Store (~/.openclaw/cron/jobs.json standardmäßig, oder cron.store wenn überschrieben) auf alte Job-Shapes, die der Scheduler aus Kompatibilitätsgründen noch akzeptiert.

Aktuelle Cron-Bereinigungen:

• jobId → id
• schedule.cron → schedule.expr
• Top-Level-Payload-Felder (message, model, thinking, …) → payload
• Top-Level-Delivery-Felder (deliver, channel, to, provider, …) → delivery
• Payload-provider-Delivery-Aliase → explizites delivery.channel
• Einfache Legacy-notify: true-Webhook-Fallback-Jobs → explizites delivery.mode="webhook" mit delivery.to=cron.webhook

Doctor migriert notify: true-Jobs nur automatisch, wenn es ohne Verhaltensänderung möglich ist. Wenn ein Job einen Legacy-Notify-Fallback mit einem bestehenden Nicht-Webhook-Delivery-Modus kombiniert, warnt doctor und überlässt diesen Job der manuellen Überprüfung.

4) State-Integritätsprüfungen (Session-Persistenz, Routing und Sicherheit)

Das State-Verzeichnis ist das operative Hirnstamm-Äquivalent. Geht es verloren, verlierst du Sessions, Credentials, Logs und Konfiguration (sofern keine Backups anderswo existieren).

Doctor prüft:

• State-Verzeichnis fehlt: Warnt vor katastrophalem State-Verlust, bietet an, das Verzeichnis neu zu erstellen, und erinnert daran, dass fehlende Daten nicht wiederhergestellt werden können.
• State-Verzeichnis-Berechtigungen: Prüft Schreibbarkeit; bietet Berechtigungsreparatur an (und gibt einen chown-Hinweis aus, wenn ein Eigentümer/Gruppen-Mismatch erkannt wird).
• macOS-Cloud-Sync-State-Verzeichnis: Warnt, wenn der State unter iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) oder ~/Library/CloudStorage/... aufgelöst wird, da sync-basierte Pfade langsameres I/O und Lock-/Sync-Races verursachen können.
• Linux-SD- oder eMMC-State-Verzeichnis: Warnt, wenn der State auf eine mmcblk*-Mount-Source zeigt, da SD- oder eMMC-basiertes Random-I/O langsamer sein kann und unter Session- und Credential-Schreibvorgängen schneller verschleißt.
• Session-Verzeichnisse fehlen: sessions/ und das Session-Store-Verzeichnis werden benötigt, um History zu persistieren und ENOENT-Abstürze zu vermeiden.
• Transkript-Mismatch: Warnt, wenn aktuelle Session-Einträge fehlende Transkript-Dateien haben.
• Haupt-Session “1-Zeilen-JSONL”: Markiert, wenn das Haupttranskript nur eine Zeile hat (History sammelt sich nicht an).
• Mehrere State-Verzeichnisse: Warnt, wenn mehrere ~/.openclaw-Ordner über Home-Verzeichnisse hinweg existieren oder wenn OPENCLAW_STATE_DIR anderswohin zeigt (History kann sich zwischen Installationen aufteilen).
• Remote-Modus-Erinnerung: Wenn gateway.mode=remote, erinnert doctor daran, den Befehl auf dem Remote-Host auszuführen (der State liegt dort).
• Konfigurationsdatei-Berechtigungen: Warnt, wenn ~/.openclaw/openclaw.json gruppen-/weltweit lesbar ist und bietet an, auf 600 zu verschärfen.

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

Doctor prüft OAuth-Profile im Auth-Store, warnt wenn Token ablaufen/abgelaufen sind und kann sie erneuern, wenn es sicher ist. Bei veraltetem Anthropic-Claude-Code-Profil schlägt es vor, claude setup-token auszuführen (oder einen Setup-Token einzufügen). Erneuerungs-Prompts erscheinen nur bei interaktiver Ausführung (TTY); --non-interactive überspringt Erneuerungsversuche.

Doctor meldet auch Auth-Profile, die vorübergehend nicht nutzbar sind aufgrund von:

• kurzen Cooldowns (Rate-Limits/Timeouts/Auth-Fehler)
• längeren Deaktivierungen (Billing-/Credit-Fehler)

6) Hooks-Modell-Validierung

Wenn hooks.gmail.model gesetzt ist, validiert doctor die Modellreferenz gegen den Katalog und die Allowlist und warnt, wenn sie nicht aufgelöst werden kann oder nicht erlaubt ist.

7) Sandbox-Image-Reparatur

Wenn Sandboxing aktiviert ist, prüft doctor Docker-Images und bietet an, sie zu bauen oder zu Legacy-Namen zu wechseln, falls das aktuelle Image fehlt.

8) Gateway-Service-Migrationen und Aufräumhinweise

Doctor erkennt Legacy-Gateway-Services (launchd/systemd/schtasks) und bietet an, sie zu entfernen und den OpenClaw-Service mit dem aktuellen Gateway-Port zu installieren. Es kann auch nach zusätzlichen Gateway-ähnlichen Services suchen und Aufräumhinweise ausgeben. Profilbenannte OpenClaw-Gateway-Services gelten als erstklassig und werden nicht als “zusätzlich” markiert.

9) Sicherheitswarnungen

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

10) systemd-Linger (Linux)

Bei Ausführung als systemd-User-Service stellt doctor sicher, dass Lingering aktiviert ist, damit das Gateway nach dem Logout weiterläuft.

11) Skills-Status

Doctor gibt eine kurze Zusammenfassung der berechtigten/fehlenden/blockierten Skills für den aktuellen Workspace aus.

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

Doctor prüft die lokale Gateway-Token-Auth-Bereitschaft.

• Wenn der Token-Modus einen Token benötigt und keine Token-Quelle existiert, bietet doctor an, einen zu generieren.
• Wenn gateway.auth.token per SecretRef verwaltet wird, aber nicht verfügbar ist, warnt doctor und überschreibt ihn nicht mit Klartext.
• openclaw doctor --generate-gateway-token erzwingt die Generierung nur, wenn kein Token-SecretRef konfiguriert ist.

12b) Read-Only-SecretRef-bewusste Reparaturen

Einige Reparatur-Flows müssen konfigurierte Credentials prüfen, ohne das Laufzeit-Fail-Fast-Verhalten zu schwächen.

• openclaw doctor --fix verwendet jetzt dasselbe Read-Only-SecretRef-Summary-Modell wie Status-Family-Befehle für gezielte Konfigurations-Reparaturen.
• Beispiel: Telegram-allowFrom-/groupAllowFrom-@username-Reparatur versucht, konfigurierte Bot-Credentials zu verwenden, wenn verfügbar.
• Wenn das Telegram-Bot-Token per SecretRef konfiguriert, aber im aktuellen Befehlspfad nicht verfügbar ist, meldet doctor, dass das Credential konfiguriert-aber-nicht-verfügbar ist und überspringt die Auto-Auflösung, anstatt abzustürzen oder das Token fälschlich als fehlend zu melden.

13) Gateway-Gesundheitsprüfung + Neustart

Doctor führt eine Gesundheitsprüfung durch und bietet an, das Gateway neu zu starten, wenn es ungesund wirkt.

14) Kanal-Status-Warnungen

Wenn das Gateway gesund ist, führt doctor einen Kanal-Status-Probe durch und meldet Warnungen mit Lösungsvorschlägen.

15) Supervisor-Konfigurations-Audit + Reparatur

Doctor prüft die installierte Supervisor-Konfiguration (launchd/systemd/schtasks) auf fehlende oder veraltete Standardwerte (z. B. systemd-network-online-Abhängigkeiten und Neustartverzögerung). Bei Abweichungen empfiehlt es ein Update und kann die Service-Datei/Task auf die aktuellen Standards umschreiben.

Hinweise:

• openclaw doctor fragt vor dem Umschreiben der Supervisor-Konfiguration nach.
• openclaw doctor --yes akzeptiert die Standard-Reparatur-Prompts.
• openclaw doctor --repair wendet empfohlene Fixes ohne Prompts an.
• openclaw doctor --repair --force überschreibt benutzerdefinierte Supervisor-Konfigurationen.
• Wenn Token-Auth einen Token erfordert und gateway.auth.token per SecretRef verwaltet wird, validiert doctor den SecretRef beim Service-Install/Reparatur, persistiert aber keine aufgelösten Klartext-Token-Werte in Supervisor-Service-Umgebungsmetadaten.
• Wenn Token-Auth einen Token erfordert und der konfigurierte Token-SecretRef nicht aufgelöst werden kann, blockiert doctor den Install-/Reparatur-Pfad mit umsetzbarer Anleitung.
• Wenn sowohl gateway.auth.token als auch gateway.auth.password konfiguriert sind und gateway.auth.mode nicht gesetzt ist, blockiert doctor Install/Reparatur bis der Modus explizit gesetzt wird.
• Für Linux-User-systemd-Units prüft doctor Token-Drift jetzt sowohl Environment= als auch EnvironmentFile=-Quellen beim Vergleich von Service-Auth-Metadaten.
• Du kannst jederzeit ein vollständiges Umschreiben erzwingen mit openclaw gateway install --force.

16) Gateway-Laufzeit + Port-Diagnose

Doctor prüft die Service-Laufzeit (PID, letzter Exit-Status) und warnt, wenn der Service installiert aber nicht tatsächlich laufend ist. Es prüft auch auf 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-Service unter Bun oder einem Version-Manager-Node-Pfad (nvm, fnm, volta, asdf usw.) läuft. WhatsApp- + Telegram-Kanäle erfordern Node, und Version-Manager-Pfade können nach Upgrades brechen, weil der Service deine Shell-Init nicht lädt. Doctor bietet an, zu einer System-Node-Installation zu migrieren, wenn verfügbar (Homebrew/apt/choco).

18) Konfigurations-Schreiben + Wizard-Metadaten

Doctor persistiert alle Konfigurationsänderungen und setzt Wizard-Metadaten, um den Doctor-Lauf zu protokollieren.

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

Doctor schlägt ein Workspace-Memory-System vor, wenn es fehlt, und gibt einen Backup-Tipp aus, falls der Workspace noch nicht unter Git steht.

Siehe /concepts/agent-workspace für einen vollständigen Guide zur Workspace-Struktur und Git-Backup (empfohlen: privates GitHub oder GitLab).