vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-10-06 13:36:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 29
openclaw/docs/cli/doctor.md
Peter Steinberger 588b5d7d50
fix: avoid slow requester checks during Doctor repairs (#162200) 
Doctor requester-authority validation copied the entire SQLite database in a synchronous worker on every authority callback (195 snapshot launches, 31 s for the configured-owner case; candidate Doctor 74 s). Maintenance now owns one reusable live reader; admission, physical file identity, and revocation are re-checked on every reused read, and the reader joins maintenance and database cleanup. Configured-owner case 31.4 s -> 3.6-4.6 s; snapshot launches <= 8 during admission, zero during maintenance.

Refs #161949
Refs #161867
2026-09-30 17:26:18 -07:00

6.6 KiB
Raw Blame History

summary read_when title
CLI reference for `openclaw doctor` (health checks + guided repairs)
You have connectivity/auth issues and want guided fixes
You updated and want a sanity check
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.

During a chat-requested update, Doctor rechecks the original requester's current owner permissions between repair steps. Removing or replacing that owner prevents further changes. After the pre-mutation backup boundary, these checks reuse the maintenance session's live reader instead of repeatedly copying the shared database.

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.

Doctor reports sessions whose usage-cost cache refresh failed, since their totals may be incomplete. Check the Gateway logs and request usage again to retry. The bounded failure history keeps the latest 256 sessions across restarts; a successful refresh clears that session's warning. --fix does not clear a warning before the session has refreshed successfully.

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.

Related