ContextQMD
Back to Openclaw

Doctor

docs/cli/doctor.md

2026.5.57.7 KB
Original Source

openclaw doctor

Health checks + quick fixes for the gateway and channels.

Related:

Examples

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

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

Notes:

  • 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 transcript files in the sessions directory. Archiving them as .deleted.<timestamp> requires an interactive confirmation; --fix, --yes, and headless runs leave them in place.
  • Doctor also scans ~/.openclaw/cron/jobs.json (or cron.store) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.
  • 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 selects agentRuntime.id: "codex" only when the Codex plugin is installed, enabled, contributes the codex harness, and has usable OAuth; otherwise it selects agentRuntime.id: "pi" so the route stays on the default OpenClaw runner.
  • Doctor cleans legacy plugin dependency staging state created by older OpenClaw versions. 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.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 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 or ~/.openclaw/sandbox/browsers.json) are present, doctor reports them; openclaw doctor --fix migrates valid entries into sharded registry directories and quarantines invalid legacy 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.
  • 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.

bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD