Naar hoofdinhoud gaan

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

openclaw doctor is de reparatie- en migratietool voor OpenClaw. Het herstelt verouderde configuratie/status, controleert de gezondheid en biedt uitvoerbare reparatiestappen.

​
Snelstart

openclaw doctor

​
Headless- en automatiseringsmodi

openclaw doctor --yes
Accepteer standaardwaarden zonder prompt (inclusief stappen voor herstart/service/sandboxreparatie waar van toepassing).
Als je wijzigingen wilt controleren voordat je schrijft, open dan eerst het configuratiebestand: 
cat ~/.openclaw/openclaw.json

​
Wat het doet (samenvatting)

  • Optionele preflight-update voor git-installaties (alleen interactief).
  • Controle op versheid van het UI-protocol (bouwt Control UI opnieuw wanneer het protocolschema nieuwer is).
  • Gezondheidscontrole + prompt voor herstart.
  • Skills-statussamenvatting (geschikt/ontbrekend/geblokkeerd) en pluginstatus.
  • Configuratienormalisatie voor legacy-waarden.
  • Migratie van Talk-configuratie van legacy platte talk.*-velden naar talk.provider + talk.providers.<provider>.
  • Browsermigratiecontroles voor legacy Chrome-extensieconfiguraties en Chrome MCP-gereedheid.
  • Waarschuwingen voor OpenCode-provideroverschrijvingen (models.providers.opencode / models.providers.opencode-go).
  • Waarschuwingen voor Codex OAuth-shadowing (models.providers.openai-codex).
  • Controle van OAuth TLS-vereisten voor OpenAI Codex OAuth-profielen.
  • Waarschuwingen voor plugin-/tool-allowlists wanneer plugins.allow beperkend is maar het toolbeleid nog steeds om wildcard- of plugin-eigen tools vraagt.
  • Legacy-statusmigratie op schijf (sessions/agent dir/WhatsApp-auth).
  • Migratie van legacy pluginmanifest-contractsleutels (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders → contracts).
  • Migratie van legacy cron-store (jobId, schedule.cron, delivery-/payloadvelden op topniveau, payload provider, eenvoudige notify: true webhook-fallbacktaken).
  • Opschoning van legacy runtimebeleid voor de volledige agent; runtimebeleid voor provider/model is de actieve routekiezer.
  • Opschoning van verouderde pluginconfiguratie wanneer plugins zijn ingeschakeld; wanneer plugins.enabled=false, worden verouderde pluginverwijzingen behandeld als inerte containment-configuratie en behouden.
  • Inspectie van sessievergrendelingsbestanden en opschoning van verouderde vergrendelingen.
  • Reparatie van sessietranscripten voor gedupliceerde prompt-herschrijftakken die zijn gemaakt door getroffen 2026.4.24-builds.
  • Detectie van tombstones voor herstart-herstel van vastgelopen subagents, met --fix-ondersteuning voor het wissen van verouderde afgebroken herstelvlaggen zodat startup het child niet blijft behandelen als door herstart afgebroken.
  • Controles op statusintegriteit en rechten (sessions, transcripts, state dir).
  • Controles op rechten van configuratiebestanden (chmod 600) bij lokale uitvoering.
  • Gezondheid van modelauthenticatie: controleert OAuth-verloop, kan tokens die bijna verlopen vernieuwen en rapporteert cooldown-/uitgeschakelde statussen van auth-profielen.
  • Detectie van extra workspace-dir (~/openclaw).
  • Reparatie van sandboximage wanneer sandboxing is ingeschakeld.
  • Legacy-servicemigratie en detectie van extra Gateways.
  • Migratie van legacy-status voor Matrix-kanaal (in --fix- / --repair-modus).
  • Runtimecontroles voor Gateway (service geïnstalleerd maar draait niet; gecachet launchd-label).
  • Waarschuwingen over kanaalstatus (geprobed vanuit de draaiende Gateway).
  • Kanaalspecifieke rechtencontroles staan onder openclaw channels capabilities; Discord-spraakkanaalrechten worden bijvoorbeeld gecontroleerd met openclaw channels capabilities --channel discord --target channel:<channel-id>.
  • Responsiviteitscontroles voor WhatsApp bij verslechterde eventloopgezondheid van de Gateway terwijl lokale TUI-clients nog draaien; --fix stopt alleen geverifieerde lokale TUI-clients.
  • Reparatie van Codex-routes voor legacy openai-codex/*-modelrefs in primaire modellen, fallbacks, heartbeat-/subagent-/compaction-overschrijvingen, hooks, kanaalmodeloverschrijvingen en sessieroutepins; --fix herschrijft ze naar openai/*, verwijdert verouderde runtimepins voor sessie/volledige agent en laat canonieke OpenAI-agentrefs op de standaard Codex-harness staan.
  • Audit van supervisorconfiguratie (launchd/systemd/schtasks) met optionele reparatie.
  • Opschoning van embedded proxy-omgeving voor Gateway-services die tijdens installatie of update shellwaarden HTTP_PROXY / HTTPS_PROXY / NO_PROXY hebben vastgelegd.
  • Best-practicecontroles voor Gateway-runtime (Node versus Bun, paden van versiebeheerders).
  • Diagnostiek voor Gateway-poortconflicten (standaard 18789).
  • Beveiligingswaarschuwingen voor open DM-beleid.
  • Gateway-authcontroles voor lokale tokenmodus (biedt tokengeneratie aan wanneer er geen tokenbron bestaat; overschrijft geen token-SecretRef-configuraties).
  • Detectie van problemen met apparaatkoppeling (wachtende eerste koppelverzoeken, wachtende rol-/scope-upgrades, drift in verouderde lokale apparaat-tokencache en authdrift in gekoppelde records).
  • systemd-linger-controle op Linux.
  • Controle van bestandsgrootte van workspace-bootstrapbestanden (waarschuwingen voor truncatie/bijna-limiet voor contextbestanden).
  • Gereedheidscontrole voor Skills voor de standaardagent; rapporteert toegestane skills met ontbrekende bins, env, config of OS-vereisten, en --fix kan niet-beschikbare skills uitschakelen in skills.entries.
  • Statuscontrole en automatische installatie/upgrade van shellaanvulling.
  • Gereedheidscontrole voor embeddingprovider voor geheugenzoekopdrachten (lokaal model, externe API-sleutel of QMD-binary).
  • Controles voor broninstallatie (pnpm-workspace-mismatch, ontbrekende UI-assets, ontbrekende tsx-binary).
  • Schrijft bijgewerkte configuratie + wizardmetadata.

​
Backfill en reset voor Dreams UI

De Dreams-scène van de Control UI bevat acties Backfill, Reset en Clear Grounded voor de grounded dreaming-workflow. Deze acties gebruiken RPC-methoden in doctor-stijl van de Gateway, maar ze maken geen deel uit van de reparatie/migratie van de openclaw doctor CLI. Wat ze doen:
  • Backfill scant historische memory/YYYY-MM-DD.md-bestanden in de actieve workspace, voert de grounded REM-dagboekpass uit en schrijft omkeerbare backfill-items naar DREAMS.md.
  • Reset verwijdert alleen die gemarkeerde backfill-dagboekitems uit DREAMS.md.
  • Clear Grounded verwijdert alleen gestagede grounded-only kortetermijnitems die uit historische replay kwamen en nog geen live recall of dagelijkse ondersteuning hebben opgebouwd.
Wat ze zelf niet doen:
  • ze bewerken MEMORY.md niet
  • ze voeren geen volledige doctor-migraties uit
  • ze stagen grounded candidates niet automatisch naar de live kortetermijnpromotiestore tenzij je eerst expliciet het gestagede CLI-pad uitvoert
Als je wilt dat grounded historische replay de normale diepe promotielaan beïnvloedt, gebruik dan in plaats daarvan de CLI-flow: 
openclaw memory rem-backfill --path ./memory --stage-short-term
Dat staget grounded durable candidates naar de short-term dreaming-store terwijl DREAMS.md het reviewoppervlak blijft.

​
Gedetailleerd gedrag en rationale

Als dit een git-checkout is en doctor interactief draait, biedt het aan om te updaten (fetch/rebase/build) voordat doctor wordt uitgevoerd.
Als de configuratie legacy-waardevormen bevat (bijvoorbeeld messages.ackReaction zonder kanaalspecifieke overschrijving), normaliseert doctor ze naar het huidige schema.Dat omvat legacy platte Talk-velden. De huidige openbare Talk-speechconfiguratie is talk.provider + talk.providers.<provider>, en realtime-spraakconfiguratie is talk.realtime.*. Doctor herschrijft oude talk.voiceId / talk.voiceAliases / talk.modelId / talk.outputFormat / talk.apiKey-vormen naar de providermap, en herschrijft legacy realtime-selectors op topniveau (talk.mode, talk.transport, talk.brain, talk.model, talk.voice) naar talk.realtime.Doctor waarschuwt ook wanneer plugins.allow niet leeg is en toolbeleid wildcard- of plugin-eigen toolitems gebruikt. tools.allow: ["*"] matcht alleen tools van plugins die daadwerkelijk laden; het omzeilt de exclusieve plugin- allowlist niet. Doctor schrijft plugins.bundledDiscovery: "compat" voor gemigreerde legacy allowlist-configuraties om bestaand gedrag van gebundelde providers te behouden, en wijst daarna naar de strengere instelling "allowlist".
Wanneer de configuratie verouderde sleutels bevat, weigeren andere opdrachten te draaien en vragen ze je om openclaw doctor uit te voeren.Doctor zal:
  • Uitleggen welke legacy-sleutels zijn gevonden.
  • De migratie tonen die is toegepast.
  • ~/.openclaw/openclaw.json herschrijven met het bijgewerkte schema.
Gateway-startup weigert legacy-configuratieformaten en vraagt je om openclaw doctor --fix uit te voeren; het herschrijft openclaw.json niet bij startup. Cron-taakstoremigraties worden ook afgehandeld door openclaw doctor --fix.Huidige migraties:
  • 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
  • channels.telegram.requireMention → channels.telegram.groups."*".requireMention
  • geconfigureerde kanaalconfiguraties zonder zichtbaar antwoordbeleid → messages.groupChat.visibleReplies: "message_tool"
  • routing.queue → messages.queue
  • routing.bindings → bovenliggend bindings
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • verouderde talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + talk.providers.<provider>
  • verouderde bovenliggende realtime Talk-selectors (talk.mode/talk.transport/talk.brain/talk.model/talk.voice) + talk.provider/talk.providers → talk.realtime
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • messages.tts.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
  • messages.tts.provider: "edge" en messages.tts.providers.edge → messages.tts.provider: "microsoft" en messages.tts.providers.microsoft
  • 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.tts.provider: "edge" en plugins.entries.voice-call.config.tts.providers.edge → provider: "microsoft" en providers.microsoft
  • 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
  • Verplaats voor kanalen met benoemde accounts maar achtergebleven kanaalwaarden op bovenliggend niveau voor één account die accountgebonden waarden naar het gepromoveerde account dat voor dat kanaal is gekozen (accounts.default voor de meeste kanalen; Matrix kan een bestaand overeenkomend benoemd/default-doel behouden)
  • 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
  • verwijder agents.defaults.llm; gebruik models.providers.<id>.timeoutSeconds voor time-outs van trage providers/modellen
  • browser.ssrfPolicy.allowPrivateNetwork → browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
  • browser.profiles.*.driver: "extension" → "existing-session"
  • verwijder browser.relayBindHost (verouderde relaisinstelling voor extensies)
  • verouderde models.providers.*.api: "openai" → "openai-completions" (Gateway-opstarten slaat ook providers over waarvan api is ingesteld op een toekomstige of onbekende enumwaarde in plaats van gesloten te falen)
  • verwijder plugins.entries.codex.config.codexDynamicToolsProfile; de Codex-appserver houdt Codex-native werkruimtetools altijd native
Doctor-waarschuwingen bevatten ook begeleiding voor account-defaults bij kanalen met meerdere accounts:
  • Als twee of meer channels.<channel>.accounts-items zijn geconfigureerd zonder channels.<channel>.defaultAccount of accounts.default, waarschuwt doctor dat fallbackroutering een onverwacht account kan kiezen.
  • Als channels.<channel>.defaultAccount is ingesteld op een onbekende account-ID, waarschuwt doctor en vermeldt hij de geconfigureerde account-ID’s.
Als je models.providers.opencode, opencode-zen of opencode-go handmatig hebt toegevoegd, overschrijft dit de ingebouwde OpenCode-catalogus van @mariozechner/pi-ai. Daardoor kunnen modellen op de verkeerde API worden gezet of kunnen kosten op nul worden gezet. Doctor waarschuwt zodat je de overschrijving kunt verwijderen en API-routering + kosten per model kunt herstellen.
Als je browserconfiguratie nog naar het verwijderde Chrome-extensiepad verwijst, normaliseert doctor die naar het huidige hostlokale Chrome MCP-koppelmodel:
  • browser.profiles.*.driver: "extension" wordt "existing-session"
  • browser.relayBindHost wordt verwijderd
Doctor controleert ook het hostlokale Chrome MCP-pad wanneer je defaultProfile: "user" of een geconfigureerd existing-session-profiel gebruikt:
  • controleert of Google Chrome op dezelfde host is geïnstalleerd voor standaardprofielen met automatisch verbinden
  • controleert de gedetecteerde Chrome-versie en waarschuwt wanneer die lager is dan Chrome 144
  • herinnert je eraan om foutopsporing op afstand in de inspectiepagina van de browser in te schakelen (bijvoorbeeld chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging of edge://inspect/#remote-debugging)
Doctor kan de Chrome-instelling niet voor je inschakelen. Hostlokale Chrome MCP vereist nog steeds:
  • een Chromium-gebaseerde browser 144+ op de gateway-/node-host
  • de browser die lokaal draait
  • foutopsporing op afstand ingeschakeld in die browser
  • goedkeuring van de eerste toestemmingsprompt voor koppelen in de browser
Gereedheid gaat hier alleen over lokale koppelvereisten. Existing-session behoudt de huidige routelimieten van Chrome MCP; geavanceerde routes zoals responsebody, PDF-export, downloadonderschepping en batchacties vereisen nog steeds een beheerde browser of een raw CDP-profiel.Deze controle is niet van toepassing op Docker-, sandbox-, remote-browser- of andere headless-flows. Die blijven raw CDP gebruiken.
Wanneer een OpenAI Codex OAuth-profiel is geconfigureerd, test doctor het OpenAI-autorisatie-eindpunt om te controleren of de lokale Node/OpenSSL TLS-stack de certificaatketen kan valideren. Als de test mislukt met een certificaatfout (bijvoorbeeld UNABLE_TO_GET_ISSUER_CERT_LOCALLY, een verlopen certificaat of een zelfondertekend certificaat), toont doctor platformspecifieke herstelbegeleiding. Op macOS met een Homebrew Node is de oplossing meestal brew postinstall ca-certificates. Met --deep wordt de test ook uitgevoerd als de gateway gezond is.
Als je eerder verouderde OpenAI-transportinstellingen onder models.providers.openai-codex hebt toegevoegd, kunnen die het ingebouwde Codex OAuth-providerpad overschaduwen dat nieuwere releases automatisch gebruiken. Doctor waarschuwt wanneer hij die oude transportinstellingen naast Codex OAuth ziet, zodat je de verouderde transportoverschrijving kunt verwijderen of herschrijven en het ingebouwde routerings-/fallbackgedrag terugkrijgt. Aangepaste proxy’s en alleen-headeroverschrijvingen worden nog steeds ondersteund en activeren deze waarschuwing niet.
Doctor controleert op verouderde openai-codex/*-modelrefs. Native Codex-harnessroutering gebruikt canonieke openai/*-modelrefs; OpenAI-agentbeurten lopen via de Codex-appserverharness in plaats van via het OpenClaw PI OpenAI-pad.In de modus --fix / --repair herschrijft doctor betrokken default-agent- en per-agentrefs, inclusief primaire modellen, fallbacks, heartbeat-/subagent-/compaction-overschrijvingen, hooks, kanaalmodeloverschrijvingen en verouderde persistente sessieroutestatus:
  • openai-codex/gpt-* wordt openai/gpt-*.
  • Codex-intent gaat naar provider-/modelgebonden agentRuntime.id: "codex"-items voor gerepareerde agentmodelrefs, zodat openai-codex:...-authprofielen nog steeds kunnen worden geselecteerd nadat de modelref openai/* wordt.
  • Verouderde runtimeconfiguratie voor de hele agent en persistente sessieruntimepins worden verwijderd omdat runtimeselectie provider-/modelgebonden is.
  • Bestaand provider-/modelruntimebeleid blijft behouden, tenzij de gerepareerde verouderde modelref Codex-routering nodig heeft om het oude authpad te behouden.
  • Bestaande modelfallbacklijsten blijven behouden met herschreven verouderde items; gekopieerde instellingen per model verhuizen van de verouderde sleutel naar de canonieke openai/*-sleutel.
  • Persistente sessie-modelProvider/providerOverride, model/modelOverride, fallbackmeldingen en authprofielpins worden gerepareerd in alle ontdekte sessiestores van agents.
  • /codex ... betekent “beheer of bind een native Codex-gesprek vanuit chat.”
  • /acp ... of runtime: "acp" betekent “gebruik de externe ACP/acpx-adapter.”
Doctor scant ontdekte sessiestores van agents ook op verouderde automatisch aangemaakte routestatus nadat je geconfigureerde modellen of runtime hebt verplaatst weg van een plugin-eigen route zoals Codex.openclaw doctor --fix kan automatisch aangemaakte verouderde status wissen, zoals modelOverrideSource: "auto"-modelpins, runtimemodelmetadata, gepinde harness-ID’s, CLI-sessiebindingen en automatische authprofieloverschrijvingen wanneer hun eigenaarroute niet langer is geconfigureerd. Expliciete modelkeuzes van gebruikers of verouderde sessies worden gemeld voor handmatige beoordeling en blijven ongemoeid; wijzig ze met /model ..., /new of reset de sessie wanneer die route niet langer bedoeld is.
Doctor kan oudere schijfindelingen migreren naar de huidige structuur:
  • Sessiestore + transcripties:
    • van ~/.openclaw/sessions/ naar ~/.openclaw/agents/<agentId>/sessions/
  • Agentmap:
    • van ~/.openclaw/agent/ naar ~/.openclaw/agents/<agentId>/agent/
  • WhatsApp-authstatus (Baileys):
    • van verouderde ~/.openclaw/credentials/*.json (behalve oauth.json)
    • naar ~/.openclaw/credentials/whatsapp/<accountId>/... (standaardaccount-ID: default)
Deze migraties zijn best-effort en idempotent; doctor geeft waarschuwingen wanneer hij verouderde mappen als back-ups achterlaat. De Gateway/CLI migreert de verouderde sessies + agentmap ook automatisch bij het opstarten, zodat geschiedenis/auth/modellen in het pad per agent terechtkomen zonder handmatige doctor-run. Normalisatie van Talk-provider/provider-map vergelijkt nu op structurele gelijkheid, zodat verschillen die alleen door sleutelvolgorde ontstaan niet langer herhaalde no-op doctor --fix-wijzigingen veroorzaken.
Doctor scant alle geïnstalleerde pluginmanifesten op verouderde capabilitiesleutels op bovenliggend niveau (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders). Wanneer ze worden gevonden, biedt hij aan om ze naar het contracts-object te verplaatsen en het manifestbestand ter plekke te herschrijven. Deze migratie is idempotent; als de contracts-sleutel al dezelfde waarden heeft, wordt de verouderde sleutel verwijderd zonder de gegevens te dupliceren.
Doctor controleert ook de Cron-taakstore (standaard ~/.openclaw/cron/jobs.json, of cron.store wanneer overschreven) op oude taakvormen die de scheduler nog steeds accepteert voor compatibiliteit.Huidige cronopschoningen omvatten:
  • jobId → id
  • schedule.cron → schedule.expr
  • payloadvelden op topniveau (message, model, thinking, …) → payload
  • leveringsvelden op topniveau (deliver, channel, to, provider, …) → delivery
  • payload-provider-leveringsaliassen → expliciete delivery.channel
  • eenvoudige legacy notify: true Webhook-fallbackjobs → expliciete delivery.mode="webhook" met delivery.to=cron.webhook
Doctor migreert notify: true-jobs alleen automatisch wanneer dat kan zonder gedrag te veranderen. Als een job legacy notify-fallback combineert met een bestaande niet-Webhook-leveringsmodus, waarschuwt doctor en laat die job staan voor handmatige beoordeling.Op Linux waarschuwt doctor ook wanneer de crontab van de gebruiker nog steeds legacy ~/.openclaw/bin/ensure-whatsapp.sh aanroept. Dat hostlokale script wordt niet onderhouden door de huidige OpenClaw en kan valse Gateway inactive-berichten naar ~/.openclaw/logs/whatsapp-health.log schrijven wanneer Cron de systemd-gebruikersbus niet kan bereiken. Verwijder de verouderde crontab-entry met crontab -e; gebruik openclaw channels status --probe, openclaw doctor en openclaw gateway status voor huidige gezondheidscontroles.
Doctor scant elke sessiemap van agents op verouderde write-lockbestanden — bestanden die zijn achtergebleven wanneer een sessie abnormaal is afgesloten. Voor elk gevonden lockbestand rapporteert het: het pad, de PID, of de PID nog actief is, de leeftijd van de lock en of deze als verouderd wordt beschouwd (dode PID, ouder dan 30 minuten, of een actieve PID waarvan kan worden bewezen dat die bij een niet-OpenClaw-proces hoort). In --fix- / --repair-modus verwijdert het verouderde lockbestanden automatisch; anders drukt het een opmerking af en geeft het de instructie om opnieuw uit te voeren met --fix.
Doctor scant JSONL-bestanden van agent-sessies op de gedupliceerde branchvorm die is aangemaakt door de prompt-transcript-herschrijffout van 2026.4.24: een verlaten gebruikersbeurt met interne OpenClaw-runtimecontext plus een actieve sibling met dezelfde zichtbare gebruikersprompt. In --fix- / --repair-modus maakt doctor naast het origineel een back-up van elk getroffen bestand en herschrijft het transcript naar de actieve branch, zodat Gateway-geschiedenis en geheugenlezers geen dubbele beurten meer zien.
De statusmap is de operationele hersenstam. Als die verdwijnt, verlies je sessies, referenties, logs en configuratie (tenzij je elders back-ups hebt).Doctor controleert:
  • Statusmap ontbreekt: waarschuwt voor catastrofaal statusverlies, vraagt om de map opnieuw aan te maken en herinnert je eraan dat het ontbrekende gegevens niet kan herstellen.
  • Machtigingen van statusmap: verifieert schrijfbaarheid; biedt aan om machtigingen te herstellen (en geeft een chown-hint wanneer een mismatch in eigenaar/groep wordt gedetecteerd).
  • macOS-cloudgesynchroniseerde statusmap: waarschuwt wanneer status onder iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) of ~/Library/CloudStorage/... wordt gevonden, omdat door synchronisatie ondersteunde paden tragere I/O en lock-/synchronisatieraces kunnen veroorzaken.
  • Linux SD- of eMMC-statusmap: waarschuwt wanneer status naar een mmcblk*-mountbron verwijst, omdat willekeurige I/O op SD of eMMC trager kan zijn en sneller kan slijten bij sessie- en referentiewrites.
  • Sessiemappen ontbreken: sessions/ en de sessiestoremap zijn vereist om geschiedenis te bewaren en ENOENT-crashes te voorkomen.
  • Transcript komt niet overeen: waarschuwt wanneer recente sessie-items ontbrekende transcriptbestanden hebben.
  • Hoofdsessie “1-regel JSONL”: markeert wanneer het hoofdtranscript slechts één regel heeft (geschiedenis stapelt zich niet op).
  • Meerdere statusmappen: waarschuwt wanneer meerdere ~/.openclaw-mappen bestaan verspreid over homedirectories of wanneer OPENCLAW_STATE_DIR ergens anders naartoe wijst (geschiedenis kan tussen installaties worden opgesplitst).
  • Herinnering voor externe modus: als gateway.mode=remote, herinnert doctor je eraan het op de externe host uit te voeren (de status bevindt zich daar).
  • Machtigingen van configuratiebestand: waarschuwt als ~/.openclaw/openclaw.json leesbaar is voor groep/wereld en biedt aan dit aan te scherpen naar 600.
Doctor inspecteert OAuth-profielen in de auth-store, waarschuwt wanneer tokens bijna verlopen of verlopen zijn en kan ze vernieuwen wanneer dat veilig is. Als het Anthropic OAuth-/tokenprofiel verouderd is, stelt het een Anthropic API-sleutel of het Anthropic setup-tokenpad voor. Vernieuwingsprompts verschijnen alleen wanneer interactief wordt uitgevoerd (TTY); --non-interactive slaat vernieuwingspogingen over.Wanneer een OAuth-vernieuwing permanent mislukt (bijvoorbeeld refresh_token_reused, invalid_grant, of een provider die aangeeft dat je opnieuw moet inloggen), meldt doctor dat opnieuw authenticeren vereist is en drukt het de exacte uit te voeren openclaw models auth login --provider ...-opdracht af.Doctor rapporteert ook auth-profielen die tijdelijk onbruikbaar zijn door:
  • korte cooldowns (rate limits/time-outs/authenticatiefouten)
  • langere uitschakelingen (facturerings-/tegoedfouten)
Als hooks.gmail.model is ingesteld, valideert doctor de modelreferentie tegen de catalogus en allowlist en waarschuwt het wanneer deze niet kan worden opgelost of niet is toegestaan.
Wanneer sandboxing is ingeschakeld, controleert doctor Docker-images en biedt het aan om te bouwen of over te schakelen naar legacy namen als de huidige image ontbreekt.
Doctor verwijdert legacy door OpenClaw gegenereerde stagingstatus voor Plugin-afhankelijkheden in openclaw doctor --fix- / openclaw doctor --repair-modus. Dit omvat verouderde gegenereerde afhankelijkheidsroots, oude install-stage-mappen, package-lokale restanten van eerdere gebundelde-Plugin-afhankelijkheidsreparatiecode en verweesde of herstelde beheerde npm-kopieen van gebundelde @openclaw/*-plugins die het huidige gebundelde manifest kunnen overschaduwen.Doctor kan ook ontbrekende downloadbare plugins opnieuw installeren wanneer configuratie ernaar verwijst maar het lokale Plugin-register ze niet kan vinden. Voorbeelden zijn materiele plugins.entries, geconfigureerde kanaal-/provider-/zoekinstellingen en geconfigureerde agent-runtimes. Tijdens package-updates vermijdt doctor het uitvoeren van package-manager-Plugin-reparatie terwijl het kernpackage wordt vervangen; voer openclaw doctor --fix opnieuw uit na de update als een geconfigureerde Plugin nog steeds herstel nodig heeft. Gateway-opstart en configuratie-herladen voeren geen package managers uit; Plugin-installaties blijven expliciet doctor-/install-/updatewerk.
Doctor detecteert legacy Gateway-services (launchd/systemd/schtasks) en biedt aan deze te verwijderen en de OpenClaw-service te installeren met de huidige Gateway-poort. Het kan ook scannen op extra Gateway-achtige services en opschoonhints afdrukken. OpenClaw Gateway-services met profielnamen worden als volwaardig beschouwd en niet als “extra” gemarkeerd.Op Linux installeert doctor niet automatisch een tweede service op gebruikersniveau als de Gateway-service op gebruikersniveau ontbreekt maar er een OpenClaw Gateway-service op systeemniveau bestaat. Inspecteer met openclaw gateway status --deep of openclaw doctor --deep, verwijder vervolgens het duplicaat of stel OPENCLAW_SERVICE_REPAIR_POLICY=external in wanneer een systeem-supervisor de Gateway-levenscyclus beheert.
Wanneer een Matrix-kanaalaccount een wachtende of uitvoerbare legacy statusmigratie heeft, maakt doctor (in --fix- / --repair-modus) een pre-migratiesnapshot en voert daarna de best-effort migratiestappen uit: legacy Matrix-statusmigratie en legacy versleutelde-statusvoorbereiding. Beide stappen zijn niet-fataal; fouten worden gelogd en het opstarten gaat door. In read-onlymodus (openclaw doctor zonder --fix) wordt deze controle volledig overgeslagen.
Doctor inspecteert nu de apparaatkoppelingsstatus als onderdeel van de normale gezondheidsronde.Wat het rapporteert:
  • wachtende eerste koppelingsverzoeken
  • wachtende rolupgrades voor al gekoppelde apparaten
  • wachtende scope-upgrades voor al gekoppelde apparaten
  • reparaties van publieke-sleutel-mismatches waarbij de apparaat-id nog steeds overeenkomt maar de apparaatidentiteit niet meer overeenkomt met het goedgekeurde record
  • gekoppelde records zonder actief token voor een goedgekeurde rol
  • gekoppelde tokens waarvan de scopes buiten de goedgekeurde koppelingsbaseline zijn gedrift
  • lokaal gecachete apparaattoken-items voor de huidige machine die ouder zijn dan een tokenrotatie aan Gateway-zijde of verouderde scope-metadata bevatten
Doctor keurt koppelingsverzoeken niet automatisch goed en roteert apparaattokens niet automatisch. Het drukt in plaats daarvan de exacte volgende stappen af:
  • inspecteer wachtende verzoeken met openclaw devices list
  • keur het exacte verzoek goed met openclaw devices approve <requestId>
  • roteer een vers token met openclaw devices rotate --device <deviceId> --role <role>
  • verwijder een verouderd record en keur het opnieuw goed met openclaw devices remove <deviceId>
Dit sluit het veelvoorkomende gat “al gekoppeld maar nog steeds koppeling vereist”: doctor onderscheidt nu eerste koppeling van wachtende rol-/scope-upgrades en van verouderde token-/apparaatidentiteitsdrift.
Doctor geeft waarschuwingen wanneer een provider openstaat voor DM’s zonder allowlist, of wanneer een beleid op een gevaarlijke manier is geconfigureerd.
Als het als systemd-gebruikersservice draait, zorgt doctor ervoor dat lingering is ingeschakeld zodat de Gateway na uitloggen actief blijft.
Doctor drukt een samenvatting af van de werkruimtestatus voor de standaardagent:
  • Skills-status: telt geschikte Skills, Skills met ontbrekende vereisten en door allowlist geblokkeerde Skills.
  • Legacy werkruimtemappen: waarschuwt wanneer ~/openclaw of andere legacy werkruimtemappen naast de huidige werkruimte bestaan.
  • Plugin-status: telt ingeschakelde/uitgeschakelde/mislukte plugins; vermeldt Plugin-ID’s voor eventuele fouten; rapporteert mogelijkheden van bundle-plugins.
  • Plugin-compatibiliteitswaarschuwingen: markeert plugins die compatibiliteitsproblemen hebben met de huidige runtime.
  • Plugin-diagnostiek: toont eventuele laadwaarschuwingen of fouten die door het Plugin-register zijn uitgegeven.
Doctor controleert of werkruimte-bootstrapbestanden (bijvoorbeeld AGENTS.md, CLAUDE.md of andere geinjecteerde contextbestanden) dicht bij of boven het geconfigureerde tekenbudget zitten. Het rapporteert per bestand ruwe versus geinjecteerde tekentellingen, truncatiepercentage, truncatieoorzaak (max/file of max/total) en het totaal aantal geinjecteerde tekens als fractie van het totale budget. Wanneer bestanden worden getrunceerd of dicht bij de limiet zitten, drukt doctor tips af voor het afstellen van agents.defaults.bootstrapMaxChars en agents.defaults.bootstrapTotalMaxChars.
Wanneer openclaw doctor --fix een ontbrekende kanaal-Plugin verwijdert, verwijdert het ook de loshangende kanaalgebonden configuratie die naar die Plugin verwees: channels.<id>-items, Heartbeat-doelen die het kanaal noemden en agents.*.models["<channel>/*"]-overrides. Dit voorkomt Gateway-opstartlussen waarbij de kanaalruntime verdwenen is maar de configuratie de Gateway nog steeds vraagt zich eraan te binden.
Doctor controleert of tabaanvulling is geinstalleerd voor de huidige shell (zsh, bash, fish of PowerShell):
  • Als het shellprofiel een traag dynamisch aanvullingspatroon gebruikt (source <(openclaw completion ...)), upgradet doctor dit naar de snellere variant met gecachet bestand.
  • Als aanvulling in het profiel is geconfigureerd maar het cachebestand ontbreekt, regenereert doctor de cache automatisch.
  • Als er helemaal geen aanvulling is geconfigureerd, vraagt doctor om deze te installeren (alleen interactieve modus; overgeslagen met --non-interactive).
Voer openclaw completion --write-state uit om de cache handmatig opnieuw te genereren.
Doctor controleert of lokale Gateway-tokenauthenticatie gereed is.
  • Als tokenmodus een token nodig heeft en er geen tokenbron bestaat, biedt doctor aan er een te genereren.
  • Als gateway.auth.token door SecretRef wordt beheerd maar niet beschikbaar is, waarschuwt doctor en overschrijft het niet met platte tekst.
  • openclaw doctor --generate-gateway-token forceert generatie alleen wanneer er geen token-SecretRef is geconfigureerd.
Sommige reparatiestromen moeten geconfigureerde inloggegevens inspecteren zonder het fail-fast-gedrag tijdens runtime te verzwakken.
  • openclaw doctor --fix gebruikt nu hetzelfde alleen-lezen SecretRef-samenvattingsmodel als statusfamilie-opdrachten voor gerichte configuratiereparaties.
  • Voorbeeld: Telegram allowFrom / groupAllowFrom @username-reparatie probeert geconfigureerde botinloggegevens te gebruiken wanneer die beschikbaar zijn.
  • Als het Telegram-bottoken via SecretRef is geconfigureerd maar niet beschikbaar is in het huidige opdrachtpad, meldt doctor dat de inloggegevens geconfigureerd-maar-onbeschikbaar zijn en slaat automatische resolutie over in plaats van te crashen of het token onterecht als ontbrekend te rapporteren.
Doctor voert een gezondheidscontrole uit en biedt aan de Gateway opnieuw te starten wanneer die ongezond lijkt.
Doctor controleert of de geconfigureerde embeddingprovider voor geheugenzoekopdrachten gereed is voor de standaardagent. Het gedrag hangt af van de geconfigureerde backend en provider:
  • QMD-backend: controleert of het qmd-binaire bestand beschikbaar en startbaar is. Zo niet, dan wordt hersteladvies afgedrukt, inclusief het npm-pakket en een optie voor een handmatig binair pad.
  • Expliciete lokale provider: controleert op een lokaal modelbestand of een herkende externe/downloadbare model-URL. Als die ontbreekt, wordt voorgesteld om over te schakelen naar een externe provider.
  • Expliciete externe provider (openai, voyage, enz.): verifieert dat er een API-sleutel aanwezig is in de omgeving of auth store. Drukt bruikbare hersteltips af als die ontbreekt.
  • Automatische provider: controleert eerst de beschikbaarheid van het lokale model en probeert daarna elke externe provider in automatische-selectievolgorde.
Wanneer een gecachet Gateway-proberesultaat beschikbaar is (de Gateway was gezond op het moment van de controle), vergelijkt doctor het resultaat met de voor de CLI zichtbare configuratie en meldt eventuele verschillen. Doctor start geen nieuwe embedding-ping op het standaardpad; gebruik de diepe geheugenstatusopdracht wanneer je een live providercontrole wilt.Gebruik openclaw memory status --deep om de embeddinggereedheid tijdens runtime te verifiëren.
Als de Gateway gezond is, voert doctor een kanaalstatusprobe uit en rapporteert waarschuwingen met voorgestelde oplossingen.
Doctor controleert de geïnstalleerde supervisorconfiguratie (launchd/systemd/schtasks) op ontbrekende of verouderde standaardwaarden (bijv. systemd network-online-afhankelijkheden en herstartvertraging). Wanneer er een afwijking wordt gevonden, beveelt het een update aan en kan het het servicebestand/de taak herschrijven naar de huidige standaardwaarden.Opmerkingen:
  • openclaw doctor vraagt om bevestiging voordat supervisorconfiguratie wordt herschreven.
  • openclaw doctor --yes accepteert de standaardreparatieprompts.
  • openclaw doctor --repair past aanbevolen oplossingen toe zonder prompts.
  • openclaw doctor --repair --force overschrijft aangepaste supervisorconfiguraties.
  • OPENCLAW_SERVICE_REPAIR_POLICY=external houdt doctor alleen-lezen voor de Gateway-servicelevenscyclus. Het rapporteert nog steeds servicestatus en voert niet-servicegerelateerde reparaties uit, maar slaat service-installatie/start/herstart/bootstrap, herschrijvingen van supervisorconfiguratie en opschoning van legacy services over omdat een externe supervisor die levenscyclus beheert.
  • Op Linux herschrijft doctor geen opdracht-/entrypointmetadata terwijl de overeenkomende systemd-Gateway-unit actief is. Het negeert ook inactieve niet-legacy extra Gateway-achtige units tijdens de scan op dubbele services, zodat begeleidende servicebestanden geen opschoningsruis veroorzaken.
  • Als tokenauthenticatie een token vereist en gateway.auth.token door SecretRef wordt beheerd, valideert doctor bij service-installatie/-reparatie de SecretRef maar bewaart het geen opgeloste platte-teksttokenwaarden in de omgevingsmetadata van de supervisorservice.
  • Doctor detecteert beheerde .env/SecretRef-ondersteunde serviceomgevingswaarden die oudere LaunchAgent-, systemd- of Windows Scheduled Task-installaties inline hebben ingesloten en herschrijft de servicemetadata zodat die waarden vanuit de runtimebron worden geladen in plaats van vanuit de supervisordefinitie.
  • Doctor detecteert wanneer de serviceopdracht nog steeds een oude --port vastzet nadat gateway.port is gewijzigd en herschrijft de servicemetadata naar de huidige poort.
  • Als tokenauthenticatie een token vereist en de geconfigureerde token-SecretRef niet is opgelost, blokkeert doctor het installatie-/reparatiepad met bruikbare aanwijzingen.
  • Als zowel gateway.auth.token als gateway.auth.password zijn geconfigureerd en gateway.auth.mode niet is ingesteld, blokkeert doctor installatie/reparatie totdat de modus expliciet is ingesteld.
  • Voor Linux user-systemd-units omvatten doctortokendriftcontroles nu zowel Environment=- als EnvironmentFile=-bronnen bij het vergelijken van service-authmetadata.
  • Doctor-servicereparaties weigeren een Gateway-service van een ouder OpenClaw-binair bestand te herschrijven, stoppen of herstarten wanneer de configuratie voor het laatst door een nieuwere versie is geschreven. Zie Gateway-probleemoplossing.
  • Je kunt altijd een volledige herschrijving forceren via openclaw gateway install --force.
Doctor inspecteert de serviceruntime (PID, laatste exitstatus) en waarschuwt wanneer de service is geïnstalleerd maar niet daadwerkelijk draait. Het controleert ook op poortconflicten op de Gateway-poort (standaard 18789) en rapporteert waarschijnlijke oorzaken (Gateway draait al, SSH-tunnel).
Doctor waarschuwt wanneer de Gateway-service op Bun draait of op een versiebeheerd Node-pad (nvm, fnm, volta, asdf, enz.). WhatsApp- en Telegram-kanalen vereisen Node, en versiebeheerpaden kunnen na upgrades breken omdat de service je shell-init niet laadt. Doctor biedt aan te migreren naar een systeeminstallatie van Node wanneer die beschikbaar is (Homebrew/apt/choco).Nieuw geïnstalleerde of gerepareerde macOS LaunchAgents gebruiken een canoniek systeem-PATH (/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin) in plaats van het interactieve shell-PATH te kopiëren, zodat door Homebrew beheerde systeembinaries beschikbaar blijven terwijl Volta-, asdf-, fnm-, pnpm- en andere versiebeheermappen niet wijzigen welke Node-kinderprocessen worden gevonden. Linux-services behouden nog steeds expliciete omgevingsroots (NVM_DIR, FNM_DIR, VOLTA_HOME, ASDF_DATA_DIR, BUN_INSTALL, PNPM_HOME) en stabiele user-bin-mappen, maar geraden fallbackmappen van versiebeheerders worden alleen naar het service-PATH geschreven wanneer die mappen op schijf bestaan.
Doctor bewaart alle configuratiewijzigingen en stempelt wizardmetadata om de doctor-run vast te leggen.
Doctor stelt een geheugensysteem voor de werkruimte voor wanneer dat ontbreekt en drukt een back-uptip af als de werkruimte nog niet onder git staat.Zie /concepts/agent-workspace voor een volledige handleiding voor werkruimtestructuur en git-back-up (aanbevolen: privé GitHub of GitLab).

​
Gerelateerd