openclaw doctor is the repair + migration tool for OpenClaw. It fixes stale config/state, checks health, and provides actionable repair steps.

openclaw doctor

openclaw doctor --yes

Accept defaults without prompting (including restart/service/sandbox repair steps when applicable).

openclaw doctor --repair

Apply recommended repairs without prompting (repairs + restarts where safe).

openclaw doctor --repair --force

Apply aggressive repairs too (overwrites custom supervisor configs).

openclaw doctor --non-interactive

Run without prompts and only apply safe migrations (config normalization + on-disk state moves). Skips restart/service/sandbox actions that require human confirmation. Legacy state migrations run automatically when detected.

openclaw doctor --deep

Scan system services for extra gateway installs (launchd/systemd/schtasks).

If you want to review changes before writing, open the config file first:

cat ~/.openclaw/openclaw.json

• Optional pre-flight update for git installs (interactive only).
• UI protocol freshness check (rebuilds Control UI when the protocol schema is newer).
• Health check + restart prompt.
• Skills status summary (eligible/missing/blocked).
• Config normalization for legacy values.
• OpenCode Zen provider override warnings (models.providers.opencode).
• Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
• State integrity and permissions checks (sessions, transcripts, state dir).
• Config file permission checks (chmod 600) when running locally.
• Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.
• Extra workspace dir detection (~/openclaw).
• Sandbox image repair when sandboxing is enabled.
• Legacy service migration and extra gateway detection.
• Gateway runtime checks (service installed but not running; cached launchd label).
• Channel status warnings (probed from the running gateway).
• Supervisor config audit (launchd/systemd/schtasks) with optional repair.
• Gateway runtime best-practice checks (Node vs Bun, version-manager paths).
• Gateway port collision diagnostics (default 18789).
• Security warnings for open DM policies.
• Gateway auth warnings when no gateway.auth.token is set (local mode; offers token generation).
• systemd linger check on Linux.
• Source install checks (pnpm workspace mismatch, missing UI assets, missing tsx binary).
• Writes updated config + wizard metadata.

If this is a git checkout and doctor is running interactively, it offers to update (fetch/rebase/build) before running doctor.

If the config contains legacy value shapes (for example messages.ackReaction without a channel-specific override), doctor normalizes them into the current schema.

When the config contains deprecated keys, other commands refuse to run and ask you to run openclaw doctor.

Doctor will:

• Explain which legacy keys were found.
• Show the migration it applied.
• Rewrite ~/.openclaw/openclaw.json with the updated schema.