🐛 OpenClaw Agent Debugging

功能介绍

世界上有一种痛苦叫"调试AI Agent"。它不像传统代码，你设个断点就能看到变量值。Agent的决策过程是黑盒——你只知道它"做了什么"，不知道它"为什么这么做"。

OpenClaw的Agent Debugging工具箱就是来破这个局的。时间旅行调试让你倒回任意时刻；步骤回放展示每个决策节点；错误追踪精确定位问题根源。就像给Agent装了个"行车记录仪"。

时间旅行调试

这是最强大的调试功能。就像电影的倒带键——你可以回到任意对话轮次，检查当时的上下文、工具调用、决策逻辑。

# 启用时间旅行调试
debugging:
  time_travel:
    enabled: true
    record_everything: true  # 记录所有中间状态
    
# CLI 使用
openclaw debug session sess_abc123

# 查看第5轮的完整状态
openclaw debug session sess_abc123 --turn 5

# 查看某个工具调用的详细过程
openclaw debug session sess_abc123 --tool-call web_fetch_7

调试界面示例

Session: sess_abc123 | Total turns: 12 | Status: error

Turn 5: [14:23:07]
  Input:    "搜索最新的AI工具发布"
  Skill:    web_search
  Tool:     brave_search
  Result:   {found: 8 results}
  LLM Call: gpt-4o, 1200 tokens, $0.018
  Decision: "选择前3个结果进行深度获取"
  
Turn 6: [14:23:09]  ← ⚠️ ERROR HERE
  Input:    "获取前3个URL的内容"
  Skill:    web_fetch
  Tool:     fetch_url("https://...")
  Error:    "Rate limit: 429 Too Many Requests"
  Retry:    3/5 (backoff: 5s)
  State:    waiting_for_retry
  
  ↓ Time Travel: 你可以在这里修改请求参数重试

Prompt Inspector

很多时候bug不是代码问题，而是Prompt问题。Prompt Inspector让你看到发送给LLM的完整内容。

# 启用Prompt检查
debugging:
  prompt_inspector:
    enabled: true
    log_all_prompts: true
    highlight_changes: true  # 高亮每轮Prompt的变化
    
# 查看完整Prompt
openclaw debug prompt sess_abc123 --turn 6

# 输出：
# ═══════════════════════════════════════
# SYSTEM PROMPT (2,847 tokens)
# ═══════════════════════════════════════
# [SOUL.md content...]
# [SKILL instructions...]
# 
# ═══════════════════════════════════════
# USER MESSAGE (156 tokens)  
# ═══════════════════════════════════════
# "搜索最新的AI工具发布"
#
# ═══════════════════════════════════════
# CONTEXT (3,200 tokens)
# ═══════════════════════════════════════
# [Previous conversation...]
# [Tool results...]
#
# Total: 6,203 tokens
# Cost: $0.093

断点调试

# 设置断点
debugging:
  breakpoints:
    - skill: web_fetch
      condition: "status == error"
      action: pause
      
    - skill: "*"
      condition: "tokens_used > 5000"
      action: pause_and_notify
      
    - tool: brave_search
      action: always_pause  # 每次都暂停
      
# 实时调试
openclaw debug live --breakpoints

# 当断点命中时，可以：
# 1. 查看当前状态
# 2. 修改变量
# 3. 重试当前步骤
# 4. 跳过当前步骤
# 5. 继续执行

常见问题诊断

1. Agent陷入循环

# 检测循环
debugging:
  loop_detection:
    enabled: true
    max_repetitions: 3  # 同一操作重复3次视为循环
    action: pause_and_analyze

# 手动诊断
openclaw debug analyze --detect-loops sess_abc123
# 输出: "检测到循环: turn 7-10 重复调用web_fetch，参数相同"

2. 幻觉问题

3. 工具调用失败

# 工具错误分析
openclaw debug errors sess_abc123 --tool-errors

# 输出:
# Error #1: brave_search - 429 Rate Limit
#   Cause: API配额已用完
#   Solution: 等待60秒或升级API plan
#
# Error #2: web_fetch - 404 Not Found  
#   Cause: URL已失效
#   Solution: 添加URL验证步骤

最佳实践

• 默认开启记录：生产环境也记录调试信息，存储成本低但排查价值高
• 错误分类：将错误分为Prompt问题、工具问题、模型问题、逻辑问题四类
• 复现优先：能稳定复现的bug先修，偶发的bug先记录
• Prompt是Bug重灾区：60%的Agent bug源于Prompt不清晰或指令冲突
• 自动化测试：修复bug后写回归测试，防止同类问题再犯

相关链接