转录卫生

OpenClaw 会在运行前（构建模型上下文时）应用 provider 特定的修复。这些是为了满足严格 provider 要求而进行的 内存中 调整。运行时转录状态仍保留在 SQLite 中；provider 特定的 assistant 预填充剥离仅在构造出站负载时发生。

范围包括：

• 仅运行时提示上下文不进入用户可见的转录轮次
• 工具调用 ID 清理
• 工具调用输入验证
• 工具结果配对修复
• 轮次验证 / 排序
• Thought 签名清理
• Thinking 签名清理
• 图像负载清理
• provider 重放前清理空白文本块
• provider 重放前对不完整的纯推理 length-turn 进行清理
• 用户输入来源标记（用于跨会话路由的提示词）
• 为 provider 重放移除空的 assistant 错误轮次

如需了解转录存储细节，请参阅 Session management deep dive。

失败尝试与恢复¶

纯文本 assistant 错误会被缓冲，直到逻辑运行结束。恢复会丢弃其部分文本，因为恢复后的回复会取代它。最终失败则保留最后一次尝试的部分文本和错误。

工具调用、可显示的非文本内容和附件事实会立即持久化，先于依赖的工具结果或恢复后的回复。这些事实行省略错误，并使用可重放的停止原因，以便 provider 重放保留这些调用。对于混合文本/事实消息，部分文本和错误会分别保留在缓冲区；最终结算不会重复事实或用量。这使用现有的 assistant 行结构，不需要数据库迁移。

全局规则：运行时上下文不属于用户转录¶

运行/系统上下文可以添加到某一轮次的模型提示中，但它不是最终用户创作的内容。OpenClaw 为 Gateway 回复、排队中的后续问题、ACP、CLI 和嵌入式 OpenClaw 运行保留一个单独的、面向转录的提示正文。存储的可见用户轮次使用该转录正文，而不是运行时增强后的提示。

对于已经持久化了运行时包装器的旧会话，Gateway 历史界面会在将消息返回给 WebChat、TUI、REST 或 SSE 客户端之前应用显示投影。

运行位置¶

嵌入式运行器选择并应用转录策略：

• 策略选择：src/agents/transcript-policy.ts（resolveTranscriptPolicy，以 provider、modelApi 和 modelId 为键）
• 清理/修复应用：src/agents/embedded-agent-runner/replay-history.ts 中的 sanitizeSessionHistory

旧版 JSONL 校验和导入属于 openclaw doctor --fix；嵌入式运行器不会修复或重新打开基于文件的运行时转录。

全局规则：图像清理¶

图像负载始终会被清理，以防止因大小限制而被 provider 拒绝（对过大的 base64 图像进行缩小/重新压缩）。这也有助于控制视觉能力模型的图像驱动 token 压力：较低的最大尺寸可减少 token 用量，较高的尺寸则可保留更多细节。

实现：

• src/agents/embedded-agent-helpers/images.ts 中的 sanitizeSessionMessagesImages
• src/agents/tool-images.ts 中的 sanitizeContentBlocksImages
• 图像最大边长可通过 agents.defaults.imageMaxDimensionPx 配置（默认：1200）
• 此过程遍历重放内容时会移除空白文本块。变为空的 assistant 轮次会被丢弃，除非它们拥有不透明的 provider 重放状态；变为空的 user 和 tool-result 轮次会收到一个非空的省略内容占位符。

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

在构建模型上下文之前，会丢弃同时缺少 input 和 arguments 的 assistant 工具调用块。这可以防止部分持久化的工具调用（例如在速率限制失败后）导致 provider 拒绝。

当工具在当前目录中被禁用、移除或不可用时，已完成的调用/结果对仍保留在历史中。其名称仍须符合有效语法；格式错误的调用、模糊配对和合成的缺失结果修复不享有此例外。重放已完成的配对不会宣传或授权该工具用于新调用。

实现：

• src/agents/session-transcript-repair.ts 中的 sanitizeToolCallInputs
• 应用于 sanitizeSessionHistory（src/agents/embedded-agent-runner/replay-history.ts）

全局规则：工具结果配对¶

在重写 provider 特定的调用 ID 之前，工具结果会与每个 assistant 轮次中的工具调用出现位置配对。provider 生成的 ID 可能在后续轮次中重复，因此紧邻重复调用的结果会保留在该出现位置。只有当恰好一个未解析的出现位置可以拥有某个被移位的结构时，它才会被移动；存在歧义的额外结果会被丢弃，缺失的出现位置会收到合成的错误结果。

实现：src/agents/session-transcript-repair.ts 中的 sanitizeToolUseResultPairing

切换模型时，provider 重放会在移除源模型的异步元数据之前，将延迟的异步工具结果移到其原始调用旁边。匹配前会修剪调用 ID 和结果 ID，因此周围的空白不会把真实结果变成合成的缺失结果错误。此投影在 packages/ai/src/transcript-transform.ts 中运行，并保持已存储的历史不变。

全局规则：不完整或静默的纯推理轮次¶

当 assistant 轮次在以下任一事件后仅包含 thinking 或 redacted-thinking 内容时，它们会从内存重放副本中省略：

• provider 输出限制以不完整的推理状态结束该轮次。
• 静默回复清理移除了该轮次唯一可见的 NO_REPLY 文本。

当严格的 provider 重建对话时，静默回复清理可防止隐藏推理合并到后续的 assistant 工具使用轮次中。

空的 length-turn 保持不变，带可见文本、工具调用或未知内容块的 length-turn 也保持不变。带工具调用或未知内容块的静默回复轮次同样保持不变。已存储的转录不会被重写。

实现：normalizeAssistantReplayContent 位于 src/agents/embedded-agent-runner/replay-history.ts

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

当代理通过 sessions_send 向另一个会话发送提示（包括代理到代理的回复/通告步骤）时，OpenClaw 会持久化创建的用户轮次，并设置 message.provenance.kind = "inter_session"。

OpenClaw 还会在路由的提示文本前添加同轮 [Inter-session message] ... isUser=false 标记，以便当前模型调用能够区分外部会话输出与外部最终用户指令。该标记在可用时包含源会话、通道和工具。转录仍使用 role: "user" 以保持提供商兼容性，但可见文本和来源元数据都将该轮次标记为跨会话数据。

在上下文重建期间，OpenClaw 会对仅具有来源元数据的较早持久化跨会话用户轮次应用相同标记。

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

OpenAI / OpenAI Codex

• 仅进行图像清理。
• 对于 OpenAI Responses/Codex 转录，丢弃孤立的推理签名（没有后续内容块的独立推理项），并在模型路由切换后丢弃可重放的 OpenAI 推理。
• 保留可重放的 OpenAI Responses 推理项负载，包括加密的空摘要项，以便手动/WebSocket 重放保持所需的 rs_* 状态与助手输出项配对。
• 原生 ChatGPT Codex Responses 遵循 Codex 线路一致性，通过重放先前的 Responses 推理/消息/函数负载（不带先前项 ID）同时保留会话 prompt_cache_key。
• OpenAI Responses 系列重放保留规范的 call_*|fc_* 同模型推理对，但在 pi-ai 负载转换前确定性地规范化畸形或过长的 call_id/函数调用项 ID。
• 工具结果配对修复可能会移动真实匹配的输出，并为缺失的工具调用合成 Codex 风格的 aborted 输出。
• 不进行轮次验证或重新排序；不剥离思考签名。

OpenAI 兼容 Chat Completions

• 重放前会剥离历史助手思考/推理块，以便本地和代理式 OpenAI 兼容服务器不会收到先前轮次的推理字段，例如 reasoning 或 reasoning_content。
• 当前同轮工具调用续接会保持助手推理块附加到工具调用，直到工具结果被重放。
• 具有 reasoning: true 的自定义/自托管模型条目会保留重放的推理元数据。
• 提供商拥有的异常可以在其线路协议要求重放推理元数据时选择退出。

Google (Generative AI / Gemini CLI / Antigravity)

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

Anthropic / Minimax (Anthropic 兼容)

• 前缀绑定的 Claude 模型（例如 Fable 5.1）会将其用户轮次之后立即持久化的运行时上下文载体作为隐藏自定义消息，并原地重放它们。较早用户轮次上的内联入站元数据也会被保留。此模型范围的仅追加策略包括 Bedrock、Vertex 和 Foundry 路由。载体仅包含分隔的上下文主体；共享指令只存在于稳定系统提示中一次。载体保持用户角色上下文，并被排除在聊天历史和压缩摘要之外。其他 Claude 模型和 Anthropic 兼容模型保留临时载体，避免在没有任何内容绑定前缀时因旧载体产生重复的缓存读取费用和上下文使用。
• 工具结果配对修复和合成工具结果。
• 轮次验证（合并连续用户轮次以满足严格交替）。对于 Messages API 上的前缀绑定模型，仅追加重放会保持连续用户轮次分开，因此命令轮次后跟提示会以相同的每轮时间戳重放，这些时间戳是活动轮次被签署覆盖的；Bedrock Converse 仍会合并它们。
• 当启用思考时，包括 Cloudflare AI Gateway 路由，会从出站 Anthropic Messages 负载中剥离尾部助手预填充轮次。
• 当会话已被压缩时，提供商重放前会剥离压缩前的助手思考签名。对于前缀绑定模型，压缩会更改已签署的前缀（摘要内容替换原始内容），因此重放原始签名可能导致 Anthropic 以 "Invalid signature in thinking block" 拒绝请求。思考文本会作为未签名块保留，然后由以下规则处理。
• 具有缺失、空或空白重放签名的思考块会在提供商转换前被剥离。如果这使助手轮次变空，OpenClaw 会以非空的省略推理文本保持轮次形状。
• 必须剥离的较早仅思考助手轮次会被替换为非空的省略推理文本，以便提供商适配器不会丢弃重放轮次。

Amazon Bedrock (Converse API)

• 空助手流错误轮次和旧版回退占位符会从内存重放副本中丢弃。这避免了无效的空 ContentBlocks 和合成助手预填充，而无需重写存储的转录。
• 零使用的空停止轮次也会被丢弃；已计费的静默回复和具有真实助手内容的错误保留其现有重放处理。
• 当会话已被压缩时，Converse 重放前会剥离压缩前的助手思考签名，原因与上述 Anthropic 相同。
• 具有缺失、空或空白重放签名的 Claude 思考块会在 Converse 重放前被剥离。如果这使助手轮次变空，OpenClaw 会以非空的省略推理文本保持轮次形状。
• 必须剥离的较早仅思考助手轮次会被替换为非空的省略推理文本，以便 Converse 重放保持严格的轮次形状。
• 重放会过滤 OpenClaw 投递镜像和网关注入的助手轮次。
• 图像清理通过全局规则应用。

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

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

OpenRouter Gemini

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

OpenRouter Anthropic

• 当启用推理时，会从经过验证的 OpenRouter OpenAI 兼容的 Anthropic 模型负载中移除末尾的 assistant 预填充轮次， 以匹配直接 Anthropic 和 Cloudflare Anthropic 的重放行为。

其他所有内容

• 仅进行图像清理。

历史行为（2026.1.22 之前）¶

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

• 一个 transcript-sanitize 扩展 会在每次上下文构建时运行，并且可以：
• 修复工具使用/结果配对。
• 清理工具调用 ID（包括一种非严格模式，该模式保留 _/-）。
• runner 还执行了特定于提供商的清理，这造成了重复工作。
• 在提供商策略之外还发生了额外的修改，包括 在持久化之前从 assistant 文本中移除 <final> 标签、丢弃 空的 assistant 错误轮次，以及在工具调用后修剪 assistant 内容。

这种复杂性导致了跨提供商的回归问题（尤其是 openai-responses 的 call_id|fc_id 配对）。2026.1.22 的清理移除了 该扩展，将逻辑集中到 runner 中，并使 OpenAI 除图像清理外保持 无接触。

相关¶

• 会话管理
• 会话修剪