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.