OpenClaw Doctor Guide: Diagnose and Repair Gateway Configuration Safely

When an OpenClaw Gateway refuses to start, behaves differently after a configuration edit, or carries state forward from an older installation, the tempting response is to keep changing settings until something works. That approach makes recovery harder to explain and easier to repeat incorrectly.

OpenClaw Doctor gives you a more deliberate path. It can inspect configuration and health, identify migrations, provide repair steps, and support read-only checks for automation. The important distinction is that Doctor has both diagnostic and mutating modes. Start with the mode that only reports what it finds, then decide whether a repair is appropriate for this machine and this release.

Quick answer: Run openclaw doctor --lint first when you need a read-only preflight. Use openclaw doctor for an interactive report and openclaw doctor --fix when you have reviewed the proposed repair path. Treat --yes, --non-interactive, and especially --force as operating-mode choices, not harmless convenience flags.

What OpenClaw Doctor does

The official Doctor command is the repair and migration tool for OpenClaw. It checks stale configuration or state, reports health-related findings, and offers actionable repair steps. That makes it useful after an upgrade, after moving a Gateway between hosts, or after a configuration change leaves the service unable to boot.

Doctor is not a replacement for every operational check. It does not prove that a messaging provider is delivering messages, that a remote tunnel is reachable from a particular client, or that a tool policy matches your threat model. After a repair, check the live Gateway and the affected channel separately. LobsterDome’s Gateway health checks guide covers that second layer.

Doctor also should not be treated as a generic “make it safe” button. Some findings are informational or diagnostic only. Some repairs affect local files, service configuration, or sandbox setup. Read the proposed action and keep a private backup of important configuration before allowing writes.

Start with read-only lint

For a CI job, deployment preflight, or cautious first pass, use:

openclaw doctor --lint

Lint mode is designed to be automation-friendly. It does not prompt, repair, restart, migrate, or write configuration/state. The default profile focuses on broad, local, static checks that are useful in review gates. It does not automatically include every environment-sensitive or live-service check.

To request machine-readable findings, add --json:

openclaw doctor --lint --json

The structured result includes whether a finding met the selected severity threshold, counts for selected and skipped checks, and diagnostic records. The documented exit codes are useful in scripts:

• 0: no findings at or above the selected threshold.
• 1: one or more findings met the selected threshold.
• 2: the command failed before it could emit findings.

A status of 1 is not the same as a crashed Doctor command. It means the check found something that deserves review. A status of 2 points to a command or runtime failure and should be investigated as such.

When you need the full registered lint audit rather than the broad-safe default, use:

openclaw doctor --lint --all

For a targeted check, the official documentation also supports selecting a check with --only <id>. Use the exact check identifier reported by your installed version instead of guessing a name from an older release. You can combine severity filtering and JSON output when a pipeline needs a narrower gate:

openclaw doctor --lint --severity-min warning --json

Choose the repair mode deliberately

Interactive Doctor

The plain command is the best starting point when a human is available:

openclaw doctor

It presents a friendly report and can ask before applying actions that need confirmation. Use it when you want to understand the state of a personal Gateway and review the repair sequence in context.

Recommended repairs with --fix

To apply recommended repairs without the normal confirmation flow, use:

openclaw doctor --fix

--fix is a mutating operation. It can write configuration or state, and its repair policy is distinct from the read-only lint profile. A finding appearing in doctor --lint --all does not guarantee that doctor --fix will change that area; some findings are intentionally diagnostic only.

Accept defaults with --yes

The --yes flag accepts defaults without prompting, including restart, service, or sandbox repair steps when they apply:

openclaw doctor --yes

This is convenient for a controlled maintenance window, but it removes the human checkpoint. Do not use it as a first response to an unfamiliar failure. Review the normal interactive output first, or test the read-only path in your automation.

Safe unattended migrations with --non-interactive

For unattended maintenance that should apply only safe migrations, use:

openclaw doctor --non-interactive

This mode applies safe configuration normalization and on-disk state moves without prompting. It skips restart, service, and sandbox actions that require human confirmation. Legacy state migrations still run when detected. That narrower contract is often a better fit for scheduled maintenance than an unattended broad repair.

Reserve --force for an understood exception

The combination below applies aggressive repairs too:

openclaw doctor --fix --force

The official documentation warns that aggressive repairs can overwrite custom supervisor configurations. If your Gateway is managed by systemd, launchd, a task scheduler, or another wrapper, inspect that integration before using --force. Save the relevant service definition and record why the override is necessary.

A staged recovery runbook

Use this sequence after a failed edit, upgrade, or migration:

1. Identify the active installation. Confirm the OS user, profile, service account, and configuration path. A shell session and a background service may not use the same environment.
2. Protect the current state. Make a private, access-controlled copy of ~/.openclaw/openclaw.json and relevant service configuration. Do not put credentials in a repository or support ticket.
3. Run lint first. Start with openclaw doctor --lint --json and save the output somewhere private. If the command exits 2, fix that runtime problem before interpreting findings.
4. Inspect the schema. Use openclaw config schema and the current configuration reference to verify field names, types, and supported scopes. OpenClaw rejects unknown keys and malformed values.
5. Use interactive Doctor. Run openclaw doctor and review each proposed migration or repair. Do not assume every warning has an automatic fix.
6. Apply the narrow repair. Prefer --fix over --fix --force. Choose --non-interactive only when the safe-migration contract fits the maintenance task.
7. Restart only as required. If the repair reports a service or restart action, follow the displayed procedure and check the supervisor rather than launching a second Gateway accidentally.
8. Re-run diagnostics. Run lint again and compare the findings. A clean lint result is evidence about the checks it ran, not proof that every channel or remote client works.
9. Check live behavior. Run openclaw health, inspect status and logs, and test the affected channel or control path.
10. Audit exposure changes. After changes to binding, authentication, groups, tools, browser control, plugins, or remote access, run openclaw security audit. The security guide explains the trusted-operator model and audit scope.

The configuration documentation describes a last-known-good copy retained after successful startup, but startup and hot reload do not restore it automatically. Do not expect a failed reload to undo a bad edit by itself. Use Doctor’s supported repair path and your private backup intentionally.

Common mistakes

Confusing lint with fix

doctor --lint is read-only. doctor --fix can write. Keep those commands separate in scripts and name the mode in maintenance logs so another operator can tell whether a run only inspected the machine or changed it.

Treating every warning as a failure

Lint findings have severity and selection rules. A warning may be valid for a trusted personal setup but worth tightening for a broader exposure. Review the finding, the effective configuration, and the trust boundary before changing policy.

Running --force before checking the supervisor

If a custom service wrapper is part of how the Gateway starts, an aggressive repair can replace assumptions your deployment relies on. Capture the service definition first and prefer a narrow repair.

Restoring an old config blindly

A backup from a previous release may contain fields that no longer match the current schema. Compare it with the installed schema and let Doctor identify migrations rather than overwriting the active file without review.

Assuming a clean lint proves delivery

Lint can pass while a channel credential is expired, a remote tunnel is blocked, or a session is stale. Finish with a health check and a real, low-risk end-to-end test.

FAQ

Is OpenClaw Doctor safe to run?

The plain command and --lint are intended for inspection, but repair modes can write configuration or state. Read the mode’s contract before using --fix, --yes, or --non-interactive.

Should I use doctor --lint in CI?

Yes, it is specifically documented for CI and preflight automation. Use JSON output, choose a severity threshold that matches your policy, and handle exit code 2 separately from findings.

Does doctor --fix repair every lint finding?

No. Doctor separates detection from repair. Some checks are diagnostic only, and the lint profile is not the same ordered repair path used by --fix.

When should I use --deep?

Use --deep when you need Doctor to scan for extra Gateway installations in system services such as launchd, systemd, or scheduled tasks. It is useful during migrations, but inspect the results before changing an installation you did not intend to manage.

What should I do after Doctor repairs the Gateway?

Re-run lint, verify Gateway health and logs, test the affected channel, and run a security audit if the change touched access, tools, plugins, binding, or remote exposure.

Sources

• OpenClaw Doctor
• OpenClaw configuration
• OpenClaw security
• OpenClaw Gateway Health Checks on LobsterDome
• OpenClaw Configuration Guide on LobsterDome