Doctor Diagnostic Tool: Complete Guide

Doctor Tool Overview

openclaw doctor is OpenClaw's built-in diagnostic tool that automatically detects environment configuration, network connectivity, provider status, and other common issues, providing fix recommendations. It should be the first tool you reach for when troubleshooting.

Basic Usage

openclaw doctor

Full diagnostic output example:

OpenClaw Doctor v1.2.3
======================

Environment:
  ✓ Node.js v20.11.0 (required: >=18)
  ✓ npm v10.2.4
  ✓ OS: Linux x64
  ✓ Memory: 3.8GB available

Configuration:
  ✓ Config file: ~/.openclaw/config.json
  ✓ Config syntax: valid
  ✓ Required fields: present
  ✗ Warning: No systemPrompt set for channel "discord-main"

Secrets:
  ✓ OPENAI_API_KEY: set
  ✓ TELEGRAM_BOT_TOKEN: set
  ✗ ANTHROPIC_API_KEY: not set (referenced in config)

Providers:
  ✓ openai: connected (180ms)
  ✓ ollama: connected (15ms)
  ✗ anthropic: failed (API key missing)

Channels:
  ✓ telegram-main: webhook configured
  ✓ discord-main: connected
  ✗ whatsapp: disconnected (QR code scan required)

Gateway:
  ✓ Port 3000: available
  ✓ Base URL: https://gateway.example.com (reachable)

Issues found: 3
Run 'openclaw doctor --fix' for automatic fixes

Scoped Checks

Check Providers Only

openclaw doctor --check providers

Check a Specific Provider

openclaw doctor --provider openai
openclaw doctor --provider openai --model gpt-4o

Check Channels Only

openclaw doctor --check channels

Check Configuration Only

openclaw doctor --check config

Check Environment Only

openclaw doctor --check env

Verbose Mode

Get more detailed diagnostic information:

openclaw doctor --verbose

This outputs detailed information for every check item, including HTTP requests and responses, which helps with deep troubleshooting.

Auto-Fix

Doctor can automatically fix some issues:

openclaw doctor --fix

Issues that can be auto-fixed:

Missing configuration fields (filled with default values)
Incorrect file permissions
Unset webhook URLs
Expired cache data

Issues that cannot be auto-fixed:

Missing API keys
Network connectivity problems
Channels requiring manual authorization (e.g., WhatsApp QR codes)

Network Diagnostics

openclaw doctor --check network

Network Diagnostics:
  ✓ DNS resolution: working
  ✓ api.openai.com: reachable (45ms)
  ✓ api.anthropic.com: reachable (52ms)
  ✓ api.telegram.org: reachable (30ms)
  ✗ discord.com: blocked (Connection refused)
    → Suggestion: Check firewall rules or proxy settings
  ✓ Proxy: not configured
  ✓ IPv4: working
  ✓ IPv6: not available (ok)

Port Diagnostics

openclaw doctor --check ports

Port Diagnostics:
  ✓ Port 3000: available
  ✗ Port 443: in use by nginx (pid: 1234)
    → This is expected if using Nginx as reverse proxy

Performance Diagnostics

openclaw doctor --check performance

Performance Diagnostics:
  ✓ CPU: 2 cores, 15% usage
  ✓ Memory: 256MB used / 4GB total
  ✓ Disk: 2GB used / 50GB total
  ✓ Event loop delay: 2ms (healthy)
  ⚠ Model response time: 3500ms (slow)
    → Consider using a faster model or check network

Export Diagnostic Reports

Generate a complete diagnostic report file:

openclaw doctor --export report.json

# Generate a shareable report (sensitive information automatically removed)
openclaw doctor --export report.json --safe

Continuous Monitoring Mode

openclaw doctor --watch

Runs diagnostics every 30 seconds, displaying status changes in real time. Useful for observing the system for a period after deployment.

Common Diagnostic Results and Solutions

Node.js Version Too Old

✗ Node.js v16.20.0 (required: >=18)

Solution:

nvm install 20
nvm use 20

Invalid API Key

✗ openai: authentication failed (401)