跳转至

转录卫生

OpenClaw 在运行前(构建模型上下文时)会对转录应用提供商特定修复。这些是内存中的调整,用于满足严格的提供商要求。运行时转录状态保留在 SQLite 中;提供商特定的助手预填充剥离仅发生在构建出站载荷时。

范围包括:

  • 仅运行时的提示词上下文不进入用户可见的转录轮次
  • 工具调用 ID 净化
  • 工具调用输入验证
  • 工具结果配对修复
  • 轮次验证 / 排序
  • 思考签名清理
  • 思维签名清理
  • 图像载荷净化
  • 提供商重放前的空白文本块清理
  • 提供商重放前的不完整纯推理长度轮次清理
  • 用户输入来源标记(用于跨会话路由的提示词)
  • 提供商重放时移除空的助手错误轮次

如需转录存储详情,请参阅 会话管理深入解析。


失败尝试与恢复

纯文本助手错误会被缓冲,直到逻辑运行稳定。恢复会丢弃其部分文本,因为恢复后的回复会取代它。终止失败会持久化最后一次尝试的部分文本和错误。

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

全局规则:运行时上下文不是用户转录

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

压缩和保存的 CLI 会话笔记会排除保留的 openclaw.runtime-context 自定义消息类型,包括没有载体元数据的旧条目以及选择退出提供商重放的条目。提供商载体元数据控制重放权限;它不会使私有上下文有资格用于摘要或保存的笔记。现有转录在读取时会接受此过滤,而不会重写已存储的历史。

对于已经持久化运行时包装器的旧会话,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;嵌入式运行器不会修复或重新打开基于文件的运行时转录。


全局规则:图像净化

图像载荷始终会被净化,以防止因大小限制导致提供商端拒绝(缩小/重新压缩过大的 base64 图像)。当图像后端可用时,重放还会检查每个保留的图像是否可以解码。损坏的图像会变成 omitted image payload 备注;有效图像、周围文本和工具错误保持完整。成功回复不会修复原始存储的图像字节,因此失败的检查永远不会被记住,损坏图像在每次重放中保持省略。成功结果(原样验证或缩小后的替换)按内容摘要和限制在进程内缓存,上限为 16 MiB,因此后续轮次会复用它们,而不是再次解码相同的字节。 这还有助于控制具备视觉能力的模型中由图像驱动的 token 压力:较低的最大尺寸会降低 token 使用量,较高尺寸可保留细节。

实现:

  • src/agents/embedded-agent-helpers/images.ts 中的 sanitizeSessionMessagesImages
  • src/agents/tool-images.ts 中的 sanitizeContentBlocksImages
  • 最大图像边长可通过 agents.defaults.imageMaxDimensionPx 配置 (默认值:1200)
  • 在此遍历重放内容时,空白文本块会被移除。 变为空的助手轮次会被丢弃,除非它们拥有不透明的提供商重放状态;变为空的用户和工具结果轮次会收到一个非空的省略内容占位符。

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

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

当工具被禁用、移除或在当前目录中不可用时,已完成的调用/结果对仍保留在历史中。它们的名称仍需要有效语法;格式错误的调用、歧义配对和合成的缺失结果修复不授予此例外。重放已完成对不会为新调用宣告或授权该工具。

实现:

  • src/agents/session-transcript-repair.ts 中的 sanitizeToolCallInputs
  • 在 sanitizeSessionHistory 中应用 (src/agents/embedded-agent-runner/replay-history.ts)

全局规则:工具结果配对

实时运行器会重写重复先前调用的提供商 ID,在嵌入式运行尝试内的各响应之间保持 ID 唯一,包括压缩后。已持久化的旧转录仍使用基于出现次数的配对。

在重写提供商特定的调用 ID 之前,工具结果会先与每个助手轮次内的工具调用出现次数配对。提供商生成的 ID 可能在后续轮次中重复,因此紧邻重复调用的结果仍与该出现次数保持关联。只有当恰好有一个未解析的出现次数可以拥有该结果时,才会移动被错位的结果;歧义的多余结果会被丢弃,缺失的出现次数会收到合成的错误结果。

Synthetic missing results tell the model that the outcome is unknown: retry only read-only or idempotent operations, and verify current state before repeating an operation that may have had side effects. Responses-family transports retain their aborted placeholder. Neither placeholder proves that the tool did not run.

Implementation: sanitizeToolUseResultPairing in src/agents/session-transcript-repair.ts

When switching models, provider replay moves delayed asynchronous tool results next to their originating call before removing the source model's async metadata. Call and result IDs are trimmed before matching, so surrounding whitespace does not turn a real result into a synthetic missing-result error. This projection runs in packages/ai/src/transcript-transform.ts and leaves stored history intact.


全局规则:不完整或静默的仅推理轮次

当助手轮次在以下任一事件之后仅包含 thinking 或 redacted-thinking 内容时,会从内存重放副本中省略:

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

静默回复清理可防止隐藏推理在严格提供商重建对话时合并到后续的助手工具使用轮次中。

空长度轮次保持不变,带有可见文本、工具调用或未知内容块的长度轮次也保持不变。带有工具调用或未知内容块的静默回复轮次也保持不变。存储的转录不会被重写。

Implementation: normalizeAssistantReplayContent in 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_* 状态与助手输出项配对。
  • Node 轮次在返回已完成的助手消息之前,会规范化新的推理签名,因此实时续写和转录存储使用相同的签名字节。加密推理字节、可执行工具参数以及先前批准的历史记录保持不变。
  • 原生 ChatGPT Codex Responses 遵循 Codex 线路一致性,通过重放先前的 Responses 推理/消息/函数负载(不带先前项 ID)并保持会话 prompt_cache_key 来实现。
  • OpenAI Responses 系列重放保留规范的 call_*|fc_* 同模型推理对,但在 pi-ai 负载转换之前,确定性地规范化格式错误或过长的 call_id/函数调用项 ID。
  • 工具结果配对修复可能会移动真实匹配的输出,并为缺失的工具调用合成 Codex 风格的 aborted 输出。
  • 不进行轮次验证或重新排序;不剥离思考签名。

OpenAI 兼容 Chat Completions

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

Google (Generative AI / Gemini CLI / Antigravity)

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

Anthropic / Minimax (Anthropic 兼容)

  • 前缀绑定 Claude 模型(例如 Fable 5.1)会将其运行时上下文载体持久化为隐藏自定义消息,立即位于其用户轮次之后,并原地重放它们。旧用户轮次上的内联入站元数据也会被保留。此模型范围的仅追加策略包括 Bedrock、Vertex 和 Foundry 路由。代理核心在用户角色兼容消息上使用带类型的运行时上下文元数据标记载体。提供商适配器以协议支持的最高权限投影该消息;Anthropic 系列和外部插件适配器保留带标签的用户表示,而 OpenAI 兼容适配器使用 system 或 developer 权限。载体被排除在聊天历史和压缩摘要之外。其他 Claude 模型和 Anthropic 兼容模型保留瞬态载体,当没有内容绑定前缀时,避免对旧载体产生重复的缓存读取费用和上下文使用。
  • 工具结果配对修复和合成工具结果。
  • 轮次验证(合并连续用户轮次以满足严格交替)。对于 Messages API 上的前缀绑定模型,仅追加重放反而保持连续用户轮次分离,因此命令轮次后跟提示时,重放会使用与活动轮次签名所覆盖的相同逐轮时间戳;Bedrock Converse 仍然会合并它们。
  • 启用 thinking 时,会从发往 Anthropic Messages 的负载中剥离末尾的助手预填充轮次,包括 Cloudflare AI Gateway 路由。
  • 当会话已被压缩时,会在提供商重放前剥离压缩前的助手 thinking 签名。对于前缀绑定模型,压缩会更改已签名前缀(摘要内容替换原始内容),因此重放原始签名可能导致 Anthropic 以“Invalid signature in thinking block”拒绝请求。thinking 文本会作为未签名块保留,然后由以下规则处理。
  • 具有缺失、空或空白重放签名的 thinking 块会在提供商转换前被剥离。如果这使助手轮次变空,OpenClaw 会使用非空的 omitted-reasoning 文本保持轮次形状。
  • 必须剥离的较早仅 thinking 助手轮次会被替换为非空的 omitted-reasoning 文本,以便提供商适配器不会丢弃重放轮次。

Amazon Bedrock (Converse API)

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

Mistral(包括基于 model-id 的检测)

  • 工具调用 id 清理:strict9(字母数字,长度 9)。

OpenRouter Gemini

  • 思考签名清理:剥离非 base64 的 thought_signature 值(保留 base64)。

OpenRouter Anthropic

  • 当启用推理时,会从经过验证的 OpenRouter OpenAI 兼容 Anthropic 模型负载中剥离尾随的助手预填充轮次,以匹配直接 Anthropic 和 Cloudflare Anthropic 的重放行为。

其他所有

  • 仅图像清理。

历史行为(2026.1.22 之前)

在 2026.1.22 版本发布之前,OpenClaw 应用了多层转录清理:

  • 一个 transcript-sanitize 扩展 在每次上下文构建时运行,并且可以:
  • 修复工具使用/结果配对。
  • 清理工具调用 id(包括保留 _/- 的非严格模式)。
  • 运行器还执行了特定于提供商的清理,这造成了重复工作。
  • 在提供商策略之外还发生了其他变更,包括在持久化之前从助手文本中剥离 <final> 标签、丢弃空的助手错误轮次,以及修剪工具调用后的助手内容。

这种复杂性导致了跨提供商回归(尤其是 openai-responses 的 call_id|fc_id 配对)。2026.1.22 的清理移除了该扩展,将逻辑集中到运行器中,并使 OpenAI 除图像清理外保持 no-touch。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw