openclaw doctor

Integritätsprüfungen und Schnellkorrekturen für Gateway, Kanäle, Plugins, Skills, Modell-Routing, lokalen Zustand und Konfigurationsmigrationen. Verwenden Sie den Befehl immer dann, wenn etwas nicht wie erwartet funktioniert und Sie mit einem einzigen Befehl herausfinden möchten, wo das Problem liegt.

Verwandte Themen:

• Fehlerbehebung: Fehlerbehebung
• Sicherheitsaudit: Sicherheit

Modi

Doctor verfügt über fünf Modi:

Verwenden Sie vorzugsweise --lint, wenn eine Automatisierung ein stabiles Ergebnis benötigt. Verwenden Sie vorzugsweise --fix, wenn ein menschlicher Operator möchte, dass Doctor die Konfiguration oder den Zustand bearbeitet.

Beispiele

openclaw doctoropenclaw doctor --lintopenclaw doctor --lint --jsonopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --deepopenclaw doctor --fixopenclaw doctor --fix --non-interactiveopenclaw doctor --generate-gateway-tokenopenclaw doctor --post-upgradeopenclaw doctor --post-upgrade --jsonopenclaw doctor --state-sqlite compactopenclaw doctor --state-sqlite compact --jsonopenclaw doctor --session-sqlite inspect --session-sqlite-all-agentsopenclaw doctor --session-sqlite dry-run --session-sqlite-agent main --jsonopenclaw doctor --session-sqlite import --session-sqlite-all-agentsopenclaw doctor --session-sqlite validate --session-sqlite-all-agents --jsonopenclaw doctor --session-sqlite compact --session-sqlite-all-agentsopenclaw doctor --session-sqlite recover --github-issueopenclaw doctor --session-sqlite restore --session-sqlite-all-agents

Verwenden Sie für kanalspezifische Berechtigungen statt doctor die Kanalprüfungen:

openclaw channels capabilities --channel discord --target channel:<channel-id>openclaw channels status --probe

channels capabilities meldet die effektiven Berechtigungen des Bots für ein bestimmtes Kanalziel. channels status --probe prüft alle konfigurierten Kanäle und Ziele für den automatischen Beitritt zu Sprachkanälen.

Optionen

--severity-min, --all, --only und --skip werden nur zusammen mit --lint akzeptiert; --json wird mit --lint, --post-upgrade, --state-sqlite und --session-sqlite akzeptiert.

Lint-Modus

openclaw doctor --lint ist schreibgeschützt: keine Eingabeaufforderungen, keine Reparatur, keine Neuschreibung von Konfiguration oder Zustand.

openclaw doctor --lintopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --jsonopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

Die menschenlesbare Ausgabe ist kompakt:

doctor --lint: 6 Prüfung(en) ausgeführt, 1 Befund(e)  [warning] core/doctor/gateway-config gateway.mode - gateway.mode ist nicht festgelegt; der Start des Gateways wird blockiert.    Behebung: Führen Sie `openclaw configure` aus und legen Sie den Gateway-Modus (local/remote) fest oder führen Sie `openclaw config set gateway.mode local` aus.

Die JSON-Ausgabe ist die Schnittstelle für Skripte:

{  "ok": false,  "checksRun": 5,  "checksSkipped": 0,  "findings": [    {      "checkId": "core/doctor/gateway-config",      "severity": "warning",      "message": "gateway.mode ist nicht festgelegt; der Start des Gateways wird blockiert.",      "path": "gateway.mode",      "fixHint": "Führen Sie `openclaw configure` aus und legen Sie den Gateway-Modus (local/remote) fest oder führen Sie `openclaw config set gateway.mode local` aus."    }  ]}

Exit-Codes:

--severity-min steuert sowohl, welche Befunde ausgegeben werden, als auch den Exit-Schwellenwert: openclaw doctor --lint --severity-min error kann nichts ausgeben und mit 0 beendet werden, selbst wenn Befunde mit niedrigerem Schweregrad info/warning vorhanden sind.

--all steuert, welche Prüfungen vor der Filterung nach Schweregrad ausgewählt werden. Der standardmäßige Lint-Durchlauf schließt Prüfungen aus, die tiefgreifend oder historisch sind oder mit höherer Wahrscheinlichkeit reparierbare Altlasten aufdecken; verwenden Sie --all für das vollständige Inventar. --only <id> ist der präziseste Selektor und kann jede registrierte Prüfung anhand ihrer ID ausführen.

core/doctor/local-audio-acceleration meldet den automatisch ausgewählten lokalen STT-Befehl, getrennte Nachweise für geeignete/angeforderte/beobachtete Backends sowie die Fallback-Reihenfolge, ohne ein Sprachmodell zu laden. Die Prüfung erzeugt einen informativen Befund; geben Sie daher --severity-min info an, um ihn anzuzeigen.

Strukturierte Zustandsprüfungen

Moderne Doctor-Prüfungen verwenden einen kleinen zweigeteilten Vertrag:

detect(ctx, scope?) -> HealthFinding[]repair?(ctx, findings) -> HealthRepairResult

detect() bildet die Grundlage für doctor --lint. repair() ist optional und wird nur unter doctor --fix / doctor --repair ausgeführt. Prüfungen, die noch nicht auf diese Form migriert wurden, verwenden weiterhin den bisherigen Doctor-Beitragsablauf.

Reparaturkontexte können dryRun-/diff-Anforderungen enthalten; Reparaturergebnisse können strukturierte diffs (Konfigurations-/Dateiänderungen) und effects (Dienst-, Prozess-, Paket-, Zustands- oder andere Nebeneffekte) zurückgeben, sodass konvertierte Prüfungen schrittweise doctor --fix --dry-run unterstützen können, ohne die Planung von Änderungen in detect() zu verlagern.

repair() meldet status: "repaired" | "skipped" | "failed" (ein nicht angegebener Status bedeutet repaired). Wenn die Reparatur skipped oder failed zurückgibt, meldet Doctor den Grund und überspringt die Validierung für diese Prüfung. Nach einer erfolgreichen Reparatur führt Doctor detect() erneut aus, beschränkt auf die reparierten Befunde. Ist der Befund weiterhin vorhanden, meldet Doctor eine Reparaturwarnung, statt die Änderung als abgeschlossen zu behandeln.

Ein Befund enthält:

Modernisierte Kernprüfungen von Doctor bleiben dem geordneten Doctor-Beitrag zugeordnet, dem ihr für Menschen bestimmtes Verhalten von doctor / doctor --fix gehört. Die gemeinsame strukturierte Zustandsregistrierung ist der Erweiterungspunkt: Gebündelte und Plugin-gestützte Prüfungen werden nach den Kernprüfungen von Doctor ausgeführt, sobald ihr zuständiges Paket sie im aktiven Befehlspfad registriert. openclaw/plugin-sdk/health stellt Plugin-Autoren denselben Vertrag bereit.

Prüfungsauswahl

openclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --skip core/doctor/skills-readinessopenclaw doctor --lint --all --skip core/doctor/session-locks

--only und --skip akzeptieren vollständige Prüfungs-IDs und können wiederholt werden. Wenn eine --only-ID nicht registriert ist, wird für diese ID keine Prüfung ausgeführt; verwenden Sie checksRun/checksSkipped in der Ausgabe, um zu bestätigen, dass ein gezieltes Gate die erwarteten Prüfungen auswählt.

Modus nach einem Upgrade

openclaw doctor --post-upgrade führt Plugin-Kompatibilitätsprüfungen zur Verkettung nach einem Build oder Upgrade aus. Befunde werden auf stdout ausgegeben; der Exit-Code lautet 1, wenn ein Befund level: "error" aufweist. Fügen Sie --json hinzu, um eine maschinenlesbare Hülle ({ probesRun, findings }) zu erhalten, die für CI, das Community-Skill fork-upgrade und andere Smoke-Test-Werkzeuge nach Upgrades geeignet ist. Wenn der Index der installierten Plugins fehlt oder fehlerhaft ist, gibt der JSON-Modus weiterhin die Hülle mit einem Fehlerbefund plugin.index_unavailable aus.

Der Start eines Container-Images bildet die Ausnahme vom üblichen Ablauf „Doctor nach der Aktualisierung ausführen“. Wenn openclaw gateway run mit einer neuen OpenClaw-Version startet, führt es sichere Reparaturen des Zustands und der Plugins aus, bevor es Bereitschaft meldet. Wenn die Reparatur nicht sicher abgeschlossen werden kann, wird der Start beendet und Sie werden angewiesen, dasselbe Image einmal mit openclaw doctor --fix für denselben eingebundenen Zustand/dieselbe eingebundene Konfiguration auszuführen, bevor Sie den Container normal neu starten.

SQLite-Compaction des gemeinsamen Zustands

openclaw doctor --state-sqlite compact ist eine explizite Offline-Wartung für die kanonische Datenbank des gemeinsamen Zustands unter <state-dir>/state/openclaw.sqlite. Der Befehl akzeptiert keinen beliebigen Datenbankpfad, wird im normalen Gateway-Betrieb niemals aufgerufen und ist nicht Bestandteil von openclaw doctor --fix.

Stoppen Sie zuerst das Gateway und erstellen Sie eine verifizierte Sicherung:

openclaw gateway stopopenclaw backup create --verifyopenclaw doctor --state-sqlite compact --jsonopenclaw gateway start

Der Befehl:

1. Erfordert eine reguläre Datei am kanonischen Pfad des gemeinsamen Zustands. Eine fehlende Datenbank wird als skipped gemeldet, und der Befehl wird erfolgreich beendet.
2. Validiert die aktuell unterstützte Schemaversion und schema_meta.role = "global", bevor ein Checkpoint ausgeführt oder die Datei geändert wird.
3. Erfordert ein nicht belegtes wal_checkpoint(TRUNCATE). Stoppen Sie alle verbleibenden OpenClaw- Prozesse und versuchen Sie es erneut, wenn der Checkpoint belegt ist.
4. Setzt auto_vacuum auf INCREMENTAL, führt ein vollständiges VACUUM aus und erstellt erneut einen Checkpoint.
5. Führt quick_check, integrity_check und foreign_key_check aus und wendet anschließend erneut ausschließlich dem Eigentümer gewährte Berechtigungen auf die Datenbank und die SQLite-Sidecar-Dateien an.

Die JSON-Ausgabe meldet die Größen der Datenbank und des WAL, die Seiten der Freelist, die Seitengröße und den auto_vacuum-Wert vor und nach der Compaction sowie die zurückgewonnenen Bytes und die Ergebnisse von quick_check und integrity_check. foreign_key_check wird nach dem Fail-Closed-Prinzip durchgesetzt und besitzt kein separates Erfolgsfeld. SQLite meldet auto_vacuum als 0 für „keines“, 1 für „vollständig“ und 2 für „inkrementell“.

Die Compaction schlägt ohne Änderung fehl, wenn das Schema veraltet oder neuer als der ausgeführte OpenClaw-Build ist oder zu einer Agentendatenbank gehört. Führen Sie bei einem älteren Schema des gemeinsamen Zustands zuerst openclaw doctor --fix aus. Stellen Sie bei einem neueren Schema eine kompatible Sicherung wieder her oder aktualisieren Sie OpenClaw.

SQLite-Migration von Sitzungen

OpenClaw importiert veraltete Sitzungszeilen und den Transkriptverlauf beim Start des Gateway und bei openclaw doctor --fix automatisch in die SQLite-Datenbank jedes Agenten. openclaw doctor --session-sqlite <mode> ist das gezielte Inspektions- und Validierungswerkzeug für diese Migration. Aktuelle Laufzeit- Sitzungszeilen befinden sich in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Veraltete sessions.json-Dateien dienen als Migrationsquellen. Aktive JSONL-Transkriptdateien werden importiert und nach erfolgreichem Import aus dem aktiven Sitzungsverzeichnis archiviert; JSONL-Dateien der Archivstufe bleiben Support-Artefakte und sind keine Laufzeit- Fallbacks.

Modi:

Selektoren:

• Standard: der konfigurierte Speicher des Standardagenten, sofern diese veraltete Speicherdatei vorhanden ist.
• --session-sqlite-agent <id>: ein konfigurierter Agent.
• --session-sqlite-all-agents: konfigurierte Agentenspeicher sowie erkannte Agentenspeicher.
• --session-sqlite-store <path>: ein expliziter Pfad zu einer veralteten sessions.json.

Manuelle Inspektionsabfolge:

openclaw doctor --session-sqlite inspect --session-sqlite-all-agentsopenclaw doctor --session-sqlite dry-run --session-sqlite-all-agents --jsonopenclaw doctor --session-sqlite import --session-sqlite-all-agentsopenclaw doctor --session-sqlite validate --session-sqlite-all-agents --jsonopenclaw doctor --session-sqlite compact --session-sqlite-all-agentsopenclaw doctor --session-sqlite recover --github-issue

Sichern Sie das OpenClaw-Zustandsverzeichnis, bevor Sie import in einer Installation mit wichtigem Verlauf ausführen. validate wird mit einem von null verschiedenen Exit-Code beendet, wenn ein ausgewählter veralteter Eintrag in SQLite fehlt, eine Sitzungs-ID abweicht oder die Anzahl der Transkriptereignisse abweicht. Wenn Sie --session-sqlite-store <path> verwenden, prüfen Sie, ob der Bericht die erwartete Anzahl von Zielen enthält; ein nicht vorhandener expliziter Speicherpfad wählt keine Ziele aus.

SQLite-Löschvorgänge geben zunächst Seiten innerhalb der Datenbank frei; sie verkleinern die Datenbankdatei nicht notwendigerweise sofort. Führen Sie nach dem Löschen oder Archivieren großer Transkripte openclaw doctor --session-sqlite compact --session-sqlite-all-agents aus, um WAL-Dateien mit einem Checkpoint zu versehen, VACUUM auszuführen und die Größen von Datenbank und WAL vorher und nachher zu melden. Die Compaction erfordert eine reguläre Datei mit dem aktuellen Agentenschema, den dauerhaften Eigentümermetadaten des ausgewählten Agenten und keinen offenen Handle im Doctor- Prozess. Dies ist eine explizite Offline-Wartung: Stoppen Sie zuerst das Gateway, damit normale Schreibvorgänge nicht mit dem Checkpoint oder VACUUM konkurrieren können.

Jeder Import schreibt ein Manifest unter ~/.openclaw/session-sqlite-migration-runs/, bevor Transkriptartefakte in das Archiv verschoben werden. Wenn der Start eine fehlgeschlagene SQLite-Sitzungsmigration meldet, nachdem Artefakte verschoben wurden, führen Sie die Wiederherstellung aus:

openclaw doctor --session-sqlite recover --github-issue

Die Wiederherstellung wählt das neueste Manifest einer fehlgeschlagenen Migration aus, stellt ausschließlich die archivierten Artefakte des Manifests wieder her, validiert die betroffenen Ziele, aktualisiert die bereinigten Berichte .failure.md und .failure.json und bereitet den Text eines GitHub-Issues vor, der Transkriptinhalte, die unbereinigte Umgebung, Secrets und unbegrenzt umfangreiche Konfiguration vermeidet. Wenn kein Manifest einer fehlgeschlagenen Migration vorhanden ist, aber eine ausgewählte SQLite- Agentendatenbank beschädigt oder keine Datenbank ist oder Journal-Sidecars ohne Haupt- datenbank besitzt, kopiert die Wiederherstellung den vollständigen Dateisatz in ein temporäres Inspektions- verzeichnis. SQLite kann ein gültiges aktives Journal in dieser entbehrlichen Kopie zurücksetzen, bevor quick_check, integrity_check und foreign_key_check ausgeführt werden, während die ursprünglichen forensischen Dateien unverändert bleiben. Fehlgeschlagene Integritätsprüfungen oder verwaiste Sidecars bewahren die DB-, WAL-, SHM- und Rollback-Journal-Dateien auf, indem der gesamte erkannte Satz mit einem einheitlichen Suffix .corrupt-<timestamp> umbenannt wird. Bei einem abgefangenen Fehler beim Umbenennen werden bereits verschobene Dateien zurückverschoben, bevor der Fehler gemeldet wird, sodass ein wiederherstellbarer Dateisatz nicht unbemerkt aufgeteilt wird. Stoppen Sie das Gateway vor der Wiederherstellung; das Kopieren oder Umbenennen eines sich aktiv ändernden SQLite-Dateisatzes ist unsicher und verhält sich je nach Betriebssystem unterschiedlich. Mit --github-issue --yes verwendet Doctor die GitHub CLI, um das Issue in openclaw/openclaw zu erstellen; ohne Bestätigung schreibt es den lokalen Supportbericht und gibt eine vorausgefüllte Issue-URL aus.

restore bleibt die grundlegende Rückgängig-Operation. Sie verwendet die Einträge sourcePath -> archivePath des Manifests, verschiebt archivierte Artefakte nur dann zurück, wenn der ursprüngliche Pfad fehlt, meldet Konflikte, wenn beide Pfade vorhanden sind, und lässt die SQLite-Datenbank bestehen.

Downgrade nach der SQLite-Sitzungsmigration

Stellen Sie vor dem Start einer älteren dateibasierten OpenClaw-Version die archivierten veralteten Transkriptartefakte wieder her:

openclaw doctor --session-sqlite restore --session-sqlite-all-agents

Ältere Versionen lesen sessions.json-Einträge und die in diesen Einträgen aufgezeichneten sessionFile-Pfade. Nach der SQLite-Migration verschieben erfolgreiche Importe aktive JSONL- Transkripte nach session-sqlite-import-archive/, sodass die ältere Laufzeit diesen Verlauf erst sehen kann, nachdem Restore die im Manifest aufgezeichneten Artefakte an ihre ursprünglichen Pfade zurückverschoben hat.

Restore löscht keine SQLite-Daten. Sitzungen, die nach der Umstellung auf SQLite erstellt wurden, existieren ausschließlich in SQLite und werden für die ältere Laufzeit nicht angezeigt. Wenn Sie später erneut aktualisieren, führen Sie die oben beschriebene normale Migrationsvalidierungsabfolge aus, damit OpenClaw die wiederhergestellten veralteten Artefakte vor dem Import mit den SQLite-Zeilen vergleichen kann.

Hinweise

• Im Nix-Modus (OPENCLAW_NIX_MODE=1) funktionieren schreibgeschützte Doctor-Prüfungen weiterhin, aber doctor --fix, doctor --repair, doctor --yes und doctor --generate-gateway-token sind deaktiviert, da openclaw.json unveränderlich ist. Bearbeiten Sie stattdessen die Nix-Quelle für diese Installation; verwenden Sie für nix-openclaw den agentenzentrierten Schnellstart.
• Interaktive Eingabeaufforderungen (Schlüsselbund-/OAuth-Korrekturen usw.) werden nur ausgeführt, wenn stdin ein TTY ist und --non-interactive nicht gesetzt ist. Ausführungen ohne Terminal (Cron, Telegram, kein Terminal) überspringen die Eingabeaufforderungen.
• Nicht interaktive doctor-Ausführungen überspringen das vorzeitige Laden von Plugins, damit Systemprüfungen ohne Terminal schnell bleiben. Interaktive Sitzungen laden weiterhin die Plugin-Oberflächen, die für den veralteten Systemprüfungs-/Reparaturablauf benötigt werden.
• --lint ist strenger als --non-interactive: immer schreibgeschützt, keine Eingabeaufforderungen und keine Anwendung sicherer Migrationen. Verwenden Sie doctor --fix oder doctor --repair, wenn Doctor Änderungen vornehmen soll.
• Doctor führt standardmäßig keine exec-SecretRefs aus, wenn Secrets geprüft werden. Verwenden Sie --allow-exec (mit oder ohne --lint) nur, wenn Doctor diese konfigurierten Secret-Resolver bewusst ausführen soll.
• Bei jedem Schreiben der Konfiguration (einschließlich einer Reparatur mit --fix) wird eine Sicherung nach ~/.openclaw/openclaw.json.bak rotiert (mit einem nummerierten Ring von .bak.1 bis .bak.4). --fix entfernt außerdem unbekannte Konfigurationsschlüssel, die von der Schemavalidierung gemeldet wurden, und führt jede Entfernung auf; während einer laufenden Aktualisierung wird dies übersprungen, damit ein teilweise geschriebener Upgrade-Zustand nicht entfernt wird, bevor dessen Migration abgeschlossen ist.
• Setzen Sie OPENCLAW_SERVICE_REPAIR_POLICY=external, wenn ein anderer Supervisor den Gateway-Lebenszyklus verwaltet. Doctor meldet weiterhin den Zustand von Gateway und Dienst und führt Reparaturen durch, die nicht den Dienst betreffen, überspringt jedoch Installation, Start, Neustart und Bootstrap des Dienstes sowie die Bereinigung veralteter Dienste.
• Unter Linux ignoriert Doctor inaktive zusätzliche Gateway-ähnliche systemd-Units und schreibt bei einer Reparatur die Befehls-/Einstiegspunkt-Metadaten eines laufenden systemd-Gateway-Dienstes nicht neu. Beenden Sie zuerst den Dienst oder verwenden Sie openclaw gateway install --force, um den aktiven Starter zu ersetzen.
• doctor --fix --non-interactive meldet fehlende oder veraltete Definitionen des Gateway-Dienstes, installiert oder überschreibt sie außerhalb des Aktualisierungsreparaturmodus jedoch nicht. Führen Sie bei einem fehlenden Dienst openclaw gateway install aus oder verwenden Sie openclaw gateway install --force, um den Starter zu ersetzen.
• Integritätsprüfungen des Zustands erkennen verwaiste Transkriptdateien im Sitzungsverzeichnis. Für ihre Archivierung als .deleted.<timestamp> ist eine interaktive Bestätigung erforderlich; --fix, --yes und Ausführungen ohne Terminal belassen sie an Ort und Stelle.
• Doctor durchsucht ~/.openclaw/cron/jobs.json (oder cron.store) nach veralteten Formen von Cron-Aufträgen und schreibt sie neu, bevor kanonische Zeilen in SQLite importiert werden.
• Doctor meldet Cron-Aufträge mit einer expliziten Überschreibung durch payload.model, einschließlich der Anzahl pro Provider-Namespace und Abweichungen von agents.defaults.model, sodass geplante Aufträge, die das Standardmodell nicht übernehmen, bei Untersuchungen zur Authentifizierung oder Abrechnung sichtbar sind.
• Doctor meldet Cron-Aufträge, die weiterhin als in Ausführung (state.runningAtMs) markiert sind, wodurch openclaw cron list sie als running anzeigen kann. Diese Prüfung ist schreibgeschützt: Wenn derzeit kein Gateway einen markierten Auftrag ausführt, zeichnet der nächste Start des Cron-Dienstes die unterbrochene Ausführung auf und entfernt die Markierung.
• Unter Linux warnt Doctor, wenn die Crontab des Benutzers weiterhin das nicht mehr gewartete veraltete Skript ~/.openclaw/bin/ensure-whatsapp.sh ausführt, das fälschlicherweise Gateway inactive melden kann, wenn Cron die Umgebung des systemd-Benutzerbusses fehlt.
• Wenn WhatsApp aktiviert ist, prüft Doctor auf eine beeinträchtigte Gateway-Ereignisschleife, während lokale openclaw-tui-Clients weiterhin ausgeführt werden. doctor --fix beendet nur verifizierte lokale TUI-Clients, damit WhatsApp-Antworten nicht hinter veralteten TUI-Aktualisierungsschleifen in die Warteschlange eingereiht werden.
• Doctor schreibt veraltete Modellreferenzen vom Typ openai-codex/* in allen primären Modellen, Fallbacks, Modellen zur Bild-/Videogenerierung, Heartbeat-/Subagent-/Compaction-Überschreibungen, Hooks, Kanalmodellüberschreibungen und veralteten Sitzungs-Routenbindungen in kanonische Referenzen vom Typ openai/* um. --fix migriert außerdem veraltete Authentifizierungsprofile vom Typ openai-codex:* und Einträge unter auth.order.openai-codex zu openai:*, überträgt die Codex-Absicht auf Provider-/modellbezogene Einträge vom Typ agentRuntime.id: "codex", entfernt veraltete Laufzeitbindungen für ganze Agenten und Sitzungen und behält reparierte OpenAI-Agentenreferenzen im Codex-Authentifizierungsrouting, anstatt sie über die direkte OpenAI-API-Schlüssel-Authentifizierung zu leiten.
• Doctor meldet nicht leere Listen unter auth.order.<provider>, deren referenzierte Profile vollständig fehlen, obwohl kompatible gespeicherte Anmeldedaten vorhanden sind. doctor --fix löscht nur diese veralteten Überschreibungen und stellt damit die automatische agentenspezifische Auswahl von Anmeldedaten wieder her; explizit leere Reihenfolgen, teilweise noch gültige Listen und Reihenfolgen ohne kompatible gespeicherte Anmeldedaten bleiben unverändert. Wenn ein aktiver SQLite-Authentifizierungsspeicher nicht lesbar oder fehlerhaft ist, erklärt Doctor, warum diese Reparatur übersprungen wurde. Starten Sie ein laufendes Gateway neu, bevor Sie den Authentifizierungsstatus erneut prüfen, falls dessen Konfigurations-Neulademodus den Schreibvorgang nicht automatisch anwendet.
• Doctor bereinigt veraltete Staging-Zustände für Plugin-Abhängigkeiten aus älteren OpenClaw-Versionen und verknüpft das Hostpaket openclaw für verwaltete npm-Plugins, die es als Peer-Abhängigkeit deklarieren, erneut. Außerdem repariert Doctor fehlende herunterladbare Plugins, auf die von der Konfiguration verwiesen wird (plugins.entries, konfigurierte Kanäle, konfigurierte Provider-/Sucheinstellungen und konfigurierte Agentenlaufzeiten). Während Paketaktualisierungen überspringt Doctor die Plugin-Reparatur durch den Paketmanager, bis der Paketaustausch abgeschlossen ist; führen Sie anschließend openclaw doctor --fix erneut aus, falls ein konfiguriertes Plugin weiterhin wiederhergestellt werden muss. Wenn ein Download fehlschlägt, meldet Doctor den Installationsfehler und behält den konfigurierten Plugin-Eintrag für den nächsten Reparaturversuch bei.
• Doctor repariert veraltete Plugin-Konfigurationen, indem fehlende Plugin-IDs aus plugins.allow/plugins.deny/plugins.entries sowie die zugehörigen verwaisten Kanalkonfigurationen, Heartbeat-Ziele und Kanalmodellüberschreibungen entfernt werden, sofern die Plugin-Erkennung ordnungsgemäß funktioniert.
• Doctor isoliert ungültige Plugin-Konfigurationen, indem der betroffene Eintrag plugins.entries.<id> deaktiviert und dessen ungültige config-Nutzlast entfernt wird. Beim Start überspringt das Gateway bereits nur dieses fehlerhafte Plugin, sodass andere Plugins und Kanäle weiter ausgeführt werden.
• Doctor entfernt das eingestellte plugins.entries.codex.config.codexDynamicToolsProfile; der Codex-App-Server behält Codex-native Arbeitsbereichswerkzeuge immer nativ bei.
• Doctor migriert automatisch die veraltete flache Talk-Konfiguration (talk.voiceId, talk.modelId und ähnliche Einträge) zu talk.provider + talk.providers.<provider>. Wiederholte Ausführungen von doctor --fix melden bzw. wenden die Talk-Normalisierung nicht mehr an, wenn der einzige Unterschied in der Reihenfolge der Objektschlüssel besteht.
• Doctor enthält eine Bereitschaftsprüfung für die Speichersuche und kann openclaw configure --section model empfehlen, wenn Anmeldedaten für Einbettungen fehlen.
• Doctor warnt, wenn kein Befehlseigentümer konfiguriert ist. Der Befehlseigentümer ist das Konto des menschlichen Betreibers, das Befehle ausführen darf, die ausschließlich Eigentümern vorbehalten sind, und gefährliche Aktionen genehmigen darf. Die DM-Kopplung erlaubt einer Person lediglich, mit dem Bot zu kommunizieren; wenn Sie einen Absender genehmigt haben, bevor der Bootstrap für den ersten Eigentümer verfügbar war, legen Sie commands.ownerAllowFrom explizit fest.
• Doctor meldet einen Hinweis, wenn Agenten im Codex-Modus konfiguriert sind und persönliche Codex-CLI-Ressourcen im Codex-Basisverzeichnis des Betreibers vorhanden sind. Lokale Starts des Codex-App-Servers verwenden isolierte agentenspezifische Basisverzeichnisse; installieren Sie bei Bedarf zuerst das Codex-Plugin und verwenden Sie dann openclaw migrate plan codex, um Ressourcen zu erfassen, die bewusst übernommen werden sollen.
• Doctor warnt, wenn Skills, die für den Standardagenten zulässig sind, in der aktuellen Laufzeitumgebung nicht verfügbar sind (fehlende Binärdateien, Umgebungsvariablen, Konfigurationen oder Betriebssystemanforderungen). doctor --fix kann diese nicht verfügbaren Skills mit skills.entries.<skill>.enabled=false deaktivieren; installieren bzw. konfigurieren Sie stattdessen die fehlende Anforderung, wenn der Skill aktiv bleiben soll.
• Wenn der Sandbox-Modus aktiviert, Docker jedoch nicht verfügbar ist, meldet Doctor eine eindeutige Warnung mit Abhilfemaßnahmen (install Docker oder openclaw config set agents.defaults.sandbox.mode off).
• Wenn veraltete Sandbox-Registrierungsdateien oder Shard-Verzeichnisse vorhanden sind (~/.openclaw/sandbox/containers.json, ~/.openclaw/sandbox/browsers.json, ~/.openclaw/sandbox/containers/ oder ~/.openclaw/sandbox/browsers/), meldet Doctor sie; --fix migriert gültige Einträge in SQLite und isoliert ungültige veraltete Dateien.
• Wenn gateway.auth.token/gateway.auth.password durch SecretRef verwaltet werden und im aktuellen Befehlspfad nicht verfügbar sind, meldet Doctor eine schreibgeschützte Warnung und schreibt keine Fallback-Anmeldedaten im Klartext. Bei exec-basierten SecretRefs überspringt Doctor die Ausführung, sofern --allow-exec nicht angegeben ist.
• Wenn die Prüfung einer Kanal-SecretRef in einem Korrekturpfad fehlschlägt, fährt Doctor fort und meldet eine Warnung, anstatt vorzeitig beendet zu werden.
• Nach Migrationen des Zustandsverzeichnisses warnt Doctor, wenn aktivierte Telegram- oder Discord-Standardkonten von einem Umgebungs-Fallback abhängen und TELEGRAM_BOT_TOKEN oder DISCORD_BOT_TOKEN für den Doctor-Prozess nicht verfügbar ist.
• Die automatische Auflösung von Telegram-Benutzernamen in allowFrom (doctor --fix) erfordert ein im aktuellen Befehlspfad auflösbares Telegram-Token. Wenn die Token-Prüfung nicht verfügbar ist, meldet Doctor eine Warnung und überspringt die automatische Auflösung für diesen Durchlauf.

macOS: launchctl-Umgebungsüberschreibungen

Wenn Sie zuvor launchctl setenv OPENCLAW_GATEWAY_TOKEN ... (oder ...PASSWORD) ausgeführt haben, überschreibt dieser Wert Ihre Konfigurationsdatei und kann dauerhafte „unauthorized“-Fehler verursachen.

launchctl getenv OPENCLAW_GATEWAY_TOKENlaunchctl getenv OPENCLAW_GATEWAY_PASSWORD launchctl unsetenv OPENCLAW_GATEWAY_TOKENlaunchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

Verwandte Themen

• CLI-Referenz
• Gateway-Diagnose