OpenClaw 🦞

转录本清理

转录本清理（提供者修复）

本文档描述了在运行之前（构建模型上下文）应用于转录本的特定于提供者的修复。这些是用于满足严格提供者要求的内存中调整。这些清理步骤不会重写磁盘上存储的 JSONL 转录本；但是，在会话加载之前，单独的会话文件修复过程可能会通过删除无效行来重写格式错误的 JSONL 文件。当发生修复时，原始文件会备份在会话文件旁边。

范围包括：

  • 工具调用 id 清理
  • 工具调用输入验证
  • 工具结果配对修复
  • 轮次验证/排序
  • 思考签名清理
  • 图像负载清理
  • 用户输入来源标记（用于会话间路由提示）

如果需要转录本存储详细信息，请参阅：

运行位置

所有转录本清理都集中在嵌入式运行器中：

  • 策略选择：src/agents/transcript-policy.ts
  • 清理/修复应用：sanitizeSessionHistory 在 src/agents/pi-embedded-runner/google.ts 中

策略使用 provider、modelApi 和 modelId 来决定应用什么。

与转录本清理分开，会话文件在加载前进行修复（如果需要）：

  • repairSessionFileIfNeeded 在 src/agents/session-file-repair.ts 中
  • 从 run/attempt.ts 和 compact.ts（嵌入式运行器）调用

全局规则：图像清理

图像负载始终会被清理，以防止因大小限制而导致提供者端拒绝（缩小/重新压缩过大的 base64 图像）。

这也有助于控制视觉能力模型的图像驱动 token 压力。较低的最大尺寸通常会减少 token 使用；较高尺寸保留细节。

实现：

  • sanitizeSessionMessagesImages 在 src/agents/pi-embedded-helpers/images.ts 中
  • sanitizeContentBlocksImages 在 src/agents/tool-images.ts 中
  • 最大图像边长可通过 agents.defaults.imageMaxDimensionPx 配置（默认：1200）。

全局规则：格式错误的工具调用

在构建模型上下文之前，会删除缺少 input 和 arguments 的助手工具调用块。这可以防止提供者因部分持久化的工具调用（例如，在速率限制失败后）而拒绝。

实现：

  • sanitizeToolCallInputs 在 src/agents/session-transcript-repair.ts 中
  • 在 src/agents/pi-embedded-runner/google.ts 中的 sanitizeSessionHistory 中应用

全局规则：会话间输入来源

当代理通过 sessions_send 将提示发送到另一个会话时（包括代理到代理的回复/宣布步骤），OpenClaw 会持久化创建的用户轮次，包含：

  • message.provenance.kind = "inter_session"

此元数据在转录本追加时写入，不会更改角色（role: "user" 保持与提供者兼容）。转录本读者可以使用它来避免将路由的内部提示视为终端用户编写的指令。

在上下文重建期间，OpenClaw 还会在内存中为这些用户轮次添加简短的 [Inter-session message] 标记，以便模型可以将它们与外部终端用户指令区分开来。

提供者矩阵（当前行为）

OpenAI / OpenAI Codex

  • 仅图像清理。
  • 为 OpenAI Responses/Codex 转录本删除孤立的推理签名（没有后续内容块的独立推理项）。
  • 无工具调用 id 清理。
  • 无工具结果配对修复。
  • 无轮次验证或重新排序。
  • 无合成工具结果。
  • 无思考签名剥离。

Google（Generative AI / Gemini CLI / Antigravity）

  • 工具调用 id 清理：严格的字母数字。
  • 工具结果配对修复和合成工具结果。
  • 轮次验证（Gemini 风格的轮次交替）。
  • Google 轮次排序修复（如果历史记录以助手开始，则添加一个小的用户引导）。
  • Antigravity Claude：规范化思考签名；删除未签名的思考块。

Anthropic / Minimax（Anthropic 兼容）

  • 工具结果配对修复和合成工具结果。
  • 轮次验证（合并连续的用户轮次以满足严格的交替）。

Mistral（包括基于 model-id 的检测）

  • 工具调用 id 清理：strict9（字母数字长度 9）。

OpenRouter Gemini

  • 思考签名清理：删除非 base64 thought_signature 值（保留 base64）。

其他所有

  • 仅图像清理。

历史行为（2026.1.22 之前）

在 2026.1.22 版本之前，OpenClaw 应用了多层转录本清理：

  • transcript-sanitize 扩展在每次上下文构建时运行，并且可以：
    • 修复工具使用/结果配对。
    • 清理工具调用 id（包括保留 _/- 的非严格模式）。
  • 运行器还执行特定于提供者的清理，这重复了工作。
  • 额外的突变发生在提供者策略之外，包括：
    • 在持久化之前从助手文本中剥离 <final> 标签。
    • 删除空的助手错误轮次。
    • 在工具调用后修剪助手内容。

这种复杂性导致了跨提供者回归（特别是 openai-responses call_id|fc_id 配对）。2026.1.22 清理删除了扩展，将逻辑集中在运行器中，并使 OpenAI 除了图像清理外不接触。