Doctor (Diagnostics)

''openclaw doctor'' is OpenClaw's repair + migration tool. It fixes stale configuration/state, checks health, and provides actionable repair steps.

openclaw doctor

#

openclaw doctor --yes

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

openclaw doctor --repair

Apply recommended repairs without prompting (repair + restart if safe).

openclaw doctor --repair --force

Also apply aggressive repairs (overwrite custom supervisor configs).

openclaw doctor --non-interactive

Run without prompting, only apply safe migrations (config normalization + disk state moves). Skip restart/service/sandbox operations that require human confirmation. Automatically runs when legacy state migration is detected.

openclaw doctor --deep

Scan system services for additional gateway installations (launchd/systemd/schtasks).

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

cat ~/.openclaw/openclaw.json

- Optional pre-run update for git installs (interactive only).

- UI protocol freshness check (rebuild control UI when protocol schema is newer).

- Health check + restart prompt.

- Skill status summary (eligible/missing/blocked).

- Configuration normalization of legacy values.

- OpenCode Zen provider override warning ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'models.providers.opencode'</code>').

- Legacy disk state migration (sessions/agent directories/WhatsApp auth).

- State integrity and permission checks (sessions, transcripts, state directories).

- Local runtime config file permission check (chmod 600).

- Model auth health: checks OAuth expirations, can refresh expired tokens, and reports auth profile cooldown/disabled status.

- Extra workspace directory detection ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/openclaw'</code>').

- Sandbox image repair when sandbox is enabled.

- Legacy service migration and extra gateway detection.

- Gateway runtime check (service installed but not running; cached launchd labels).

- Channel status warnings (probed from running gateway).

- Supervisor config audit (launchd/systemd/schtasks) and optional repair.

- Gateway runtime best practices check (Node vs Bun, version manager paths).

- Gateway port conflict diagnostics (default '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'18789'</code>').

- Security warning for open DM policy.

- Gateway auth warning when '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.auth.token'</code>' is not 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 (e.g. '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.ackReaction'</code>' without channel-specific overrides), doctor normalizes them to the current schema.

#

ReferenceGatewayDoctorPage.step06.p3

ReferenceGatewayDoctorPage.step06.p4

When config contains deprecated keys, other commands will refuse to run and ask you to run '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>'.

Doctor will:

- Explain which legacy keys were found.

- Show the migrations it applies.

- Rewrite '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/openclaw.json'</code>' with updated schema.

Gateway also auto-runs doctor migration on startup when it detects abnormal legacy config formats, so stale configs are fixed without manual intervention.

Current migrations:

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.allowFrom'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channels.whatsapp.allowFrom'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.groupChat.requireMention'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channels.whatsapp/telegram/imessage.groups."*".requireMention'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.groupChat.historyLimit'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.groupChat.historyLimit'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.groupChat.mentionPatterns'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.groupChat.mentionPatterns'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.queue'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'messages.queue'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.bindings'</code>' → top-level '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bindings'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.agents'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.defaultAgentId'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.list'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.list[].default'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.agentToAgent'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tools.agentToAgent'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'routing.transcribeAudio'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tools.media.audio.models'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bindings[].match.accountID'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bindings[].match.accountId'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'identity'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.list[].identity'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agent.*'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tools.*'</code>' (tools/elevate/exec/sandbox/subagents)

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agent.model'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'allowedModels'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'modelAliases'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'modelFallbacks'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'imageModelFallbacks'</code>' → '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.models'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.model.primary/fallbacks'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.imageModel.primary/fallbacks'</code>'

#

If you've manually added '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'models.providers.opencode'</code>' (or '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'opencode-zen'</code>'), it overrides the built-in OpenCode Zen catalog in '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'@mariozechner/pi-ai'</code>'. That can force a single API for all models or zero costs. Doctor warns that you can delete the override and restore per-model API routing + costs.

#

Doctor can migrate old disk layouts to current structure:

- Session storage + transcripts:

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/sessions/'</code>' to '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/agents/'<agentId>'/sessions/'</code>'

- Agent directories:

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/agent/'</code>' to '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/agents/'<agentId>'/agent/'</code>'

- WhatsApp auth state (Baileys):

- From legacy '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/credentials/*.json'</code>' (excluding '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'oauth.json'</code>')

- To '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/credentials/whatsapp/'<accountId>'/...'</code>' (default account ID: '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'default'</code>')

These migrations are best-effort and idempotent. Doctor warns that it leaves all old folders as backups. Gateway/CLI also auto-migrate legacy sessions + agent directories on startup, so history/auth/models are placed in per-agent paths without running doctor manually. WhatsApp auth is only migrated intentionally via '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>'.

#

The state directory is the brainstem of operations. If it disappears, sessions, credentials, logs, and config are lost (unless backed up elsewhere).

Doctor checks:

- <strong>Missing state directory</strong>: warns about catastrophic state loss, prompts to recreate directory, reminds that lost data cannot be recovered.

- '<strong>'State directory permissions'</strong>': verifies writable, offers to fix permissions (outputs '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'chown'</code>' prompt if owner/group mismatch detected).

- '<strong>'Missing session directory'</strong>': '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'sessions/'</code>' and session storage directories hold history and are needed to avoid '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'ENOENT'</code>' crashes.

- <strong>Transcript mismatches</strong>: warns when recent session entries are missing transcript files.

- <strong>Master session "1-line JSONL"</strong>: flags when master record has only one line (history not accumulating).

- '<strong>'Multiple state directories'</strong>': warns when multiple '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw'</code>' folders exist in primary directory, or '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'OPENCLAW_STATE_DIR'</code>' points elsewhere (history may be split across installs).

- '<strong>'Remote mode reminder'</strong>': if '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.mode=remote'</code>', doctor reminds to run on remote host (state is there).

- '<strong>'Config file permissions'</strong>': if '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'~/.openclaw/openclaw.json'</code>' exists and is group/world-readable, offers to tighten to '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'600'</code>'.

#

Doctor checks OAuth profiles in the auth store, warns when tokens are near/past expiration, and can refresh them when safe. If Anthropic Claude password profile is stale, it suggests running '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'claude setup-token'</code>' (or pasting a setup token). Refresh prompts only appear when running interactively (TTY). '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'--non-interactive'</code>' skips refresh attempts.

Doctor also reports auth profiles that are temporarily unavailable due to:

- Short cooldown (rate limit/timeout/auth failure)

- Long disabled period (billing/credit failure)

#

If '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.gmail.model'</code>' is set, doctor validates the model reference against the model catalog and whitelist, warning if it can't be resolved or isn't allowed.

#

If sandbox is enabled, doctor checks the Docker image and offers to build or switch to the current image name if none is present.

#

Doctor detects legacy gateway services (launchd/systemd/schtasks) and offers to delete them and install an OpenClaw service on the current gateway port. It can also scan for additional gateway-like services and print cleanup prompts. Named OpenClaw gateway services in config are considered first-class and not flagged as "additional".

#

Doctor warns if providers are open to DMs without an allowlist, or if policies are set dangerously.

#

If running as a systemd user service, doctor checks that linger is enabled so the gateway remains active after logout.

#

Doctor prints a brief summary of current eligible/missing/blocked skills in the workspace.

#

If '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'gateway.auth'</code>' is missing on a local gateway, doctor warns and offers to generate a token. Use '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --generate-gateway-token'</code>' to force token creation for automation.

#

Doctor runs a health check and if unhealthy, offers to restart the gateway after checks.

#

If the gateway is healthy, doctor runs channel status probes and reports warnings with suggested fixes.

#

Doctor checks installed supervisor configs (launchd/systemd/schtasks) for missing or stale defaults (e.g. systemd network-online dependencies and restart delays). If it finds mismatches, it offers to update and can rewrite service files/tasks to current defaults.

Notes:

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor'</code>' prompts before rewriting supervisor configs.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --yes'</code>' accepts default repair prompts.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --repair'</code>' applies recommended repairs without prompting.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw doctor --repair --force'</code>' overwrites custom supervisor configs.

- You can always force a full rewrite via '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw gateway install --force'</code>'.

#

Doctor checks service runtime (PID, last exit status) and warns if service is installed but not actually running. It also checks for port conflicts on the gateway port (default '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'18789'</code>'), reporting possible causes (gateway already running, SSH tunnel).

#

If gateway service is running with Bun or a versioned Node path, doctor warns ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'nvm'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'fnm'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'volta'</code>', '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'asdf'</code>', etc.). WhatsApp + Telegram channels require Node, and version manager paths can break after upgrades since services don't load shell initialization. Doctor offers to migrate to a system Node install if available (Homebrew/apt/choco).

#

Doctor persists config changes and marks wizard metadata to record that doctor was run.

#

Doctor suggests using the workspace memory system if you're lost, and prints a backup prompt if the workspace isn't already under git.

See '<a href="/concepts/agent-workspace" className="text-emerald-400 hover:text-emerald-300 transition-colors">'/concepts/agent-workspace'</a>' for a complete guide on workspace structure and git backups (private GitHub or GitLab recommended).