- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)

- Security audit: [Security](/gateway/security)

## Why Use It

`openclaw doctor` is the OpenClaw health surface. Use it when the gateway,

channels, plugins, skills, model routing, local state, or config migrations are

not behaving as expected and you want one command that can explain what is

wrong.

Doctor has three postures:

| Posture | Command | Behavior |

| ------- | ------------------------ | ------------------------------------------------------------------------------- |

| Inspect | `openclaw doctor` | Human-oriented checks and guided prompts. |

| Repair | `openclaw doctor --fix` | Applies supported repairs, using prompts unless non-interactive repair is safe. |

| Lint | `openclaw doctor --lint` | Read-only structured findings for CI, preflight, and review gates. |

Prefer `--lint` when automation needs a stable result. Prefer `--fix` when a

human operator intentionally wants doctor to edit config or state.

## Examples

```bash

openclaw doctor

openclaw doctor --repair

openclaw doctor --lint

openclaw doctor --lint --json

openclaw doctor --lint --severity-min warning

openclaw doctor --deep

openclaw doctor --repair --non-interactive

openclaw doctor --fix

openclaw doctor --fix --non-interactive

openclaw doctor --generate-gateway-token

```

- `--non-interactive`: run without prompts; safe migrations and non-service repairs only

- `--generate-gateway-token`: generate and configure a gateway token

- `--deep`: scan system services for extra gateway installs and report recent Gateway supervisor restart handoffs

- `--lint`: run modernized health checks in read-only mode and emit diagnostic findings

- `--json`: with `--lint`, emit JSON findings instead of human output

- `--severity-min <level>`: with `--lint`, drop findings below `info`, `warning`, or `error`

- `--skip <id>`: with `--lint`, skip a check id; repeat to skip more than one

- `--only <id>`: with `--lint`, run only a check id; repeat to run a small selected set

## Lint mode

`openclaw doctor --lint` is the read-only automation posture for doctor checks.

It uses the structured health-check path, does not prompt, and does not repair

or rewrite config/state. Use it in CI, preflight scripts, and review workflows

when you want machine-readable findings instead of guided repair prompts.

Lint-output options such as `--json`, `--severity-min`, `--only`, and `--skip`

are only accepted with `--lint`.

```bash

openclaw doctor --lint

openclaw doctor --lint --severity-min warning

openclaw doctor --lint --json

openclaw doctor --lint --only core/doctor/gateway-config --json

```

Human output is compact:

```text

doctor --lint: ran 5 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 for lint runs:

```json

{

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

}

]

}

```

Exit behavior:

- `0`: no findings at or above the selected severity threshold

- `1`: at least one finding meets the selected threshold

- `2`: command/runtime failure before lint findings can be produced

`--severity-min` controls both visible findings and the exit threshold. For

example, `openclaw doctor --lint --severity-min error` can print no findings and

exit `0` even when lower-severity `info` or `warning` findings exist.

## Structured Health Checks

Modern doctor checks use a small structured contract:

```ts

detect(ctx, scope?) -> HealthFinding[]

repair?(ctx, findings) -> HealthRepairResult

```

`detect()` powers `doctor --lint`. `repair()` is optional and is only considered

by `doctor --fix` / `doctor --repair`. Checks that have not migrated to this

shape continue to use the legacy doctor contribution flow.

The split is intentional: `detect()` owns diagnosis, while `repair()` owns

reporting what it changed or would change. Repair contexts can carry

`dryRun`/`diff` requests, and repair results can return structured `diffs` for

config/file edits plus `effects` for service, process, package, state, or other

side effects. That lets converted checks grow toward `doctor --fix --dry-run`

and diff reporting without moving mutation planning into `detect()`.

`repair()` reports whether it attempted the requested repair with `status:

"repaired" | "skipped" | "failed"`. Omitted status means `repaired`, so simple

repair checks only need to return changes. When repair returns `skipped` or

`failed`, doctor reports the reason and does not run validation for that check.

After a successful structured repair, doctor re-runs `detect()` with the

repaired findings as scope. Checks can use selected findings, paths, or `ocPath`

values for focused validation. If the finding is still present, doctor reports a

repair warning instead of treating the change as silently 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` | Suggested operator action or repair summary. |

This release registers the modernized core doctor checks on the structured

health path. The `openclaw/plugin-sdk/health` subpath exposes the same

contract for bundled follow-up consumers, but plugin-backed checks only run

after their owning package registers them in the active command path.

## Check Selection

Use `--only` and `--skip` when a workflow wants a focused gate:

```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. If an `--only`

id is not registered, no check runs for that id; use the command's `checksRun`

and `checksSkipped` fields to verify a focused gate is selecting the checks you

expect.

Notes:

- In Nix mode (`OPENCLAW_NIX_MODE=1`), read-only doctor checks still work, but `doctor --fix`, `doctor --repair`, `doctor --yes`, and `doctor --generate-gateway-token` are disabled because `openclaw.json` is immutable. Edit the Nix source for this install instead; for nix-openclaw, use the agent-first [Quick Start](https://github.com/openclaw/nix-openclaw#quick-start).

- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.

- Performance: non-interactive `doctor` runs skip eager plugin loading so headless health checks stay fast. Interactive sessions still fully load plugins when a check needs their contribution.

- Performance: non-interactive `doctor` runs skip eager plugin loading so headless health checks stay fast. Interactive doctor sessions still load the plugin surfaces needed by the legacy health and repair flow.

- `--lint` is stricter than `--non-interactive`: it is always read-only, never prompts, and never applies safe migrations. Run `doctor --fix` or `doctor --repair` when you want doctor to make changes.

- `--fix` (alias for `--repair`) writes a backup to `~/.openclaw/openclaw.json.bak` and drops unknown config keys, listing each removal.

- Modernized health checks can expose a `repair()` path for `doctor --fix`; checks that do not expose one continue through the existing doctor repair flow.

- `doctor --fix --non-interactive` reports missing or stale gateway service definitions but does not install or rewrite them outside update repair mode. Run `openclaw gateway install` for a missing service, or `openclaw gateway install --force` when you intentionally want to replace the launcher.

- State integrity checks now detect orphan transcript files in the sessions directory. Archiving them as `.deleted.<timestamp>` requires an interactive confirmation; `--fix`, `--yes`, and headless runs leave them in place.

- Doctor also scans `~/.openclaw/cron/jobs.json` (or `cron.store`) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.