# openclaw doctor

Controlli di integrità + correzioni rapide per il Gateway e i canali.

Correlati:

• Risoluzione dei problemi: Risoluzione dei problemi
• Audit di sicurezza: Sicurezza

# Esempi

openclaw doctor
openclaw doctor --repair
openclaw doctor --deep
openclaw doctor --repair --non-interactive
openclaw doctor --generate-gateway-token

# Opzioni

• --no-workspace-suggestions: disabilita i suggerimenti di memoria/ricerca del workspace
• --yes: accetta i valori predefiniti senza chiedere conferma
• --repair: applica le riparazioni consigliate non relative ai servizi senza chiedere conferma; le installazioni e le riscritture del servizio Gateway richiedono comunque una conferma interattiva o comandi Gateway espliciti
• --fix: alias di --repair
• --force: applica riparazioni aggressive, inclusa la sovrascrittura della configurazione personalizzata del servizio quando necessario
• --non-interactive: esegue senza prompt; solo migrazioni sicure e riparazioni non relative ai servizi
• --generate-gateway-token: genera e configura un token Gateway
• --deep: analizza i servizi di sistema per installazioni Gateway aggiuntive e segnala i passaggi di consegne recenti dei riavvii del supervisore Gateway

Note:

• In modalità Nix (OPENCLAW_NIX_MODE=1), i controlli doctor di sola lettura funzionano comunque, ma doctor --fix, doctor --repair, doctor --yes e doctor --generate-gateway-token sono disabilitati perché openclaw.json è immutabile. Modifica invece il sorgente Nix per questa installazione; per nix-openclaw, usa la Guida rapida agent-first.
• I prompt interattivi (come le correzioni keychain/OAuth) vengono eseguiti solo quando stdin è un TTY e --non-interactive non è impostato. Le esecuzioni headless (cron, Telegram, senza terminale) salteranno i prompt.
• Prestazioni: le esecuzioni non interattive di doctor saltano il caricamento anticipato dei Plugin, così i controlli di integrità headless restano rapidi. Le sessioni interattive caricano comunque completamente i Plugin quando un controllo richiede il loro contributo.
• --fix (alias di --repair) scrive un backup in ~/.openclaw/openclaw.json.bak e rimuove le chiavi di configurazione sconosciute, elencando ogni rimozione.
• doctor --fix --non-interactive segnala definizioni del servizio Gateway mancanti o obsolete, ma non le installa né le riscrive al di fuori della modalità di riparazione aggiornamento. Esegui openclaw gateway install per un servizio mancante, oppure openclaw gateway install --force quando vuoi intenzionalmente sostituire il launcher.
• I controlli di integrità dello stato ora rilevano file di trascrizione orfani nella directory delle sessioni. L'archiviazione come .deleted.<timestamp> richiede una conferma interattiva; --fix, --yes e le esecuzioni headless li lasciano al loro posto.
• Doctor analizza anche ~/.openclaw/cron/jobs.json (o cron.store) alla ricerca di forme legacy dei job Cron e può riscriverle sul posto prima che lo scheduler debba normalizzarle automaticamente a runtime.
• Su Linux, doctor avvisa quando il crontab dell'utente esegue ancora il legacy ~/.openclaw/bin/ensure-whatsapp.sh; quello script non è più mantenuto e può registrare falsi disservizi del Gateway WhatsApp quando cron non dispone dell'ambiente user-bus di systemd.
• Quando WhatsApp è abilitato, doctor controlla la presenza di un loop eventi Gateway degradato con client locali openclaw-tui ancora in esecuzione. doctor --fix arresta solo i client TUI locali verificati, così le risposte WhatsApp non vengono accodate dietro loop di aggiornamento TUI obsoleti.
• Doctor riscrive i riferimenti modello legacy openai-codex/* in riferimenti canonici openai/* tra modelli principali, fallback, override heartbeat/subagent/compaction, hook, override dei modelli dei canali e pin obsoleti delle route di sessione. --fix seleziona agentRuntime.id: "codex" solo quando il Plugin Codex è installato, abilitato, contribuisce l'harness codex e dispone di OAuth utilizzabile; altrimenti seleziona agentRuntime.id: "pi" così la route resta sul runner OpenClaw predefinito.
• Doctor pulisce lo stato legacy di staging delle dipendenze dei Plugin creato da versioni precedenti di OpenClaw. Ripara inoltre i Plugin scaricabili mancanti a cui fa riferimento la configurazione, come plugins.entries, i canali configurati, le impostazioni configurate di provider/ricerca o i runtime agente configurati. Durante gli aggiornamenti dei pacchetti, doctor salta la riparazione dei Plugin tramite package manager finché lo scambio del pacchetto non è completo; riesegui openclaw doctor --fix dopo, se un Plugin configurato richiede ancora il ripristino. Se il download non riesce, doctor segnala l'errore di installazione e conserva la voce del Plugin configurata per il successivo tentativo di riparazione.
• Doctor ripara la configurazione obsoleta dei Plugin rimuovendo gli id dei Plugin mancanti da plugins.allow/plugins.entries, oltre alla configurazione dei canali pendente corrispondente, ai target heartbeat e agli override dei modelli dei canali quando la scoperta dei Plugin è sana.
• Doctor mette in quarantena la configurazione non valida dei Plugin disabilitando la voce plugins.entries.<id> interessata e rimuovendo il relativo payload config non valido. L'avvio del Gateway salta già solo quel Plugin non valido, così gli altri Plugin e canali possono continuare a funzionare.
• Imposta OPENCLAW_SERVICE_REPAIR_POLICY=external quando un altro supervisore controlla il ciclo di vita del Gateway. Doctor segnala comunque l'integrità del Gateway/servizio e applica riparazioni non relative ai servizi, ma salta installazione/avvio/riavvio/bootstrap del servizio e pulizia dei servizi legacy.
• Su Linux, doctor ignora le unità systemd inattive aggiuntive simili al Gateway e non riscrive i metadati di comando/entrypoint per un servizio Gateway systemd in esecuzione durante la riparazione. Arresta prima il servizio oppure usa openclaw gateway install --force quando vuoi intenzionalmente sostituire il launcher attivo.
• Doctor migra automaticamente la configurazione piatta legacy di Talk (talk.voiceId, talk.modelId e simili) in talk.provider + talk.providers.<provider>.
• Le esecuzioni ripetute di doctor --fix non segnalano/applicano più la normalizzazione di Talk quando l'unica differenza è l'ordine delle chiavi dell'oggetto.
• Doctor include un controllo di prontezza della ricerca in memoria e può consigliare openclaw configure --section model quando mancano le credenziali di embedding.
• Doctor avvisa quando non è configurato alcun proprietario dei comandi. Il proprietario dei comandi è l'account dell'operatore umano autorizzato a eseguire comandi riservati al proprietario e ad approvare azioni pericolose. L'abbinamento DM permette solo a qualcuno di parlare con il bot; se hai approvato un mittente prima che esistesse il bootstrap del primo proprietario, imposta esplicitamente commands.ownerAllowFrom.
• Doctor avvisa quando sono configurati agenti in modalità Codex ed esistono asset personali della CLI Codex nella home Codex dell'operatore. Gli avvii locali dell'app-server Codex usano home isolate per agente, quindi usa openclaw migrate codex --dry-run per inventariare gli asset da promuovere deliberatamente.
• Doctor avvisa quando le Skills consentite per l'agente predefinito non sono disponibili nell'ambiente di runtime corrente perché mancano binari, variabili d'ambiente, configurazione o requisiti del sistema operativo. doctor --fix può disabilitare quelle Skills non disponibili con skills.entries.<skill>.enabled=false; installa/configura invece il requisito mancante quando vuoi mantenere attiva la skill.
• Se la modalità sandbox è abilitata ma Docker non è disponibile, doctor segnala un avviso ad alto segnale con rimedio (install Docker oppure openclaw config set agents.defaults.sandbox.mode off).
• Se sono presenti file legacy del registro sandbox (~/.openclaw/sandbox/containers.json o ~/.openclaw/sandbox/browsers.json), doctor li segnala; openclaw doctor --fix migra le voci valide in directory di registro partizionate e mette in quarantena i file legacy non validi.
• Se gateway.auth.token/gateway.auth.password sono gestiti da SecretRef e non disponibili nel percorso del comando corrente, doctor segnala un avviso di sola lettura e non scrive credenziali di fallback in chiaro.
• Se l'ispezione SecretRef del canale non riesce in un percorso di correzione, doctor continua e segnala un avviso invece di uscire in anticipo.
• Dopo le migrazioni della directory di stato, doctor avvisa quando gli account Telegram o Discord predefiniti abilitati dipendono dal fallback env e TELEGRAM_BOT_TOKEN o DISCORD_BOT_TOKEN non è disponibile al processo doctor.
• La risoluzione automatica dello username allowFrom di Telegram (doctor --fix) richiede un token Telegram risolvibile nel percorso del comando corrente. Se l'ispezione del token non è disponibile, doctor segnala un avviso e salta la risoluzione automatica per quel passaggio.

# macOS: override env di launchctl

Se in precedenza hai eseguito launchctl setenv OPENCLAW_GATEWAY_TOKEN ... (o ...PASSWORD), quel valore sovrascrive il file di configurazione e può causare errori "unauthorized" persistenti.

launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

# Correlati

• Riferimento CLI
• Gateway doctor