调试指南（Debugging Guide）

当 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 实时日志

不需要重启，实时查看 Gateway 日志：

openclaw logs --follow

这会在终端中持续打印日志，适合快速排查消息路由、通道连接和模型报错。

---

原始流日志（Raw Stream Logging）

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

• AI 模型返回了意外内容
• 流式输出中断
• Token 截断问题

查看原始流日志示例

[stream] --> POST https://api.anthropic.com/v1/messages
[stream] <-- 200 OK
[stream] data: {"type":"content_block_start","index":0,...}
[stream] data: {"type":"content_block_delta","delta":{"text":"你好"},...}
[stream] data: [DONE]

---

原始块日志（Raw Chunk Logging）

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

• 消息格式问题
• 工具调用参数丢失
• 消息组装异常

查看原始块日志示例

[chunk] type=text content="你好，我是" index=0
[chunk] type=tool_use name="search" input={"query":"..."} index=1
[chunk] type=text content="根据搜索结果..." index=2

---

日志命令参考

# 查看所有日志
openclaw logs

# 只看 Gateway 相关日志
openclaw logs --filter gateway

# 查看最近 100 条日志
openclaw logs --tail 100

# 持续监听新日志（类似 tail -f）
openclaw logs --follow

---

常见调试场景

API 调用失败

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 --probe
3. 查看 Gateway 日志：openclaw logs --follow
4. 检查通道 Token 是否过期

工具执行错误

1. 开启 rawChunks: true，查看工具调用参数
2. 检查工具定义是否与模型期望格式匹配
3. 手动测试工具脚本是否正常运行
4. 查看工具执行日志：openclaw logs --filter tools

---

安全注意事项

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

• API Key 片段
• 用户输入内容
• 模型返回的敏感信息

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

---

在 VS Code 里调试 Gateway

如果你是在看 OpenClaw 源码，而不是只使用命令行，那么 VS Code 调试很有用。 新版本构建出来的文件名可能带 hash，所以必须打开 source map，断点才能正确跳回 src/ 里的 TypeScript 源码。

最省心的方式：

1. 打开 VS Code 左侧的 Run and Debug 面板。
2. 选择 Rebuild and Debug Gateway。
3. 点击开始调试。

这个配置会自动删除 dist，重新构建，并打开 source map。 适合你刚改完源码、想从干净构建开始调试的场景。

如果你想自己控制构建，按下面做。

Linux/macOS：

export OUTPUT_SOURCE_MAPS=1
pnpm clean:dist && pnpm build

Windows PowerShell：

$env:OUTPUT_SOURCE_MAPS="1"
pnpm clean:dist
pnpm build

Windows CMD：

set OUTPUT_SOURCE_MAPS=1
pnpm clean:dist
pnpm build

然后在 VS Code 里选择 Debug Gateway 再启动。

调试时你可以：

• 在 src/ 目录里的 TypeScript 文件打断点。
• 单步执行。
• 查看变量。
• 查看调用栈。

如果调试过程中还需要用构建后的 OpenClaw CLI，可以另开一个终端运行：

node ./openclaw.mjs

或者临时建一个别名：

alias openclaw-build="node $(pwd)/openclaw.mjs"

两个调试配置怎么选

刚改完源码、想自动重新构建，选 Rebuild and Debug Gateway。 已经构建好了、只是想反复启动调试，选 Debug Gateway。

---

下一步：故障排查