夜雨聆风OpenClaw 故障排查与日志分析
AI 助手突然不响应了，消息发不出去，不知道从哪查起。这篇文章给你一套标准化排查流程，从 Gateway 状态到日志分析，5 分钟定位问题。
60 秒快速诊断
遇到问题，第一步不是查日志，而是按顺序跑这几个命令。绝大多数常见问题在这一步就能定位：
# 1. 检查 Gateway 基本状态
openclaw status
# 2. 检查所有组件状态
openclaw status --all
# 3. Gateway 健康探测
openclaw gateway probe
# 4. Gateway 详细状态
openclaw gateway status
# 5. 医生模式：检查配置和环境
openclaw doctor
# 6. 探测各渠道连通性
openclaw channels status --probe
# 7. 实时查看日志
openclaw logs --follow
这七条命令覆盖了 Gateway 进程、渠道连接、配置完整性三个维度。按顺序跑下来，常见问题的根因基本都能暴露。
常见故障分类
类型一：连接类问题
表现：消息发出去没有回应，AI 完全没有反应。
排查顺序：
确认 Gateway 在跑：
docker ps | grep openclaw
如果容器不在运行状态，重启它：
docker compose restart
# 或
docker restart openclaw
检查渠道连通性：
openclaw channels status --probe
检查对应平台的机器人状态： 飞书：机器人是否被禁用？AppID/AppSecret 是否过期？ 微信公众号：服务器 IP 是否在白名单？Token 是否正确验证？ QQ：WebSocket 连接是否正常？机器人是否被腾讯风控？
类型二：认证类问题
表现：API 调用返回 401/403 错误，或模型突然不工作了。
排查顺序：
检查模型配置：
openclaw config show | grep -i model
检查 API Key 是否有效：
# 测试 API Key 是否有效（以 OpenAI 为例）
curl https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY"
检查余额：大多数模型服务商在余额不足时会静默降级或返回错误 查看认证日志：
openclaw logs --follow | grep -i "auth\|401\|403\|unauthorized"
类型三：执行类问题
表现：exec 工具报错、命令执行失败、工具调用异常。
排查顺序：
检查 exec 安全配置：
openclaw security audit | grep -i exec
查看 exec 权限是否正确（参考上篇安全配置文章）：
{
tools: {
exec: {
security: "deny", // 是否默认拒绝
ask: "always", // 是否每次询问
}
}
}
检查工具执行日志：
openclaw logs --follow | grep -i "exec\|tool\|error"
类型四：内存与状态类问题
表现：上下文丢失、对话不连贯、状态跳跃。
排查顺序：
检查 Session 状态：
openclaw sessions list
查看会话是否有异常中断：
openclaw sessions history <session_id>
触发手动 Compaction 清理上下文：
/compact
日志分析：找到真正有用的信息
OpenClaw 日志位置：~/.openclaw/logs/
# 实时监控所有日志
openclaw logs --follow
# 过滤错误级别
openclaw logs --follow | grep -i error
# 过滤特定请求 ID（定位某条消息的问题）
openclaw logs --follow | grep "req_abc123"
# 按时间范围查看
openclaw logs --from "2026-04-01 09:00" --to "2026-04-01 10:00"
关键日志关键字
| 关键字 | 含义 |
|---|---|
channel error |
渠道连接问题，如飞书/QQ 断开 |
auth failed |
认证失败，检查 API Key |
rate limit |
触发了限流，模型服务商的问题 |
tool execution failed |
工具执行出错 |
compaction |
上下文压缩触发，正常现象 |
gateway restart |
Gateway 被重启过 |
官方排查工具：openclaw doctor
doctor 是 OpenClaw 内置的自动诊断工具，会检查：
环境变量是否正确配置 配置文件语法是否正确 各渠道插件是否正常加载 依赖模块是否完整 常见配置错误
openclaw doctor
输出通常会长这样：
[✓] Gateway配置文件语法正确
[✓] 飞书插件已加载
[✓] 模型配置有效
[✗] exec 安全模式为 full，建议检查是否需要
[✓] 日志目录可写
按 [✗] 的提示逐项修复即可。
场景实战：飞书机器人突然不响应
这是最常见的问题之一。完整排查路径：
第一步：确认机器人状态
openclaw channels status --probe
第二步：检查飞书开放平台的机器人配置
登录飞书开放平台 → 找到你的应用 → 检查：
机器人功能是否开启 消息权限是否申请 Webhook URL 是否还能响应
第三步：验证 Token
飞书的 app_access_token 和 tenant_access_token 有有效期（2小时），如果你的消息处理很慢，Token 可能在处理过程中过期。需要重启相应的刷新机制。
第四步：检查 IP 白名单
如果你的服务器 IP 变了（重启后公网 IP 漂移），需要更新飞书的 IP 白名单。
第五步：看日志定位具体错误
openclaw logs --follow | grep -i feishu
预防性维护清单
与其等坏了再修，不如定期做这些检查：
| 周期 | 检查项 | 命令 |
|---|---|---|
| 每天 | Gateway 是否在跑 | docker ps | grep openclaw |
| 每周 | 安全审计 | openclaw security audit |
| 每周 | 渠道连通性 | openclaw channels status --probe |
| 每月 | 日志目录大小 | du -sh ~/.openclaw/logs/ |
| 每月 | 配置备份 | cp ~/.openclaw/openclaw.json ~/backup/ |
| 每次部署后 | doctor 检查 | openclaw doctor |
总结
遇到问题不要慌，按顺序来：
先跑 openclaw status— 确认基本状态再跑 openclaw doctor— 自动化检查然后 openclaw logs --follow— 找到具体错误最后根据错误类型定位 — 连接/认证/执行/内存
大多数问题 5 分钟内能定位。如果跑完这套流程还是找不到原因，再去 GitHub Issues 或社区求助，记得附上 openclaw doctor 的完整输出。
