Here's a pattern we see constantly in support: someone spends two hours debugging a mysterious gateway failure. They restart, check logs, Google the error, post on Reddit. Eventually they find the culprit — a missing comma in openclaw.json or a port conflict or a bad env var.

What they didn't know: openclaw doctor would have found it in 10 seconds.

openclaw doctor

That's it. Run that before you do anything else when something's broken. Here's everything it actually checks.

What openclaw doctor Checks

Check What It Catches Severity
JSON validity Syntax errors in openclaw.json — missing commas, unclosed braces, trailing commas Error
Schema validation Unknown keys, wrong types, deprecated field names that no longer work Error
Gateway port Whether port 3721 (or your configured port) is already in use Error
Auth config Missing or malformed API keys, expired auth tokens Error
Model reachability Whether configured providers (Anthropic, Ollama, etc.) are actually reachable Warning
Workspace path Whether the configured workspace directory exists and is writable Warning
Skills/plugins Installed skills with missing dependencies or incompatible versions Warning
Node.js version Whether your Node version meets the minimum requirement (v20+ required, v22 recommended) Info
Channel config Telegram/Discord/Signal config issues — missing tokens, incorrect IDs Warning
exec-approvals.json Missing or malformed approvals file (added in 2026.4.1) Warning

Reading the Output

A healthy setup looks like this:

✓ Config JSON valid
✓ Schema: all fields recognized
✓ Gateway port 3721 available
✓ Auth: anthropic API key present
✓ Provider reachable: anthropic (200ms)
✓ Workspace: /home/user/.openclaw/workspace (writable)
✓ Node.js v22.0.0 (recommended)
✓ exec-approvals.json present

ℹ 3 skills installed, all dependencies met

All checks passed. Gateway should start cleanly.

A setup with problems:

✓ Config JSON valid
✗ Schema: unknown key "tools.exec.elevated" — did you mean "tools.elevated"?
✗ Gateway port 3721 already in use (PID 18432)
✓ Auth: anthropic API key present
⚠ Provider: ollama not reachable at http://127.0.0.1:11434 — is Ollama running?
✓ Workspace: /home/user/.openclaw/workspace (writable)
⚠ exec-approvals.json not found — exec commands will be blocked

2 errors, 2 warnings. Gateway will not start until errors are resolved.

The output tells you exactly what's wrong and often suggests the fix inline. Errors block gateway startup. Warnings don't — but they usually mean something won't work as expected.

Most Common Issues Doctor Catches

1. Port already in use

The previous gateway process didn't shut down cleanly. Doctor tells you the PID. Kill it:

kill $(lsof -ti:3721)
openclaw gateway start

2. Unknown config keys after an update

OpenClaw's config schema changes between releases. Keys that worked in 3.x sometimes get moved or renamed in 4.x. Doctor catches these immediately instead of letting you discover them when something silently fails at runtime.

3. Ollama not running

If you've configured Ollama as a provider, doctor checks whether it's actually reachable. Common cause: you rebooted and Ollama isn't set to start automatically.

# Start Ollama
ollama serve &

# Or add it to startup (systemd)
sudo systemctl enable ollama

4. exec-approvals.json missing

Introduced in 2026.4.1. Doctor flags this as a warning — the gateway will start, but all exec commands will be blocked until you create the file. See our exec-approvals guide for the fix.

Run Doctor Automatically Before Updates

One pattern we use in every ClawReady setup: run doctor before and after updates to quickly spot what changed.

# Before update — save baseline
openclaw doctor > /tmp/doctor-before.txt

# Update
npm install -g openclaw@latest

# After update — compare
openclaw doctor > /tmp/doctor-after.txt
diff /tmp/doctor-before.txt /tmp/doctor-after.txt

Any new errors or warnings in the diff point directly to what the update changed. This turns a mystery into a 30-second investigation.

TL;DR: Before posting in r/openclaw, before restarting for the tenth time, before Googling the error — run openclaw doctor. It catches the most common issues instantly and often tells you exactly how to fix them.