Lint and post-upgrade modes

Doctor's read-only postures produce findings without changing config or state. This page covers lint output, check selection, and post-upgrade probes.

Lint mode

Bare openclaw doctor --json is read-only and non-interactive: no prompts, repairs, or config/state rewrites. It emits the same default findings as lint mode, but exits 0 after a report is produced so output formatting does not change ordinary Doctor's advisory success contract. Read the payload's ok and findings fields to determine health.

Explicit openclaw doctor --lint is the deployment-preflight posture. Add --json for machine-readable output without changing lint's threshold-based exit code.

openclaw doctor --jsonopenclaw doctor --lintopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --jsonopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min infoopenclaw doctor --lint --only memory-core/managed-local-embedding-setup --severity-min error --json

The managed local embedding setup check is a scoped, non-mutating pre-cutover gate for existing semantic indexes. It is opt-in through --only or --all, so plain doctor --lint behavior stays unchanged. It reports missing llama.cpp setup and the interactive models auth login remediation without claiming full Gateway readiness, starting services, downloading models, or changing config.

Human output is compact:

doctor --lint: ran 6 check(s), 1 finding(s)  [warning] core/doctor/gateway-config gateway.mode - gateway.mode is unset; gateway start will be blocked.    fix: Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`.

JSON output is the scripting surface:

{  "ok": false,  "checksRun": 5,  "checksSkipped": 0,  "findings": [    {      "checkId": "core/doctor/gateway-config",      "severity": "warning",      "message": "gateway.mode is unset; gateway start will be blocked.",      "path": "gateway.mode",      "fixHint": "Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`."    }  ]}

Explicit lint exit codes:

--severity-min controls both which findings print and the exit threshold: openclaw doctor --lint --severity-min error can print nothing and exit 0 even when lower-severity info/warning findings exist.

Bare openclaw doctor --json exits 0 once it emits a findings payload, including when ok is false. Argument errors or runtime failures before a payload can be produced remain nonzero.

--all controls which checks are selected before severity filtering. The default lint run excludes checks that are deep, historical, or more likely to surface repairable legacy residue; use --all for the complete inventory. --only <id> is the most precise selector and can run any registered check by id.

core/doctor/local-audio-acceleration reports the auto-selected local STT command, separate capable/requested/observed backend evidence, and fallback order without loading a speech model. It emits an informational finding, so include --severity-min info to display it.

core/doctor/skill-workshop-relocation distinguishes pending legacy collection backup roots from roots preserved for review. Eligible proposals or backup roots receive openclaw doctor --fix guidance, not a guarantee that every backup will be retired. Preserved roots require manual review of workspace ownership, backup manifests, and workspace migration blockers. If both kinds remain, Doctor reports both next steps. Do not delete preserved backups to clear the warning.

Check selection

openclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --skip core/doctor/skills-readiness

--only and --skip accept full check ids and may be repeated. An unregistered --only id emits a core/doctor/lint-selection error finding; valid selected checks still run. Use checksRun/checksSkipped in the output to confirm a focused gate selects the checks you expect.

To check model credentials, run openclaw doctor --lint --only core/doctor/auth-profiles --json. This opt-in check inspects shared credentials and each configured agent's local auth store, including fleets without a default agent. Shared credential problems are reported once; agent-specific cooldowns remain attributed to their local store.

Post-upgrade mode

openclaw doctor --post-upgrade runs plugin compatibility probes for chaining after a build or upgrade. Findings go to stdout; exit code is 1 if any finding has level: "error". Add --json for a machine-readable envelope ({ probesRun, findings }), suitable for CI, the community fork-upgrade skill, and other post-upgrade smoke tooling. If the installed plugin index is missing or malformed, JSON mode still emits the envelope with a plugin.index_unavailable error finding.

The probes also warn with plugin.version_drift when an enabled official plugin in the installed index belongs to a different release cohort than the upgraded OpenClaw CLI. Follow the reported plugin update command, then restart the Gateway. Exact npm pins receive an update command only after the registry confirms that target exists. Independently versioned community plugins and disabled plugins are excluded; version drift alone does not change the exit code.

Container image startup is the exception to the usual "run doctor after updating" flow. When openclaw gateway run starts on a new OpenClaw version, it runs safe state and plugin repairs before reporting ready. If repair cannot finish safely, startup exits and tells you to run the same image once with openclaw doctor --fix against the same mounted state/config before restarting the container normally.