OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Doctor CLI

openclaw doctor

Health checks and quick fixes for the gateway, channels, plugins, skills, model routing, local state, and config migrations. Use it whenever something is not behaving as expected and you want one command to explain what is wrong.

When run for a managed Gateway, Doctor compares active official plugins with the OpenClaw package referenced by the installed service. This check still works when the Gateway is stopped or unreachable. When an older Gateway is still running, Doctor reports its version separately from the post-restart version. If the service package cannot be identified, Doctor reports restart readiness as unknown instead of treating the plugin set as compatible.

When Gateway status reports degraded SecretRef owners, doctor prints a Secret runtime degradation warning with every cold or stale owner, affected config path, redacted reason, and the openclaw secrets reload retry command.

When channel ingress events are dead-lettered, doctor names each affected channel account and points to openclaw channels dead-letters list for inspection and recovery.

Doctor warns when a registry-owned project clone is partial or shallow. It names the clone, shallow state, and partial-clone config keys, including URL-keyed remote twins. It prints manual repair commands; --fix does not fetch or repack these clones. Agent workspaces and manually registered checkouts are excluded.

When the Gateway has exporter health facts, doctor reports the latest trusted per-signal state and transport under Telemetry exporters. The summary is redacted and does not include endpoint values, headers, certificates, payloads, or raw errors.

Related:

Doctor pages

This page is an index. openclaw doctor is documented on seven pages, one per reader job. Open the page that matches your task.

Page Read it when
Run doctor Pick a posture, copy a working example, or look up what an option does.
Gateway and service recovery The Gateway service, remote target, Control UI assets, or Gateway token needs repair.
Lint and post-upgrade modes You want read-only findings for a CI gate, or post-upgrade plugin compatibility probes.
Structured health check contract You are writing a doctor check or a plugin-backed health check.
Legacy state migration A file-to-SQLite migration is blocked and needs manual reconciliation.
SQLite maintenance and session migration You are compacting a database, or importing, validating, or recovering session history.
Other checks and repairs You want the inventory of every remaining check and repair, from Nix mode to channels.

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /cli/doctor#session-sqlite-migration still resolves. Each entry points at the page that now holds the content.

Was this useful?
On this page

On this page