Complete reference for openclaw doctor, running health checks, applying config repairs, and auditing six categories of system state across config, services, auth, security, and more.
What does Openclaw Doctor do?
It’s OpenClaw’s all-in-one diagnostic and repair tool. A single run audits six distinct system areas, config schema, state integrity, model auth, background services, security policies, and live Gateway health and then either prompts you to apply repairs interactively or applies them automatically depending on the flags you pass.
Think of it as the first command to run when something isn’t working and the last command to run after a major version upgrade. It produces both warnings and actionable fixes, not just a passive status report.
Interactive vs. Automated Runs
Without flags, doctor is interactive, it explains each issue and asks before making any change. This is often a better first step than a full OpenClaw Reset, as it attempts to surgically repair specific configuration errors or permission issues without wiping your entire database or chat history.
The escalation ladder for repairs goes:
--repair --force: Aggressive fixes, including supervisor overwrites.--non-interactive: Safe migrations only.--repair: Recommended repairs and service restarts.
Basic Command
| openclaw doctor Runs the interactive doctor flow. Performs health checks and prompts you for confirmation before applying any repairs, modifying services, or restarting the Gateway. Safe to run at any time, nothing is changed without explicit confirmation. |
basic usage
# Interactive — prompts before every repair action openclaw doctor
Headless & Automation Flags
For scripting, CI pipelines, or bypassing interactive prompts. Flags escalate from safe-only to aggressive, pick the right level for your context.
| Flag | Risk Level | What it does |
|---|---|---|
| –non-interactive | safe only | Runs without prompts but only applies safe migrations, config normalization and on-disk state moves. Intentionally skips anything requiring human confirmation: service restarts, sandbox repairs. |
| –yes | standard | Automatically accepts the default prompts for all repair steps, including restarts, service updates, and sandbox repairs. Equivalent to pressing enter at every prompt. |
| –repair / –fix | standard | Applies recommended repairs without prompting, including safe restarts. Writes a backup to ~/openclaw/openclaw.json.bak, drops unknown config keys, and lists the removals. |
--repair --force | aggressive | Applies aggressive repairs, includes overwriting custom supervisor configurations (launchd / systemd). Use only when you’re okay with supervisor configs being regenerated from defaults. |
--repair --force will overwrite your custom launchd or systemd supervisor configurations. Any manual edits to those files will be lost. The –repair flag without –force preserves custom supervisor configs.
Additional utility flags
| –deep Scans system services to detect extra or legacy gateway installs (launchd / systemd / schtasks). Use after a multi-version migration or if you suspect duplicate service entries. | –generate-gateway-token Forces generation of a local gateway auth token if one is needed and no token SecretRef is currently configured. Useful during fresh setups where auth hasn’t been initialized yet. |
| –no-workspace-suggestions Disables the tips recommending workspace memory systems. Pass this in automation contexts where you want clean output without informational suggestions. |
common automation patterns
# Safe migrations only — no restarts, good for CI openclaw doctor --non-interactive # Apply all recommended repairs including restarts openclaw doctor --repair # Aggressive — also rewrites supervisor configs openclaw doctor --repair --force # Repair + scan for legacy installs + generate token if needed openclaw doctor --repair --deep --generate-gateway-token
What Doctor Actually Audits
Six audit categories run in sequence. Each can produce warnings, offer fixes, or apply repairs depending on the flags used.
1. Config & State Migrations
Normalizes legacy configuration values into the current schema and migrates older on-disk file layouts, like sessions or legacy WhatsApp auth, to the correct agent directories. This runs even with –non-interactive.
schema normalization | file layout migration | legacy auth paths
2. State Integrity & Permissions
Verifies that your state directory exists and warns if it’s placed in a cloud-synced folder (like iCloud). Checks file permissions, for example, offering to tighten openclaw.json to 600. Can also clean up orphan transcript files to reclaim disk space.
iCloud / cloud-sync detection | file permission tightening | orphan transcript cleanup
3. Model Auth Health
Inspects OAuth profiles, warns about expiring or disabled tokens (such as Anthropic / Claude Code), and can interactively prompt to refresh them before they cause failures in agent runs.
expiring token detection | disabled token detection | interactive token refresh
4. Service & Runtime Checks
Audits background supervisor configs (launchd / systemd / schtasks) for outdated defaults and offers to rewrite them. Warns if the Gateway is running on an unsupported runtime, like Bun or a version manager path that might break, and checks for port collisions.
outdated supervisor config | unsupported runtime path | port collision detection | supervisor config rewrite
5. Security & Sandboxing
Audits DM policies to warn if a provider is fully open without an allowlist. If sandboxing is enabled, checks Docker image health and offers to build or repair missing images. Will suggest disabling sandbox mode if Docker is unavailable.
open DM policy (no allowlist) | Docker image build / repair | Docker unavailable detection
6. Health Check
Runs a live Gateway health check and channel status probe. If the Gateway appears unhealthy, offers to restart it. This is the same probe used by openclaw channels status –probe but integrated into the full diagnostic flow.
Gateway health probe | channel status probe | Gateway restart offer
Run openclaw doctor –repair after any major CLI upgrade to catch config schema changes and file layout migrations that might silently affect behavior. The backup written to ~/openclaw/openclaw.json.bak gives you a rollback point if anything unexpected is removed.
