openclaw doctor

Integritätsprüfungen und schnelle Fehlerbehebungen für Gateway, Kanäle, Plugins, Skills, Modellrouting, lokalen Zustand und Konfigurationsmigrationen. Verwenden Sie diesen Befehl, wenn etwas nicht wie erwartet funktioniert und Sie mit einem einzigen Befehl herausfinden möchten, was nicht stimmt.

Wenn der Gateway-Status beeinträchtigte SecretRef-Verantwortliche meldet, gibt doctor eine Warnung vom Typ Beeinträchtigung der Secret-Laufzeit mit allen nicht initialisierten oder veralteten Verantwortlichen, dem betroffenen Konfigurationspfad, einem redigierten Grund und dem Wiederholungsbefehl openclaw secrets reload aus.

Wenn eingehende Kanalereignisse in die Dead-Letter-Warteschlange verschoben werden, nennt doctor jedes betroffene Kanalkonto und verweist zur Untersuchung und Wiederherstellung auf openclaw channels dead-letters list.

Verwandte Themen:

• Fehlerbehebung: Fehlerbehebung
• Sicherheitsaudit: Sicherheit

Betriebsarten

Doctor verfügt über fünf Betriebsarten:

Verwenden Sie vorzugsweise --lint, wenn die Automatisierung ein stabiles Ergebnis benötigt. Verwenden Sie vorzugsweise --fix, wenn ein menschlicher Operator die Konfiguration oder den Zustand durch doctor bearbeiten lassen möchte.

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 die Kanalprüfungen anstelle von doctor:

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 Reparaturen und kein Neuschreiben 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 gesetzt; der Gateway-Start 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 bildet die Schnittstelle für Skripte:

{  "ok": false,  "checksRun": 5,  "checksSkipped": 0,  "findings": [    {      "checkId": "core/doctor/gateway-config",      "severity": "warning",      "message": "gateway.mode ist nicht gesetzt; der Gateway-Start 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 vom Typ info/warning vorhanden sind.

--all steuert, welche Prüfungen vor der Filterung nach Schweregrad ausgewählt werden. Der standardmäßige Lint-Lauf schließt Prüfungen aus, die tiefgehend 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 und beobachtete Backends sowie die Fallback-Reihenfolge, ohne ein Sprachmodell zu laden. Dabei wird ein informativer Befund ausgegeben; fügen Sie daher --severity-min info hinzu, um ihn anzuzeigen.

Strukturierte Integritätsprüfungen

Moderne doctor-Prüfungen verwenden einen kleinen, aufgeteilten 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 veralteten 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 in Richtung doctor --fix --dry-run erweitert werden können, ohne die Mutationsplanung nach detect() zu verschieben.

repair() meldet status: "repaired" | "skipped" | "failed" (ein ausgelassener 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; wenn der Befund weiterhin vorhanden ist, meldet Doctor eine Reparaturwarnung, statt die Änderung als abgeschlossen zu behandeln.

Ein Befund enthält:

Modernisierte Doctor-Prüfungen des Kerns bleiben dem geordneten Doctor-Beitrag zugeordnet, dem ihr für Menschen bestimmtes doctor-/doctor --fix-Verhalten gehört. Die gemeinsame strukturierte Zustandsregistrierung ist der Erweiterungspunkt: Gebündelte und Plugin-gestützte Prüfungen werden nach den Doctor-Prüfungen des Kerns ausgeführt, sobald ihr zuständiges Paket sie im aktiven Befehlspfad registriert. openclaw/plugin-sdk/health stellt denselben Vertrag für Plugin-Autoren 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 an stdout ausgegeben; der Exit-Code ist 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 installierter Plugins fehlt oder fehlerhaft ist, gibt der JSON-Modus dennoch die Hülle mit einem plugin.index_unavailable-Fehlerbefund aus.

Der Start eines Container-Images ist 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 die Bereitschaft meldet. Wenn die Reparatur nicht sicher abgeschlossen werden kann, wird der Start beendet und Sie werden aufgefordert, dasselbe Image einmal mit openclaw doctor --fix für denselben eingebundenen Zustand/dieselbe eingebundene Konfiguration auszuführen, bevor der Container normal neu gestartet wird.

Migration von Legacy-Zuständen

openclaw doctor --fix ist die einzige zuständige Komponente für persistente Migrationen von Dateien zu SQLite. Sie validiert und beansprucht jede erkannte Quelle, schreibt und überprüft kanonische Zeilen, zeichnet einen Migrationsbeleg auf und entfernt anschließend die stillgelegte Quelle. Laufzeitcode führt keine verzögerten Importe oder Fallback-Lesevorgänge durch.

Dies umfasst stillgelegte MCP-OAuth-Dateien unter <state-dir>/mcp-oauth/*.json. Stoppen Sie vor der Reparatur den Gateway. Doctor importiert gültige Anmeldedaten nach <state-dir>/state/openclaw.sqlite, behält eine vorhandene kanonische SQLite-Sitzung bei, wenn beide Speicher vorhanden sind, entfernt den veralteten persistierten OAuth-Wert state und verhindert mithilfe seines Belegs, dass eine neu erstellte veraltete Datei abgemeldete Anmeldedaten wiederherstellt. Stillgelegte .lock-Sidecars schlagen nach dem Fail-Closed-Prinzip fehl: Wenn Doctor einen veralteten Besitzer meldet, stellen Sie sicher, dass kein älterer OpenClaw-Prozess ausgeführt wird, entfernen Sie dieses Sidecar und führen Sie Doctor erneut aus.

SQLite-Compaction des gemeinsamen Zustands

Informationen zur Schemaversionierung, zu Integritätsprüfungen und zur Wiederherstellung nach einem Downgrade finden Sie unter Datenbankschemas.

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 niemals durch den normalen Gateway-Betrieb aufgerufen und ist kein Bestandteil von openclaw doctor --fix. Der Befehl erwirbt dieselbe Besitzsperre für den Zustand wie der Gateway-Start und hält sie während der Validierung, des Checkpointings, von VACUUM und der abschließenden Integritätsprüfungen. Die Ausführung wird verweigert, solange ein Gateway oder ein anderer SQLite-Wartungsbefehl diese Sperre besitzt. Die Zustandssperre bleibt aktiv, wenn OPENCLAW_ALLOW_MULTI_GATEWAY=1 den Gateway-Singleton pro Konfiguration überspringt, sodass eine Betreiber-Shell nicht die Umgebung des Gateway-Dienstes übernehmen muss, damit die Wartung ihn erkennt.

Stoppen Sie zunächst den 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 erstellt oder die Datei geändert wird.
3. Erfordert ein nicht ausgelastetes wal_checkpoint(TRUNCATE). Stoppen Sie alle verbleibenden OpenClaw- Prozesse und versuchen Sie es erneut, wenn der Checkpoint ausgelastet 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 Besitzer gewährte Berechtigungen auf die Datenbank und die SQLite-Sidecar-Dateien an.

Die JSON-Ausgabe meldet die Datenbank- und WAL-Größen, Freelist-Seiten, die Seitengröße und den Wert auto_vacuum 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 hat kein separates Erfolgsfeld. SQLite meldet auto_vacuum als 0 für „keine“, 1 für „vollständig“ und 2 für „inkrementell“.

Die Compaction schlägt ohne Mutation fehl, wenn das Schema veraltet oder neuer als der ausgeführte OpenClaw-Build ist oder zu einer Agent-Datenbank 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-Sitzungsmigration

OpenClaw importiert während des Gateway-Starts und während openclaw doctor --fix automatisch Legacy-Sitzungszeilen und den Transkriptverlauf in die SQLite-Datenbank jedes Agenten. openclaw doctor --session-sqlite <mode> ist das gezielte Inspektions- und Validierungswerkzeug für diese Migration. Aktuelle Sitzungszeilen der Laufzeit befinden sich in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. Legacy- Dateien vom Typ sessions.json sind Migrationsquellen. Aktive Transkript-JSONL-Dateien werden nach erfolgreichem Import importiert und 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 Legacy-Speicherdatei vorhanden ist.
• --session-sqlite-agent <id>: ein konfigurierter Agent.
• --session-sqlite-all-agents: konfigurierte Agent-Speicher sowie erkannte Agent-Speicher.
• --session-sqlite-store <path>: ein expliziter Legacy-Pfad vom Typ sessions.json.

Manuelle Inspektionssequenz:

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 auf einer Installation mit wichtigem Verlauf ausführen. validate wird mit einem von null verschiedenen Exit-Code beendet, wenn ein ausgewählter Legacy-Eintrag in SQLite fehlt, eine Sitzungs-ID abweicht oder die Anzahl der Transkriptereignisse abweicht. Prüfen Sie bei Verwendung von --session-sqlite-store <path>, ob der Bericht die erwartete Zielanzahl enthält; ein nicht vorhandener expliziter Speicherpfad wählt keine Ziele aus.

SQLite-Löschungen geben zunächst Seiten innerhalb der Datenbank frei; sie verkleinern die Datenbankdatei nicht zwangsläufig sofort. Führen Sie nach dem Löschen oder Archivieren großer Transkripte openclaw doctor --session-sqlite compact --session-sqlite-all-agents aus, um Checkpoints für WAL-Dateien zu erstellen, VACUUM auszuführen und die Datenbank- und WAL- Größen vorher und nachher zu melden. Die Compaction erfordert eine reguläre Datei mit dem aktuellen Agent-Schema, den dauerhaften Besitzer-Metadaten des ausgewählten Agenten und keinen offenen Handle im Doctor- Prozess. Die destruktiven Modi import, compact, recover und restore halten während ihres gesamten Vorgangs dieselbe Besitzsperre für den Zustand wie der Gateway-Start; inspect, dry-run und validate bleiben schreibgeschützt und erwerben sie nicht. Stoppen Sie zuerst den Gateway. Destruktive Modi schlagen fehl, statt mit aktiven Schreibvorgängen oder einem anderen Wartungsbefehl in Konkurrenz zu treten. Ein destruktives Ziel vom Typ --session-sqlite-store muss sich innerhalb des aktiven Zustandsverzeichnisses befinden; setzen Sie OPENCLAW_STATE_DIR auf das besitzende Zustandsverzeichnis des Speichers, bevor Sie eine andere Installation warten. Vorhandene hart verknüpfte Ziele werden abgelehnt, da ein anderer Pfad außerhalb des gesperrten Zustandsverzeichnisses denselben Datenbank-Inode gemeinsam nutzen kann. Dieselben Besitzprüfungen gelten für SQLite-WAL-, Shared-Memory- und Rollback-Journal-Sidecars.

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 nur die archivierten Artefakte des Manifests wieder her, validiert die betroffenen Ziele, aktualisiert die bereinigten Berichte .failure.md und .failure.json und bereitet den Text für ein GitHub-Issue vor, der keine Transkriptinhalte, Rohdaten der Umgebung, Secrets oder unbegrenzte Konfiguration enthält. Wenn kein Manifest einer fehlgeschlagenen Migration vorhanden ist, aber eine ausgewählte SQLite- Datenbank eines Agenten beschädigt oder keine Datenbank ist oder Journal-Sidecars ohne eine Haupt- datenbank enthält, kopiert die Wiederherstellung den vollständigen Dateisatz in ein temporäres Prüfverzeichnis. SQLite kann ein gültiges Hot-Journal in dieser temporären 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 erhalten die DB-, WAL-, SHM- und Rollback-Journal-Dateien, indem der gesamte erkannte Satz mit einem einzigen 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 vor der Wiederherstellung den Gateway; 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 Undo-Operation auf niedrigerer Ebene. Sie verwendet die Manifest- Datensätze sourcePath -> archivePath, verschiebt archivierte Artefakte nur dann zurück, wenn der ursprüngliche Pfad fehlt, meldet Konflikte, wenn beide Pfade vorhanden sind, und belässt die SQLite-Datenbank an ihrem Ort.

Downgrade nach der SQLite-Migration von Sitzungen

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

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

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

Die Wiederherstellung löscht keine SQLite-Daten. Nach der Umstellung auf SQLite erstellte Sitzungen sind nur in SQLite vorhanden und werden der älteren Laufzeitumgebung nicht angezeigt. Wenn Sie später erneut ein Upgrade durchführen, führen Sie die oben beschriebene normale Validierungssequenz für die Migration aus, damit OpenClaw die wiederhergestellten Legacy-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 Benutzeroberfläche (Cron, Telegram, kein Terminal) überspringen die Eingabeaufforderungen.
• Nicht interaktive Ausführungen von doctor überspringen das vorzeitige Laden von Plugins, damit Integritätsprüfungen ohne Benutzeroberfläche schnell bleiben. Interaktive Sitzungen laden weiterhin die Plugin-Oberflächen, die für den bisherigen Integritäts-/Reparaturablauf erforderlich sind.
• --lint ist strenger als --non-interactive: immer schreibgeschützt, zeigt niemals Eingabeaufforderungen an und wendet niemals sichere Migrationen an. Verwenden Sie doctor --fix oder doctor --repair, wenn Doctor Änderungen vornehmen soll.
• Doctor führt beim standardmäßigen Prüfen von Secrets keine exec-SecretRefs aus. Verwenden Sie --allow-exec (mit oder ohne --lint) nur, wenn Doctor diese konfigurierten Secret-Resolver bewusst ausführen soll.
• Jeder Schreibvorgang an der Konfiguration (einschließlich einer --fix-Reparatur) rotiert eine Sicherung nach ~/.openclaw/openclaw.json.bak (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.
• Wenn openclaw.json nicht geparst werden kann und keine letzte bekanntermaßen funktionierende Konfiguration wiederhergestellt werden kann, bewahrt doctor --fix das Original als openclaw.json.clobbered.<timestamp> auf, lässt die aktuelle Datei unverändert und wird mit einem Fehler beendet, anstatt einen unvollständigen Ersatz zu schreiben.
• 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 außerhalb des Dienstes aus, überspringt jedoch Installation, Start, Neustart und Bootstrap des Dienstes sowie die Bereinigung bisheriger Dienste.
• Doctor meldet das angewendete Heap-Limit des verwalteten Gateways sowie die adaptive Herleitung, die für das aktuelle Arbeitsspeicherlimit des Hosts oder Containers verwendet wurde. Verwenden Sie openclaw gateway status, um denselben Bericht außerhalb eines Reparaturdurchlaufs abzurufen.
• Unter Linux ignoriert Doctor inaktive zusätzliche Gateway-ähnliche systemd-Units und schreibt während einer Reparatur keine Befehls-/Einstiegspunkt-Metadaten für einen laufenden systemd-Gateway-Dienst neu. Beenden Sie zuerst den Dienst oder verwenden Sie openclaw gateway install --force, um das aktive Startprogramm zu ersetzen.
• doctor --fix --non-interactive meldet fehlende oder veraltete Gateway-Dienstdefinitionen, installiert oder überschreibt sie außerhalb des Aktualisierungsreparaturmodus jedoch nicht. Führen Sie bei einem fehlenden Dienst openclaw gateway install oder zum Ersetzen des Startprogramms openclaw gateway install --force aus.
• Integritätsprüfungen des Zustands erkennen verwaiste Transkriptdateien im Sitzungsverzeichnis. Ihre Archivierung als .deleted.<timestamp> erfordert eine interaktive Bestätigung; --fix, --yes und Ausführungen ohne Benutzeroberfläche belassen sie an Ort und Stelle.
• Doctor durchsucht ~/.openclaw/cron/jobs.json (oder cron.store) nach bisherigen Formen von Cron-Jobs und schreibt sie neu, bevor kanonische Zeilen in SQLite importiert werden.
• Doctor meldet Cron-Jobs mit einer expliziten payload.model-Überschreibung, einschließlich der Anzahl nach Provider-Namespace und Abweichungen von agents.defaults.model, sodass geplante Jobs, die nicht das Standardmodell übernehmen, bei Untersuchungen zu Authentifizierung oder Abrechnung sichtbar sind.
• Doctor meldet Cron-Jobs, die weiterhin als in Bearbeitung (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 Job 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 gepflegte bisherige ~/.openclaw/bin/ensure-whatsapp.sh ausführt, das Gateway inactive falsch 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 eingereiht werden.
• Wenn HTTP(S)-Proxy-Umgebungsvariablen vorhanden sind, aber tools.web.fetch.useTrustedEnvProxy deaktiviert ist, erläutert Doctor, dass web_fetch weiterhin direktes Routing verwendet, führt eine kurze direkte TLS-Verbindungsprüfung aus und nennt die explizite Aktivierungsoption. Proxy-Vertrauen wird niemals automatisch aktiviert.
• Doctor schreibt bisherige Modellreferenzen codex/* und openai-codex/* in kanonische openai/*-Referenzen um: für primäre Modelle, Fallbacks, Modell-Zulassungslisten, Modelle zur Bild-/Videoerzeugung, Heartbeat-/Subagent-/Compaction-Überschreibungen, Hooks, Kanalmodell-Überschreibungen, Cron-Nutzdaten sowie veraltete Sitzungs-/Transkript-Routenbindungen. --fix führt außerdem bisherige Konfigurationen von models.providers.codex und models.providers.openai-codex zusammen, sofern dies sicher ist, migriert bisherige openai-codex:*-Authentifizierungsprofile und auth.order.openai-codex-Einträge nach openai:*, verschiebt die Codex-Absicht in Provider-/modellbezogene agentRuntime.id: "codex"-Einträge, entfernt veraltete Laufzeitbindungen für vollständige Agenten/Sitzungen und belässt reparierte OpenAI-Agentenreferenzen beim Codex-Authentifizierungsrouting statt bei direkter OpenAI-API-Schlüssel-Authentifizierung.
• Doctor meldet nicht leere auth.order.<provider>-Listen, deren referenzierte Profile sämtlich nicht mehr vorhanden sind, obwohl kompatible gespeicherte Anmeldedaten existieren. doctor --fix löscht nur diese veralteten Überschreibungen und stellt damit die automatische agentenspezifische Auswahl der 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, erläutert 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 übernimmt.
• Doctor bereinigt den bisherigen Staging-Zustand von Plugin-Abhängigkeiten aus älteren OpenClaw-Versionen und verknüpft das openclaw-Paket des Hosts für verwaltete npm-Plugins neu, die es als Peer-Abhängigkeit deklarieren. Außerdem repariert Doctor fehlende herunterladbare Plugins, auf die die Konfiguration verweist (plugins.entries, konfigurierte Kanäle, konfigurierte Provider-/Sucheinstellungen, 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. Schlägt ein Download fehl, 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 passende verwaiste Kanalkonfigurationen, Heartbeat-Ziele und Kanalmodell-Überschreibungen entfernt werden, sofern die Plugin-Erkennung ordnungsgemäß funktioniert.
• Doctor isoliert ungültige Plugin-Konfigurationen, indem der betroffene plugins.entries.<id>-Eintrag deaktiviert und seine 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 Workspace-Tools stets nativ.
• Doctor migriert automatisch die bisherige flache Talk-Konfiguration (talk.voiceId, talk.modelId und verwandte Einträge) nach talk.provider + talk.providers.<provider>. Wiederholte Ausführungen von doctor --fix melden/wenden keine Talk-Normalisierung mehr an, wenn der einzige Unterschied in der Reihenfolge der Objektschlüssel besteht.
• Doctor umfasst eine Bereitschaftsprüfung für die Speichersuche und kann openclaw configure --section model empfehlen, wenn Embedding-Anmeldedaten fehlen.
• Doctor warnt, wenn kein Befehlsinhaber konfiguriert ist. Der Befehlsinhaber ist das Konto des menschlichen Betreibers, das ausschließlich Inhabern vorbehaltene Befehle ausführen und gefährliche Aktionen genehmigen darf. Durch DM-Kopplung kann jemand lediglich mit dem Bot kommunizieren; wenn Sie einen Absender genehmigt haben, bevor der Bootstrap für den ersten Inhaber vorhanden war, setzen Sie commands.ownerAllowFrom explizit.
• Doctor meldet einen Infohinweis, wenn Agenten im Codex-Modus konfiguriert sind und persönliche Codex-CLI-Ressourcen im Codex-Ausgangsverzeichnis des Betreibers vorhanden sind. Lokale Starts des Codex-App-Servers verwenden isolierte agentenspezifische Ausgangsverzeichnisse; installieren Sie bei Bedarf zuerst das Codex-Plugin und verwenden Sie dann openclaw migrate plan codex, um Ressourcen zu inventarisieren, die bewusst übernommen werden sollen.
• Doctor warnt, wenn für den Standardagenten zugelassene Skills in der aktuellen Laufzeitumgebung nicht verfügbar sind (fehlende Binärdateien, Umgebungsvariablen, Konfiguration oder Betriebssystemanforderungen). doctor --fix kann diese nicht verfügbaren Skills mit skills.entries.<skill>.enabled=false deaktivieren; installieren/konfigurieren Sie stattdessen die fehlende Voraussetzung, wenn der Skill aktiv bleiben soll.
• Wenn der Sandbox-Modus aktiviert, Docker jedoch nicht verfügbar ist, meldet Doctor eine aussagekräftige Warnung mit Abhilfemaßnahmen (install Docker oder openclaw config set agents.defaults.sandbox.mode off).
• Wenn bisherige 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 nach SQLite und isoliert ungültige bisherige Dateien.
• Wenn gateway.auth.token/gateway.auth.password über SecretRef verwaltet werden und im aktuellen Befehlspfad nicht verfügbar sind, meldet Doctor eine schreibgeschützte Warnung und schreibt keine unverschlüsselten Fallback-Anmeldedaten. Bei ausführungsbasierten SecretRefs überspringt Doctor die Ausführung, sofern --allow-exec nicht vorhanden ist.
• Wenn die Prüfung einer Kanal-SecretRef in einem Reparaturpfad fehlschlägt, fährt Doctor fort und meldet eine Warnung, statt vorzeitig beendet zu werden.
• Nach Migrationen des Zustandsverzeichnisses warnt Doctor, wenn aktivierte standardmäßige Telegram- oder Discord-Konten 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-allowFrom-Benutzernamen (doctor --fix) erfordert ein auflösbares Telegram-Token im aktuellen Befehlspfad. 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 Fehler vom Typ „nicht autorisiert“ verursachen.

launchctl getenv OPENCLAW_GATEWAY_TOKENlaunchctl getenv OPENCLAW_GATEWAY_PASSWORD launchctl unsetenv OPENCLAW_GATEWAY_TOKENlaunchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

Verwandte Themen

• CLI-Referenz
• Gateway-Doctor