Skip to main content

​
Doctor

openclaw doctor is the repair and migration tool. It validates and normalises config, migrates legacy state, checks gateway, channel, and model-auth health, and offers actionable fixes. Run it after every install, upgrade, or config change.

​
Quick start

Interactive mode prompts before applying anything. To review the current config first:

​
Modes

Use --non-interactive in CI or scripts — it applies only the safe migrations and skips anything that needs human confirmation. Use --repair when you want it to actually fix and restart unattended.

​
What it checks

  • Config normalisation for legacy value shapes.
  • Legacy config key migrations (see below) — rewrites ~/.openclaw/openclaw.json to the current schema.
  • Legacy on-disk state migration: sessions, transcripts, agent dir, and WhatsApp (Baileys) auth into the per-agent layout.
  • State integrity and permissions: missing state dir, writability, transcript mismatches, multiple state dirs, cloud-synced state-dir warnings (iCloud), and SD/eMMC-backed state warnings on Linux.
  • Config file permission check (warns if ~/.openclaw/openclaw.json is group/world readable; offers to tighten to 600).
  • Model auth health: OAuth expiry, optional refresh of expiring tokens, and auth-profile cooldown/disabled reporting.
  • Gateway auth warnings when no gateway.auth.token is set on a local gateway (offers to generate one; force with --generate-gateway-token).
  • Security warnings for open DM policies without an allowlist.
  • OpenCode Zen provider override warnings (models.providers.opencode).
  • Gateway health check with an offer to restart when unhealthy.
  • Service installed but not running; cached launchd label issues.
  • Port collision diagnostics on the default port 18789.
  • Supervisor config audit (launchd/systemd/schtasks) with optional repair.
  • Runtime best-practice checks: warns when the service runs on Bun or a version-managed Node path (nvm, fnm, volta, asdf), which can break WhatsApp/Telegram or fail after upgrades; offers to migrate to a system Node install.
  • systemd linger check on Linux (keeps the gateway alive after logout).
  • Legacy service migration and extra-gateway detection (profile-named services are first-class, not “extra”).
  • Channel status warnings (probed from the running gateway).
  • Skills status summary (eligible/missing/blocked).
  • Sandbox image repair when sandboxing is enabled.
  • Hooks model validation (hooks.gmail.model) against the catalog and allowlist.
  • Workspace tips: suggests a memory system and a git backup when the workspace is not under version control.
  • Source-install checks: pnpm workspace mismatch, missing UI assets, missing tsx binary.

​
Config migrations

The gateway auto-runs doctor migrations on startup when it detects a legacy config format, so stale configs are usually repaired without manual intervention. Doctor explains which legacy keys it found, shows the migration, and rewrites the file. Current migrations include:
  • routing.allowFrom to channels.whatsapp.allowFrom
  • routing.groupChat.* to channels.*.groups."*".requireMention / messages.groupChat.*
  • routing.queue to messages.queue
  • routing.bindings to top-level bindings
  • routing.agents / routing.defaultAgentId to agents.list plus agents.list[].default
  • routing.agentToAgent to tools.agentToAgent
  • identity to agents.list[].identity
  • agent.* to agents.defaults plus tools.*
  • agent.model / allowedModels / modelAliases / modelFallbacks to agents.defaults.models plus agents.defaults.model.primary/fallbacks
  • browser.ssrfPolicy.allowPrivateNetwork to browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
WhatsApp auth state is intentionally migrated only via openclaw doctor, not automatically on startup. If WhatsApp shows as logged out after an upgrade, run doctor.

​
After a bad upgrade

If a tool refuses to run and asks you to run doctor, you have a deprecated config key. Run openclaw doctor (or --repair) to migrate it. If channels stopped working after switching the runtime, check the Bun-vs-Node warning — WhatsApp and Telegram require Node.
Related: Upgrading · Troubleshooting · Health checks · Multi-gateway