diff --git a/docs/zh-CN/concepts/session-tool.md b/docs/zh-CN/concepts/session-tool.md index 68e4a256b..79c70485e 100644 --- a/docs/zh-CN/concepts/session-tool.md +++ b/docs/zh-CN/concepts/session-tool.md @@ -1,34 +1,39 @@ --- read_when: - - 你想了解智能体拥有哪些会话工具 - - 你想配置跨会话访问或生成子智能体 - - 你想检查状态或控制已生成的子智能体 -summary: 用于跨会话状态、记忆、消息传递和子智能体编排的 Agent 工具 + - 你想了解智能体有哪些会话工具 + - 你想配置跨会话访问或子智能体生成 + - 你想查看状态或控制已启动的子智能体 +summary: 用于跨会话状态、召回、消息传递和子智能体编排的智能体工具 title: 会话工具 x-i18n: - generated_at: "2026-04-27T13:49:01Z" - model: gpt-5.4 + generated_at: "2026-04-28T19:38:59Z" + model: gpt-5.5 provider: openai - source_hash: 19c42436ed7123cee35f397d672db1c2e0963cd1299e36d6fff41a56b880149b + source_hash: 0464116d42e271da12cbe90529e06e9f51605981be85b54bb5850ee9b8fb7824 source_path: concepts/session-tool.md - workflow: 15 + workflow: 16 --- -OpenClaw 为智能体提供了可跨会话工作、检查状态并编排子智能体的工具。 +OpenClaw 为智能体提供工具，用于跨会话工作、检查 Status，并 +编排子智能体。 ## 可用工具 -| 工具 | 作用 | +| 工具 | 作用 | | ------------------ | --------------------------------------------------------------------------- | -| `sessions_list` | 列出会话，并支持可选筛选条件（种类、标签、智能体、最近活动时间、预览） | -| `sessions_history` | 读取特定会话的转录记录 | -| `sessions_send` | 向另一个会话发送消息，并可选择等待回复 | -| `sessions_spawn` | 为后台工作生成一个隔离的子智能体会话 | -| `sessions_yield` | 结束当前回合，并等待后续的子智能体结果 | -| `subagents` | 列出、引导或终止此会话生成的子智能体 | -| `session_status` | 显示一个类似 `/status` 的状态卡片，并可选择为每个会话设置模型覆盖 | +| `sessions_list` | 列出会话，可选筛选条件包括类型、标签、智能体、最近活动、预览 | +| `sessions_history` | 读取特定会话的转录记录 | +| `sessions_send` | 向另一个会话发送消息，并可选择等待 | +| `sessions_spawn` | 生成一个隔离的子智能体会话用于后台工作 | +| `sessions_yield` | 结束当前轮次并等待后续子智能体结果 | +| `subagents` | 列出、引导或终止此会话生成的子智能体 | +| `session_status` | 显示类似 `/status` 的卡片，并可选择设置每会话模型覆盖项 | -这些工具仍受当前工具配置文件以及 allow/deny 策略的约束。`tools.profile: "coding"` 包含完整的会话编排工具集，包括 `sessions_spawn`、`sessions_yield` 和 `subagents`。`tools.profile: "messaging"` 包含跨会话消息传递工具（`sessions_list`、`sessions_history`、`sessions_send`、`session_status`），但不包含子智能体生成功能。若要保留 messaging 配置文件并仍允许原生委派，请添加： +这些工具仍受当前工具 profile 和允许/拒绝策略约束。`tools.profile: "coding"` 包含完整的会话编排 +工具集，包括 `sessions_spawn`、`sessions_yield` 和 `subagents`。 +`tools.profile: "messaging"` 包含跨会话消息工具 +（`sessions_list`、`sessions_history`、`sessions_send`、`session_status`），但 +不包含子智能体生成。若要保留 messaging profile，同时仍允许原生委托，请添加： ```json5 { @@ -39,90 +44,128 @@ OpenClaw 为智能体提供了可跨会话工作、检查状态并编排子智 } ``` -组、提供商、沙箱和每个智能体的策略仍可在配置文件阶段之后移除这些工具。使用受影响会话中的 `/tools` 检查实际生效的工具列表。 +组、提供商、沙箱和每智能体策略仍可在 profile 阶段之后移除这些工具。 +在受影响的会话中使用 `/tools` 检查实际生效的工具列表。 -## 列出并读取会话 +## 列出和读取会话 -`sessions_list` 返回会话及其 key、agentId、kind、channel、model、token 计数和时间戳。你可以按种类（`main`、`group`、`cron`、`hook`、`node`）、精确 `label`、精确 `agentId`、搜索文本或最近活动时间（`activeMinutes`）进行筛选。当你需要类似邮箱的分诊方式时，它还可以请求返回一个基于可见性范围生成的派生标题、最后一条消息的预览片段，或每行限定数量的最近消息。派生标题和预览只会为调用方在已配置的会话工具可见性策略下本就可见的会话生成，因此不相关的会话会保持隐藏。 +`sessions_list` 返回会话及其 key、agentId、类型、渠道、模型、 +token 计数和时间戳。可按类型（`main`、`group`、`cron`、`hook`、 +`node`）、精确 `label`、精确 `agentId`、搜索文本或最近活动 +（`activeMinutes`）筛选。当你需要类似邮箱的分诊时，它还可以请求 +可见性范围内派生的标题、最后一条消息预览片段，或每一行上有界的 +近期消息。派生标题和预览只会为调用方在已配置的会话工具可见性策略下 +已经可见的会话生成，因此无关会话会保持隐藏。 -`sessions_history` 获取特定会话的对话转录记录。默认情况下，工具结果会被排除——传入 `includeTools: true` 可查看它们。返回的视图会被有意限制并经过安全过滤： +`sessions_history` 获取特定会话的对话转录记录。 +默认情况下，工具结果会被排除——传入 `includeTools: true` 可查看它们。 +返回视图是刻意有界且经过安全过滤的： -- assistant 文本在回忆前会进行规范化处理： - - 会移除 thinking 标签 - - 会移除 `` / `` 脚手架块 - - 会移除纯文本工具调用 XML 载荷块，例如 `...`、`...`、`...` 和 `...`，也包括那些未能正常闭合的截断载荷 - - 会移除降级后的工具调用/结果脚手架，例如 `[Tool Call: ...]`、`[Tool Result ...]` 和 `[Historical context ...]` - - 会移除泄露的模型控制 token，例如 `<|assistant|>`、其他 ASCII `<|...|>` token 以及全角 `<｜...｜>` 变体 - - 会移除格式错误的 MiniMax 工具调用 XML，例如 `` / `` -- 返回前会对类似凭证/token 的文本进行脱敏 +- 助手文本会在召回前标准化： + - thinking 标签会被移除 + - `` / `` 脚手架块会被移除 + - 纯文本工具调用 XML 载荷块，例如 `...`、 + `...`、`...` 和 + `...` 会被移除，包括从未正常闭合的截断 + 载荷 + - 降级的工具调用/结果脚手架，例如 `[Tool Call: ...]`、 + `[Tool Result ...]` 和 `[Historical context ...]` 会被移除 + - 泄漏的模型控制 token，例如 `<|assistant|>`、其他 ASCII + `<|...|>` token，以及全角 `<｜...｜>` 变体会被移除 + - 格式异常的 MiniMax 工具调用 XML，例如 `` / + `` 会被移除 +- 类似凭证/token 的文本会在返回前被遮盖 - 长文本块会被截断 -- 超大历史记录可能会丢弃较旧的行，或用 `[sessions_history omitted: message too large]` 替换过大的行 -- 该工具会报告摘要标志，例如 `truncated`、`droppedMessages`、`contentTruncated`、`contentRedacted` 和 `bytes` +- 非常大的历史记录可能会丢弃较旧的行，或将超大的行替换为 + `[sessions_history omitted: message too large]` +- 该工具会报告摘要标志，例如 `truncated`、`droppedMessages`、 + `contentTruncated`、`contentRedacted` 和 `bytes` -这两个工具都接受 **session key**（如 `"main"`）或来自先前列表调用的 **session ID**。 +两个工具都接受 **会话 key**（如 `"main"`）或上一次列表调用中的 **会话 ID**。 -如果你需要精确到字节、完全一致的转录记录，请直接检查磁盘上的转录文件，而不要把 `sessions_history` 当作原始转储。 +如果你需要逐字节完全一致的转录记录，请检查磁盘上的转录文件， +而不是把 `sessions_history` 当作原始转储。 ## 发送跨会话消息 -`sessions_send` 会将消息投递到另一个会话，并可选择等待响应： +`sessions_send` 会向另一个会话投递消息，并可选择等待响应： -- **发后即忘：** 设置 `timeoutSeconds: 0` 以加入队列并立即返回。 +- **发送后不等待：** 设置 `timeoutSeconds: 0`，入队后立即返回。 - **等待回复：** 设置超时时间，并以内联方式获取响应。 -目标响应后，OpenClaw 可以运行一个**回传循环**，让多个智能体交替发送消息（最多 5 个回合）。目标智能体可以回复 `REPLY_SKIP` 以提前停止。 +消息和 A2A 后续回复会在接收方提示词中标记为会话间数据 +（`[Inter-session message ... isUser=false]`），并记录在转录来源中。 +接收智能体应将其视为由工具路由的数据，而不是最终用户直接撰写的指令。 -## 状态与编排辅助工具 +目标响应后，OpenClaw 可以运行 **回复回传循环**，让智能体交替发送消息 +（最多 5 轮）。目标智能体可以回复 `REPLY_SKIP` 以提前停止。 -`session_status` 是适用于当前会话或另一个可见会话的轻量级 `/status` 等效工具。它会报告使用情况、时间、模型/运行时状态，以及存在时关联的后台任务上下文。与 `/status` 一样，它可以从最新的转录 usage 条目中回填稀疏的 token/缓存计数，而 `model=default` 会清除每会话覆盖。对调用方当前会话请使用 `sessionKey="current"`；像 `openclaw-tui` 这样的可见客户端标签不是 session key。 +## Status 与编排辅助工具 -`sessions_yield` 会有意结束当前回合，以便你正在等待的后续事件能作为下一条消息到达。在生成子智能体后，如果你希望完成结果以下一条消息的形式到达，而不是构建轮询循环，就使用它。 +`session_status` 是当前会话或另一个可见会话的轻量级 `/status` 等效工具。 +它会报告使用情况、时间、模型/运行时状态，以及存在时的关联后台任务上下文。 +与 `/status` 一样，它可以从最新的转录用量条目回填稀疏的 token/cache 计数器，并且 +`model=default` 会清除每会话覆盖项。调用方当前会话请使用 +`sessionKey="current"`；可见客户端标签（如 `openclaw-tui`）不是会话 key。 -`subagents` 是针对已生成 OpenClaw 子智能体的控制平面辅助工具。它支持： +`sessions_yield` 会有意结束当前轮次，以便下一条消息可以是你正在等待的 +后续事件。在生成子智能体后，如果你希望完成结果作为下一条消息到达， +而不是构建轮询循环，请使用它。 -- `action: "list"` 用于检查活跃/最近运行 -- `action: "steer"` 用于向正在运行的子智能体发送后续指导 -- `action: "kill"` 用于停止一个子智能体或 `all` +`subagents` 是用于已生成 OpenClaw 子智能体的控制平面辅助工具。 +它支持： + +- `action: "list"` 用于检查活跃/近期运行 +- `action: "steer"` 用于向正在运行的子会话发送后续指导 +- `action: "kill"` 用于停止一个子会话或 `all` ## 生成子智能体 -`sessions_spawn` 默认会为后台任务创建一个隔离的会话。它始终是非阻塞的——会立即返回 `runId` 和 `childSessionKey`。 +`sessions_spawn` 默认会为后台任务创建一个隔离会话。 +它始终是非阻塞的——会立即返回 `runId` 和 +`childSessionKey`。 关键选项： - `runtime: "subagent"`（默认）或 `"acp"`，用于外部 harness 智能体。 -- 为子会话设置 `model` 和 `thinking` 覆盖。 -- `thread: true` 用于将生成绑定到聊天线程（Discord、Slack 等）。 -- `sandbox: "require"` 用于对该子会话强制启用沙箱隔离。 -- `context: "fork"` 适用于当子智能体需要当前请求者转录记录时的原生子智能体；如需一个干净的子会话，可省略该项或使用 `context: "isolated"`。 +- 子会话的 `model` 和 `thinking` 覆盖项。 +- `thread: true`，将生成绑定到聊天线程（Discord、Slack 等）。 +- `sandbox: "require"`，对子会话强制执行沙箱隔离。 +- `context: "fork"`，用于在子会话需要当前请求方转录记录时的原生子智能体； + 省略它或使用 `context: "isolated"` 可获得干净的子会话。 -默认的叶子子智能体不会获得会话工具。当 `maxSpawnDepth >= 2` 时，深度为 1 的编排型子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便它们管理自己的子智能体。叶子运行仍不会获得递归编排工具。 +默认叶子子智能体不会获得会话工具。当 +`maxSpawnDepth >= 2` 时，深度为 1 的编排型子智能体会额外获得 +`sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`， +以便它们管理自己的子会话。叶子运行仍不会获得递归编排工具。 -完成后，公告步骤会将结果发布到请求者的渠道。完成投递会在可用时保留绑定的线程/主题路由；如果完成来源仅标识了一个渠道，OpenClaw 仍可复用请求者会话中存储的路由（`lastChannel` / `lastTo`）进行直接投递。 +完成后，公告步骤会将结果发布到请求方的渠道。 +完成交付会在可用时保留绑定的线程/主题路由，并且如果完成来源只标识了一个渠道， +OpenClaw 仍可以复用请求方会话存储的路由（`lastChannel` / `lastTo`）进行直接交付。 -有关 ACP 特定行为，请参见 [ACP Agents](/zh-CN/tools/acp-agents)。 +关于 ACP 专属行为，请参阅 [ACP 智能体](/zh-CN/tools/acp-agents)。 ## 可见性 -会话工具带有作用域限制，以限制智能体可以看到的内容： +会话工具会按范围限制智能体可见的内容： -| 级别 | 范围 | +| 级别 | 范围 | | ------- | ---------------------------------------- | -| `self` | 仅当前会话 | -| `tree` | 当前会话 + 已生成的子智能体 | -| `agent` | 此智能体的所有会话 | -| `all` | 所有会话（若已配置，也包括跨智能体） | +| `self` | 仅当前会话 | +| `tree` | 当前会话 + 已生成的子智能体 | +| `agent` | 此智能体的所有会话 | +| `all` | 所有会话（如已配置，则跨智能体） | -默认值为 `tree`。无论配置如何，沙箱隔离会话都会被限制为 `tree`。 +默认值为 `tree`。无论配置如何，沙箱隔离的会话都会被限制为 `tree`。 ## 延伸阅读 -- [Session Management](/zh-CN/concepts/session) —— 路由、生命周期、维护 -- [ACP Agents](/zh-CN/tools/acp-agents) —— 外部 harness 生成 -- [Multi-agent](/zh-CN/concepts/multi-agent) —— 多智能体架构 -- [Gateway Configuration](/zh-CN/gateway/configuration) —— 会话工具配置项 +- [会话管理](/zh-CN/concepts/session)——路由、生命周期、维护 +- [ACP 智能体](/zh-CN/tools/acp-agents)——外部 harness 生成 +- [多智能体](/zh-CN/concepts/multi-agent)——多智能体架构 +- [Gateway 网关配置](/zh-CN/gateway/configuration)——会话工具配置旋钮 -## 相关内容 +## 相关 -- [Session management](/zh-CN/concepts/session) -- [Session pruning](/zh-CN/concepts/session-pruning) +- [会话管理](/zh-CN/concepts/session) +- [会话剪枝](/zh-CN/concepts/session-pruning) diff --git a/docs/zh-CN/reference/transcript-hygiene.md b/docs/zh-CN/reference/transcript-hygiene.md index 4ba18c35f..f1cbb888d 100644 --- a/docs/zh-CN/reference/transcript-hygiene.md +++ b/docs/zh-CN/reference/transcript-hygiene.md @@ -1,34 +1,35 @@ --- read_when: - - 你正在调试与转录内容结构相关的提供商请求拒绝问题 - - 你正在更改转录内容清理或工具调用修复逻辑 - - 你正在调查跨提供商的工具调用 ID 不匹配问题 -summary: 参考：特定提供商的转录清理和修复规则 -title: 转录内容卫生规范 + - 你正在调试与会话记录结构相关的提供商请求拒绝问题 + - 你正在更改转录清理或工具调用修复逻辑 + - 你正在调查不同提供商之间的工具调用 ID 不匹配问题 +summary: 参考：提供商特定的记录清理和修复规则 +title: 会话记录规范 x-i18n: - generated_at: "2026-04-27T23:00:15Z" - model: gpt-5.4 + generated_at: "2026-04-28T19:38:58Z" + model: gpt-5.5 provider: openai - source_hash: 32242fe22101e83906881fb66b89f2555cab8559f5f6f73308d94dec068c8088 + source_hash: 51459c719c6314b2980057d7e1e003e1598e8fe4a619c081aa25ce29200645a8 source_path: reference/transcript-hygiene.md - workflow: 15 + workflow: 16 --- -OpenClaw 会在运行前（构建模型上下文时）对转录内容应用**特定提供商的修复**。其中大多数是用于满足严格提供商要求的**内存中**调整。另有一个独立的会话文件修复过程，也可能在加载会话前重写已存储的 JSONL：要么丢弃格式错误的 JSONL 行，要么修复那些在语法上有效、但已知会在回放期间被提供商拒绝的持久化轮次。 -当发生修复时，原始文件会在会话文件旁边备份。 +OpenClaw 在运行前（构建模型上下文时）会对转录应用**特定于提供商的修复**。其中大多数是为了满足严格的提供商要求而使用的**内存中**调整。单独的会话文件修复过程也可能在加载会话之前重写已存储的 JSONL，要么丢弃格式错误的 JSONL 行，要么修复语法有效但已知会在重放期间被 +提供商拒绝的持久化轮次。发生修复时，原始文件会备份在 +会话文件旁边。 范围包括： -- 仅运行时的提示上下文，不进入用户可见的转录轮次 +- 仅运行时的提示上下文不会进入用户可见的转录轮次 - 工具调用 ID 清理 -- 工具调用输入校验 +- 工具调用输入验证 - 工具结果配对修复 -- 轮次校验 / 排序 -- 思考签名清理 -- thinking 签名清理 -- 图像负载清理 +- 轮次验证 / 排序 +- 思维签名清理 +- Thinking 签名清理 +- 图像载荷清理 - 用户输入来源标记（用于跨会话路由的提示） -- Bedrock Converse 回放中的空 assistant 错误轮次修复 +- Bedrock Converse 重放的空助手错误轮次修复 如果你需要转录存储细节，请参阅： @@ -36,24 +37,29 @@ OpenClaw 会在运行前（构建模型上下文时）对转录内容应用**特 --- -## 全局规则：运行时上下文不是用户转录内容 +## 全局规则：运行时上下文不是用户转录 -运行时 / system 上下文可以添加到某个轮次的模型提示中，但它不是最终用户创作的内容。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` +- 清理/修复应用：`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,10 +68,11 @@ OpenClaw 会在运行前（构建模型上下文时）对转录内容应用**特 ## 全局规则：图像清理 -图像负载始终会被清理，以防止因大小限制导致提供商侧拒绝（对过大的 base64 图像进行缩放 / 重新压缩）。 +图像载荷始终会被清理，以防因大小 +限制（缩小/重新压缩过大的 base64 图像）导致提供商端拒绝。 -这也有助于控制由图像驱动的 token 压力，适用于支持视觉的模型。 -较小的最大图像尺寸通常会减少 token 使用量；较大的尺寸则能保留更多细节。 +这也有助于控制支持视觉的模型中由图像驱动的 token 压力。 +较低的最大尺寸通常会减少 token 使用量；较高的尺寸会保留细节。 实现： @@ -77,8 +84,9 @@ OpenClaw 会在运行前（构建模型上下文时）对转录内容应用**特 ## 全局规则：格式错误的工具调用 -在构建模型上下文之前，缺少 `input` 和 `arguments` 的 assistant 工具调用块会被丢弃。 -这可以防止提供商因部分持久化的工具调用而拒绝请求（例如，在速率限制失败之后）。 +在构建模型上下文之前，会丢弃同时缺少 `input` 和 `arguments` 的助手工具调用块。 +这可以防止部分持久化的工具调用 +（例如，在速率限制失败之后）导致提供商拒绝。 实现： @@ -89,15 +97,20 @@ OpenClaw 会在运行前（构建模型上下文时）对转录内容应用**特 ## 全局规则：跨会话输入来源 -当一个智能体通过 `sessions_send` 将提示发送到另一个会话时（包括智能体到智能体的 reply / announce 步骤），OpenClaw 会将创建的用户轮次持久化，并附带： +当智能体通过 `sessions_send` 向另一个会话发送提示时（包括 +智能体到智能体的回复/公告步骤），OpenClaw 会将创建的用户轮次持久化为： - `message.provenance.kind = "inter_session"` -此元数据会在追加到转录内容时写入，不会改变角色 -（出于提供商兼容性，`role: "user"` 保持不变）。转录读取器可以据此避免将这些路由的内部提示视为最终用户创作的指令。 +OpenClaw 还会在被路由的提示文本前添加同一轮的 `[Inter-session message ... isUser=false]` +标记，让当前模型调用能够区分 +外部会话输出和外部最终用户指令。该标记会在可用时包含 +源会话、渠道和工具。为了提供商兼容性，转录仍使用 +`role: "user"`，但可见文本和来源 +元数据都会将该轮标记为跨会话数据。 -在重建上下文期间，OpenClaw 还会在内存中为这些用户轮次添加一个简短的 `[Inter-session message]` -标记，以便模型将它们与外部最终用户指令区分开来。 +在上下文重建期间，OpenClaw 会对只有来源元数据的旧持久化 +跨会话用户轮次应用同样的标记。 --- @@ -106,50 +119,62 @@ OpenClaw 会在运行前（构建模型上下文时）对转录内容应用**特 **OpenAI / OpenAI Codex** - 仅图像清理。 -- 对于 OpenAI Responses / Codex 转录内容，丢弃孤立的 reasoning 签名（后面没有内容块的独立 reasoning 条目），并在模型路由切换后丢弃可回放的 OpenAI reasoning。 -- 保留可回放的 OpenAI Responses reasoning 条目负载，包括加密的空摘要条目，以便手动 / WebSocket 回放保留与 assistant 输出条目配对所需的 `rs_*` 状态。 +- 对 OpenAI Responses/Codex 转录丢弃孤立的推理签名（没有后续内容块的独立推理项），并在模型路由切换后丢弃可重放的 OpenAI 推理。 +- 保留可重放的 OpenAI Responses 推理项载荷，包括加密的空摘要项，使手动/WebSocket 重放保留必需的 `rs_*` 状态，并与助手输出项配对。 - 不进行工具调用 ID 清理。 -- 工具结果配对修复可能会移动真正匹配的输出，并为缺失的工具调用合成 Codex 风格的 `aborted` 输出。 -- 不进行轮次校验或重排。 -- 缺失的 OpenAI Responses 系列工具输出会被合成为 `aborted`，以匹配 Codex 回放规范化。 -- 不移除 thought 签名。 +- 工具结果配对修复可能会移动真实匹配输出，并为缺失的工具调用合成 Codex 风格的 `aborted` 输出。 +- 不进行轮次验证或重新排序。 +- 缺失的 OpenAI Responses 系列工具输出会被合成为 `aborted`，以匹配 Codex 重放规范化。 +- 不剥离思维签名。 -**OpenAI-compatible Gemma 4** +**OpenAI 兼容的 Gemma 4** -- 在回放前移除历史 assistant thinking / reasoning 块，以便本地 OpenAI-compatible Gemma 4 服务器不会收到先前轮次的 reasoning 内容。 -- 当前同轮次的工具调用延续会保留附加到工具调用上的 assistant reasoning 块，直到工具结果已被回放。 +- 历史助手 thinking/reasoning 块会在重放前被剥离，使本地 + OpenAI 兼容的 Gemma 4 服务器不会收到先前轮次的推理内容。 +- 当前同一轮工具调用续接会保留附加到工具调用上的助手推理块， + 直到工具结果已被重放。 **Google（Generative AI / Gemini CLI / Antigravity）** - 工具调用 ID 清理：严格字母数字。 - 工具结果配对修复和合成工具结果。 -- 轮次校验（Gemini 风格的轮次交替）。 -- Google 轮次顺序修复（如果历史记录以 assistant 开始，则预置一个很小的 user 引导消息）。 +- 轮次验证（Gemini 风格的轮次交替）。 +- Google 轮次排序修正（如果历史记录以助手开头，则前置一个很小的用户引导）。 - Antigravity Claude：规范化 thinking 签名；丢弃未签名的 thinking 块。 -**Anthropic / Minimax（Anthropic-compatible）** +**Anthropic / Minimax（Anthropic 兼容）** - 工具结果配对修复和合成工具结果。 -- 轮次校验（合并连续的 user 轮次以满足严格交替要求）。 -- 启用 thinking 时，会从发往 Anthropic Messages 负载中移除尾部 assistant 预填充轮次，包括 Cloudflare AI Gateway 路由。 -- 缺少、为空或仅空白的回放签名的 thinking 块，会在提供商转换前被移除。如果这导致 assistant 轮次为空，OpenClaw 会使用非空的省略 reasoning 文本来保留轮次结构。 -- 必须被移除的旧版纯 thinking assistant 轮次，会被替换为非空的省略 reasoning 文本，以便提供商适配器不会丢弃该回放轮次。 +- 轮次验证（合并连续的用户轮次以满足严格交替）。 +- 启用 thinking 时，会从传出的 Anthropic Messages + 载荷中剥离尾随的助手预填充轮次，包括 Cloudflare AI Gateway 路由。 +- 在提供商转换前，会剥离缺失、为空或空白的重放签名的 thinking 块。如果这会清空一个助手轮次，OpenClaw 会用非空的已省略推理文本 + 保留轮次形状。 +- 必须被剥离的较旧仅 thinking 助手轮次会被替换为 + 非空的已省略推理文本，使提供商适配器不会丢弃重放 + 轮次。 **Amazon Bedrock（Converse API）** -- 空的 assistant 流式错误轮次会在回放前修复为非空的回退文本块。Bedrock Converse 会拒绝 `content: []` 的 assistant 消息，因此，已持久化且 `stopReason: "error"` 并带有空内容的 assistant 轮次，也会在加载前于磁盘上修复。 -- 缺少、为空或仅空白的回放签名的 Claude thinking 块，会在 Converse 回放前被移除。如果这导致 assistant 轮次为空，OpenClaw 会使用非空的省略 reasoning 文本来保留轮次结构。 -- 必须被移除的旧版纯 thinking assistant 轮次，会被替换为非空的省略 reasoning 文本，以便 Converse 回放保持严格的轮次结构。 -- 回放会过滤掉 OpenClaw 投递镜像和 Gateway 网关注入的 assistant 轮次。 -- 图像清理通过全局规则生效。 +- 空助手流错误轮次会在重放前修复为非空的后备文本块。 + Bedrock Converse 会拒绝带有 `content: []` 的助手消息，因此 + 带有 `stopReason: "error"` 且内容为空的持久化助手轮次也会 + 在加载前被写入磁盘修复。 +- 缺失、为空或空白的重放签名的 Claude thinking 块会 + 在 Converse 重放前被剥离。如果这会清空一个助手轮次，OpenClaw + 会用非空的已省略推理文本保留轮次形状。 +- 必须被剥离的较旧仅 thinking 助手轮次会被替换为 + 非空的已省略推理文本，使 Converse 重放保持严格的轮次形状。 +- 重放会过滤 OpenClaw 交付镜像和 Gateway 网关注入的助手轮次。 +- 图像清理通过全局规则应用。 -**Mistral（包括基于 model-id 的检测）** +**Mistral（包括基于模型 ID 的检测）** -- 工具调用 ID 清理：strict9（长度为 9 的字母数字）。 +- 工具调用 ID 清理：strict9（字母数字长度 9）。 **OpenRouter Gemini** -- thought 签名清理：移除非 base64 的 `thought_signature` 值（保留 base64）。 +- 思维签名清理：剥离非 base64 的 `thought_signature` 值（保留 base64）。 **其他所有情况** @@ -159,21 +184,22 @@ OpenClaw 会在运行前（构建模型上下文时）对转录内容应用**特 ## 历史行为（2026.1.22 之前） -在 2026.1.22 版本之前，OpenClaw 应用了多层转录内容卫生规范： +在 2026.1.22 版本之前，OpenClaw 会应用多层转录卫生处理： -- 一个**转录清理扩展**会在每次构建上下文时运行，并且可以： - - 修复工具使用 / 结果配对。 - - 清理工具调用 ID（包括保留 `_` / `-` 的非严格模式）。 -- 运行器也会执行特定提供商的清理，这造成了重复处理。 -- 提供商策略之外还存在额外的变更，包括： - - 在持久化前从 assistant 文本中移除 `` 标签。 - - 丢弃空的 assistant 错误轮次。 - - 在工具调用之后裁剪 assistant 内容。 +- 一个 **transcript-sanitize 插件**会在每次上下文构建时运行，并且可以： + - 修复工具使用/结果配对。 + - 清理工具调用 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)