对话记录卫生(提供商修复)

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

范围包括:

工具调用 ID 清理
工具调用输入验证
工具结果配对修复
轮次验证/排序
思考签名清理
图像负载清理

如果您需要对话记录存储详细信息,请参阅:

/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 图像)。

实现:

src/agents/pi-embedded-helpers/images.ts 中的 sanitizeSessionMessagesImages
src/agents/tool-images.ts 中的 sanitizeContentBlocksImages

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

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

实现:

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

提供商矩阵(当前行为)

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 除图像清理外不进行任何修改。

对话记录卫生(提供商修复) ​

运行位置 ​

全局规则:图像清理 ​

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