diff --git a/docs/zh-CN/providers/openrouter.md b/docs/zh-CN/providers/openrouter.md index 43bf27e73..171521c97 100644 --- a/docs/zh-CN/providers/openrouter.md +++ b/docs/zh-CN/providers/openrouter.md @@ -1,27 +1,27 @@ --- read_when: - - 你想为多个 LLM 使用一个 API 密钥 - - 你想在 OpenClaw 中通过 OpenRouter 运行模型 - - 你想使用 OpenRouter 进行图像生成 + - 你想为多个大语言模型使用一个 API 密钥 + - 你想要在 OpenClaw 中通过 OpenRouter 运行模型 + - 你想使用 OpenRouter 生成图像 - 你想使用 OpenRouter 进行视频生成 -summary: 在 OpenClaw 中使用 OpenRouter 的统一 API 访问多种模型 +summary: 在 OpenClaw 中使用 OpenRouter 的统一 API 访问多个模型 title: OpenRouter x-i18n: - generated_at: "2026-04-28T12:02:40Z" + generated_at: "2026-05-02T05:52:48Z" model: gpt-5.5 provider: openai - source_hash: 47206ce7279eb8a38f71b5c40d34646ad01df2cac25860b629951f9cec73270f + source_hash: f6f7c6f9c77e2a62866fdeaa65667d3871930be2ce22a638accdb8baa76220fd source_path: providers/openrouter.md workflow: 16 --- -OpenRouter 提供一个**统一 API**，可通过单个端点和 API key 将请求路由到许多模型。它与 OpenAI 兼容，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。 +OpenRouter 提供一个**统一 API**，可通过单一端点和 API 密钥将请求路由到许多模型。它与 OpenAI 兼容，因此大多数 OpenAI SDK 只需切换基础 URL 即可使用。 ## 入门指南 - - 在 [openrouter.ai/keys](https://openrouter.ai/keys) 创建 API key。 + + 在 [openrouter.ai/keys](https://openrouter.ai/keys) 创建 API 密钥。 ```bash @@ -29,7 +29,7 @@ OpenRouter 提供一个**统一 API**，可通过单个端点和 API key 将请 ``` - 新手引导默认使用 `openrouter/auto`。稍后选择一个具体模型： + 新手引导默认使用 `openrouter/auto`。之后可以选择一个具体模型： ```bash openclaw models set openrouter// @@ -54,7 +54,7 @@ OpenRouter 提供一个**统一 API**，可通过单个端点和 API key 将请 ## 模型引用 -模型引用遵循 `openrouter//` 模式。如需查看可用提供商和模型的完整列表，请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers)。 +模型引用遵循 `openrouter//` 模式。可用提供商和模型的完整列表请参见 [/concepts/model-providers](/zh-CN/concepts/model-providers)。 内置回退示例： @@ -62,11 +62,11 @@ OpenRouter 提供一个**统一 API**，可通过单个端点和 API key 将请 | 模型引用 | 说明 | | --------------------------------- | ---------------------------- | | `openrouter/auto` | OpenRouter 自动路由 | -| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 通过 MoonshotAI | +| `openrouter/moonshotai/kimi-k2.6` | 通过 MoonshotAI 使用 Kimi K2.6 | ## 图像生成 -OpenRouter 也可以支持 `image_generate` 工具。在 `agents.defaults.imageGenerationModel` 下使用 OpenRouter 图像模型： +OpenRouter 也可以作为 `image_generate` 工具的后端。在 `agents.defaults.imageGenerationModel` 下使用 OpenRouter 图像模型： ```json5 { @@ -82,11 +82,11 @@ OpenRouter 也可以支持 `image_generate` 工具。在 `agents.defaults.imageG } ``` -OpenClaw 会使用 `modalities: ["image", "text"]` 将图像请求发送到 OpenRouter 的 chat completions 图像 API。Gemini 图像模型会通过 OpenRouter 的 `image_config` 接收受支持的 `aspectRatio` 和 `resolution` 提示。对于较慢的 OpenRouter 图像模型，请使用 `agents.defaults.imageGenerationModel.timeoutMs`；`image_generate` 工具每次调用的 `timeoutMs` 参数仍然优先。 +OpenClaw 会使用 `modalities: ["image", "text"]` 将图像请求发送到 OpenRouter 的聊天补全图像 API。Gemini 图像模型通过 OpenRouter 的 `image_config` 接收受支持的 `aspectRatio` 和 `resolution` 提示。对于较慢的 OpenRouter 图像模型，请使用 `agents.defaults.imageGenerationModel.timeoutMs`；`image_generate` 工具每次调用的 `timeoutMs` 参数仍会优先。 ## 视频生成 -OpenRouter 也可以通过其异步 `/videos` API 支持 `video_generate` 工具。在 `agents.defaults.videoGenerationModel` 下使用 OpenRouter 视频模型： +OpenRouter 也可以通过其异步 `/videos` API 作为 `video_generate` 工具的后端。在 `agents.defaults.videoGenerationModel` 下使用 OpenRouter 视频模型： ```json5 { @@ -101,11 +101,11 @@ OpenRouter 也可以通过其异步 `/videos` API 支持 `video_generate` 工具 } ``` -OpenClaw 会向 OpenRouter 提交文本转视频和图像转视频作业，轮询返回的 `polling_url`，并从 OpenRouter 的 `unsigned_urls` 或已记录的作业内容端点下载完成的视频。默认情况下，参考图像会作为首帧/末帧图像发送；标记为 `reference_image` 的图像会作为 OpenRouter 输入引用发送。内置的 `google/veo-3.1-fast` 默认值声明当前支持 4/6/8 秒时长、`720P`/`1080P` 分辨率，以及 `16:9`/`9:16` 宽高比。OpenRouter 未注册视频转视频，因为上游视频生成 API 当前接受文本和图像引用。 +OpenClaw 会向 OpenRouter 提交文本转视频和图像转视频作业，轮询返回的 `polling_url`，并从 OpenRouter 的 `unsigned_urls` 或已记录的作业内容端点下载完成的视频。默认情况下，参考图像会作为首帧/末帧图像发送；标记为 `reference_image` 的图像会作为 OpenRouter 输入参考发送。内置的 `google/veo-3.1-fast` 默认值声明了当前支持的 4/6/8 秒时长、`720P`/`1080P` 分辨率，以及 `16:9`/`9:16` 宽高比。OpenRouter 未注册视频转视频，因为上游视频生成 API 目前接受文本和图像参考。 ## 文本转语音 -OpenRouter 也可以通过其 OpenAI 兼容的 `/audio/speech` 端点用作 TTS 提供商。 +OpenRouter 也可以通过其兼容 OpenAI 的 `/audio/speech` 端点用作 TTS 提供商。 ```json5 { @@ -125,49 +125,53 @@ OpenRouter 也可以通过其 OpenAI 兼容的 `/audio/speech` 端点用作 TTS } ``` -如果省略 `messages.tts.providers.openrouter.apiKey`，TTS 会复用 `models.providers.openrouter.apiKey`，然后再使用 `OPENROUTER_API_KEY`。 +如果省略 `messages.tts.providers.openrouter.apiKey`，TTS 会复用 `models.providers.openrouter.apiKey`，然后使用 `OPENROUTER_API_KEY`。 -## 身份验证和标头 +## 身份验证和请求头 -OpenRouter 底层使用带有你的 API key 的 Bearer token。 +OpenRouter 底层使用带有你的 API 密钥的 Bearer 令牌。 -在真实的 OpenRouter 请求（`https://openrouter.ai/api/v1`）中，OpenClaw 还会添加 OpenRouter 文档中说明的应用归因标头： +在真实的 OpenRouter 请求（`https://openrouter.ai/api/v1`）上，OpenClaw 还会添加 OpenRouter 文档中说明的应用归因请求头： -| 标头 | 值 | +| 请求头 | 值 | | ------------------------- | --------------------- | | `HTTP-Referer` | `https://openclaw.ai` | | `X-OpenRouter-Title` | `OpenClaw` | | `X-OpenRouter-Categories` | `cli-agent` | -如果你将 OpenRouter 提供商重新指向其他代理或 base URL，OpenClaw **不会**注入这些 OpenRouter 专用标头或 Anthropic 缓存标记。 +如果你将 OpenRouter 提供商重新指向其他代理或基础 URL，OpenClaw **不会**注入这些 OpenRouter 专用请求头或 Anthropic 缓存标记。 ## 高级配置 - 在已验证的 OpenRouter 路由上，Anthropic 模型引用会保留 OpenRouter 专用的 Anthropic `cache_control` 标记，OpenClaw 使用这些标记来更好地复用系统/开发者 prompt 块的 prompt 缓存。 + 在已验证的 OpenRouter 路由上，Anthropic 模型引用会保留 OpenRouter 专用的 Anthropic `cache_control` 标记，OpenClaw 使用这些标记来提升系统/开发者提示块的提示缓存复用。 + + + + 在已验证的 OpenRouter 路由上，启用推理的 Anthropic 模型引用会在请求到达 OpenRouter 之前丢弃尾随的助手预填充轮次，以匹配 Anthropic 对推理对话必须以用户轮次结束的要求。 - 在受支持的非 `auto` 路由上，OpenClaw 会将选定的思考级别映射到 OpenRouter 代理推理载荷。不受支持的模型提示和 `openrouter/auto` 会跳过该推理注入。Hunter Alpha 也会针对陈旧配置的模型引用跳过代理推理，因为 OpenRouter 可能会在该已退役路由的推理字段中返回最终答案文本。 + 在受支持的非 `auto` 路由上，OpenClaw 会将所选思考级别映射到 OpenRouter 代理推理载荷。不受支持的模型提示和 `openrouter/auto` 会跳过该推理注入。Hunter Alpha 也会对过期配置的模型引用跳过代理推理，因为 OpenRouter 可能会在该已停用路由的推理字段中返回最终答案文本。 - - OpenRouter 仍然通过代理式 OpenAI 兼容路径运行，因此不会转发原生仅 OpenAI 的请求整形，例如 `serviceTier`、Responses `store`、OpenAI 推理兼容载荷和 prompt 缓存提示。 + + OpenRouter 仍然会经过代理风格、兼容 OpenAI 的路径，因此不会转发原生仅 OpenAI 的请求塑形，例如 `serviceTier`、Responses `store`、OpenAI 推理兼容载荷和提示缓存提示。 - Gemini 支持的 OpenRouter 引用会停留在代理 Gemini 路径上：OpenClaw 会在那里保留 Gemini thought-signature 清理，但不会启用原生 Gemini 重放验证或 bootstrap 重写。 + Gemini 支持的 OpenRouter 引用会留在代理 Gemini 路径上：OpenClaw 会在那里保留 Gemini 思维签名清理，但不会启用原生 Gemini 重放验证或引导重写。 - 如果你在模型参数下传入 OpenRouter 提供商路由，OpenClaw 会在共享流包装器运行之前将其作为 OpenRouter 路由元数据转发。 + 如果你在模型参数下传递 OpenRouter 提供商路由，OpenClaw 会在共享流包装器运行之前将其作为 OpenRouter 路由元数据转发。 -## 相关 +## 相关内容 diff --git a/docs/zh-CN/reference/transcript-hygiene.md b/docs/zh-CN/reference/transcript-hygiene.md index b509f25e5..4215b2d00 100644 --- a/docs/zh-CN/reference/transcript-hygiene.md +++ b/docs/zh-CN/reference/transcript-hygiene.md @@ -3,57 +3,65 @@ read_when: - 你正在调试与对话记录结构相关的提供商请求拒绝问题 - 你正在更改会话记录清理或工具调用修复逻辑 - 你正在调查跨提供商的工具调用 ID 不匹配问题 -summary: 参考：提供商特定的会话记录清理与修复规则 -title: 对话记录整理规范 +summary: 参考：提供商特定的会话记录清理和修复规则 +title: 会话记录整理 x-i18n: - generated_at: "2026-04-28T19:51:46Z" + generated_at: "2026-05-02T05:52:52Z" model: gpt-5.5 provider: openai - source_hash: d95f065d87ce58019ff2e6cdd6801879404d3b4fa402d26fc6fed9d51966b0a1 + source_hash: 6976d4349e47954f49c9dbf300822013851b604ed665f4ab647c62025760a96c source_path: reference/transcript-hygiene.md workflow: 16 --- -OpenClaw 会在运行前（构建模型上下文）对转录记录应用**特定于提供商的修复**。其中大多数都是**内存中**调整，用于满足严格的提供商要求。单独的会话文件修复流程也可能在加载会话前重写已存储的 JSONL，方式是丢弃格式错误的 JSONL 行，或修复语法有效但已知会在重放期间被提供商拒绝的已持久化轮次。发生修复时，原始文件会在会话文件旁边备份。 +OpenClaw 会在运行前（构建模型上下文时）对对话记录应用**提供商特定修复**。其中大多数是**内存中**调整，用于满足严格的提供商要求。另一个单独的会话文件修复过程也可能在加载会话前重写已存储的 JSONL，方式可能是丢弃格式异常的 JSONL 行，或修复语法有效但已知会在 +提供商重放期间被拒绝的持久化轮次。发生修复时，原始文件会在 +会话文件旁边备份。 范围包括： -- 仅运行时提示上下文不进入用户可见的转录记录轮次 -- 工具调用 ID 清理 +- 仅运行时使用的提示上下文不会进入用户可见的对话记录轮次 +- 工具调用 id 清理 - 工具调用输入验证 - 工具结果配对修复 - 轮次验证 / 排序 - 思考签名清理 - Thinking 签名清理 - 图像载荷清理 -- 提供商重放前清理空白文本块 -- 用户输入来源标记（用于跨会话路由的提示） -- Bedrock Converse 重放的空 assistant 错误轮次修复 +- 提供商重放前的空白文本块清理 +- 用户输入来源标记（用于跨会话路由提示） +- Bedrock Converse 重放的空助手错误轮次修复 -如果你需要转录记录存储详情，请参阅： +如果你需要对话记录存储细节，请参阅： - [会话管理深度解析](/zh-CN/reference/session-management-compaction) --- -## 全局规则：运行时上下文不是用户转录记录 +## 全局规则：运行时上下文不是用户对话记录 -运行时/系统上下文可以添加到某个轮次的模型提示中，但它不是最终用户编写的内容。OpenClaw 会为 Gateway 网关回复、排队的后续消息、ACP、CLI 和嵌入式 Pi 运行保留一个单独面向转录记录的提示正文。已存储的可见用户轮次使用该转录记录正文，而不是运行时增强后的提示。 +可以为某个轮次将运行时/系统上下文添加到模型提示中，但它 +不是终端用户创作的内容。OpenClaw 会为 Gateway 网关回复、排队的后续消息、ACP、CLI 和嵌入式 Pi +运行保留单独的面向对话记录的 +提示正文。已存储的可见用户轮次会使用该对话记录正文，而不是 +运行时增强后的提示。 -对于已经持久化运行时包装器的旧版会话，Gateway 网关历史表面会在向 WebChat、TUI、REST 或 SSE 客户端返回消息前应用显示投影。 +对于已经持久化运行时包装器的旧版会话，Gateway 网关历史 +界面会在向 WebChat、 +TUI、REST 或 SSE 客户端返回消息前应用显示投影。 --- ## 运行位置 -所有转录记录卫生处理都集中在嵌入式运行器中： +所有对话记录清理都集中在嵌入式运行器中： - 策略选择：`src/agents/transcript-policy.ts` - 清理/修复应用：`src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` 该策略使用 `provider`、`modelApi` 和 `modelId` 来决定应用哪些处理。 -与转录记录卫生处理分开，会话文件会在加载前被修复（如有需要）： +与对话记录清理分开，会话文件会在加载前按需修复： - `src/agents/session-file-repair.ts` 中的 `repairSessionFileIfNeeded` - 从 `run/attempt.ts` 和 `compact.ts`（嵌入式运行器）调用 @@ -62,39 +70,52 @@ OpenClaw 会在运行前（构建模型上下文）对转录记录应用**特定 ## 全局规则：图像清理 -图像载荷始终会被清理，以防由于大小限制导致提供商端拒绝（对过大的 base64 图像进行缩放/重新压缩）。 +图像载荷始终会被清理，以防止因大小 +限制导致提供商端拒绝（缩小/重新压缩过大的 base64 图像）。 -这也有助于控制支持视觉的模型由图像驱动的 token 压力。较低的最大尺寸通常会减少 token 使用量；较高的尺寸会保留细节。 +这也有助于控制支持视觉的模型中由图像驱动的 token 压力。 +较低的最大尺寸通常会减少 token 使用量；较高的尺寸会保留细节。 实现： - `src/agents/pi-embedded-helpers/images.ts` 中的 `sanitizeSessionMessagesImages` - `src/agents/tool-images.ts` 中的 `sanitizeContentBlocksImages` - 最大图像边长可通过 `agents.defaults.imageMaxDimensionPx` 配置（默认值：`1200`）。 -- 当此流程遍历重放内容时，会移除空白文本块。变为空的 assistant 轮次会从重放副本中丢弃；变为空的用户和工具结果轮次会收到一个非空的已省略内容占位符。 +- 当此过程遍历重放内容时，会移除空白文本块。变为空的助手 + 轮次会从重放副本中丢弃；变为空的用户轮次和工具结果 + 轮次会收到一个非空的省略内容占位符。 --- -## 全局规则：格式错误的工具调用 +## 全局规则：格式异常的工具调用 -在构建模型上下文之前，会丢弃同时缺少 `input` 和 `arguments` 的 assistant 工具调用块。这样可以防止提供商因部分持久化的工具调用而拒绝（例如，在速率限制失败之后）。 +在构建模型上下文前，会丢弃同时缺少 `input` 和 `arguments` 的助手工具调用块。 +这可以防止提供商因部分 +持久化的工具调用而拒绝请求（例如在速率限制失败之后）。 实现： - `src/agents/session-transcript-repair.ts` 中的 `sanitizeToolCallInputs` -- 在 `src/agents/pi-embedded-runner/replay-history.ts` 的 `sanitizeSessionHistory` 中应用 +- 在 `src/agents/pi-embedded-runner/replay-history.ts` 中的 `sanitizeSessionHistory` 中应用 --- ## 全局规则：跨会话输入来源 -当智能体通过 `sessions_send`（包括智能体到智能体的回复/公告步骤）向另一个会话发送提示时，OpenClaw 会将创建的用户轮次持久化为： +当智能体通过 `sessions_send` 将提示发送到另一个会话时（包括 +智能体到智能体的回复/公告步骤），OpenClaw 会持久化创建的用户轮次，并包含： - `message.provenance.kind = "inter_session"` -OpenClaw 还会在路由后的提示文本前添加同一轮次的 `[Inter-session message ... isUser=false]` 标记，以便活动模型调用能区分外部会话输出和外部最终用户指令。可用时，此标记包含源会话、渠道和工具。为了提供商兼容性，转录记录仍使用 `role: "user"`，但可见文本和来源元数据都会将该轮次标记为跨会话数据。 +OpenClaw 还会在路由后的提示文本前，为同一轮次添加一个 `[Inter-session message ... isUser=false]` +标记，使当前模型调用能够区分 +来自其他会话的输出与外部终端用户指令。该标记会在可用时包含 +源会话、渠道和工具。为兼容提供商，对话记录仍使用 +`role: "user"`，但可见文本和来源 +元数据都会将该轮次标记为跨会话数据。 -在上下文重建期间，OpenClaw 会对仅具有来源元数据的较旧持久化跨会话用户轮次应用同一标记。 +在上下文重建期间，OpenClaw 会对仅具有来源元数据的旧持久化 +跨会话用户轮次应用相同标记。 --- @@ -102,75 +123,97 @@ OpenClaw 还会在路由后的提示文本前添加同一轮次的 `[Inter-sessi **OpenAI / OpenAI Codex** -- 仅进行图像清理。 -- 对 OpenAI Responses/Codex 转录记录，丢弃孤立的推理签名（没有后续内容块的独立推理项），并在模型路由切换后丢弃可重放的 OpenAI 推理。 -- 保留可重放的 OpenAI Responses 推理项载荷，包括加密的空摘要项，以便手动/WebSocket 重放保留与 assistant 输出项配对所需的 `rs_*` 状态。 -- 不进行工具调用 ID 清理。 -- 工具结果配对修复可能会移动真实匹配的输出，并为缺失的工具调用合成 Codex 风格的 `aborted` 输出。 +- 仅图像清理。 +- 对于 OpenAI Responses/Codex 对话记录，丢弃孤立的推理签名（没有后续内容块的独立推理项），并在模型路由切换后丢弃可重放的 OpenAI 推理。 +- 保留可重放的 OpenAI Responses 推理项载荷，包括加密的空摘要项，以便手动/WebSocket 重放保持必需的 `rs_*` 状态与助手输出项配对。 +- 不清理工具调用 id。 +- 工具结果配对修复可能会移动真实的匹配输出，并为缺失的工具调用合成 Codex 风格的 `aborted` 输出。 - 不进行轮次验证或重排序。 - 缺失的 OpenAI Responses 系列工具输出会被合成为 `aborted`，以匹配 Codex 重放规范化。 - 不剥离思考签名。 **OpenAI 兼容 Gemma 4** -- 历史 assistant thinking/reasoning 块会在重放前被剥离，以便本地 OpenAI 兼容 Gemma 4 服务器不会接收先前轮次的推理内容。 -- 当前同轮次工具调用延续会保留附加到工具调用的 assistant 推理块，直到工具结果已重放。 +- 历史助手思考/推理块会在重放前被剥离，避免本地 + OpenAI 兼容 Gemma 4 服务器接收前一轮的推理内容。 +- 当前同一轮次的工具调用续接会保留附加在工具调用上的助手推理块， + 直到工具结果已被重放。 **Google（Generative AI / Gemini CLI / Antigravity）** -- 工具调用 ID 清理：严格字母数字。 +- 工具调用 id 清理：严格字母数字。 - 工具结果配对修复和合成工具结果。 - 轮次验证（Gemini 风格的轮次交替）。 -- Google 轮次排序修复（如果历史以 assistant 开始，则前置一个很小的用户引导）。 -- Antigravity Claude：规范化 thinking 签名；丢弃未签名的 thinking 块。 +- Google 轮次排序修正（如果历史以助手开头，则前置一条极小的用户引导）。 +- Antigravity Claude：规范化 Thinking 签名；丢弃未签名的 Thinking 块。 **Anthropic / Minimax（Anthropic 兼容）** - 工具结果配对修复和合成工具结果。 - 轮次验证（合并连续用户轮次以满足严格交替）。 -- 启用 thinking 时，会从传出的 Anthropic Messages 载荷中剥离尾随的 assistant 预填充轮次，包括 Cloudflare AI Gateway 路由。 -- 在提供商转换前，会剥离缺失、为空或空白的重放签名的 thinking 块。如果这会使 assistant 轮次为空，OpenClaw 会使用非空的已省略推理文本保留轮次形状。 -- 必须剥离的较旧仅 thinking assistant 轮次会替换为非空的已省略推理文本，以便提供商适配器不会丢弃重放轮次。 +- 启用 Thinking 时，会从传出的 Anthropic Messages + 载荷中剥离尾随的助手预填充轮次，包括 Cloudflare AI Gateway 路由。 +- 缺失、为空或空白重放签名的 Thinking 块会在 + 提供商转换前被剥离。如果这使助手轮次变为空，OpenClaw 会使用 + 非空的已省略推理文本保留轮次形状。 +- 必须剥离的较旧纯 Thinking 助手轮次会被替换为 + 非空的已省略推理文本，以便提供商适配器不会丢弃重放 + 轮次。 **Amazon Bedrock（Converse API）** -- 空 assistant 流错误轮次会在重放前被修复为非空回退文本块。Bedrock Converse 会拒绝带有 `content: []` 的 assistant 消息，因此带有 `stopReason: "error"` 且内容为空的已持久化 assistant 轮次也会在加载前在磁盘上修复。 -- 仅包含空白文本块的 assistant 流错误轮次会从内存中的重放副本中丢弃，而不是重放无效的空白块。 -- 缺失、为空或空白的重放签名的 Claude thinking 块会在 Converse 重放前被剥离。如果这会使 assistant 轮次为空，OpenClaw 会使用非空的已省略推理文本保留轮次形状。 -- 必须剥离的较旧仅 thinking assistant 轮次会替换为非空的已省略推理文本，以便 Converse 重放保持严格轮次形状。 -- 重放会过滤 OpenClaw 投递镜像和 Gateway 网关注入的 assistant 轮次。 +- 空助手流错误轮次会在重放前修复为非空回退文本块。 + Bedrock Converse 会拒绝 `content: []` 的助手消息，因此 + 带有 `stopReason: "error"` 且内容为空的持久化助手轮次也会 + 在加载前在磁盘上修复。 +- 仅包含空白文本块的助手流错误轮次会从 + 内存中的重放副本中丢弃，而不是重放无效的空白块。 +- 缺失、为空或空白重放签名的 Claude Thinking 块会 + 在 Converse 重放前被剥离。如果这使助手轮次变为空，OpenClaw + 会使用非空的已省略推理文本保留轮次形状。 +- 必须剥离的较旧纯 Thinking 助手轮次会被替换为 + 非空的已省略推理文本，以便 Converse 重放保持严格的轮次形状。 +- 重放会过滤 OpenClaw 投递镜像和 Gateway 网关注入的助手轮次。 - 图像清理通过全局规则应用。 -**Mistral（包括基于模型 ID 的检测）** +**Mistral（包括基于模型 id 的检测）** -- 工具调用 ID 清理：strict9（字母数字，长度为 9）。 +- 工具调用 id 清理：strict9（字母数字，长度 9）。 **OpenRouter Gemini** - 思考签名清理：剥离非 base64 的 `thought_signature` 值（保留 base64）。 -**其他所有提供商** +**OpenRouter Anthropic** -- 仅进行图像清理。 +- 启用推理时，会从已验证的 OpenRouter + OpenAI 兼容 Anthropic 模型载荷中剥离尾随的助手预填充轮次，与 + 直接 Anthropic 和 Cloudflare Anthropic 重放行为一致。 + +**其他所有情况** + +- 仅图像清理。 --- ## 历史行为（2026.1.22 之前） -在 2026.1.22 版本之前，OpenClaw 应用了多层转录记录卫生处理： +在 2026.1.22 发布之前，OpenClaw 应用了多层对话记录清理： -- 一个 **transcript-sanitize 插件**会在每次上下文构建时运行，并且可以： +- 一个**对话记录清理插件**在每次上下文构建时运行，并且可以： - 修复工具使用/结果配对。 - - 清理工具调用 ID（包括保留 `_`/`-` 的非严格模式）。 -- 运行器还会执行特定于提供商的清理，这造成了重复工作。 -- 提供商策略之外还会发生额外变更，包括： - - 在持久化前从 assistant 文本中剥离 `` 标签。 - - 丢弃空的 assistant 错误轮次。 - - 在工具调用后截断 assistant 内容。 + - 清理工具调用 id（包括保留 `_`/`-` 的非严格模式）。 +- 运行器还执行提供商特定清理，这造成了重复工作。 +- 提供商策略之外还发生了其他变更，包括： + - 在持久化前从助手文本中剥离 `` 标签。 + - 丢弃空助手错误轮次。 + - 在工具调用后截断助手内容。 -这种复杂性导致了跨提供商回归（尤其是 `openai-responses` 的 `call_id|fc_id` 配对）。2026.1.22 清理移除了该插件，将逻辑集中到运行器中，并使 OpenAI 在图像清理之外保持**不改动**。 +这种复杂性导致了跨提供商回归（尤其是 `openai-responses` +`call_id|fc_id` 配对）。2026.1.22 清理移除了该插件，将 +逻辑集中到运行器中，并使 OpenAI 除图像清理外保持**不改动**。 ## 相关 - [会话管理](/zh-CN/concepts/session) -- [会话裁剪](/zh-CN/concepts/session-pruning) +- [会话修剪](/zh-CN/concepts/session-pruning)