Doctor

openclaw doctor est l’outil de réparation et de migration pour OpenClaw. Il corrige les configurations/états obsolètes, vérifie la santé et fournit des étapes de réparation actionnables.

Quick start

openclaw doctor

Modes sans tête et d’automatisation

--yes--fix--lint--fix --force--non-interactive--deep

openclaw doctor --yes

Accepter les valeurs par défaut sans invitation (y compris les étapes de réparation de redémarrage/service/sandbox lorsque applicable).

openclaw doctor --fix

Appliquer les réparations recommandées sans invitation (réparations + redémarrages lorsque c’est sûr).

openclaw doctor --lint
openclaw doctor --lint --json

Exécuter des vérifications de santé structurées pour l’automatisation CI ou pré-vol. Ce mode est en lecture seule : il n’invite pas, ne répare pas, ne migre pas la configuration, ne redémarre pas les services ou ne touche pas à l’état.

openclaw doctor --fix --force

Appliquer également des réparations agressives (écrase les configurations de superviseur personnalisées).

openclaw doctor --non-interactive

Exécuter sans invites et n’appliquer que les migrations sûres (normalisation de la configuration + déplacements d’état sur disque). Ignore les actions de redémarrage/service/sandbox nécessitant une confirmation humaine. Les migrations d’état héritées s’exécutent automatiquement lorsqu’elles sont détectées.

openclaw doctor --deep

Rechercher dans les services système les installations de passerelle supplémentaires (launchd/systemd/schtasks).

Si vous souhaitez examiner les modifications avant l’écriture, ouvrez d’abord le fichier de configuration :

cat ~/.openclaw/openclaw.json

Mode lint en lecture seule

openclaw doctor --lint est le frère adapté à l’automatisation de openclaw doctor --fix. Les deux utilisent les vérifications de santé du doctor, mais leur posture est différente :

Mode	Invites	Écrit la config/l’état	Sortie	Utilisation
openclaw doctor	oui	non	rapport de santé convivial	un humain vérifiant le statut
openclaw doctor --fix	parfois	oui, avec une politique de réparation	journal de réparation convivial	application des réparations approuvées
openclaw doctor --lint	non	non	résultats structurés	CI, pré-vol et portes de révision

Les contrôles de santé modernisés peuvent fournir une implémentation repair() facultative. doctor --fix applique ces réparations lorsqu’elles existent et continue à utiliser le flux de réparation doctor existant pour les contrôles qui n’ont pas encore été migrés. Le contrat de réparation structuré sépare également le signalement des réparations de la détection : detect() signale les résultats actuels, tandis que repair() peut signaler des modifications, les différences de configuration/fichier et les effets secondaires hors fichier. Cela permet de garder la voie de migration ouverte pour les futurs doctor --fix --dry-run et la sortie de différences sans obliger les contrôles de lint à planifier des mutations.

Exemples :

openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --only core/doctor/gateway-config --json

La sortie JSON inclut :

• ok : indique si un résultat visible a atteint le seuil de gravité sélectionné
• checksRun : nombre de contrôles de santé exécutés
• checksSkipped : contrôles ignorés par --only ou --skip
• findings : diagnostics structurés avec checkId, severity, message et facultatif path, line, column, ocPath, et fixHint

Codes de sortie :

• 0 : aucun résultat au niveau ou au-dessus du seuil sélectionné
• 1 : un ou plusieurs résultats ont atteint le seuil sélectionné
• 2 : échec de la commande/à l’exécution avant que les résultats du lint ne puissent être émis

Utilisez --severity-min info|warning|error pour contrôler à la fois ce qui est imprimé et ce qui provoque une sortie de lint non nulle. Utilisez --only <id> pour des portes de pré-vol étroites et --skip <id> pour exclure temporairement une vérification bruyante tout en gardant le reste de l’exécution du lint actif. Les options de sortie de lint telles que --json, --severity-min, --only et --skip doivent être associées à --lint ; les exécutions régulières du docteur et des réparations les rejettent.

Ce qu’il fait (résumé)

Santé, interface utilisateur et mises à jour

• Mise à jour préalable facultative pour les installations git (mode interactif uniquement).
• Vérification de la fraîcheur du protocole d’interface (reconstruit l’interface de contrôle lorsque le schéma du protocole est plus récent).
• Vérification de la santé + invite de redémarrage.
• Résumé de l’état des Skills (éligibles/manquantes/bloquées) et état des plugins.

Config et migrations

• Normalisation de la configuration pour les valeurs héritées.
• Migration de la configuration Talk des champs talk.* plats hérités vers talk.provider + `talk.providers.

. - Vérifications de migration du navigateur pour les configurations d'extension Chrome héritées et la préparation Chrome MCP. - Avertissements de substitution de fournisseur OpenCode (models.providers.opencode/models.providers.opencode-go). - Migration du fournisseur/profil Codex OpenAI hérité (openai-codex→openai) et avertissements de masquage pour models.providers.openai-codexobsolètes. - Vérification des prérequis TLS OAuth pour les profils OpenAI Codex OAuth. - Avertissements de liste d'autorisation (allowlist) de plugin/tool lorsqueplugins.allow est restrictif mais que la stratégie d'outils demande toujours des outils génériques (wildcard) ou détenus par des plugins. - Migration de l'état sur disque hérité (sessions/répertoire agent/authentification WhatsApp). - Migration de la clé de contrat du manifeste de plugin héritée (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders→contracts). - Migration du magasin cron hérité (jobId, schedule.cron, champs de livraison/payload de niveau supérieur, payload provider, tâches de repli webhook notify: true). - Nettoyage de la stratégie d'exécution (runtime-policy) de l'agent entier héritée ; la stratégie d'exécution provider/model est le sélecteur d'itinéraire actif. - Nettoyage de la configuration de plugin obsolète lorsque les plugins sont activés ; lorsque plugins.enabled=false`, les références de plugin obsolètes sont traitées comme une configuration de confinement inerte et sont conservées.

État et intégrité

• Inspection du fichier de verrouillage de session et nettoyage des verrous obsolètes.
• Réparation des transcriptions de session pour les branches de réécriture de prompt dupliquées créées par les versions affectées du 24/04/2026.
• Détection des pierres tombales de redémarrage-récupération de sous-agent bloqué, avec --fix pour effacer les indicateurs obsolètes de récupération abandonnée afin que le démarrage ne continue pas à traiter l’enfant comme abandonné lors du redémarrage.
• Contrôles d’intégrité et d’autorisation de l’état (sessions, transcriptions, répertoire d’état).
• Contrôles des autorisations du fichier de configuration (chmod 600) lors d’une exécution locale.
• Santé de l’authentification du modèle : vérifie l’expiration OAuth, peut actualiser les jetons expirants et signale les états de refroidissement/désactivation du profil d’authentification.
• Détection de répertoire d’espace de travail supplémentaire (~/openclaw).

GatewayGateway, services and supervisors

• Réparation de l’image Sandbox lorsque le sandboxing est activé.
• Migration des services hérités et détection de passerelles supplémentaires.
• Migration de l’état hérité du channel Matrix (en mode --fix / --repairGateway).
• Vérifications de l’exécution de la passerelle (service installé mais non exécuté ; label launchd mis en cache).
• Avertissements de l’état du channel (sondés à partir de la passerelle en cours d’exécution).
• Les vérifications d’autorisation spécifiques au canal se trouvent sous openclaw channels capabilitiesDiscord ; par exemple, les autorisations du canal vocal Discord sont auditées avec `openclaw channels capabilities —channel discord —target channel:

WhatsAppGatewayTUI. - Vérifications de réactivité de WhatsApp pour une santé dégradée de la boucle d'événements de la passerelle alors que les clients TUI locaux sont toujours en cours d'exécution ; —fixTUI n'arrête que les clients TUI locaux vérifiés. - Réparation des routes Codex pour les références de model héritées openai-codex/dans les modèles principaux, les solutions de repli, les modèles de génération d'images/vidéos, les substitutions de battement de cœur/sous-agent/compactage, les hooks, les substitutions de model de channel et les épingles de route de session ;—fixles réécrit enopenai/, migre les profils/ordres d'auth openai-codex:versopenai:OpenAI, supprime les épingles d'exécution de session/agent entier obsolètes et laisse des références d'agent OpenAI canoniques sur le harnais Codex par défaut. - Audit de la configuration du superviseur (launchd/systemd/schtasks) avec réparation facultative. - Nettoyage de l'environnement de proxy intégré pour les services de passerelle qui ont capturé les valeurs shell HTTP_PROXY/HTTPS_PROXY/NO_PROXYGatewayBunGateway lors de l'installation ou de la mise à jour. - Vérifications des meilleures pratiques d'exécution de la passerelle (Node vs Bun, chemins du gestionnaire de versions). - Diagnostics des collisions de ports de passerelle (18789` par défaut).

Authentification, sécurité et appariement

• Avertissements de sécurité pour les politiques DM ouvertes.
• Vérifications d’authentification de la Gateway pour le mode de jeton local (propose la génération de jeton lorsqu’aucune source de jeton n’existe ; ne remplace pas les configurations SecretRef de jeton).
• Détection des problèmes d’appareil (demandes de premier appariement en attente, mises à niveau de rôle/portée en attente, dérive du cache du jeton d’appareil local périmé et dérive d’authentification de l’enregistrement apparié).

Espace de travail et shell

• Vérification de la persistance systemd sur Linux.
• Vérification de la taille du fichier d’amorçage de l’espace de travail (avertissements de troncation/proche de la limite pour les fichiers de contexte).
• Vérification de la disponibilité des compétences pour l’agent par défaut ; signale les compétences autorisées dont les binaires, les variables d’environnement, la configuration ou les exigences OS sont manquants, et --fix peut désactiver les compétences indisponibles dans skills.entries.
• Vérification de l’état de la complétion du shell et installation/mise à niveau automatique.
• Vérification de la disponibilité du fournisseur d’embeddings pour la recherche mémoire (modèle local, clé API distante, ou binaire QMD).
• Vérifications de l’installation source (inadéquation de l’espace de travail pnpm, assets UI manquants, binaire tsx manquant).
• Écrit la configuration mise à jour + les métadonnées de l’assistant.

Remplissage (backfill) et réinitialisation de Dreams UI

La scène Dreams de l’interface de contrôle Control UI comprend les actions Backfill (Remplissage), Reset (Réinitialisation) et Clear Grounded (Effacer Grounded) pour le workflow de rêve ancré (grounded dreaming). Ces actions utilisent des méthodes RPC de style docteur de passerelle, mais elles ne font pas partie de la réparation/migration du CLI openclaw doctor.

Ce qu’elles font :

• Le Backfill analyse les fichiers historiques memory/YYYY-MM-DD.md dans l’espace de travail actif, exécute la passe de journal REM ancrée, et écrit des entrées de remplissage réversibles dans DREAMS.md.
• Le Reset supprime uniquement ces entrées de journal de remplissage marquées de DREAMS.md.
• Clear Grounded supprime uniquement les entrées à court terme mises en scène et uniquement ancrées (grounded-only) provenant de la rediffusion historique et qui n’ont pas encore accumulé de rappel en direct ou de support quotidien.

Ce qu’elles ne font pas par elles-mêmes :

• ils ne modifient pas MEMORY.md
• elles n’exécutent pas les migrations complètes du docteur
• ils ne mettent pas automatiquement en scène les candidats ancrés dans le magasin de promotion à court terme en direct, sauf si vous exécutez explicitement d’abord le chemin de la CLI intermédiaire

Si vous souhaitez que la relecture historique ancrée influence la voie de promotion profonde normale, utilisez plutôt le flux CLI :

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

Cela met en scène les candidats durables ancrés dans le stockage de rêve à court terme tout en conservant DREAMS.md comme surface de révision.

Comportement détaillé et justification

0. Mise à jour facultative (installations git)

S’il s’agit d’une extraction git et que doctor s’exécute de manière interactive, il propose de mettre à jour (fetch/rebase/build) avant d’exécuter doctor.

1. Normalisation de la configuration

Si la configuration contient des formes de valeurs héritées (par exemple messages.ackReaction sans une priorité spécifique au channel), doctor les normalise dans le schéma actuel.

Cela inclut les champs plats hérités de Talk. La configuration publique actuelle de la parole Talk est talk.provider + `talk.providers.

, et la configuration vocale en temps réel est talk.realtime.*. Doctor réécrit les anciennes formes talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey dans la carte du provider, et réécrit les sélecteurs hérités de premier niveau en temps réel (talk.mode, talk.transport, talk.brain, talk.model, talk.voice) en talk.realtime`.

Doctor avertit également lorsque `plugins.allow` n'est pas vide et que la stratégie de tool utilise des entrées de tool avec caractères génériques ou appartenant à des plugins. `tools.allow: ["*"]` ne correspond qu'aux tools des plugins qui sont réellement chargés ; il ne contourne pas la liste d'autorisation exclusive des plugins.

2. Migration des clés de configuration héritées

Lorsque la configuration contient des clés obsolètes, les autres commandes refusent de s’exécuter et vous demandent d’exécuter openclaw doctor.

Doctor va :

• Expliquer quelles clés héritées ont été trouvées.
• Afficher la migration qu’il a appliquée.
• Réécrire ~/.openclaw/openclaw.json avec le schéma mis à jour.

Le démarrage de Gateway refuse les formats de configuration hérités et vous demande d’exécuter openclaw doctor --fix ; il ne réécrit pas openclaw.json au démarrage. Les migrations du magasin de tâches Cron sont également gérées par openclaw doctor --fix.

Migrations actuelles :

• 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
• supprimer les channels.webchat et gateway.webchat retirés
• routing.queue → messages.queue
• routing.bindings → bindings de premier niveau
• routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
• hérité talk.voiceId/talk.voiceAliases/talk.modelId/talk.outputFormat/talk.apiKey → talk.provider + `talk.providers.

- sélecteurs Talk temps réel hérités de premier niveau (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.

(openai/elevenlabs/microsoft/edge) → messages.tts.providers.

-messages.tts.provider: “edge”etmessages.tts.providers.edge→messages.tts.provider: “microsoft”etmessages.tts.providers.microsoft - Champs de sélection du locuteur TTS (voice/voiceName/voiceId) → speakerVoice/speakerVoiceId -channels.discord.voice.tts.

(openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.

-channels.discord.accounts.

.voice.tts.

(openai/elevenlabs/microsoft/edge) → channels.discord.accounts.

.voice.tts.providers.

-plugins.entries.voice-call.config.tts.

(openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.

-plugins.entries.voice-call.config.tts.provider: “edge”etplugins.entries.voice-call.config.tts.providers.edge→provider: “microsoft”etproviders.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 - Pour les channels avec unaccounts nommé mais des valeurs de channel de premier niveau à compte unique persistantes, déplacer ces valeurs étendues au compte vers le compte promu choisi pour ce channel (accounts.defaultpour la plupart des channels ; Matrix peut préserver une cible par défaut/nommée correspondante existante) -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 - supprimeragents.defaults.llm; utilisermodels.providers.

.timeoutSecondspour les délais d'expiration lents des providers/modèles, et garder le délai d'expiration de l'agent/exécution au-dessus de cette valeur lorsque l'exécution entière doit durer plus longtemps -browser.ssrfPolicy.allowPrivateNetwork→browser.ssrfPolicy.dangerouslyAllowPrivateNetwork -browser.profiles..driver: “extension”→”existing-session” - supprimerbrowser.relayBindHost(paramètre de relais d'extension hérité) - héritémodels.providers..api: “openai”→”openai-completions”(le démarrage de la passerelle ignore également les providers dont leapiest défini sur une valeur d'énumération future ou inconnue plutôt que d'échouer fermement) - supprimerplugins.entries.codex.config.codexDynamicToolsProfile` ; Codex app-server garde toujours les outils d’espace de travail natifs Codex natifs

Les avertissements de Doctor incluent également des recommandations par défaut de compte pour les channels multi-comptes :

- Si deux entrées `channels.

.accountsou plus sont configurées sanschannels.

.defaultAccountniaccounts.default, le docteur avertit que le routage de secours peut choisir un compte inattendu. - Si channels.

.defaultAccount` est défini sur un ID de compte inconnu, le docteur avertit et liste les IDs de compte configurés.

2b. Remplacements du fournisseur OpenCode

Si vous avez ajouté models.providers.opencode, opencode-zen ou opencode-go manuellement, cela remplace le catalogue OpenCode intégré de openclaw/plugin-sdk/llmAPIAPI. Cela peut forcer les modèles vers la mauvaise API ou annuler les coûts. Doctor vous avertit pour que vous puissiez supprimer le remplacement et restaurer le routage API par modèle + les coûts.

2c. Migration du navigateur et préparation de Chrome MCP

Si votre configuration de navigateur pointe toujours vers le chemin de l’extension Chrome supprimée, doctor la normalise vers le modèle d’attachement Chrome MCP hôte-local actuel :

• browser.profiles.*.driver: "extension" devient "existing-session"
• browser.relayBindHost est supprimé

Doctor audit également le chemin Chrome MCP hôte-local lorsque vous utilisez defaultProfile: "user" ou un profil existing-session configuré :

• vérifie si Google Chrome est installé sur le même hôte pour les profils de connexion automatique par défaut
• vérifie la version de Chrome détectée et avertit lorsqu’elle est inférieure à Chrome 144
• vous rappelle d’activer le débogage à distance dans la page d’inspection du navigateur (par exemple chrome://inspect/#remote-debugging, brave://inspect/#remote-debugging ou edge://inspect/#remote-debugging)

Doctor ne peut pas activer le paramètre côté Chrome pour vous. Chrome MCP hôte-local nécessite toujours :

• un navigateur basé sur Chromium 144+ sur l’hôte de la passerelle/du nœud
• le navigateur exécuté localement
• le débogage à distance activé dans ce navigateur
• l’approbation de la première invite de consentement d’attachement dans le navigateur

La préparation ici concerne uniquement les prérequis d’attachement local. Existing-session conserve les limites de routage Chrome MCP actuelles ; les routes avancées comme responsebodyDocker, l’exportation PDF, l’interception de téléchargement et les actions par lots nécessitent toujours un navigateur géré ou un profil CDP brut.

Cette vérification ne s’applique pas à Docker, sandbox, remote-browser ou d’autres flux sans interface. Ceux-ci continuent d’utiliser CDP brut.

OAuth2d. Prérequis TLS OAuth

Lorsqu’un profil OAuth Codex OpenAI est configuré, doctor sonde le point de terminaison d’autorisation macOS pour vérifier que la pile TLS locale Node/OpenSSL peut valider la chaîne de certificats. Si la sonde échoue avec une erreur de certificat (par exemple UNABLE_TO_GET_ISSUER_CERT_LOCALLY, certificat expiré ou auto-signé), doctor imprime des instructions de réparation spécifiques à la plateforme. Sur macOS avec un Node installé via Homebrew, la solution est généralement brew postinstall ca-certificates. Avec --deep, la sonde s’exécute même si la passerelle est en bonne santé.

OAuth2e. Remplacements du fournisseur OAuth Codex

Si vous avez précédemment ajouté des paramètres de transport hérités OpenAI sous models.providers.openai-codexOAuthOAuth, ils peuvent masquer le chemin du fournisseur OAuth Codex intégré que les nouvelles versions utilisent automatiquement. Doctor avertit lorsqu’il détecte ces anciens paramètres de transport en même temps qu’OAuth Codex afin que vous puissiez supprimer ou réécrire l’ancien remplacement de transport et récupérer le comportement de routage/secours intégré. Les proxies personnalisés et les remplacements d’en-têtes uniquement sont toujours pris en charge et ne déclenchent pas cet avertissement.

2f. Réparation de l'itinéraire Codex

Doctor vérifie les anciennes références de modèle openai-codex/*. Le routage du harnais Codex natif utilise des références de modèle canoniques openai/* ; les tours d’agent OpenAI passent par le harnais Codex app-server au lieu du chemin du fournisseur OpenClaw OpenAI.

En mode --fix / --repair, le docteur réécrit les références de l’agent par défaut et par agent affectées, y compris les modèles principaux, les solutions de repli, les modèles de génération d’images/vidéos, les substitutions de battement de cœur/sous-agent/compactage, les hooks, les substitutions de modèle de canal et l’état d’itinéraire de session persistant obsolète :

• openai-codex/gpt-* devient openai/gpt-*.
• L’intention Codex passe aux entrées agentRuntime.id: "codex" délimitées par fournisseur/modèle pour les références de modèle d’agent réparées.
• La configuration d’exécution obsolète de l’agent entier et les épingles d’exécution de session persistante sont supprimées car la sélection d’exécution est délimitée par fournisseur/modèle.
• La stratégie d’exécution existante du fournisseur/modèle est préservée, sauf si la référence de modèle héritée réparée a besoin du routage Codex pour conserver l’ancien chemin d’authentification.
• Les listes de repli de modèle existantes sont préservées avec leurs entrées héritées réécrites ; les paramètres copiés par modèle passent de la clé héritée à la clé canonique openai/*.
• Les sessions persistantes modelProvider/providerOverride, model/modelOverride, les avis de repli et les épingles de profil d’authentification sont réparés dans tous les magasins de sessions d’agent découverts.
• /codex ... signifie « contrôler ou lier une conversation Codex native depuis le chat ».
• /acp ... ou runtime: "acp" signifie « utiliser l’adaptateur ACP/acpx externe ».

2g. Nettoyage de la route de session

Doctor analyse également les magasins de sessions d’agent découverts pour détecter l’état de route obsolète créé automatiquement après avoir déplacé des modèles configurés ou l’exécution hors d’une route détenue par un plugin telle que Codex.

openclaw doctor --fix peut effacer l’état obsolète créé automatiquement tel que les épingles de modèles modelOverrideSource: "auto", les métadonnées de modèle d’exécution, les identifiants de harnais épinglés, les liaisons de session CLI et les substitutions automatiques de profil d’authentification lorsque leur route propriétaire n’est plus configurée. Les choix de modèle de session utilisateur explicites ou hérités sont signalés pour examen manuel et laissés intacts ; changez-les avec /model ..., /new, ou réinitialisez la session lorsque cette route n’est plus prévue.

3. Migrations d'état hérité (disposition du disque)

Doctor peut migrer les dispositions sur disque plus anciennes vers la structure actuelle :

• Magasin de sessions + transcriptions :
  • de ~/.openclaw/sessions/ vers `~/.openclaw/agents/

/sessions/ - Répertoire de l'agent : - de/.openclaw/agent/vers/.openclaw/agents/

/agent/ - État d'authentification WhatsApp (Baileys) : - de l'ancien/.openclaw/credentials/*.json(saufoauth.json) - vers /.openclaw/credentials/whatsapp/

/…(id de compte par défaut :default`)

Ces migrations sont de type « best-effort » et idempotentes ; doctor émettra des avertissements lorsqu'il laisse des dossiers hérités derrière en tant que sauvegardes. Le Gateway/CLI migre également automatiquement les sessions héritées + le répertoire de l'agent au démarrage afin que l'historique/l'authentification/les modèles atterrissent dans le chemin par agent sans exécution manuelle de doctor. L'authentification WhatsApp n'est intentionnellement migrée que via `openclaw doctor`. La normalisation du fournisseur Talk/de la carte des fournisseurs compare désormais par égalité structurelle, les diffs basés uniquement sur l'ordre des clés ne déclenchent donc plus de modifications répétées sans effet de type `doctor --fix`.

3a. Migrations de manifestes de plugins hérités

Doctor analyse tous les manifestes de plugins installés pour détecter les clés de capacités de premier niveau obsolètes (speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders, webSearchProviders). Lorsqu’il en trouve, il propose de les déplacer dans l’objet contracts et de réécrire le fichier manifeste sur place. Cette migration est idempotente ; si la clé contracts possède déjà les mêmes valeurs, la clé héritée est supprimée sans dupliquer les données.

3b. Migrations héritées du magasin cron

Doctor vérifie également le magasin de tâches cron (~/.openclaw/cron/jobs.json par défaut, ou cron.store en cas de substitution) pour les anciennes structures de tâches que le planificateur accepte toujours pour la compatibilité.

Les nettoyages cron actuels incluent :

• jobId → id
• schedule.cron → schedule.expr
• champs de payload de premier niveau (message, model, thinking, …) → payload
• champs de livraison de premier niveau (deliver, channel, to, provider, …) → delivery
• alias de livraison provider du payload → delivery.channel explicite
• tâches de repli de webhook notify: true héritées → livraison webhook explicite depuis cron.webhook ; les tâches d’annonce conservent leur livraison par chat et obtiennent delivery.completionDestination

Le Gateway nettoie également les lignes cron malformées au chargement afin que les tâches valides continuent de s’exécuter. Les lignes brutes malformées sont copiées dans jobs-quarantine.json à côté du magasin actif avant d’être supprimées de jobs.json ; doctor signale les lignes mises en quarantaine pour que vous puissiez les réviser ou les réparer manuellement.

Doctor et le démarrage du Gateway utilisent la même migration notify: true avant l’exécution du planificateur. Si cron.webhook est manquant, doctor avertit et laisse le marqueur de notification hérité pour une réparation manuelle.

Sur Linux, doctor avertit également lorsque la crontab de l’utilisateur appelle encore le script ~/.openclaw/bin/ensure-whatsapp.sh hérité. Ce script localisé à l’hôte n’est pas maintenu par la version actuelle d’OpenClaw et peut écrire de faux messages Gateway inactive dans ~/.openclaw/logs/whatsapp-health.log lorsque cron ne peut pas atteindre le bus utilisateur systemd. Supprimez l’entrée de crontab obsolète avec crontab -e ; utilisez openclaw channels status --probe, openclaw doctor et openclaw gateway status pour les contrôles de santé actuels.

3c. Nettoyage des verrous de session

Doctor analyse chaque répertoire de session d’agent pour détecter les fichiers de verrouillage d’écriture obsolètes — des fichiers laissés en place lorsqu’une session s’est terminée de manière anormale. Pour chaque fichier de verrou trouvé, il signale : le chemin, le PID, si le PID est toujours actif, l’ancienneté du verrou et s’il est considéré comme obsolète (PID mort, métadonnées de propriétaire mal formées, âge supérieur à 30 minutes, ou un PID actif qui peut être prouvé comme appartenant à un processus non-OpenClaw). En mode --fix / --repair, il supprime automatiquement les verrous avec des propriétaires morts, orphelins, recyclés, mal formés-anciens ou non-OpenClaw. Les anciens verrous qui appartiennent toujours à un processus OpenClaw actif sont signalés mais conservés en place afin que doctor ne coupe pas un enregistreur de transcription actif.

3d. Réparation de la branche de transcription de session

Doctor analyse les fichiers JSONL de session d’agent pour détecter la forme de branche dupliquée créée par le bug de réécriture de la transcription des invites du 2026.4.24 : un tour utilisateur abandonné avec le contexte d’exécution interne OpenClaw plus un frère actif contenant la même invite utilisateur visible. En mode --fix / --repair, doctor sauvegarde chaque fichier affecté à côté de l’original et réécrit la transcription vers la branche active afin que les lecteurs d’historique et de mémoire de la passerelle ne voient plus les tours en double.

4. Vérifications de l'intégrité de l'état (persistance de la session, routage et sécurité)

Le répertoire d’état est le cerveau opérationnel. S’il disparaît, vous perdez les sessions, les identifiants, les journaux et la configuration (sauf si vous avez des sauvegardes ailleurs).

Doctor vérifie :

• Répertoire d’état manquant : avertit d’une perte catastrophique de l’état, invite à recréer le répertoire et rappelle qu’il ne peut pas récupérer les données manquantes.
• Autorisations du répertoire d’état : vérifie la possibilité d’écriture ; propose de réparer les autorisations (et émet une indication chownmacOS lorsqu’une inadéquation de propriétaire/groupe est détectée).
• Répertoire d’état synchronisé par le cloud sur macOS : avertit lorsque l’état se trouve sous iCloud Drive (~/Library/Mobile Documents/com~apple~CloudDocs/...) ou ~/Library/CloudStorage/...Linux car les chemins sauvegardés par synchronisation peuvent provoquer des E/S plus lentes et des conflits de verrouillage/synchronisation.
• Répertoire d’état SD ou eMMC sur Linux : avertit lorsque l’état correspond à une source de montage mmcblk*, car les E/S aléatoires sur SD ou eMMC peuvent être plus lentes et s’user plus rapidement sous les écritures de session et d’identifiants.
• Répertoires de session manquants : sessions/ et le répertoire de stockage de la session sont requis pour conserver l’historique et éviter les plantages ENOENT.
• Inadéquation de la transcription : avertit lorsque les entrées de session récentes ont des fichiers de transcription manquants.
• Session principale « 1-line JSONL » : signale lorsque la transcription principale ne comporte qu’une seule ligne (l’historique ne s’accumule pas).
• Plusieurs répertoires d’état : avertit lorsque plusieurs dossiers ~/.openclaw existent dans les répertoires personnels ou lorsque OPENCLAW_STATE_DIR pointe ailleurs (l’historique peut être divisé entre les installations).
• Rappel du mode distant : si gateway.mode=remote, doctor vous rappelle de l’exécuter sur l’hôte distant (l’état s’y trouve).
• Autorisations du fichier de configuration : avertit si ~/.openclaw/openclaw.json est lisible par le groupe/le monde et propose de le resserrer à 600.

OAuth5. Intégrité de l'authentification du modèle (expiration OAuth)

Doctor inspecte les profils OAuth dans le magasin d’authentification, avertit lorsque les jetons arrivent à expiration ou sont expirés, et peut les actualiser en toute sécurité. Si le profil OAuth/jeton Anthropic est obsolète, il suggère une clé API Anthropic ou le chemin du jeton de configuration (setup-token) Anthropic. Les invites d’actualisation n’apparaissent que lors d’une exécution interactive (TTY) ; --non-interactiveOAuth ignore les tentatives d’actualisation.

Lorsqu’une actualisation OAuth échoue définitivement (par exemple refresh_token_reused, invalid_grant, ou un provider vous demandant de vous reconnecter), doctor signale qu’une nouvelle authentification est requise et imprime la commande exacte openclaw models auth login --provider ...OAuthmacOS à exécuter.

Doctor signale également les profils d’authentification temporairement inutilisables en raison de :

• courts temps d’attente (limites de délai/délais d’attente/échecs d’authentification)
• désactivations plus longues (échecs de facturation/crédit)

Les profils OAuth Codex hérités dont les jetons résident dans le trousseau macOS (onboarding plus ancien avant la disposition sidecar basée sur les fichiers) sont réparés uniquement par doctor. Exécutez openclaw doctor --fix une fois depuis un terminal interactif pour migrer les jetons hérités sauvegardés par le trousseau directement dans auth-profiles.jsonTelegramOpenAIOAuth ; après cela, les tours intégrés (Telegram, cron, envoi de sous-agent) les résolvent en tant que profils OAuth OpenAI canoniques.

6. Validation du modèle de Hooks

Si hooks.gmail.model est défini, doctor valide la référence du modèle par rapport au catalogue et à la liste autorisée et avertit lorsqu’il ne peut pas être résolu ou n’est pas autorisé.

7. Réparation de l'image Sandbox

Lorsque la mise en bac à sable (sandboxing) est activée, doctor vérifie les images Docker et propose de les construire ou de passer aux noms hérités si l’image actuelle est manquante.

7b. Nettoyage de l'installation des plugins

Doctor supprime l’état de préparation de dépendance de plugin hérité généré par OpenClaw en mode openclaw doctor --fix / openclaw doctor --repairnpm. Cela couvre les racines de dépendances générées obsolètes, les anciens répertoires d’étape d’installation, les débris locaux de package provenant du code précédent de réparation des dépendances des plugins groupés, et les copies gérées orphelines ou récupérées de plugins @openclaw/* groupés qui peuvent masquer le manifeste groupé actuel. Doctor relie également le package hôte openclaw dans les plugins gérés npm qui déclarent peerDependencies.openclaw, afin que les imports d’exécution locaux de package tels que openclaw/plugin-sdk/* continuent à être résolus après les mises à jour ou les réparations npm.

Doctor peut également réinstaller les plugins téléchargeables manquants lorsque la configuration les référence mais que le registre de plugins local ne peut pas les trouver. Les exemples incluent le plugins.entries matériel, les paramètres de canal/fournisseur/recherche configurés et les runtimes d’agent configurés. Lors des mises à jour de package, doctor évite d’exécuter la réparation de plugin du gestionnaire de package pendant que le package principal est en cours d’échange ; exécutez openclaw doctor --fix à nouveau après la mise à jour si un plugin configuré a toujours besoin de récupération. Le démarrage du Gateway et le rechargement de la configuration n’exécutent pas les gestionnaires de packages ; les installations de plugins restent un travail explicite de doctor/install/update.

8. Migration et indices de nettoyage des services de Gateway

Doctor détecte les services de passerelle hérités (launchd/systemd/schtasks) et propose de les supprimer et d’installer le service OpenClaw en utilisant le port de passerelle actuel. Il peut également rechercher des services de type passerelle supplémentaires et imprimer des indices de nettoyage. Les services de passerelle OpenClaw nommés par profil sont considérés comme de première classe et ne sont pas signalés comme « supplémentaires ».

Sur Linux, si le service de passerelle au niveau de l’utilisateur est manquant mais qu’un service de passerelle OpenClaw au niveau du système existe, doctor n’installe pas automatiquement un deuxième service au niveau de l’utilisateur. Inspectez avec openclaw gateway status --deep ou openclaw doctor --deep, puis supprimez le doublon ou définissez OPENCLAW_SERVICE_REPAIR_POLICY=external lorsqu’un superviseur système possède le cycle de vie de la passerelle.

8b. Migration de Matrix au démarrage

Lorsqu’un compte de Matrix channel a une migration d’état héritée en attente ou actionnable, doctor (en mode --fix / --repair) crée un instantané de pré-migration puis exécute les étapes de migration de meilleure tentative : migration d’état hérité Matrix et préparation de l’état chiffré hérité. Ces deux étapes ne sont pas fatales ; les erreurs sont consignées et le démarrage se poursuit. En mode lecture seule (openclaw doctor sans --fix), cette vérification est entièrement ignorée.

8c. Appareillage des appareils et dérive d'authentification

Doctor inspecte désormais l’état de l’appareillage des appareils dans le cadre de la vérification de santé normale.

Ce qu’il signale :

• les demandes de premier appareillage en attente
• les mises à niveau de rôle en attente pour les appareils déjà appareillés
• les mises à niveau de portée en attente pour les appareils déjà appareillés
• les réparations de discordance de clé publique où l’identifiant de l’appareil correspond toujours mais l’identité de l’appareil ne correspond plus à l’enregistrement approuvé
• les enregistrements appareillés manquant un jeton actif pour un rôle approuvé
• les jetons appareillés dont les portées dérivent en dehors de la ligne de base d’appareillage approuvée
• les entrées de jeton d’appareil mises en cache localement pour la machine actuelle qui précèdent une rotation de jeton côté passerelle ou portent des métadonnées de portée obsolètes

Doctor n’approuve pas automatiquement les demandes d’appareillage et ne fait pas tourner automatiquement les jetons d’appareil. Il imprime plutôt les étapes suivantes exactes :

• inspecter les demandes en attente avec openclaw devices list
• approuver la demande exacte avec `openclaw devices approve

- faire tourner un nouveau jeton avecopenclaw devices rotate —device

—role

- supprimer et réapprouver un enregistrement obsolète avecopenclaw devices remove

`

Cela comble le trou courant « déjà appareillé mais nécessitant toujours un appareillage » : doctor distingue désormais le premier appareillage des mises à niveau de rôle/portée en attente et de la dérive de jeton/identité d'appareil obsolète.

9. Avertissements de sécurité

Doctor émet des avertissements lorsqu’un provider est ouvert aux DMs sans liste d’autorisation, ou lorsqu’une stratégie est configurée de manière dangereuse.

Linux10. persistance systemd (Linux)

S’il s’exécute en tant que service utilisateur systemd, doctor s’assure que la persistance est activée afin que la passerelle reste active après la déconnexion.

11. Statut de l'espace de travail (Skills, plugins et répertoires hérités)

Doctor imprime un résumé de l’état de l’espace de travail pour l’agent par défaut :

• Statut des Skills : compte les skills éligibles, celles dont il manque des exigences et celles bloquées par la liste d’autorisation.
• Répertoires d’espace de travail hérités : avertit lorsque ~/openclaw ou d’autres répertoires d’espace de travail hérités existent à côté de l’espace de travail actuel.
• Statut des plugins : compte les plugins activés/désactivés/en erreur ; répertorie les ID de plugins pour toute erreur ; signale les capacités des plugins groupés.
• Avertissements de compatibilité des plugins : signale les plugins qui ont des problèmes de compatibilité avec le runtime actuel.
• Diagnostics des plugins : met en évidence les avertissements ou erreurs de chargement émis par le registre des plugins.

11b. Taille du fichier d'amorçage

Doctor vérifie si les fichiers d’amorçage de l’espace de travail (par exemple AGENTS.md, CLAUDE.md ou d’autres fichiers de contexte injectés) sont proches ou dépassent le budget de caractères configuré. Il rapporte les nombres de caractères bruts par rapport aux caractères injectés par fichier, le pourcentage de troncation, la cause de la troncation (max/file ou max/total), et le total des caractères injectés en fraction du budget total. Lorsque les fichiers sont tronqués ou proches de la limite, doctor affiche des conseils pour régler agents.defaults.bootstrapMaxChars et agents.defaults.bootstrapTotalMaxChars.

11d. Nettoyage des plugins de channel obsolètes

Lorsque openclaw doctor --fix supprime un plugin de channel manquant, il supprime également la configuration obsolète étendue au channel qui référençait ce plugin : entrées `channels.

, cibles de heartbeat nommant le channel, et substitutions agents.*.models[”

/*”]`. Cela empêche les boucles de démarrage de Gateway où le runtime du channel a disparu mais la configuration demande toujours à la passerelle de s’y lier.

11c. Complétion du shell

Doctor vérifie si la complétion par tabulation est installée pour le shell actuel (zsh, bash, fish ou PowerShell) :

• Si le profil du shell utilise un modèle de complétion dynamique lent (source <(openclaw completion ...)), doctor le met à niveau vers la variante de fichier en cache plus rapide.
• Si la complétion est configurée dans le profil mais que le fichier cache est manquant, doctor régénère automatiquement le cache.
• Si aucune complétion n’est configurée du tout, doctor invite à l’installer (mode interactif uniquement ; ignoré avec --non-interactive).

Exécutez openclaw completion --write-state pour régénérer le cache manuellement.

Gateway12. Vérifications d'authentification Gateway (jeton local)

Doctor vérifie la disponibilité de l’authentification par jeton local de la passerelle.

• Si le mode de jeton nécessite un jeton et qu’aucune source de jeton n’existe, Doctor propose d’en générer un.
• Si gateway.auth.token est géré par SecretRef mais indisponible, Doctor avertit et ne l’écrase pas en texte clair.
• openclaw doctor --generate-gateway-token force la génération uniquement lorsqu’aucune référence de SecretRef pour le jeton n’est configurée.

12b. Réparations conscientes de SecretRef en lecture seule

Certains flux de réparation doivent inspecter les informations d’identification configurées sans affaiblir le comportement d’échec rapide (fail-fast) à l’exécution.

• openclaw doctor --fixTelegram utilise désormais le même modèle de résumé SecretRef en lecture seule que les commandes de la famille status pour les réparations de configuration ciblées.
• Exemple : la réparation allowFrom / groupAllowFrom @usernameTelegram du bot Telegram tente d’utiliser les informations d’identification configurées lorsqu’elles sont disponibles.
• Si le jeton du bot Telegram est configuré via SecretRef mais indisponible dans le chemin de commande actuel, Doctor signale que les informations d’identification sont configurées mais indisponibles et ignore la résolution automatique au lieu de planter ou de signaler incorrectement le jeton comme manquant.

Gateway13. Vérification de l'état du Gateway + redémarrage

Doctor exécute une vérification de l’état et propose de redémarrer le gateway lorsqu’il semble défectueux.

13b. Prêt pour la recherche mémoire

Doctor vérifie si le fournisseur d’intégration de recherche mémoire configuré est prêt pour l’agent par défaut. Le comportement dépend du backend et du fournisseur configurés :

• Backend QMD : sonde si le binaire qmd est disponible et démarrable. Sinon, il imprime des instructions de correction, y compris le package npm et une option de chemin binaire manuel.
• Fournisseur local explicite : vérifie la présence d’un fichier de modèle local ou d’une URL de modèle distante/téléchargeable reconnue. S’il manque, suggère de passer à un fournisseur distant.
• Fournisseur distant explicite (openai, voyage, etc.) : vérifie qu’une clé API est présente dans l’environnement ou le magasin d’authentification. Imprime des indices de correction exploitables si elle manque.
• Fournisseur automatique hérité : traite memorySearch.provider: "auto" comme OpenAI, vérifie la disponibilité de OpenAI et doctor --fix le réécrit en provider: "openai".

Lorsqu’un résultat de sonde de passerelle en cache est disponible (la passerelle était en bonne santé au moment de la vérification), doctor recoupe ce résultat avec la configuration visible via la CLI et note toute divergence. Doctor ne lance pas de nouveau ping d’intégration sur le chemin par défaut ; utilisez la commande de statut de mémoire profonde lorsque vous voulez une vérification en direct du fournisseur.

Utilisez openclaw memory status --deep pour vérifier la disponibilité de l’intégration lors de l’exécution.

14. Avertissements de statut de channel

Si la passerelle est en bonne santé, Doctor exécute une sonde de statut de channel et signale des avertissements avec des corrections suggérées.

15. Audit et réparation de la configuration du superviseur

Doctor vérifie la configuration du superviseur installée (launchd/systemd/schtasks) pour détecter les valeurs par défaut manquantes ou obsolètes (par exemple, les dépendances réseau systemd et le délai de redémarrage). Lorsqu’il détecte une incohérence, il recommande une mise à jour et peut réécrire le fichier de service/tâche avec les valeurs par défaut actuelles.

Notes :

• openclaw doctor demande une confirmation avant de réécrire la configuration du superviseur.
• openclaw doctor --yes accepte les invites de réparation par défaut.
• openclaw doctor --fix applique les corrections recommandées sans confirmation (--repair est un alias).
• openclaw doctor --fix --force écrase les configurations personnalisées du superviseur.
• OPENCLAW_SERVICE_REPAIR_POLICY=external maintient doctor en lecture seule pour le cycle de vie du service de passerelle. Il signale toujours l’état de santé du service et exécute les réparations non liées aux services, mais ignore l’installation, le démarrage, le redémarrage, l’amorçage, la réécriture de la configuration du superviseur et le nettoyage des services hérités, car un superviseur externe possède ce cycle de vie.
• Sur Linux, doctor ne réécrit pas les métadonnées de commande/point d’entrée tant que l’unité systemd de passerelle correspondante est active. Il ignore également les unités supplémentaires de type passerelle inactives et non héritées lors de l’analyse des services en double, afin que les fichiers de services compagnons ne créent pas de bruit lors du nettoyage.
• Si l’authentification par jeton exige un jeton et que gateway.auth.token est géré par SecretRef, l’installation/réparation du service doctor valide le SecretRef mais ne persiste pas les valeurs de jeton en texte clair résolues dans les métadonnées d’environnement du service superviseur.
• Doctor détecte les valeurs d’environnement de service gérées .env/prises en charge par SecretRef que les anciennes installations LaunchAgent, systemd ou Tâche planifiée Windows avaient intégrées en ligne, et réécrit les métadonnées du service afin que ces valeurs soient chargées depuis la source d’exécution au lieu de la définition du superviseur.
• Doctor détecte lorsque la commande du service épingle encore un ancien --port après des modifications gateway.port et réécrit les métadonnées du service vers le port actuel.
• Si l’authentification par jeton exige un jeton et que le SecretRef du jeton configuré n’est pas résolu, doctor bloque le chemin d’installation/réparation avec des conseils exploitables.
• Si gateway.auth.token et gateway.auth.password sont tous deux configurés et que gateway.auth.mode n’est pas défini, doctor bloque l’installation/réparation jusqu’à ce que le mode soit défini explicitement.
• Pour les unités utilisateur systemd sous Linux, les vérifications de dérive de jeton de doctor incluent désormais les sources Environment= et EnvironmentFile= lors de la comparaison des métadonnées d’authentification du service.
• Les réparations de service de doctor refusent de réécrire, d’arrêter ou de redémarrer un service de passerelle issu d’un binaire OpenClaw plus ancien lorsque la configuration a été écrite pour la dernière fois par une version plus récente. Voir Dépannage Gateway.
• Vous pouvez toujours forcer une réécriture complète via openclaw gateway install --force.

Gateway16. Diagnostics du runtime Gateway + du port

Doctor inspecte le runtime du service (PID, dernier état de sortie) et avertit lorsque le service est installé mais pas réellement en cours d’exécution. Il vérifie également les collisions de ports sur le port de la passerelle (par défaut 18789) et signale les causes probables (passerelle déjà en cours d’exécution, tunnel SSH).

Gateway17. Bonnes pratiques pour le runtime Gateway

Doctor avertit lorsque le service Gateway s’exécute sur Bun ou un chemin Node géré par un gestionnaire de versions (nvm, fnm, volta, asdfWhatsAppTelegrammacOS, etc.). Les canaux WhatsApp + Telegram nécessitent Node, et les chemins des gestionnaires de versions peuvent se briser après les mises à jour car le service ne charge pas votre initialisation de shell. Doctor propose de migrer vers une installation système de Node si disponible (Homebrew/apt/choco).

Les LaunchAgents nouvellement installés ou réparés sur macOS utilisent un PATH système canonique (/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbinLinux) au lieu de copier le PATH du shell interactif, de sorte que les binaires système gérés par Homebrew restent disponibles tandis que les répertoires Volta, asdf, fnm, pnpm et autres gestionnaires de versions ne modifient pas la résolution des processus enfants Node. Les services Linux conservent toujours des racines d’environnement explicites (NVM_DIR, FNM_DIR, VOLTA_HOME, ASDF_DATA_DIR, BUN_INSTALL, PNPM_HOME) et des répertoires bin utilisateur stables, mais les répertoires de repli supposés des gestionnaires de versions ne sont écrits dans le PATH du service que lorsque ces répertoires existent sur le disque.

18. Écriture de configuration + métadonnées de l'assistant

Doctor persiste toutes les modifications de configuration et applique les métadonnées de l’assistant pour enregistrer l’exécution de doctor.

19. Conseils d'espace de travail (sauvegarde + système de mémoire)

Doctor suggère un système de mémoire pour l’espace de travail lorsqu’il est manquant et imprime un conseil de sauvegarde si l’espace de travail n’est pas déjà sous git.

Consultez /concepts/agent-workspace pour un guide complet sur la structure de l’espace de travail et la sauvegarde git (GitHub privé ou GitLab recommandé).

Connexes

• Guide de procédure Gateway
• Dépannage Gateway