chore(i18n): refresh zh-CN translations

2026-04-28 03:24:45 +00:00 · 2026-04-28 03:24:45 +00:00 · 2569863f92
commit 2569863f92
parent a85e6cae47
5 changed files with 544 additions and 507 deletions
--- a/docs/zh-CN/automation/cron-jobs.md
+++ b/docs/zh-CN/automation/cron-jobs.md
@ -4,18 +4,18 @@ read_when:
    - 将外部触发器（webhook、Gmail）接入 OpenClaw
    - 为计划任务决定使用 heartbeat 还是 cron
 sidebarTitle: Scheduled tasks
-summary: Gateway 网关 调度器的计划任务、webhook 和 Gmail PubSub 触发器
+summary: Gateway 网关调度器的计划任务、webhook 和 Gmail PubSub 触发器
 title: 计划任务
 x-i18n:
-    generated_at: "2026-04-28T01:19:04Z"
+    generated_at: "2026-04-28T03:22:25Z"
    model: gpt-5.4
    provider: openai
-    source_hash: c1a044f3d76acebec45e631b6b5c3bffc753543afd21f8e1a16326d1c50aa50b
+    source_hash: df45c96f3e803ede8c4c2d24a9c3ae489967f052d0279235c17fef4759771dbb
    source_path: automation/cron-jobs.md
    workflow: 15
 ---

-Cron 是 Gateway 网关 的内置调度器。它会持久化作业，在正确时间唤醒智能体，并且可以将输出回传到聊天渠道或 webhook 端点。
+Cron 是 Gateway 网关的内置调度器。它会持久化作业，在正确的时间唤醒智能体，并且可以将输出回传到聊天渠道或 webhook 端点。

 ## 快速开始

@ -44,87 +44,87 @@ Cron 是 Gateway 网关 的内置调度器。它会持久化作业，在正确
  </Step>
 </Steps>

-## cron 的工作方式
+## cron 的工作原理

- Cron 在 **Gateway 网关** 进程内部运行（不在模型内部）。
- 作业定义会持久化到 `~/.openclaw/cron/jobs.json`，因此重启不会丢失计划。
- 运行时执行状态会持久化到它旁边的 `~/.openclaw/cron/jobs-state.json`。如果你在 git 中跟踪 cron 定义，请跟踪 `jobs.json`，并将 `jobs-state.json` 加入 gitignore。
- 在拆分之后，旧版 OpenClaw 仍然可以读取 `jobs.json`，但可能会把作业视为全新作业，因为运行时字段现在位于 `jobs-state.json` 中。
- 当 Gateway 网关 运行中或停止时编辑了 `jobs.json`，OpenClaw 会将变更后的调度字段与待运行的运行时槽位元数据进行比较，并清除过期的 `nextRunAtMs` 值。纯格式化或仅键顺序变化的重写会保留待运行槽位。
+- Cron 在 **Gateway 网关** 进程**内部**运行（而不是在模型内部）。
+- 作业定义会持久化到 `~/.openclaw/cron/jobs.json`，因此重启不会丢失调度。
+- 运行时执行状态会持久化到旁边的 `~/.openclaw/cron/jobs-state.json`。如果你用 git 跟踪 cron 定义，请跟踪 `jobs.json`，并将 `jobs-state.json` 加入 gitignore。
+- 在拆分之后，旧版 OpenClaw 可以读取 `jobs.json`，但可能会把作业视为全新作业，因为运行时字段现在位于 `jobs-state.json` 中。
+- 当 Gateway 网关运行中或停止时编辑了 `jobs.json`，OpenClaw 会将变更后的调度字段与待处理运行时槽位元数据进行比较，并清除过期的 `nextRunAtMs` 值。纯格式化或仅键顺序重写会保留待处理槽位。
 - 所有 cron 执行都会创建[后台任务](/zh-CN/automation/tasks)记录。
- 一次性作业（`--at`）默认会在成功后自动删除。
- 隔离的 cron 运行会在运行完成后，尽力关闭其 `cron:<jobId>` 会话所跟踪的浏览器标签页/进程，因此分离的浏览器自动化不会留下孤儿进程。
- 隔离的 cron 运行还会防止过时的确认性回复。如果第一个结果只是中间状态更新（如 `on it`、`pulling everything together` 以及类似提示），并且没有后代子智能体运行仍在负责最终答案，OpenClaw 会再提示一次以获取实际结果，然后再进行交付。
- 隔离的 cron 运行会优先使用来自嵌入式运行的结构化执行拒绝元数据，然后再回退到已知的最终摘要/输出标记，例如 `SYSTEM_RUN_DENIED` 和 `INVALID_REQUEST`，从而避免把被阻止的命令误报为绿色运行。
- 隔离的 cron 运行还会将运行级别的智能体失败视为作业错误，即使没有生成任何回复负载也一样，因此模型/提供商失败会增加错误计数并触发失败通知，而不是将作业清除为成功。
+- 一次性作业（`--at`）在成功后默认会自动删除。
+- 独立 cron 运行会尽力在运行完成时关闭其 `cron:<jobId>` 会话所跟踪的浏览器标签页/进程，因此分离的浏览器自动化不会留下孤儿进程。
+- 独立 cron 运行还会防止过时的确认回复。如果第一个结果只是临时状态更新（如 `on it`、`pulling everything together` 以及类似提示），并且没有任何后代子智能体运行仍负责最终答案，OpenClaw 会在交付前再次提示一次以获取实际结果。
+- 独立 cron 运行会优先使用来自嵌入式运行的结构化执行拒绝元数据，然后回退到已知的最终摘要/输出标记，例如 `SYSTEM_RUN_DENIED` 和 `INVALID_REQUEST`，这样被阻止的命令就不会被报告为绿色成功运行。
+- 即使没有生成任何回复负载，独立 cron 运行也会将运行级别的智能体失败视为作业错误，因此模型/提供商失败会增加错误计数并触发失败通知，而不是把作业标记为成功完成。

 <a id="maintenance"></a>

 <Note>
-cron 的任务对账会先以运行时归属为准，其次才依赖持久历史：只要 cron 运行时仍在跟踪某个作业处于运行中，该活动 cron 任务就保持存活，即使仍存在一条旧的子会话记录也是如此。一旦运行时不再拥有该作业，且 5 分钟宽限窗口已过，维护检查就会为匹配的 `cron:<jobId>:<startedAt>` 运行检查已持久化的运行日志和作业状态。如果该持久历史显示终态结果，任务账本就会据此完成；否则，由 Gateway 网关 拥有的维护逻辑可以将任务标记为 `lost`。离线 CLI 审计可以基于持久历史进行恢复，但它不会把自身空的进程内活动作业集合视为 Gateway 网关 拥有的 cron 运行已消失的证据。
+cron 的任务协调会优先依赖运行时归属，其次依赖持久化历史：只要 cron 运行时仍将某个作业标记为正在运行，该活跃 cron 任务就会保持活动状态，即使旧的子会话行仍然存在也是如此。一旦运行时不再拥有该作业，且 5 分钟宽限窗口到期，维护检查就会查看与之匹配的 `cron:<jobId>:<startedAt>` 运行的持久化运行日志和作业状态。如果该持久化历史显示了终止结果，任务账本就会据此完成；否则，由 Gateway 网关拥有的维护流程可以将任务标记为 `lost`。离线 CLI 审计可以根据持久化历史进行恢复，但它不会把自己在进程内空的活跃作业集视为 Gateway 网关拥有的 cron 运行已经消失的证据。
 </Note>

 ## 调度类型

-| 类型    | CLI 标志 | 说明                                                |
-| ------- | -------- | --------------------------------------------------- |
-| `at`    | `--at`   | 一次性时间戳（ISO 8601 或类似 `20m` 的相对时间）    |
-| `every` | `--every`| 固定间隔                                            |
-| `cron`  | `--cron` | 5 字段或 6 字段 cron 表达式，可选配 `--tz`          |
+| 类型    | CLI 标志 | 说明 |
+| ------- | --------- | ---- |
+| `at`    | `--at`    | 一次性时间戳（ISO 8601 或类似 `20m` 的相对时间） |
+| `every` | `--every` | 固定间隔 |
+| `cron`  | `--cron`  | 5 字段或 6 字段 cron 表达式，可选 `--tz` |

-不带时区的时间戳会被视为 UTC。添加 `--tz America/New_York` 可按本地挂钟时间进行调度。
+不带时区的时间戳会被视为 UTC。添加 `--tz America/New_York` 可按本地挂钟时间调度。

-每小时整点的循环表达式会自动错峰，最多延后 5 分钟，以减少负载尖峰。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定显式错峰窗口。
+按整点重复的表达式会自动错峰，最多延迟 5 分钟，以减少负载尖峰。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定明确的错峰窗口。

 ### day-of-month 和 day-of-week 使用 OR 逻辑

-Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当 day-of-month 和 day-of-week 字段都不是通配符时，croner 会在 **任一** 字段匹配时触发——而不是两个都匹配时才触发。这是标准的 Vixie cron 行为。
+Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当 day-of-month 和 day-of-week 字段都不是通配符时，croner 会在**任一**字段匹配时触发，而不是要求两者都匹配。这是标准的 Vixie cron 行为。

 ```
-# 预期："每月 15 日上午 9 点，且只有在星期一时"
-# 实际："每个 15 日上午 9 点，以及每个星期一上午 9 点"
+# 预期："每月 15 号上午 9 点，且仅当这一天是星期一"
+# 实际：  "每月每个 15 号上午 9 点，以及每个星期一上午 9 点"
 0 9 15 * 1
 ```

-这样每月会触发约 5–6 次，而不是 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件，请使用 Croner 的 `+` day-of-week 修饰符（`0 9 15 * +1`），或者只按一个字段调度，并在作业的提示词或命令中对另一个条件进行判断。
+这会每月触发约 5–6 次，而不是每月 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件都满足，请使用 Croner 的 `+` day-of-week 修饰符（`0 9 15 * +1`），或者按一个字段进行调度，并在作业的提示词或命令中对另一个字段进行保护判断。

 ## 执行样式

-| 样式           | `--session` 值      | 运行位置                 | 最适合                         |
-| -------------- | ------------------- | ------------------------ | ------------------------------ |
-| 主会话         | `main`              | 下一次 heartbeat 回合    | 提醒、系统事件                 |
-| 隔离           | `isolated`          | 专用 `cron:<jobId>`      | 报告、后台杂务                 |
-| 当前会话       | `current`           | 在创建时绑定             | 依赖上下文的周期性工作         |
-| 自定义会话     | `session:custom-id` | 持久命名会话             | 基于历史逐步构建的工作流       |
+| 样式 | `--session` 值 | 运行位置 | 最适合 |
+| --------------- | ------------------- | ------------------------ | ------------------------------- |
+| 主会话 | `main` | 下一个 heartbeat 回合 | 提醒、系统事件 |
+| 独立 | `isolated` | 专用 `cron:<jobId>` | 报告、后台杂务 |
+| 当前会话 | `current` | 在创建时绑定 | 依赖上下文的重复工作 |
+| 自定义会话 | `session:custom-id` | 持久命名会话 | 基于历史逐步构建的工作流 |

 <AccordionGroup>
-  <Accordion title="主会话 vs 隔离 vs 自定义">
-    **主会话** 作业会将系统事件加入队列，并可选择唤醒 heartbeat（`--wake now` 或 `--wake next-heartbeat`）。这些系统事件不会延长目标会话的每日/空闲重置新鲜度。**隔离** 作业会在一个全新会话中运行专用智能体回合。**自定义会话**（`session:xxx`）会跨运行保留上下文，从而支持诸如每日站会这类基于之前摘要持续推进的工作流。
+  <Accordion title="主会话、独立与自定义之间的区别">
+    **主会话**作业会将系统事件加入队列，并可选择唤醒 heartbeat（`--wake now` 或 `--wake next-heartbeat`）。这些系统事件不会延长目标会话的每日/空闲重置新鲜度。**独立**作业会在一个新的会话中运行专用的智能体回合。**自定义会话**（`session:xxx`）会在各次运行之间保留上下文，从而支持例如基于之前摘要构建的每日站会这类工作流。
  </Accordion>
-  <Accordion title="隔离作业中的“全新会话”是什么意思">
-    对于隔离作业来说，“全新会话”意味着每次运行都会有新的 transcript/session id。OpenClaw 可能会保留安全偏好，例如 thinking/fast/verbose 设置、标签以及用户显式选择的模型/凭证覆盖，但不会从旧的 cron 记录继承环境式会话上下文：渠道/群组路由、发送或排队策略、提权、来源或 ACP 运行时绑定。如果某个周期性作业需要有意构建在同一会话上下文上，请使用 `current` 或 `session:<id>`。
+  <Accordion title="对于独立作业，什么叫“全新会话”">
+    对于独立作业，“全新会话”意味着每次运行都会使用新的 transcript/session id。OpenClaw 可能会携带安全的偏好设置，例如 thinking/fast/verbose 设置、标签以及用户显式选择的模型/凭证覆盖，但不会继承来自旧 cron 行的环境会话上下文：渠道/群组路由、发送或排队策略、提权、来源或 ACP 运行时绑定。如果一个重复作业应当有意建立在相同的会话上下文之上，请使用 `current` 或 `session:<id>`。
  </Accordion>
  <Accordion title="运行时清理">
-    对于隔离作业，运行时拆除现在还包括对该 cron 会话执行尽力而为的浏览器清理。清理失败会被忽略，因此真正的 cron 结果仍然优先生效。
+    对于独立作业，运行时拆除现在包括对该 cron 会话的浏览器进行尽力清理。清理失败会被忽略，因此实际的 cron 结果仍然优先生效。

-    隔离的 cron 运行还会通过共享的运行时清理路径，处置为该作业创建的所有内置 MCP 运行时实例。这与主会话和自定义会话的 MCP 客户端清理方式一致，因此隔离的 cron 作业不会在多次运行之间泄漏 stdio 子进程或长生命周期的 MCP 连接。
+    独立 cron 运行还会通过共享的运行时清理路径，释放为该作业创建的任何内置 MCP 运行时实例。这与主会话和自定义会话的 MCP 客户端销毁方式一致，因此独立 cron 作业不会在多次运行之间泄漏 stdio 子进程或长期存活的 MCP 连接。

  </Accordion>
  <Accordion title="子智能体与 Discord 交付">
-    当隔离的 cron 运行编排子智能体时，交付也会优先采用最终后代输出，而不是过时的父级中间文本。如果后代仍在运行，OpenClaw 会抑制该不完整的父级更新，而不是将其发布出去。
+    当独立 cron 运行编排子智能体时，交付也会优先选择最终后代输出，而不是过时的父级临时文本。如果后代仍在运行，OpenClaw 会抑制该父级部分更新，而不是宣布它。

-    对于仅文本的 Discord announce 目标，OpenClaw 会只发送一次规范的最终 assistant 文本，而不是同时重放流式/中间文本负载和最终答案。媒体和结构化 Discord 负载仍会作为单独负载交付，以避免附件和组件被丢弃。
+    对于仅文本的 Discord 公告目标，OpenClaw 会只发送一次规范的最终助手文本，而不是重复发送流式/中间文本负载以及最终答案。媒体和结构化 Discord 负载仍会作为单独的负载发送，因此附件和组件不会丢失。

  </Accordion>
 </AccordionGroup>

-### 隔离作业的负载选项
+### 独立作业的负载选项

 <ParamField path="--message" type="string" required>
-  提示词文本（隔离模式必填）。
+  提示文本（独立作业必需）。
 </ParamField>
 <ParamField path="--model" type="string">
-  模型覆盖；使用为该作业选择的允许模型。
+  模型覆盖；使用为该作业选定且被允许的模型。
 </ParamField>
 <ParamField path="--thinking" type="string">
  thinking 级别覆盖。
@ -136,44 +136,44 @@ Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当 day-o
  限制作业可使用的工具，例如 `--tools exec,read`。
 </ParamField>

-`--model` 会将所选允许模型用作该作业的主模型。它不同于聊天会话中的 `/model` 覆盖：当作业主模型失败时，已配置的回退链仍会继续生效。如果请求的模型不被允许，cron 会记录一条警告，并回退到该作业的智能体/默认模型选择。
+`--model` 会将所选的允许模型用作该作业的主模型。它不同于聊天会话中的 `/model` 覆盖：当作业主模型失败时，已配置的回退链仍然适用。如果请求的模型不被允许或无法解析，cron 会以明确的验证错误使该次运行失败，而不是静默回退到该作业的智能体/默认模型选择。

-Cron 作业还可以携带负载级别的 `fallbacks`。存在时，该列表会替换该作业已配置的回退链。当你希望严格的 cron 运行只尝试所选模型时，可在作业负载/API 中使用 `fallbacks: []`。如果作业有 `--model`，但负载和配置中都没有 fallbacks，OpenClaw 会传递一个显式的空回退覆盖，这样智能体主模型就不会被作为隐藏的额外重试目标附加进去。
+Cron 作业还可以携带负载级别的 `fallbacks`。存在时，该列表会替换该作业已配置的回退链。当你希望严格的 cron 运行只尝试所选模型时，请在作业负载/API 中使用 `fallbacks: []`。如果某个作业有 `--model`，但既没有负载回退也没有已配置回退，OpenClaw 会传递一个显式的空回退覆盖，这样智能体主模型就不会作为隐藏的额外重试目标被附加进去。

-隔离作业的模型选择优先级如下：
+独立作业的模型选择优先级如下：

 1. Gmail hook 模型覆盖（当运行来自 Gmail 且该覆盖被允许时）
 2. 每个作业负载中的 `model`
 3. 用户选择并存储的 cron 会话模型覆盖
 4. 智能体/默认模型选择

-Fast 模式也会遵循已解析的实时选择。如果所选模型配置带有 `params.fastMode`，隔离的 cron 默认会使用它。已存储的会话 `fastMode` 覆盖在任意方向上都仍然优先生效。
+Fast mode 也会遵循解析后的实时选择。如果所选模型配置带有 `params.fastMode`，独立 cron 默认会使用它。无论方向如何，已存储的会话 `fastMode` 覆盖仍然优先于配置。

-如果隔离运行遇到实时模型切换交接，cron 会使用切换后的提供商/模型重试，并在重试前为当前运行持久化该实时选择。如果切换还携带了新的凭证配置文件，cron 也会为当前运行持久化该凭证配置文件覆盖。重试是有界的：初次尝试之后最多再进行 2 次切换重试，超过后 cron 会中止，而不是无限循环。
+如果独立运行遇到实时模型切换交接，cron 会使用切换后的提供商/模型重试，并在重试前为当前运行持久化该实时选择。当切换还携带新的凭证配置文件时，cron 也会为当前运行持久化该凭证配置文件覆盖。重试次数是有上限的：初次尝试后再加 2 次切换重试，cron 就会中止，而不是无限循环。

-在隔离的 cron 运行进入智能体运行器之前，OpenClaw 会检查已配置 `api: "ollama"` 和 `api: "openai-completions"` 且其 `baseUrl` 为 loopback、私有网络或 `.local` 的本地提供商端点是否可达。如果该端点不可用，此次运行会被记录为 `skipped`，并带有清晰的提供商/模型错误，而不是开始模型调用。该端点检查结果会缓存 5 分钟，因此多个到期作业如果使用同一个不可用的本地 Ollama、vLLM、SGLang 或 LM Studio 服务器，只会共享一次小型探测，而不会形成请求风暴。因提供商预检而被跳过的运行不会增加执行错误退避；如果你希望重复收到 skip 通知，请启用 `failureAlert.includeSkipped`。
+在独立 cron 运行进入智能体运行器之前，OpenClaw 会检查已配置 `api: "ollama"` 和 `api: "openai-completions"` 的提供商中，那些 `baseUrl` 为 loopback、私有网络或 `.local` 的可达本地提供商端点。如果该端点已关闭，这次运行会被记录为 `skipped`，并附带清晰的提供商/模型错误，而不是开始模型调用。该端点结果会缓存 5 分钟，因此多个到期作业如果使用同一个失效的本地 Ollama、vLLM、SGLang 或 LM Studio 服务器，将共享一次小型探测，而不会造成请求风暴。被提供商预检跳过的运行不会增加执行错误退避；当你希望对重复跳过发送通知时，可启用 `failureAlert.includeSkipped`。

 ## 交付与输出

-| 模式       | 结果                                                            |
-| ---------- | --------------------------------------------------------------- |
-| `announce` | 如果智能体没有发送，则回退交付最终文本到目标                    |
-| `webhook`  | 向某个 URL POST 已完成事件负载                                  |
-| `none`     | 不进行运行器回退交付                                            |
+| 模式 | 发生的情况 |
+| ---------- | ------------------------------------------------------------------- |
+| `announce` | 如果智能体没有发送，则回退交付最终文本到目标 |
+| `webhook`  | 将已完成事件负载 POST 到某个 URL |
+| `none`     | 不进行运行器回退交付 |

-使用 `--announce --channel telegram --to "-1001234567890"` 可交付到渠道。对于 Telegram forum topic，请使用 `-1001234567890:topic:123`；直接 RPC/配置调用方也可以把 `delivery.threadId` 作为字符串或数字传入。Slack/Discord/Mattermost 目标应使用显式前缀（`channel:<id>`、`user:<id>`）。Matrix 房间 ID 区分大小写；请使用精确的房间 ID，或使用来自 Matrix 的 `room:!room:server` 形式。
+使用 `--announce --channel telegram --to "-1001234567890"` 可交付到渠道。对于 Telegram forum topics，请使用 `-1001234567890:topic:123`；直接 RPC/配置调用方也可以将 `delivery.threadId` 作为字符串或数字传递。Slack/Discord/Mattermost 目标应使用显式前缀（`channel:<id>`、`user:<id>`）。Matrix 房间 ID 区分大小写；请使用精确的房间 ID，或使用来自 Matrix 的 `room:!room:server` 形式。

-对于隔离作业，聊天交付是共享的。如果存在聊天路由，即使作业使用 `--no-deliver`，智能体也可以使用 `message` 工具。如果智能体已发送到配置的/当前目标，OpenClaw 会跳过回退 announce。否则，`announce`、`webhook` 和 `none` 只控制运行器在智能体回合结束后如何处理最终回复。
+对于独立作业，聊天交付是共享的。如果存在聊天路由，即使作业使用 `--no-deliver`，智能体也可以使用 `message` 工具。如果智能体发送到了已配置/当前目标，OpenClaw 会跳过回退公告。否则，`announce`、`webhook` 和 `none` 仅控制运行器在智能体回合结束后如何处理最终回复。

-当智能体从活动聊天中创建隔离提醒时，OpenClaw 会为回退 announce 路由存储保留的实时交付目标。内部会话键可能是小写；当当前聊天上下文可用时，不会根据这些键重建提供商交付目标。
+当智能体从活动聊天中创建一个独立提醒时，OpenClaw 会为回退公告路由存储保留的实时交付目标。内部会话键可能是小写；当当前聊天上下文可用时，不会根据这些键重建提供商交付目标。

 失败通知遵循单独的目标路径：

- `cron.failureDestination` 为失败通知设置全局默认目标。
- `job.delivery.failureDestination` 可为单个作业覆盖该设置。
- 如果两者都未设置，且该作业已经通过 `announce` 交付，失败通知现在会回退到该主 announce 目标。
+- `cron.failureDestination` 为失败通知设置全局默认值。
+- `job.delivery.failureDestination` 按作业覆盖该设置。
+- 如果两者都未设置，且作业已经通过 `announce` 交付，则失败通知现在会回退到该主公告目标。
 - `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 的作业上受支持，除非主交付模式是 `webhook`。
- `failureAlert.includeSkipped: true` 可让单个作业或全局 cron 告警策略选择加入重复的 skipped 运行告警。Skipped 运行会维护单独的连续跳过计数器，因此不会影响执行错误退避。
+- `failureAlert.includeSkipped: true` 可让某个作业或全局 cron 告警策略启用重复的跳过运行告警。跳过运行会维护单独的连续跳过计数，因此不会影响执行错误退避。

 ## CLI 示例

@ -188,7 +188,7 @@ Fast 模式也会遵循已解析的实时选择。如果所选模型配置带有
      --wake now
    ```
  </Tab>
-  <Tab title="循环隔离作业">
+  <Tab title="重复的独立作业">
    ```bash
    openclaw cron add \
      --name "Morning brief" \
@ -218,7 +218,7 @@ Fast 模式也会遵循已解析的实时选择。如果所选模型配置带有

 ## Webhook

-Gateway 网关 可以暴露 HTTP webhook 端点以接收外部触发器。在配置中启用：
+Gateway 网关可以暴露 HTTP webhook 端点以接收外部触发器。在配置中启用：

 ```json5
 {
@ -230,14 +230,14 @@ Gateway 网关 可以暴露 HTTP webhook 端点以接收外部触发器。在配
 }
 ```

-### 认证
+### 身份验证

-每个请求都必须通过请求头携带 hook token：
+每个请求都必须通过请求头包含 hook token：

 - `Authorization: Bearer <token>`（推荐）
 - `x-openclaw-token: <token>`

-查询字符串中的 token 会被拒绝。
+不接受查询字符串中的 token。

 <AccordionGroup>
  <Accordion title="POST /hooks/wake">
@ -259,7 +259,7 @@ Gateway 网关 可以暴露 HTTP webhook 端点以接收外部触发器。在配

  </Accordion>
  <Accordion title="POST /hooks/agent">
-    运行一次隔离的智能体回合：
+    运行一个独立的智能体回合：

    ```bash
    curl -X POST http://127.0.0.1:18789/hooks/agent \
@ -268,10 +268,10 @@ Gateway 网关 可以暴露 HTTP webhook 端点以接收外部触发器。在配
      -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'
    ```

-    字段：`message`（必填）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`fallbacks`、`thinking`、`timeoutSeconds`。
+    字段：`message`（必需）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`fallbacks`、`thinking`、`timeoutSeconds`。

  </Accordion>
-  <Accordion title="映射 hooks（POST /hooks/<name>）">
+  <Accordion title="映射的 hook（POST /hooks/<name>）">
    自定义 hook 名称通过配置中的 `hooks.mappings` 解析。映射可以使用模板或代码转换，将任意负载转换为 `wake` 或 `agent` 动作。
  </Accordion>
 </AccordionGroup>
@ -279,11 +279,11 @@ Gateway 网关 可以暴露 HTTP webhook 端点以接收外部触发器。在配
 <Warning>
 将 hook 端点放在 loopback、tailnet 或受信任的反向代理之后。

- 使用专用 hook token；不要复用 gateway 凭证 token。
- 将 `hooks.path` 保持在专用子路径下；`/` 会被拒绝。
- 设置 `hooks.allowedAgentIds` 以限制显式 `agentId` 路由。
+- 使用专用的 hook token；不要复用 gateway 凭证 token。
+- 将 `hooks.path` 保持在专用子路径下；不接受 `/`。
+- 设置 `hooks.allowedAgentIds` 以限制显式的 `agentId` 路由。
 - 除非你确实需要由调用方选择会话，否则请保持 `hooks.allowRequestSessionKey=false`。
- 如果你启用了 `hooks.allowRequestSessionKey`，也请同时设置 `hooks.allowedSessionKeyPrefixes`，以限制允许的会话键形态。
+- 如果你启用了 `hooks.allowRequestSessionKey`，还应设置 `hooks.allowedSessionKeyPrefixes` 以限制允许的会话键形态。
 - 默认情况下，hook 负载会被安全边界包装。
  </Warning>

@ -292,7 +292,7 @@ Gateway 网关 可以暴露 HTTP webhook 端点以接收外部触发器。在配
 通过 Google PubSub 将 Gmail 收件箱触发器接入 OpenClaw。

 <Note>
-**前置条件：** `gcloud` CLI、`gog`（gogcli）、已启用 OpenClaw hooks，以及用于公共 HTTPS 端点的 Tailscale。
+**前置条件：**`gcloud` CLI、`gog`（gogcli）、已启用 OpenClaw hooks，以及用于公共 HTTPS 端点的 Tailscale。
 </Note>

 ### 向导设置（推荐）
@ -301,17 +301,17 @@ Gateway 网关 可以暴露 HTTP webhook 端点以接收外部触发器。在配
 openclaw webhooks gmail setup --account openclaw@gmail.com
 ```

-这会写入 `hooks.gmail` 配置，启用 Gmail preset，并为推送端点使用 Tailscale Funnel。
+这会写入 `hooks.gmail` 配置、启用 Gmail 预设，并为推送端点使用 Tailscale Funnel。

-### Gateway 网关 自动启动
+### Gateway 网关自动启动

-当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关 会在启动时运行 `gog gmail watch serve` 并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出。
+当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关会在启动时运行 `gog gmail watch serve` 并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出。

 ### 手动一次性设置

 <Steps>
  <Step title="选择 GCP 项目">
-    选择 `gog` 所用 OAuth 客户端所属的 GCP 项目：
+    选择 `gog` 使用的 OAuth 客户端所属的 GCP 项目：

    ```bash
    gcloud auth login
@ -320,7 +320,7 @@ openclaw webhooks gmail setup --account openclaw@gmail.com
    ```

  </Step>
-  <Step title="创建 topic 并授予 Gmail 推送访问权限">
+  <Step title="创建主题并授予 Gmail 推送访问权限">
    ```bash
    gcloud pubsub topics create gog-gmail-watch
    gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
@ -363,7 +363,7 @@ openclaw cron show <jobId>
 # 编辑作业
 openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

-# 立即强制运行一个作业
+# 立即强制运行作业
 openclaw cron run <jobId>

 # 仅在到期时运行
@ -383,12 +383,12 @@ openclaw cron edit <jobId> --clear-agent
 <Note>
 模型覆盖说明：

- `openclaw cron add|edit --model ...` 会更改作业选定的模型。
- 如果该模型被允许，那个精确的提供商/模型会传递到隔离智能体运行中。
- 如果不被允许，cron 会发出警告，并回退到作业的智能体/默认模型选择。
- 已配置的回退链仍会生效，因为 cron 的 `--model` 是作业主模型，而不是会话 `/model` 覆盖。
- 负载中的 `fallbacks` 会替换该作业已配置的 fallbacks；`fallbacks: []` 会禁用回退，使运行变为严格模式。
- 只有普通的 `--model` 且没有显式或已配置的回退列表时，不会静默回退到智能体主模型作为额外重试目标。
+- `openclaw cron add|edit --model ...` 会更改作业所选的模型。
+- 如果该模型被允许，那么这个精确的提供商/模型就会传递给独立智能体运行。
+- 如果它不被允许或无法解析，cron 会以明确的验证错误使该次运行失败。
+- 已配置的回退链仍然适用，因为 cron `--model` 是作业主模型，而不是会话 `/model` 覆盖。
+- 负载 `fallbacks` 会替换该作业已配置的回退；`fallbacks: []` 会禁用回退并使该次运行变为严格模式。
+- 仅有普通 `--model` 而没有显式或已配置回退列表时，不会静默落回到智能体主模型作为额外重试目标。
  </Note>

 ## 配置
@ -411,23 +411,23 @@ openclaw cron edit <jobId> --clear-agent
 }
 ```

-`maxConcurrentRuns` 同时限制计划的 cron 分发和隔离智能体回合执行。隔离的 cron 智能体回合在内部使用队列专用的 `cron-nested` 执行通道，因此提高该值可以让彼此独立的 cron LLM 运行并行推进，而不是仅启动其外层 cron 包装器。共享的非 cron `nested` 通道不会因该设置而变宽。
+`maxConcurrentRuns` 同时限制计划的 cron 分发和独立智能体回合执行。独立 cron 智能体回合在内部使用队列专用的 `cron-nested` 执行通道，因此提高此值可以让相互独立的 cron LLM 运行并行推进，而不是只启动它们的外层 cron 包装器。共享的非 cron `nested` 通道不会因该设置而扩展。

-运行时状态 sidecar 由 `cron.store` 推导而来：像 `~/clawd/cron/jobs.json` 这样的 `.json` 存储会使用 `~/clawd/cron/jobs-state.json`，而没有 `.json` 后缀的存储路径则会附加 `-state.json`。
+运行时状态 sidecar 由 `cron.store` 推导得出：像 `~/clawd/cron/jobs.json` 这样的 `.json` 存储会使用 `~/clawd/cron/jobs-state.json`，而没有 `.json` 后缀的存储路径则会附加 `-state.json`。

-如果你手动编辑 `jobs.json`，请不要将 `jobs-state.json` 纳入源码控制。OpenClaw 使用该 sidecar 存储待运行槽位、活动标记、最近运行元数据，以及用于告知调度器“外部编辑的作业何时需要新的 `nextRunAtMs`”的调度标识。
+如果你手动编辑 `jobs.json`，请将 `jobs-state.json` 排除在版本控制之外。OpenClaw 使用该 sidecar 保存待处理槽位、活跃标记、上次运行元数据以及调度标识，用于让调度器知道某个外部编辑过的作业何时需要新的 `nextRunAtMs`。

 禁用 cron：`cron.enabled: false` 或 `OPENCLAW_SKIP_CRON=1`。

 <AccordionGroup>
  <Accordion title="重试行为">
-    **一次性重试**：瞬时错误（限流、过载、网络、服务器错误）最多重试 3 次，并使用指数退避。永久错误会立即禁用。
+    **一次性重试**：瞬时错误（限流、过载、网络、服务器错误）最多重试 3 次，并采用指数退避。永久性错误会立即禁用。

-    **循环重试**：重试之间采用指数退避（30 秒到 60 分钟）。在下一次成功运行后，退避会重置。
+    **重复重试**：在重试之间采用指数退避（30 秒到 60 分钟）。在下一次成功运行后，退避会重置。

  </Accordion>
  <Accordion title="维护">
-    `cron.sessionRetention`（默认 `24h`）会清理隔离运行的会话条目。`cron.runLog.maxBytes` / `cron.runLog.keepLines` 会自动清理运行日志文件。
+    `cron.sessionRetention`（默认 `24h`）会清理独立运行的会话条目。`cron.runLog.maxBytes` / `cron.runLog.keepLines` 会自动清理运行日志文件。
  </Accordion>
 </AccordionGroup>

@ -449,22 +449,22 @@ openclaw doctor
 <AccordionGroup>
  <Accordion title="Cron 未触发">
    - 检查 `cron.enabled` 和 `OPENCLAW_SKIP_CRON` 环境变量。
-    - 确认 Gateway 网关 持续运行中。
-    - 对于 `cron` 调度，检查时区（`--tz`）与主机时区是否一致。
-    - 运行输出中的 `reason: not-due` 表示使用 `openclaw cron run <jobId> --due` 检查手动运行时，该作业尚未到期。
+    - 确认 Gateway 网关持续运行。
+    - 对于 `cron` 调度，验证时区（`--tz`）与主机时区是否一致。
+    - 运行输出中的 `reason: not-due` 表示手动运行是通过 `openclaw cron run <jobId> --due` 检查的，而作业尚未到期。
  </Accordion>
  <Accordion title="Cron 已触发但没有交付">
-    - 交付模式 `none` 表示不会有运行器回退发送。若聊天路由可用，智能体仍可直接使用 `message` 工具发送。
-    - 缺少/无效的交付目标（`channel`/`to`）意味着外发被跳过。
-    - 对于 Matrix，复制而来或旧作业里被小写化的 `delivery.to` 房间 ID 可能会失败，因为 Matrix 房间 ID 区分大小写。请将作业编辑为来自 Matrix 的精确 `!room:server` 或 `room:!room:server` 值。
+    - 交付模式 `none` 表示不应期待运行器回退发送。如果聊天路由可用，智能体仍可直接使用 `message` 工具发送。
+    - 缺少/无效的交付目标（`channel`/`to`）意味着出站发送被跳过。
+    - 对于 Matrix，复制来的或旧作业如果使用了小写的 `delivery.to` 房间 ID，可能会失败，因为 Matrix 房间 ID 区分大小写。请将作业编辑为来自 Matrix 的精确 `!room:server` 或 `room:!room:server` 值。
    - 渠道凭证错误（`unauthorized`、`Forbidden`）表示交付被凭证阻止。
-    - 如果隔离运行只返回静默 token（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接外发交付，也会抑制回退的排队摘要路径，因此不会向聊天回发任何内容。
-    - 如果智能体应当自行给用户发消息，请检查该作业是否有可用路由（`channel: "last"` 且存在之前聊天，或显式的渠道/目标）。
+    - 如果独立运行只返回静默 token（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接出站交付，也会抑制回退的队列摘要路径，因此不会向聊天回发任何内容。
+    - 如果智能体应当自行向用户发送消息，请检查作业是否具有可用路由（`channel: "last"` 且有先前聊天，或显式的渠道/目标）。
  </Accordion>
-  <Accordion title="Cron 或 heartbeat 看起来阻止了 /new-style rollover">
-    - 每日和空闲重置的新鲜度并不是基于 `updatedAt`；参见[会话管理](/zh-CN/concepts/session#session-lifecycle)。
-    - Cron 唤醒、heartbeat 运行、exec 通知和 gateway 记账都可能更新会话行以进行路由/状态记录，但它们不会延长 `sessionStartedAt` 或 `lastInteractionAt`。
-    - 对于这些字段出现之前创建的旧记录，只要 transcript JSONL 会话头文件仍可用，OpenClaw 就可以从中恢复 `sessionStartedAt`。对于没有 `lastInteractionAt` 的旧空闲记录，会使用恢复出的开始时间作为其空闲基线。
+  <Accordion title="Cron 或 heartbeat 似乎阻止了 /new 风格的滚动切换">
+    - 每日和空闲重置新鲜度并不是基于 `updatedAt`；请参见[会话管理](/zh-CN/concepts/session#session-lifecycle)。
+    - Cron 唤醒、heartbeat 运行、exec 通知和 gateway 记账可能会更新会话行以用于路由/状态，但它们不会延长 `sessionStartedAt` 或 `lastInteractionAt`。
+    - 对于这些字段出现之前创建的旧行，如果文件仍可用，OpenClaw 可以从 transcript JSONL 会话头中恢复 `sessionStartedAt`。没有 `lastInteractionAt` 的旧空闲行会使用该恢复出的开始时间作为空闲基线。
  </Accordion>
  <Accordion title="时区注意事项">
    - 不带 `--tz` 的 cron 会使用 gateway 主机时区。
--- a/docs/zh-CN/cli/cron.md
+++ b/docs/zh-CN/cli/cron.md
@ -1,24 +1,24 @@
 ---
 read_when:
-    - 你想要计划任务和唤醒功能
+    - 你想要定时任务和唤醒功能
    - 你正在调试 cron 执行和日志
-summary: '`openclaw cron` 的 CLI 参考（用于调度和运行后台作业）'
+summary: '`openclaw cron` 的 CLI 参考（调度并运行后台任务）'
 title: Cron
 x-i18n:
-    generated_at: "2026-04-28T01:18:57Z"
+    generated_at: "2026-04-28T03:22:25Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 35a9ba4c89c6022bda7e8c4dfb81d2efae7c541d73f4c4b36683fd128af0ba4d
+    source_hash: 15a67675caea0948e698f7c054da2662f4bcbcd8bdfe6c8c4d14b8f092076375
    source_path: cli/cron.md
    workflow: 15
 ---

 # `openclaw cron`

-管理 Gateway 网关调度器的 cron 作业。
+管理 Gateway 网关调度器的 cron 任务。

 <Tip>
-运行 `openclaw cron --help` 查看完整命令面。概念性指南请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)。
+运行 `openclaw cron --help` 查看完整命令面。概念指南请参见 [Cron 任务](/zh-CN/automation/cron-jobs)。
 </Tip>

 ## 会话
@ -28,21 +28,21 @@ x-i18n:
 <AccordionGroup>
  <Accordion title="会话键">
    - `main` 绑定到智能体的主会话。
-    - `isolated` 为每次运行创建全新的对话记录和会话 ID。
+    - `isolated` 为每次运行创建一个新的转录和会话 id。
    - `current` 绑定到创建时的活动会话。
-    - `session:<id>` 固定到显式的持久化会话键。
+    - `session:<id>` 固定到一个显式的持久会话键。
  </Accordion>
  <Accordion title="隔离会话语义">
-    隔离运行会重置环境对话上下文。渠道和群组路由、发送/排队策略、提权、来源以及 ACP 运行时绑定都会为新的运行重置。安全偏好以及用户显式选择的模型或凭证覆盖可以在多次运行之间继承。
+    隔离运行会重置环境对话上下文。渠道和群组路由、发送/排队策略、提权、来源以及 ACP 运行时绑定都会为新运行重置。安全偏好以及用户显式选择的模型或认证覆盖项可以在运行之间延续。
  </Accordion>
 </AccordionGroup>

 ## 传递

-`openclaw cron list` 和 `openclaw cron show <job-id>` 会预览解析后的传递路由。对于 `channel: "last"`，预览会显示该路由是从主会话还是当前会话解析而来，或者将会以故障关闭方式失败。
+`openclaw cron list` 和 `openclaw cron show <job-id>` 会预览解析后的传递路由。对于 `channel: "last"`，预览会显示该路由是从主会话还是当前会话解析而来，或者将会以失败关闭。

 <Note>
-隔离的 `cron add` 作业默认使用 `--announce` 传递。使用 `--no-deliver` 可将输出保留为内部可见。`--deliver` 仍然保留为 `--announce` 的已弃用别名。
+隔离的 `cron add` 任务默认使用 `--announce` 传递。使用 `--no-deliver` 可将输出保留为内部输出。`--deliver` 仍然保留为 `--announce` 的已弃用别名。
 </Note>

 ### 传递所有权
@ -50,103 +50,103 @@ x-i18n:
 隔离 cron 聊天传递由智能体和运行器共享负责：

 - 当聊天路由可用时，智能体可以使用 `message` 工具直接发送。
- 只有当智能体未直接发送到已解析目标时，`announce` 才会作为后备方式传递最终回复。
- `webhook` 会将完成后的负载发送到某个 URL。
- `none` 会禁用运行器后备传递。
+- 当智能体没有直接发送到已解析目标时，`announce` 会回退传递最终回复。
+- `webhook` 会将完成的负载 POST 到某个 URL。
+- `none` 会禁用运行器的回退传递。

-`--announce` 是针对最终回复的运行器后备传递。`--no-deliver` 会禁用该后备方式，但在聊天路由可用时不会移除智能体的 `message` 工具。
+`--announce` 是针对最终回复的运行器回退传递。`--no-deliver` 会禁用该回退，但不会在聊天路由可用时移除智能体的 `message` 工具。

-从活动聊天创建的提醒会保留实时聊天传递目标，用于后备 announce 传递。内部会话键可能是小写；不要将它们用作区分大小写的提供商 ID（例如 Matrix 房间 ID）的真实依据。
+从活动聊天创建的提醒会保留实时聊天传递目标，用于回退 announce 传递。内部会话键可能是小写形式；不要将它们作为区分大小写的提供商 ID（例如 Matrix 房间 ID）的真实依据。

 ### 失败传递

 失败通知按以下顺序解析：

-1. 作业上的 `delivery.failureDestination`。
+1. 任务上的 `delivery.failureDestination`。
 2. 全局 `cron.failureDestination`。
-3. 作业的主 announce 目标（当未设置显式失败目标时）。
+3. 任务的主 announce 目标（当未设置显式失败目标时）。

 <Note>
-主会话作业仅可在主传递模式为 `webhook` 时使用 `delivery.failureDestination`。隔离作业在所有模式下都接受它。
+主会话任务只有在主传递模式为 `webhook` 时才能使用 `delivery.failureDestination`。隔离任务在所有模式下都接受它。
 </Note>

-注意：隔离 cron 运行会将运行级别的智能体失败视为作业错误，即使没有生成回复负载也是如此，因此模型/提供商失败仍会增加错误计数器并触发失败通知。
+注意：隔离 cron 运行会将运行级智能体失败视为任务错误，即使没有生成回复负载也是如此，因此模型/提供商失败仍会增加错误计数并触发失败通知。

 ## 调度

-### 单次作业
+### 一次性任务

-`--at <datetime>` 会调度一次性运行。不带偏移量的日期时间默认按 UTC 处理，除非你同时传入 `--tz <iana>`，此时会按给定时区中的墙上时间进行解释。
+`--at <datetime>` 用于调度一次性运行。没有偏移量的日期时间默认按 UTC 处理，除非你同时传入 `--tz <iana>`，此时会按给定时区解释该墙上时钟时间。

 <Note>
-单次作业在成功后默认删除。使用 `--keep-after-run` 可保留它们。
+一次性任务默认在成功后删除。使用 `--keep-after-run` 可保留它们。
 </Note>

-### 周期性作业
+### 周期性任务

-周期性作业在连续出错后使用指数退避重试：30 秒、1 分钟、5 分钟、15 分钟、60 分钟。下一次成功运行后，调度会恢复正常。
+周期性任务在连续错误后使用指数重试退避：30 秒、1 分钟、5 分钟、15 分钟、60 分钟。下一次成功运行后，调度会恢复正常。

 跳过的运行会与执行错误分开跟踪。它们不会影响重试退避，但 `openclaw cron edit <job-id> --failure-alert-include-skipped` 可以让失败告警选择加入重复的跳过运行通知。

-对于以本地已配置模型提供商为目标的隔离作业，cron 会在启动智能体轮次之前运行轻量级提供商预检。`api: "ollama"` 的 loopback、私有网络和 `.local` 提供商会在 `/api/tags` 上探测；本地兼容 OpenAI 的提供商（如 vLLM、SGLang 和 LM Studio）会在 `/models` 上探测。如果端点不可达，该次运行会被记录为 `skipped`，并在后续计划中重试；匹配的失效端点会缓存 5 分钟，以避免大量作业反复冲击同一个本地服务器。
+对于面向本地已配置模型提供商的隔离任务，cron 会在启动智能体轮次前运行轻量级提供商预检。Loopback、私有网络和 `.local` 的 `api: "ollama"` 提供商会在 `/api/tags` 上探测；像 vLLM、SGLang 和 LM Studio 这样的本地 OpenAI 兼容提供商会在 `/models` 上探测。如果端点不可达，该次运行会被记录为 `skipped`，并在稍后的调度中重试；匹配的失效端点会缓存 5 分钟，以避免多个任务持续冲击同一台本地服务器。

-注意：cron 作业定义保存在 `jobs.json` 中，而待处理的运行时状态保存在 `jobs-state.json` 中。如果 `jobs.json` 被外部编辑，Gateway 网关会重新加载已变更的调度并清除陈旧的待处理槽位；仅格式化层面的重写不会清除该待处理槽位。
+注意：cron 任务定义保存在 `jobs.json` 中，而待处理运行时状态保存在 `jobs-state.json` 中。如果 `jobs.json` 被外部编辑，Gateway 网关会重新加载变更后的调度并清除陈旧的待处理槽位；仅格式化改写不会清除待处理槽位。

 ### 手动运行

-`openclaw cron run` 会在手动运行入队后立即返回。成功响应会包含 `{ ok: true, enqueued: true, runId }`。使用 `openclaw cron runs --id <job-id>` 来跟踪最终结果。
+`openclaw cron run` 会在手动运行进入队列后立即返回。成功响应包含 `{ ok: true, enqueued: true, runId }`。使用 `openclaw cron runs --id <job-id>` 来跟踪最终结果。

 <Note>
-`openclaw cron run <job-id>` 默认会强制运行。使用 `--due` 可保留旧的“仅在到期时运行”行为。
+`openclaw cron run <job-id>` 默认执行强制运行。使用 `--due` 可以保留旧的“仅在到期时运行”行为。
 </Note>

 ## 模型

-`cron add|edit --model <ref>` 为作业选择一个允许使用的模型。
+`cron add|edit --model <ref>` 为任务选择一个允许的模型。

 <Warning>
-如果该模型不被允许，cron 会发出警告，并回退到作业的智能体模型或默认模型选择。
+如果该模型不被允许或无法解析，cron 会以明确的校验错误使该次运行失败，而不是回退到任务的智能体或默认模型选择。
 </Warning>

-Cron 的 `--model` 是**作业主模型**，不是聊天会话的 `/model` 覆盖。这意味着：
+Cron 的 `--model` 是**任务主模型**，而不是聊天会话的 `/model` 覆盖。这意味着：

- 当所选作业模型失败时，已配置的模型回退仍然适用。
- 当存在每作业负载 `fallbacks` 时，它会替换已配置的回退列表。
- 空的每作业回退列表（作业负载/API 中的 `fallbacks: []`）会让 cron 运行变为严格模式。
- 当作业带有 `--model` 但未配置回退列表时，OpenClaw 会传递一个显式的空回退覆盖，以避免将智能体主模型作为隐藏的重试目标追加进去。
+- 当所选任务模型失败时，已配置的模型回退仍然适用。
+- 当存在每任务负载 `fallbacks` 时，它会替换已配置的回退列表。
+- 空的每任务回退列表（任务负载/API 中的 `fallbacks: []`）会让该 cron 运行变为严格模式。
+- 当任务设置了 `--model`，但没有配置回退列表时，OpenClaw 会传递一个显式的空回退覆盖，这样智能体主模型就不会作为隐藏重试目标被附加上去。

 ### 隔离 cron 模型优先级

 隔离 cron 按以下顺序解析活动模型：

 1. Gmail-hook 覆盖。
-2. 每作业 `--model`。
-3. 已存储的 cron 会话模型覆盖（当用户选定了某个模型时）。
-4. 智能体模型或默认模型选择。
+2. 每任务 `--model`。
+3. 已存储的 cron 会话模型覆盖（当用户选择过模型时）。
+4. 智能体或默认模型选择。

 ### 快速模式

-隔离 cron 的快速模式会遵循已解析的实时模型选择。默认会应用模型配置 `params.fastMode`，但已存储的会话 `fastMode` 覆盖仍然优先于配置。
+隔离 cron 快速模式遵循已解析的实时模型选择。模型配置 `params.fastMode` 默认生效，但已存储的会话 `fastMode` 覆盖仍然优先于配置。

 ### 实时模型切换重试

-如果隔离运行抛出 `LiveSessionModelSwitchError`，cron 会在重试前为当前运行持久化已切换的提供商和模型（以及存在时已切换的凭证配置文件覆盖）。外层重试循环在初始尝试后最多只允许两次切换重试，然后会中止，而不是无限循环。
+如果隔离运行抛出 `LiveSessionModelSwitchError`，cron 会在重试前为当前运行持久化切换后的提供商和模型（以及存在时切换后的认证配置覆盖）。外层重试循环在初始尝试后最多只允许两次切换重试，随后会中止，而不是无限循环。

 ## 运行输出与拒绝

-### 过时确认抑制
+### 过期确认抑制

-隔离 cron 轮次会抑制仅包含过时确认的回复。如果第一个结果只是中间状态更新，且最终答案并不是由某个后代子智能体运行负责，cron 会再次提示一次以获取真实结果，然后再进行传递。
+隔离 cron 轮次会抑制仅用于确认的过期回复。如果第一个结果只是中间状态更新，且没有后代子智能体运行负责最终答案，cron 会在传递前再次提示一次以获取真实结果。

 ### 静默 token 抑制

-如果隔离 cron 运行只返回静默 token（`NO_REPLY` 或 `no_reply`），cron 会同时抑制直接对外传递和后备排队摘要路径，因此不会向聊天回发任何内容。
+如果隔离 cron 运行仅返回静默 token（`NO_REPLY` 或 `no_reply`），cron 会同时抑制直接对外传递和回退排队摘要路径，因此不会向聊天回发任何内容。

 ### 结构化拒绝

-隔离 cron 运行会优先使用来自嵌入式运行的结构化执行拒绝元数据，然后再回退到最终输出中的已知拒绝标记，例如 `SYSTEM_RUN_DENIED`、`INVALID_REQUEST` 以及与审批绑定的拒绝措辞。
+隔离 cron 运行会优先使用嵌入式运行中的结构化执行拒绝元数据，然后再回退到最终输出中的已知拒绝标记，例如 `SYSTEM_RUN_DENIED`、`INVALID_REQUEST` 以及与审批绑定的拒绝短语。

-`cron list` 和运行历史会显示拒绝原因，而不是把被阻止的命令报告为 `ok`。
+`cron list` 和运行历史会显示拒绝原因，而不是将被阻止的命令报告为 `ok`。

 ## 保留

@ -155,10 +155,10 @@ Cron 的 `--model` 是**作业主模型**，不是聊天会话的 `/model` 覆
 - `cron.sessionRetention`（默认 `24h`）会清理已完成的隔离运行会话。
 - `cron.runLog.maxBytes` 和 `cron.runLog.keepLines` 会清理 `~/.openclaw/cron/runs/<jobId>.jsonl`。

-## 迁移旧作业
+## 迁移旧任务

 <Note>
-如果你有来自当前传递和存储格式之前的 cron 作业，请运行 `openclaw doctor --fix`。Doctor 会规范化旧版 cron 字段（`jobId`、`schedule.cron`、顶层传递字段，包括旧版 `threadId`、负载中的 `provider` 传递别名），并在配置了 `cron.webhook` 时，将简单的 `notify: true` webhook 后备作业迁移为显式 webhook 传递。
+如果你有早于当前传递和存储格式的 cron 任务，请运行 `openclaw doctor --fix`。Doctor 会规范化旧版 cron 字段（`jobId`、`schedule.cron`、顶层传递字段，包括旧版 `threadId`、负载 `provider` 传递别名），并在配置了 `cron.webhook` 时，将简单的 `notify: true` webhook 回退任务迁移为显式的 webhook 传递。
 </Note>

 ## 常见编辑
@ -169,37 +169,37 @@ Cron 的 `--model` 是**作业主模型**，不是聊天会话的 `/model` 覆
 openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
 ```

-为隔离作业禁用传递：
+为隔离任务禁用传递：

 ```bash
 openclaw cron edit <job-id> --no-deliver
 ```

-为隔离作业启用轻量级引导上下文：
+为隔离任务启用轻量级引导上下文：

 ```bash
 openclaw cron edit <job-id> --light-context
 ```

-向特定渠道进行 announce：
+向特定渠道 announce：

 ```bash
 openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
 ```

-创建带轻量级引导上下文的隔离作业：
+创建一个带有轻量级引导上下文的隔离任务：

 ```bash
 openclaw cron add \
-  --name "Lightweight morning brief" \
+  --name "轻量级晨间简报" \
  --cron "0 7 * * *" \
  --session isolated \
-  --message "Summarize overnight updates." \
+  --message "总结一夜之间的更新。" \
  --light-context \
  --no-deliver
 ```

-`--light-context` 仅适用于隔离的智能体轮次作业。对于 cron 运行，轻量模式会保持引导上下文为空，而不是注入完整的工作区引导集。
+`--light-context` 仅适用于隔离的智能体轮次任务。对于 cron 运行，轻量模式会保持引导上下文为空，而不是注入完整的工作区引导集合。

 ## 常见管理命令

@ -213,7 +213,7 @@ openclaw cron run <job-id> --due
 openclaw cron runs --id <job-id> --limit 50
 ```

-`cron runs` 条目包括传递诊断信息，其中包含预期的 cron 目标、已解析目标、message 工具发送、后备使用情况以及已传递状态。
+`cron runs` 条目包含传递诊断信息，包括预期的 cron 目标、已解析目标、message-tool 发送、回退使用情况以及已传递状态。

 智能体和会话重定向：

@ -224,7 +224,7 @@ openclaw cron edit <job-id> --session current
 openclaw cron edit <job-id> --session "session:daily-brief"
 ```

-传递微调：
+传递调整：

 ```bash
 openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
@ -236,4 +236,4 @@ openclaw cron edit <job-id> --no-deliver
 ## 相关内容

 - [CLI 参考](/zh-CN/cli)
- [计划任务](/zh-CN/automation/cron-jobs)
+- [定时任务](/zh-CN/automation/cron-jobs)
--- a/docs/zh-CN/concepts/memory-qmd.md
+++ b/docs/zh-CN/concepts/memory-qmd.md
@ -2,34 +2,34 @@
 read_when:
    - 你想将 QMD 设置为你的记忆后端
    - 你想要高级记忆功能，例如重排序或额外的索引路径
-summary: 本地优先的搜索 sidecar，支持 BM25、向量、重排序和查询扩展
+summary: 本地优先搜索边车，支持 BM25、向量、重排序和查询扩展
 title: QMD 记忆引擎
 x-i18n:
-    generated_at: "2026-04-27T13:49:05Z"
+    generated_at: "2026-04-28T03:22:25Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 1995a2b087c484595b0e0efed7a4ae3987b8fb3ac95e3c41bdf5335ba6240e73
+    source_hash: 09de0490a2584d1c7eeccd4ba8613d63ea4c69e62e5eb5a0492a8baa1a6c7eea
    source_path: concepts/memory-qmd.md
    workflow: 15
 ---

-[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索 sidecar，与 OpenClaw 并行运行。它将 BM25、向量搜索和重排序整合到一个二进制程序中，并且可以为你的工作区记忆文件之外的内容建立索引。
+[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索边车，与 OpenClaw 一起运行。它将 BM25、向量搜索和重排序整合到一个二进制文件中，并且可以为你的工作区记忆文件之外的内容建立索引。

-## 相比 builtin 它增加了什么
+## 相比内置引擎新增了什么

 - **重排序和查询扩展**，以获得更好的召回效果。
 - **为额外目录建立索引** —— 项目文档、团队笔记、磁盘上的任何内容。
 - **为会话转录建立索引** —— 回忆更早的对话。
- **完全本地运行** —— 配合可选的 `node-llama-cpp` 运行时包运行，并自动下载 GGUF 模型。
- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到 builtin 引擎。
+- **完全本地运行** —— 搭配可选的 `node-llama-cpp` 运行时包，并自动下载 GGUF 模型。
+- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到内置引擎。

 ## 入门指南

-### 前提条件
+### 前置条件

 - 安装 QMD：`npm install -g @tobilu/qmd` 或 `bun install -g @tobilu/qmd`
- 支持扩展的 SQLite 构建版本（在 macOS 上可使用 `brew install sqlite`）。
- QMD 必须在 Gateway 网关的 `PATH` 中。
+- 允许扩展的 SQLite 构建版本（在 macOS 上使用 `brew install sqlite`）。
+- QMD 必须位于 Gateway 网关的 `PATH` 中。
 - macOS 和 Linux 开箱即用。Windows 最佳支持方式是通过 WSL2。

 ### 启用
@ -42,46 +42,46 @@ x-i18n:
 }
 ```

-OpenClaw 会在 `~/.openclaw/agents/<agentId>/qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 生命周期 —— 集合、更新和嵌入运行都会由它处理。它会优先使用当前的 QMD collection 和 MCP 查询格式，但在需要时仍会回退到备用的 collection pattern 标志和较旧的 MCP 工具名称。启动时的协调过程还会在检测到存在同名旧版 QMD collection 时，将过期的受管集合重新创建为其规范模式。
+OpenClaw 会在 `~/.openclaw/agents/<agentId>/qmd/` 下创建一个自包含的 QMD 主目录，并自动管理边车生命周期 —— 集合、更新和嵌入运行都会由它代为处理。它优先使用当前的 QMD 集合和 MCP 查询形式，但在需要时仍会回退到替代的集合模式标志和较旧的 MCP 工具名称。启动时的协调还会在检测到存在同名旧版 QMD 集合时，将过时的托管集合重新创建为其规范模式。

-## sidecar 的工作方式
+## 边车如何工作

 - OpenClaw 会根据你的工作区记忆文件以及任何已配置的 `memory.qmd.paths` 创建集合，然后在启动时和周期性地运行 `qmd update`（默认每 5 分钟一次）。语义模式还会运行 `qmd embed`。
 - 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 不会作为根记忆文件建立索引。
 - 启动刷新会在后台运行，因此不会阻塞聊天启动。
 - 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。`search` 仅使用 BM25，因此 OpenClaw 会在该模式下跳过语义向量就绪探测和嵌入维护。如果某个模式失败，OpenClaw 会使用 `qmd query` 重试。
- 对于声明支持多 collection 过滤器的 QMD 版本，OpenClaw 会将同源集合分组，在一次 QMD 搜索调用中完成搜索。较旧的 QMD 版本则保留兼容的逐 collection 回退路径。
- 如果 QMD 完全失败，OpenClaw 会回退到 builtin SQLite 引擎。
+- 对于声明支持多集合过滤的 QMD 版本，OpenClaw 会将同源集合分组到一次 QMD 搜索调用中。较旧的 QMD 版本则继续使用兼容的逐集合回退方案。
+- 如果 QMD 完全失败，OpenClaw 会回退到内置的 SQLite 引擎。在打开失败后，重复的聊天轮次尝试会短暂退避，因此缺失的二进制文件或损坏的边车依赖不会造成重试风暴；`openclaw memory status` 和一次性 CLI 探测仍会直接重新检查 QMD。

 <Info>
-第一次搜索可能较慢 —— QMD 会在第一次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。
+第一次搜索可能会比较慢 —— QMD 会在首次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。
 </Info>

 ## 搜索性能与兼容性

-OpenClaw 会让 QMD 搜索路径同时兼容当前版和旧版 QMD 安装。
+OpenClaw 让 QMD 搜索路径同时兼容当前版和较旧版的 QMD 安装。

-在启动时，OpenClaw 会为每个管理器检查一次已安装的 QMD 帮助文本。如果该二进制程序声明支持多个 collection 过滤器，OpenClaw 就会用一条命令搜索所有同源集合：
+启动时，OpenClaw 会为每个管理器检查一次已安装的 QMD 帮助文本。如果该二进制文件声明支持多个集合过滤器，OpenClaw 就会通过一条命令搜索所有同源集合：

 ```bash
 qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main
 ```

-这样可以避免为每个持久记忆 collection 启动一个 QMD 子进程。会话转录集合仍保留在它们自己的源分组中，因此混合的 `memory` + `sessions` 搜索仍然能从两个来源获得结果多样化输入。
+这样可以避免为每个持久记忆集合都启动一个 QMD 子进程。会话转录集合仍保留在各自的源分组中，因此混合 `memory` + `sessions` 搜索仍能从这两类来源中获得结果多样化输入。

-较旧的 QMD 构建版本只接受一个 collection 过滤器。当 OpenClaw 检测到这类构建时，它会保留兼容路径，分别搜索每个 collection，然后再合并并去重结果。
+较旧的 QMD 构建仅接受一个集合过滤器。当 OpenClaw 检测到这类构建时，它会保留兼容路径，并分别搜索每个集合，然后再合并和去重结果。

-要手动检查已安装的契约，请运行：
+如需手动检查已安装的契约，请运行：

 ```bash
 qmd --help | grep -i collection
 ```

-当前的 QMD 帮助文本说明 collection 过滤器可以针对一个或多个集合。旧版帮助通常只描述单个 collection。
+当前的 QMD 帮助文本会说明集合过滤器可以定位一个或多个集合。较旧版本的帮助文本通常只描述单个集合。

 ## 模型覆盖

-QMD 模型环境变量会从 Gateway 网关进程原样透传，因此你可以全局调整 QMD，而无需添加新的 OpenClaw 配置：
+QMD 模型环境变量会从 Gateway 网关进程原样透传，因此你可以在不新增 OpenClaw 配置的情况下全局调整 QMD：

 ```bash
 export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
@ -93,7 +93,7 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"

 ## 为额外路径建立索引

-将 QMD 指向其他目录，使其可搜索：
+让 QMD 指向其他目录，使它们也可被搜索：

 ```json5
 {
@ -106,11 +106,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
 }
 ```

-来自额外路径的片段会在搜索结果中显示为 `qmd/<collection>/<relative-path>`。`memory_get` 能识别这个前缀，并从正确的 collection 根目录读取内容。
+来自额外路径的片段会在搜索结果中显示为 `qmd/<collection>/<relative-path>`。`memory_get` 能识别此前缀，并从正确的集合根目录读取内容。

 ## 为会话转录建立索引

-启用会话索引，以便回忆更早的对话：
+启用会话索引以回忆更早的对话：

 ```json5
 {
@ -123,11 +123,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
 }
 ```

-转录内容会以净化后的 User/Assistant 轮次导出到专用的 QMD collection 中，路径为 `~/.openclaw/agents/<id>/qmd/sessions/`。
+转录内容会作为已清理的用户/助手轮次导出到专用的 QMD 集合中，路径位于 `~/.openclaw/agents/<id>/qmd/sessions/`。

 ## 搜索范围

-默认情况下，QMD 搜索结果会显示在私信和渠道会话中（不包括群组）。可通过配置 `memory.qmd.scope` 来更改：
+默认情况下，QMD 搜索结果会显示在私信和渠道会话中（不包括群组）。可配置 `memory.qmd.scope` 来更改此行为：

 ```json5
 {
@ -142,11 +142,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
 }
 ```

-当 scope 拒绝搜索时，OpenClaw 会记录一条警告日志，其中包含推导出的渠道和聊天类型，以便更容易调试空结果问题。
+当范围规则拒绝搜索时，OpenClaw 会记录一条包含推导出的渠道和聊天类型的警告，以便更容易调试空结果。

 ## 引用

-当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含 `Source: <path#line>` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍会在内部将路径传递给智能体。
+当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含一个 `Source: <path#line>` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍会在内部将路径传递给智能体。

 ## 何时使用

@ -154,17 +154,18 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"

 - 通过重排序获得更高质量的结果。
 - 搜索工作区之外的项目文档或笔记。
- 回忆过往会话对话。
- 完全本地搜索，无需 API 密钥。
+- 回忆过去的会话对话。
+- 完全本地的搜索，无需 API 密钥。

-对于更简单的设置，[builtin 引擎](/zh-CN/concepts/memory-builtin) 在无需额外依赖的情况下也能很好地工作。
+对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在不增加额外依赖的情况下也能很好地工作。

 ## 故障排除

-**找不到 QMD？** 请确保该二进制程序位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建一个符号链接：
+**找不到 QMD？** 请确认该二进制文件位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建一个符号链接：
 `sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`。

-如果 `qmd --version` 在你的 shell 中可以正常运行，但 OpenClaw 仍然报告 `spawn qmd ENOENT`，则 Gateway 网关进程很可能使用了与你的交互式 shell 不同的 `PATH`。请显式固定该二进制路径：
+如果 `qmd --version` 在你的 shell 中可以运行，但 OpenClaw 仍然报告
+`spawn qmd ENOENT`，则 Gateway 网关进程很可能使用了与你的交互式 shell 不同的 `PATH`。请显式固定该二进制文件：

 ```json5
 {
@ -177,29 +178,32 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
 }
 ```

-在安装了 QMD 的环境中使用 `command -v qmd`，然后再通过 `openclaw memory status --deep` 重新检查。
+在安装了 QMD 的环境中使用 `command -v qmd`，然后通过 `openclaw memory status --deep` 重新检查。

-**第一次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录，通过 `qmd query "test"` 进行预热。
+**第一次搜索非常慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录，通过 `qmd query "test"` 进行预热。

-**搜索期间出现很多 QMD 子进程？** 如果可能，请升级 QMD。只有当已安装的 QMD 声明支持多个 `-c` 过滤器时，OpenClaw 才会对同源多 collection 搜索使用单个进程；否则，为了保证正确性，它会保留较旧的逐 collection 回退路径。
+**搜索时出现很多 QMD 子进程？** 如果可能，请更新 QMD。只有当已安装的 QMD 声明支持多个 `-c` 过滤器时，OpenClaw 才会对同源多集合搜索使用单个进程；否则它会保留较旧的逐集合回退方案，以确保正确性。

-**仅 BM25 的 QMD 仍在尝试构建 llama.cpp？** 设置 `memory.qmd.searchMode = "search"`。OpenClaw 会将该模式视为纯词法搜索，不会运行 QMD 向量状态探测或嵌入维护，并将语义就绪检查留给 `vsearch` 或 `query` 配置。
+**仅 BM25 的 QMD 仍在尝试构建 llama.cpp？** 请设置
+`memory.qmd.searchMode = "search"`。OpenClaw 会将该模式视为纯词法搜索，不会运行 QMD 向量状态探测或嵌入维护，而是将语义就绪检查留给 `vsearch` 或 `query` 配置。

-**搜索超时？** 增加 `memory.qmd.limits.timeoutMs`（默认：4000ms）。对于较慢的硬件，可设置为 `120000`。
+**搜索超时？** 请增大 `memory.qmd.limits.timeoutMs`（默认：4000ms）。
+对于较慢的硬件，可将其设为 `120000`。

-**群聊中结果为空？** 检查 `memory.qmd.scope` —— 默认仅允许私信和渠道会话。
+**群聊中结果为空？** 请检查 `memory.qmd.scope` —— 默认只允许私信和渠道会话。

-**根记忆搜索突然变得过宽？** 重启 Gateway 网关，或等待下一次启动协调。OpenClaw 在检测到同名冲突时，会将过期的受管集合重新创建为规范的 `MEMORY.md` 和 `memory/` 模式。
+**根记忆搜索突然变得过于宽泛？** 请重启 Gateway 网关或等待下一次启动协调。OpenClaw 在检测到同名冲突时，会将过时的托管集合重新创建回规范的 `MEMORY.md` 和 `memory/` 模式。

-**工作区可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？** QMD 遍历当前遵循底层 QMD 扫描器的行为，而不是 OpenClaw builtin 的符号链接规则。在 QMD 暴露出防循环遍历或显式排除控制之前，请将临时 monorepo 检出保存在 `.tmp/` 之类的隐藏目录下，或放在已索引 QMD 根目录之外。
+**工作区可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？**
+QMD 当前的遍历行为遵循底层 QMD 扫描器的行为，而不是 OpenClaw 内置的符号链接规则。请将临时 monorepo 检出保留在诸如 `.tmp/` 之类的隐藏目录下，或放在已建立索引的 QMD 根目录之外，直到 QMD 提供可防循环的遍历或显式排除控制。

 ## 配置

-有关完整的配置项（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及所有其他可调项，请参见
+如需查看完整配置项（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及所有其他可调项，请参阅
 [记忆配置参考](/zh-CN/reference/memory-config)。

 ## 相关内容

 - [记忆概览](/zh-CN/concepts/memory)
- [Builtin 记忆引擎](/zh-CN/concepts/memory-builtin)
+- [内置记忆引擎](/zh-CN/concepts/memory-builtin)
 - [Honcho 记忆](/zh-CN/concepts/memory-honcho)
--- a/docs/zh-CN/concepts/qa-matrix.md
+++ b/docs/zh-CN/concepts/qa-matrix.md
@ -2,23 +2,23 @@
 read_when:
    - 在本地运行 `pnpm openclaw qa matrix`
    - 添加或选择 Matrix QA 场景
-    - 排查 Matrix QA 失败、超时或卡住的清理流程
-summary: Docker 支持的 Matrix 实时 QA 通道的维护者参考：CLI、配置文件、环境变量、场景和输出产物。
+    - 排查 Matrix QA 失败、超时或清理卡住的问题
+summary: Docker 支持的 Matrix 实时 QA 通道的维护者参考：CLI、配置文件、环境变量、场景和输出工件。
 title: Matrix QA
 x-i18n:
-    generated_at: "2026-04-27T20:27:53Z"
+    generated_at: "2026-04-28T03:22:29Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 55fcacd1348b681ef9e550d3f4cdf7c5ed3a2cb8d0df6d93b8ac025ec3280329
+    source_hash: 440c24f2f1b19331f6800bb3224075f718c2429688bb023e96c59f3d3e4c4932
    source_path: concepts/qa-matrix.md
    workflow: 15
 ---

-Matrix QA 通道会针对一次性 Docker 中的 Tuwunel homeserver 运行内置的 `@openclaw/matrix` 插件，并使用临时的驱动、SUT 和观察者账号以及预置房间。这是 Matrix 的实时传输覆盖。
+Matrix QA 通道会在 Docker 中针对一次性 Tuwunel homeserver 运行内置的 `@openclaw/matrix` 插件，并使用临时的 driver、SUT 和 observer 账号以及预置房间。它为 Matrix 提供基于真实传输的实时覆盖。

-这是仅供维护者使用的工具。打包后的 OpenClaw 发布版本会刻意省略 `qa-lab`，因此 `openclaw qa` 只能在源码检出环境中使用。源码检出会直接加载内置运行器——不需要安装插件。
+这是仅供维护者使用的工具。打包发布的 OpenClaw 版本会刻意省略 `qa-lab`，因此 `openclaw qa` 仅可在源码检出环境中使用。源码检出会直接加载内置 runner——不需要安装插件。

-有关更广泛的 QA 框架背景，请参阅 [QA overview](/zh-CN/concepts/qa-e2e-automation)。
+如需了解更广泛的 QA 框架背景，请参阅 [QA overview](/zh-CN/concepts/qa-e2e-automation)。

 ## 快速开始

@ -26,16 +26,16 @@ Matrix QA 通道会针对一次性 Docker 中的 Tuwunel homeserver 运行内置
 pnpm openclaw qa matrix --profile fast --fail-fast
 ```

-直接运行 `pnpm openclaw qa matrix` 会使用 `--profile all`，并且不会在首次失败时停止。将 `--profile fast --fail-fast` 用于发布门禁；当你要并行运行完整场景清单时，可使用 `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` 对目录进行分片。
+直接运行 `pnpm openclaw qa matrix` 会使用 `--profile all`，并且不会在首次失败时停止。将 `--profile fast --fail-fast` 用作发布门禁；在并行运行完整清单时，可使用 `--profile transport|media|e2ee-smoke|e2ee-deep|e2ee-cli` 对场景目录进行分片。

-## 此通道会执行什么
+## 该通道会执行什么

-1. 在 Docker 中创建一个一次性的 Tuwunel homeserver（默认镜像为 `ghcr.io/matrix-construct/tuwunel:v1.5.1`，服务器名称为 `matrix-qa.test`，端口为 `28008`）。
-2. 注册三个临时用户——`driver`（发送入站流量）、`sut`（被测的 OpenClaw Matrix 账号）、`observer`（第三方流量捕获）。
-3. 为所选场景预置所需房间（主房间、线程房间、媒体房间、重启房间、次级房间、allowlist 房间、E2EE 房间、验证私信房间等）。
-4. 启动一个子 OpenClaw Gateway 网关，并在其中加载限定到 SUT 账号的真实 Matrix 插件；子进程中不会加载 `qa-channel`。
+1. 在 Docker 中预配一个一次性的 Tuwunel homeserver（默认镜像为 `ghcr.io/matrix-construct/tuwunel:v1.5.1`，服务器名为 `matrix-qa.test`，端口为 `28008`）。
+2. 注册三个临时用户——`driver`（发送入站流量）、`sut`（待测的 OpenClaw Matrix 账号）、`observer`（第三方流量捕获）。
+3. 为所选场景预置所需房间（main、threading、media、restart、secondary、allowlist、E2EE、verification 私信 等）。
+4. 启动一个子 OpenClaw Gateway 网关，并将真实的 Matrix 插件限定到 SUT 账号；子进程中不会加载 `qa-channel`。
 5. 按顺序运行场景，并通过 driver/observer Matrix 客户端观察事件。
-6. 清理 homeserver，写出报告和摘要产物，然后退出。
+6. 拆除 homeserver，写入报告和摘要工件，然后退出。

 ## CLI

@ -45,100 +45,101 @@ pnpm openclaw qa matrix [options]

 ### 常用标志

-| 标志 | 默认值 | 说明 |
-| --------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `--profile <profile>` | `all` | 场景配置文件。参见 [Profiles](#profiles)。 |
-| `--fail-fast` | off | 在首次检查或场景失败后停止。 |
-| `--scenario <id>` | — | 仅运行此场景。可重复使用。参见 [Scenarios](#scenarios)。 |
-| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | 报告、摘要、观测事件和输出日志的写入位置。相对路径会相对于 `--repo-root` 解析。 |
-| `--repo-root <path>` | `process.cwd()` | 当你从中立工作目录调用时使用的仓库根目录。 |
-| `--sut-account <id>` | `sut` | QA Gateway 网关配置中的 Matrix 账号 id。 |
+| 标志                  | 默认值                                        | 说明                                                                 |
+| --------------------- | --------------------------------------------- | -------------------------------------------------------------------- |
+| `--profile <profile>` | `all`                                         | 场景配置文件。参见 [Profiles](#profiles)。                           |
+| `--fail-fast`         | 关闭                                          | 在第一个失败的检查或场景后停止。                                     |
+| `--scenario <id>`     | —                                             | 仅运行此场景。可重复指定。参见 [Scenarios](#scenarios)。             |
+| `--output-dir <path>` | `<repo>/.artifacts/qa-e2e/matrix-<timestamp>` | 写入报告、摘要、观测事件和输出日志的位置。相对路径会相对于 `--repo-root` 解析。 |
+| `--repo-root <path>`  | `process.cwd()`                               | 从中立工作目录调用时使用的仓库根目录。                               |
+| `--sut-account <id>`  | `sut`                                         | QA Gateway 网关配置中的 Matrix 账号 id。                             |

 ### 提供商标志

 该通道使用真实的 Matrix 传输，但模型提供商可配置：

-| 标志 | 默认值 | 说明 |
-| ------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `--provider-mode <mode>` | `live-frontier` | 使用 `mock-openai` 可获得确定性的 mock 调度，使用 `live-frontier` 可运行实时 frontier 提供商。旧别名 `live-openai` 仍然可用。 |
-| `--model <ref>` | provider 默认值 | 主 `provider/model` 引用。 |
-| `--alt-model <ref>` | provider 默认值 | 运行过程中场景切换时使用的备用 `provider/model` 引用。 |
-| `--fast` | off | 在支持的情况下启用提供商快速模式。 |
+| 标志                     | 默认值           | 说明 |
+| ------------------------ | ---------------- | ---- |
+| `--provider-mode <mode>` | `live-frontier`  | 使用 `mock-openai` 进行确定性的 mock 分发，或使用 `live-frontier` 调用实时 frontier 提供商。旧别名 `live-openai` 仍然可用。 |
+| `--model <ref>`          | 提供商默认值     | 主 `provider/model` 引用。 |
+| `--alt-model <ref>`      | 提供商默认值     | 场景在运行过程中切换时使用的备用 `provider/model` 引用。 |
+| `--fast`                 | 关闭             | 在支持时启用提供商快速模式。 |

-Matrix QA 不接受 `--credential-source` 或 `--credential-role`。该通道会在本地创建一次性用户；没有可供租用的共享凭证池。
+Matrix QA 不接受 `--credential-source` 或 `--credential-role`。该通道会在本地预配一次性用户；没有可供租用的共享凭证池。

 ## Profiles

 所选配置文件决定运行哪些场景。

-| 配置文件 | 适用场景 |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `all`（默认） | 完整目录。较慢，但覆盖最全面。 |
-| `fast` | 用于发布门禁的子集，覆盖实时传输契约：canary、提及门控、allowlist 阻止、回复形态、重启恢复、线程后续跟进、线程隔离、reaction 观测。 |
-| `transport` | 传输层级的线程、私信、房间、自动加入、提及/allowlist 场景。 |
-| `media` | 图像、音频、视频、PDF、EPUB 附件覆盖。 |
-| `e2ee-smoke` | 最小 E2EE 覆盖——基础加密回复、线程后续跟进、bootstrap 成功。 |
-| `e2ee-deep` | 全面的 E2EE 状态丢失、备份、密钥和恢复场景。 |
-| `e2ee-cli` | 通过 QA harness 驱动的 `openclaw matrix encryption setup` 和 `verify *` CLI 场景。 |
+| 配置文件        | 用途 |
+| --------------- | ---- |
+| `all`（默认）   | 完整目录。较慢，但覆盖最全面。 |
+| `fast`          | 用于发布门禁的子集，覆盖实时传输契约：canary、mention gating、allowlist block、reply shape、restart resume、thread follow-up、thread isolation、reaction observation，以及 exec approval metadata delivery。 |
+| `transport`     | 传输层的线程、私信、房间、autojoin、mention/allowlist、approval 和 reaction 场景。 |
+| `media`         | 图片、音频、视频、PDF、EPUB 附件覆盖。 |
+| `e2ee-smoke`    | 最小 E2EE 覆盖——基础加密回复、thread follow-up、bootstrap 成功。 |
+| `e2ee-deep`     | 全面的 E2EE 状态丢失、备份、密钥和恢复场景。 |
+| `e2ee-cli`      | 通过 QA harness 驱动的 `openclaw matrix encryption setup` 和 `verify *` CLI 场景。 |

 精确映射位于 `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts`。

 ## Scenarios

-完整的场景 id 列表是 `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15` 中的 `MatrixQaScenarioId` 联合类型。类别包括：
+完整场景 id 列表是 `extensions/qa-matrix/src/runners/contract/scenario-catalog.ts:15` 中的 `MatrixQaScenarioId` 联合类型。类别包括：

 - threading —— `matrix-thread-*`、`matrix-subagent-thread-spawn`
- top-level / DM / room —— `matrix-top-level-reply-shape`、`matrix-room-*`、`matrix-dm-*`
- streaming and tool progress —— `matrix-room-partial-streaming-preview`、`matrix-room-quiet-streaming-preview`、`matrix-room-tool-progress-*`、`matrix-room-block-streaming`
+- top-level / 私信 / room —— `matrix-top-level-reply-shape`、`matrix-room-*`、`matrix-dm-*`
+- 流式传输和工具进度 —— `matrix-room-partial-streaming-preview`、`matrix-room-quiet-streaming-preview`、`matrix-room-tool-progress-*`、`matrix-room-block-streaming`
 - media —— `matrix-media-type-coverage`、`matrix-room-image-understanding-attachment`、`matrix-attachment-only-ignored`、`matrix-unsupported-media-safe`
 - routing —— `matrix-room-autojoin-invite`、`matrix-secondary-room-*`
 - reactions —— `matrix-reaction-*`
- restart and replay —— `matrix-restart-*`、`matrix-stale-sync-replay-dedupe`、`matrix-room-membership-loss`、`matrix-homeserver-restart-resume`、`matrix-initial-catchup-then-incremental`
- mention gating and allowlists —— `matrix-mention-*`、`matrix-allowlist-*`、`matrix-multi-actor-ordering`、`matrix-inbound-edit-*`、`matrix-mxid-prefixed-command-block`、`matrix-observer-allowlist-override`
- E2EE —— `matrix-e2ee-*`（基础回复、线程后续跟进、bootstrap、恢复密钥生命周期、状态丢失变体、服务器备份行为、设备卫生、SAS / QR / 私信验证、重启、产物脱敏）
- E2EE CLI —— `matrix-e2ee-cli-*`（加密设置、幂等设置、bootstrap 失败、恢复密钥生命周期、多账号、Gateway 网关回复往返、自我验证）
+- approvals —— `matrix-approval-*`（exec/plugin metadata、chunked fallback、deny reactions、threads，以及 `target: "both"` 路由）
+- restart 和 replay —— `matrix-restart-*`、`matrix-stale-sync-replay-dedupe`、`matrix-room-membership-loss`、`matrix-homeserver-restart-resume`、`matrix-initial-catchup-then-incremental`
+- mention gating 和 allowlists —— `matrix-mention-*`、`matrix-allowlist-*`、`matrix-multi-actor-ordering`、`matrix-inbound-edit-*`、`matrix-mxid-prefixed-command-block`、`matrix-observer-allowlist-override`
+- E2EE —— `matrix-e2ee-*`（基础回复、thread follow-up、bootstrap、recovery key 生命周期、state-loss 变体、服务器备份行为、设备卫生、SAS / QR / 私信 验证、重启、工件脱敏）
+- E2EE CLI —— `matrix-e2ee-cli-*`（encryption setup、幂等 setup、bootstrap failure、recovery-key 生命周期、多账号、gateway-reply 往返、自验证）

-传入 `--scenario <id>`（可重复）以运行一组手工挑选的场景；与 `--profile all` 组合使用可忽略配置文件门控。
+传入 `--scenario <id>`（可重复）以运行手动挑选的一组场景；与 `--profile all` 组合使用可忽略配置文件门控。

 ## 环境变量

-| 变量 | 默认值 | 作用 |
-| --------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OPENCLAW_QA_MATRIX_TIMEOUT_MS` | `1800000`（30 分钟） | 整个运行过程的硬性最长时间上限。 |
-| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000` | 用于否定性“无回复”断言的静默窗口。会被限制为 `≤` 运行超时时间。 |
-| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000` | Docker 清理的时间上限。失败信息中会包含恢复命令 `docker compose ... down --remove-orphans`。 |
-| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | 在针对不同 Tuwunel 版本进行验证时，用于覆盖 homeserver 镜像。 |
-| `OPENCLAW_QA_MATRIX_PROGRESS` | on | `0` 会静默 stderr 上的 `[matrix-qa] ...` 进度行。`1` 会强制开启。 |
-| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT` | redacted | `1` 会在 `matrix-qa-observed-events.json` 中保留消息正文和 `formatted_body`。默认会脱敏，以保证 CI 产物安全。 |
-| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | off | `1` 会跳过写入产物后的确定性 `process.exit`。默认会强制退出，因为 `matrix-js-sdk` 的原生加密句柄可能在产物写完后仍让事件循环保持活跃。 |
-| `OPENCLAW_RUN_NODE_OUTPUT_LOG` | unset | 当外层启动器设置了该值时（例如 `scripts/run-node.mjs`），Matrix QA 会复用该日志路径，而不是自行启动 tee。 |
+| 变量                                    | 默认值                                    | 作用 |
+| --------------------------------------- | ----------------------------------------- | ---- |
+| `OPENCLAW_QA_MATRIX_TIMEOUT_MS`         | `1800000`（30 分钟）                      | 整个运行过程的硬性上限。 |
+| `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS` | `8000`                                    | 用于否定性“无回复”断言的静默窗口。会被限制为 `≤` 运行超时。 |
+| `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS` | `90000`                                   | Docker 拆除的时间上限。失败表面包括恢复用的 `docker compose ... down --remove-orphans` 命令。 |
+| `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`      | `ghcr.io/matrix-construct/tuwunel:v1.5.1` | 在针对不同 Tuwunel 版本验证时覆盖 homeserver 镜像。 |
+| `OPENCLAW_QA_MATRIX_PROGRESS`           | 开启                                      | `0` 会静默 stderr 上的 `[matrix-qa] ...` 进度行。`1` 会强制开启。 |
+| `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT`    | 已脱敏                                    | `1` 会在 `matrix-qa-observed-events.json` 中保留消息正文和 `formatted_body`。默认会进行脱敏，以保证 CI 工件安全。 |
+| `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT` | 关闭                                      | `1` 会跳过写入工件后的确定性 `process.exit`。默认会强制退出，因为 `matrix-js-sdk` 的原生加密句柄可能在工件写完后仍让事件循环保持存活。 |
+| `OPENCLAW_RUN_NODE_OUTPUT_LOG`          | 未设置                                    | 当由外层启动器（例如 `scripts/run-node.mjs`）设置时，Matrix QA 会复用该日志路径，而不是启动自己的 tee。 |

-## 输出产物
+## 输出工件

 写入到 `--output-dir`：

- `matrix-qa-report.md` —— Markdown 协议报告（哪些通过、失败、跳过，以及原因）。
- `matrix-qa-summary.json` —— 适用于 CI 解析和仪表盘的结构化摘要。
- `matrix-qa-observed-events.json` —— 来自 driver 和 observer 客户端观测到的 Matrix 事件。除非设置了 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`，否则正文会被脱敏。
- `matrix-qa-output.log` —— 运行过程中的合并 stdout/stderr。如果设置了 `OPENCLAW_RUN_NODE_OUTPUT_LOG`，则会改为复用外层启动器的日志。
+- `matrix-qa-report.md` — Markdown 协议报告（哪些通过、失败、被跳过，以及原因）。
+- `matrix-qa-summary.json` — 适合用于 CI 解析和仪表板的结构化摘要。
+- `matrix-qa-observed-events.json` — 来自 driver 和 observer 客户端观测到的 Matrix 事件。除非设置 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1`，否则正文会被脱敏；approval metadata 会以选定的安全字段和截断后的命令预览进行摘要。
+- `matrix-qa-output.log` — 本次运行的合并 stdout/stderr。如果设置了 `OPENCLAW_RUN_NODE_OUTPUT_LOG`，则会改为复用外层启动器的日志。

-默认输出目录为 `<repo>/.artifacts/qa-e2e/matrix-<timestamp>`，因此连续运行不会互相覆盖。
+默认输出目录是 `<repo>/.artifacts/qa-e2e/matrix-<timestamp>`，因此连续运行不会互相覆盖。

 ## 排查提示

- **运行在接近结束时卡住：** `matrix-js-sdk` 的原生加密句柄可能会比 harness 存活得更久。默认行为是在写入产物后强制执行一次干净的 `process.exit`；如果你设置了 `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`，则应预期进程会继续挂住一段时间。
- **清理错误：** 查找打印出来的恢复命令（一个 `docker compose ... down --remove-orphans` 调用），然后手动运行它以释放 homeserver 端口。
+- **运行在接近结束时挂起：** `matrix-js-sdk` 的原生加密句柄可能在 harness 结束后仍然存活。默认行为是在写入工件后强制执行干净的 `process.exit`；如果你设置了 `OPENCLAW_QA_MATRIX_DISABLE_FORCE_EXIT=1`，则应预期进程会继续停留。
+- **清理错误：** 查找打印出来的恢复命令（一次 `docker compose ... down --remove-orphans` 调用），并手动运行它以释放 homeserver 端口。
 - **CI 中否定断言窗口不稳定：** 当 CI 很快时，调低 `OPENCLAW_QA_MATRIX_NO_REPLY_WINDOW_MS`（默认 8 秒）；在较慢的共享 runner 上则调高它。
- **需要为 bug 报告保留未脱敏正文：** 使用 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` 重新运行，并附上 `matrix-qa-observed-events.json`。请将生成的产物视为敏感内容。
- **不同的 Tuwunel 版本：** 将 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 指向正在测试的版本。该通道仓库中只固定提交了默认钉住的镜像版本。
+- **需要带未脱敏正文的 bug 报告：** 使用 `OPENCLAW_QA_MATRIX_CAPTURE_CONTENT=1` 重新运行，并附上 `matrix-qa-observed-events.json`。请将生成的工件视为敏感信息。
+- **不同的 Tuwunel 版本：** 将 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 指向待测试的版本。该通道仅签入了固定的默认镜像。

 ## 实时传输契约

-Matrix 是三个实时传输通道之一（Matrix、Telegram、Discord），它们共享同一份契约检查清单，该清单定义于 [QA overview → Live transport coverage](/zh-CN/concepts/qa-e2e-automation#live-transport-coverage)。`qa-channel` 仍然是覆盖范围更广的合成测试套件，并且被刻意排除在该矩阵之外。
+Matrix 是三个实时传输通道之一（Matrix、Telegram、Discord），它们共享一份在 [QA overview → Live transport coverage](/zh-CN/concepts/qa-e2e-automation#live-transport-coverage) 中定义的统一契约检查清单。`qa-channel` 仍然是广覆盖的合成测试套件，并且有意不属于该矩阵的一部分。

 ## 相关内容

- [QA overview](/zh-CN/concepts/qa-e2e-automation) —— 整体 QA 栈和实时传输契约
- [QA channel](/zh-CN/channels/qa-channel) —— 用于仓库驱动场景的合成渠道适配器
- [Testing](/zh-CN/help/testing) —— 运行测试和添加 QA 覆盖
- [Matrix](/zh-CN/channels/matrix) —— 正在测试的渠道插件
+- [QA overview](/zh-CN/concepts/qa-e2e-automation) — 整体 QA 栈和实时传输契约
+- [QA channel](/zh-CN/channels/qa-channel) — 用于基于仓库场景的合成渠道适配器
+- [Testing](/zh-CN/help/testing) — 运行测试和添加 QA 覆盖
+- [Matrix](/zh-CN/channels/matrix) — 被测的渠道插件
--- a/docs/zh-CN/plugins/sdk-migration.md
+++ b/docs/zh-CN/plugins/sdk-migration.md
@ -4,72 +4,74 @@ read_when:
    - 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告
    - 你在 OpenClaw 2026.4.25 之前使用了 `api.registerEmbeddedExtensionFactory`
    - 你正在将一个插件更新到现代插件架构
-    - 你在维护一个外部 OpenClaw 插件
+    - 你维护一个外部 OpenClaw 插件
 sidebarTitle: Migrate to SDK
 summary: 从旧版向后兼容层迁移到现代插件 SDK
 title: 插件 SDK 迁移
 x-i18n:
-    generated_at: "2026-04-28T03:09:21Z"
+    generated_at: "2026-04-28T03:22:27Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 330ae4446c56e1a596e6c1b8e198a98bb03b616104efd1b25b4285c2700166c3
+    source_hash: f98e3e5d999f8f18069f39f5d8a2f65b97003301d10e59ab5cfcf744ac0720c4
    source_path: plugins/sdk-migration.md
    workflow: 15
 ---

-OpenClaw 已从宽泛的向后兼容层迁移到采用聚焦式、文档化导入的现代插件架构。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。
+OpenClaw 已从宽泛的向后兼容层迁移到具有聚焦且文档化导入方式的现代插件架构。如果你的插件是在新架构之前构建的，本指南将帮助你完成迁移。

 ## 正在发生哪些变化

-旧版插件系统提供了两个高度开放的接口面，允许插件从单一入口点导入所需的任何内容：
+旧版插件系统提供了两个高度开放的接口，让插件可以从单一入口导入所需的任何内容：

- **`openclaw/plugin-sdk/compat`** —— 一个会重新导出数十个辅助工具的单一导入入口。它的引入是为了在构建新插件架构期间，保持较旧的基于 hook 的插件继续工作。
- **`openclaw/plugin-sdk/infra-runtime`** —— 一个宽泛的运行时辅助 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型以及无关的实用工具。
- **`openclaw/plugin-sdk/config-runtime`** —— 一个宽泛的配置兼容性 barrel，在迁移窗口期间仍然承载已弃用的直接加载/写入辅助工具。
- **`openclaw/extension-api`** —— 一个桥接层，使插件能够直接访问宿主侧辅助工具，例如嵌入式智能体运行器。
- **`api.registerEmbeddedExtensionFactory(...)`** —— 一个已移除、仅供 Pi 使用的内置扩展 hook，它曾可观察诸如 `tool_result` 之类的嵌入式运行器事件。
+- **`openclaw/plugin-sdk/compat`** —— 单一导入入口，重新导出了数十个辅助工具。它的引入是为了在构建新插件架构期间，让较旧的基于钩子的插件继续工作。
+- **`openclaw/plugin-sdk/infra-runtime`** —— 一个宽泛的运行时辅助 barrel，混合了系统事件、心跳状态、投递队列、fetch/proxy 辅助工具、文件辅助工具、审批类型以及不相关的实用工具。
+- **`openclaw/plugin-sdk/config-runtime`** —— 一个宽泛的配置兼容性 barrel，在迁移窗口期内仍然保留已弃用的直接加载/写入辅助工具。
+- **`openclaw/extension-api`** —— 一个桥接层，让插件可以直接访问宿主端辅助工具，例如嵌入式智能体运行器。
+- **`api.registerEmbeddedExtensionFactory(...)`** —— 一个已移除的仅限 Pi 的内置扩展钩子，可观察嵌入式运行器事件，例如 `tool_result`。

-这些宽泛的导入接口现在都已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件则应在下一个主版本移除它们之前完成迁移。仅供 Pi 使用的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。
+这些宽泛的导入接口现已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。

-OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。破坏性契约变更必须先经过兼容性适配器、诊断、文档和弃用窗口。这同样适用于 SDK 导入、manifest 字段、设置 API、hooks 和运行时注册行为。
+OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。破坏性契约变更必须先经过兼容性适配器、诊断、文档和弃用窗口。这适用于 SDK 导入、manifest 字段、设置 API、钩子以及运行时注册行为。

 <Warning>
-  向后兼容层将在未来的主版本中被移除。届时，仍从这些接口面导入内容的插件将会失效。
-  仅供 Pi 使用的嵌入式扩展工厂注册已不再加载。
+  向后兼容层将在未来的主要版本中移除。届时，仍从这些接口导入的插件将会失效。
+  仅限 Pi 的嵌入式扩展工厂注册已经不再加载。
 </Warning>

 ## 为什么会有这项变更

-旧方法带来了这些问题：
+旧方案会导致一些问题：

 - **启动缓慢** —— 导入一个辅助工具会加载数十个无关模块
- **循环依赖** —— 宽泛的重新导出使创建导入循环变得很容易
- **API 接口面不清晰** —— 无法判断哪些导出是稳定的，哪些属于内部实现
+- **循环依赖** —— 宽泛的重新导出很容易造成导入循环
+- **API 接口不清晰** —— 无法判断哪些导出是稳定的，哪些是内部实现

-现代插件 SDK 解决了这一点：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含的模块，具有明确用途和已文档化的契约。
+现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含模块，具有明确用途和文档化契约。

-面向内置渠道的旧版 provider 便捷接口也已移除。
-带有渠道品牌的辅助接口是私有 monorepo 捷径，而不是稳定的插件契约。请改用更窄、更通用的 SDK 子路径。在内置插件工作区内部，请将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。
+针对内置渠道的旧版 provider 便捷接口也已移除。
+带有渠道品牌色彩的辅助接口属于私有 monorepo 快捷方式，而不是稳定的插件契约。请改用范围更窄的通用 SDK 子路径。在内置插件工作区内部，应将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。

-当前内置 provider 示例：
+当前的内置 provider 示例：

- Anthropic 将 Claude 专用的流式辅助工具保留在其自己的 `api.ts` /
-  `contract-api.ts` 接口中
- OpenAI 将 provider 构建器、默认模型辅助工具和实时 provider 构建器保留在其自己的 `api.ts` 中
- OpenRouter 将 provider 构建器以及新手引导/配置辅助工具保留在其自己的 `api.ts` 中
+- Anthropic 在其自己的 `api.ts` / `contract-api.ts` 接口中保留 Claude 专用流式辅助工具
+- OpenAI 在其自己的 `api.ts` 中保留 provider 构建器、默认模型辅助工具和实时 provider 构建器
+- OpenRouter 在其自己的 `api.ts` 中保留 provider 构建器以及新手引导/配置辅助工具

 ## 兼容性策略

 对于外部插件，兼容性工作遵循以下顺序：

 1. 添加新契约
-2. 通过兼容性适配器保持旧行为继续连通
-3. 发出点明旧路径及其替代项的诊断或警告
-4. 在测试中覆盖两条路径
-5. 记录弃用信息和迁移路径
-6. 仅在已公告的迁移窗口之后移除，通常是在主版本中
+2. 通过兼容性适配器保持旧行为继续可用
+3. 发出点明旧路径和替代方案的诊断或警告
+4. 在测试中覆盖两种路径
+5. 记录弃用和迁移路径
+6. 仅在已宣布的迁移窗口结束后移除，通常是在主要版本中

-如果某个 manifest 字段仍被接受，插件作者就可以继续使用它，直到文档和诊断另有说明。新代码应优先使用已文档化的替代方案，但现有插件不应在普通的次版本发布中被破坏。
+维护者可以通过 `pnpm plugins:boundary-report` 审查当前迁移队列。
+该报告会按移除日期对已弃用的兼容性记录进行分组，统计本地代码/文档引用数，标示跨所有者保留的 SDK 导入，并汇总私有 memory-host SDK 桥接情况，从而让兼容性清理保持明确，而不是依赖临时搜索。
+
+如果某个 manifest 字段仍然被接受，插件作者就可以继续使用它，直到文档和诊断另有说明。新代码应优先使用文档化的替代方案，但现有插件不应在常规次要版本中损坏。

 ## 如何迁移

@ -77,9 +79,9 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
  <Step title="迁移运行时配置加载/写入辅助工具">
    内置插件应停止直接调用
    `api.runtime.config.loadConfig()` 和
-    `api.runtime.config.writeConfigFile(...)`。优先使用已传入当前活动调用路径中的配置。需要当前进程快照的长生命周期处理器可以使用 `api.runtime.config.current()`。长生命周期智能体工具应在 `execute` 内使用工具上下文中的 `ctx.getRuntimeConfig()`，这样在配置写入之前创建的工具仍然可以看到已刷新的运行时配置。
+    `api.runtime.config.writeConfigFile(...)`。优先使用已传入当前活动调用路径的配置。需要当前进程快照的长生命周期处理器可以使用 `api.runtime.config.current()`。长生命周期智能体工具应在 `execute` 内使用工具上下文的 `ctx.getRuntimeConfig()`，这样即使工具创建于配置写入之前，也仍能看到刷新后的运行时配置。

-    配置写入必须通过事务性辅助工具完成，并选择一种写入后策略：
+    配置写入必须通过事务型辅助工具执行，并选择写入后的策略：

    ```typescript
    await api.runtime.config.mutateConfigFile({
@ -90,35 +92,35 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
    });
    ```

-    当调用方明确知道该变更需要一次干净的 Gateway 网关重启时，请使用
-    `afterWrite: { mode: "restart", reason: "..." }`；只有在调用方负责后续处理并且明确希望抑制重载规划器时，才使用
+    当调用方明确知道变更需要彻底重启 Gateway 网关时，请使用
+    `afterWrite: { mode: "restart", reason: "..." }`；而仅当调用方自行负责后续处理，并且有意抑制重载规划器时，才使用
    `afterWrite: { mode: "none", reason: "..." }`。
-    变更结果包含一个带类型的 `followUp` 摘要，供测试和日志使用；Gateway 网关仍负责执行或安排重启。
-    `loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为外部插件的已弃用兼容性辅助工具保留，并会使用 `runtime-config-load-write` 兼容性代码发出一次警告。内置插件和仓库运行时代码受以下扫描护栏保护：
+    变更结果会包含一个带类型的 `followUp` 摘要，用于测试和日志记录；Gateway 网关 仍负责应用或调度重启。
+    `loadConfig` 和 `writeConfigFile` 在迁移窗口期内仍作为外部插件的已弃用兼容性辅助工具保留，并会以 `runtime-config-load-write` 兼容性代码发出一次警告。内置插件和仓库运行时代码受到
    `pnpm check:deprecated-internal-config-api` 和
-    `pnpm check:no-runtime-action-load-config`：新的生产插件用法会被直接判为失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，运行时渠道发送/动作/客户端辅助工具必须从其边界接收配置，而长生命周期运行时模块中环境式 `loadConfig()` 调用的允许数量为零。
+    `pnpm check:no-runtime-action-load-config` 中扫描器防护措施的保护：新的生产插件用法会直接失败，直接配置写入会失败，Gateway 网关 服务器方法必须使用请求运行时快照，运行时渠道发送/操作/客户端辅助工具必须从其边界接收配置，而长生命周期运行时模块不允许存在任何环境式 `loadConfig()` 调用。

    新插件代码也应避免导入宽泛的
-    `openclaw/plugin-sdk/config-runtime` 兼容性 barrel。请使用与任务匹配的窄化 SDK 子路径：
+    `openclaw/plugin-sdk/config-runtime` 兼容性 barrel。请使用与任务匹配的窄范围 SDK 子路径：

    | 需求 | 导入 |
    | --- | --- |
-    | 配置类型，例如 `OpenClawConfig` | `openclaw/plugin-sdk/config-types` |
+    | 配置类型，如 `OpenClawConfig` | `openclaw/plugin-sdk/config-types` |
    | 已加载配置断言和插件入口配置查找 | `openclaw/plugin-sdk/plugin-config-runtime` |
    | 当前运行时快照读取 | `openclaw/plugin-sdk/runtime-config-snapshot` |
    | 配置写入 | `openclaw/plugin-sdk/config-mutation` |
    | 会话存储辅助工具 | `openclaw/plugin-sdk/session-store-runtime` |
    | Markdown 表格配置 | `openclaw/plugin-sdk/markdown-table-runtime` |
-    | 群组策略运行时辅助工具 | `openclaw/plugin-sdk/runtime-group-policy` |
-    | Secret 输入解析 | `openclaw/plugin-sdk/secret-input-runtime` |
+    | 组策略运行时辅助工具 | `openclaw/plugin-sdk/runtime-group-policy` |
+    | 密钥输入解析 | `openclaw/plugin-sdk/secret-input-runtime` |
    | 模型/会话覆盖 | `openclaw/plugin-sdk/model-session-runtime` |

-    内置插件及其测试受到扫描器保护，不得依赖这个宽泛的 barrel，因此导入和 mock 都应局部化到它们实际需要的行为。这个宽泛的 barrel 仍然存在以保持外部兼容性，但新代码不应依赖它。
+    内置插件及其测试受到扫描器保护，不能使用这个宽泛的 barrel，因此导入和 mock 都会局限于其实际所需的行为。这个宽泛的 barrel 仍然存在以保持外部兼容性，但新代码不应依赖它。

  </Step>

  <Step title="将 Pi 工具结果扩展迁移到中间件">
-    内置插件必须将仅供 Pi 使用的
+    内置插件必须将仅限 Pi 的
    `api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为与运行时无关的中间件。

    ```typescript
@ -140,34 +142,33 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
    }
    ```

-    外部插件不能注册工具结果中间件，因为它可以在模型看到高信任度工具输出之前重写这些输出。
+    外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前对其进行重写。

  </Step>

  <Step title="将原生审批处理器迁移到能力事实">
-    支持审批的渠道插件现在通过
-    `approvalCapability.nativeRuntime` 加上共享的运行时上下文注册表来暴露原生审批行为。
+    具备审批能力的渠道插件现在通过
+    `approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来公开原生审批行为。

    关键变化：

    - 将 `approvalCapability.handler.loadRuntime(...)` 替换为
      `approvalCapability.nativeRuntime`
-    - 将审批专用的 auth/delivery 从旧版 `plugin.auth` /
-      `plugin.approvals` 接线迁移到 `approvalCapability`
+    - 将审批专用 auth/delivery 从旧版 `plugin.auth` /
+      `plugin.approvals` 连接迁移到 `approvalCapability`
    - `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery/native/render 字段迁移到 `approvalCapability`
-    - `plugin.auth` 仅保留用于渠道登录/登出流程；其中的审批 auth hooks 不再由核心读取
-    - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有的运行时对象，例如客户端、令牌或 Bolt app
-    - 不要从原生审批处理器发送插件自有的重新路由通知；核心现在根据实际投递结果负责“已路由到其他位置”的通知
-    - 在将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。
+    - `plugin.auth` 仅保留给渠道登录/登出流程使用；核心不再读取其中的审批 auth 钩子
+    - 通过 `openclaw/plugin-sdk/channel-runtime-context` 注册渠道自有运行时对象，例如客户端、令牌或 Bolt 应用
+    - 不要从原生审批处理器发送插件自有的“已改道”通知；核心现在根据实际投递结果负责“已在其他位置路由”的通知
+    - 向 `createChannelManager(...)` 传入 `channelRuntime` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 将被拒绝。

-    请参阅 `/plugins/sdk-channel-plugins` 了解当前审批能力布局。
+    有关当前审批能力布局，请参阅 `/plugins/sdk-channel-plugins`。

  </Step>

-  <Step title="审查 Windows wrapper 回退行为">
-    如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，未解析的 Windows
-    `.cmd`/`.bat` wrapper 现在会默认失败关闭，除非你显式传入
-    `allowShellFallback: true`。
+  <Step title="审查 Windows 包装器回退行为">
+    如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在在未显式传入
+    `allowShellFallback: true` 的情况下，无法解析的 Windows `.cmd`/`.bat` 包装器将以关闭失败方式处理。

    ```typescript
    // 之前
@ -176,8 +177,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
    // 之后
    const program = applyWindowsSpawnProgramPolicy({
      candidate,
-      // 仅对受信任的兼容性调用方设置此项，这些调用方明确接受
-      // 通过 shell 中介的回退。
+      // 仅对有意接受 shell 中介回退的受信任兼容性调用方设置此项。
      allowShellFallback: true,
    });
    ```
@ -187,8 +187,8 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释

  </Step>

-  <Step title="查找已弃用的导入">
-    在你的插件中搜索来自任一已弃用接口面的导入：
+  <Step title="查找已弃用导入">
+    在你的插件中搜索是否从已弃用接口导入：

    ```bash
    grep -r "plugin-sdk/compat" my-plugin/
@ -199,8 +199,8 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释

  </Step>

-  <Step title="替换为聚焦式导入">
-    旧接口面的每个导出都映射到一个特定的现代导入路径：
+  <Step title="替换为聚焦导入">
+    旧接口中的每个导出都映射到特定的现代导入路径：

    ```typescript
    // 之前（已弃用的向后兼容层）
@ -210,16 +210,16 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
      resolveControlCommandGate,
    } from "openclaw/plugin-sdk/compat";

-    // 之后（现代聚焦式导入）
+    // 之后（现代聚焦导入）
    import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
    import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
    import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
    ```

-    对于宿主侧辅助工具，请使用注入的插件运行时，而不是直接导入：
+    对于宿主端辅助工具，请使用注入的插件运行时，而不是直接导入：

    ```typescript
-    // 之前（已弃用的 extension-api 桥接层）
+    // 之前（已弃用的 extension-api 桥接）
    import { runEmbeddedPiAgent } from "openclaw/extension-api";
    const result = await runEmbeddedPiAgent({ sessionId, prompt });

@ -227,7 +227,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
    const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
    ```

-    其他旧版桥接辅助工具也遵循相同模式：
+    相同模式也适用于其他旧版桥接辅助工具：

    | 旧导入 | 现代等价项 |
    | --- | --- |
@ -237,12 +237,12 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
    | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
    | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
    | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
-    | session store helpers | `api.runtime.agent.session.*` |
+    | 会话存储辅助工具 | `api.runtime.agent.session.*` |

  </Step>

  <Step title="替换宽泛的 infra-runtime 导入">
-    `openclaw/plugin-sdk/infra-runtime` 仍然存在以保持外部兼容性，但新代码应导入它实际需要的聚焦式辅助接口：
+    `openclaw/plugin-sdk/infra-runtime` 仍然存在，以保持外部兼容性，但新代码应导入其实际所需的聚焦辅助工具接口：

    | 需求 | 导入 |
    | --- | --- |
@ -252,11 +252,11 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
    | 渠道活动遥测 | `openclaw/plugin-sdk/channel-activity-runtime` |
    | 内存内去重缓存 | `openclaw/plugin-sdk/dedupe-runtime` |
    | 安全的本地文件/媒体路径辅助工具 | `openclaw/plugin-sdk/file-access-runtime` |
-    | 具备 dispatcher 感知能力的 fetch | `openclaw/plugin-sdk/runtime-fetch` |
-    | proxy 和受保护的 fetch 辅助工具 | `openclaw/plugin-sdk/fetch-runtime` |
+    | 感知 dispatcher 的 fetch | `openclaw/plugin-sdk/runtime-fetch` |
+    | 代理和受保护 fetch 辅助工具 | `openclaw/plugin-sdk/fetch-runtime` |
    | SSRF dispatcher 策略类型 | `openclaw/plugin-sdk/ssrf-dispatcher` |
    | 审批请求/解析类型 | `openclaw/plugin-sdk/approval-runtime` |
-    | 审批回复载荷和命令辅助工具 | `openclaw/plugin-sdk/approval-reply-runtime` |
+    | 审批回复负载和命令辅助工具 | `openclaw/plugin-sdk/approval-reply-runtime` |
    | 错误格式化辅助工具 | `openclaw/plugin-sdk/error-runtime` |
    | 传输就绪等待 | `openclaw/plugin-sdk/transport-ready-runtime` |
    | 安全令牌辅助工具 | `openclaw/plugin-sdk/secure-random-runtime` |
@ -265,13 +265,13 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
    | 进程本地异步锁 | `openclaw/plugin-sdk/async-lock-runtime` |
    | 文件锁 | `openclaw/plugin-sdk/file-lock` |

-    内置插件受到扫描器保护，不得使用 `infra-runtime`，因此仓库代码无法回退到这个宽泛的 barrel。
+    内置插件受到扫描器保护，不能使用 `infra-runtime`，因此仓库代码无法回退到这个宽泛的 barrel。

  </Step>

  <Step title="迁移渠道路由辅助工具">
    新的渠道路由代码应使用 `openclaw/plugin-sdk/channel-route`。
-    在迁移窗口期间，旧的 route-key 和 comparable-target 名称仍作为兼容性别名保留，但新插件应使用能够直接描述行为的路由名称：
+    在迁移窗口期内，旧的 route-key 和 comparable-target 名称仍保留为兼容性别名，但新插件应使用能够直接描述行为的路由名称：

    | 旧辅助工具 | 现代辅助工具 |
    | --- | --- |
@ -283,8 +283,8 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
    | `comparableChannelTargetsMatch(...)` | `channelRouteTargetsMatchExact(...)` |
    | `comparableChannelTargetsShareRoute(...)` | `channelRouteTargetsShareConversation(...)` |

-    现代路由辅助工具会在原生审批、回复抑制、入站去重、cron 投递和会话路由之间，以一致方式规范化 `{ channel, to, accountId, threadId }`。
-    如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)`，将该解析器适配到相同的路由目标契约中。
+    现代路由辅助工具会在原生审批、回复抑制、入站去重、cron 投递和会话路由之间，一致地规范化 `{ channel, to, accountId, threadId }`。
+    如果你的插件拥有自定义目标语法，请使用 `resolveChannelRouteTargetWithParser(...)`，将该解析器适配到同一路由目标契约中。

  </Step>

@ -302,60 +302,60 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
  | 导入路径 | 用途 | 关键导出 |
  | --- | --- | --- |
  | `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` |
-  | `plugin-sdk/core` | 面向渠道入口定义/构建器的旧版总括式重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
+  | `plugin-sdk/core` | 用于渠道入口定义/构建器的旧版总括重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
  | `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` |
-  | `plugin-sdk/provider-entry` | 单一 provider 入口辅助工具 | `defineSingleProviderPluginEntry` |
-  | `plugin-sdk/channel-core` | 聚焦式渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
-  | `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置 Status 构建器 |
-  | `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 导入安全的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托式设置代理 |
+  | `plugin-sdk/provider-entry` | 单 provider 入口辅助工具 | `defineSingleProviderPluginEntry` |
+  | `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
+  | `plugin-sdk/setup` | 共享设置向导辅助工具 | allowlist 提示、设置 Status 构建器 |
+  | `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 可安全导入的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 |
  | `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` |
  | `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
-  | `plugin-sdk/account-core` | 多账号辅助工具 | 账号列表/配置/动作门控辅助工具 |
-  | `plugin-sdk/account-id` | 账号 ID 辅助工具 | `DEFAULT_ACCOUNT_ID`、账号 ID 规范化 |
+  | `plugin-sdk/account-core` | 多账号辅助工具 | 账号列表/配置/操作门控辅助工具 |
+  | `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 |
  | `plugin-sdk/account-resolution` | 账号查找辅助工具 | 账号查找 + 默认回退辅助工具 |
-  | `plugin-sdk/account-helpers` | 窄化账号辅助工具 | 账号列表/账号动作辅助工具 |
-  | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` |
+  | `plugin-sdk/account-helpers` | 窄范围账号辅助工具 | 账号列表/账号操作辅助工具 |
+  | `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
  | `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` |
-  | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + typing 接线 | `createChannelReplyPipeline` |
+  | `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入布线 | `createChannelReplyPipeline` |
  | `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` |
-  | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语和仅通用构建器 |
-  | `plugin-sdk/bundled-channel-config-schema` | 内置配置 schema | 仅供 OpenClaw 维护的内置插件使用；新插件必须定义插件本地 schema |
+  | `plugin-sdk/channel-config-schema` | 配置 schema 构建器 | 共享渠道配置 schema 原语和仅限通用构建器 |
+  | `plugin-sdk/bundled-channel-config-schema` | 内置配置 schema | 仅限 OpenClaw 维护的内置插件；新插件必须定义插件本地 schema |
  | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置 schema | 仅兼容性别名；维护中的内置插件请使用 `plugin-sdk/bundled-channel-config-schema` |
  | `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复/冲突校验 |
  | `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` |
-  | `plugin-sdk/channel-lifecycle` | 账号状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览终结辅助工具 |
-  | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享 route + envelope 构建器辅助工具 |
-  | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 |
+  | `plugin-sdk/channel-lifecycle` | 账号 Status 和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览最终化辅助工具 |
+  | `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope 构建器辅助工具 |
+  | `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录与分发辅助工具 |
  | `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 |
  | `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 |
-  | `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 轻量级 `resolveOutboundSendDep` 查找，无需导入完整出站运行时 |
-  | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、identity/send delegate、会话、格式化和载荷规划辅助工具 |
+  | `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 轻量级 `resolveOutboundSendDep` 查找，无需导入完整的出站运行时 |
+  | `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、身份/发送委托、会话、格式化和负载规划辅助工具 |
  | `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 |
-  | `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 面向旧版字段布局的智能体媒体载荷构建器 |
-  | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时实用工具 |
+  | `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧字段布局的智能体媒体负载构建器 |
+  | `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅限旧版渠道运行时实用工具 |
  | `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 |
  | `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` |
  | `plugin-sdk/runtime` | 宽泛运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 |
-  | `plugin-sdk/runtime-env` | 窄化运行时环境辅助工具 | logger/运行时环境、超时、重试和退避辅助工具 |
-  | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/hooks/http/交互式辅助工具 |
-  | `plugin-sdk/hook-runtime` | hook 管道辅助工具 | 共享 webhook/内部 hook 管道辅助工具 |
+  | `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | logger/运行时环境、超时、重试和退避辅助工具 |
+  | `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/钩子/http/交互式辅助工具 |
+  | `plugin-sdk/hook-runtime` | 钩子流水线辅助工具 | 共享 webhook/内部钩子流水线辅助工具 |
  | `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
  | `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 |
  | `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 |
-  | `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 |
+  | `plugin-sdk/gateway-runtime` | Gateway 网关 辅助工具 | Gateway 网关 客户端和渠道 Status 补丁辅助工具 |
  | `plugin-sdk/config-runtime` | 已弃用的配置兼容性 shim | 优先使用 `config-types`、`plugin-config-runtime`、`runtime-config-snapshot` 和 `config-mutation` |
  | `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供回退稳定的 Telegram 命令校验辅助工具 |
-  | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批载荷、审批 capability/profile 辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 |
-  | `plugin-sdk/approval-auth-runtime` | 审批 auth 辅助工具 | approver 解析、同聊天动作 auth |
+  | `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec/插件审批负载、approval capability/profile 辅助工具、原生审批路由/运行时辅助工具，以及结构化审批显示路径格式化 |
+  | `plugin-sdk/approval-auth-runtime` | 审批 auth 辅助工具 | approver 解析、同聊天操作 auth |
  | `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批 profile/filter 辅助工具 |
-  | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批 capability/delivery 适配器 |
-  | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 |
-  | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 面向热路径渠道入口点的轻量级原生审批适配器加载辅助工具 |
-  | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；如果更窄的 adapter/gateway 接口已足够，应优先使用它们 |
+  | `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生 approval capability/delivery 适配器 |
+  | `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关 辅助工具 | 共享审批 Gateway 网关 解析辅助工具 |
+  | `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于高热渠道入口点的轻量级原生审批适配器加载辅助工具 |
+  | `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；若更窄的 adapter/gateway 接口已足够，优先使用它们 |
  | `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标/账号绑定辅助工具 |
-  | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复载荷辅助工具 |
+  | `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec/插件审批回复负载辅助工具 |
  | `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register/get/watch 辅助工具 |
-  | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和 secret 收集辅助工具 |
+  | `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和密钥收集辅助工具 |
  | `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 |
  | `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | pinned-dispatcher、受保护 fetch、SSRF 策略辅助工具 |
  | `plugin-sdk/system-event-runtime` | 系统事件辅助工具 | `enqueueSystemEvent`, `peekSystemEventEntries` |
@ -368,21 +368,21 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
  | `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` |
  | `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
  | `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 |
-  | `plugin-sdk/fetch-runtime` | 包装后的 fetch/proxy 辅助工具 | `resolveFetch`、proxy 辅助工具 |
+  | `plugin-sdk/fetch-runtime` | 封装的 fetch/proxy 辅助工具 | `resolveFetch`、proxy 辅助工具 |
  | `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` |
  | `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 |
-  | `plugin-sdk/allow-from` | Allowlist 格式化 | `formatAllowFromLowercase` |
-  | `plugin-sdk/allowlist-resolution` | Allowlist 输入映射 | `mapAllowlistResolutionInputs` |
-  | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具，包括动态参数菜单格式化 |
+  | `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` |
+  | `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` |
+  | `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具（包括动态参数菜单格式化） |
  | `plugin-sdk/command-status` | 命令 Status/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
-  | `plugin-sdk/secret-input` | Secret 输入解析 | Secret 输入辅助工具 |
+  | `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 |
  | `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标实用工具 |
-  | `plugin-sdk/webhook-request-guards` | webhook 请求体守卫辅助工具 | 请求体读取/限制辅助工具 |
+  | `plugin-sdk/webhook-request-guards` | webhook body 守卫辅助工具 | 请求体读取/限制辅助工具 |
  | `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 |
-  | `plugin-sdk/reply-dispatch-runtime` | 窄化回复分发辅助工具 | 终结、provider 分发和会话标签辅助工具 |
+  | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | 最终化、provider 分发和会话标签辅助工具 |
  | `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
  | `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` |
-  | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/markdown 分块辅助工具 |
+  | `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/Markdown 分块辅助工具 |
  | `plugin-sdk/session-store-runtime` | 会话存储辅助工具 | 存储路径 + updated-at 辅助工具 |
  | `plugin-sdk/state-paths` | 状态路径辅助工具 | 状态和 OAuth 目录辅助工具 |
  | `plugin-sdk/routing` | 路由/会话键辅助工具 | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、会话键规范化辅助工具 |
@ -392,92 +392,94 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
  | `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类请求输入中提取字符串 URL |
  | `plugin-sdk/run-command` | 定时命令辅助工具 | 带规范化 stdout/stderr 的定时命令运行器 |
  | `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 |
-  | `plugin-sdk/tool-payload` | 工具载荷提取 | 从工具结果对象中提取规范化载荷 |
+  | `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取规范化负载 |
  | `plugin-sdk/tool-send` | 工具发送提取 | 从工具参数中提取规范发送目标字段 |
  | `plugin-sdk/temp-path` | 临时路径辅助工具 | 共享临时下载路径辅助工具 |
  | `plugin-sdk/logging-core` | Logging 辅助工具 | 子系统 logger 和脱敏辅助工具 |
  | `plugin-sdk/markdown-table-runtime` | Markdown 表格辅助工具 | Markdown 表格模式辅助工具 |
-  | `plugin-sdk/reply-payload` | 消息回复类型 | 回复载荷类型 |
+  | `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 |
  | `plugin-sdk/provider-setup` | 精选的本地/自托管 provider 设置辅助工具 | 自托管 provider 发现/配置辅助工具 |
-  | `plugin-sdk/self-hosted-provider-setup` | 聚焦式 OpenAI 兼容自托管 provider 设置辅助工具 | 同一组自托管 provider 发现/配置辅助工具 |
+  | `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI-compatible 自托管 provider 设置辅助工具 | 相同的自托管 provider 发现/配置辅助工具 |
  | `plugin-sdk/provider-auth-runtime` | provider 运行时 auth 辅助工具 | 运行时 API key 解析辅助工具 |
  | `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导/profile 写入辅助工具 |
  | `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 |
  | `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 |
  | `plugin-sdk/provider-selection-runtime` | provider 选择辅助工具 | 已配置或自动 provider 选择，以及原始 provider 配置合并 |
  | `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider auth 环境变量查找辅助工具 |
-  | `plugin-sdk/provider-model-shared` | 共享 provider 模型/replay 辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider endpoint 辅助工具，以及 model-id 规范化辅助工具 |
-  | `plugin-sdk/provider-catalog-shared` | 共享 provider catalog 辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
-  | `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 |
+  | `plugin-sdk/provider-model-shared` | 共享 provider 模型/replay 辅助工具 | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、provider endpoint 辅助工具，以及 model-id 规范化辅助工具 |
+  | `plugin-sdk/provider-catalog-shared` | 共享 provider catalog 辅助工具 | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
+  | `plugin-sdk/provider-onboard` | provider onboarding 补丁 | onboarding 配置辅助工具 |
  | `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP/endpoint capability 辅助工具，包括音频转录 multipart form 辅助工具 |
  | `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册/缓存辅助工具 |
-  | `plugin-sdk/provider-web-search-config-contract` | provider web-search 配置辅助工具 | 面向不需要插件启用接线的 provider 的窄化 web-search 配置/凭证辅助工具 |
-  | `plugin-sdk/provider-web-search-contract` | provider web-search 契约辅助工具 | 窄化的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化的凭证 setter/getter |
+  | `plugin-sdk/provider-web-search-config-contract` | provider web-search 配置辅助工具 | 针对不需要插件启用连接逻辑的 provider，提供窄范围 web-search 配置/凭证辅助工具 |
+  | `plugin-sdk/provider-web-search-contract` | provider web-search 契约辅助工具 | 窄范围 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化凭证 setter/getter |
  | `plugin-sdk/provider-web-search` | provider web-search 辅助工具 | web-search provider 注册/缓存/运行时辅助工具 |
-  | `plugin-sdk/provider-tools` | provider 工具/schema 兼容性辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
-  | `plugin-sdk/provider-usage` | provider 用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`，以及其他 provider 用量辅助工具 |
-  | `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
-  | `plugin-sdk/provider-transport-runtime` | provider 传输辅助工具 | 原生 provider 传输辅助工具，例如受保护 fetch、传输消息转换和可写传输事件流 |
+  | `plugin-sdk/provider-tools` | provider 工具/schema 兼容性辅助工具 | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容性辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
+  | `plugin-sdk/provider-usage` | provider 使用量辅助工具 | `fetchClaudeUsage`、`fetchGeminiUsage`、`fetchGithubCopilotUsage` 以及其他 provider 使用量辅助工具 |
+  | `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装辅助工具 |
+  | `plugin-sdk/provider-transport-runtime` | provider 传输辅助工具 | 原生 provider 传输辅助工具，例如受保护 fetch、传输消息变换和可写传输事件流 |
  | `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` |
-  | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体 fetch/转换/存储辅助工具，以及媒体载荷构建器 |
-  | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像/视频/音乐生成的共享 failover 辅助工具、候选项选择和缺失模型提示 |
+  | `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取/转换/存储辅助工具，以及媒体负载构建器 |
+  | `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像/视频/音乐生成的共享故障转移辅助工具、候选项选择和缺失模型提示 |
  | `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像/音频辅助工具导出 |
-  | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 对智能体可见文本的剥离、markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本实用工具，以及相关文本/Logging 辅助工具 |
+  | `plugin-sdk/text-runtime` | 共享文本辅助工具 | 面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本实用工具，以及相关文本/日志辅助工具 |
  | `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 |
-  | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的 directive、注册表、校验辅助工具和 OpenAI 兼容 TTS 构建器 |
-  | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、directives、规范化 |
+  | `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的 directive、注册表、校验辅助工具和 OpenAI-compatible TTS 构建器 |
+  | `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、directive、规范化 |
  | `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 |
-  | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具和 bridge 会话辅助工具 |
-  | `plugin-sdk/image-generation` | 图像生成辅助工具 | 图像生成 provider 类型，以及图像资产/data URL 辅助工具和 OpenAI 兼容图像 provider 构建器 |
-  | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、failover、auth 和注册表辅助工具 |
-  | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider/request/result 类型 |
-  | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、failover 辅助工具、provider 查找和 model-ref 解析 |
-  | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider/request/result 类型 |
-  | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、failover 辅助工具、provider 查找和 model-ref 解析 |
-  | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复载荷规范化/归约 |
-  | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄化渠道 config-schema 原语 |
+  | `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具和桥接会话辅助工具 |
+  | `plugin-sdk/image-generation` | 图像生成辅助工具 | 图像生成 provider 类型，以及图像资源/data URL 辅助工具和 OpenAI-compatible 图像 provider 构建器 |
+  | `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、故障转移、auth 和注册表辅助工具 |
+  | `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider/请求/结果类型 |
+  | `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 |
+  | `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider/请求/结果类型 |
+  | `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、故障转移辅助工具、provider 查找和 model-ref 解析 |
+  | `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化/归约 |
+  | `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道 config-schema 原语 |
  | `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 |
  | `plugin-sdk/channel-plugin-common` | 共享渠道前导模块 | 共享渠道插件前导导出 |
  | `plugin-sdk/channel-status` | 渠道 Status 辅助工具 | 共享渠道 Status 快照/摘要辅助工具 |
-  | `plugin-sdk/allowlist-config-edit` | Allowlist 配置辅助工具 | Allowlist 配置编辑/读取辅助工具 |
+  | `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑/读取辅助工具 |
  | `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 |
  | `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信 auth/守卫辅助工具 |
-  | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/Status 和环境式 proxy 辅助原语 |
+  | `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/Status 和环境代理辅助原语 |
  | `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 |
  | `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径规范化辅助工具 |
  | `plugin-sdk/web-media` | 共享 Web 媒体辅助工具 | 远程/本地媒体加载辅助工具 |
-  | `plugin-sdk/zod` | Zod 重新导出 | 面向插件 SDK 使用者重新导出的 `zod` |
-  | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | 内存管理器/配置/文件/CLI 辅助接口 |
-  | `plugin-sdk/memory-core-engine-runtime` | 内存引擎运行时门面 | 内存索引/搜索运行时门面 |
-  | `plugin-sdk/memory-core-host-engine-foundation` | 内存宿主基础引擎 | 内存宿主基础引擎导出 |
-  | `plugin-sdk/memory-core-host-engine-embeddings` | 内存宿主嵌入引擎 | 内存嵌入契约、注册表访问、本地 provider 和通用批处理/远程辅助工具；具体远程 provider 位于其所属插件中 |
-  | `plugin-sdk/memory-core-host-engine-qmd` | 内存宿主 QMD 引擎 | 内存宿主 QMD 引擎导出 |
-  | `plugin-sdk/memory-core-host-engine-storage` | 内存宿主存储引擎 | 内存宿主存储引擎导出 |
-  | `plugin-sdk/memory-core-host-multimodal` | 内存宿主多模态辅助工具 | 内存宿主多模态辅助工具 |
-  | `plugin-sdk/memory-core-host-query` | 内存宿主查询辅助工具 | 内存宿主查询辅助工具 |
-  | `plugin-sdk/memory-core-host-secret` | 内存宿主 secret 辅助工具 | 内存宿主 secret 辅助工具 |
-  | `plugin-sdk/memory-core-host-events` | 内存宿主事件日志辅助工具 | 内存宿主事件日志辅助工具 |
-  | `plugin-sdk/memory-core-host-status` | 内存宿主 Status 辅助工具 | 内存宿主 Status 辅助工具 |
-  | `plugin-sdk/memory-core-host-runtime-cli` | 内存宿主 CLI 运行时 | 内存宿主 CLI 运行时辅助工具 |
-  | `plugin-sdk/memory-core-host-runtime-core` | 内存宿主核心运行时 | 内存宿主核心运行时辅助工具 |
-  | `plugin-sdk/memory-core-host-runtime-files` | 内存宿主文件/运行时辅助工具 | 内存宿主文件/运行时辅助工具 |
-  | `plugin-sdk/memory-host-core` | 内存宿主核心运行时别名 | 面向供应商中立的内存宿主核心运行时辅助工具别名 |
-  | `plugin-sdk/memory-host-events` | 内存宿主事件日志别名 | 面向供应商中立的内存宿主事件日志辅助工具别名 |
-  | `plugin-sdk/memory-host-files` | 内存宿主文件/运行时别名 | 面向供应商中立的内存宿主文件/运行时辅助工具别名 |
-  | `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向 memory 相关插件的共享托管 markdown 辅助工具 |
-  | `plugin-sdk/memory-host-search` | 活跃内存搜索门面 | 惰性 active-memory search-manager 运行时门面 |
-  | `plugin-sdk/memory-host-status` | 内存宿主 Status 别名 | 面向供应商中立的内存宿主 Status 辅助工具别名 |
-  | `plugin-sdk/memory-lancedb` | 内置 Memory LanceDB 辅助工具 | Memory LanceDB 辅助接口 |
-  | `plugin-sdk/testing` | 测试工具 | 旧版宽泛兼容性 barrel；优先使用聚焦式测试子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/channel-target-testing`、`plugin-sdk/test-env` 和 `plugin-sdk/test-fixtures` |
+  | `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用者重新导出的 `zod` |
+  | `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | memory manager/配置/文件/CLI 辅助工具接口 |
+  | `plugin-sdk/memory-core-engine-runtime` | memory 引擎运行时门面 | memory 索引/搜索运行时门面 |
+  | `plugin-sdk/memory-core-host-engine-foundation` | memory host 基础引擎 | memory host 基础引擎导出 |
+  | `plugin-sdk/memory-core-host-engine-embeddings` | memory host embedding 引擎 | memory embedding 契约、注册表访问、本地 provider 和通用批处理/远程辅助工具；具体远程 provider 位于其所属插件中 |
+  | `plugin-sdk/memory-core-host-engine-qmd` | memory host QMD 引擎 | memory host QMD 引擎导出 |
+  | `plugin-sdk/memory-core-host-engine-storage` | memory host 存储引擎 | memory host 存储引擎导出 |
+  | `plugin-sdk/memory-core-host-multimodal` | memory host 多模态辅助工具 | memory host 多模态辅助工具 |
+  | `plugin-sdk/memory-core-host-query` | memory host 查询辅助工具 | memory host 查询辅助工具 |
+  | `plugin-sdk/memory-core-host-secret` | memory host 密钥辅助工具 | memory host 密钥辅助工具 |
+  | `plugin-sdk/memory-core-host-events` | memory host 事件日志辅助工具 | memory host 事件日志辅助工具 |
+  | `plugin-sdk/memory-core-host-status` | memory host Status 辅助工具 | memory host Status 辅助工具 |
+  | `plugin-sdk/memory-core-host-runtime-cli` | memory host CLI 运行时 | memory host CLI 运行时辅助工具 |
+  | `plugin-sdk/memory-core-host-runtime-core` | memory host 核心运行时 | memory host 核心运行时辅助工具 |
+  | `plugin-sdk/memory-core-host-runtime-files` | memory host 文件/运行时辅助工具 | memory host 文件/运行时辅助工具 |
+  | `plugin-sdk/memory-host-core` | memory host 核心运行时别名 | 面向 vendor-neutral 的 memory host 核心运行时辅助工具别名 |
+  | `plugin-sdk/memory-host-events` | memory host 事件日志别名 | 面向 vendor-neutral 的 memory host 事件日志辅助工具别名 |
+  | `plugin-sdk/memory-host-files` | memory host 文件/运行时别名 | 面向 vendor-neutral 的 memory host 文件/运行时辅助工具别名 |
+  | `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助工具 | 面向 memory 相邻插件的共享托管 Markdown 辅助工具 |
+  | `plugin-sdk/memory-host-search` | 活跃 memory 搜索门面 | 惰性活跃 memory search-manager 运行时门面 |
+  | `plugin-sdk/memory-host-status` | memory host Status 别名 | 面向 vendor-neutral 的 memory host Status 辅助工具别名 |
+  | `plugin-sdk/memory-lancedb` | 内置 Memory LanceDB 辅助工具 | Memory LanceDB 辅助工具接口 |
+  | `plugin-sdk/testing` | 测试实用工具 | 旧版宽泛兼容性 barrel；优先使用聚焦的测试子路径，例如 `plugin-sdk/plugin-test-runtime`、`plugin-sdk/channel-test-helpers`、`plugin-sdk/channel-target-testing`、`plugin-sdk/test-env` 和 `plugin-sdk/test-fixtures` |
 </Accordion>

-这个表格刻意只包含常见迁移子集，而不是完整的 SDK
-接口。完整的 200+ 个入口点列表位于
+此表有意只列出常见迁移子集，而非完整的 SDK
+接口。完整的 200+ 入口点列表位于
 `scripts/lib/plugin-sdk-entrypoints.json`。

-该列表仍然包含一些内置插件辅助接口，例如
+该列表仍包含一些内置插件辅助接口，例如
 `plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、
-`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些接口仍会继续导出，以支持内置插件维护和兼容性，但它们被有意排除在常见迁移表之外，也不是新插件代码的推荐目标。
+`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些导出仍保留，用于
+内置插件维护和兼容性，但它们被有意排除在常见迁移表之外，也不是
+新插件代码的推荐目标。

 同样的规则也适用于其他内置辅助工具家族，例如：

@ -495,22 +497,26 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
  `plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`，
  以及 `plugin-sdk/voice-call`

-`plugin-sdk/github-copilot-token` 当前暴露的是窄化的令牌辅助工具接口：
+`plugin-sdk/github-copilot-token` 当前公开了窄范围令牌辅助工具接口
 `DEFAULT_COPILOT_API_BASE_URL`、
 `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。

-请使用与你的任务最匹配的最窄导入路径。如果你找不到某个导出，请检查 `src/plugin-sdk/` 中的源码，或在 Discord 中提问。
+请使用与任务最匹配的最窄导入路径。如果你找不到某个导出，
+请检查 `src/plugin-sdk/` 中的源码，或在 Discord 中提问。

-## 当前活跃的弃用项
+## 当前弃用项

-这些是适用于插件 SDK、provider 契约、运行时接口和 manifest 的更窄范围弃用项。它们目前仍然可用，但会在未来的主版本中被移除。每一项下方的条目都将旧 API 映射到其规范替代项。
+这些范围更窄的弃用项适用于整个插件 SDK、provider 契约、
+运行时接口和 manifest。它们当前仍可使用，但将在未来的主要版本中移除。
+每个条目下方都会将旧 API 映射到其规范替代方案。

 <AccordionGroup>
  <Accordion title="command-auth 帮助构建器 → command-status">
    **旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`、
    `buildCommandsMessagePaginated`、`buildHelpMessage`。

-    **新版（`openclaw/plugin-sdk/command-status`）**：签名相同、导出相同——只是改为从更窄的子路径导入。`command-auth`
+    **新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出也相同——
+    只是改为从更窄的子路径导入。`command-auth`
    会将它们作为兼容性 stub 重新导出。

    ```typescript
@ -529,71 +535,89 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
    `openclaw/plugin-sdk/channel-inbound` 或
    `openclaw/plugin-sdk/channel-mention-gating`。

-    **新版**：`resolveInboundMentionDecision({ facts, policy })` —— 它返回的是单个决策对象，而不是拆分成两次调用。
+    **新版**：`resolveInboundMentionDecision({ facts, policy })` —— 返回
+    单个决策对象，而不是拆分成两个调用。

-    下游渠道插件（Slack、Discord、Matrix、Microsoft Teams）都已经完成切换。
+    下游渠道插件（Slack、Discord、Matrix、Microsoft Teams）已经完成切换。

  </Accordion>

-  <Accordion title="渠道运行时 shim 和渠道 actions 辅助工具">
-    `openclaw/plugin-sdk/channel-runtime` 是为旧版渠道插件提供的兼容性 shim。新代码不要导入它；请使用
-    `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时对象。
+  <Accordion title="渠道运行时 shim 和渠道动作辅助工具">
+    `openclaw/plugin-sdk/channel-runtime` 是为旧版
+    渠道插件提供的兼容性 shim。新代码不要导入它；请使用
+    `openclaw/plugin-sdk/channel-runtime-context` 来注册运行时
+    对象。

-    `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助工具与原始的 “actions” 渠道导出一同被弃用。请改为通过语义化的 `presentation` 接口暴露 capabilities —— 渠道插件声明它们渲染什么（cards、buttons、selects），而不是声明它们接受哪些原始 action 名称。
+    `openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助工具
+    会与原始 “actions” 渠道导出一起被弃用。应改为通过语义化的
+    `presentation` 接口公开能力——渠道插件声明自己渲染什么
+    （cards、buttons、selects），而不是声明它接受哪些原始
+    action 名称。

  </Accordion>

  <Accordion title="Web 搜索 provider tool() 辅助工具 → 插件上的 createTool()">
-    **旧版**：来自 `openclaw/plugin-sdk/provider-web-search` 的 `tool()` 工厂。
+    **旧版**：`openclaw/plugin-sdk/provider-web-search` 中的 `tool()` 工厂。

    **新版**：直接在 provider 插件上实现 `createTool(...)`。
-    OpenClaw 不再需要 SDK 辅助工具来注册该工具包装器。
+    OpenClaw 不再需要这个 SDK 辅助工具来注册工具包装器。

  </Accordion>

  <Accordion title="纯文本渠道 envelope → BodyForAgent">
    **旧版**：`formatInboundEnvelope(...)`（以及
-    `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平纯文本提示 envelope。
+    `ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建
+    扁平纯文本提示 envelope。

-    **新版**：`BodyForAgent` 加上结构化的用户上下文块。渠道插件会将路由元数据（thread、topic、reply-to、reactions）附加为类型化字段，而不是把它们拼接到提示字符串中。
-    `formatAgentEnvelope(...)` 辅助工具对合成的面向助手的 envelope 仍然受支持，但入站纯文本 envelope 正在逐步淘汰。
+    **新版**：`BodyForAgent` 加上结构化用户上下文块。渠道
+    插件通过带类型字段附加路由元数据（线程、主题、reply-to、reactions），
+    而不是将它们拼接进提示字符串中。
+    `formatAgentEnvelope(...)` 辅助工具仍支持用于合成的面向助手的
+    envelope，但入站纯文本 envelope 正在逐步淘汰。

-    受影响区域：`inbound_claim`、`message_received`，以及任何会后处理 `channelEnvelope` 文本的自定义渠道插件。
+    受影响区域：`inbound_claim`、`message_received`，以及任何对
+    `channelEnvelope` 文本进行后处理的自定义渠道插件。

  </Accordion>

  <Accordion title="Provider 发现类型 → provider catalog 类型">
-    四个发现类型别名现在已变成 catalog 时代类型的薄包装：
+    4 个 discovery 类型别名现已成为 catalog 时代类型的薄包装：

    | 旧别名 | 新类型 |
    | ------------------------- | ------------------------- |
-    | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` |
-    | `ProviderDiscoveryContext`| `ProviderCatalogContext` |
-    | `ProviderDiscoveryResult` | `ProviderCatalogResult` |
-    | `ProviderPluginDiscovery` | `ProviderPluginCatalog` |
+    | `ProviderDiscoveryOrder`  | `ProviderCatalogOrder`    |
+    | `ProviderDiscoveryContext`| `ProviderCatalogContext`  |
+    | `ProviderDiscoveryResult` | `ProviderCatalogResult`   |
+    | `ProviderPluginDiscovery` | `ProviderPluginCatalog`   |

-    此外，还有旧版 `ProviderCapabilities` 静态对象——provider 插件应通过 provider 运行时契约附加 capability 事实，而不是使用静态对象。
+    另外还有旧版 `ProviderCapabilities` 静态对象——provider 插件
+    应通过 provider 运行时契约附加 capability 事实，
+    而不是通过静态对象。

  </Accordion>

-  <Accordion title="Thinking 策略 hooks → resolveThinkingProfile">
-    **旧版**（`ProviderThinkingPolicy` 上的三个独立 hook）：
+  <Accordion title="Thinking 策略钩子 → resolveThinkingProfile">
+    **旧版**（`ProviderThinkingPolicy` 上的 3 个独立钩子）：
    `isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和
    `resolveDefaultThinkingLevel(ctx)`。

-    **新版**：单一的 `resolveThinkingProfile(ctx)`，它返回一个
-    `ProviderThinkingProfile`，其中包含规范的 `id`、可选的 `label` 以及按等级排序的 level 列表。OpenClaw 会根据 profile rank 自动降级过时的已存储值。
+    **新版**：单个 `resolveThinkingProfile(ctx)`，返回一个
+    `ProviderThinkingProfile`，包含规范 `id`、可选 `label` 和
+    排序后的级别列表。OpenClaw 会按照 profile 排名自动降级
+    过期的已存储值。

-    现在实现一个 hook 即可，不再需要三个。旧版 hooks 在弃用窗口期间仍可继续使用，但不会与 profile 结果进行组合。
+    只需实现一个钩子，而不是 3 个。旧版钩子在弃用窗口期内仍可工作，
+    但不会与 profile 结果组合使用。

  </Accordion>

  <Accordion title="外部 OAuth provider 回退 → contracts.externalAuthProviders">
-    **旧版**：在插件 manifest 中未声明 provider 的情况下，实现 `resolveExternalOAuthProfiles(...)`。
+    **旧版**：实现 `resolveExternalOAuthProfiles(...)`，但没有
+    在插件 manifest 中声明该 provider。

    **新版**：在插件 manifest 中声明 `contracts.externalAuthProviders`
-    **并且**实现 `resolveExternalAuthProfiles(...)`。旧版的 “auth
-    fallback” 路径会在运行时发出警告，并将在未来被移除。
+    **并且** 实现 `resolveExternalAuthProfiles(...)`。旧版的 “auth
+    回退” 路径会在运行时发出警告，并将在未来移除。

    ```json
    {
@ -608,46 +632,48 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
  <Accordion title="Provider 环境变量查找 → setup.providers[].envVars">
    **旧版** manifest 字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。

-    **新版**：将相同的环境变量查找镜像到 manifest 中的 `setup.providers[].envVars`。
-    这样可以将设置/Status 环境变量元数据整合到一个位置，并避免仅为回答环境变量查找而启动插件运行时。
+    **新版**：将相同的环境变量查找镜像到 manifest 中的 `setup.providers[].envVars`
+    中。这会将设置/Status 的环境变量元数据整合到一个
+    位置，并避免为了响应环境变量查找而启动插件运行时。

-    `providerAuthEnvVars` 会通过兼容性适配器继续受支持，直到弃用窗口结束。
+    `providerAuthEnvVars` 在弃用窗口关闭前，仍会通过兼容性适配器
+    继续受支持。

  </Accordion>

-  <Accordion title="内存插件注册 → registerMemoryCapability">
-    **旧版**：三个独立调用——
+  <Accordion title="Memory 插件注册 → registerMemoryCapability">
+    **旧版**：3 个独立调用——
    `api.registerMemoryPromptSection(...)`、
    `api.registerMemoryFlushPlan(...)`、
    `api.registerMemoryRuntime(...)`。

-    **新版**：在内存状态 API 上使用一次调用——
+    **新版**：在 memory-state API 上进行 1 次调用——
    `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。

-    相同的插槽，单一的注册调用。附加型内存辅助工具
+    相同插槽，单次注册调用。增量 memory 辅助工具
    （`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、
    `registerMemoryEmbeddingProvider`）不受影响。

  </Accordion>

  <Accordion title="Subagent 会话消息类型已重命名">
-    两个旧版类型别名仍然从 `src/plugins/runtime/types.ts` 导出：
+    仍从 `src/plugins/runtime/types.ts` 导出的两个旧版类型别名：

    | 旧版 | 新版 |
    | ----------------------------- | ------------------------------- |
-    | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` |
-    | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` |
+    | `SubagentReadSessionParams`   | `SubagentGetSessionMessagesParams` |
+    | `SubagentReadSessionResult`   | `SubagentGetSessionMessagesResult` |

-    运行时方法 `readSession` 已弃用，改用
-    `getSessionMessages`。
-    签名相同；旧方法会透传调用新方法。
+    运行时方法 `readSession` 已被弃用，取而代之的是
+    `getSessionMessages`。签名相同；旧方法会转调到新方法。

  </Accordion>

  <Accordion title="runtime.tasks.flow → runtime.tasks.flows">
-    **旧版**：`runtime.tasks.flow`（单数）返回一个实时任务流访问器。
+    **旧版**：`runtime.tasks.flow`（单数）返回一个实时 task-flow 访问器。

-    **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问，这种方式是导入安全的，而且不需要加载完整的任务运行时。
+    **新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问，
+    这样可安全导入，并且不需要加载完整任务运行时。

    ```typescript
    // 之前
@ -659,14 +685,17 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
  </Accordion>

  <Accordion title="嵌入式扩展工厂 → 智能体工具结果中间件">
-    上文“如何迁移 → 将 Pi 工具结果扩展迁移到中间件”中已覆盖。这里为完整起见再次列出：已移除、仅供 Pi 使用的
-    `api.registerEmbeddedExtensionFactory(...)` 路径，现由
-    `api.registerAgentToolResultMiddleware(...)` 替代，并在 `contracts.agentToolResultMiddleware` 中显式声明运行时列表。
+    上文“如何迁移 → 将 Pi 工具结果扩展迁移到
+    中间件”中已经介绍。这里为了完整性再次列出：已移除的仅限 Pi 的
+    `api.registerEmbeddedExtensionFactory(...)` 路径已被
+    `api.registerAgentToolResultMiddleware(...)` 替代，并要求在
+    `contracts.agentToolResultMiddleware` 中显式声明运行时
+    列表。
  </Accordion>

  <Accordion title="OpenClawSchemaType 别名 → OpenClawConfig">
-    从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType`
-    现在只是 `OpenClawConfig` 的单行别名。请优先使用规范名称。
+    从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在只是
+    `OpenClawConfig` 的一行别名。请优先使用规范名称。

    ```typescript
    // 之前
@ -679,8 +708,11 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
 </AccordionGroup>

 <Note>
-扩展级弃用项（位于 `extensions/` 下的内置渠道/provider 插件内部）会在它们各自的 `api.ts` 和 `runtime-api.ts`
-barrel 中进行跟踪。它们不影响第三方插件契约，因此不在此列出。如果你直接使用某个内置插件的本地 barrel，请在升级前阅读该 barrel 中的弃用注释。
+扩展级别的弃用项（位于 `extensions/` 下的内置渠道/provider 插件内部）
+会在它们各自的 `api.ts` 和 `runtime-api.ts`
+barrel 中跟踪。它们不影响第三方插件契约，因此未在此列出。
+如果你直接使用某个内置插件的本地 barrel，请在升级前先阅读
+该 barrel 中的弃用注释。
 </Note>

 ## 移除时间线
@ -688,20 +720,20 @@ barrel 中进行跟踪。它们不影响第三方插件契约，因此不在此
 | 时间 | 会发生什么 |
 | ---------------------- | ----------------------------------------------------------------------- |
 | **现在** | 已弃用接口会发出运行时警告 |
-| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 |
+| **下一个主要版本** | 已弃用接口将被移除；仍在使用它们的插件将会失败 |

-所有核心插件都已经完成迁移。外部插件应在下一个主版本之前完成迁移。
+所有核心插件都已经完成迁移。外部插件应在下一个主要版本之前完成迁移。

 ## 临时抑制警告

-在迁移过程中，可设置以下环境变量：
+在你处理迁移期间，可设置以下环境变量：

 ```bash
 OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
 OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
 ```

-这只是临时性的应急出口，不是永久解决方案。
+这是临时的逃生口，不是永久解决方案。

 ## 相关内容

@ -709,5 +741,5 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
 - [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考
 - [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
 - [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建提供商插件
- [插件内部机制](/zh-CN/plugins/architecture) — 架构深入解析
+- [插件架构内部机制](/zh-CN/plugins/architecture) — 架构深度解析
 - [插件 Manifest](/zh-CN/plugins/manifest) — manifest schema 参考