×

OpenClaw调试指南（Debugging Guide）

benking benking 发表于2026-03-01 18:39:25 浏览12 评论0

抢沙发发表评论

当 Agent 行为异常或请求没有按预期执行时，开启调试模式能让你看到 OpenClaw 与 AI 模型之间的完整通信细节，快速定位问题所在。

开启调试模式（Debug Mode）

在配置文件中添加 debug 块，即可启用详细日志：

{  debug: {    enabled: true,      // 启用调试模式    rawStream: true,    // 记录原始流日志    rawChunks: true,    // 记录原始块日志    verbose: true       // 输出详细信息  }}

配置文件位置

默认配置文件路径为 ~/.openclaw/config.json5。运行 openclaw config edit 可以直接打开编辑。

修改配置后，重启 Gateway 使配置生效：

openclaw gateway restart

Gateway 监视模式（Watch Mode）

不需要重启，实时查看 Gateway 事件流：

openclaw gateway --watch

这会在终端中持续打印 Gateway 接收和发送的事件，适合快速排查消息路由问题。

原始流日志（Raw Stream Logging）

启用 rawStream: true 后，OpenClaw 会记录与 AI 模型之间的完整 HTTP 流式响应。适合排查：

  • AI 模型返回了意外内容

  • 流式输出中断

  • Token 截断问题


原始块日志（Raw Chunk Logging）

启用 rawChunks: true 后，OpenClaw 会记录消息在内部传递时的分块详情。适合排查：

  • 消息格式问题

  • 工具调用参数丢失

  • 消息组装异常


日志命令参考

# 查看所有日志openclaw logs# 只看 Gateway 相关日志openclaw logs --filter gateway# 查看最近 100 条日志openclaw logs --tail 100# 持续监听新日志（类似 tail -f）openclaw logs --follow

常见调试场景

  1. 开启 rawStream: true，查看完整的 HTTP 请求和响应

  2. 确认 API Key 是否正确：openclaw config show

  3. 检查 API 端点是否可访问：curl https://api.anthropic.com/v1/models

  4. 查看错误码含义（401 = 未授权，429 = 超速限制，500 = 服务端错误）

  1. 开启 verbose: true，查看消息路由日志

  2. 确认通道连接状态：openclaw channels status

  3. 查看 Gateway 事件：openclaw gateway --watch

  4. 检查通道 Token 是否过期

  1. 开启 rawChunks: true，查看工具调用参数

  2. 检查工具定义是否与模型期望格式匹配

  3. 手动测试工具脚本是否正常运行

  4. 查看工具执行日志：openclaw logs --filter tools

安全注意事项

调试日志（尤其是 rawStream 和 rawChunks）可能包含：

  • API Key 片段

  • 用户输入内容

  • 模型返回的敏感信息

生产环境请勿开启调试模式。 调试完成后，务必将 debug.enabled 改回 false 并重启 Gateway。