OpenClaw 时间旅行调试完整指南

凌晨4点17分，一个 bug 悄悄溜走了。它就像薛定谔的猫——当我打开日志时它已经不在了。直到我发现了时间旅行调试，终于能在过去抓住它。

什么是时间旅行调试？

时间旅行调试（Time Travel Debugging）让你能够回放 agent 的完整执行历史，就像拥有了一台时光机。你可以在任意时间点暂停、检查状态、然后继续执行，彻底告别"为什么刚才好好的"的困惑。

启用录制

配置录制

{
  "debug": {
    "recording": {
      "enabled": true,
      "mode": "full",
      "storage": {
        "type": "local",
        "path": "~/.openclaw/recordings/",
        "maxSize": "10GB",
        "retention": 7
      },
      "capture": {
        "state": true,
        "toolCalls": true,
        "llmRequests": true,
        "memory": true
      }
    }
  }
}

录制管理

# 列出所有录制
openclaw debug recordings list

# 查看特定录制详情
openclaw debug recordings show 

# 导出录制
openclaw debug recordings export  --output debug-session.json

回放调试

启动回放

# 回放特定会话
openclaw debug replay 

# 从特定步骤开始
openclaw debug replay  --step 42

# 回放到特定事件
openclaw debug replay  --until "tool_call:web_search"

断点调试

# 设置断点
openclaw debug breakpoint add --event tool_call --name web_search

# 条件断点
openclaw debug breakpoint add --condition "tool_name === 'exec'"

# 删除断点
openclaw debug breakpoint remove --id

状态检查

// 在回放中检查状态
debug.inspect("context");
debug.inspect("memory");
debug.inspect("toolResult");

// 查看变量历史
debug.history("context.userInput");

时间线导航

# 查看时间线
openclaw debug timeline 

# 跳转到特定时间
openclaw debug goto --time "2026-04-21T03:14:27Z"

# 单步执行
openclaw debug step --forward
openclaw debug step --backward

快照对比

# 创建快照
openclaw debug snapshot create --name "before-bug"

# 对比快照
openclaw debug snapshot diff  

# 自动检测状态变化
openclaw debug snapshot autodiff --threshold 0.1

问题定位

自动分析

# 分析录制中的异常
openclaw debug analyze  --find anomalies

# 追踪变量变化
openclaw debug trace --variable context.result

# 查找性能瓶颈
openclaw debug analyze  --find slow

生成报告

# 生成调试报告
openclaw debug report  --output debug-report.html

# 导出为可共享格式
openclaw debug export  --format json

性能考虑

{
  "debug": {
    "recording": {
      "performanceMode": "auto",
      "sampling": {
        "enabled": true,
        "rate": 0.1
      },
      "compression": true
    }
  }
}

最佳实践

  • 按需录制 - 生产环境可使用采样
  • 定期清理 - 设置合理的保留期
  • 标记关键点 - 在关键步骤添加注释
  • 共享录制 - 与团队分享复杂问题的录制

相关资源