转录清洗（Provider 修复）

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

范围包括：

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

如需转录存储详情，见：

/openclaw/reference/session-management-compaction

运行位置

所有转录清洗集中在嵌入式运行器中：

策略选择：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 中应用

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

当代理通过 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 应用了多层转录清洗：

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

这种复杂性导致了跨提供商回归（尤其是 openai-responses 的 call_id|fc_id 配对问题）。2026.1.22 清理版本移除了该扩展，将逻辑集中到运行器，并使 OpenAI 在图像净化之外不做任何处理。

转录清洗（Provider 修复） ​

运行位置 ​

全局规则：图像净化 ​

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

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

提供商矩阵（当前行为） ​