转录卫生（提供商修复?

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

范围包括?

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

如果你需要转录存储详情，请参阅：

运行位置

所有转录卫生都集中在嵌入式运行器中?

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

该策略使?provider、modelApi ?modelId 来决定应用什么?

与转录卫生分开，会话文件在加载前（如需要）会被修复?

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

全局规则：图片清?

图片负载始终被清理，以防止因大小限制而被提供商拒绝（缩小/重新压缩过大?base64 图片）?

这也有助于控制视觉模型的图片驱动 token 压力? 较低?最大尺寸通常会减?token 使用；较高的尺寸可以保留更多细节?

实现?

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

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

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

实现?

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

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

?agent 通过 sessions_send 将提示发送到另一个会话时（包?agent ?agent 回复/宣布步骤），OpenClaw 持久化创建的用户轮次并带有：

  • message.provenance.kind = "inter_session"

此元数据在转录追加时写入，不改变角色（role: "user" 保持不变以保持提供商兼容性）。转录阅读器可以使用此信息避免将路由的内部提示视为最终用户编写的指令?

在上下文重建期间，OpenClaw 还会预先pend 一个简短的 [Inter-session message] 标记到那些内存中的用户轮次，以便模型可以将它们与外部最终用户指令区分开来?

提供商矩阵（当前行为?

OpenAI / OpenAI Codex

  • 仅图片清理?
  • ?OpenAI Responses/Codex 转录丢弃孤立的推理签名（没有后续内容块的独立推理项）?
  • 无工具调?ID 清理?
  • 无工具结果配对修复?
  • 无轮次验证或重排序?
  • 无合成工具结果?
  • 无思考签名剥离?

*Google（生成式 AI / Gemini CLI / Antigravity?

  • 工具调用 ID 清理：严格字母数字?
  • 工具结果配对修复和合成工具结果?
  • 轮次验证（Gemini 风格的轮次交替）?
  • Google 轮次排序修复（如果历史以助手开头，预先pend 一个微小的用户引导）?
  • Antigravity Claude：规范化思考签名；丢弃无符号思考块?

*Anthropic / Minimax（Anthropic 兼容?

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

Mistral（包括基于模?ID 的检测）

  • 工具调用 ID 清理：strict9（字母数字长?9）?

OpenRouter Gemini

  • 思考签名清理：剥离?base64 ?thought_signature 值（保留 base64）?

*其他所?

  • 仅图片清理?

历史行为?026.1.22 之前?

:2026.1.22 发布之前，OpenClaw 应用了多层转录卫生：

  • 转录清理扩展在每个上下文构建上运行，可以?
    • 修复工具使用/结果配对?
    • 清理工具调用 ID（包括保?_/- 的非严格模式）?
  • 运行器还执行提供商特定的卫生，重复了工作?
  • 发生额外的变更（在提供商策略之外），包括?
    • 在持久化之前从助手文本中剥离 <final> 标签?
    • 丢弃空的助手错误轮次?
    • 在工具调用后修整助手内容?

这种复杂性导致了跨提供商的回归（特别?openai-responses ?call_id|fc_id 配对）?026.1.22 清理删除了扩展，将逻辑集中在运行器中，并使 OpenAI **无操?*（仅图片清理除外）?