Doctor 工具概述
openclaw doctor 是 OpenClaw 内置的诊断工具，能够自动检测环境配置、网络连接、供应商状态等常见问题，并提供修复建议。它是排查问题的第一步工具。
基本使用
openclaw doctor
完整诊断输出示例：
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
指定检查范围
只检查供应商
openclaw doctor --check providers
只检查特定供应商
openclaw doctor --provider openai
openclaw doctor --provider openai --model gpt-4o
只检查频道
openclaw doctor --check channels
只检查配置
openclaw doctor --check config
只检查环境
openclaw doctor --check env
详细诊断模式
获取更详细的诊断信息：
openclaw doctor --verbose
这会输出每个检查项的详细信息，包括 HTTP 请求和响应内容，有助于深入排查。
自动修复
Doctor 可以自动修复部分问题：
openclaw doctor --fix
可以自动修复的问题：
- 缺失的配置字段（使用默认值填充）
- 权限不正确的文件
- 未设置的 Webhook URL
- 过期的缓存数据
不能自动修复的问题：
- 缺失的 API Key
- 网络连接问题
- 需要手动授权的频道（如 WhatsApp QR 码）
网络诊断
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)
端口检查
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
性能诊断
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
导出诊断报告
生成完整的诊断报告文件：
openclaw doctor --export report.json
输出 JSON 格式的报告，包含所有检查项的详细信息，适合提交给社区寻求帮助。
# 生成可分享的报告（自动移除敏感信息）
openclaw doctor --export report.json --safe
持续监控模式
openclaw doctor --watch
每 30 秒运行一次诊断，实时显示状态变化。适合部署后观察一段时间。
常见诊断结果与解决方案
Node.js 版本过低
✗ Node.js v16.20.0 (required: >=18)
解决：
nvm install 20
nvm use 20
API Key 无效
✗ openai: authentication failed (401)
解决：
openclaw secrets set OPENAI_API_KEY "sk-new-valid-key"
Webhook 不可达
✗ telegram webhook: not reachable from internet
解决：检查域名 DNS、防火墙、反向代理配置。
内存使用过高
⚠ Memory: 480MB used / 512MB limit (94%)
解决：增加内存限制或减少 historyLimit。
与其他工具配合
# 先诊断，再查看日志
openclaw doctor && openclaw logs --level error --since "1h"
# 修复后重启
openclaw doctor --fix && openclaw restart
总结
openclaw doctor 是日常运维的必备工具。建议在以下场景使用：初始部署后、修改配置后、遇到异常时、定期巡检时。它能快速定位 90% 的常见问题，大大减少排查时间。