Doctor

openclaw doctor ist das Reparatur- und Migrationstool für OpenClaw. Es behebt veraltete Config/State-Probleme, prüft die Systemgesundheit und zeigt dir konkrete Reparaturschritte.

Schnellstart

openclaw doctor

Headless / Automatisierung

openclaw doctor --yes

Akzeptiert Standardwerte ohne Nachfrage (einschließlich Neustart/Service/Sandbox-Reparaturen, wenn nötig).

openclaw doctor --repair

Wendet empfohlene Reparaturen ohne Nachfrage an (Reparaturen + Neustarts, wo sicher).

openclaw doctor --repair --force

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

openclaw doctor --non-interactive

Läuft ohne Prompts und wendet nur sichere Migrationen an (Config-Normalisierung + State-Verschiebungen auf der Festplatte). Überspringt Neustart/Service/Sandbox-Aktionen, die eine manuelle Bestätigung erfordern. Legacy-State-Migrationen laufen automatisch, wenn sie erkannt werden.

openclaw doctor --deep

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

Wenn du Änderungen vor dem Schreiben prüfen möchtest, öffne zuerst die Config-Datei:

cat ~/.openclaw/openclaw.json

Was es macht (Zusammenfassung)

  • Optionales Pre-Flight-Update für Git-Installationen (nur interaktiv).
  • UI-Protokoll-Frischeprüfung (baut Control UI neu, wenn das Protokollschema neuer ist).
  • Gesundheitscheck + Neustart-Prompt.
  • Skills-Status-Zusammenfassung (berechtigt/fehlend/blockiert).
  • Config-Normalisierung für Legacy-Werte.
  • OpenCode Zen Provider-Override-Warnungen (models.providers.opencode).
  • Legacy-State-Migration auf der Festplatte (Sessions/Agent-Verzeichnis/WhatsApp-Auth).
  • State-Integritäts- und Berechtigungsprüfungen (Sessions, Transcripts, State-Verzeichnis).
  • Config-Dateiberechtigungsprüfungen (chmod 600) bei lokaler Ausführung.
  • Model-Auth-Gesundheit: prüft OAuth-Ablauf, kann ablaufende Tokens erneuern und meldet Auth-Profil-Cooldown/Deaktiviert-Zustände.
  • Erkennung zusätzlicher Workspace-Verzeichnisse (~/openclaw).
  • Sandbox-Image-Reparatur, wenn Sandboxing aktiviert ist.
  • Legacy-Service-Migration und Erkennung zusätzlicher Gateways.
  • Gateway-Runtime-Checks (Service installiert aber nicht laufend; gecachtes launchd-Label).
  • Channel-Status-Warnungen (vom laufenden Gateway abgefragt).
  • Supervisor-Config-Audit (launchd/systemd/schtasks) mit optionaler Reparatur.
  • Gateway-Runtime-Best-Practice-Checks (Node vs Bun, Version-Manager-Pfade).
  • Gateway-Port-Kollisionsdiagnose (Standard 18789).
  • Sicherheitswarnungen für offene DM-Policies.
  • Gateway-Auth-Warnungen, wenn kein gateway.auth.token gesetzt ist (lokaler Modus; bietet Token-Generierung an).
  • systemd-Linger-Check unter Linux.
  • Source-Install-Checks (pnpm-Workspace-Mismatch, fehlende UI-Assets, fehlendes tsx-Binary).
  • Schreibt aktualisierte Config + Wizard-Metadaten.

Detailliertes Verhalten und Begründung

0) Optionales Update (Git-Installationen)

Wenn dies ein Git-Checkout ist und Doctor interaktiv läuft, bietet es an, vor dem Doctor-Lauf zu aktualisieren (fetch/rebase/build).

1) Config-Normalisierung

Wenn die Config Legacy-Wertformen enthält (zum Beispiel messages.ackReaction ohne Channel-spezifischen Override), normalisiert Doctor sie ins aktuelle Schema.

2) Legacy-Config-Key-Migrationen

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

Doctor wird:

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

Das Gateway führt Doctor-Migrationen auch automatisch beim Start aus, wenn es ein Legacy-Config-Format erkennt, sodass veraltete Configs 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 du models.providers.opencode (oder opencode-zen) manuell hinzugefügt hast, überschreibt das den eingebauten OpenCode Zen-Katalog von @mariozechner/pi-ai. Das kann jedes Model auf eine einzelne API zwingen oder Kosten auf null setzen. Doctor warnt dich, damit du den Override entfernen und das Per-Model-API-Routing + Kosten wiederherstellen kannst.

3) Legacy-State-Migrationen (Festplattenlayout)

Doctor kann ältere Festplattenlayouts in die aktuelle Struktur migrieren:

  • Sessions-Store + Transcripts:
    • 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 es Legacy-Ordner als Backups zurücklässt. Das Gateway/CLI migriert auch automatisch die Legacy-Sessions + Agent-Verzeichnisse beim Start, sodass History/Auth/Models im Per-Agent-Pfad landen, ohne dass ein manueller Doctor-Lauf nötig ist. WhatsApp-Auth wird absichtlich nur über openclaw doctor migriert.

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

Das State-Verzeichnis ist das operative Stammhirn. Wenn es verschwindet, verlierst du Sessions, Credentials, Logs und Config (es sei denn, du hast Backups woanders).

Doctor prüft:

  • State-Verzeichnis fehlt: warnt vor katastrophalem State-Verlust, fragt nach, ob das Verzeichnis neu erstellt werden soll, und erinnert dich daran, dass fehlende Daten nicht wiederhergestellt werden können.
  • State-Verzeichnis-Berechtigungen: prüft Schreibbarkeit; bietet an, Berechtigungen zu reparieren (und gibt einen chown-Hinweis, wenn Owner/Group-Mismatch erkannt wird).
  • Session-Verzeichnisse fehlen: sessions/ und das Session-Store-Verzeichnis werden benötigt, um History zu persistieren und ENOENT-Crashes zu vermeiden.
  • Transcript-Mismatch: warnt, wenn aktuelle Session-Einträge fehlende Transcript-Dateien haben.
  • Haupt-Session “1-Zeilen-JSONL”: markiert, wenn das Haupt-Transcript nur eine Zeile hat (History akkumuliert nicht).
  • Mehrere State-Verzeichnisse: warnt, wenn mehrere ~/.openclaw-Ordner über Home-Verzeichnisse existieren oder wenn OPENCLAW_STATE_DIR woanders hinzeigt (History kann sich zwischen Installationen aufteilen).
  • Remote-Modus-Erinnerung: wenn gateway.mode=remote, erinnert Doctor dich daran, es auf dem Remote-Host auszuführen (der State lebt dort).
  • Config-Dateiberechtigungen: warnt, wenn ~/.openclaw/openclaw.json gruppen-/weltlesbar ist und bietet an, auf 600 zu verschärfen.

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

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

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

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

6) Hooks-Model-Validierung

Wenn hooks.gmail.model gesetzt ist, validiert Doctor die Model-Referenz gegen den Katalog und die Allowlist und warnt, wenn sie nicht aufgelöst wird 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, wenn das aktuelle Image fehlt.

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

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 scannen und Aufräum-Hinweise ausgeben. Profil-benannte OpenClaw-Gateway-Services werden als erstklassig betrachtet und nicht als “extra” markiert.

9) Sicherheitswarnungen

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

10) systemd-Linger (Linux)

Wenn als systemd-User-Service laufend, stellt Doctor sicher, dass Lingering aktiviert ist, damit das Gateway nach dem Logout am Leben bleibt.

11) Skills-Status

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

12) Gateway-Auth-Checks (lokaler Token)

Doctor warnt, wenn gateway.auth auf einem lokalen Gateway fehlt und bietet an, einen Token zu generieren. Verwende openclaw doctor --generate-gateway-token, um die Token-Erstellung in der Automatisierung zu erzwingen.

13) Gateway-Gesundheitscheck + Neustart

Doctor führt einen Gesundheitscheck durch und bietet an, das Gateway neu zu starten, wenn es ungesund aussieht.

14) Channel-Status-Warnungen

Wenn das Gateway gesund ist, führt Doctor eine Channel-Status-Abfrage durch und meldet Warnungen mit vorgeschlagenen Fixes.

15) Supervisor-Config-Audit + Reparatur

Doctor prüft die installierte Supervisor-Config (launchd/systemd/schtasks) auf fehlende oder veraltete Standardwerte (z.B. systemd network-online-Abhängigkeiten und Neustart-Verzögerung). Wenn es einen Mismatch findet, empfiehlt es ein Update und kann die Service-Datei/Task auf die aktuellen Standardwerte neu schreiben.

Hinweise:

  • openclaw doctor fragt vor dem Neuschreiben der Supervisor-Config 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-Configs.
  • Du kannst jederzeit ein vollständiges Neuschreiben über openclaw gateway install --force erzwingen.

16) Gateway-Runtime + Port-Diagnose

Doctor inspiziert die Service-Runtime (PID, letzter Exit-Status) und warnt, wenn der Service installiert aber nicht tatsächlich laufend ist. Es prüft auch auf Port-Kollisionen auf dem Gateway-Port (Standard 18789) und meldet wahrscheinliche Ursachen (Gateway läuft bereits, SSH-Tunnel).

17) Gateway-Runtime-Best-Practices

Doctor warnt, wenn der Gateway-Service auf Bun oder einem Version-Manager-Node-Pfad läuft (nvm, fnm, volta, asdf, etc.). WhatsApp + Telegram Channels erfordern Node, und Version-Manager-Pfade können nach Upgrades brechen, weil der Service dein Shell-Init nicht lädt. Doctor bietet an, zu einer System-Node-Installation zu migrieren, wenn verfügbar (Homebrew/apt/choco).

18) Config-Schreiben + Wizard-Metadaten

Doctor persistiert alle Config-Änderungen und stempelt Wizard-Metadaten, um den Doctor-Lauf aufzuzeichnen.

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

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

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