On this page
On this page
CLI commands
Structured health check contract
This page describes the structured health check contract for check authors. Operators do not need it to run doctor.
Structured health checks
To inspect registry clone shape, run
openclaw doctor --lint --only core/doctor/project-clone-shape --json.
This check also runs in ordinary Doctor and --lint --all. Unreadable clones
produce a skipped-inspection warning without aborting the remaining checks.
openclaw doctor --fix unshallows managed project clones while retaining
blob:none under the project checkout lifecycle lease. It skips busy clones and
does not repack or remove promisor settings. See
project clone repair.
Doctor checks that use the structured health registry declare a small split contract:
detect() powers doctor --lint. repair() is optional and only runs under doctor --fix / doctor --repair. Doctor contributions that declare only a run() handler instead of healthChecks are not exposed through this contract.
Repair contexts can carry dryRun/diff requests; repair results can return structured diffs (config/file edits) and effects (service, process, package, state, or other side effects), so converted checks can grow toward doctor --fix --dry-run without moving mutation planning into detect().
repair() reports status: "repaired" | "skipped" | "failed" (omitted status means repaired). When repair returns skipped or failed, doctor reports the reason and skips validation for that check. After a successful repair, doctor re-runs detect() scoped to the repaired findings; if the finding is still present, doctor reports a repair warning instead of treating the change as complete.
A finding includes:
| Field | Purpose |
|---|---|
checkId |
Stable id for skip/only filters and CI allowlists. |
severity |
info, warning, or error. |
message |
Human-readable problem statement. |
path |
Config, file, or logical path when available. |
line / column |
Source location when available. |
ocPath |
Precise oc:// address when a check can point to one. |
fixHint |
Concrete next step; say when no action is needed. |
category |
Optional fix-now, recommended, or historical operator priority, independent of severity. |
docsUrl |
Documentation explaining the finding and its remedy. |
Core doctor checks that declare structured health checks stay attached to the ordered doctor contribution that owns their human doctor / doctor --fix behavior. The shared structured health registry is the extension point: bundled and plugin-backed checks run after core doctor checks once their owning package registers them in the active command path. openclaw/plugin-sdk/health exposes the same contract for plugin authors.
Set category at the producing check. Do not classify free-form message text. Absent a category, warning/error findings require attention and info findings are recommendations. Historical findings describe retained evidence, not current readiness. Doctor summarizes remaining findings after repair verification.
Model-reference retirement inventory
The internal openclaw/plugin-sdk/doctor-repair-runtime surface exports
inspectDoctorModelReferences({ cfg, env, matches })
for provider retirement checks. It resolves configured model aliases and reads
saved session selectors and the selected cron partition without editing state
or loading transcripts. The result contains references (path, canonical model
reference, optional agent ID) and warnings for incomplete scans. Report those
warnings as findings; an unreadable store is not evidence of a clean migration.
