OpenClaw 故障排查
约 2 分钟
基础排查命令
按顺序执行：
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe健康信号：
openclaw gateway status显示Runtime: running和RPC probe: okopenclaw doctor无阻塞性问题openclaw channels status --probe显示 connected/ready
常见问题
1. 没有回复
排查：
openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw config get channels
openclaw logs --follow常见原因：
- 配对待批准
- 群组需要 @提及
- 通道/群组白名单不匹配
日志关键词：
drop guild message (mention required→ 群消息被忽略pairing request→ 发送者需要批准blocked/allowlist→ 被策略过滤
2. Dashboard 无法连接
排查：
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json常见原因：
- URL/端口错误
- 认证模式/令牌不匹配
- 非安全上下文需要设备认证
日志关键词：
device identity required→ 非安全上下文或缺少设备认证unauthorized→ 令牌/密码不匹配gateway connect failed:→ 目标主机/端口错误
3. 网关服务不运行
排查：
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep常见原因：
- 配置模式错误
- 端口冲突
日志关键词：
Gateway start blocked: set gateway.mode=local→ 需要设置gateway.mode="local"refusing to bind gateway ... without auth→ 非回环绑定需要令牌another gateway instance is already listening/EADDRINUSE→ 端口被占用
4. 通道连接但无消息
排查：
openclaw channels status --probe
openclaw pairing list <channel>
openclaw status --deep
openclaw logs --follow
openclaw config get channels常见原因：
- DM 策略问题
- 群组白名单/提及要求
- 通道 API 权限缺失
日志关键词：
mention required→ 消息被群组提及策略忽略pairing→ 发送者未批准missing_scope,not_in_channel,Forbidden→ 通道权限问题
5. Cron/心跳未执行
排查：
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow常见原因：
- Cron 被禁用
- 调度器故障
日志关键词：
cron: scheduler disabled; jobs will not run automatically→ Cron 已禁用cron: timer tick failed→ 调度器故障heartbeat skippedwithreason=quiet-hours→ 休眠时间跳过
快速诊断
# 检查整体状态
openclaw status
# 检查网关
openclaw gateway status
# 检查日志
openclaw logs --follow
# 运行诊断
openclaw doctor
# 检查通道
openclaw channels status --probe