故障排查

OpenClaw 症状优先的故障排查入口，2 分钟快速定位问题。

前 60 秒诊断命令

按顺序执行：

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

常见问题快速修复

本地 OpenAI 兼容后端直接可用但在 OpenClaw 中失败

1. 错误含 messages[].content 期望字符串 → 设置 models.providers.<provider>.models[].compat.requiresStringContent: true
2. 仅 Agent 轮次失败 → 设置 models.providers.<provider>.models[].compat.supportsTools: false

插件安装失败（缺少 openclaw extensions）

在插件 package.json 中添加：

{
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

插件被可疑所有权阻止

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

决策树

症状	排查方向
无回复	检查 Gateway 状态、渠道连接、配对/允许列表
Dashboard/Control UI 无法连接	检查 Gateway 状态、认证配置、端口
Gateway 无法启动	检查配置模式、端口占用、认证设置
渠道连接但消息不流通	检查 mention 门控、配对状态、权限
Cron/Heartbeat 未触发	检查 cron 状态、活跃时间窗口、HEARTBEAT.md
节点已配对但工具失败	检查节点连接、权限、exec 审批
Exec 突然要求审批	检查 tools.exec.host/security/ask 配置
浏览器工具失败	检查浏览器状态、CDP 配置、可执行文件路径

关键日志签名

无回复：

• drop guild message (mention required → Discord mention 门控
• pairing request → 发送者等待 DM 配对审批
• blocked / allowlist → 发送者/房间/群组被过滤

Cron/Heartbeat：

• cron: scheduler disabled → Cron 已禁用
• heartbeat skipped + reason=quiet-hours → 在安静时间窗口外
• heartbeat skipped + reason=empty-heartbeat-file → HEARTBEAT.md 为空
• requests-in-flight → 主通道忙，Heartbeat 被推迟

Exec 审批：

• Approval required. → 命令等待 /approve ...
• SYSTEM_RUN_DENIED: allowlist miss → 命令不在 exec 允许列表中

相关链接

• help-debugging — 调试工具与方法
• docs/gateway/troubleshooting — Gateway 专项故障排查