openclaw doctor: the supported postures, ready-to-run
examples, and every option the command accepts.
If a plugin fails to load during Doctor, the report includes an error finding
with the plugin ID, source path, and error. ENOSPC failures name the disk-space
cause. Standalone doctor --non-interactive exits 1 for these failures and
reports that Doctor finished with plugin load errors. When an updater invokes
Doctor, the same failures remain recorded warnings so an otherwise safe update
can continue; rerun Doctor after resolving the reported cause.
Postures
Doctor supports these postures:
Use
openclaw doctor --json when an operator or script wants the advisory Doctor report as JSON. It exits successfully after producing a report; inspect ok and findings for health state. Use explicit openclaw doctor --lint --json when CI should exit nonzero for findings at the selected severity threshold. Prefer --fix when a human operator wants Doctor to edit config or state.
For read-only diagnosis, use --lint or bare --json. Ordinary doctor, including doctor --non-interactive, can copy legacy config and migrate state even without --fix. --non-interactive suppresses prompts, not writes.
When ordinary doctor asks Apply recommended config repairs now?, it checks
that the selected root config file still matches the source of that proposal.
If its contents or selected path changed before the write, Doctor preserves the newer file,
leaves the pending config fixes unwritten, and exits with an error. Rerun
openclaw doctor to review an updated proposal.
If saving succeeds but later processing fails, Doctor stops with an error, names
the file that was written, and reports whether the write was rolled back. When it was not rolled
back or recovery could not be confirmed, inspect that file and the active config
before rerunning Doctor.
If the shared state database uses a newer schema, Doctor refuses before offering
an interactive update because update admission also needs that database. Run
Doctor from the OpenClaw install that wrote the state, or another compatible
build. A readable shared database still permits an interactive source update
when agent databases use newer schemas; if the update does not take over,
Doctor checks all database schemas again before diagnostics or repair. See
Database schemas.
After an exec-approval format upgrade, Doctor reports older generated approvals
that are no longer active because they were not tied to a working directory.
openclaw doctor --fix removes those inactive generated entries and leaves
manual allowlist rules unchanged. Rerun affected workflows and choose
Always allow here to renew trust for the intended directory. The normal
openclaw update finalization runs this safe repair automatically.
Explicit repair stops the matching managed Gateway and checks Gateway, state,
and agent-database ownership before taking read-only schema snapshots. It
excludes other processes during repair, then restarts the same service once
and verifies readiness. Policy refresh preserves the installed launcher and
environment. Separately, eligible installation drift
in a previously running service is reconciled through the native installer.
Automatic installation refresh covers installation-only drift; other operator
edits or uncertain inspection still require interactive confirmation. Services
confirmed offline before maintenance keep their launcher and stop state; Linux
policy can refresh without activation as described below. Use the reported
profile-aware openclaw gateway install --force command to reconcile their
installation drift (installation may start the service). On Linux, Doctor also
restores a previously running service if systemd unloads the stopped unit during
repair; a changed service definition or manager still blocks restart. A loaded, enabled
macOS job between respawns is not offline: Doctor stops it before repair and
resumes it afterward. Run repair from a shell outside the Gateway process tree. For externally supervised or unmatched installations, stop
and start the Gateway through its owning supervisor.
Before a Linux maintenance stop, Doctor backs up and refreshes outdated OpenClaw
unit policy and confirms daemon-reload. Operator drop-ins remain unchanged.
The current service stop policy is 330 seconds. A resident Gateway can still have
an older, shorter shutdown budget: published 2026.9.5 cached that budget at startup.
For a short or unreported resident budget, maintenance asks the Gateway to fence
new admission and drain existing work, stopping as soon as it reports idle.
The wait uses the update’s existing per-step deadline (30 minutes by default).
At that deadline, admitted turns may be interrupted with a warning; a reported
write-custody phase, such as session mutation or terminal persistence, refuses the
stop and names its owner phase. Older residents without the custody observation
stop at the deadline with a warning naming active root requests and cron runs;
unknown custody is not a refusal. An owned service confirmed offline can receive
the policy refresh without being started.
During automatic triage, repair can run
against an offline target when schema and maintenance locks permit it. If repair
needs to stop the managed Gateway, Doctor refuses inside its automatic fixing
subtree because that stop would cancel recovery. Use read-only diagnosis or safe
offline artifact repair followed by an atomic openclaw gateway restart, or ask
an independent operator to run Doctor from a shell outside triage.
Read-only database snapshots and initial integrity scans have a 30-second
execution limit per database. A timeout names the database and asks you to stop
its Gateway service and other OpenClaw processes before retrying. If all writers
are stopped, inspect storage performance and the reported database; a timeout
does not prove corruption.
openclaw doctor --fix --non-interactive applies the supported migrations that
block Gateway startup without prompting, including shared-state audit schema,
legacy workspace setup, legacy session stores, and exec approvals. Malformed or
conflicting input is retained and requires the manual action in the diagnostic.
The updater uses this repair path before accepting the installed target.
Update-time Doctor runs startup-required repairs before optional inspections.
On large fleets it can defer auth and model diagnostics, plugin inspection,
skills and workspace metadata, session-snapshot cleanup, and advisory lint to
reserve time for required repairs and update validation. Each deferred check
appears as an update-inspection-deferred warning in Doctor output and the
update outcome, with the reason and remaining inspection allowance. A deferred
check did not pass or fail; it was not run.
Run openclaw doctor --fix after activation to complete those checks and review
optional repairs. An ordinary Doctor run does not retain the update’s inspection
limit. Required session, database, workspace-state, and exec-approval readiness
checks still run during the update. Project-clone inspection, SQLite database-size
advice, and workspace backup and memory suggestions retain their standalone scope.
This maintenance window also applies when repair ultimately finds no changes.
Runs without --fix, --repair, or --yes do not enter maintenance.
Custom state directories remain runtime-only and do not adopt a native service.
--force alone does not select repair mode: openclaw doctor --force remains
guided and still requires interactive consent before an eligible service rewrite.
With --fix, --repair, or --yes, it allows aggressive config/state repairs
with the same installation-drift and Linux policy-refresh rules above. Force does
not bypass service
ownership, write-access, or interactive-only confirmation requirements.
During an update, Doctor respects the updater’s service activation policy.
If the running Gateway has an old version/build or cannot load its WebSocket
handler after package replacement, Doctor stops that stale instance through
the verified service manager and confirms its process and listener are gone.
It retains service custody while running offline repairs, including legacy session
imports, then restarts the service and verifies the candidate’s version and build
ID over RPC. Startup can require those imports, so candidate readiness is checked
after maintenance. A warning names the replaced PID and verified serving build.
HTTP health alone does not prove recovery. A refused stop or unverified restoration
records the failed phase and exact recovery commands in the update result.
Legacy post-core convergence retains service maintenance custody while its fresh
Doctor processes run, then restores the Gateway before publishing completion.
An ordinary healthy Gateway still follows the parent’s activation policy;
openclaw update --no-restart does not grant state-repair access to a live writer.
Unavailable service inspection becomes a warning and grants no service-control
authority. Doctor still checks Gateway/state coordinators, agent-database leases,
and the temporary-file lock used by older Gateways such as 2026.6.33 before
repair. A live or unverifiable legacy lock owner blocks repair and names its PID
and lock path; stop that Gateway through its service owner, then run
openclaw doctor --fix from an independent shell. An unmatched service that can
still run also blocks maintenance; inspect it with openclaw gateway status --deep.
Once the native manager confirms it is offline, Doctor can repair its selected
state without changing or starting that service. A stopped or disabled systemd
unit need not remain loaded in the manager for state repair to proceed.
If migration or config repair cannot finish, Doctor leaves the stopped service
stopped and reports an incomplete repair with exit code 1. When state requires
manual recovery, the diagnosis names its path and the next action:
- Unsupported canonical workspace version: use an OpenClaw build that supports that version. Preserve the shared database unchanged.
- Unreadable or conflicting exec policy: stop the Gateway and node hosts, then reconcile the named legacy file or interrupted claim with a verified copy of the intended policy. Preserve the existing SQLite policy.
Examples
doctor:
channels capabilities reports the bot’s effective permissions for a specific channel target. channels status --probe audits all configured channels and voice auto-join targets.
Options
--severity-min, --all, --only, and --skip are only accepted together with --lint. Bare --json uses the default read-only lint check selection but keeps Doctor’s advisory exit behavior. Both read-only postures reject --repair, --fix, --force, --yes, and --generate-gateway-token. Explicit --lint also rejects --session-sqlite modes and their selectors, including --github-issue. Other machine modes can still use --json for their own output.