- openclaw doctor runs 12 checks covering gateway connectivity, provider auth, agent configs, plugins, logs, and network health — results appear in under 3 seconds
- Each result is PASS, WARN, or FAIL — FAIL blocks operation, WARN indicates degraded reliability, PASS means healthy
- Run openclaw doctor --fix to auto-resolve safe issues like stale lock files, stuck agents, and oversized logs
- Use --json flag to pipe doctor output into monitoring systems, alerting pipelines, or log aggregators
- Add doctor to daily cron monitoring for production systems — a single FAIL result should trigger an alert
Your agent stopped responding. You changed nothing. This is the situation openclaw doctor was built for. One command. Twelve checks. Every broken thing surfaced with a precise fix in under three seconds. Here's how to get the most from it.
What Doctor Checks and Why Each Check Matters
The doctor command runs a fixed sequence of diagnostic checks every time. Understanding what each check covers helps you interpret results without hunting through documentation.
The 12 checks run in this order:
- CLI version — confirms your installed version matches the latest stable release
- Gateway connectivity — pings your configured gateway URL and checks response time
- Gateway auth — verifies your gateway token authenticates successfully
- Provider API keys — tests each configured provider key with a minimal validation call
- Agent config integrity — parses all agent YAML files and checks for schema errors
- Channel registration — confirms all configured channels are registered and reachable
- Plugin load state — verifies each declared plugin is installed and loadable
- Shared memory access — checks read/write access to the memory backend
- Log write permissions — confirms the log directory is writable
- Network reachability — tests outbound connectivity to required external endpoints
- TLS certificates — checks certificate validity and expiry for all HTTPS endpoints
- Disk space — warns when available disk space drops below safe thresholds
Each check takes milliseconds. The total runtime is consistently under three seconds even on slow systems. That speed matters when you're debugging a live production issue at 2am.
The OpenClaw community and support team will almost always ask for doctor output first. Run openclaw doctor --json > doctor-output.json and attach the file to any support request. It contains everything needed to diagnose your issue without back-and-forth questioning.
Reading Doctor Output Correctly
The output format is designed for fast scanning. Each line shows check name, status, and an action when status is WARN or FAIL.
$ openclaw doctor
OpenClaw Doctor v2.1.4
━━━━━━━━━━━━━━━━━━━━━━
✓ CLI version 2.1.4 (latest)
✓ Gateway connectivity 12ms — gateway.example.com:8080
✓ Gateway auth token valid
✗ Provider API keys anthropic: INVALID KEY — run: openclaw config set anthropic.key <key>
✓ Agent config 3 agents parsed, no errors
✓ Channel registration telegram:research-bot, api:main
✗ Plugin load web-search: NOT INSTALLED — run: openclaw plugins install web-search
✓ Shared memory redis backend reachable
✓ Log permissions /var/log/openclaw writable
✓ Network reachability api.anthropic.com, api.openai.com reachable
! TLS certificates gateway.example.com expires in 14 days
✓ Disk space 42GB free (threshold: 2GB)
━━━━━━━━━━━━━━━━━━━━━━
2 failures · 1 warning · 9 passed
Run: openclaw doctor --fix to auto-resolve safe issuesThe symbols tell you everything at a glance: ✓ is PASS, ✗ is FAIL, and ! is WARN. Every FAIL and WARN includes the exact command to run or the specific config change to make. No ambiguity.
Here's where most people stop. They fix the FAIL items and close the terminal. The WARN items — like the certificate expiring in 14 days — get ignored until they become emergencies. Fix WARNs the same day you see them.
Flags and Options
Doctor has a focused set of flags for different use cases:
| Flag | What It Does |
|---|---|
| --fix | Auto-apply safe fixes (lock files, stuck agents, log rotation) |
| --json | Output results as JSON for monitoring system integration |
| --check <name> | Run a single named check instead of all 12 |
| --agent <name> | Scope checks to a specific agent only |
| --verbose | Show full diagnostic data for each check, not just pass/fail |
| --exit-on-fail | Exit with code 1 if any FAIL result — useful in CI pipelines |
Auto-Fix Mode: What It Can and Cannot Do
The --fix flag instructs doctor to automatically resolve issues it can safely fix without human intervention. Understanding the boundary between auto-fixable and manual-only issues saves time.
# Run doctor with auto-fix
openclaw doctor --fix
# Run a single targeted check with auto-fix
openclaw doctor --check plugin-load --fix
# Use in CI: fail the pipeline if doctor finds issues
openclaw doctor --exit-on-fail --json | tee doctor-results.jsonAuto-fixable issues include: clearing stale lock files that prevent agent startup, restarting agents that crashed into a hung state, rotating oversized log files that are approaching disk limits, and regenerating corrupted config checksums.
Issues that always require manual action are labeled MANUAL in output: invalid API keys (doctor can't know the correct key), expired TLS certificates (doctor can't renew them), missing channel tokens, and permission errors on system directories. Doctor tells you exactly what to do — it just can't do it for you.
When doctor's auto-fix detects a hung agent, it sends SIGTERM followed by a restart. In production environments, this means brief interruptions to agent availability. Run openclaw doctor --fix --dry-run first to preview what fixes would be applied before committing to them on live systems.
Common Mistakes When Using Doctor
Ignoring WARN results. WARNs are pre-failures. A certificate expiring in 14 days becomes a hard outage in 14 days. An agent running on an outdated version becomes incompatible when you update the gateway. Every WARN has a timer attached to it — treat them as time-sensitive fixes.
Running doctor without --verbose when investigating. The default output is designed for fast scanning, not debugging. When you're trying to understand why a check fails, the short output may not give enough context. Always add --verbose when you're investigating a specific failure — it shows the full response data, not just pass/fail.
Not scoping to a specific agent when debugging one agent. Running doctor system-wide when you suspect one agent is the problem shows you 12 checks across every agent. Use --agent your-agent-name to focus all checks on the specific agent you're investigating.
Not piping JSON output into monitoring. Running doctor manually is useful for ad-hoc debugging. But for production systems, manual runs mean you only see problems when you remember to look. Pipe openclaw doctor --json into your monitoring stack and alert on any FAIL result.
Frequently Asked Questions
What does openclaw doctor check?
Doctor runs 12 automated checks: CLI version, gateway connectivity, provider API key validity, agent config integrity, channel registration status, skill load state, memory access, log write permissions, network reachability, TLS certificate validity, dependency versions, and disk space. Each check reports PASS, WARN, or FAIL with a specific fix action.
How do I fix a WARN result in openclaw doctor?
WARN results indicate non-critical issues that won't break operation immediately but may cause problems later. Each WARN includes a recommended fix. Run the suggested command or make the config change shown, then re-run openclaw doctor to confirm the warning clears. WARN items don't prevent agent operation but should be resolved within 24 hours.
Can openclaw doctor fix issues automatically?
Yes, for certain categories. Run openclaw doctor --fix to automatically apply safe fixes: clearing stale lock files, restarting stuck agents, regenerating corrupted config checksums, and pruning oversized log files. Fixes requiring credentials or manual config edits always require human action — doctor flags these with a MANUAL label.
Why does openclaw doctor show gateway unreachable when the gateway is running?
This usually means the gateway is listening on a different port or address than your CLI config expects. Check openclaw config get gateway.url and compare it to the actual address in your gateway.yaml. A mismatch between these two values is the most common cause of false gateway-unreachable errors from doctor.
How often should I run openclaw doctor?
Run doctor after every major change: new agent deployment, provider key rotation, plugin installation, or OpenClaw version update. For production systems, add doctor to a daily monitoring cron job and alert on any FAIL results. The JSON output flag makes this straightforward to pipe into monitoring systems.
Does openclaw doctor check plugin and skill health?
Yes. Doctor checks that every plugin listed in agent configs is installed and loadable. It catches cases where a plugin install was queued but failed silently — a common issue after openclaw onboard. If a plugin shows FAIL in doctor output, run openclaw plugins install plugin-name to force a fresh install.
A. Larsen builds and maintains OpenClaw integrations for enterprise clients, running doctor as the first step in every debugging session. Has diagnosed and resolved more than 400 unique OpenClaw configuration failures across production deployments in financial services, logistics, and SaaS platforms.