What Does openclaw doctor --fix Do? Every Warning Explained

Key takeaways

• openclaw doctor --fix removes invalid config keys, applies legacy key renames, and normalizes state files. It will not overwrite your custom settings. Safe to run on any setup.
• --fix is an alias for --repair. Both do the same thing.
• --force goes further and overwrites custom service configs. Don't use it unless you know your service config is broken.
• "Config invalid" doesn't mean the gateway is broken. It means the config file has unknown keys that doctor will strip when you run --fix.
• openclaw doctor (without --fix) runs more than a dozen health checks on your config, state directory, service config, auth tokens, and channels in one pass. Run it first to see what needs fixing.
• The LAN binding security warning is expected on a VPS. It's a problem on a home machine with a weak or missing auth token.

openclaw doctor --fix: when to use it vs manual repair

--fix is the right choice for most warnings. It removes unknown config keys, applies legacy key renames, and canonicalizes state files. Running it won't overwrite your custom settings. The --fix flag is documented as an alias for --repair, so both do the same thing.

The cases where you want manual review first:

• You have a custom systemd unit or launchd plist. The --force flag will overwrite it. Review what doctor wants to change before running --force.
• You're on a production server and want to see the migration plan before committing. Run openclaw doctor first (without flags), read the output, then decide.
• The warning involves auth tokens or credentials. Doctor can generate a new gateway token, but you should know that's what it's doing.

Here's the flag breakdown:

openclaw doctor

openclaw doctor --fix

openclaw doctor --fix --force

cat ~/.openclaw/openclaw.json

"Config invalid" warning: what unknown config keys mean

"Config invalid; doctor will run with best-effort config" is one of the more alarming-sounding warnings, but the gateway still starts and runs with an invalid config. What it actually means is that the config file contains keys that don't exist in the current schema. Doctor can't validate the full config, so it proceeds in best-effort mode.

Here's the real output from a production server running an older config:

◇  Config ───────────────────────────────────────────────────╮
│                                                            │
│  Config invalid; doctor will run with best-effort config.  │
│                                                            │
├────────────────────────────────────────────────────────────╯
│
◇  Unknown config keys ────────────────────╮
│                                          │
│  - commands.ownerDisplay                 │
│  - channels.telegram.streaming           │
│  - gateway.controlUi.allowedOrigins      │
│                                          │
├──────────────────────────────────────────╯
│
◇  Doctor ────────────────────────────────────────────╮
│                                                     │
│  Run "openclaw doctor --fix" to remove these keys.  │
│                                                     │
├─────────────────────────────────────────────────────╯

Those three keys are removed features from earlier OpenClaw (previously known as Clawdbot and Moltbot) releases:

• commands.ownerDisplay was an old display name config option
• channels.telegram.streaming was a toggle for streaming responses in Telegram (now handled differently)
• gateway.controlUi.allowedOrigins was an origin whitelist for the control UI

None of them affect the running gateway. The gateway ignores keys it doesn't recognize. But they do put the config in an invalid state, which means schema validation fails. Other commands may warn about the invalid config too.

Fix: run openclaw doctor --fix. It removes the unknown keys and rewrites ~/.openclaw/openclaw.json.

What breaks if you ignore it: nothing immediately. But over time, config validation errors can mask real problems. If you add a new config key and typo it, you won't get the expected "unknown key" warning because the config is already invalid.

Legacy config migrations: what doctor rewrites automatically

Doctor handles a list of config key renames that have accumulated across OpenClaw versions. You don't need to edit these manually. Doctor explains the migration, applies it, and rewrites the config file.

Current migrations:

The gateway also auto-migrates most of these on startup when it detects a legacy config format. So in many cases, you won't see this warning at all because the gateway already handled it.

The one exception: WhatsApp auth state migration. That only runs via openclaw doctor, not on gateway startup. If you're seeing WhatsApp auth issues after an upgrade, run doctor explicitly.

State integrity checks: permissions, missing dirs, cloud sync warnings

The state directory (~/.openclaw/) holds your sessions, credentials, agent state, and config. If permissions are wrong or the directory is missing, the gateway can't write session data and channels go silent without a clear error.

A missing state directory is the most serious warning. Doctor can recreate the empty directory and will be explicit that it can't recover data that's already gone. If you've got backups, this is when you restore from them. A rm -rf on the wrong path or a botched home directory restore are the usual causes.

Permission failures are quieter but just as damaging. The gateway will start but fail silently on any write, including session updates. Doctor verifies the directory is writable by the process running the gateway and, on a mismatch, shows you the exact chown command to run.

On macOS, watch for the iCloud Drive warning. If ~/.openclaw/ resolves under ~/Library/Mobile Documents/... or ~/Library/CloudStorage/..., you're on a sync-backed path. Two things happen: every session write goes through iCloud's I/O layer (slower), and you can get lock races where iCloud and the gateway fight over the same file. Move the state directory off iCloud if you see this warning.

On Linux, a similar warning appears for SD card or eMMC storage (mmcblk* mount sources). SD-backed random I/O is slow and wears the card. Fine for testing, bad for a long-running server.

For permission errors, doctor offers to repair automatically. For cloud sync and SD/eMMC, you move the directory yourself. Doctor doesn't relocate it.

Legacy state migration: sessions.json canonicalization

◇  Legacy state detected ──────────────────────────────────────╮
│                                                              │
│  - Sessions: canonicalize legacy keys in                     │
│    /home/user/.openclaw/agents/main/sessions/sessions.json   │
│                                                              │
├──────────────────────────────────────────────────────────────╯

Legacy state migrations are best-effort and idempotent, meaning you can run doctor multiple times and the migration won't be applied twice. This particular warning means the sessions.json file uses an older key format that the current gateway still understands but prefers to have normalized.

It's safe to apply. Run openclaw doctor --fix and it canonicalizes the keys automatically. The sessions themselves aren't deleted or modified, just the key names in the file.

If you're nervous: back up the file first, then run --fix.

cp ~/.openclaw/agents/main/sessions/sessions.json ~/.openclaw/agents/main/sessions/sessions.json.bak
openclaw doctor --fix

Security warning: gateway bound to LAN (0.0.0.0)

◇  Security ──────────────────────────────────────────────────────────╮
│                                                                     │
│  - WARNING: Gateway bound to "lan" (0.0.0.0) (network-accessible).  │
│    Ensure your auth credentials are strong and not exposed.         │
│  - Run: openclaw security audit --deep                              │
│                                                                     │
├─────────────────────────────────────────────────────────────────────╯

This warning means the gateway is listening on all network interfaces (0.0.0.0). It's expected behavior for remote server setups where you access the gateway from another machine. If you're on a VPS and this is your intended config, you can acknowledge it and move on.

It's a real problem in two situations:

1. You're on a home or office network and didn't intend to expose the gateway to other devices.
2. You haven't set a gateway auth token, or you're using a weak one. Anyone who can reach the port can talk to your agent.

Doctor doesn't fix this directly. It points you to openclaw security audit --deep, which checks your auth config, port exposure, and DM policy settings.

openclaw security audit --deep

openclaw gateway config.get gateway.token

openclaw doctor --generate-gateway-token

Gateway service config: entrypoint mismatch warning

◇  Gateway service config ────────────────────────────────────────────────╮
│                                                                         │
│  - Gateway service entrypoint does not match the current install.       │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────╯

This warning means the service file (systemd unit on Linux, launchd plist on macOS, or scheduled task on Windows) is pointing at a binary path that doesn't match the current install location. The supervisor config audit is one of the checks doctor runs against launchd, systemd, and schtasks.

This most often happens after running npm update -g openclaw or reinstalling with a version manager like nvm. The update moves the binary but doesn't update the service file.

If you ignore it, the gateway appears to run but it's loading the old binary. The service starts successfully. The new version never activates until the service file gets fixed and the gateway restarts.

Fix with --fix:

openclaw doctor --fix

Doctor rewrites the service entrypoint to match the current binary location. If your service config has custom options (environment variables, user settings, restart behavior), use --fix first, not --force. Doctor's --fix updates the entrypoint and leaves the rest. --force rewrites the whole config.

After fixing, restart the service:

openclaw gateway restart

Port conflicts and Node vs Bun runtime checks

Doctor checks port availability on the default gateway port (18789) and warns when something else is already listening there.

If you see a port conflict warning, find what's using the port:

lsof -i :18789

Common culprits: another gateway instance running in the background, a previous install that didn't clean up, or an unrelated service that happens to use the same port.

Doctor also checks whether the gateway is running under Node or Bun, and whether version-manager paths (nvm, fnm, asdf) are configured correctly in the service file. This matters because version managers set up shims that only work in interactive shells. A systemd unit or launchd plist running in a non-interactive environment won't find the right binary unless the path is set explicitly.

If doctor warns about version-manager paths, it means the service file is using a shim path that won't resolve at startup. The fix is to point the service at the absolute binary path instead of the shim.

Skills status: why "missing requirements" shows up for most skills

◇  Skills status ────────────╮
│                            │
│  Eligible: 38              │
│  Missing requirements: 34  │
│  Blocked by allowlist: 0   │

34 out of 38 skills showing "missing requirements" on a standard VPS install isn't a problem. It's a checklist. Each skill in that count needs something that isn't set up: a Python package, an external CLI tool, an API key, or a specific system dependency.

Eligible skills passed all requirement checks and are ready to use. Missing requirements means the skill exists but something it needs isn't installed on this machine. Blocked by allowlist means the skill is present and its requirements are met, but the agent's allowlist is preventing it from running.

For a minimal server install focused on Telegram or Discord, most of the 34 "missing" skills are things you don't need (browser automation, image generation, speech-to-text, etc.). They show up as missing because their dependencies aren't installed, not because something is broken.

To see which skills are missing requirements and what they need, check the ClawHub skills guide. You can also run openclaw skills list to get a per-skill breakdown.

Model auth warnings: OAuth expiry and cooldown states

Doctor checks each configured model's auth status and reports problems before they show up as silent failures in your agent.

An expired OAuth token means that model won't respond until you re-authenticate. Doctor can attempt a refresh automatically. If the refresh fails, you'll get a prompt to re-auth manually. The agent won't use that model until auth is valid again.

Cooldown is different. Some models enter a cooldown after rate limit errors or repeated API failures. It's transient and usually clears on its own. Doctor shows you which models are in cooldown and when they'll recover.

Disabled is the one that's easy to miss. A model can be disabled explicitly in config, or automatically after too many consecutive failures. Doctor flags disabled models separately from cooldown ones. A disabled model stays disabled until you change the config or manually re-enable it.

If your agent goes quiet and you're not sure why, run doctor and check the model auth section first. It covers every configured model in one shot.

How to run openclaw doctor in automation and cron

Use --non-interactive for cron jobs and CI pipelines. It applies safe migrations only: config normalization and on-disk state moves. It skips anything that requires a restart, a running gateway, or human confirmation.

openclaw doctor --non-interactive

--non-interactive and --yes are not the same. --non-interactive is the cautious one: config normalization, on-disk state moves, nothing that touches a running service or requires a restart. Predictable output, safe to run from cron. --yes is broader. It accepts all defaults including restarts and sandbox repair steps. Good for interactive scripts where you want full automation. Not what you want in a production cron job where unexpected restarts are a problem.

For a weekly cron that catches config drift without touching the running gateway:

0 3 * * 0 openclaw doctor --non-interactive >> /var/log/openclaw-doctor.log 2>&1

crontab -e

0 3 * * 0 openclaw doctor --non-interactive >> /var/log/openclaw-doctor.log 2>&1

touch /var/log/openclaw-doctor.log

Key Terms

openclaw doctor: OpenClaw's built-in health check and repair tool. Runs checks against your config, state directory, service config, model auth, and channels in a single pass.

--fix / --repair: Flags that apply recommended repairs without prompting. Both do the same thing. Documented as equivalent in the CLI reference.

--force: Applies aggressive repairs including overwriting custom service configs. Use only when you know the service config is broken.

--non-interactive: Runs doctor without prompts and applies only safe migrations. Intended for automation.

State directory: ~/.openclaw/ on Linux and macOS. Holds sessions, credentials, config, and agent state. If this directory has permission problems or is on a slow or synced filesystem, the gateway will have trouble writing session data.

Supervisor config: The service file that starts the gateway on boot. Systemd unit on Linux (/etc/systemd/system/openclaw.service or ~/.config/systemd/user/openclaw.service), launchd plist on macOS, or a scheduled task on Windows.

FAQ

What does "openclaw doctor config invalid" mean?

"Config invalid" means the ~/.openclaw/openclaw.json file contains keys that aren't in the current schema. This happens after upgrades that remove or rename config options. The gateway still runs, but it can't fully validate the config. Running openclaw doctor --fix removes the unknown keys and restores a valid config state.

Does openclaw doctor --fix delete my config?

No. openclaw doctor --fix removes unknown keys (ones that no longer exist in the schema) and renames legacy keys to their current equivalents. It doesn't touch your working settings. If you've set values for things like channels.telegram.token, agents, or models, those stay untouched.

Why does openclaw doctor show "missing requirements" for most skills?

Most skills need external tools (Python packages, specific CLIs, API keys) that aren't installed by default. A server set up for basic Telegram or Discord use won't have image generation tools, browser automation, speech processing, or specialized API clients. "Missing requirements" means those skills exist but their dependencies aren't present on this machine. It's not an error.

When should I use openclaw doctor --force?

Use --force only when doctor reports that the gateway service config is wrong and you don't have any custom settings in that service file you want to preserve. --force overwrites the entire supervisor config with a fresh generated version. If you've added environment variables, custom user settings, or restart behavior to your systemd unit or launchd plist, --force will wipe them.

Can openclaw doctor fix a broken WhatsApp connection?

Sometimes. Doctor handles WhatsApp auth migration from older directory layouts. But it doesn't re-establish a broken WhatsApp session. If your WhatsApp connection dropped, check the WhatsApp errors guide for the specific reconnection steps.

How often should I run openclaw doctor?

After every OpenClaw upgrade. Also any time your agent stops responding to a channel without an obvious reason. For automated drift detection, run it weekly with --non-interactive in a cron job and review the log output.