OpenClaw Doctor Command: Complete Guide to Every Flag and Fix [2026]

The openclaw doctor command is your first line of defense when something goes wrong. It diagnoses issues, explains what's broken, and can auto-fix most problems.

Basic Usage

# Diagnose issues (read-only)
openclaw doctor

# Diagnose and auto-fix
openclaw doctor --fix

The doctor runs a series of health checks and reports findings as OK, WARN, or FAIL.

What Doctor Checks

1. Gateway Configuration

Checks if gateway.mode is set and valid.

FAIL  gateway.mode is unset — gateway start will be blocked
FIX:  openclaw config set gateway.mode local

Auto-fix with --fix: Sets gateway.mode to local.

2. Device Token Mismatch

Checks if device tokens match the gateway's expected tokens.

FAIL  device token mismatch — stored token doesn't match gateway
FIX:  regenerating device token

Auto-fix with --fix: Regenerates matching tokens and re-pairs devices.

3. Unknown Config Keys

Checks for unrecognized keys in your openclaw.json.

WARN  unknown config key: "model" (did you mean "ai.model"?)
WARN  unknown config key: "telegramToken" (did you mean "telegram.token"?)

Auto-fix with --fix: Removes or migrates unrecognized keys to their correct names.

4. Config Validation

Checks for invalid values, missing required fields, and malformed JSON.

FAIL  config validation failed: "gateway.port" must be a number

Auto-fix with --fix: Corrects type mismatches and sets defaults for missing fields.

5. Pairing Status

Checks if Telegram and other integrations are properly paired.

WARN  pairing required — Telegram bot is configured but not paired
FIX:  openclaw pairing approve telegram CODE

Auto-fix with --fix: Initiates the pairing flow and provides the approval command.

6. Directory Permissions

Checks that OpenClaw's data directories exist and are writable.

FAIL  data directory not writable: /app/data
FIX:  fixing permissions

7. Port Availability

Checks if the configured gateway port is available.

FAIL  port 3001 is already in use by process 12345
FIX:  kill the process or change gateway.port

8. Node.js Version

Checks that your Node.js version meets the minimum requirement (22+).

FAIL  Node.js 18.x detected — OpenClaw requires Node.js 22+

Useful Flags

--fix

Auto-fix all detected issues:

openclaw doctor --fix

Safe to run multiple times. It won't change things that are already correct.

--generate-gateway-token

Generate a new gateway token (useful after a device token mismatch):

openclaw doctor --generate-gateway-token

--verbose

Show detailed diagnostic output:

openclaw doctor --verbose

--json

Output results as JSON (useful for scripting):

openclaw doctor --json

Common Scenarios

After a Fresh Install

openclaw doctor --fix

This configures gateway mode, sets up directories, and validates the initial config.

After an Upgrade

openclaw doctor --fix

Migrates deprecated config keys and fixes any breaking changes from the upgrade.

After a Container Rebuild

docker exec -it CONTAINER_ID openclaw doctor --fix

Regenerates tokens and re-pairs devices that were lost during the rebuild.

When Nothing Else Works

openclaw doctor --fix --verbose

The verbose flag shows exactly what's being checked and fixed, helping you identify issues that doctor can't auto-repair.

What Doctor Can't Fix

Some issues require manual intervention:

• Wrong API keys: Doctor can't verify your AI provider credentials
• Network issues: Firewall rules, DNS, or ISP blocking
• Reverse proxy misconfiguration: Caddy/Nginx config is outside OpenClaw's scope
• Telegram bot conflicts: Another process polling the same bot token

For these, check openclaw logs --follow for specific error messages.

Run Doctor Regularly

Add openclaw doctor to your maintenance routine — especially after updates. It catches configuration drift before it causes problems.

Pre-Configured and Doctor-Free

ClawTank manages your OpenClaw configuration automatically. No doctor runs needed — the platform handles gateway tokens, config validation, and pairing for you.