OpenClaw Doctor: Systemfehler in 2 Minuten beheben

Übersicht

Das OpenClaw-Tool doctor dient als zentrale Anlaufstelle für die Reparatur und Migration deiner Instanz. Es identifiziert veraltete Konfigurationen oder fehlerhafte Zustände, prüft den Systemstatus und schlägt dir konkrete Schritte zur Fehlerbehebung vor.

Funktionsweise von openclaw doctor

Das CLI-Tool analysiert deine lokale Umgebung und vergleicht sie mit den aktuellen Anforderungen von OpenClaw. Wenn du Probleme mit deinem Gateway oder deiner API-Anbindung hast, hilft dir dieser Befehl dabei, die Ursache schnell einzugrenzen.

1. Führe den folgenden Befehl in deinem Terminal aus, um den Diagnoseprozess zu starten:

openclaw doctor

2. Das Tool prüft nun automatisch deine Node.js-Version, die Docker-Konfiguration sowie die Integrität deiner JSON-Dateien.

Fehlerbehebung und Reparatur

Wenn das System Inkonsistenzen feststellt, bietet dir openclaw doctor direkte Korrekturvorschläge an. Diese reichen von der Aktualisierung deiner npm- oder pnpm-Abhängigkeiten bis hin zur Neuinitialisierung von webhook-Endpunkten.

1. Überprüfe die Ausgabe des CLI-Tools auf Warnungen oder Fehlermeldungen.
2. Folge den Anweisungen auf dem Bildschirm, um die vorgeschlagenen Reparaturen anzuwenden.
3. Falls eine automatische Reparatur nicht möglich ist, zeigt dir das Tool den Pfad zur betroffenen Konfigurationsdatei an, damit du diese manuell über GitHub oder deinen lokalen Editor anpassen kannst.

openclaw doctor --yes

Systemprüfung

Die Systemprüfung stellt sicher, dass alle Komponenten korrekt miteinander kommunizieren. Dies ist besonders nützlich, wenn du Änderungen an deinem Gateway vorgenommen hast oder neue webhook-Integrationen testen möchtest.

1. Nutze den folgenden Befehl, um einen detaillierten Bericht über den Zustand deiner OpenClaw-Installation zu erhalten:

openclaw doctor --verbose

2. Achte besonders auf die Statusmeldungen zu deinen API-Schlüsseln und der Docker-Container-Verfügbarkeit.

AI Setup Assistant

Schnelleinstieg

Um sicherzustellen, dass deine Umgebung korrekt konfiguriert ist, kannst du den OpenClaw CLI Diagnosebefehl ausführen. Dieser prüft deine Installation und gibt dir direktes Feedback zu möglichen Problemen.

openclaw doctor

Headless / Automatisierung

Wenn du OpenClaw in einer automatisierten Umgebung wie einer CI/CD-Pipeline oder einem Docker-Container nutzt, kannst du den Diagnoseprozess ohne manuelle Eingaben steuern. Diese Befehle helfen dir dabei, den Status deiner API-Verbindungen und des Gateway-Setups effizient zu verwalten.

1. Führe den Befehl mit dem --yes Flag aus, um Standardeinstellungen ohne Rückfragen zu akzeptieren, einschließlich notwendiger Neustarts oder Reparaturen von Diensten.

openclaw doctor --yes

2. Nutze das --repair Flag, um empfohlene Korrekturen automatisch anzuwenden, sofern diese als sicher eingestuft sind.

openclaw doctor --repair

3. Verwende --repair --force, wenn du aggressive Reparaturen erzwingen möchtest, was beispielsweise benutzerdefinierte Supervisor-Konfigurationen überschreibt.

openclaw doctor --repair --force

4. Mit --non-interactive führst du den Prozess ohne Eingabeaufforderungen aus und wendest nur sichere Migrationen an, wie etwa die Normalisierung der JSON-Konfiguration. Aktionen, die eine menschliche Bestätigung erfordern, werden hierbei übersprungen.

openclaw doctor --non-interactive

5. Der --deep Befehl scannt deine Systemdienste gezielt nach zusätzlichen Gateway-Installationen, etwa in launchd, systemd oder schtasks.

openclaw doctor --deep

Falls du die Änderungen überprüfen möchtest, bevor sie geschrieben werden, kannst du dir die Konfigurationsdatei direkt anzeigen lassen:

cat ~/.openclaw/openclaw.json

Funktionsübersicht von OpenClaw

OpenClaw führt bei jedem Start eine Reihe von automatisierten Prüfungen durch, um sicherzustellen, dass deine Umgebung korrekt konfiguriert ist und alle Dienste reibungslos funktionieren. Diese Funktionen decken die Systemintegrität, die Migration von Konfigurationsdateien sowie die Überwachung deiner Gateway-Instanz ab.

Vorab-Updates und Systemprüfungen

Bevor der eigentliche Prozess startet, führt OpenClaw eine Reihe von Integritätsprüfungen durch, um die Stabilität der Umgebung zu gewährleisten. Dies umfasst sowohl die Aktualisierung von Git-Installationen als auch die Überprüfung des UI-Protokolls.

1. Optionale Vorab-Updates für Git-Installationen (nur im interaktiven Modus).
2. Prüfung der Aktualität des UI-Protokolls (erstellt die Control UI neu, wenn das Protokollschema neuer ist).
3. Integritätsprüfung und Aufforderung zum Neustart bei Fehlern.
4. Zusammenfassung des Status deiner Skills (berechtigt/fehlend/blockiert) sowie der Plugins.

Konfigurationsmigration und Bereinigung

Um sicherzustellen, dass ältere Setups mit aktuellen Versionen kompatibel bleiben, führt OpenClaw eine automatische Normalisierung deiner Konfigurationsdateien durch. Dabei werden veraltete Strukturen in das aktuelle Format überführt.

1. Normalisierung der Konfiguration für veraltete Werte.
2. Migration der Talk-Konfiguration von alten flachen talk.* Feldern zu talk.provider und talk.providers.<provider>.
3. Browser-Migrationsprüfungen für alte Chrome-Erweiterungskonfigurationen und die Chrome MCP-Bereitschaft.
4. Warnungen bei Überschreibungen durch den OpenCode-Provider (models.providers.opencode / models.providers.opencode-go).
5. Warnungen bei Shadowing durch Codex OAuth (models.providers.openai-codex).
6. Prüfung der OAuth TLS-Voraussetzungen für OpenAI Codex OAuth-Profile.

Migration von Zuständen und Verträgen

OpenClaw kümmert sich um die Konsistenz deiner lokalen Daten, indem es alte Speicherstrukturen und Manifest-Verträge aktualisiert. Dies verhindert Konflikte bei der Nutzung von Plugins und Session-Daten.

1. Migration von veralteten Zuständen auf der Festplatte (Sessions/Agent-Verzeichnis/WhatsApp-Authentifizierung).
2. Migration der veralteten Plugin-Manifest-Vertragsschlüssel (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
3. Migration des veralteten Cron-Speichers (jobId, schedule.cron, übergeordnete Delivery/Payload-Felder, Payload provider, einfache notify: true webhook Fallback-Jobs).

Integrität und Berechtigungen

Damit deine Anwendung sicher läuft, überprüft OpenClaw die Dateiberechtigungen und den Status deiner Sessions. Dies ist besonders bei lokalen Installationen wichtig, um unbefugten Zugriff zu verhindern.

1. Überprüfung der Session-Lock-Datei und Bereinigung veralteter Locks.
2. Prüfung der Zustandsintegrität und Berechtigungen (Sessions, Transkripte, Zustandsverzeichnis).
3. Prüfung der Berechtigungen der Konfigurationsdatei (chmod 600) bei lokaler Ausführung.
4. Überprüfung der Modell-Authentifizierung (prüft OAuth-Ablauf, kann ablaufende Tokens aktualisieren und meldet den Status von Auth-Profilen).

Gateway und Laufzeitumgebung

Die Überwachung des Gateway ist essenziell für den Betrieb von OpenClaw. Das System erkennt automatisch, ob Dienste korrekt installiert sind, ob Port-Konflikte vorliegen oder ob die Laufzeitumgebung optimiert werden muss.

1. Erkennung zusätzlicher Arbeitsverzeichnisse (~/openclaw).
2. Reparatur des Sandbox-Images, wenn das Sandboxing aktiviert ist.
3. Migration veralteter Dienste und Erkennung zusätzlicher Gateway-Instanzen.
4. Migration des veralteten Matrix-Kanal-Zustands (im --fix / --repair Modus).
5. Laufzeitprüfungen für das Gateway (Dienst installiert, aber nicht aktiv; zwischengespeichertes launchd-Label).
6. Warnungen zum Kanalstatus (abgefragt vom laufenden Gateway).
7. Audit der Supervisor-Konfiguration (launchd/systemd/schtasks) mit optionaler Reparatur.
8. Best-Practice-Prüfungen für die Gateway-Laufzeit (Node.js vs Bun, Pfade des Version-Managers).
9. Diagnose von Port-Kollisionen beim Gateway (Standard 18789).

Sicherheit und Systemintegration

Abschließend stellt OpenClaw sicher, dass deine Sicherheitsrichtlinien eingehalten werden und die Systemintegration (wie Shell-Completion oder Speicher-Embeddings) korrekt konfiguriert ist.

1. Sicherheitswarnungen für offene DM-Richtlinien.
2. Gateway-Authentifizierungsprüfungen für den lokalen Token-Modus (bietet Token-Generierung an, wenn keine Token-Quelle existiert; überschreibt keine Token SecretRef-Konfigurationen).
3. Erkennung von Problemen beim Geräte-Pairing (ausstehende erstmalige Pairing-Anfragen, ausstehende Rollen-/Scope-Upgrades, Drift des lokalen Geräte-Token-Caches und Drift der Pairing-Datensatz-Authentifizierung).
4. Systemd-Linger-Prüfung unter Linux.
5. Prüfung der Dateigröße der Arbeitsbereich-Bootstrap-Datei (Warnungen bei Kürzung/nahe am Limit für Kontextdateien).
6. Statusprüfung der Shell-Completion und automatische Installation/Aktualisierung.
7. Prüfung der Bereitschaft des Embedding-Providers für die Speichersuche (lokales Modell, Remote-API-Schlüssel oder QMD-Binärdatei).
8. Prüfungen der Quellcode-Installation (pnpm-Workspace-Fehlanpassung, fehlende UI-Assets, fehlende tsx-Binärdatei).
9. Schreiben der aktualisierten Konfiguration und der Wizard-Metadaten.

AI Setup Assistant

Dreams UI Backfill und Reset

Die Control UI Dreams-Szene enthält die Aktionen Backfill, Reset und Clear Grounded für den Grounded-Dreaming-Workflow. Diese Aktionen nutzen RPC-Methoden im Gateway-Doctor-Stil, sind jedoch kein Bestandteil der openclaw doctor CLI-Reparatur oder -Migration.

Was diese Aktionen bewirken:

1. Backfill durchsucht historische memory/YYYY-MM-DD.md-Dateien im aktiven Workspace, führt den Grounded REM-Tagebuch-Durchlauf aus und schreibt umkehrbare Backfill-Einträge in die DREAMS.md.
2. Reset entfernt ausschließlich diese markierten Backfill-Tagebucheinträge aus der DREAMS.md.
3. Clear Grounded entfernt nur die bereitgestellten, kurzfristigen Grounded-Einträge, die aus der historischen Wiedergabe stammen und noch keine Live-Erinnerung oder tägliche Unterstützung angesammelt haben.

Was diese Aktionen von sich aus nicht tun:

1. Sie bearbeiten nicht die MEMORY.md.
2. Sie führen keine vollständigen Doctor-Migrationen aus.
3. Sie stufen Grounded-Kandidaten nicht automatisch in den Live-Kurzzeit-Promotionsspeicher hoch, es sei denn, du führst explizit zuerst den bereitgestellten CLI-Pfad aus.

Wenn du möchtest, dass die Grounded-Wiedergabe der Historie die normale Deep-Promotion-Spur beeinflusst, verwende stattdessen den CLI-Ablauf:

openclaw memory rem-backfill --path ./memory --stage-short-term

Dies stuft Grounded-Durable-Kandidaten in den Kurzzeit-Dreaming-Speicher ein, während die DREAMS.md weiterhin als Oberfläche für deine Überprüfung dient.

Detailliertes Verhalten und Begründung

0) Optionale Aktualisierung (git-Installationen)

Wenn es sich um einen git-Checkout handelt und der doctor interaktiv ausgeführt wird, bietet er an, vor dem Ausführen des doctor-Checks ein Update (fetch/rebase/build) durchzuführen.

1) Konfigurationsnormalisierung

Wenn die Konfiguration veraltete Werteformate enthält (zum Beispiel messages.ackReaction ohne kanalspezifische Überschreibung), normalisiert der doctor diese in das aktuelle Schema.

Dies umfasst auch veraltete Talk-Flachfelder. Die aktuelle öffentliche Talk-Konfiguration besteht aus talk.provider + talk.providers.<provider>. Der doctor schreibt alte talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey Formate in die Provider-Map um.

2) Migrationen veralteter Konfigurationsschlüssel

Wenn die Konfiguration veraltete Schlüssel enthält, verweigern andere Befehle den Dienst und fordern dich auf, openclaw doctor auszuführen.

Der doctor wird:

1. Erklären, welche veralteten Schlüssel gefunden wurden.
2. Die angewendete Migration anzeigen.
3. ~/.openclaw/openclaw.json mit dem aktualisierten Schema neu schreiben.

Das Gateway führt beim Start ebenfalls automatisch doctor-Migrationen aus, wenn es ein veraltetes Konfigurationsformat erkennt, sodass veraltete Konfigurationen ohne manuelles Eingreifen repariert werden. Migrationen des Cron-Job-Speichers werden über openclaw doctor --fix abgewickelt.

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
• legacy talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + talk.providers.<provider>
• routing.agentToAgent → tools.agentToAgent
• routing.transcribeAudio → tools.media.audio.models
• messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
• channels.discord.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.<provider>
• channels.discord.accounts.<id>.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.accounts.<id>.voice.tts.providers.<provider>
• plugins.entries.voice-call.config.tts.<provider> (openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.<provider>
• plugins.entries.voice-call.config.provider: "log" → "mock"
• plugins.entries.voice-call.config.twilio.from → plugins.entries.voice-call.config.fromNumber
• plugins.entries.voice-call.config.streaming.sttProvider → plugins.entries.voice-call.config.streaming.provider
• plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold → plugins.entries.voice-call.config.streaming.providers.openai.*
• bindings[].match.accountID → bindings[].match.accountId
• Für Kanäle mit benannten accounts, aber verbleibenden Single-Account-Werten auf oberster Ebene, werden diese kontospezifischen Werte in das für diesen Kanal gewählte bevorzugte Konto verschoben (accounts.default für die meisten Kanäle; Matrix kann ein bestehendes passendes benanntes/Standard-Ziel beibehalten)
• 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
• browser.profiles.*.driver: "extension" → "existing-session"
• remove browser.relayBindHost (legacy extension relay setting)

Doctor-Warnungen enthalten auch Anleitungen zu Konto-Standards für Kanäle mit mehreren Konten:

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

2b) OpenCode Provider-Überschreibungen

Wenn du models.providers.opencode, opencode-zen oder opencode-go manuell hinzugefügt hast, überschreibt dies den integrierten OpenCode-Katalog von @mariozechner/pi-ai. Dies kann Modelle auf die falsche API zwingen oder Kosten auf Null setzen. Der doctor warnt dich, damit du die Überschreibung entfernen und das modellbasierte API-Routing + Kosten wiederherstellen kannst.

2c) Browser-Migration und Chrome MCP-Bereitschaft

Wenn deine Browser-Konfiguration noch auf den entfernten Chrome-Erweiterungspfad zeigt, normalisiert der doctor sie auf das aktuelle host-lokale Chrome MCP-Attach-Modell:

1. browser.profiles.*.driver: "extension" wird zu "existing-session"
2. browser.relayBindHost wird entfernt

Der doctor prüft auch den host-lokalen Chrome MCP-Pfad, wenn du defaultProfile: "user" oder ein konfiguriertes existing-session-Profil verwendest:

1. Er prüft, ob Google Chrome auf demselben Host für standardmäßige Auto-Connect-Profile installiert ist.
2. Er prüft die erkannte Chrome-Version und warnt, wenn sie unter Chrome 144 liegt.
3. Er erinnert dich daran, das Remote-Debugging auf der Browser-Inspektionsseite zu aktivieren (zum Beispiel chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging oder edge://inspect/#remote-debugging).

Der doctor kann die Chrome-seitige Einstellung nicht für dich aktivieren. Host-lokales Chrome MCP erfordert weiterhin:

1. Einen Chromium-basierten Browser 144+ auf dem Gateway/Node-Host.
2. Den lokal laufenden Browser.
3. Aktiviertes Remote-Debugging im Browser.
4. Die Bestätigung der ersten Attach-Zustimmungsaufforderung im Browser.

Die Bereitschaft bezieht sich hier nur auf lokale Attach-Voraussetzungen. existing-session behält die aktuellen Chrome MCP-Routenlimits bei; fortgeschrittene Routen wie responsebody, PDF-Export, Download-Interzeption und Batch-Aktionen erfordern weiterhin einen verwalteten Browser oder ein rohes CDP-Profil.

Diese Prüfung gilt nicht für Docker, Sandbox, Remote-Browser oder andere Headless-Flows. Diese verwenden weiterhin rohes CDP.

2d) OAuth TLS-Voraussetzungen

Wenn ein OpenAI Codex OAuth-Profil konfiguriert ist, prüft der doctor den OpenAI-Autorisierungsendpunkt, um sicherzustellen, dass der lokale Node/OpenSSL TLS-Stack die Zertifikatskette validieren kann. Wenn die Prüfung mit einem Zertifikatsfehler fehlschlägt (zum Beispiel UNABLE_TO_GET_ISSUER_CERT_LOCALLY, abgelaufenes Zertifikat oder selbstsigniertes Zertifikat), gibt der doctor plattformspezifische Korrekturanleitungen aus. Unter macOS mit einem Homebrew Node ist die Lösung meist brew postinstall ca-certificates. Mit --deep wird die Prüfung auch dann ausgeführt, wenn das Gateway gesund ist.

2c) Codex OAuth Provider-Überschreibungen

Wenn du zuvor veraltete OpenAI-Transporteinstellungen unter models.providers.openai-codex hinzugefügt hast, können diese den integrierten Codex OAuth-Provider-Pfad verdecken, den neuere Releases automatisch verwenden. Der doctor warnt, wenn er diese alten Transporteinstellungen zusammen mit Codex OAuth sieht, damit du die veraltete Transport-Überschreibung entfernen oder umschreiben kannst, um das integrierte Routing/Fallback-Verhalten zurückzuerhalten. Benutzerdefinierte Proxys und reine Header-Überschreibungen werden weiterhin unterstützt und lösen diese Warnung nicht aus.

3) Migrationen veralteter Zustände (Festplattenlayout)

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

• Sitzungsspeicher + Transkripte:
  • von ~/.openclaw/sessions/ zu ~/.openclaw/agents/<agentId>/sessions/
• Agent-Verzeichnis:
  • von ~/.openclaw/agent/ zu ~/.openclaw/agents/<agentId>/agent/
• WhatsApp-Authentifizierungsstatus (Baileys):
  • von veraltetem ~/.openclaw/credentials/*.json (außer oauth.json)
  • zu ~/.openclaw/credentials/whatsapp/<accountId>/... (Standard-Konto-ID: default)

Diese Migrationen sind “best-effort” und idempotent; der doctor gibt Warnungen aus, wenn er veraltete Ordner als Backups zurücklässt. Das Gateway/CLI migriert die veralteten Sitzungen + das Agent-Verzeichnis beim Start ebenfalls automatisch, sodass Verlauf/Auth/Modelle ohne manuellen doctor-Lauf im agentenspezifischen Pfad landen. Die WhatsApp-Authentifizierung wird absichtlich nur über openclaw doctor migriert. Die Normalisierung der Talk-Provider/Provider-Map vergleicht nun nach struktureller Gleichheit, sodass Unterschiede, die nur die Schlüsselreihenfolge betreffen, keine wiederholten, wirkungslosen doctor --fix-Änderungen mehr auslösen.

3a) Migrationen veralteter Plugin-Manifeste

Der doctor scannt alle installierten Plugin-Manifeste nach veralteten Capability-Schlüsseln auf oberster Ebene (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders). Wenn diese gefunden werden, bietet er an, sie in das contracts-Objekt zu verschieben und die Manifest-Datei direkt zu überschreiben. Diese Migration ist idempotent; wenn der contracts-Schlüssel bereits dieselben Werte enthält, wird der veraltete Schlüssel entfernt, ohne die Daten zu duplizieren.

3b) Migrationen veralteter Cron-Speicher

Der doctor prüft auch den Cron-Job-Speicher (~/.openclaw/cron/jobs.json standardmäßig, oder cron.store bei Überschreibung) auf alte Job-Formate, die der Scheduler aus Kompatibilitätsgründen noch akzeptiert.

Aktuelle Cron-Bereinigungen umfassen:

• jobId → id
• schedule.cron → schedule.expr
• Payload-Felder auf oberster Ebene (message, model, thinking, …) → payload
• Zustellungsfelder auf oberster Ebene (deliver, channel, to, provider, …) → delivery
• Payload provider Zustellungs-Aliase → explizite delivery.channel
• einfache veraltete notify: true Webhook-Fallback-Jobs → explizite delivery.mode="webhook" mit delivery.to=cron.webhook

Der doctor migriert notify: true-Jobs nur dann automatisch, wenn dies ohne Verhaltensänderung möglich ist. Wenn ein Job veraltetes Notify-Fallback mit einem bestehenden Nicht-Webhook-Zustellungsmodus kombiniert, warnt der doctor und überlässt diesen Job der manuellen Überprüfung.

3c) Bereinigung von Sitzungssperren

Der doctor scannt jedes Agent-Sitzungsverzeichnis nach veralteten Schreibsperrdateien — Dateien, die zurückbleiben, wenn eine Sitzung abnormal beendet wurde. Für jede gefundene Sperrdatei meldet er: den Pfad, die PID, ob die PID noch aktiv ist, das Alter der Sperre und ob sie als veraltet gilt (tote PID oder älter als 30 Minuten). Im --fix / --repair-Modus entfernt er veraltete Sperrdateien automatisch; andernfalls druckt er einen Hinweis und weist dich an, den Befehl mit --fix erneut auszuführen.

4) Integritätsprüfungen des Zustands (Sitzungspersistenz, Routing und Sicherheit)

Das Zustandsverzeichnis ist der operative Hirnstamm. Wenn es verschwindet, verlierst du Sitzungen, Anmeldedaten, Protokolle und Konfigurationen (sofern du keine Backups an anderer Stelle hast).

Der doctor prüft:

• Zustandsverzeichnis fehlt: warnt vor katastrophalem Zustandsverlust, fordert zum Neuerstellen des Verzeichnisses auf und erinnert daran, dass fehlende Daten nicht wiederhergestellt werden können.
• Berechtigungen des Zustandsverzeichnisses: verifiziert die Schreibbarkeit; bietet Reparatur der Berechtigungen an (und gibt einen chown-Hinweis aus, wenn ein Besitzer/Gruppen-Mismatch erkannt wird).
• macOS cloud-synchronisiertes Zustandsverzeichnis: warnt, wenn der Zustand unter iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) oder ~/Library/CloudStorage/... aufgelöst wird, da synchronisierte Pfade langsamere I/O und Sperr-/Synchronisationskonflikte verursachen können.
• Linux SD- oder eMMC-Zustandsverzeichnis: warnt, wenn der Zustand auf eine mmcblk*-Mount-Quelle aufgelöst wird, da SD- oder eMMC-basierte zufällige I/O langsamer sein und bei Sitzungs- und Anmeldedatenschreibvorgängen schneller verschleißen kann.
• Sitzungsverzeichnisse fehlen: sessions/ und das Sitzungsspeicherverzeichnis sind erforderlich, um den Verlauf beizubehalten und ENOENT-Abstürze zu vermeiden.
• Transkript-Mismatch: warnt, wenn aktuelle Sitzungseinträge fehlende Transkriptdateien aufweisen.
• Hauptsitzung “1-line JSONL”: markiert, wenn das Haupttranskript nur eine Zeile hat (der Verlauf sammelt sich nicht an).
• Mehrere Zustandsverzeichnisse: warnt, wenn mehrere ~/.openclaw-Ordner über Home-Verzeichnisse hinweg existieren oder wenn OPENCLAW_STATE_DIR woanders hin zeigt (der Verlauf kann zwischen Installationen aufgeteilt werden).
• Remote-Modus-Erinnerung: wenn gateway.mode=remote, erinnert dich der doctor daran, ihn auf dem Remote-Host auszuführen (der Zustand liegt dort).
• Berechtigungen der Konfigurationsdatei: warnt, wenn ~/.openclaw/openclaw.json für die Gruppe/Welt lesbar ist und bietet an, dies auf 600 zu verschärfen.

5) Integrität der Modell-Authentifizierung (OAuth-Ablauf)

Der doctor inspiziert OAuth-Profile im Authentifizierungsspeicher, warnt, wenn Token ablaufen/abgelaufen sind, und kann sie aktualisieren, wenn dies sicher ist. Wenn das Anthropic OAuth/Token-Profil veraltet ist, schlägt er einen Anthropic API-Schlüssel oder den Anthropic Setup-Token-Pfad vor. Aktualisierungsaufforderungen erscheinen nur bei interaktiver Ausführung (TTY); --non-interactive überspringt Aktualisierungsversuche.

Wenn eine OAuth-Aktualisierung dauerhaft fehlschlägt (zum Beispiel refresh_token_reused, invalid_grant oder ein Provider, der dich auffordert, dich erneut anzumelden), meldet der doctor, dass eine erneute Authentifizierung erforderlich ist, und druckt den genauen openclaw models auth login --provider ... Befehl zum Ausführen.

Der doctor meldet auch Authentifizierungsprofile, die vorübergehend unbrauchbar sind aufgrund von:

• kurzen Abklingzeiten (Ratenbegrenzungen/Timeouts/Authentifizierungsfehler)
• längeren Deaktivierungen (Abrechnungs-/Kreditfehler)

6) Validierung des Hooks-Modells

Wenn hooks.gmail.model gesetzt ist, validiert der doctor die Modellreferenz gegen den Katalog und die Zulassungsliste und warnt, wenn sie nicht aufgelöst werden kann oder nicht zulässig ist.

7) Reparatur von Sandbox-Images

Wenn Sandboxing aktiviert ist, prüft der doctor Docker-Images und bietet an, sie zu erstellen oder zu veralteten Namen zu wechseln, wenn das aktuelle Image fehlt.

7b) Laufzeitabhängigkeiten gebündelter Plugins

Der doctor verifiziert Laufzeitabhängigkeiten nur für gebündelte Plugins, die in der aktuellen Konfiguration aktiv sind oder durch ihr gebündeltes Manifest-Standardverhalten aktiviert wurden, zum Beispiel plugins.entries.discord.enabled: true, veraltetes channels.discord.enabled: true oder ein standardmäßig aktivierter gebündelter Provider. Wenn welche fehlen, meldet der doctor die Pakete und installiert sie im openclaw doctor --fix / openclaw doctor --repair-Modus. Externe Plugins verwenden weiterhin openclaw plugins install / openclaw plugins update; der doctor installiert keine Abhängigkeiten für beliebige Plugin-Pfade.

8) Migrationen des Gateway-Dienstes und Bereinigungshinweise

Der doctor erkennt veraltete Gateway-Dienste (launchd/systemd/schtasks) und bietet an, sie zu entfernen und den OpenClaw-Dienst unter Verwendung des aktuellen Gateway-Ports zu installieren. Er kann auch nach zusätzlichen Gateway-ähnlichen Diensten suchen und Bereinigungshinweise drucken. Profilbenannte OpenClaw-Gateway-Dienste gelten als erstklassig und werden nicht als “extra” markiert.

8b) Matrix-Start-Migration

Wenn ein Matrix-Kanal-Konto eine ausstehende oder ausführbare veraltete Zustandsmigration hat, erstellt der doctor (im --fix / --repair-Modus) einen Snapshot vor der Migration und führt dann die Best-Effort-Migrationsschritte aus: veraltete Matrix-Zustandsmigration und Vorbereitung des veralteten verschlüsselten Zustands. Beide Schritte sind nicht fatal; Fehler werden protokolliert und der Start wird fortgesetzt. Im schreibgeschützten Modus (openclaw doctor ohne --fix) wird diese Prüfung vollständig übersprungen.

8c) Gerätekopplung und Authentifizierungsdrift

Der doctor inspiziert nun den Gerätekopplungsstatus als Teil des normalen Gesundheitschecks.

Was er meldet:

• ausstehende erstmalige Kopplungsanfragen
• ausstehende Rollen-Upgrades für bereits gekoppelte Geräte
• ausstehende Scope-Upgrades für bereits gekoppelte Geräte
• Reparaturen bei Public-Key-Mismatch, bei denen die Geräte-ID noch übereinstimmt, die Geräteidentität aber nicht mehr mit dem genehmigten Datensatz übereinstimmt
• gekoppelte Datensätze, denen ein aktives Token für eine genehmigte Rolle fehlt
• gekoppelte Token, deren Scopes von der genehmigten Kopplungsbasis abweichen
• lokal zwischengespeicherte Gerätetoken-Einträge für die aktuelle Maschine, die vor einer Gateway-seitigen Token-Rotation liegen oder veraltete Scope-Metadaten enthalten

Der doctor genehmigt Kopplungsanfragen nicht automatisch und rotiert Gerätetoken nicht automatisch. Er druckt stattdessen die genauen nächsten Schritte:

• ausstehende Anfragen mit openclaw devices list inspizieren
• die genaue Anfrage mit openclaw devices approve <requestId> genehmigen
• ein neues Token mit openclaw devices rotate --device <deviceId> --role <role> rotieren
• einen veralteten Datensatz mit openclaw devices remove <deviceId> entfernen

Dies schließt die häufige Lücke “bereits gekoppelt, aber immer noch Kopplung erforderlich”: der doctor unterscheidet nun zwischen erstmaliger Kopplung, ausstehenden Rollen-/Scope-Upgrades und veralteter Token-/Geräteidentitätsdrift.

9) Sicherheitswarnungen

Der doctor gibt Warnungen aus, wenn ein Provider ohne Zulassungsliste für DMs offen ist oder wenn eine Richtlinie auf gefährliche Weise konfiguriert ist.

10) systemd linger (Linux)

Wenn der Dienst als systemd-Benutzerdienst ausgeführt wird, stellt der doctor sicher, dass “linger” aktiviert ist, damit das Gateway nach dem Logout aktiv bleibt.

11) Arbeitsbereichsstatus (Skills, Plugins und veraltete Verzeichnisse)

Der doctor druckt eine Zusammenfassung des Arbeitsbereichsstatus für den Standard-Agenten:

• Skills-Status: zählt berechtigte, Anforderungen vermissende und durch Zulassungslisten blockierte Skills.
• Veraltete Arbeitsbereichsverzeichnisse: warnt, wenn ~/openclaw oder andere veraltete Arbeitsbereichsverzeichnisse neben dem aktuellen Arbeitsbereich existieren.
• Plugin-Status: zählt geladene/deaktivierte/fehlerhafte Plugins; listet Plugin-IDs für Fehler auf; meldet Fähigkeiten gebündelter Plugins.
• Plugin-Kompatibilitätswarnungen: markiert Plugins, die Kompatibilitätsprobleme mit der aktuellen Laufzeit haben.
• Plugin-Diagnose: zeigt alle Warnungen oder Fehler beim Laden an, die von der Plugin-Registry ausgegeben werden.

11b) Bootstrap-Dateigröße

Der doctor prüft, ob Bootstrap-Dateien des Arbeitsbereichs (zum Beispiel AGENTS.md, CLAUDE.md oder andere injizierte Kontextdateien) nahe oder über dem konfigurierten Zeichenbudget liegen. Er meldet pro Datei die rohen vs. injizierten Zeichenanzahlen, den Prozentsatz der Kürzung, die Ursache der Kürzung (max/file oder max/total) und die gesamten injizierten Zeichen als Bruchteil des Gesamtbudgets. Wenn Dateien gekürzt werden oder nahe am Limit sind, druckt der doctor Tipps zur Anpassung von agents.defaults.bootstrapMaxChars und agents.defaults.bootstrapTotalMaxChars.

11c) Shell-Vervollständigung

Der doctor prüft, ob die Tab-Vervollständigung für die aktuelle Shell (zsh, bash, fish oder PowerShell) installiert ist:

• Wenn das Shell-Profil ein langsames dynamisches Vervollständigungsmuster verwendet (source <(openclaw completion ...)), aktualisiert der doctor es auf die schnellere zwischengespeicherte Dateivariante.
• Wenn die Vervollständigung im Profil konfiguriert ist, aber die Cache-Datei fehlt, regeneriert der doctor den Cache automatisch.
• Wenn gar keine Vervollständigung konfiguriert ist, fordert der doctor zur Installation auf (nur interaktiver Modus; mit --non-interactive übersprungen).

Führe openclaw completion --write-state aus, um den Cache manuell zu regenerieren.

12) Gateway-Authentifizierungsprüfungen (lokales Token)

Der doctor prüft die Bereitschaft der lokalen Gateway-Token-Authentifizierung.

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

12b) Schreibgeschützte SecretRef-bewusste Reparaturen

Einige Reparaturabläufe müssen konfigurierte Anmeldedaten inspizieren, ohne das Fail-Fast-Verhalten der Laufzeit zu schwächen.

• openclaw doctor --fix verwendet nun dasselbe schreibgeschützte SecretRef-Zusammenfassungsmodell wie Status-Befehle für gezielte Konfigurationsreparaturen.
• Beispiel: Die Telegram allowFrom / groupAllowFrom @username Reparatur versucht, konfigurierte Bot-Anmeldedaten zu verwenden, wenn verfügbar.
• Wenn das Telegram-Bot-Token über SecretRef konfiguriert, aber im aktuellen Befehlspfad nicht verfügbar ist, meldet der doctor, dass die Anmeldedaten konfiguriert, aber nicht verfügbar sind, und überspringt die automatische Auflösung, anstatt abzustürzen oder das Token fälschlicherweise als fehlend zu melden.

13) Gateway-Gesundheitscheck + Neustart

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

13b) Bereitschaft der Speichersuche

Der doctor prüft, ob der konfigurierte Provider für die Speichersuche-Einbettung für den Standard-Agenten bereit ist. Das Verhalten hängt vom konfigurierten Backend und Provider ab:

• QMD-Backend: prüft, ob die qmd-Binärdatei verfügbar und startbar ist. Wenn nicht, druckt er Korrekturanleitungen einschließlich des npm-Pakets und einer Option für einen manuellen Binärpfad.
• Expliziter lokaler Provider: prüft auf eine lokale Modelldatei oder eine erkannte Remote-/downloadbare Modell-URL. Wenn diese fehlen, schlägt er den Wechsel zu einem Remote-Provider vor.
• Expliziter Remote-Provider (openai, voyage usw.): verifiziert, dass ein API-Schlüssel in der Umgebung oder im Authentifizierungsspeicher vorhanden ist. Druckt umsetzbare Korrekturhinweise, falls dieser fehlt.
• Auto-Provider: prüft zuerst die lokale Modellverfügbarkeit, dann versucht er jeden Remote-Provider in der Reihenfolge der automatischen Auswahl.

Wenn ein Gateway-Prüfergebnis verfügbar ist (Gateway war zum Zeitpunkt der Prüfung gesund), vergleicht der doctor dessen Ergebnis mit der CLI-sichtbaren Konfiguration und notiert jede Diskrepanz.

Verwende openclaw memory status --deep, um die Einbettungsbereitschaft zur Laufzeit zu verifizieren.

14) Warnungen zum Kanalstatus

Wenn das Gateway gesund ist, führt der doctor eine Kanalstatusprüfung durch und meldet Warnungen mit vorgeschlagenen Korrekturen.

15) Prüfung + Reparatur der Supervisor-Konfiguration

Der doctor prüft die installierte Supervisor-Konfiguration (launchd/systemd/schtasks) auf fehlende oder veraltete Standards (z. B. systemd network-online-Abhängigkeiten und Neustartverzögerung). Wenn er eine Diskrepanz findet, empfiehlt er ein Update und kann die Dienstdatei/Aufgabe auf die aktuellen Standards umschreiben.

Hinweise:

• openclaw doctor fragt vor dem Umschreiben der Supervisor-Konfiguration nach.
• openclaw doctor --yes akzeptiert die Standard-Reparaturaufforderungen.
• openclaw doctor --repair wendet empfohlene Korrekturen ohne Aufforderungen an.
• openclaw doctor --repair --force überschreibt benutzerdefinierte Supervisor-Konfigurationen.
• Wenn die Token-Authentifizierung ein Token erfordert und gateway.auth.token SecretRef-verwaltet ist, validiert die Dienstinstallation/-reparatur des Doctors die SecretRef, speichert aufgelöste Klartext-Token-Werte jedoch nicht in den Umgebungsmetadaten des Supervisor-Dienstes.
• Wenn die Token-Authentifizierung ein Token erfordert und die konfigurierte Token-SecretRef nicht aufgelöst ist, blockiert der doctor den Installations-/Reparaturpfad mit umsetzbaren Anleitungen.
• Wenn sowohl gateway.auth.token als auch gateway.auth.password konfiguriert sind und gateway.auth.mode nicht gesetzt ist, blockiert der doctor die Installation/Reparatur, bis der Modus explizit gesetzt ist.
• Für Linux-Benutzer-systemd-Einheiten enthalten die Token-Drift-Prüfungen des Doctors nun sowohl Environment= als auch EnvironmentFile= Quellen beim Vergleich der Dienst-Authentifizierungsmetadaten.
• Du kannst ein vollständiges Umschreiben jederzeit über openclaw gateway install --force erzwingen.

16) Gateway-Laufzeit + Port-Diagnose

Der doctor inspiziert die Dienstlaufzeit (PID, letzter Exit-Status) und warnt, wenn der Dienst installiert, aber nicht tatsächlich ausgeführt wird. Er prüft auch auf Port-Kollisionen auf dem Gateway-Port (Standard 18789) und meldet wahrscheinliche Ursachen (Gateway läuft bereits, SSH-Tunnel).

17) Best Practices für die Gateway-Laufzeit

Der doctor warnt, wenn der Gateway-Dienst auf Bun oder einem versionsverwalteten Node-Pfad (nvm, fnm, volta, asdf usw.) läuft. WhatsApp + Telegram-Kanäle erfordern Node, und Versionsmanager-Pfade können nach Upgrades brechen, da der Dienst deine Shell-Initialisierung nicht lädt. Der doctor bietet an, auf eine System-Node-Installation zu migrieren, wenn verfügbar (Homebrew/apt/choco).

18) Konfigurationsschreiben + Wizard-Metadaten

Der doctor speichert alle Konfigurationsänderungen und stempelt Wizard-Metadaten, um den doctor-Lauf aufzuzeichnen.

19) Tipps zum Arbeitsbereich (Backup + Speichersystem)

Der doctor schlägt ein Arbeitsbereichs-Speichersystem vor, wenn dieses fehlt, und druckt einen Backup-Tipp, falls der Arbeitsbereich noch nicht unter git steht.

Siehe /concepts/agent-workspace für einen vollständigen Leitfaden zur Arbeitsbereichsstruktur und git-Backup (empfohlenes privates GitHub oder GitLab).

AI Setup Assistant