openclaw/docs/cli/doctor/lint.md

Multi-channel AI gateway with extensible messaging integrations

---
summary: "Read-only lint findings, check selection, and post-upgrade plugin checks"
title: "Lint and post-upgrade modes"
read_when:
  - You want a read-only health report for CI or deployment preflight
  - You are chaining doctor after a build or upgrade
---

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

## 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. Policy findings reported here are documented in [`openclaw policy`](/cli/policy).

The setup assistant's `doctor` action uses this read-only lint posture in an isolated
process. It reports findings without applying repairs or migrations. Run
`openclaw doctor --fix` separately on the Gateway host when you intend to repair state.

Full reports reuse a private shared-state snapshot for ordinary reads within the
report, preserving the live database and its WAL files. Each new report reads a
fresh snapshot. Checks that need writable inspection state or independent database
verification retain their own copies; `--only` checks prepare state on demand.

Read-only reports preserve existing SQLite database, WAL, and shared-memory files,
including their modification times. An older shared-state schema produces a
"migration pending" finding with `openclaw doctor --fix` guidance; inspection does
not upgrade it. Ordinary Doctor and explicit repair retain their migration behavior.

Doctor retires private database readers and writers before removing inspection
snapshots. A cleanup failure preserves completed findings and check counts;
updater runs report failed temporary-file removal as a warning. If database
retirement fails, Doctor reports the error and leaves the private snapshot in place.

Plugin source captures use the original profile's temporary storage, outside these
database snapshots. Their plugin-cache owner retains them until plugin inspection
finishes, so later channel setup checks can reuse admitted native files safely.

```bash
openclaw doctor --json
openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --allow-exec
openclaw doctor --lint --only core/doctor/gateway-config --json
openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info
openclaw 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:

```text
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:

```json
{
  "schemaVersion": 1,
  "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:

| Code | Meaning                                                  |
| ---- | -------------------------------------------------------- |
| `0`  | No findings at or above the selected severity threshold. |
| `1`  | At least one finding meets the selected threshold.       |
| `2`  | Command/runtime failure before health checks complete.   |

`--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.

When the updater runs lint, warning-severity findings below its error threshold are retained in a separate JSON `warnings` array. They do not change the lint exit code. The updater records these advisories in its run history, including intentional open channel policies, so they remain available in `openclaw update status`. Ordinary standalone lint keeps the selected output threshold.

If a caller cancels state-lease acquisition before an inspection starts, Doctor records
an informational diagnostic with `errorCode: OPENCLAW_STATE_LEASE_ABORTED`, the elapsed
time, and the caller's signal as its cause. Below the selected threshold, this diagnostic
appears in JSON `warnings` and human output without failing lint. It means the inspection
was not performed. Cancellation after acquisition and other inspection failures remain errors.

During updates, optional inspections and policy advisories are warnings, including intentional open DM policies. Required configuration, state, and startup checks remain blocking. The saved report retains every finding with an individually bounded reason; update history keeps severity counts, deciding errors, and an explicit omission count when its diagnostic bound is reached.

Security findings retain their specific check identifier and remediation in update reports. Secret migration commands appear before long field lists so bounded diagnostics keep the `openclaw secrets configure` and `openclaw secrets apply` next steps.

`PLAINTEXT_FOUND`, `REF_SHADOWED`, and `LEGACY_RESIDUE` are findings from the separate `openclaw secrets audit` command. They describe hardening or retained recovery material, not database corruption. Standalone `secrets audit --check` can exit nonzero for these findings; that result alone does not identify a failing candidate Doctor check. Use the candidate's recorded lint findings, not a truncated stderr tail, to identify the update failure.

A configured Codex plugin that is missing or whose advertised health API cannot be
verified produces an availability warning under `core/doctor/codex-session-routes`,
with the plugin name and repair command. Untrusted installations are not imported
to inspect their health API.
The updater's `--severity-min error` pass exits `0` for these warnings, using the
same warning policy as Gateway startup. Invalid configuration, unsafe state
inspection, and errors reported by an actual health check retain their failures.
Missing configured `plugins.load.paths` produce a warning under
`core/doctor/final-config-validation`, with requirement
`configured-plugin-path-unavailable` and the unavailable path in `source`.
Permission, I/O, and other inspection failures instead use
`configured-plugin-path-inspection-failed`, retain the filesystem `errorCode`
and error message, and provide a recovery hint for the affected path.
The updater retains the warning and continues. Doctor preserves settings whose
plugin owner could not be inspected; see [Plugin repair warnings](/install/update-troubleshooting#plugin-repair-warnings).

Bare `openclaw doctor --json` exits `0` once it emits a findings payload, including when `ok` is `false`. Argument errors remain nonzero. If the lint runner fails before producing a report, Doctor exits `2` and emits one redacted JSON document with `ok: false`, `checksRun: 0`, and an error finding under `core/doctor/lint-inspection`. It retains the `error: { type: "cli_error", message }` field for existing consumers. This readiness shape is accepted by published updaters, including 2026.9.5, without treating an inspection failure as a successful check.

`--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/session-snapshots` reports stale paths in retained legacy session
metadata as informational findings. It preserves the original files even under
`--fix`; active sessions use canonical SQLite state and the current runtime skill
catalog. Historical snapshot paths do not require cleanup or a session reset.

`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.

## Check selection

```bash
openclaw doctor --lint --only core/doctor/gateway-config --json
openclaw 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.

`core/doctor/runtime-tool-schemas` does not check OAuth-backed MCP servers in read-only
Doctor reports, including triage and update checks. A check can rotate a refresh token
at the external server even when local state writes go to a disposable snapshot.
Doctor reports this deferral at informational severity; use `--severity-min info` to
display it. For servers in `mcp.servers`, run `openclaw mcp probe <name>` against the
serving configuration. Validate plugin-provided servers or agent-local auth profiles
from an authenticated serving-agent turn so refreshed credentials persist with their
owner. Non-OAuth MCP schema checks still run.

## Post-upgrade mode

`openclaw doctor --post-upgrade` runs plugin compatibility checks 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 checks 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.