会话记录清理（提供商修复）

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

范围包括：

  • Tool call id 清理
  • Tool call 输入验证
  • Tool 结果配对修复
  • 轮次验证/排序
  • 思考签名清理
  • 图像 payload 清理

如果你需要会话记录存储详情，请参阅：

在哪里运行

所有会话记录清理都集中在嵌入式运行器中：

  • 策略选择： 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（嵌入式运行器）调用

全局规则：图像清理

图像 payload 总是会被清理，以防止因大小限制导致提供商端拒绝（缩放/重新压缩过大的 base64 图像）。

实现：

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

全局规则：格式错误的 tool call

缺少 input 和 arguments 的 Assistant tool-call 块会在构建模型上下文前被删除。这可以防止提供商拒绝部分持久化的 tool call（例如，在速率限制失败后）。

实现：

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

提供商矩阵（当前行为）

OpenAI / OpenAI Codex

  • 仅图像清理
  • 在切换到 OpenAI Responses/Codex 模型时，删除孤立的推理签名（没有后续内容块的独立推理项）
  • 无 tool call id 清理
  • 无 tool 结果配对修复
  • 无轮次验证或重新排序
  • 无合成 tool 结果
  • 无思考签名剥离

Google（Generative AI / Gemini CLI / Antigravity）

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

Anthropic / Minimax（Anthropic 兼容）

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

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

  • Tool call id 清理：strict9（字母数字长度 9）

OpenRouter Gemini

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

其他所有

  • 仅图像清理

历史行为（2026.1.22 之前）

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

  • transcript-sanitize 扩展在每次上下文构建时运行，可以：

    • 修复 tool use/result 配对
    • 清理 tool call id（包括保留 _/- 的非严格模式）

  • 运行器还执行提供商特定的清理，这重复了工作

  • 在提供商策略之外还发生了额外的变更，包括：

    • 在持久化前从 assistant 文本中剥离标签
    • 删除空的 assistant 错误轮次
    • 在 tool call 后修剪 assistant 内容

这种复杂性导致了跨提供商的退化（特别是 openai-responses 的 call_id|fc_id 配对）。2026.1.22 的清理移除了扩展，将逻辑集中在运行器中，并使 OpenAI 除了图像清理外不触及任何内容。

← 返回文档首页