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 完全没有反应。

排查顺序：

1. 确认 Gateway 在跑：

docker ps | grep openclaw

如果容器不在运行状态，重启它：

docker compose restart
# 或
docker restart openclaw

1. 检查渠道连通性：

openclaw channels status --probe

1. 检查对应平台的机器人状态：

   • 飞书：机器人是否被禁用？AppID/AppSecret 是否过期？
   • 微信公众号：服务器 IP 是否在白名单？Token 是否正确验证？
   • QQ：WebSocket 连接是否正常？机器人是否被腾讯风控？

类型二：认证类问题

表现：API 调用返回 401/403 错误，或模型突然不工作了。

排查顺序：

1. 检查模型配置：

openclaw config show | grep -i model

1. 检查 API Key 是否有效：

# 测试 API Key 是否有效（以 OpenAI 为例）
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

1. 检查余额：大多数模型服务商在余额不足时会静默降级或返回错误
2. 查看认证日志：

openclaw logs --follow | grep -i "auth\|401\|403\|unauthorized"

类型三：执行类问题

表现：exec 工具报错、命令执行失败、工具调用异常。

排查顺序：

1. 检查 exec 安全配置：

openclaw security audit | grep -i exec

1. 查看 exec 权限是否正确（参考上篇安全配置文章）：

{
  tools: {
    exec: {
      security: "deny",    // 是否默认拒绝
      ask: "always",      // 是否每次询问
    }
  }
}

1. 检查工具执行日志：

openclaw logs --follow | grep -i "exec\|tool\|error"

类型四：内存与状态类问题

表现：上下文丢失、对话不连贯、状态跳跃。

排查顺序：

1. 检查 Session 状态：

openclaw sessions list

1. 查看会话是否有异常中断：

openclaw sessions history <session_id>

1. 触发手动 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"

关键日志关键字

官方排查工具：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

预防性维护清单

与其等坏了再修，不如定期做这些检查：

总结

遇到问题不要慌，按顺序来：

1. 先跑 openclaw status — 确认基本状态
2. 再跑 openclaw doctor — 自动化检查
3. 然后 openclaw logs --follow — 找到具体错误
4. 最后根据错误类型定位 — 连接/认证/执行/内存

大多数问题 5 分钟内能定位。如果跑完这套流程还是找不到原因，再去 GitHub Issues 或社区求助，记得附上 openclaw doctor 的完整输出。