Doctor 诊断
openclaw doctor 是内置的诊断工具，自动检查 Gateway 的配置、连接、安全和运行状态，并给出修复建议。
基本用法
bash
openclaw doctor输出示例：
text
🔍 OpenClaw Doctor — System Health Check
✓ Gateway process running (PID: 42187)
✓ Port 18789 available and listening
✓ Configuration file valid
✓ Authentication configured
⚠ Sandbox mode is "off" — consider enabling
✓ Channel "openai" connected
✗ Channel "anthropic" connection failed: invalid API key
✓ Disk space sufficient (45 GB free)
✓ No stale lock files
Summary: 7 passed, 1 warning, 1 error检查项目
系统检查
| 检查项 | 说明 |
|---|---|
| Gateway 进程 | 进程是否在运行 |
| 端口占用 | 端口是否可用或已被占用 |
| 磁盘空间 | 数据目录剩余空间 |
| 锁文件 | 是否存在过期的锁文件 |
| 系统资源 | CPU 和内存使用率 |
配置检查
| 检查项 | 说明 |
|---|---|
| 配置语法 | JSON5 语法是否正确 |
| 必填项 | 必要配置是否齐全 |
| 引用解析 | ${SECRET} 引用是否可解析 |
| 值范围 | 配置值是否在有效范围内 |
连接检查
| 检查项 | 说明 |
|---|---|
| Channel 连接 | 各 Channel 是否可达 |
| API Key 有效性 | API Key 是否有效 |
| 网络连通性 | 外部 API 端点是否可达 |
| DNS 解析 | 域名解析是否正常 |
安全检查
| 检查项 | 说明 |
|---|---|
| 认证配置 | Token 或密码是否已设置 |
| 沙箱状态 | 沙箱是否启用 |
| Token 强度 | Token 是否足够安全 |
| 暴露风险 | Gateway 是否意外暴露到公网 |
指定检查范围
bash
# 仅检查 Channel 连接
openclaw doctor --check channels
# 仅检查安全配置
openclaw doctor --check security
# 仅检查 Gateway 连接
openclaw doctor --check gateway-connection
# 仅检查沙箱
openclaw doctor --check sandbox
# 运行所有检查（详细模式）
openclaw doctor --verbose常见发现与修复
✗ Gateway not running
text
✗ Gateway process not running
Fix: Start the gateway with:
openclaw gateway⚠ Sandbox disabled
text
⚠ Sandbox mode is "off"
Recommendation: Enable sandbox for security:
openclaw config set security.sandbox.mode standard✗ Channel connection failed
text
✗ Channel "openai" connection failed: 401 Unauthorized
Fix: Check your API key:
openclaw secrets set OPENAI_API_KEY "your-valid-key"⚠ Token too short
text
⚠ Gateway token is only 12 characters (recommend 32+)
Fix: Generate a strong token:
export OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"✗ Port already in use
text
✗ Port 18789 is in use by another process (PID: 12345)
Fix: Stop the other process or use a different port:
openclaw gateway --port 18790⚠ Stale lock file
text
⚠ Stale lock file detected: ~/.openclaw/gateway.lock
Lock owner PID 98765 is not running
Fix: Remove the stale lock:
openclaw gateway unlock自动修复
部分问题 Doctor 可以自动修复：
bash
# 运行诊断并自动修复可修复的问题
openclaw doctor --fix可自动修复的问题：
| 问题 | 自动修复操作 |
|---|---|
| 过期锁文件 | 删除锁文件 |
| 缺少数据目录 | 创建目录 |
| 日志文件过大 | 触发日志轮转 |
| 过期缓存 | 清理缓存文件 |
自动修复限制
Doctor 不会自动修改安全相关配置（如 Token、密码、沙箱模式），这些需要手动处理。
输出格式
bash
# JSON 输出（适合脚本集成）
openclaw doctor --format json
# 简洁输出（仅显示问题）
openclaw doctor --quietjson
{
"status": "warning",
"checks": [
{"name": "gateway_running", "status": "pass"},
{"name": "sandbox_mode", "status": "warning", "message": "Sandbox disabled"},
{"name": "channel_openai", "status": "fail", "message": "401 Unauthorized"}
],
"summary": {"pass": 7, "warning": 1, "fail": 1}
}定期诊断
建议将 Doctor 加入定期检查：
bash
# cron 定期执行
0 */6 * * * openclaw doctor --quiet --format json >> /var/log/openclaw-doctor.json