The OpenClaw doctor

The doctor is the command every troubleshooting page in the OpenClaw docs ends with: the repair and migration tool that fixes stale config and state, checks health and gives actionable repair steps. It is also more careful than the name suggests, with a read-only mode for automation and a set of flags that say exactly how much it may touch. Here is the command, its modes, the difference between lint and fix, and a tour of what it checks, grouped the way the docs group it.

The modes

• Plain: guided checks with prompts, applying safe migrations and confirmed repairs, and a friendly health report.
• Yes, or fix: accept the default non-service repairs without prompting, entering maintenance while preserving the installed Gateway service definition; the repair alias means the same; force adds aggressive config and state repairs, and replacing a launcher is a separate install command.
• Non-interactive: no prompts and only safe migrations, config normalization and on-disk state moves, skipping restarts, services and sandbox actions; with fix it also applies the startup-blocking repairs such as workspace setup, session stores, exec approvals and audit schema migrations, checking ownership before touching a database.
• Deep scans the system services for extra Gateway installs; lint is the read-only sibling described next.

Read-only: no prompts, repairs, migrations, restarts, or state writes.

Lint versus fix

Lint and fix share the same rule registry but do not select or act on rules the same way. Lint runs structured health checks for CI and preflight automation, with a JSON form, and by default the broad-safe profile: static, local checks, skipping the advisory, environment-sensitive, live-service, inventory and historical-cleanup ones, which an all flag adds back and an only flag narrows to one. Fix does not use that profile and does not accept all: it runs the ordered repair path, where modern checks may offer a repair and older areas keep their legacy flow, and some lint findings are diagnostic only, so a finding in lint does not mean fix will change that area.

What it checks

• Health, UI and updates: an optional pre-flight update for git installs, a Control UI protocol freshness rebuild, a health check with a restart prompt, problem-only skill and plugin notes, and MCP server schema failures reported without stopping the rest.
• Config and migrations: normalization of legacy shapes, the legacy key table, the Talk, browser, Codex and plugin-manifest migrations, allowlist warnings, on-disk state moves, cron store and workspace file migrations, and stale plugin config cleanup.
• State and integrity: session locks, transcript branch repair, wedged-session tombstones, state and config permissions, and model auth health with token refresh.
• Gateway, services, supervisors, security and pairing: sandbox image repair, service migration and extra-install detection, channel status warnings, Codex route repair, supervisor config audit, proxy environment cleanup, port collision diagnostics, and warnings for open DM policies.

The OpenClaw config file explains the strict validation the doctor repairs against, and OpenClaw update failed the case where a failed update sends you here.

When to run it

After an upgrade, after a hand edit that the Gateway refuses, when a service is installed but not running, and before asking for help, because the docs’ issue templates assume you have. Read the config file first if you want to review changes before they are written. OpenClaw terminal commands lists it among the commands that work even when the Gateway does not start.

On Diali

On Diali the doctor runs as part of every release we roll out, and its findings are ours to act on before an instance restarts; the equivalent for you is the dashboard’s health view rather than a terminal. Hosted OpenClaw on Diali is the assistant.

• Lint reads; fix writes; force writes more.
• Non-interactive means safe migrations only unless fix is added.
• Six groups of checks, from config keys to open DM policies.