openclaw/docs/cli/doctor.md

summary, read_when, title

summary	read_when	title
CLI reference for `openclaw doctor` (health checks + guided repairs)	You have connectivity/auth issues and want guided fixes You updated and want a sanity check	Doctor

openclaw doctor

Health checks + quick fixes for the gateway and channels.

Related:

• Troubleshooting: Troubleshooting
• Security audit: Security

Examples

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

For channel-specific permissions, use the channel probes instead of doctor:

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

The targeted Discord capabilities probe reports the bot's effective channel permissions; the status probe audits configured Discord channels and voice auto-join targets.

Options

• --no-workspace-suggestions: disable workspace memory/search suggestions
• --yes: accept defaults without prompting
• --repair: apply recommended non-service repairs without prompting; gateway service installs and rewrites still require interactive confirmation or explicit gateway commands
• --fix: alias for --repair
• --force: apply aggressive repairs, including overwriting custom service config when needed
• --non-interactive: run without prompts; safe migrations and non-service repairs only
• --generate-gateway-token: generate and configure a gateway token
• --deep: scan system services for extra gateway installs and report recent Gateway supervisor restart handoffs

Notes:

• In Nix mode (OPENCLAW_NIX_MODE=1), read-only doctor checks still work, but doctor --fix, doctor --repair, doctor --yes, and doctor --generate-gateway-token are disabled because openclaw.json is immutable. Edit the Nix source for this install instead; for nix-openclaw, use the agent-first Quick Start.
• Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and --non-interactive is not set. Headless runs (cron, Telegram, no terminal) will skip prompts.
• Performance: non-interactive doctor runs skip eager plugin loading so headless health checks stay fast. Interactive sessions still fully load plugins when a check needs their contribution.
• --fix (alias for --repair) writes a backup to ~/.openclaw/openclaw.json.bak and drops unknown config keys, listing each removal.
• doctor --fix --non-interactive reports missing or stale gateway service definitions but does not install or rewrite them outside update repair mode. Run openclaw gateway install for a missing service, or openclaw gateway install --force when you intentionally want to replace the launcher.
• State integrity checks now detect orphan legacy transcript files in old sessions directories. Deleting those leftovers requires an interactive confirmation; --fix, --yes, and headless runs leave them in place unless a migration step imports and removes them.
• Doctor also imports legacy ~/.openclaw/cron/jobs.json / jobs-state.json cron stores into SQLite and normalizes old job shapes before the scheduler sees them.
• On Linux, doctor warns when the user's crontab still runs legacy ~/.openclaw/bin/ensure-whatsapp.sh; that script is no longer maintained and can log false WhatsApp gateway outages when cron lacks the systemd user-bus environment.
• When WhatsApp is enabled, doctor checks for a degraded Gateway event loop with local openclaw-tui clients still running. doctor --fix stops only verified local TUI clients so WhatsApp replies are not queued behind stale TUI refresh loops.
• Doctor rewrites legacy openai-codex/* model refs to canonical openai/* refs across primary models, fallbacks, heartbeat/subagent/compaction overrides, hooks, channel model overrides, and stale session route pins. --fix moves Codex intent onto provider/model-scoped agentRuntime.id: "codex" entries, preserves session auth-profile pins such as openai-codex:..., removes stale whole-agent/session runtime pins, and keeps repaired OpenAI agent refs on Codex auth routing instead of direct OpenAI API-key auth.
• Doctor cleans legacy plugin dependency staging state created by older OpenClaw versions and relinks the host openclaw package for managed npm plugins that declare it as a peer dependency. It also repairs missing downloadable plugins that are referenced by config, such as plugins.entries, configured channels, configured provider/search settings, or configured agent runtimes. During package updates, doctor skips package-manager plugin repair until the package swap is complete; rerun openclaw doctor --fix afterward if a configured plugin still needs recovery. If the download fails, doctor reports the install error and preserves the configured plugin entry for the next repair attempt.
• Doctor repairs stale plugin config by removing missing plugin ids from plugins.allow/plugins.deny/plugins.entries, plus matching dangling channel config, heartbeat targets, and channel model overrides when plugin discovery is healthy.
• Doctor quarantines invalid plugin config by disabling the affected plugins.entries.<id> entry and removing its invalid config payload. Gateway startup already skips only that bad plugin so other plugins and channels can keep running.
• Set OPENCLAW_SERVICE_REPAIR_POLICY=external when another supervisor owns the gateway lifecycle. Doctor still reports gateway/service health and applies non-service repairs, but skips service install/start/restart/bootstrap and legacy service cleanup.
• On Linux, doctor ignores inactive extra gateway-like systemd units and does not rewrite command/entrypoint metadata for a running systemd gateway service during repair. Stop the service first or use openclaw gateway install --force when you intentionally want to replace the active launcher.
• Doctor auto-migrates legacy flat Talk config (talk.voiceId, talk.modelId, and friends) into talk.provider + talk.providers.<provider>.
• Repeat doctor --fix runs no longer report/apply Talk normalization when the only difference is object key order.
• Doctor includes a memory-search readiness check and can recommend openclaw configure --section model when embedding credentials are missing.
• Doctor warns when no command owner is configured. The command owner is the human operator account allowed to run owner-only commands and approve dangerous actions. DM pairing only lets someone talk to the bot; if you approved a sender before first-owner bootstrap existed, set commands.ownerAllowFrom explicitly.
• Doctor warns when Codex-mode agents are configured and personal Codex CLI assets exist in the operator's Codex home. Local Codex app-server launches use isolated per-agent homes, so use openclaw migrate codex --dry-run to inventory assets that should be promoted deliberately.
• Doctor removes retired plugins.entries.codex.config.codexDynamicToolsProfile; Codex app-server always keeps Codex-native workspace tools native.
• Doctor warns when skills allowed for the default agent are unavailable in the current runtime environment because bins, env vars, config, or OS requirements are missing. doctor --fix can disable those unavailable skills with skills.entries.<skill>.enabled=false; install/configure the missing requirement instead when you want to keep the skill active.
• If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (install Docker or openclaw config set agents.defaults.sandbox.mode off).
• If legacy sandbox registry files (~/.openclaw/sandbox/containers.json, ~/.openclaw/sandbox/browsers.json, or old registry shard JSON files) are present, doctor reports them; openclaw doctor --fix migrates valid entries into SQLite and quarantines invalid legacy files.
• Legacy session state (sessions.json, transcript JSONL files, compaction checkpoints, and related session sidecars) is a doctor/migrate input only. Repair imports valid data into the global/per-agent SQLite databases and removes successfully imported sources; runtime code no longer keeps compatibility readers for those files.
• If gateway.auth.token/gateway.auth.password are SecretRef-managed and unavailable in the current command path, doctor reports a read-only warning and does not write plaintext fallback credentials.
• If channel SecretRef inspection fails in a fix path, doctor continues and reports a warning instead of exiting early.
• Extension-owned state migrations run through doctor without loading full channel runtimes. BlueBubbles, Discord, Feishu, Matrix, Microsoft Teams, QQBot, and Telegram import their legacy JSON sidecars into SQLite plugin state/blob tables from their own setup/doctor migration files, then remove the imported sources.
• After state-directory migrations, doctor warns when enabled default Telegram or Discord accounts depend on env fallback and TELEGRAM_BOT_TOKEN or DISCORD_BOT_TOKEN is unavailable to the doctor process.
• Telegram allowFrom username auto-resolution (doctor --fix) requires a resolvable Telegram token in the current command path. If token inspection is unavailable, doctor reports a warning and skips auto-resolution for that pass.

macOS: launchctl env overrides

If you previously ran launchctl setenv OPENCLAW_GATEWAY_TOKEN ... (or ...PASSWORD), that value overrides your config file and can cause persistent "unauthorized" errors.

launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

Related

• CLI reference
• Gateway doctor