ClawTrace

ClawTrace 每次分析一个 OpenClaw 会话。它结合 OpenClaw 日志与当前会话上下文，重建执行步骤、汇总模块活动，并生成一份 Markdown 格式的追踪报告。

适用场景

• 端到端地检查单个 OpenClaw 会话
• 解释运行缓慢、失败、重试或噪声较大的执行过程
• 生成结构化的会话追踪报告
• 提供基于证据的优化建议

核心规则

1. 始终每次仅分析一个会话。
2. 撰写报告前必须同时使用以下两类数据源：
   • openclaw logs --json --local-time --no-color
   • 当前会话上下文
3. 绝不虚构缺失值。必要时使用 Not available、Estimated 或 Unknown。
4. 优先采用日志中明确记录的精确标识符和时间戳，而非推断值。
5. 报告语言默认使用用户所用语言；除非用户明确要求其他语言。
6. 若用户聊天通道支持文件发送，优先以 Markdown 文件形式交付报告；否则在聊天中直接返回结构相同的文本内容。
7. 最终报告中不得输出原始日志、原始 JSON 或逐字复制的日志行。

输入

日志

使用 JSON 格式日志，确保事件可被可靠解析。

openclaw logs --json --local-time --no-color

• --limit ：限制输出行数
• --max-bytes ：避免截取过长的尾部日志
• --interval ：如需轮询，指定轮询间隔（毫秒）
• --timeout ：如需等待最新输出，设置超时时间（毫秒）
• --expect-final：仅当任务需等待最终响应时使用

上下文

利用当前会话上下文识别目标运行实例，并补全日志中未显式记录的信息，例如请求作用域、最近响应、会话线索以及上下文尺寸指示器等。

分析流程

1：识别目标会话

• sessionId
• sessionKey
• runId
• 渠道（channel）
• 邻近时间戳
• 当前会话线索

若同一会话中存在多个运行实例，默认选择最新完成的运行，除非用户明确指向其他运行。

2：提取关键事件

提取会话、提示（prompt）、智能体（agent）、工具（tool）、通道（lane）、上下文（context）、警告（warning）、错误（error）及相关网关（gateway）事件，并捕获分析所需的关键字段，包括时间、日志等级（level）、模块（module）、sessionID、runID、tool、toolCallID、耗时（duration）、摘要（summary）和结果（outcome）。

3：重建执行步骤

将事件转换为有序的执行步骤，例如 queue、prompt、agent、tool、gateway、context、warn、error 和 done。

尽可能配对起始事件与结束事件以计算耗时；若仅有其一，则将耗时标记为 Unknown。

4：计算指标

• 会话 ID（Session ID）
• 会话密钥（Session Key）
• 运行 ID（Run ID）
• 开始与结束时间
• 总耗时
• 步骤总数
• 工具调用次数
• 警告次数
• 错误次数
• 模块数量
• 上下文指标
• Token 指标

有确切值时优先使用；否则标记为 Estimated 或 Not available。

5：生成优化建议

仅提供基于证据的建议，例如重复的工具调用、上下文过大、警告反复出现、工具执行耗时过长、队列延迟、网关噪声过多等。

若无明确优化机会，应明确说明“未发现具备证据支持的优化项”。

输出格式

若用户聊天通道支持文件发送，优先输出 Markdown 文件，命名建议为 clawtrace-run-.md 或 clawtrace-report-.md；否则在聊天中直接返回相同结构的文本内容。

示例 Markdown 输出：

# ClawTrace 报告

## 概览
作用域：RunId= 或 Message=
开始时间：
结束时间：
总 Token 使用量：
总耗时：（秒）
总步骤数：
使用的工具：（英文逗号分隔）
警告数：
错误数：
生成时间：

优化建议：
- <基于证据的建议>
- <基于证据的建议>

## 模块统计

| 模块 | 成功数 | 警告数 | 错误数 | 总步骤数 | 平均耗时 | 备注 |
| --- | ---: | ---: | ---: | ---: | --- | --- |
|  |  |  |  |  |  |  |

## 执行步骤

| 步骤 | 时间 | 类型 | 模块 | 动作 | 耗时 | 结果 | 备注 |
| ---: | --- | --- | --- | --- | --- | --- | --- |
| 1 |  |  |  |  |  |  |  |
| 2 |  |  |  |  |  |  |  |

请严格按时间升序排列 Steps 表格中的行。结果（Result）字段仅允许使用 Success、Failed、Warning 或 Unknown；禁止包含原始日志或原始 JSON 内容。

部分数据处理

若日志中包含 Log tail truncated (increase --max-bytes). 提示，请明确声明本报告基于部分日志生成。

不得虚构缺失步骤；对不确定的耗时及指标，统一标记为 Unknown、Estimated 或 Not available。

噪声过滤

忽略无关的后台噪声，例如定时任务（cron timers）、心跳信号（heartbeats）及非目标会话相关的通道流量，除非其对目标会话产生实质性影响。

质量标准

报告应能快速呈现：所分析的是哪个会话、耗时多久、涉及哪些模块与步骤、时间主要消耗在何处、发生了哪些警告或失败、下一步应如何优化。若证据薄弱，须清晰说明。