chore(i18n): refresh zh-CN translations

2026-04-24 17:02:27 +00:00 · 2026-04-24 17:02:27 +00:00 · 04dfff11ec
commit 04dfff11ec
parent 02663410ce
8 changed files with 1400 additions and 1355 deletions
--- a/docs/zh-CN/channels/index.md
+++ b/docs/zh-CN/channels/index.md
@ -1,55 +1,60 @@
 ---
 read_when:
    - 你想为 OpenClaw 选择一个聊天渠道
-    - 你需要一个受支持消息平台的快速概览
+    - 你需要快速了解受支持的消息平台概览
 summary: OpenClaw 可连接的消息平台
 title: 聊天渠道
 x-i18n:
-    generated_at: "2026-04-23T20:41:17Z"
+    generated_at: "2026-04-24T16:58:30Z"
    model: gpt-5.4
    provider: openai
-    source_hash: c016b78b16724e73b21946d6bed0009f4cbebd1f887620431b9b4bff70f2b1ff
+    source_hash: e97818dce89ea06a60f2cccd0cc8a78cba48d66ea39e4769f2b583690a4f75d0
    source_path: channels/index.md
    workflow: 15
 ---

 OpenClaw 可以通过你已经在使用的任何聊天应用与你交流。每个渠道都通过 Gateway 网关连接。
-所有渠道都支持文本；媒体和表情回应支持会因渠道而异。
+所有渠道都支持文本；媒体和回应功能则因渠道而异。
+
+## 传递说明
+
+- Telegram 回复中包含 Markdown 图片语法（例如 `![alt](url)`）时，在最终出站路径上会尽可能转换为媒体回复。
+- Slack 多人私信会按群聊路由，因此群组策略、提及行为以及群组会话规则同样适用于 MPIM 对话。
+- WhatsApp 采用按需安装的设置方式：新手引导可以在 Baileys 运行时依赖完成准备之前先展示设置流程，而 Gateway 网关仅在该渠道实际启用时才加载 WhatsApp 运行时。

 ## 支持的渠道

- [BlueBubbles](/zh-CN/channels/bluebubbles) — **iMessage 的推荐方案**；使用 BlueBubbles macOS 服务器 REST API，提供完整功能支持（内置插件；编辑、撤回、效果、表情回应、群组管理——编辑功能目前在 macOS 26 Tahoe 上不可用）。
- [Discord](/zh-CN/channels/discord) — Discord Bot API + Gateway 网关；支持服务器、频道和私信。
- [Feishu](/zh-CN/channels/feishu) — 通过 WebSocket 的 Feishu/Lark 机器人（内置插件）。
- [Google Chat](/zh-CN/channels/googlechat) — 通过 HTTP webhook 的 Google Chat API 应用。
- [iMessage (legacy)](/zh-CN/channels/imessage) — 基于 imsg CLI 的传统 macOS 集成（已弃用，新部署请使用 BlueBubbles）。
- [IRC](/zh-CN/channels/irc) — 经典 IRC 服务器；支持频道和私信，并带有配对/允许列表控制。
+- [BlueBubbles](/zh-CN/channels/bluebubbles) — **iMessage 的推荐方案**；使用 BlueBubbles macOS 服务器 REST API，并提供完整功能支持（内置插件；编辑、撤回、特效、回应、群组管理——编辑功能目前在 macOS 26 Tahoe 上不可用）。
+- [Discord](/zh-CN/channels/discord) — Discord Bot API + Gateway 网关；支持服务器、渠道和私信。
+- [Feishu](/zh-CN/channels/feishu) — 通过 WebSocket 连接的 Feishu/Lark 机器人（内置插件）。
+- [Google Chat](/zh-CN/channels/googlechat) — 通过 HTTP webhook 接入的 Google Chat API 应用。
+- [iMessage（旧版）](/zh-CN/channels/imessage) — 通过 imsg CLI 提供的旧版 macOS 集成（已弃用，新设置请使用 BlueBubbles）。
+- [IRC](/zh-CN/channels/irc) — 经典 IRC 服务器；支持渠道和私信，并带有配对/允许列表控制。
 - [LINE](/zh-CN/channels/line) — LINE Messaging API 机器人（内置插件）。
 - [Matrix](/zh-CN/channels/matrix) — Matrix 协议（内置插件）。
- [Mattermost](/zh-CN/channels/mattermost) — Bot API + WebSocket；支持频道、群组、私信（内置插件）。
+- [Mattermost](/zh-CN/channels/mattermost) — Bot API + WebSocket；支持渠道、群组、私信（内置插件）。
 - [Microsoft Teams](/zh-CN/channels/msteams) — Bot Framework；支持企业场景（内置插件）。
 - [Nextcloud Talk](/zh-CN/channels/nextcloud-talk) — 通过 Nextcloud Talk 提供的自托管聊天（内置插件）。
- [Nostr](/zh-CN/channels/nostr) — 通过 NIP-04 的去中心化私信（内置插件）。
+- [Nostr](/zh-CN/channels/nostr) — 通过 NIP-04 实现的去中心化私信（内置插件）。
 - [QQ Bot](/zh-CN/channels/qqbot) — QQ Bot API；支持私聊、群聊和富媒体（内置插件）。
- [Signal](/zh-CN/channels/signal) — `signal-cli`；注重隐私。
- [Slack](/zh-CN/channels/slack) — Bolt SDK；工作区应用。
- [Synology Chat](/zh-CN/channels/synology-chat) — 通过出站 + 入站 webhook 的 Synology NAS Chat（内置插件）。
- [Telegram](/zh-CN/channels/telegram) — 通过 grammY 的 Bot API；支持群组。
- [Tlon](/zh-CN/channels/tlon) — 基于 Urbit 的消息工具（内置插件）。
- [Twitch](/zh-CN/channels/twitch) — 通过 IRC 连接接入 Twitch 聊天（内置插件）。
- [Voice Call](/zh-CN/plugins/voice-call) — 通过 Plivo 或 Twilio 提供电话功能（插件，需单独安装）。
- [WebChat](/zh-CN/web/webchat) — 通过 WebSocket 的 Gateway 网关 WebChat UI。
- [WeChat](/zh-CN/channels/wechat) — 通过扫码登录的腾讯 iLink Bot 插件；仅支持私聊（外部插件）。
- [WhatsApp](/zh-CN/channels/whatsapp) — 最常用；使用 Baileys，并需要扫码配对。
+- [Signal](/zh-CN/channels/signal) — signal-cli；注重隐私。
+- [Slack](/zh-CN/channels/slack) — Bolt SDK；适用于工作区应用。
+- [Synology Chat](/zh-CN/channels/synology-chat) — 通过出站 + 入站 webhook 接入的 Synology NAS Chat（内置插件）。
+- [Telegram](/zh-CN/channels/telegram) — 通过 grammY 接入的 Bot API；支持群组。
+- [Tlon](/zh-CN/channels/tlon) — 基于 Urbit 的消息应用（内置插件）。
+- [Twitch](/zh-CN/channels/twitch) — 通过 IRC 连接接入的 Twitch 聊天（内置插件）。
+- [Voice Call](/zh-CN/plugins/voice-call) — 通过 Plivo 或 Twilio 提供的电话功能（插件，需单独安装）。
+- [WebChat](/zh-CN/web/webchat) — 通过 WebSocket 提供的 Gateway 网关 WebChat UI。
+- [微信](/zh-CN/channels/wechat) — 通过二维码登录的腾讯 iLink Bot 插件；仅支持私聊（外部插件）。
+- [WhatsApp](/zh-CN/channels/whatsapp) — 最常用；使用 Baileys，并需要二维码配对。
 - [Zalo](/zh-CN/channels/zalo) — Zalo Bot API；越南流行的消息应用（内置插件）。
- [Zalo Personal](/zh-CN/channels/zalouser) — 通过扫码登录的 Zalo 个人账户（内置插件）。
+- [Zalo Personal](/zh-CN/channels/zalouser) — 通过二维码登录的 Zalo 个人账号（内置插件）。

-## 注意事项
+## 说明

- 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天进行路由。
- 通常最快的设置方式是 **Telegram**（只需简单的机器人令牌）。WhatsApp 需要扫码配对，
-  并会在磁盘上存储更多状态。
+- 渠道可以同时运行；配置多个渠道后，OpenClaw 会按聊天分别路由。
+- 通常最快的设置方式是 **Telegram**（简单的机器人令牌）。WhatsApp 需要二维码配对，并会在磁盘上存储更多状态。
 - 群组行为因渠道而异；参见 [Groups](/zh-CN/channels/groups)。
 - 出于安全考虑，会强制执行私信配对和允许列表；参见 [Security](/zh-CN/gateway/security)。
- 故障排除：[渠道故障排除](/zh-CN/channels/troubleshooting)。
- 模型提供商文档单独提供；参见 [模型提供商](/zh-CN/providers/models)。
+- 故障排除：参见 [Channel troubleshooting](/zh-CN/channels/troubleshooting)。
+- 模型提供商单独提供文档；参见 [Model Providers](/zh-CN/providers/models)。
--- a/docs/zh-CN/gateway/security/index.md
+++ b/docs/zh-CN/gateway/security/index.md
--- a/docs/zh-CN/help/testing.md
+++ b/docs/zh-CN/help/testing.md
@ -1,116 +1,117 @@
 ---
 read_when:
-    - 在本地或 CI 中运行测试
-    - 为模型/提供商缺陷添加回归测试
+    - 在本地或在 CI 中运行测试
+    - 为模型 / 提供商缺陷添加回归测试
    - 调试 Gateway 网关 + 智能体行为
-summary: 测试工具包：unit/e2e/live 测试套件、Docker 运行器，以及每项测试覆盖的内容
+summary: 测试工具包：单元 / e2e / 实时测试套件、Docker 运行器，以及每项测试覆盖的内容
 title: 测试
 x-i18n:
-    generated_at: "2026-04-24T16:11:55Z"
+    generated_at: "2026-04-24T16:58:30Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 0d4f837faddc458509702b2a315d71d35740c01810ca76e40d652df54b09f38e
+    source_hash: ca845ba5856546841706ac9477aae07041f37620ae5eaafc35fd18ead97dcfae
    source_path: help/testing.md
    workflow: 15
 ---

-OpenClaw 有三个 Vitest 测试套件（unit/integration、e2e、live）以及少量 Docker 运行器。本文档是一份“我们如何测试”的指南：
+OpenClaw 有三个 Vitest 测试套件（单元 / 集成、e2e、实时），以及一小组 Docker 运行器。本文档是一份“我们如何测试”的指南：

- 每个测试套件覆盖什么（以及它刻意 _不_ 覆盖什么）。
- 常见工作流（本地、推送前、调试）应运行哪些命令。
- live 测试如何发现凭证并选择模型/提供商。
- 如何为真实世界中的模型/提供商问题添加回归测试。
+- 每个测试套件覆盖什么（以及它明确**不**覆盖什么）。
+- 常见工作流应运行哪些命令（本地、推送前、调试）。
+- 实时测试如何发现凭证并选择模型 / 提供商。
+- 如何为真实世界中的模型 / 提供商问题添加回归测试。

 ## 快速开始

 大多数时候：

- 完整门禁（预期在 push 前执行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test`
+- 完整门禁（预期在 push 前运行）：`pnpm build && pnpm check && pnpm check:test-types && pnpm test`
 - 在资源充足的机器上更快地运行本地完整测试套件：`pnpm test:max`
 - 直接使用 Vitest 观察模式循环：`pnpm test:watch`
- 直接指定文件现在也支持 extension/channel 路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
- 当你在迭代单个失败用例时，优先使用定向运行。
- Docker 支持的 QA 站点：`pnpm qa:lab:up`
- Linux VM 支持的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`
+- 直接按文件定位现在也会路由到扩展 / 渠道路径：`pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
+- 当你在迭代单个失败用例时，优先先运行定向测试。
+- 基于 Docker 的 QA 站点：`pnpm qa:lab:up`
+- 基于 Linux VM 的 QA 通道：`pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`

-当你修改了测试或想获得更多信心时：
+当你修改测试或想要更多信心时：

 - 覆盖率门禁：`pnpm test:coverage`
 - E2E 测试套件：`pnpm test:e2e`

-在调试真实提供商/模型时（需要真实凭证）：
+当调试真实提供商 / 模型时（需要真实凭证）：

- live 测试套件（模型 + Gateway 网关工具/图像探测）：`pnpm test:live`
- 安静地仅运行一个 live 文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts`
- Docker live 模型扫描：`pnpm test:docker:live-models`
-  - 现在每个选中的模型都会运行一次文本轮次以及一个类似小型文件读取的探测。元数据声明支持 `image` 输入的模型还会运行一个极小的图像轮次。在隔离提供商故障时，可通过 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用额外探测。
-  - CI 覆盖：每日运行的 `OpenClaw Scheduled Live And E2E Checks` 和手动触发的 `OpenClaw Release Checks` 都会调用可复用的 live/E2E 工作流，并设置 `include_live_suites: true`，其中包含按提供商分片的独立 Docker live 模型矩阵作业。
-  - 若要进行聚焦的 CI 重跑，可触发 `OpenClaw Live And E2E Checks (Reusable)`，并设置 `include_live_suites: true` 和 `live_models_only: true`。
-  - 将新的高信号提供商密钥添加到 `scripts/ci-hydrate-live-auth.sh`、`.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 及其 scheduled/release 调用方中。
+- 实时测试套件（模型 + Gateway 网关工具 / 图像探测）：`pnpm test:live`
+- 安静地只运行一个实时测试文件：`pnpm test:live -- src/agents/models.profiles.live.test.ts`
+- Docker 实时模型扫描：`pnpm test:docker:live-models`
+  - 现在每个选定模型都会运行一次文本轮次外加一个小型文件读取风格探测。元数据声明支持 `image` 输入的模型还会运行一次微型图像轮次。隔离提供商故障时，可通过 `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` 或 `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` 禁用额外探测。
+  - CI 覆盖：每日的 `OpenClaw Scheduled Live And E2E Checks` 和手动触发的 `OpenClaw Release Checks` 都会调用可复用的实时 / E2E 工作流，并设置 `include_live_suites: true`，其中包含按提供商分片的独立 Docker 实时模型矩阵作业。
+  - 若要进行聚焦的 CI 重跑，可派发 `OpenClaw Live And E2E Checks (Reusable)`，并设置 `include_live_suites: true` 与 `live_models_only: true`。
+  - 将新的高信号提供商密钥添加到 `scripts/ci-hydrate-live-auth.sh`，以及 `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` 和其 scheduled/release 调用方中。
 - 原生 Codex 绑定聊天冒烟测试：`pnpm test:docker:live-codex-bind`
-  - 在 Docker live 通道中针对 Codex app-server 路径运行，绑定一个带有 `/codex bind` 的合成 Slack 私信，会执行 `/codex fast` 和 `/codex permissions`，然后验证普通回复和图像附件都通过原生 plugin 绑定路由，而不是 ACP。
- Moonshot/Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行隔离的 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`。验证 JSON 报告的是 Moonshot/K2.6，且 assistant transcript 中存储了规范化的 `usage.cost`。
+  - 针对 Codex app-server 路径运行一个 Docker 实时通道，绑定一个合成的 Slack 私信并执行 `/codex bind`，测试 `/codex fast` 和 `/codex permissions`，然后验证普通回复与图像附件是通过原生插件绑定而非 ACP 路由的。
+- Moonshot / Kimi 成本冒烟测试：设置 `MOONSHOT_API_KEY` 后，运行 `openclaw models list --provider moonshot --json`，然后针对 `moonshot/kimi-k2.6` 运行独立命令 `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`
+  。验证 JSON 报告的是 Moonshot / K2.6，并且助手转录中存储了规范化后的 `usage.cost`。

-提示：当你只需要一个失败用例时，优先通过下文描述的 allowlist 环境变量来收窄 live 测试范围。
+提示：当你只需要一个失败用例时，优先使用下面描述的 allowlist 环境变量来缩小实时测试范围。

 ## QA 专用运行器

-当你需要 QA-lab 级别的真实环境时，这些命令与主测试套件并列使用：
+当你需要 QA-lab 级别的真实环境时，这些命令与主测试套件并列存在：

-CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上运行，也可通过手动触发配合 mock 提供商执行。`QA-Lab - All Lanes` 会在 `main` 上每夜运行，也可通过手动触发，并将 mock parity gate、live Matrix 通道以及由 Convex 管理的 live Telegram 通道作为并行作业运行。`OpenClaw Release Checks` 会在发布批准前运行相同的通道。
+CI 会在专用工作流中运行 QA Lab。`Parity gate` 会在匹配的 PR 上运行，也可通过手动派发结合模拟提供商运行。`QA-Lab - All Lanes` 会在 `main` 上每晚运行，也可手动派发，包含模拟 parity gate、实时 Matrix 通道，以及由 Convex 管理的实时 Telegram 通道，作为并行作业运行。`OpenClaw Release Checks` 会在发布审批前运行相同的通道。

 - `pnpm openclaw qa suite`
-  - 直接在主机上运行基于仓库的 QA 场景。
-  - 默认会以隔离的 Gateway 网关工作进程并行运行多个选定场景。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency <count>` 调整工作进程数量，或使用 `--concurrency 1` 回退到旧的串行通道。
-  - 任一场景失败时以非零状态退出。如果你想保留产物但不希望以失败退出码结束，请使用 `--allow-failures`。
-  - 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。`aimock` 会启动一个本地 AIMock 支持的 provider 服务器，用于实验性 fixture 和协议 mock 覆盖，而不会替代具备场景感知的 `mock-openai` 通道。
+  - 直接在宿主机上运行基于仓库的 QA 场景。
+  - 默认会以隔离的 Gateway 网关工作进程并行运行多个选定场景。`qa-channel` 默认并发数为 4（受所选场景数量限制）。使用 `--concurrency <count>` 调整工作进程数，或使用 `--concurrency 1` 运行旧的串行通道。
+  - 任一场景失败时以非零状态退出。若你希望保留产物但不以失败退出码结束，可使用 `--allow-failures`。
+  - 支持提供商模式 `live-frontier`、`mock-openai` 和 `aimock`。`aimock` 会启动一个本地基于 AIMock 的提供商服务器，用于实验性的夹具与协议模拟覆盖，而不会替代具备场景感知能力的 `mock-openai` 通道。
 - `pnpm openclaw qa suite --runner multipass`
  - 在一次性 Multipass Linux VM 中运行相同的 QA 测试套件。
-  - 与主机上的 `qa suite` 保持相同的场景选择行为。
-  - 复用与 `qa suite` 相同的提供商/模型选择标志。
-  - live 运行会转发那些对 guest 来说可行的受支持 QA 凭证输入：基于环境变量的提供商密钥、QA live 提供商配置路径，以及存在时的 `CODEX_HOME`。
-  - 输出目录必须保持在仓库根目录下，这样 guest 才能通过挂载的工作区回写文件。
-  - 会将常规 QA 报告 + 摘要以及 Multipass 日志写入 `.artifacts/qa-e2e/...`。
+  - 保持与宿主机上 `qa suite` 相同的场景选择行为。
+  - 复用与 `qa suite` 相同的提供商 / 模型选择标志。
+  - 实时运行会转发对来宾机可行的受支持 QA 认证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。
+  - 输出目录必须位于仓库根目录下，以便来宾机能通过挂载的工作区回写内容。
+  - 将常规 QA 报告、摘要以及 Multipass 日志写入 `.artifacts/qa-e2e/...`。
 - `pnpm qa:lab:up`
-  - 启动 Docker 支持的 QA 站点，用于偏操作员风格的 QA 工作。
+  - 启动基于 Docker 的 QA 站点，用于操作员风格的 QA 工作。
 - `pnpm test:docker:npm-onboard-channel-agent`
-  - 基于当前 checkout 构建一个 npm tarball，在 Docker 中全局安装，以非交互方式执行 OpenAI API key 新手引导，默认配置 Telegram，验证启用 plugin 时会按需安装运行时依赖，运行 doctor，并针对一个 mock OpenAI 端点执行一次本地智能体轮次。
-  - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行同样的打包安装通道。
+  - 从当前检出构建一个 npm tarball，在 Docker 中全局安装，运行非交互式 OpenAI API 密钥新手引导，默认配置 Telegram，验证启用插件时会按需安装运行时依赖，运行 doctor，并针对模拟的 OpenAI 端点执行一次本地智能体轮次。
+  - 使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 可在 Discord 上运行相同的打包安装通道。
 - `pnpm test:docker:npm-telegram-live`
-  - 在 Docker 中安装一个已发布的 OpenClaw 包，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后将该已安装包作为 SUT Gateway 网关复用 live Telegram QA 通道。
-  - 默认使用 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`。
-  - 使用与 `pnpm openclaw qa telegram` 相同的 Telegram 环境变量凭证或 Convex 凭证来源。对于 CI/发布自动化，设置 `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，再加上 `OPENCLAW_QA_CONVEX_SITE_URL` 和角色密钥。如果在 CI 中存在 `OPENCLAW_QA_CONVEX_SITE_URL` 以及 Convex 角色密钥，Docker 包装器会自动选择 Convex。
-  - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 仅覆盖该通道共享的 `OPENCLAW_QA_CREDENTIAL_ROLE`。
-  - GitHub Actions 将该通道暴露为手动维护者工作流 `NPM Telegram Beta E2E`。它不会在 merge 时运行。该工作流使用 `qa-live-shared` 环境和 Convex CI 凭证租约。
+  - 在 Docker 中安装已发布的 OpenClaw 包，运行已安装包的新手引导，通过已安装的 CLI 配置 Telegram，然后复用实时 Telegram QA 通道，并将该已安装包作为被测 Gateway 网关（SUT）。
+  - 默认为 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`。
+  - 使用与 `pnpm openclaw qa telegram` 相同的 Telegram 环境变量凭证或 Convex 凭证来源。对于 CI / 发布自动化，设置 `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`，并同时设置 `OPENCLAW_QA_CONVEX_SITE_URL` 和角色密钥。如果在 CI 中存在 `OPENCLAW_QA_CONVEX_SITE_URL` 和 Convex 角色密钥，Docker 包装器会自动选择 Convex。
+  - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` 仅为该通道覆盖共享的 `OPENCLAW_QA_CREDENTIAL_ROLE`。
+  - GitHub Actions 将该通道暴露为手动维护者工作流 `NPM Telegram Beta E2E`。它不会在合并时运行。该工作流使用 `qa-live-shared` environment 和 Convex CI 凭证租约。
 - `pnpm test:docker:bundled-channel-deps`
-  - 在 Docker 中打包并安装当前 OpenClaw 构建产物，启动已配置 OpenAI 的 Gateway 网关，然后通过编辑配置启用内置的 channel/plugins。
-  - 验证设置发现阶段不会预先安装未配置 plugin 的运行时依赖，首次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置 plugin 的运行时依赖，第二次重启不会重新安装已激活的依赖。
-  - 还会安装一个已知较旧的 npm 基线，在运行 `openclaw update --tag <candidate>` 之前启用 Telegram，并验证候选版本在更新后的 doctor 中能够修复内置渠道运行时依赖，而无需 harness 侧的 postinstall 修复。
+  - 在 Docker 中打包并安装当前 OpenClaw 构建，使用已配置的 OpenAI 启动 Gateway 网关，然后通过配置编辑启用内置渠道 / 插件。
+  - 验证设置发现阶段不会预先安装未配置插件的运行时依赖；首次配置后的 Gateway 网关或 doctor 运行会按需安装每个内置插件的运行时依赖；第二次重启不会重复安装已激活的依赖。
+  - 还会安装一个已知较旧的 npm 基线，在运行 `openclaw update --tag <candidate>` 之前启用 Telegram，并验证候选版本的更新后 doctor 会修复内置渠道运行时依赖，而无需测试框架侧的 postinstall 修复。
 - `pnpm openclaw qa aimock`
-  - 仅启动本地 AIMock provider 服务器，用于直接协议冒烟测试。
+  - 仅启动本地 AIMock 提供商服务器，用于直接协议冒烟测试。
 - `pnpm openclaw qa matrix`
-  - 针对一次性 Docker 支持的 Tuwunel homeserver 运行 Matrix live QA 通道。
-  - 该 QA 主机目前仅供 repo/dev 使用。打包后的 OpenClaw 安装不包含 `qa-lab`，因此不会暴露 `openclaw qa`。
-  - 仓库 checkout 会直接加载内置运行器；不需要单独安装 plugin。
-  - 会创建三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后启动一个以真实 Matrix plugin 作为 SUT 传输层的 QA gateway 子进程。
-  - 默认使用固定的稳定 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。如需测试其他镜像，可通过 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。
-  - Matrix 不暴露共享的 credential-source 标志，因为该通道会在本地创建一次性用户。
-  - 会将 Matrix QA 报告、摘要、observed-events 产物以及合并的 stdout/stderr 输出日志写入 `.artifacts/qa-e2e/...`。
+  - 针对一次性的、基于 Docker 的 Tuwunel homeserver 运行 Matrix 实时 QA 通道。
+  - 该 QA 宿主当前仅用于仓库 / 开发场景。打包后的 OpenClaw 安装不会附带 `qa-lab`，因此不会暴露 `openclaw qa`。
+  - 仓库检出会直接加载内置运行器；不需要单独的插件安装步骤。
+  - 配置三个临时 Matrix 用户（`driver`、`sut`、`observer`）以及一个私有房间，然后启动一个 QA Gateway 网关子进程，并将真实 Matrix 插件作为 SUT 传输层。
+  - 默认使用固定的稳定版 Tuwunel 镜像 `ghcr.io/matrix-construct/tuwunel:v1.5.1`。需要测试其他镜像时，可通过 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` 覆盖。
+  - Matrix 不暴露共享凭证来源标志，因为该通道会在本地配置一次性用户。
+  - 将 Matrix QA 报告、摘要、observed-events 产物以及合并的 stdout/stderr 输出日志写入 `.artifacts/qa-e2e/...`。
 - `pnpm openclaw qa telegram`
-  - 使用来自环境变量的 driver 和 SUT bot token，针对真实私有群组运行 Telegram live QA 通道。
-  - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram chat 的数字 id。
-  - 支持 `--credential-source convex` 以使用共享池凭证。默认使用环境变量模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。
-  - 任一场景失败时以非零状态退出。如果你想保留产物但不希望以失败退出码结束，请使用 `--allow-failures`。
-  - 需要两个位于同一私有群组中的不同 bot，并且 SUT bot 需要暴露 Telegram 用户名。
-  - 为了稳定地观察 bot 对 bot 通信，请在 `@BotFather` 中为两个 bot 都启用 Bot-to-Bot Communication Mode，并确保 driver bot 能观察到群组中的 bot 流量。
-  - 会将 Telegram QA 报告、摘要和 observed-messages 产物写入 `.artifacts/qa-e2e/...`。回复场景会包含从 driver 发送请求到观察到 SUT 回复的 RTT。
+  - 使用环境变量中的 driver 和 SUT bot token，针对真实私有群组运行 Telegram 实时 QA 通道。
+  - 需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`。群组 id 必须是 Telegram 聊天的数字 id。
+  - 支持 `--credential-source convex` 以使用共享池化凭证。默认使用环境变量模式，或设置 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` 以启用池化租约。
+  - 任一场景失败时以非零状态退出。若你希望保留产物但不以失败退出码结束，可使用 `--allow-failures`。
+  - 需要位于同一私有群组中的两个不同 bot，且 SUT bot 必须暴露 Telegram 用户名。
+  - 为了稳定观察 bot 与 bot 之间的通信，在 `@BotFather` 中为两个 bot 启用 Bot-to-Bot Communication Mode，并确保 driver bot 可以观察群组中的 bot 流量。
+  - 将 Telegram QA 报告、摘要和 observed-messages 产物写入 `.artifacts/qa-e2e/...`。回复类场景包含从 driver 发送请求到观察到 SUT 回复的 RTT。

-live 传输通道共享一套标准契约，以避免新传输方式发生漂移：
+实时传输通道共享一个标准契约，以避免新传输层出现漂移：

-`qa-channel` 仍然是宽泛的合成 QA 测试套件，不属于 live 传输覆盖矩阵的一部分。
+`qa-channel` 仍然是覆盖面更广的合成 QA 测试套件，不属于实时传输覆盖矩阵的一部分。

-| 通道 | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | 帮助命令 |
-| ---- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | -------- |
+| 通道 | Canary | 提及门控 | allowlist 阻止 | 顶层回复 | 重启恢复 | 线程跟进 | 线程隔离 | Reaction 观察 | 帮助命令 |
+| ---- | ------ | -------- | -------------- | -------- | -------- | -------- | -------- | ------------- | -------- |
 | Matrix | x | x | x | x | x | x | x | x |  |
 | Telegram | x |  |  |  |  |  |  |  | x |

@ -118,19 +119,19 @@ live 传输通道共享一套标准契约，以避免新传输方式发生漂移

 当为 `openclaw qa telegram` 启用 `--credential-source convex`（或 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`）时，QA lab 会从 Convex 支持的凭证池中获取一个独占租约，在通道运行期间为该租约发送心跳，并在关闭时释放该租约。

-参考 Convex 项目脚手架：
+参考的 Convex 项目脚手架：

 - `qa/convex-credential-broker/`

-必需环境变量：
+必需的环境变量：

 - `OPENCLAW_QA_CONVEX_SITE_URL`（例如 `https://your-deployment.convex.site`）
- 所选角色对应的一个密钥：
-  - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` 用于 `maintainer`
-  - `OPENCLAW_QA_CONVEX_SECRET_CI` 用于 `ci`
+- 为所选角色配置一个密钥：
+  - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` 对应 `maintainer`
+  - `OPENCLAW_QA_CONVEX_SECRET_CI` 对应 `ci`
 - 凭证角色选择：
  - CLI：`--credential-role maintainer|ci`
-  - 默认环境变量：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认为 `ci`，否则默认为 `maintainer`）
+  - 环境变量默认值：`OPENCLAW_QA_CREDENTIAL_ROLE`（在 CI 中默认 `ci`，否则默认 `maintainer`）

 可选环境变量：

@ -139,14 +140,14 @@ live 传输通道共享一套标准契约，以避免新传输方式发生漂移
 - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`（默认 `90000`）
 - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`（默认 `15000`）
 - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`（默认 `/qa-credentials/v1`）
- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选跟踪 id）
+- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`（可选追踪 id）
 - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` 允许在仅限本地开发时使用 loopback `http://` Convex URL。

 正常运行时，`OPENCLAW_QA_CONVEX_SITE_URL` 应使用 `https://`。

-维护者管理命令（池添加/删除/列出）需要专门使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。
+维护者管理员命令（池添加 / 删除 / 列表）必须专门使用 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`。

-供维护者使用的 CLI 帮助命令：
+面向维护者的 CLI 辅助命令：

 ```bash
 pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
@ -154,14 +155,14 @@ pnpm openclaw qa credentials list --kind telegram
 pnpm openclaw qa credentials remove --credential-id <credential-id>
 ```

-在脚本和 CI 工具中使用 `--json` 以获得机器可读的输出。
+在脚本和 CI 工具中使用 `--json` 可获得机器可读输出。

 默认端点契约（`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`）：

 - `POST /acquire`
  - 请求：`{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }`
  - 成功：`{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }`
-  - 已耗尽/可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }`
+  - 耗尽 / 可重试：`{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }`
 - `POST /heartbeat`
  - 请求：`{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }`
  - 成功：`{ status: "ok" }`（或空的 `2xx`）
@ -182,59 +183,59 @@ pnpm openclaw qa credentials remove --credential-id <credential-id>
 Telegram 类型的 payload 结构：

 - `{ groupId: string, driverToken: string, sutToken: string }`
- `groupId` 必须是 Telegram chat id 的数字字符串。
- `admin/add` 会为 `kind: "telegram"` 校验该结构，并拒绝格式错误的 payload。
+- `groupId` 必须是 Telegram 聊天 id 的数字字符串。
+- `admin/add` 会为 `kind: "telegram"` 验证此结构，并拒绝格式错误的 payload。

-### 向 QA 添加一个渠道
+### 向 QA 添加渠道

-向 markdown QA 系统添加一个渠道，严格来说只需要两样东西：
+将一个渠道添加到 Markdown QA 系统中，严格只需要两样东西：

 1. 该渠道的传输适配器。
 2. 一个用于验证该渠道契约的场景包。

-当共享的 `qa-lab` 主机能够承载流程时，不要新增一个顶层 QA 命令根。
+如果共享的 `qa-lab` 宿主能够承载该流程，就不要添加新的顶层 QA 命令根。

-`qa-lab` 负责共享主机机制：
+`qa-lab` 负责共享宿主机制：

 - `openclaw qa` 命令根
- 测试套件启动和拆除
- worker 并发控制
+- 测试套件启动与拆除
+- 工作进程并发
 - 产物写入
 - 报告生成
 - 场景执行
- 对旧版 `qa-channel` 场景的兼容别名
+- 对旧 `qa-channel` 场景的兼容别名

-运行器 plugins 负责传输契约：
+运行器插件负责传输契约：

- 如何将 `openclaw qa <runner>` 挂载到共享的 `qa` 根命令下
- 如何为该传输方式配置 Gateway 网关
+- 如何将 `openclaw qa <runner>` 挂载到共享 `qa` 根下
+- 如何为该传输配置 Gateway 网关
 - 如何检查就绪状态
 - 如何注入入站事件
 - 如何观察出站消息
- 如何暴露 transcript 和规范化的传输状态
- 如何执行由传输方式支持的操作
- 如何处理传输特定的重置或清理
+- 如何暴露转录与规范化后的传输状态
+- 如何执行基于传输的操作
+- 如何处理传输专属的重置或清理

 新渠道的最低接入门槛是：

-1. 保持由 `qa-lab` 作为共享 `qa` 根命令的拥有者。
-2. 在共享的 `qa-lab` 主机接口上实现传输运行器。
-3. 将传输特定机制保留在运行器 plugin 或渠道 harness 内部。
+1. 保持 `qa-lab` 作为共享 `qa` 根的所有者。
+2. 在共享的 `qa-lab` 宿主接缝上实现传输运行器。
+3. 将传输专属机制保留在运行器插件或渠道测试框架中。
 4. 将运行器挂载为 `openclaw qa <runner>`，而不是注册一个竞争性的根命令。
-   运行器 plugins 应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。
-   保持 `runtime-api.ts` 足够轻量；惰性 CLI 和运行器执行应置于独立入口点之后。
-5. 在按主题组织的 `qa/scenarios/` 目录下编写或调整 markdown 场景。
-6. 为新场景使用通用场景辅助工具。
+   运行器插件应在 `openclaw.plugin.json` 中声明 `qaRunners`，并从 `runtime-api.ts` 导出匹配的 `qaRunnerCliRegistrations` 数组。
+   保持 `runtime-api.ts` 足够轻量；惰性 CLI 和运行器执行应放在单独的入口点之后。
+5. 在带主题的 `qa/scenarios/` 目录下编写或适配 Markdown 场景。
+6. 对新场景使用通用场景辅助函数。
 7. 除非仓库正在进行有意迁移，否则保持现有兼容别名继续可用。

-决策规则非常严格：
+决策规则是严格的：

- 如果某个行为可以在 `qa-lab` 中统一表达一次，就把它放到 `qa-lab`。
- 如果某个行为依赖某一种渠道传输方式，就把它保留在对应的运行器 plugin 或 plugin harness 中。
- 如果某个场景需要一个可被多个渠道复用的新能力，就添加一个通用辅助工具，而不是在 `suite.ts` 中加入渠道特定分支。
- 如果某个行为只对某一种传输方式有意义，就保持该场景为传输特定，并在场景契约中明确这一点。
+- 如果某个行为可以在 `qa-lab` 中统一表达一次，就把它放进 `qa-lab`。
+- 如果某个行为依赖单一渠道传输，就将它保留在该运行器插件或插件测试框架中。
+- 如果某个场景需要新增一种能力，且不止一个渠道可以使用它，那么应添加通用辅助函数，而不是在 `suite.ts` 中添加渠道专属分支。
+- 如果某个行为只对一种传输有意义，就保持该场景为传输专属，并在场景契约中明确说明。

-新场景推荐使用的通用辅助工具名称：
+新场景优先使用的通用辅助函数名称是：

 - `waitForTransportReady`
 - `waitForChannelReady`
@ -257,365 +258,365 @@ Telegram 类型的 payload 结构：
 - `formatConversationTranscript`
 - `resetBus`

-新的渠道开发应使用通用辅助工具名称。
-兼容别名的存在是为了避免一次性强制迁移，而不是作为新场景编写的范式。
+新的渠道开发应使用通用辅助函数名称。
+兼容别名的存在是为了避免一次性迁移日，而不是作为新场景编写的范式。

-## 测试套件（各自运行在哪里）
+## 测试套件（各自在哪里运行）

-可以把这些测试套件理解为“真实度逐级提高”（同时波动性/成本也逐级增加）：
+可以把这些测试套件理解为“真实程度逐步增加”（同时不稳定性 / 成本也逐步增加）：

-### Unit / integration（默认）
+### 单元 / 集成（默认）

 - 命令：`pnpm test`
- 配置：未定向运行使用 `vitest.full-*.config.ts` 分片集合，并且可能会将多项目分片展开为按项目拆分的配置，以便并行调度
- 文件：位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts` 下的 core/unit 清单，以及 `vitest.unit.config.ts` 覆盖的白名单 `ui` node 测试
+- 配置：未定向运行使用 `vitest.full-*.config.ts` 分片集合，并且可能会将多项目分片展开为按项目划分的配置，以便并行调度
+- 文件：核心 / 单元测试清单位于 `src/**/*.test.ts`、`packages/**/*.test.ts`、`test/**/*.test.ts`，以及由 `vitest.unit.config.ts` 覆盖的白名单 `ui` Node 测试
 - 范围：
-  - 纯 unit 测试
-  - 进程内 integration 测试（Gateway 网关认证、路由、工具、解析、配置）
-  - 已知缺陷的确定性回归测试
+  - 纯单元测试
+  - 进程内集成测试（Gateway 网关认证、路由、工具、解析、配置）
+  - 针对已知缺陷的确定性回归测试
 - 预期：
  - 在 CI 中运行
  - 不需要真实密钥
  - 应该快速且稳定
    <AccordionGroup>
-    <Accordion title="项目、分片和定向通道"> - 未定向的 `pnpm test` 会运行 12 个更小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个巨大的原生根项目进程。这样可以降低高负载机器上的 RSS 峰值，并避免 auto-reply/extension 工作拖慢无关测试套件。 - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片 watch 循环并不现实。 - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会优先通过定向通道来处理显式的文件/目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 不必承担完整根项目启动的成本。 - 当变更的 git 路径仅触及可路由的源文件/测试文件时，`pnpm test:changed` 会将这些路径展开到相同的定向通道；而配置/设置改动仍会回退到更宽泛的根项目重跑。 - `pnpm check:changed` 是处理小范围变更时常规的智能本地门禁。它会将 diff 分类为 core、core tests、extensions、extension tests、apps、docs、release metadata 和 tooling，然后运行对应的 typecheck/lint/test 通道。公共 Plugin SDK 和 plugin-contract 的变更会额外包含一次 extension 验证，因为 extensions 依赖这些 core 契约。仅包含发布元数据版本号变更时，会运行定向的版本/config/root-dependency 检查，而不是完整测试套件，并带有一个保护机制，用于拒绝顶层 version 字段之外的 package 变更。 - 来自 agents、commands、plugins、auto-reply 辅助工具、`plugin-sdk` 以及类似纯工具区域的轻导入 unit 测试，会路由到 `unit-fast` 通道，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态/运行时较重的文件则保留在现有通道中。 - 某些 `plugin-sdk` 和 `commands` 辅助源码文件在 changed 模式下也会映射到这些轻量通道中的显式同级测试，因此辅助工具改动无需为该目录重跑完整的重型测试套件。 - `auto-reply` 有三个专用桶：顶层 core 辅助工具、顶层 `reply.*` integration 测试，以及 `src/auto-reply/reply/**` 子树。这样可以让最重的 reply harness 工作不影响廉价的状态/chunk/token 测试。
+    <Accordion title="项目、分片和作用域通道"> - 未定向的 `pnpm test` 会运行十二个更小的分片配置（`core-unit-fast`、`core-unit-src`、`core-unit-security`、`core-unit-ui`、`core-unit-support`、`core-support-boundary`、`core-contracts`、`core-bundled`、`core-runtime`、`agentic`、`auto-reply`、`extensions`），而不是一个巨大的原生根项目进程。这样可在负载较高的机器上降低峰值 RSS，并避免 auto-reply / 扩展工作拖慢无关的测试套件。 - `pnpm test --watch` 仍然使用原生根 `vitest.config.ts` 项目图，因为多分片的 watch 循环并不现实。 - `pnpm test`、`pnpm test:watch` 和 `pnpm test:perf:imports` 会优先通过作用域通道来路由显式文件 / 目录目标，因此 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` 可以避免支付完整根项目启动成本。 - 当变更的 git 路径只涉及可路由的源文件 / 测试文件时，`pnpm test:changed` 会将这些变更路径展开为相同的作用域通道；配置 / setup 编辑仍会回退到更广泛的根项目重跑。 - `pnpm check:changed` 是窄范围开发工作的常规智能本地门禁。它会将差异分类为 core、core tests、extensions、extension tests、apps、docs、release metadata 和 tooling，然后运行匹配的 typecheck / lint / test 通道。公共插件 SDK 和插件契约变更会额外包含一次扩展验证，因为扩展依赖这些核心契约。仅涉及发布元数据的版本号提升会运行定向的版本 / 配置 / 根依赖检查，而不是完整测试套件，并带有一个保护机制，用于拒绝顶层版本字段之外的 package 变更。 - 来自 agents、commands、plugins、auto-reply 辅助函数、`plugin-sdk` 以及类似纯工具区域的轻导入单元测试，会通过 `unit-fast` 通道路由，该通道会跳过 `test/setup-openclaw-runtime.ts`；有状态 / 运行时较重的文件仍保留在现有通道中。 - 选定的 `plugin-sdk` 和 `commands` 辅助源文件也会在 changed 模式运行时映射到这些轻量通道中的显式同级测试，因此对辅助函数的修改无需为该目录重跑完整的重型测试套件。 - `auto-reply` 有三个专用桶：顶层核心辅助函数、顶层 `reply.*` 集成测试，以及 `src/auto-reply/reply/**` 子树。这可使最重的 reply 测试框架工作远离轻量的状态 / 分块 / token 测试。
    </Accordion>

      <Accordion title="嵌入式运行器覆盖">
-        - 当你修改消息工具发现输入或压缩运行时上下文时，请同时保持两个层级的覆盖。
-        - 为纯路由和规范化边界添加聚焦的辅助工具回归测试。
-        - 保持嵌入式运行器 integration 测试套件健康：
+        - 当你修改消息工具发现输入或压缩运行时上下文时，请同时保留两个层级的覆盖。
+        - 为纯路由和规范化边界添加聚焦的辅助函数回归测试。
+        - 保持嵌入式运行器集成测试套件健康：
          `src/agents/pi-embedded-runner/compact.hooks.test.ts`、
          `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` 和
          `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`。
-        - 这些测试套件会验证带作用域的 id 和压缩行为是否仍然通过真实的 `run.ts` / `compact.ts` 路径流转；仅有辅助工具测试不足以替代这些 integration 路径。
+        - 这些测试套件会验证带作用域的 id 和压缩行为仍然流经真实的 `run.ts` / `compact.ts` 路径；仅有辅助函数级别的测试并不足以替代这些集成路径。
      </Accordion>

-      <Accordion title="Vitest 池与隔离默认值">
+      <Accordion title="Vitest 池和隔离默认值">
        - 基础 Vitest 配置默认使用 `threads`。
-        - 共享 Vitest 配置固定为 `isolate: false`，并在根项目、e2e 和 live 配置中使用非隔离运行器。
-        - 根 UI 通道保留其 `jsdom` 设置和优化器，但也在共享的非隔离运行器上运行。
+        - 共享 Vitest 配置固定 `isolate: false`，并在根项目、e2e 和实时配置中使用非隔离运行器。
+        - 根 UI 通道保留其 `jsdom` setup 和优化器，但也运行在共享的非隔离运行器上。
        - 每个 `pnpm test` 分片都从共享 Vitest 配置继承相同的 `threads` + `isolate: false` 默认值。
-        - `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大规模本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可对比 stock V8 行为。
+        - `scripts/run-vitest.mjs` 默认会为 Vitest 子 Node 进程添加 `--no-maglev`，以减少大型本地运行期间的 V8 编译抖动。设置 `OPENCLAW_VITEST_ENABLE_MAGLEV=1` 可与原生 V8 行为进行对比。
      </Accordion>

      <Accordion title="快速本地迭代">
-        - `pnpm changed:lanes` 会显示某个 diff 触发了哪些架构通道。
-        - pre-commit hook 仅做格式化。它会重新暂存已格式化文件，但不会运行 lint、typecheck 或测试。
-        - 当你需要智能本地门禁时，请在交接或 push 前显式运行 `pnpm check:changed`。公共 Plugin SDK 和 plugin-contract 的变更会额外包含一次 extension 验证。
-        - 当变更路径可以清晰映射到更小的测试套件时，`pnpm test:changed` 会通过定向通道执行。
-        - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是使用更高的 worker 上限。
-        - 本地 worker 自动扩缩容刻意较为保守，当主机平均负载已经较高时会主动回退，因此默认情况下多个并发 Vitest 运行对系统造成的影响更小。
-        - 基础 Vitest 配置会将项目/配置文件标记为 `forceRerunTriggers`，以便在测试接线变更时，changed 模式重跑仍保持正确。
-        - 该配置会在受支持的主机上保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接分析指定一个显式缓存位置，可设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。
+        - `pnpm changed:lanes` 会显示某个差异触发了哪些架构通道。
+        - pre-commit hook 只做格式化。它会重新暂存已格式化文件，但不会运行 lint、typecheck 或测试。
+        - 当你需要智能本地门禁时，请在交接或 push 前显式运行 `pnpm check:changed`。公共插件 SDK 和插件契约变更会包含一次扩展验证。
+        - 当变更路径可以清晰映射到较小测试套件时，`pnpm test:changed` 会通过作用域通道进行路由。
+        - `pnpm test:max` 和 `pnpm test:changed:max` 保持相同的路由行为，只是使用更高的工作进程上限。
+        - 本地工作进程自动扩缩容故意采取保守策略，当宿主机负载平均值已经较高时会自动回退，因此默认情况下多个并发 Vitest 运行造成的影响会更小。
+        - 基础 Vitest 配置会将项目 / 配置文件标记为 `forceRerunTriggers`，这样当测试接线发生变化时，changed 模式重跑仍能保持正确。
+        - 在受支持的宿主上，配置会保持启用 `OPENCLAW_VITEST_FS_MODULE_CACHE`；如果你想为直接性能分析指定一个明确的缓存位置，请设置 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`。
      </Accordion>

      <Accordion title="性能调试">
        - `pnpm test:perf:imports` 会启用 Vitest 导入耗时报告以及导入拆解输出。
-        - `pnpm test:perf:imports:changed` 会将相同的分析视图限定到自 `origin/main` 以来变更的文件。
-        - 当某个热点测试的大部分时间仍然消耗在启动导入上时，应将重型依赖保留在一个狭窄的本地 `*.runtime.ts` 接口之后，并直接 mock 该接口，而不是为了通过 `vi.mock(...)` 传递它们就深度导入运行时辅助工具。
-        - `pnpm test:perf:changed:bench -- --ref <git-ref>` 会针对该已提交 diff，将定向的 `test:changed` 与原生根项目路径进行对比，并输出总耗时以及 macOS 最大 RSS。
-        - `pnpm test:perf:changed:bench -- --worktree` 会通过将变更文件列表分别路由到 `scripts/test-projects.mjs` 和根 Vitest 配置，对当前未提交工作树进行基准测试。
-        - `pnpm test:perf:profile:main` 会为 Vitest/Vite 启动和转换开销写入主线程 CPU profile。
-        - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为 unit 测试套件写入运行器 CPU + heap profile。
+        - `pnpm test:perf:imports:changed` 会将相同的性能分析视图限定为自 `origin/main` 以来变更的文件。
+        - 当某个热点测试仍然将大部分时间耗在启动导入上时，应将重型依赖放在狭窄的本地 `*.runtime.ts` 接缝之后，并直接 mock 该接缝，而不是为了通过 `vi.mock(...)` 传递它们就深度导入运行时辅助模块。
+        - `pnpm test:perf:changed:bench -- --ref <git-ref>` 会将路由后的 `test:changed` 与该已提交差异对应的原生根项目路径进行比较，并打印总耗时以及 macOS 最大 RSS。
+        - `pnpm test:perf:changed:bench -- --worktree` 会通过将变更文件列表路由到 `scripts/test-projects.mjs` 和根 Vitest 配置，对当前未提交工作树进行基准测试。
+        - `pnpm test:perf:profile:main` 会为 Vitest / Vite 启动与转换开销写出主线程 CPU profile。
+        - `pnpm test:perf:profile:runner` 会在禁用文件并行的情况下，为单元测试套件写出运行器 CPU + 堆 profile。
      </Accordion>
    </AccordionGroup>

 ### 稳定性（Gateway 网关）

 - 命令：`pnpm test:stability:gateway`
- 配置：`vitest.gateway.config.ts`，强制只使用一个 worker
+- 配置：`vitest.gateway.config.ts`，强制使用单个工作进程
 - 范围：
  - 启动一个默认启用诊断功能的真实 loopback Gateway 网关
-  - 通过诊断事件路径驱动合成的 gateway message、memory 和大负载 churn
+  - 通过诊断事件路径驱动合成的 Gateway 网关消息、内存和大负载 churn
  - 通过 Gateway 网关 WS RPC 查询 `diagnostics.stability`
-  - 覆盖诊断稳定性 bundle 持久化辅助工具
-  - 断言 recorder 保持有界、合成 RSS 样本保持在压力预算之下，并且每个会话的队列深度都会回落到零
+  - 覆盖诊断稳定性 bundle 持久化辅助函数
+  - 断言记录器保持有界、合成 RSS 采样保持在压力预算之下，并且每个会话的队列深度都会回落到零
 - 预期：
-  - 对 CI 安全且不需要密钥
-  - 这是一个用于稳定性回归跟进的窄通道，而不是完整 Gateway 网关测试套件的替代品
+  - 对 CI 安全且无需密钥
+  - 这是用于稳定性回归后续跟进的窄通道，不可替代完整的 Gateway 网关测试套件

 ### E2E（Gateway 网关冒烟）

 - 命令：`pnpm test:e2e`
 - 配置：`vitest.e2e.config.ts`
- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下的内置 plugin E2E 测试
+- 文件：`src/**/*.e2e.test.ts`、`test/**/*.e2e.test.ts`，以及 `extensions/` 下内置插件的 E2E 测试
 - 运行时默认值：
-  - 使用 Vitest `threads` 且设置 `isolate: false`，与仓库其余部分保持一致。
-  - 使用自适应 workers（CI：最多 2 个，本地：默认 1 个）。
+  - 使用 Vitest `threads`，并设置 `isolate: false`，与仓库其余部分保持一致。
+  - 使用自适应工作进程（CI：最多 2 个，本地：默认 1 个）。
  - 默认以 silent 模式运行，以减少控制台 I/O 开销。
 - 常用覆盖项：
-  - `OPENCLAW_E2E_WORKERS=<n>` 用于强制指定 worker 数量（上限为 16）。
-  - `OPENCLAW_E2E_VERBOSE=1` 用于重新启用详细控制台输出。
+  - `OPENCLAW_E2E_WORKERS=<n>`：强制指定工作进程数（上限为 16）。
+  - `OPENCLAW_E2E_VERBOSE=1`：重新启用详细控制台输出。
 - 范围：
  - 多实例 Gateway 网关端到端行为
-  - WebSocket/HTTP 表面、节点配对以及更重的网络行为
+  - WebSocket / HTTP 接口、节点配对，以及更重的网络路径
 - 预期：
  - 在 CI 中运行（当流水线中启用时）
  - 不需要真实密钥
-  - 比 unit 测试包含更多活动部件（可能更慢）
+  - 比单元测试包含更多活动部件（可能更慢）

 ### E2E：OpenShell 后端冒烟

 - 命令：`pnpm test:e2e:openshell`
 - 文件：`extensions/openshell/src/backend.e2e.test.ts`
 - 范围：
-  - 通过 Docker 在主机上启动一个隔离的 OpenShell gateway
-  - 从一个临时本地 Dockerfile 创建一个沙箱
-  - 通过真实的 `sandbox ssh-config` + SSH exec 运行 OpenClaw 的 OpenShell 后端
-  - 通过沙箱文件系统桥接验证远端规范化的文件系统行为
+  - 通过 Docker 在宿主机上启动一个隔离的 OpenShell Gateway 网关
+  - 从一个临时本地 Dockerfile 创建沙箱
+  - 通过真实的 `sandbox ssh-config` + SSH exec 测试 OpenClaw 的 OpenShell 后端
+  - 通过沙箱 fs bridge 验证远端规范文件系统行为
 - 预期：
  - 仅按需启用；不属于默认 `pnpm test:e2e` 运行的一部分
-  - 需要本地 `openshell` CLI 和一个可用的 Docker daemon
-  - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，随后销毁测试 gateway 和沙箱
+  - 需要本地 `openshell` CLI 和可用的 Docker daemon
+  - 使用隔离的 `HOME` / `XDG_CONFIG_HOME`，然后销毁测试 Gateway 网关和沙箱
 - 常用覆盖项：
-  - `OPENCLAW_E2E_OPENSHELL=1` 用于在手动运行更大范围 e2e 测试套件时启用该测试
-  - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` 用于指向非默认 CLI 二进制文件或包装脚本
+  - `OPENCLAW_E2E_OPENSHELL=1`：在手动运行更广泛的 e2e 测试套件时启用该测试
+  - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`：指向非默认 CLI 二进制或包装脚本

-### Live（真实提供商 + 真实模型）
+### 实时（真实提供商 + 真实模型）

 - 命令：`pnpm test:live`
 - 配置：`vitest.live.config.ts`
- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下的内置 plugin live 测试
- 默认：由 `pnpm test:live` **启用**（会设置 `OPENCLAW_LIVE_TEST=1`）
+- 文件：`src/**/*.live.test.ts`、`test/**/*.live.test.ts`，以及 `extensions/` 下内置插件的实时测试
+- 默认：由 `pnpm test:live` **启用**（设置 `OPENCLAW_LIVE_TEST=1`）
 - 范围：
-  - “这个提供商/模型在 _今天_ 配合真实凭证是否真的能工作？”
-  - 捕获提供商格式变更、工具调用怪异行为、认证问题以及速率限制行为
+  - “这个提供商 / 模型今天在真实凭证下是否真的可用？”
+  - 捕获提供商格式变更、工具调用怪癖、认证问题以及速率限制行为
 - 预期：
-  - 按设计不具备 CI 稳定性（真实网络、真实提供商策略、配额、故障）
-  - 会花钱 / 消耗速率限制
-  - 优先运行收窄后的子集，而不是“全部都跑”
- live 运行会读取 `~/.profile`，以获取缺失的 API key。
- 默认情况下，live 运行仍会隔离 `HOME`，并将配置/认证材料复制到一个临时测试 home 中，这样 unit fixture 就不会修改你真实的 `~/.openclaw`。
- 仅当你确实需要 live 测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。
- `pnpm test:live` 现在默认使用更安静的模式：它会保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静音 gateway 启动日志/Bonjour 噪音。如果你想恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。
- API key 轮换（提供商特定）：设置 `*_API_KEYS`（逗号/分号格式）或 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或者通过 `OPENCLAW_LIVE_*_KEY` 进行每个 live 运行的覆盖；测试会在遇到速率限制响应时重试。
- 进度/心跳输出：
-  - live 测试套件现在会向 stderr 输出进度行，因此即使 Vitest 控制台捕获处于安静模式，长时间的提供商调用也能明显显示仍在活动中。
-  - `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，因此在 live 运行期间，提供商/gateway 进度行会立即流式输出。
+  - 设计上不保证 CI 稳定性（真实网络、真实提供商策略、配额、故障）
+  - 会花钱 / 消耗速率限制额度
+  - 优先运行缩小范围的子集，而不是“全量”
+- 实时运行会加载 `~/.profile` 以获取缺失的 API 密钥。
+- 默认情况下，实时运行仍会隔离 `HOME`，并将配置 / 认证材料复制到临时测试 home 中，这样单元测试夹具就不会修改你真实的 `~/.openclaw`。
+- 只有在你明确需要让实时测试使用真实 home 目录时，才设置 `OPENCLAW_LIVE_USE_REAL_HOME=1`。
+- `pnpm test:live` 现在默认采用更安静的模式：它会保留 `[live] ...` 进度输出，但会抑制额外的 `~/.profile` 提示，并静默 Gateway 网关启动日志 / Bonjour 杂讯。如果你想恢复完整启动日志，请设置 `OPENCLAW_LIVE_TEST_QUIET=0`。
+- API 密钥轮换（按提供商区分）：设置逗号 / 分号格式的 `*_API_KEYS`，或 `*_API_KEY_1`、`*_API_KEY_2`（例如 `OPENAI_API_KEYS`、`ANTHROPIC_API_KEYS`、`GEMINI_API_KEYS`），或者通过 `OPENCLAW_LIVE_*_KEY` 进行每次实时运行覆盖；测试会在速率限制响应时重试。
+- 进度 / 心跳输出：
+  - 实时测试套件现在会向 stderr 输出进度行，因此即使 Vitest 控制台捕获较安静，长时间的提供商调用也会显式显示为仍在活动。
+  - `vitest.live.config.ts` 会禁用 Vitest 控制台拦截，以便提供商 / Gateway 网关进度行在实时运行期间立即流式输出。
  - 使用 `OPENCLAW_LIVE_HEARTBEAT_MS` 调整直接模型心跳。
-  - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 gateway/探测心跳。
+  - 使用 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS` 调整 Gateway 网关 / 探测心跳。

 ## 我应该运行哪个测试套件？

-使用这张决策表：
+使用这个决策表：

- 编辑逻辑/测试：运行 `pnpm test`（如果改动很多，再加上 `pnpm test:coverage`）
- 触及 gateway 网络 / WS 协议 / 配对：再加上 `pnpm test:e2e`
- 调试“我的 bot 挂了” / 提供商特定故障 / 工具调用：运行收窄后的 `pnpm test:live`
+- 编辑逻辑 / 测试：运行 `pnpm test`（如果你改动很多，也运行 `pnpm test:coverage`）
+- 修改 Gateway 网关网络 / WS 协议 / 配对：额外运行 `pnpm test:e2e`
+- 调试“我的 bot 挂了” / 提供商专属故障 / 工具调用：运行缩小范围的 `pnpm test:live`

-## Live（触网）测试
+## 实时（触网）测试

-关于 live 模型矩阵、CLI 后端冒烟、ACP 冒烟、Codex app-server
-harness，以及所有媒体提供商 live 测试（Deepgram、BytePlus（国际版）、ComfyUI、图像、
-音乐、视频、媒体 harness）——以及 live 运行的凭证处理——请参见
-[测试 — live 测试套件](/zh-CN/help/testing-live)。
+对于实时模型矩阵、CLI 后端冒烟、ACP 冒烟、Codex app-server
+测试框架，以及所有媒体提供商实时测试（Deepgram、BytePlus（国际版）、ComfyUI、图像、
+音乐、视频、媒体测试框架）——以及实时运行的凭证处理——请参见
+[测试——实时测试套件](/zh-CN/help/testing-live)。

 ## Docker 运行器（可选的“在 Linux 中可用”检查）

 这些 Docker 运行器分为两类：

- Live 模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像内运行与其匹配的 profile-key live 文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），并挂载你的本地配置目录和工作区（如果已挂载，还会读取 `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。
- Docker live 运行器默认使用更小的冒烟上限，以便完整的 Docker 扫描仍然可行：
+- 实时模型运行器：`test:docker:live-models` 和 `test:docker:live-gateway` 只会在仓库 Docker 镜像中运行各自匹配的 profile-key 实时测试文件（`src/agents/models.profiles.live.test.ts` 和 `src/gateway/gateway-models.profiles.live.test.ts`），挂载你的本地配置目录和工作区（如果已挂载，还会加载 `~/.profile`）。对应的本地入口点是 `test:live:models-profiles` 和 `test:live:gateway-profiles`。
+- Docker 实时运行器默认有较小的冒烟上限，以便完整的 Docker 扫描仍然可行：
  `test:docker:live-models` 默认设置 `OPENCLAW_LIVE_MAX_MODELS=12`，而
  `test:docker:live-gateway` 默认设置 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`、
  `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`、
-  `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`，以及
-  `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。当你
-  明确想要进行更大范围的穷尽扫描时，可覆盖这些环境变量。
- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次 live Docker 镜像，然后在两个 live Docker 通道中复用它。它还会通过 `test:docker:e2e-build` 构建一个共享的 `scripts/e2e/Dockerfile` 镜像，并将其复用于那些验证已构建应用的 E2E 容器冒烟运行器。
+  `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` 和
+  `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`。如果你明确需要更大的穷举扫描，可覆盖这些环境变量。
+- `test:docker:all` 会先通过 `test:docker:live-build` 构建一次实时 Docker 镜像，然后在两个实时 Docker 通道中复用它。它还会通过 `test:docker:e2e-build` 构建一个共享的 `scripts/e2e/Dockerfile` 镜像，并在测试已构建应用的 E2E 容器冒烟运行器中复用它。
 - 容器冒烟运行器：`test:docker:openwebui`、`test:docker:onboard`、`test:docker:npm-onboard-channel-agent`、`test:docker:gateway-network`、`test:docker:mcp-channels`、`test:docker:pi-bundle-mcp-tools`、`test:docker:cron-mcp-cleanup`、`test:docker:plugins`、`test:docker:plugin-update` 和 `test:docker:config-reload` 会启动一个或多个真实容器，并验证更高层级的集成路径。

-live-model Docker 运行器还会仅 bind-mount 所需的 CLI auth home（如果运行未收窄，则会挂载所有受支持的 auth home），然后在运行前将其复制到容器 home 中，这样外部 CLI OAuth 就能刷新 token，而不会修改主机 auth 存储：
+实时模型 Docker 运行器还会只绑定挂载所需的 CLI 认证 home（如果运行未缩小范围，则挂载所有受支持的认证 home），然后在运行前将它们复制到容器 home 中，以便外部 CLI OAuth 可以刷新 token，而不会修改宿主机认证存储：

- 直连模型：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`）
- ACP 绑定冒烟测试：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`）
- CLI 后端冒烟测试：`pnpm test:docker:live-cli-backend`（脚本：`scripts/test-live-cli-backend-docker.sh`）
- Codex app-server harness 冒烟测试：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-docker.sh`）
+- 直接模型：`pnpm test:docker:live-models`（脚本：`scripts/test-live-models-docker.sh`）
+- ACP 绑定冒烟：`pnpm test:docker:live-acp-bind`（脚本：`scripts/test-live-acp-bind-docker.sh`）
+- CLI 后端冒烟：`pnpm test:docker:live-cli-backend`（脚本：`scripts/test-live-cli-backend-docker.sh`）
+- Codex app-server 测试框架冒烟：`pnpm test:docker:live-codex-harness`（脚本：`scripts/test-live-codex-harness-docker.sh`）
 - Gateway 网关 + dev 智能体：`pnpm test:docker:live-gateway`（脚本：`scripts/test-live-gateway-models-docker.sh`）
- Open WebUI live 冒烟测试：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`）
- onboarding 向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`）
- Npm tarball onboarding/渠道/智能体冒烟测试：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包好的 OpenClaw tarball，通过 env-ref onboarding 配置 OpenAI，并默认配置 Telegram，验证 doctor 会修复已激活 plugin 的运行时依赖，并运行一次 mock OpenAI 智能体轮次。可使用 `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，使用 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 跳过主机构建，或使用 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。
- Bun 全局安装冒烟测试：`bash scripts/e2e/bun-global-install-smoke.sh` 会打包当前工作树，在隔离的 home 中使用 `bun install -g` 安装，并验证 `openclaw infer image providers --json` 会返回内置图像提供商而不是卡住。可使用 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，使用 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 跳过主机构建，或通过 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 从已构建的 Docker 镜像复制 `dist/`。
- 安装器 Docker 冒烟测试：`bash scripts/test-install-sh-docker.sh` 会在其 root、update 和 direct-npm 容器之间共享一个 npm 缓存。更新冒烟测试默认以 npm `latest` 作为稳定基线，再升级到候选 tarball。非 root 安装器检查会保持一个隔离的 npm 缓存，以避免 root 所有的缓存条目掩盖用户本地安装行为。设置 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` 可在本地重跑之间复用 root/update/direct-npm 缓存。
- Install Smoke CI 会通过 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 跳过重复的 direct-npm 全局更新；当需要覆盖直接 `npm install -g` 时，请在本地运行脚本且不要设置该环境变量。
- Gateway 网关网络（两个容器，WS 认证 + health）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`）
- OpenAI Responses `web_search` 最小推理回归测试：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关运行一个 mock OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升到 `low`，然后强制 provider schema 拒绝，并检查原始细节是否出现在 Gateway 网关日志中。
- MCP 渠道桥接（预置 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟测试）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`）
- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 内嵌 Pi profile allow/deny 冒烟测试）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`）
- Cron/subagent MCP 清理（真实 Gateway 网关 + 独立 cron 和一次性 subagent 运行后的 stdio MCP 子进程清理）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`）
- Plugins（安装冒烟测试 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`）
- Plugin 更新无变化冒烟测试：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`）
- 配置热重载元数据冒烟测试：`pnpm test:docker:config-reload`（脚本：`scripts/e2e/config-reload-source-docker.sh`）
- 内置 plugin 运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在主机上构建并打包一次 OpenClaw，然后将该 tarball 挂载到每个 Linux 安装场景中。可使用 `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用镜像，在完成一次新的本地构建后使用 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 跳过主机重建，或通过 `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。完整 Docker 聚合会先预打包一次该 tarball，然后将内置渠道检查分片到独立通道中；直接运行内置通道时，可使用 `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` 收窄渠道矩阵。
- 在迭代时，可通过禁用无关场景来收窄内置 plugin 运行时依赖检查，例如：
+- Open WebUI 实时冒烟：`pnpm test:docker:openwebui`（脚本：`scripts/e2e/openwebui-docker.sh`）
+- 新手引导向导（TTY，完整脚手架）：`pnpm test:docker:onboard`（脚本：`scripts/e2e/onboard-docker.sh`）
+- Npm tarball 新手引导 / 渠道 / 智能体冒烟：`pnpm test:docker:npm-onboard-channel-agent` 会在 Docker 中全局安装打包后的 OpenClaw tarball，通过 env-ref 新手引导配置 OpenAI，并默认配置 Telegram，验证 doctor 会修复已激活插件的运行时依赖，然后运行一次模拟的 OpenAI 智能体轮次。通过 `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，通过 `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` 跳过宿主重建，或通过 `OPENCLAW_NPM_ONBOARD_CHANNEL=discord` 切换渠道。
+- Bun 全局安装冒烟：`bash scripts/e2e/bun-global-install-smoke.sh` 会打包当前工作树，在隔离的 home 中使用 `bun install -g` 安装，并验证 `openclaw infer image providers --json` 会返回内置图像提供商而不是挂起。通过 `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 复用预构建 tarball，通过 `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` 跳过宿主构建，或通过 `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local` 从已构建的 Docker 镜像复制 `dist/`。
+- 安装器 Docker 冒烟：`bash scripts/test-install-sh-docker.sh` 会在其 root、update 和 direct-npm 容器之间共享同一个 npm 缓存。更新冒烟默认使用 npm `latest` 作为稳定基线，再升级到候选 tarball。非 root 安装器检查会保留隔离的 npm 缓存，这样 root 所有的缓存条目就不会掩盖用户本地安装行为。设置 `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache` 可在本地重复运行之间复用 root / update / direct-npm 缓存。
+- Install Smoke CI 会通过 `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1` 跳过重复的 direct-npm 全局更新；当你需要直接 `npm install -g` 覆盖时，请在本地运行该脚本且不要设置此环境变量。
+- Gateway 网关网络（两个容器，WS 认证 + 健康检查）：`pnpm test:docker:gateway-network`（脚本：`scripts/e2e/gateway-network-docker.sh`）
+- OpenAI Responses `web_search` 最小推理回归：`pnpm test:docker:openai-web-search-minimal`（脚本：`scripts/e2e/openai-web-search-minimal-docker.sh`）会通过 Gateway 网关运行一个模拟的 OpenAI 服务器，验证 `web_search` 会将 `reasoning.effort` 从 `minimal` 提升为 `low`，然后强制提供商 schema 拒绝，并检查原始细节出现在 Gateway 网关日志中。
+- MCP 渠道桥接（已播种的 Gateway 网关 + stdio bridge + 原始 Claude 通知帧冒烟）：`pnpm test:docker:mcp-channels`（脚本：`scripts/e2e/mcp-channels-docker.sh`）
+- Pi bundle MCP 工具（真实 stdio MCP 服务器 + 嵌入式 Pi profile allow / deny 冒烟）：`pnpm test:docker:pi-bundle-mcp-tools`（脚本：`scripts/e2e/pi-bundle-mcp-tools-docker.sh`）
+- Cron / 子智能体 MCP 清理（真实 Gateway 网关 + 在隔离 cron 和一次性子智能体运行后拆除 stdio MCP 子进程）：`pnpm test:docker:cron-mcp-cleanup`（脚本：`scripts/e2e/cron-mcp-cleanup-docker.sh`）
+- 插件（安装冒烟 + `/plugin` 别名 + Claude bundle 重启语义）：`pnpm test:docker:plugins`（脚本：`scripts/e2e/plugins-docker.sh`）
+- 插件更新未变更冒烟：`pnpm test:docker:plugin-update`（脚本：`scripts/e2e/plugin-update-unchanged-docker.sh`）
+- 配置热重载元数据冒烟：`pnpm test:docker:config-reload`（脚本：`scripts/e2e/config-reload-source-docker.sh`）
+- 内置插件运行时依赖：`pnpm test:docker:bundled-channel-deps` 默认会构建一个小型 Docker 运行器镜像，在宿主机上构建并打包 OpenClaw 一次，然后将该 tarball 挂载到每个 Linux 安装场景中。通过 `OPENCLAW_SKIP_DOCKER_BUILD=1` 复用镜像，通过 `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` 在本地新鲜构建后跳过宿主重建，或通过 `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz` 指向现有 tarball。完整 Docker 聚合会先预打包该 tarball 一次，然后把内置渠道检查分片为独立通道；直接运行内置通道时，可使用 `OPENCLAW_BUNDLED_CHANNELS=telegram,slack` 缩小渠道矩阵。该通道还会验证 `channels.<id>.enabled=false` 和 `plugins.entries.<id>.enabled=false` 会抑制 doctor / 运行时依赖修复。
+- 在迭代时缩小内置插件运行时依赖范围，可禁用无关场景，例如：
  `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`。

-如需手动预构建并复用共享的 built-app 镜像：
+若要手动预构建并复用共享的 built-app 镜像：

 ```bash
 OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build
 OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels
 ```

-设置后，诸如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 之类的测试套件专用镜像覆盖仍然优先生效。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果该镜像尚未在本地存在，脚本会先拉取它。QR 和安装器 Docker 测试保留各自的 Dockerfile，因为它们验证的是 package/install 行为，而不是共享的 built-app 运行时。
+设置后，诸如 `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE` 这类测试套件专属镜像覆盖仍然优先生效。当 `OPENCLAW_SKIP_DOCKER_BUILD=1` 指向远程共享镜像时，如果该镜像尚未存在于本地，脚本会先拉取它。QR 和安装器 Docker 测试保留各自独立的 Dockerfile，因为它们验证的是包 / 安装行为，而不是共享的 built-app 运行时。

-live-model Docker 运行器还会以只读方式 bind-mount 当前 checkout，并将其暂存到容器内的临时工作目录中。这样既能保持运行时镜像精简，又仍能让 Vitest 针对你本地的精确源码/配置运行。
-暂存步骤会跳过大型的本地专用缓存和应用构建输出，例如
-`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地的 `.build` 或
-Gradle 输出目录，因此 Docker live 运行不会花上数分钟复制机器特定产物。
-它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 gateway live 探测就不会在容器内启动
-真实的 Telegram/Discord 等渠道 worker。
-`test:docker:live-models` 仍然会运行 `pnpm test:live`，因此当你需要从该 Docker 通道中收窄或排除 gateway live 覆盖时，也请一并传入
+实时模型 Docker 运行器还会将当前检出以只读方式绑定挂载，并在容器内部临时工作目录中进行暂存。这样既能保持运行时镜像轻量，又能让 Vitest 基于你精确的本地源码 / 配置运行。
+暂存步骤会跳过大型本地专用缓存和应用构建输出，例如
+`.pnpm-store`、`.worktrees`、`__openclaw_vitest__`，以及应用本地 `.build` 或
+Gradle 输出目录，因此 Docker 实时运行不会花费数分钟复制机器专属产物。
+它们还会设置 `OPENCLAW_SKIP_CHANNELS=1`，这样 Gateway 网关实时探测就不会在容器内启动
+真实的 Telegram / Discord / 等渠道工作进程。
+`test:docker:live-models` 仍然会运行 `pnpm test:live`，因此当你需要缩小或排除该 Docker 通道中的 Gateway 网关实时覆盖时，也请同时传入
 `OPENCLAW_LIVE_GATEWAY_*`。
-`test:docker:openwebui` 是一个更高层级的兼容性冒烟测试：它会启动一个启用了 OpenAI 兼容 HTTP 端点的
-OpenClaw gateway 容器，再针对该 gateway 启动一个固定版本的 Open WebUI 容器，通过
-Open WebUI 登录，验证 `/api/models` 暴露了 `openclaw/default`，然后通过
+`test:docker:openwebui` 是更高层级的兼容性冒烟测试：它会启动一个启用了
+OpenAI 兼容 HTTP 端点的 OpenClaw Gateway 网关容器，再针对该 Gateway 网关启动一个固定版本的 Open WebUI 容器，通过
+Open WebUI 登录，验证 `/api/models` 暴露 `openclaw/default`，然后通过
 Open WebUI 的 `/api/chat/completions` 代理发送一个真实聊天请求。
-第一次运行可能会明显更慢，因为 Docker 可能需要拉取
-Open WebUI 镜像，而且 Open WebUI 可能需要完成自身的冷启动设置。
-这个通道需要一个可用的 live 模型密钥，而 `OPENCLAW_PROFILE_FILE`
-（默认是 `~/.profile`）是在 Docker 化运行中提供它的主要方式。
-成功运行会输出一小段 JSON，例如 `{ "ok": true, "model":
+首次运行可能明显更慢，因为 Docker 可能需要拉取
+Open WebUI 镜像，而且 Open WebUI 可能需要完成自己的冷启动 setup。
+该通道需要一个可用的实时模型密钥，而 `OPENCLAW_PROFILE_FILE`
+（默认 `~/.profile`）是在 Docker 化运行中提供该密钥的主要方式。
+成功运行会打印一个小型 JSON payload，例如 `{ "ok": true, "model":
 "openclaw/default", ... }`。
-`test:docker:mcp-channels` 是刻意设计为确定性的，不需要真实的
-Telegram、Discord 或 iMessage 账户。它会启动一个预置的 Gateway 网关
-容器，再启动第二个容器来运行 `openclaw mcp serve`，然后
-通过真实的 stdio MCP bridge 验证路由后的会话发现、transcript 读取、附件元数据、
-live 事件队列行为、出站发送路由，以及 Claude 风格的渠道 +
+`test:docker:mcp-channels` 是刻意保持确定性的，不需要
+真实的 Telegram、Discord 或 iMessage 账号。它会启动一个已播种的 Gateway 网关
+容器，启动第二个容器来拉起 `openclaw mcp serve`，然后
+通过真实的 stdio MCP bridge 验证已路由会话发现、转录读取、附件元数据、
+实时事件队列行为、出站发送路由，以及 Claude 风格的渠道 +
 权限通知。通知检查会直接检查原始 stdio MCP 帧，因此该冒烟测试验证的是
 bridge 实际发出的内容，而不只是某个特定客户端 SDK 恰好暴露的内容。
-`test:docker:pi-bundle-mcp-tools` 是确定性的，不需要 live
-模型密钥。它会构建仓库 Docker 镜像，在容器内启动一个真实的 stdio MCP probe 服务器，
-通过内嵌 Pi bundle MCP 运行时实例化该服务器，执行该工具，然后验证 `coding` 和 `messaging` 保留
-`bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会将其过滤掉。
-`test:docker:cron-mcp-cleanup` 是确定性的，不需要 live 模型
-密钥。它会启动一个带真实 stdio MCP probe 服务器的预置 Gateway 网关，运行一个
-独立的 cron 轮次和一个 `/subagents spawn` 一次性子智能体轮次，然后验证
+`test:docker:pi-bundle-mcp-tools` 是确定性的，不需要实时
+模型密钥。它会构建仓库 Docker 镜像，在容器中启动一个真实 stdio MCP 探针服务器，
+通过嵌入式 Pi bundle MCP 运行时实例化该服务器，执行该工具，
+然后验证 `coding` 和 `messaging` 会保留
+`bundle-mcp` 工具，而 `minimal` 和 `tools.deny: ["bundle-mcp"]` 会过滤掉它们。
+`test:docker:cron-mcp-cleanup` 是确定性的，不需要实时模型
+密钥。它会启动一个带有真实 stdio MCP 探针服务器的已播种 Gateway 网关，运行一个隔离的
+cron 轮次和一个 `/subagents spawn` 一次性子智能体轮次，然后验证
 MCP 子进程会在每次运行后退出。

-手动 ACP 自然语言线程冒烟测试（不在 CI 中运行）：
+手动 ACP 自然语言线程冒烟（非 CI）：

 - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...`
- 将此脚本保留用于回归/调试工作流。它未来可能还会再次用于 ACP 线程路由验证，因此不要删除它。
+- 保留此脚本用于回归 / 调试工作流。未来可能还需要它来验证 ACP 线程路由，因此不要删除它。

-有用的环境变量：
+常用环境变量：

- `OPENCLAW_CONFIG_DIR=...`（默认：`~/.openclaw`）会挂载到 `/home/node/.openclaw`
- `OPENCLAW_WORKSPACE_DIR=...`（默认：`~/.openclaw/workspace`）会挂载到 `/home/node/.openclaw/workspace`
- `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）会挂载到 `/home/node/.profile`，并在运行测试前被读取
- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` 用于验证仅来自 `OPENCLAW_PROFILE_FILE` 的环境变量，此时会使用临时 config/workspace 目录且不挂载外部 CLI auth
- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）会挂载到 `/home/node/.npm-global`，用于 Docker 内缓存 CLI 安装
- `$HOME` 下的外部 CLI auth 目录/文件会以只读方式挂载到 `/host-auth...` 下，然后在测试开始前复制到 `/home/node/...`
+- `OPENCLAW_CONFIG_DIR=...`（默认：`~/.openclaw`）挂载到 `/home/node/.openclaw`
+- `OPENCLAW_WORKSPACE_DIR=...`（默认：`~/.openclaw/workspace`）挂载到 `/home/node/.openclaw/workspace`
+- `OPENCLAW_PROFILE_FILE=...`（默认：`~/.profile`）挂载到 `/home/node/.profile`，并在运行测试前加载
+- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` 用于仅验证从 `OPENCLAW_PROFILE_FILE` 加载的环境变量，使用临时配置 / 工作区目录，且不挂载外部 CLI 认证
+- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`（默认：`~/.cache/openclaw/docker-cli-tools`）挂载到 `/home/node/.npm-global`，用于 Docker 内缓存 CLI 安装
+- `$HOME` 下的外部 CLI 认证目录 / 文件会以只读方式挂载到 `/host-auth...`，然后在测试开始前复制到 `/home/node/...`
  - 默认目录：`.minimax`
  - 默认文件：`~/.codex/auth.json`、`~/.codex/config.toml`、`.claude.json`、`~/.claude/.credentials.json`、`~/.claude/settings.json`、`~/.claude/settings.local.json`
-  - 收窄后的 provider 运行只会挂载根据 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录/文件
-  - 可通过 `OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none` 或逗号列表（如 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`）手动覆盖
- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于收窄运行范围
+  - 缩小后的提供商运行只会挂载从 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` 推断出的所需目录 / 文件
+  - 手动覆盖方式：`OPENCLAW_DOCKER_AUTH_DIRS=all`、`OPENCLAW_DOCKER_AUTH_DIRS=none`，或逗号列表，例如 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`
+- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` 用于缩小运行范围
 - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` 用于在容器内筛选提供商
- `OPENCLAW_SKIP_DOCKER_BUILD=1` 用于复用现有的 `openclaw:local-live` 镜像，以便在无需重建时重跑
+- `OPENCLAW_SKIP_DOCKER_BUILD=1` 用于在不需要重建的重复运行中复用现有 `openclaw:local-live` 镜像
 - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 用于确保凭证来自 profile 存储（而不是环境变量）
- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择 gateway 为 Open WebUI 冒烟测试暴露的模型
- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试使用的 nonce-check prompt
- `OPENWEBUI_IMAGE=...` 用于覆盖固定版本的 Open WebUI 镜像标签
+- `OPENCLAW_OPENWEBUI_MODEL=...` 用于选择在 Open WebUI 冒烟测试中由 Gateway 网关暴露的模型
+- `OPENCLAW_OPENWEBUI_PROMPT=...` 用于覆盖 Open WebUI 冒烟测试所使用的 nonce 检查提示词
+- `OPENWEBUI_IMAGE=...` 用于覆盖固定的 Open WebUI 镜像标签

 ## 文档完整性检查

 修改文档后运行文档检查：`pnpm check:docs`。
-当你还需要检查页内标题锚点时，运行完整的 Mintlify 锚点校验：`pnpm docs:check-links:anchors`。
+如果还需要检查页内标题锚点，请运行完整的 Mintlify 锚点验证：`pnpm docs:check-links:anchors`。

 ## 离线回归（CI 安全）

-这些是在没有真实提供商的情况下进行的“真实流水线”回归测试：
+这些是“真实流水线”回归测试，但不需要真实提供商：

- Gateway 网关工具调用（mock OpenAI，真实 gateway + 智能体循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”）
- Gateway 网关向导（WS `wizard.start`/`wizard.next`，强制写入 config + auth）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”）
+- Gateway 网关工具调用（模拟 OpenAI、真实 Gateway 网关 + 智能体循环）：`src/gateway/gateway.test.ts`（用例：“runs a mock OpenAI tool call end-to-end via gateway agent loop”）
+- Gateway 网关向导（WS `wizard.start` / `wizard.next`，写入配置 + 强制认证）：`src/gateway/gateway.test.ts`（用例：“runs wizard over ws and writes auth token config”）

 ## 智能体可靠性评估（Skills）

-我们已经有一些对 CI 安全的测试，它们的行为类似“智能体可靠性评估”：
+我们已经有一些对 CI 安全的测试，其行为类似于“智能体可靠性评估”：

- 通过真实 gateway + 智能体循环进行 mock 工具调用（`src/gateway/gateway.test.ts`）。
+- 通过真实 Gateway 网关 + 智能体循环进行模拟工具调用（`src/gateway/gateway.test.ts`）。
 - 验证会话接线和配置效果的端到端向导流程（`src/gateway/gateway.test.ts`）。

-对于 Skills（见 [Skills](/zh-CN/tools/skills)），目前仍然缺少的是：
+对于 Skills，目前仍缺少的部分（见 [Skills](/zh-CN/tools/skills)）：

- **决策**：当 prompt 中列出 Skills 时，智能体是否会选择正确的 skill（或避免无关的 skill）？
- **合规性**：智能体在使用前是否会读取 `SKILL.md` 并遵循要求的步骤/参数？
- **工作流契约**：断言工具调用顺序、会话历史延续以及沙箱边界的多轮场景。
+- **决策：** 当提示词中列出 Skills 时，智能体是否会选择正确的 Skill（或避免选择无关的 Skill）？
+- **合规：** 智能体在使用前是否会读取 `SKILL.md`，并遵循要求的步骤 / 参数？
+- **工作流契约：** 断言工具顺序、会话历史延续和沙箱边界的多轮场景。

-未来的评估应首先保持确定性：
+未来的评估应优先保持确定性：

- 一个使用 mock 提供商的场景运行器，用于断言工具调用 + 顺序、skill 文件读取以及会话接线。
- 一组小型的 skill 聚焦场景（使用 vs 避免、门控、prompt injection）。
- 仅在 CI 安全测试套件落地之后，才添加可选的 live 评估（按需启用、受环境变量门控）。
+- 一个使用模拟提供商的场景运行器，用于断言工具调用与顺序、Skill 文件读取以及会话接线。
+- 一小组聚焦 Skill 的场景（使用 vs 避免、门控、提示注入）。
+- 只有在 CI 安全套件就绪之后，才添加可选的实时评估（按需启用、由环境变量门控）。

-## 契约测试（plugin 和 channel 结构）
+## 契约测试（插件和渠道形状）

-契约测试用于验证每个已注册的 plugin 和 channel 都符合其接口契约。它们会遍历所有已发现的 plugins，并运行一组关于结构和行为的断言。默认的 `pnpm test` unit 通道会有意跳过这些共享接口和冒烟文件；当你修改共享的 channel 或 provider 表面时，请显式运行契约测试命令。
+契约测试用于验证每个已注册插件和渠道都符合其接口契约。它们会遍历所有已发现的插件，并运行一组关于形状和行为的断言。默认的 `pnpm test` 单元测试通道会刻意跳过这些共享接缝和冒烟文件；当你修改共享渠道或提供商接口时，请显式运行契约命令。

 ### 命令

- 所有契约测试：`pnpm test:contracts`
- 仅 channel 契约测试：`pnpm test:contracts:channels`
- 仅 provider 契约测试：`pnpm test:contracts:plugins`
+- 所有契约：`pnpm test:contracts`
+- 仅渠道契约：`pnpm test:contracts:channels`
+- 仅提供商契约：`pnpm test:contracts:plugins`

-### Channel 契约测试
+### 渠道契约

 位于 `src/channels/plugins/contracts/*.contract.test.ts`：

- **plugin** - 基本 plugin 结构（id、name、capabilities）
+- **plugin** - 基础插件形状（id、名称、能力）
 - **setup** - 设置向导契约
 - **session-binding** - 会话绑定行为
 - **outbound-payload** - 消息 payload 结构
 - **inbound** - 入站消息处理
- **actions** - 渠道 action 处理器
+- **actions** - 渠道操作处理器
 - **threading** - 线程 ID 处理
- **directory** - 目录/成员列表 API
- **group-policy** - 群组策略强制执行
+- **directory** - 目录 / 花名册 API
+- **group-policy** - 群组策略执行

-### Provider 状态契约测试
+### 提供商状态契约

 位于 `src/plugins/contracts/*.contract.test.ts`。

 - **status** - 渠道状态探测
- **registry** - Plugin 注册表结构
+- **registry** - 插件注册表形状

-### Provider 契约测试
+### 提供商契约

 位于 `src/plugins/contracts/*.contract.test.ts`：

 - **auth** - 认证流程契约
- **auth-choice** - 认证选择/选择机制
+- **auth-choice** - 认证选项 / 选择
 - **catalog** - 模型目录 API
- **discovery** - Plugin 发现
- **loader** - Plugin 加载
- **runtime** - Provider 运行时
- **shape** - Plugin 结构/接口
+- **discovery** - 插件发现
+- **loader** - 插件加载
+- **runtime** - 提供商运行时
+- **shape** - 插件形状 / 接口
 - **wizard** - 设置向导

 ### 何时运行

- 修改 `plugin-sdk` 导出或子路径之后
- 添加或修改 channel 或 provider plugin 之后
- 重构 plugin 注册或发现逻辑之后
+- 修改 plugin-sdk 导出或子路径之后
+- 添加或修改渠道或提供商插件之后
+- 重构插件注册或发现逻辑之后

-契约测试会在 CI 中运行，且不需要真实 API key。
+契约测试会在 CI 中运行，不需要真实 API 密钥。

-## 添加回归测试（指南）
+## 添加回归测试（指导）

-当你修复一个在 live 中发现的 provider/model 问题时：
+当你修复一个在实时环境中发现的提供商 / 模型问题时：

- 如果可能，请添加一个对 CI 安全的回归测试（mock/stub provider，或捕获精确的请求结构转换）
- 如果问题本质上只能在 live 中复现（速率限制、认证策略），请保持 live 测试足够收窄，并通过环境变量按需启用
- 优先定位到能够捕获该缺陷的最小层级：
-  - provider 请求转换/重放缺陷 → 直连模型测试
-  - gateway 会话/历史/工具管线缺陷 → gateway live 冒烟测试或对 CI 安全的 gateway mock 测试
- SecretRef 遍历保护栏：
-  - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类推导一个采样目标，然后断言会拒绝 traversal-segment exec id。
-  - 如果你在 `src/secrets/target-registry-data.ts` 中添加了新的 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会在出现未分类 target id 时故意失败，这样新类别就不会被悄悄跳过。
+- 如果可能，添加一个对 CI 安全的回归测试（模拟 / stub 提供商，或捕获精确的请求形状转换）
+- 如果它本质上只能在实时环境中复现（速率限制、认证策略），就让实时测试保持窄范围，并通过环境变量按需启用
+- 优先瞄准能够捕获该缺陷的最小层级：
+  - 提供商请求转换 / 回放缺陷 → 直接模型测试
+  - Gateway 网关会话 / 历史 / 工具流水线缺陷 → Gateway 网关实时冒烟或对 CI 安全的 Gateway 网关模拟测试
+- SecretRef 遍历防护栏：
+  - `src/secrets/exec-secret-ref-id-parity.test.ts` 会从注册表元数据（`listSecretTargetRegistryEntries()`）中为每个 SecretRef 类派生一个采样目标，然后断言遍历段 exec id 会被拒绝。
+  - 如果你在 `src/secrets/target-registry-data.ts` 中添加了新的 `includeInPlan` SecretRef 目标族，请更新该测试中的 `classifyTargetClass`。该测试会在遇到未分类目标 id 时有意失败，这样新类别就无法被静默跳过。

 ## 相关内容

- [Testing live](/zh-CN/help/testing-live)
+- [实时测试](/zh-CN/help/testing-live)
 - [CI](/zh-CN/ci)
--- a/docs/zh-CN/install/updating.md
+++ b/docs/zh-CN/install/updating.md
@ -1,14 +1,14 @@
 ---
 read_when:
    - 更新 OpenClaw
-    - 更新后出现问题时
+    - 更新后出现问题
 summary: 安全更新 OpenClaw（全局安装或源码安装），以及回滚策略
-title: 更新♀♀♀analysis to=final code  omitted
+title: 更新
 x-i18n:
-    generated_at: "2026-04-23T20:53:22Z"
+    generated_at: "2026-04-24T16:58:27Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 04ed583916ce64c9f60639c8145a46ce5b27ebf5a6dfd09924312d7acfefe1ab
+    source_hash: f57c5f4d4988eabb62a2c836c07f56e329149b1f9290baa0568ef1d86f66e0ad
    source_path: install/updating.md
    workflow: 15
 ---
@ -17,13 +17,13 @@ x-i18n:

 ## 推荐：`openclaw update`

-这是最快的更新方式。它会检测你的安装类型（npm 或 git）、获取最新版本、运行 `openclaw doctor`，并重启 gateway。
+这是最快的更新方式。它会检测你的安装类型（npm 或 git），获取最新版本，运行 `openclaw doctor`，并重启 Gateway 网关。

 ```bash
 openclaw update
 ```

-若要切换渠道或指定特定版本：
+如需切换渠道或指定特定版本：

 ```bash
 openclaw update --channel beta
@ -31,12 +31,11 @@ openclaw update --tag main
 openclaw update --dry-run   # 仅预览，不实际应用
 ```

-`--channel beta` 会优先选择 beta，但当
-beta 标签缺失或比最新稳定版更旧时，运行时会回退到 stable/latest。若你想在一次性包更新中使用原始 npm beta dist-tag，请使用 `--tag beta`。
+`--channel beta` 会优先选择 beta，但当 beta 标签不存在或版本比最新 stable 发布更旧时，运行时会回退到 stable/latest。如果你想要一次性按原始 npm beta dist-tag 更新包，请使用 `--tag beta`。

-有关渠道语义，请参见 [Development channels](/zh-CN/install/development-channels)。
+渠道语义请参见 [Development channels](/zh-CN/install/development-channels)。

-## 另一种方式：重新运行安装器
+## 另一种方式：重新运行安装脚本

 ```bash
 curl -fsSL https://openclaw.ai/install.sh | bash
@ -60,25 +59,26 @@ bun add -g openclaw@latest

 ### 由 root 拥有的全局 npm 安装

-某些 Linux npm 设置会将全局包安装到由 root 拥有的目录中，例如
-`/usr/lib/node_modules/openclaw`。OpenClaw 支持这种布局：已安装的
-包在运行时会被视为只读，而内置插件运行时依赖会被暂存到可写运行时目录中，而不是修改
-包树。
+某些 Linux npm 环境会将全局包安装到由 root 拥有的目录中，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 支持这种布局：已安装的包在运行时会被视为只读，内置插件的运行时依赖会被暂存到可写的运行时目录中，而不是修改包目录树。

-对于加固后的 systemd unit，请设置一个可写暂存目录，并将其包含在
-`ReadWritePaths` 中：
+对于加固的 systemd 单元，请设置一个可写的暂存目录，并将其包含在 `ReadWritePaths` 中：

 ```ini
 Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps
 ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
 ```

-如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在
-systemd 提供时使用 `$STATE_DIRECTORY`，否则回退到 `~/.openclaw/plugin-runtime-deps`。
+如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供时使用 `$STATE_DIRECTORY`，否则回退到 `~/.openclaw/plugin-runtime-deps`。
+
+### 内置插件运行时依赖
+
+打包安装会将内置插件运行时依赖保留在只读包目录树之外。在启动期间以及执行 `openclaw doctor --fix` 时，OpenClaw 只会为以下内置插件修复运行时依赖：在配置中处于活动状态、通过旧版渠道配置处于活动状态，或由其内置清单默认启用的插件。
+
+显式禁用具有最高优先级。已禁用的插件或渠道不会仅因为存在于安装包中就修复其运行时依赖。外部插件和自定义加载路径仍然使用 `openclaw plugins install` 或 `openclaw plugins update`。

 ## 自动更新器

-自动更新器默认关闭。可在 `~/.openclaw/openclaw.json` 中启用：
+自动更新器默认关闭。在 `~/.openclaw/openclaw.json` 中启用它：

 ```json5
 {
@ -94,13 +94,13 @@ systemd 提供时使用 `$STATE_DIRECTORY`，否则回退到 `~/.openclaw/plugin
 }
 ```

-| 渠道 | 行为 |
-| -------- | ------------------------------------------------------------------------------------------------------------- |
-| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内以确定性抖动方式应用（分散发布）。 |
-| `beta` | 每 `betaCheckIntervalHours` 检查一次（默认：每小时），并立即应用。 |
-| `dev` | 不会自动应用。请手动使用 `openclaw update`。 |
+| Channel  | 行为 |
+| -------- | ---- |
+| `stable` | 等待 `stableDelayHours`，然后在 `stableJitterHours` 范围内按确定性抖动应用（分散发布）。 |
+| `beta`   | 每隔 `betaCheckIntervalHours` 检查一次（默认：每小时），并立即应用。 |
+| `dev`    | 不会自动应用。请手动使用 `openclaw update`。 |

-gateway 还会在启动时记录更新提示（可通过 `update.checkOnStart: false` 禁用）。
+Gateway 网关还会在启动时记录更新提示（可通过 `update.checkOnStart: false` 禁用）。

 ## 更新后

@ -112,9 +112,9 @@ gateway 还会在启动时记录更新提示（可通过 `update.checkOnStart: f
 openclaw doctor
 ```

-迁移配置、审计私信策略并检查 gateway 健康状态。详情请参见：[Doctor](/zh-CN/gateway/doctor)
+迁移配置、审核私信策略，并检查 Gateway 网关健康状态。详情： [Doctor](/zh-CN/gateway/doctor)

-### 重启 gateway
+### 重启 Gateway 网关

 ```bash
 openclaw gateway restart
@ -138,7 +138,7 @@ openclaw doctor
 openclaw gateway restart
 ```

-提示：`npm view openclaw version` 会显示当前已发布版本。
+提示：`npm view openclaw version` 会显示当前已发布的版本。

 ### 固定提交（源码）

@ -149,14 +149,14 @@ pnpm install && pnpm build
 openclaw gateway restart
 ```

-若要恢复到最新版本：`git checkout main && git pull`。
+如需恢复到最新版本：`git checkout main && git pull`。

 ## 如果你卡住了

- 再次运行 `openclaw doctor`，并仔细阅读输出。
- 对于源码检出上的 `openclaw update --channel dev`，更新器会在需要时自动引导 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后重新运行更新。
- 请查看：[Troubleshooting](/zh-CN/gateway/troubleshooting)
- 可在 Discord 中提问：[https://discord.gg/clawd](https://discord.gg/clawd)
+- 再次运行 `openclaw doctor`，并仔细阅读输出内容。
+- 对于源码检出的 `openclaw update --channel dev`，更新器会在需要时自动引导安装 `pnpm`。如果你看到 pnpm/corepack 引导错误，请手动安装 `pnpm`（或重新启用 `corepack`），然后重新运行更新。
+- 查看：[故障排除](/zh-CN/gateway/troubleshooting)
+- 在 Discord 中提问：[https://discord.gg/clawd](https://discord.gg/clawd)

 ## 相关内容

--- a/docs/zh-CN/providers/openai.md
+++ b/docs/zh-CN/providers/openai.md
@ -3,36 +3,45 @@ read_when:
    - 你想在 OpenClaw 中使用 OpenAI 模型
    - 你想使用 Codex 订阅认证，而不是 API 密钥
    - 你需要更严格的 GPT-5 智能体执行行为
-summary: 在 OpenClaw 中使用 API 密钥或 Codex 订阅来接入 OpenAI
+summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
 title: OpenAI
 x-i18n:
-    generated_at: "2026-04-24T05:42:15Z"
+    generated_at: "2026-04-24T16:58:29Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 3d533338fa15d866bb69584706162ce099bb4a1edc9851183fb5442730ebdd9b
+    source_hash: bedc8975dae28e13d653494723ca0ee44cefdb63cbd4c6397658bd22fd8c3d80
    source_path: providers/openai.md
    workflow: 15
 ---

-OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列接入路径。模型前缀决定所使用的路径：
+OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列路由。模型前缀决定所使用的路由：

- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型）
- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录，并通过订阅获得访问权限（`openai-codex/*` 模型）
- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，外加 `agents.defaults.embeddedHarness.runtime: "codex"`）
+- **API 密钥** — 通过按量计费直接访问 OpenAI Platform（`openai/*` 模型）
+- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型）
+- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，并配合 `agents.defaults.embeddedHarness.runtime: "codex"`）

 OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用基于订阅的 OAuth。

+## 快速选择
+
+| 目标 | 使用方式 | 说明 |
+| --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| 直接使用 API 密钥计费 | `openai/gpt-5.4` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API 密钥新手引导。 |
+| 通过 ChatGPT/Codex 订阅认证使用 GPT-5.5 | `openai-codex/gpt-5.5` | 这是 Codex OAuth 的默认 PI 路由。对于订阅配置来说，是最佳的首选方案。 |
+| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `embeddedHarness.runtime: "codex"` | 使用 Codex app-server harness，而不是公开的 OpenAI API 路由。 |
+| 图像生成或编辑 | `openai/gpt-image-2` | 可搭配 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 使用。 |
+
 <Note>
-GPT-5.5 当前可通过订阅/OAuth 路径在 OpenClaw 中使用：
-`openai-codex/gpt-5.5` 配合 PI runner，或 `openai/gpt-5.5` 配合
-Codex app-server harness。`openai/gpt-5.5` 的直接 API 密钥访问
-会在 OpenAI 为公共 API 启用 GPT-5.5 后受支持；在此之前，请为
-`OPENAI_API_KEY` 配置使用支持 API 的模型，例如 `openai/gpt-5.4`。
+GPT-5.5 当前可在 OpenClaw 中通过订阅 / OAuth 路由使用：
+`openai-codex/gpt-5.5` 搭配 PI runner，或 `openai/gpt-5.5` 搭配
+Codex app-server harness。对于 `openai/gpt-5.5` 的直接 API 密钥访问，
+会在 OpenAI 为公开 API 启用 GPT-5.5 后受支持；在此之前，对于
+`OPENAI_API_KEY` 配置，请使用已启用 API 的模型，例如 `openai/gpt-5.4`。
 </Note>

 <Note>
 启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会启用内置的
-Codex app-server 插件。只有当你显式选择原生 Codex harness，即设置
+Codex app-server 插件。只有当你显式选择原生 Codex harness，并设置
 `embeddedHarness.runtime: "codex"`，或使用旧版 `codex/*` 模型引用时，
 OpenClaw 才会启用该插件。
 </Note>
@ -42,28 +51,28 @@ OpenClaw 才会启用该插件。
 | OpenAI 能力 | OpenClaw 表面 | 状态 |
 | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
 | 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
-| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
-| Codex app-server harness | 使用 `embeddedHarness.runtime: codex` 的 `openai/<model>` | 是 |
-| 服务端 web 搜索 | 原生 OpenAI Responses 工具 | 是，当启用 web 搜索且未固定提供商时 |
+| Codex 订阅模型 | `openai-codex/<model>` 搭配 `openai-codex` OAuth | 是 |
+| Codex app-server harness | `openai/<model>` 搭配 `embeddedHarness.runtime: codex` | 是 |
+| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
 | 图像 | `image_generate` | 是 |
 | 视频 | `video_generate` | 是 |
-| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
+| 文字转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
 | 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
 | 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
 | 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 |
-| Embeddings | memory embedding 提供商 | 是 |
+| Embeddings | memory embedding provider | 是 |

 ## 入门指南

-选择你偏好的认证方式，并按照设置步骤进行操作。
+选择你偏好的认证方式，并按照设置步骤操作。

 <Tabs>
  <Tab title="API 密钥（OpenAI Platform）">
-    **最适合：** 直接访问 API，并按使用量计费。
+    **最适合：** 直接 API 访问和按量计费。

    <Steps>
-      <Step title="获取你的 API 密钥">
-        在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 中创建或复制 API 密钥。
+      <Step title="获取 API 密钥">
+        在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。
      </Step>
      <Step title="运行新手引导">
        ```bash
@ -76,24 +85,24 @@ OpenClaw 才会启用该插件。
        openclaw onboard --openai-api-key "$OPENAI_API_KEY"
        ```
      </Step>
-      <Step title="验证模型是否可用">
+      <Step title="验证模型可用">
        ```bash
        openclaw models list --provider openai
        ```
      </Step>
    </Steps>

-    ### 路径摘要
+    ### 路由摘要

-    | Model ref | 路径 | 认证 |
+    | 模型引用 | 路由 | 认证 |
    |-----------|-------|------|
    | `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
    | `openai/gpt-5.4-mini` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
-    | `openai/gpt-5.5` | 一旦 OpenAI 在 API 中启用 GPT-5.5 后的未来直接 API 路径 | `OPENAI_API_KEY` |
+    | `openai/gpt-5.5` | 一旦 OpenAI 在 API 上启用 GPT-5.5 后可用的未来直接 API 路由 | `OPENAI_API_KEY` |

    <Note>
-    `openai/*` 默认是直接 OpenAI API 密钥路径，除非你显式强制使用
-    Codex app-server harness。GPT-5.5 本身当前仅支持订阅/OAuth；
+    除非你显式强制使用 Codex app-server harness，否则 `openai/*`
+    就是直接使用 OpenAI API 密钥的路由。GPT-5.5 本身当前仅支持订阅 / OAuth；
    如需通过默认 PI runner 使用 Codex OAuth，请使用 `openai-codex/*`。
    </Note>

@ -107,7 +116,7 @@ OpenClaw 才会启用该插件。
    ```

    <Warning>
-    OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也同样未提供它。
+    OpenClaw **不**公开提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，而当前 Codex 目录也不会公开它。
    </Warning>

  </Tab>
@ -127,7 +136,7 @@ OpenClaw 才会启用该插件。
        openclaw models auth login --provider openai-codex
        ```

-        对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调：
+        对于无头环境或不适合回调主机的配置，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调：

        ```bash
        openclaw models auth login --provider openai-codex --device-code
@ -138,23 +147,23 @@ OpenClaw 才会启用该插件。
        openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
        ```
      </Step>
-      <Step title="验证模型是否可用">
+      <Step title="验证模型可用">
        ```bash
        openclaw models list --provider openai-codex
        ```
      </Step>
    </Steps>

-    ### 路径摘要
+    ### 路由摘要

-    | Model ref | 路径 | 认证 |
+    | 模型引用 | 路由 | 认证 |
    |-----------|-------|------|
    | `openai-codex/gpt-5.5` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 |
    | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | Codex app-server 认证 |

    <Note>
-    对于认证/配置文件命令，请继续使用 `openai-codex` provider id。
-    `openai-codex/*` 模型前缀也是 Codex OAuth 通过 PI 的显式路径。
+    继续对认证 / 配置文件命令使用 `openai-codex` 提供商 id。
+    `openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路由。
    它不会选择或自动启用内置的 Codex app-server harness。
    </Note>

@ -167,28 +176,29 @@ OpenClaw 才会启用该插件。
    ```

    <Note>
-    新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在自己的智能体认证存储中管理生成的凭证。
+    新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
    </Note>

    ### 状态指示器

-    聊天中的 `/status` 会显示当前会话正在使用哪个嵌入式 harness。
-    默认的 PI harness 显示为 `Runner: pi (embedded)`，不会额外添加单独标记。
-    当选中内置 Codex app-server harness 时，`/status` 会在 `Fast` 后附加非 PI 的 harness id，例如
-    `Fast · codex`。现有会话会保留其已记录的 harness id，因此如果你在更改
+    聊天中的 `/status` 会显示当前
+    会话正在使用哪个嵌入式 harness。默认的 PI harness 会显示为 `Runner: pi (embedded)`，
+    不会额外添加单独的徽标。当选择内置的 Codex app-server harness 时，
+    `/status` 会在 `Fast` 旁附加非 PI harness id，例如
+    `Fast · codex`。现有会话会保留其记录的 harness id，因此如果你在更改
    `embeddedHarness` 后希望 `/status` 反映新的 PI/Codex 选择，请使用
    `/new` 或 `/reset`。

    ### 上下文窗口上限

-    OpenClaw 将模型元数据与运行时上下文上限视为两个独立的值。
+    OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。

    对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`：

    - 原生 `contextWindow`：`1000000`
    - 默认运行时 `contextTokens` 上限：`272000`

-    在实践中，这个更小的默认上限通常具有更好的延迟和质量特性。你可以用 `contextTokens` 覆盖它：
+    实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它：

    ```json5
    {
@ -203,27 +213,34 @@ OpenClaw 才会启用该插件。
    ```

    <Note>
-    使用 `contextWindow` 来声明模型原生元数据。使用 `contextTokens` 来限制运行时上下文预算。
+    使用 `contextWindow` 声明模型原生元数据。使用 `contextTokens` 限制运行时上下文预算。
    </Note>

+    ### 目录恢复
+
+    当存在时，OpenClaw 会对 `gpt-5.5` 使用上游 Codex 目录元数据。
+    如果实时 Codex 发现结果在账户已认证的情况下遗漏了 `openai-codex/gpt-5.5` 这一行，
+    OpenClaw 会合成该 OAuth 模型行，以便 cron、子智能体和已配置默认模型的运行
+    不会因 `Unknown model` 而失败。
+
  </Tab>
 </Tabs>

 ## 图像生成

 内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。
-它同时支持通过 OpenAI API 密钥进行图像生成，以及通过 Codex OAuth
-使用同一个 `openai/gpt-image-2` 模型引用进行图像生成。
+它通过同一个 `openai/gpt-image-2` 模型引用，同时支持基于 OpenAI API 密钥的图像生成
+和基于 Codex OAuth 的图像生成。

 | 能力 | OpenAI API 密钥 | Codex OAuth |
 | ------------------------- | ---------------------------------- | ------------------------------------ |
-| Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` |
+| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
 | 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
 | 传输 | OpenAI Images API | Codex Responses 后端 |
-| 每次请求最大图像数 | 4 | 4 |
-| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
+| 每次请求的最大图像数 | 4 | 4 |
+| 编辑模式 | 已启用（最多 5 张参考图） | 已启用（最多 5 张参考图） |
 | 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
-| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射到受支持尺寸 |
+| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API | 在安全的情况下映射到受支持的尺寸 |

 ```json5
 {
@ -236,27 +253,27 @@ OpenClaw 才会启用该插件。
 ```

 <Note>
-有关共享工具参数、提供商选择和故障切换行为，请参见 [Image Generation](/zh-CN/tools/image-generation)。
+有关共享工具参数、提供商选择和故障转移行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。
 </Note>

-`gpt-image-2` 是 OpenAI 文本生成图像和图像编辑的默认模型。
-`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流
-应使用 `openai/gpt-image-2`。
+`gpt-image-2` 是 OpenAI 文生图生成和图像编辑的默认模型。
+`gpt-image-1` 仍可作为显式模型覆盖继续使用，但新的
+OpenAI 图像工作流应使用 `openai/gpt-image-2`。

-对于 Codex OAuth 安装，请保持使用相同的 `openai/gpt-image-2` 引用。
-当已配置 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该已存储的 OAuth
-访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试
-`OPENAI_API_KEY`，也不会为该请求静默回退到 API 密钥。
-当你希望改用直接 OpenAI Images API 路径时，请使用 API 密钥、
-自定义 base URL 或 Azure endpoint 显式配置 `models.providers.openai`。
-如果该自定义图像端点位于受信任的 LAN/私有地址上，还需要设置
-`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若未显式启用此项，
-OpenClaw 会继续阻止私有/内部的 OpenAI 兼容图像端点。
+对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。当配置了
+`openai-codex` OAuth 配置文件时，OpenClaw 会解析该已存储的 OAuth
+访问令牌，并通过 Codex Responses 后端发送图像请求。对于该请求，它不会先尝试
+`OPENAI_API_KEY`，也不会静默回退到 API 密钥。
+当你想改用直接 OpenAI Images API 路由时，请显式配置
+`models.providers.openai`，并提供 API 密钥、自定义 base URL 或 Azure 端点。
+如果该自定义图像端点位于受信任的局域网 / 私有地址上，还需同时设置
+`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若未显式选择加入，
+OpenClaw 会继续阻止访问私有 / 内部的 OpenAI 兼容图像端点。

 生成：

 ```
-/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精致的发布海报" size=3840x2160 count=1
+/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精美的发布海报" size=3840x2160 count=1
 ```

 编辑：
@ -272,10 +289,10 @@ OpenClaw 会继续阻止私有/内部的 OpenAI 兼容图像端点。
 | 能力 | 值 |
 | ---------------- | --------------------------------------------------------------------------------- |
 | 默认模型 | `openai/sora-2` |
-| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
-| 参考输入 | 1 张图像或 1 个视频 |
+| 模式 | 文生视频、图生视频、单视频编辑 |
+| 参考输入 | 1 张图片或 1 个视频 |
 | 尺寸覆盖 | 支持 |
-| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 |
+| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 |

 ```json5
 {
@ -288,20 +305,20 @@ OpenClaw 会继续阻止私有/内部的 OpenAI 兼容图像端点。
 ```

 <Note>
-有关共享工具参数、提供商选择和故障切换行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。
+有关共享工具参数、提供商选择和故障转移行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。
 </Note>

 ## GPT-5 提示词贡献

-OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.4`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的叠加层。较旧的 GPT-4.x 模型则不会。
+OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.4`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会接收相同的覆盖层。较旧的 GPT-4.x 模型则不会。

-内置的原生 Codex harness 通过 Codex app-server developer instructions 使用相同的 GPT-5 行为和心跳叠加层，因此，即使 Codex 接管了其余的 harness 提示词，强制通过 `embeddedHarness.runtime: "codex"` 运行的 `openai/gpt-5.x` 会话仍会保留相同的持续跟进和主动心跳指导。
+内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖层，因此即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.x` 会话仍会保留相同的后续执行和主动心跳指引。

-这个 GPT-5 贡献增加了一个带标签的行为约定，用于规范 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证。特定于渠道的回复行为和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层则是独立的，并且可配置。
+GPT-5 贡献添加了一个带标签的行为契约，用于定义人设持久性、执行安全、工具纪律、输出形态、完成检查和验证。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指引始终启用。友好交互风格层是独立的，并且可配置。

 | 值 | 效果 |
 | ---------------------- | ------------------------------------------- |
-| `"friendly"`（默认） | 启用友好的交互风格层 |
+| `"friendly"`（默认） | 启用友好交互风格层 |
 | `"on"` | `"friendly"` 的别名 |
 | `"off"` | 仅禁用友好风格层 |

@ -327,14 +344,14 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提
 </Tabs>

 <Tip>
-在运行时，这些值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
+运行时对值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
 </Tip>

 <Note>
-当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 配置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。
+当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。
 </Note>

-## 语音与语音识别
+## 语音和语音识别

 <AccordionGroup>
  <Accordion title="语音合成（TTS）">
@ -343,14 +360,14 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提
    | 设置 | 配置路径 | 默认值 |
    |---------|------------|---------|
    | 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
-    | 声音 | `messages.tts.providers.openai.voice` | `coral` |
-    | 语速 | `messages.tts.providers.openai.speed` | （未设置） |
+    | 语音 | `messages.tts.providers.openai.voice` | `coral` |
+    | 速度 | `messages.tts.providers.openai.speed` | （未设置） |
    | 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
    | 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` |
    | API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
    | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |

-    可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用声音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
+    可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。

    ```json5
    {
@ -365,23 +382,23 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提
    ```

    <Note>
-    设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 base URL，而不会影响聊天 API endpoint。
+    设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS base URL，而不会影响聊天 API 端点。
    </Note>

  </Accordion>

  <Accordion title="语音转文本">
    内置的 `openai` 插件通过
-    OpenClaw 的媒体理解转录表面注册了批量语音转文本功能。
+    OpenClaw 的媒体理解转写表面注册了批量语音转文本功能。

    - 默认模型：`gpt-4o-transcribe`
-    - Endpoint：OpenAI REST `/v1/audio/transcriptions`
+    - 端点：OpenAI REST `/v1/audio/transcriptions`
    - 输入路径：multipart 音频文件上传
-    - 在 OpenClaw 中，只要入站音频转录使用
-      `tools.media.audio`，就支持该功能，包括 Discord 语音频道片段和渠道
+    - 在 OpenClaw 中，凡是入站音频转写使用
+      `tools.media.audio` 的地方都受支持，包括 Discord 语音频道片段和渠道
      音频附件

-    要强制对入站音频转录使用 OpenAI：
+    要强制将 OpenAI 用于入站音频转写：

    ```json5
    {
@ -401,13 +418,13 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提
    }
    ```

-    当共享音频媒体配置或单次转录请求提供了语言和提示信息时，
-    OpenClaw 会将它们转发给 OpenAI。
+    当共享音频媒体配置或每次调用的转写请求提供了
+    语言和提示词提示时，它们会被转发给 OpenAI。

  </Accordion>

-  <Accordion title="实时转录">
-    内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。
+  <Accordion title="实时转写">
+    内置的 `openai` 插件为 Voice Call 插件注册了实时转写功能。

    | 设置 | 配置路径 | 默认值 |
    |---------|------------|---------|
@ -419,7 +436,7 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提
    | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |

    <Note>
-    使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
+    使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，音频格式为 G.711 u-law（`g711_ulaw` / `audio/pcmu`）。这个流式提供商用于 Voice Call 的实时转写路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转写路径。
    </Note>

  </Accordion>
@ -430,8 +447,8 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提
    | 设置 | 配置路径 | 默认值 |
    |---------|------------|---------|
    | 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
-    | 声音 | `...openai.voice` | `alloy` |
-    | Temperature | `...openai.temperature` | `0.8` |
+    | 语音 | `...openai.voice` | `alloy` |
+    | 温度 | `...openai.temperature` | `0.8` |
    | VAD 阈值 | `...openai.vadThreshold` | `0.5` |
    | 静音时长 | `...openai.silenceDurationMs` | `500` |
    | API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
@ -443,26 +460,30 @@ OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提
  </Accordion>
 </AccordionGroup>

-## Azure OpenAI endpoint
+## Azure OpenAI 端点

-内置的 `openai` 提供商可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 中的 Azure 主机名，并自动切换到 Azure 的请求格式。
+内置的 `openai` 提供商可以通过覆盖 base URL，
+将图像生成请求发送到 Azure OpenAI 资源。在图像生成路径上，OpenClaw
+会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到
+Azure 的请求格式。

 <Note>
 实时语音使用单独的配置路径
 （`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），
-不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置请参见
-[语音与语音识别](#voice-and-speech) 下 **实时语音** 折叠面板。
+不会受到 `models.providers.openai.baseUrl` 的影响。相关 Azure
+设置请参阅 [Voice and speech](#voice-and-speech) 下的 **Realtime
+voice** 折叠面板。
 </Note>

 在以下情况下使用 Azure OpenAI：

 - 你已经拥有 Azure OpenAI 订阅、配额或企业协议
 - 你需要 Azure 提供的区域数据驻留或合规控制
- 你希望将流量保留在现有的 Azure tenancy 内部
+- 你希望将流量保留在现有的 Azure 租户内

 ### 配置

-对于通过内置 `openai` 提供商进行的 Azure 图像生成，请将
+要通过内置 `openai` 提供商使用 Azure 图像生成，请将
 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为
 Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：

@ -479,97 +500,99 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
 }
 ```

-OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路径：
+OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成
+路由：

 - `*.openai.azure.com`
 - `*.services.ai.azure.com`
 - `*.cognitiveservices.azure.com`

-对于发送到已识别 Azure 主机的图像生成请求，OpenClaw 会：
+对于发往已识别 Azure 主机的图像生成请求，OpenClaw 会：

- 发送 `api-key` header，而不是 `Authorization: Bearer`
- 使用部署作用域路径（`/openai/deployments/{deployment}/...`）
- 为每个请求附加 `?api-version=...`
+- 发送 `api-key` 请求头，而不是 `Authorization: Bearer`
+- 使用基于 deployment 的路径（`/openai/deployments/{deployment}/...`）
+- 在每个请求后附加 `?api-version=...`

-其他 base URL（公共 OpenAI、OpenAI 兼容代理）则继续使用标准的
+其他 base URL（公开 OpenAI、OpenAI 兼容代理）将继续使用标准
 OpenAI 图像请求格式。

 <Note>
-`openai` 提供商图像生成路径的 Azure 路由功能需要
+`openai` 提供商图像生成路径的 Azure 路由需要
 OpenClaw 2026.4.22 或更高版本。更早的版本会将任何自定义
-`openai.baseUrl` 都视为公共 OpenAI endpoint，并在对接 Azure
-图像部署时失败。
+`openai.baseUrl` 都视为公开 OpenAI 端点，因此在针对 Azure
+图像 deployment 时会失败。
 </Note>

 ### API 版本

-设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的
-Azure 预览版或正式版版本：
+设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：

 ```bash
 export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
 ```

-如果未设置该变量，默认值为 `2024-12-01-preview`。
+当该变量未设置时，默认值为 `2024-12-01-preview`。

-### 模型名称就是部署名称
+### 模型名称即 deployment 名称

-Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` 提供商路由的
-Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure portal 中配置的
-**Azure 部署名称**，而不是公共 OpenAI 模型 id。
+Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商
+路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段
+必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是
+公开的 OpenAI 模型 id。

-如果你创建了一个名为 `gpt-image-2-prod` 的部署，用于提供 `gpt-image-2`：
+如果你创建了一个名为 `gpt-image-2-prod`、提供 `gpt-image-2` 的 deployment：

 ```
 /tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1
 ```

-同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
+同样的 deployment 名称规则也适用于通过内置 `openai` 提供商
+路由的图像生成调用。

 ### 区域可用性

 Azure 图像生成目前仅在部分区域可用
 （例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
-`uaenorth`）。在创建部署之前，请先查看 Microsoft 当前的区域列表，
-并确认你的区域提供所需的具体模型。
+`uaenorth`）。在创建 deployment 之前，请先查看 Microsoft 的最新区域列表，
+并确认目标模型在你的区域中可用。

 ### 参数差异

-Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。
-Azure 可能会拒绝公共 OpenAI 允许的选项（例如在 `gpt-image-2` 上的某些
-`background` 值），或者仅在特定模型版本上提供这些选项。
-这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请检查 Azure portal 中你的具体部署和 API 版本所支持的参数集。
+Azure OpenAI 和公开 OpenAI 并不总是接受相同的图像参数。
+Azure 可能会拒绝公开 OpenAI 允许的某些选项（例如 `gpt-image-2` 上的某些
+`background` 值），或仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，
+而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在
+Azure 门户中检查你的具体 deployment 和 API 版本所支持的参数集。

 <Note>
 Azure OpenAI 使用原生传输和兼容行为，但不会接收
-OpenClaw 的隐藏 attribution headers——请参见
-[高级配置](#advanced-configuration) 下 **原生与 OpenAI 兼容路径**
-折叠面板。
+OpenClaw 的隐藏归因标头 —— 请参阅 [Advanced configuration](#advanced-configuration) 下
+**Native vs OpenAI-compatible routes** 折叠面板。

-对于 Azure 上的聊天或 Responses 流量（图像生成之外），请使用
-新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl`
-并不会自动采用 Azure 的 API/认证格式。另有一个独立的
-`azure-openai-responses/*` 提供商；请参见下方的
-服务端压缩折叠面板。
+对于 Azure 上的聊天或 Responses 流量（不仅限于图像生成），请使用
+新手引导流程或专用的 Azure 提供商配置 —— 单独设置 `openai.baseUrl`
+不会自动采用 Azure 的 API / 认证格式。另有单独的
+`azure-openai-responses/*` 提供商；请参阅下方的
+Server-side compaction 折叠面板。
 </Note>

 ## 高级配置

 <AccordionGroup>
  <Accordion title="传输（WebSocket 与 SSE）">
-    OpenClaw 对 `openai/*` 和 `openai-codex/*` 都默认使用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。
+    对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都会优先使用 WebSocket，并在失败时回退到 SSE（`"auto"`）。

    在 `"auto"` 模式下，OpenClaw 会：
    - 在回退到 SSE 之前，重试一次早期 WebSocket 失败
-    - 在发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
-    - 为重试和重连附加稳定的会话和轮次身份 header
-    - 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
+    - 失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE
+    - 为重试和重连附加稳定的会话和轮次身份标头
+    - 在不同传输变体之间统一使用量计数器（`input_tokens` / `prompt_tokens`）

    | 值 | 行为 |
    |-------|----------|
-    | `"auto"`（默认） | WebSocket 优先，SSE 回退 |
-    | `"sse"` | 强制仅使用 SSE |
-    | `"websocket"` | 强制仅使用 WebSocket |
+    | `"auto"`（默认） | 优先使用 WebSocket，失败时回退到 SSE |
+    | `"sse"` | 仅强制使用 SSE |
+    | `"websocket"` | 仅强制使用 WebSocket |

    ```json5
    {
@ -589,13 +612,13 @@ OpenClaw 的隐藏 attribution headers——请参见
    ```

    相关 OpenAI 文档：
-    - [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
-    - [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
+    - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
+    - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)

  </Accordion>

  <Accordion title="WebSocket 预热">
-    OpenClaw 默认对 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首轮延迟。
+    OpenClaw 默认会为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首轮延迟。

    ```json5
    // 禁用预热
@ -617,10 +640,10 @@ OpenClaw 的隐藏 attribution headers——请参见
  <Accordion title="Fast 模式">
    OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的 Fast 模式开关：

-    - **聊天/UI：** `/fast status|on|off`
+    - **聊天 / UI：** `/fast status|on|off`
    - **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`

-    启用后，OpenClaw 会将 Fast 模式映射为 OpenAI 优先级处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，Fast 模式不会重写 `reasoning` 或 `text.verbosity`。
+    启用后，OpenClaw 会将 Fast 模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，Fast 模式不会重写 `reasoning` 或 `text.verbosity`。

    ```json5
    {
@ -635,13 +658,13 @@ OpenClaw 的隐藏 attribution headers——请参见
    ```

    <Note>
-    会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖后，会话会恢复为配置中的默认值。
+    会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置中的默认值。
    </Note>

  </Accordion>

-  <Accordion title="优先级处理（service_tier）">
-    OpenAI 的 API 通过 `service_tier` 提供优先级处理能力。你可以在 OpenClaw 中按模型进行设置：
+  <Accordion title="优先处理（service_tier）">
+    OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置：

    ```json5
    {
@ -658,23 +681,23 @@ OpenClaw 的隐藏 attribution headers——请参见
    支持的值：`auto`、`default`、`flex`、`priority`。

    <Warning>
-    `serviceTier` 仅会被转发到原生 OpenAI endpoint（`api.openai.com`）和原生 Codex endpoint（`chatgpt.com/backend-api`）。如果你通过代理路由其中任一提供商，OpenClaw 会保持 `service_tier` 不变。
+    `serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
    </Warning>

  </Accordion>

  <Accordion title="服务端压缩（Responses API）">
-    对于直接的 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩：
+    对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩：

    - 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
    - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
-    - 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用则为 `80000`）
+    - 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用，则为 `80000`）

-    这适用于内置的 Pi harness 路径，也适用于嵌入式运行所使用的 OpenAI 提供商 hook。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。
+    这会应用于内置 Pi harness 路径，以及嵌入式运行所使用的 OpenAI provider hooks。原生 Codex app-server harness 通过 Codex 管理自己的上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。

    <Tabs>
      <Tab title="显式启用">
-        适用于 Azure OpenAI Responses 这类兼容 endpoint：
+        对 Azure OpenAI Responses 这样的兼容端点很有用：

        ```json5
        {
@ -726,13 +749,13 @@ OpenClaw 的隐藏 attribution headers——请参见
    </Tabs>

    <Note>
-    `responsesServerCompaction` 仅控制 `context_management` 的注入。直接的 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。
+    `responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。
    </Note>

  </Accordion>

-  <Accordion title="严格智能体式 GPT 模式">
-    对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行约定：
+  <Accordion title="严格 agent 式 GPT 模式">
+    对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：

    ```json5
    {
@ -745,10 +768,10 @@ OpenClaw 的隐藏 attribution headers——请参见
    ```

    使用 `strict-agentic` 时，OpenClaw 会：
-    - 当有可用工具操作时，不再将“仅规划”的轮次视为成功进展
-    - 通过立即执行引导来重试该轮次
-    - 对于实质性工作，自动启用 `update_plan`
-    - 如果模型持续只规划而不执行，则明确显示阻塞状态
+    - 当工具操作可用时，不再将仅计划的轮次视为成功进展
+    - 使用“立即行动”的引导重试该轮次
+    - 对于重要工作自动启用 `update_plan`
+    - 如果模型持续只做计划而不行动，则显式显示阻塞状态

    <Note>
    仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧模型系列保持默认行为。
@ -756,21 +779,21 @@ OpenClaw 的隐藏 attribution headers——请参见

  </Accordion>

-  <Accordion title="原生与 OpenAI 兼容路径">
-    OpenClaw 会将直接 OpenAI、Codex 和 Azure OpenAI endpoint 与通用的 OpenAI 兼容 `/v1` 代理区分对待：
+  <Accordion title="原生路由与 OpenAI 兼容路由">
+    OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理方式，与通用 OpenAI 兼容 `/v1` 代理不同：

-    **原生路径**（`openai/*`、Azure OpenAI）：
+    **原生路由**（`openai/*`、Azure OpenAI）：
    - 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
-    - 对于拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用的 reasoning
+    - 对拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用的 reasoning
    - 默认将工具 schema 设为严格模式
-    - 仅在已验证的原生主机上附加隐藏 attribution headers
-    - 保留 OpenAI 专有的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
+    - 仅在已验证的原生主机上附加隐藏归因标头
+    - 保留 OpenAI 专属请求整形（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示）

-    **代理/兼容路径：**
+    **代理 / 兼容路由：**
    - 使用更宽松的兼容行为
-    - 不强制严格工具 schema，也不附加仅限原生的 headers
+    - 不会强制严格工具 schema 或原生专属标头

-    Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏的 attribution headers。
+    Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因标头。

  </Accordion>
 </AccordionGroup>
@ -779,13 +802,13 @@ OpenClaw 的隐藏 attribution headers——请参见

 <CardGroup cols={2}>
  <Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
-    选择提供商、模型引用和故障切换行为。
+    选择提供商、模型引用和故障转移行为。
  </Card>
  <Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
-    共享的图像工具参数和提供商选择。
+    共享图像工具参数和提供商选择。
  </Card>
  <Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
-    共享的视频工具参数和提供商选择。
+    共享视频工具参数和提供商选择。
  </Card>
  <Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
    认证细节和凭证复用规则。
--- a/docs/zh-CN/tools/image-generation.md
+++ b/docs/zh-CN/tools/image-generation.md
@ -2,27 +2,27 @@
 read_when:
    - 通过智能体生成图像
    - 配置图像生成提供商和模型
-    - 理解 `image_generate` 工具参数
-summary: 使用已配置的提供商生成和编辑图像（OpenAI、OpenAI Codex OAuth、Google Gemini、OpenRouter、fal、MiniMax、ComfyUI、Vydra、xAI）
+    - 了解 `image_generate` 工具参数
+summary: 使用已配置的提供商（OpenAI、OpenAI Codex OAuth、Google Gemini、OpenRouter、fal、MiniMax、ComfyUI、Vydra、xAI）生成和编辑图像
 title: 图像生成
 x-i18n:
-    generated_at: "2026-04-24T03:44:00Z"
+    generated_at: "2026-04-24T16:58:28Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 51ffc32165c5e25925460f95f3a6e674a004e6640b7a4b9e88d025eb40943b4b
+    source_hash: 3a8e721918f5d610163894f33fbfd39ade6694be8bf4ad47c7c691d780d49637
    source_path: tools/image-generation.md
    workflow: 15
 ---

-`image_generate` 工具允许智能体使用你已配置的提供商来创建和编辑图像。生成的图像会作为媒体附件自动随智能体回复一起发送。
+`image_generate` 工具允许智能体使用你已配置的提供商创建和编辑图像。生成的图像会作为媒体附件自动包含在智能体的回复中。

 <Note>
-只有在至少有一个图像生成提供商可用时，这个工具才会出现。如果你在智能体工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API key，或使用 OpenAI Codex OAuth 登录。
+只有在至少有一个图像生成提供商可用时，该工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API 密钥，或使用 OpenAI Codex OAuth 登录。
 </Note>

 ## 快速开始

-1. 为至少一个提供商设置 API key（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY` 或 `OPENROUTER_API_KEY`），或使用 OpenAI Codex OAuth 登录。
+1. 为至少一个提供商设置 API 密钥（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY` 或 `OPENROUTER_API_KEY`），或使用 OpenAI Codex OAuth 登录。
 2. 可选：设置你偏好的模型：

 ```json5
@ -38,21 +38,33 @@ x-i18n:
 ```

 Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了
-`openai-codex` OAuth profile 时，OpenClaw 会通过该 OAuth profile 路由图像请求，
-而不是优先尝试 `OPENAI_API_KEY`。显式的自定义 `models.providers.openai`
-图像配置，例如 API key 或自定义/Azure `baseUrl`，会重新切回直接使用 OpenAI Images API 的路径。
-对于 LocalAI 这类 OpenAI 兼容的 LAN 端点，请保留自定义
+`openai-codex` OAuth 配置文件时，OpenClaw 会通过该相同的 OAuth 配置文件路由图像请求，而不是先尝试 `OPENAI_API_KEY`。
+显式自定义 `models.providers.openai` 图像配置（例如 API 密钥或
+自定义 / Azure 基础 URL）会切换回直接 OpenAI Images API 路由。
+对于 LocalAI 之类兼容 OpenAI 的 LAN 端点，请保留自定义
 `models.providers.openai.baseUrl`，并显式启用
-`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；默认情况下，私有/内部
-图像端点仍然会被阻止。
+`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；默认情况下，私有 / 内部图像端点仍会被阻止。

-3. 向智能体提出请求：_“生成一张友好的机器人吉祥物图片。”_
+3. 向智能体提问：_“生成一张友好机器人吉祥物的图片。”_

-智能体会自动调用 `image_generate`。不需要工具允许列表——只要有可用提供商，它默认就是启用的。
+智能体会自动调用 `image_generate`。不需要工具允许列表——当提供商可用时，它默认启用。
+
+## 常见路由
+
+| 目标 | 模型引用 | 认证 |
+| ---------------------------------------------------- | -------------------------------------------------- | ------------------------------------ |
+| 使用 API 计费的 OpenAI 图像生成 | `openai/gpt-image-2` | `OPENAI_API_KEY` |
+| 使用 Codex 订阅认证的 OpenAI 图像生成 | `openai/gpt-image-2` | OpenAI Codex OAuth |
+| OpenRouter 图像生成 | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` |
+| Google Gemini 图像生成 | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
+
+同一个 `image_generate` 工具同时处理文生图和参考图像编辑。
+对单张参考图像使用 `image`，对多张参考图像使用 `images`。
+如 `quality`、`outputFormat` 以及 OpenAI 专属的 `background` 之类由提供商支持的输出提示，会在可用时透传；当提供商不支持时，会在结果中报告为已忽略。

 ## 支持的提供商

-| 提供商 | 默认模型 | 编辑支持 | 凭证 |
+| 提供商 | 默认模型 | 编辑支持 | 认证 |
 | ---------- | --------------------------------------- | ---------------------------------- | ----------------------------------------------------- |
 | OpenAI | `gpt-image-2` | 是（最多 4 张图像） | `OPENAI_API_KEY` 或 OpenAI Codex OAuth |
 | OpenRouter | `google/gemini-3.1-flash-image-preview` | 是（最多 5 张输入图像） | `OPENROUTER_API_KEY` |
@ -63,24 +75,24 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了
 | Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` |
 | xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` |

-使用 `action: "list"` 可在运行时检查可用提供商和模型：
+使用 `action: "list"` 可在运行时检查可用的提供商和模型：

-```text
+```
 /tool image_generate action=list
 ```

 ## 工具参数

 <ParamField path="prompt" type="string" required>
-图像生成提示。`action: "generate"` 时必填。
+图像生成提示词。对于 `action: "generate"` 为必填。
 </ParamField>

 <ParamField path="action" type="'generate' | 'list'" default="generate">
-使用 `"list"` 在运行时检查可用提供商和模型。
+使用 `"list"` 在运行时检查可用的提供商和模型。
 </ParamField>

 <ParamField path="model" type="string">
-提供商/模型覆盖，例如 `openai/gpt-image-2`。
+提供商 / 模型覆盖，例如 `openai/gpt-image-2`。
 </ParamField>

 <ParamField path="image" type="string">
@ -104,11 +116,11 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了
 </ParamField>

 <ParamField path="quality" type="'low' | 'medium' | 'high' | 'auto'">
-当提供商支持时使用的质量提示。
+当提供商支持时的质量提示。
 </ParamField>

 <ParamField path="outputFormat" type="'png' | 'jpeg' | 'webp'">
-当提供商支持时使用的输出格式提示。
+当提供商支持时的输出格式提示。
 </ParamField>

 <ParamField path="count" type="number">
@ -116,7 +128,7 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了
 </ParamField>

 <ParamField path="timeoutMs" type="number">
-可选的提供商请求超时，单位为毫秒。
+可选的提供商请求超时时间（毫秒）。
 </ParamField>

 <ParamField path="filename" type="string">
@ -124,12 +136,12 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了
 </ParamField>

 <ParamField path="openai" type="object">
-仅限 OpenAI 的提示：`background`、`moderation`、`outputCompression` 和 `user`。
+仅适用于 OpenAI 的提示：`background`、`moderation`、`outputCompression` 和 `user`。
 </ParamField>

-并非所有提供商都支持所有参数。当某个回退提供商支持接近的几何选项而非精确请求值时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。像 `quality` 或 `outputFormat` 这样不受支持的输出提示，对于未声明支持的提供商会被丢弃，并在工具结果中报告。
+并非所有提供商都支持所有参数。当回退提供商支持接近的几何选项而非精确请求值时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。对于未声明支持的提供商，不受支持的输出提示（如 `quality` 或 `outputFormat`）会被丢弃，并在工具结果中报告。

-工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值反映的是实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
+工具结果会报告已应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。

 ## 配置

@ -159,26 +171,25 @@ Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了
 1. 工具调用中的 **`model` 参数**（如果智能体指定了）
 2. 配置中的 **`imageGenerationModel.primary`**
 3. 按顺序使用 **`imageGenerationModel.fallbacks`**
-4. **自动检测**——仅使用有凭证支持的提供商默认值：
-   - 先尝试当前默认提供商
-   - 再按提供商 id 顺序尝试其余已注册的图像生成提供商
+4. **自动检测**——仅使用有认证支持的提供商默认值：
+   - 先使用当前默认提供商
+   - 再按提供商 ID 顺序使用其余已注册的图像生成提供商

-如果某个提供商失败（凭证错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
+如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。

-说明：
+注意：

- 自动检测具备凭证感知能力。只有当 OpenClaw 实际能够为某个提供商完成认证时，该提供商默认值才会进入候选列表。
- 默认启用自动检测。如果你希望图像生成仅使用显式的 `model`、`primary` 和 `fallbacks`
+- 自动检测具备认证感知能力。只有当 OpenClaw 实际能够对某个提供商进行认证时，该提供商默认值才会进入候选列表。
+- 默认启用自动检测。如果你希望图像生成只使用显式的 `model`、`primary` 和 `fallbacks`
  条目，请设置
  `agents.defaults.mediaGenerationAutoProviderFallback: false`。
- 使用 `action: "list"` 可检查当前已注册的提供商、它们的
-  默认模型以及凭证环境变量提示。
+- 使用 `action: "list"` 可检查当前已注册的提供商、它们的默认模型以及认证环境变量提示。

 ### 图像编辑

 OpenAI、OpenRouter、Google、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传入参考图像路径或 URL：

-```text
+```
 "Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
 ```

@ -186,7 +197,7 @@ OpenAI、OpenRouter、Google 和 xAI 通过 `images` 参数最多支持 5 张参

 ### OpenRouter 图像模型

-OpenRouter 图像生成使用相同的 `OPENROUTER_API_KEY`，并通过 OpenRouter 的聊天补全图像 API 路由。使用 `openrouter/` 前缀选择 OpenRouter 图像模型：
+OpenRouter 图像生成使用同一个 `OPENROUTER_API_KEY`，并通过 OpenRouter 的 chat completions 图像 API 路由。使用 `openrouter/` 前缀选择 OpenRouter 图像模型：

 ```json5
 {
@ -200,27 +211,24 @@ OpenRouter 图像生成使用相同的 `OPENROUTER_API_KEY`，并通过 OpenRout
 }
 ```

-OpenClaw 会将 `prompt`、`count`、参考图像以及与 Gemini 兼容的 `aspectRatio` / `resolution` 提示转发给 OpenRouter。当前内置的 OpenRouter 图像模型快捷项包括 `google/gemini-3.1-flash-image-preview`、`google/gemini-3-pro-image-preview` 和 `openai/gpt-5.4-image-2`；使用 `action: "list"` 查看你已配置插件暴露了哪些内容。
+OpenClaw 会将 `prompt`、`count`、参考图像以及与 Gemini 兼容的 `aspectRatio` / `resolution` 提示转发到 OpenRouter。当前内置的 OpenRouter 图像模型快捷项包括 `google/gemini-3.1-flash-image-preview`、`google/gemini-3-pro-image-preview` 和 `openai/gpt-5.4-image-2`；使用 `action: "list"` 可查看你配置的插件公开了哪些模型。

 ### OpenAI `gpt-image-2`

-OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果配置了
-`openai-codex` OAuth profile，OpenClaw 会复用与 Codex 订阅聊天模型相同的 OAuth
-profile，并通过 Codex Responses 后端发送图像请求；它不会在该请求中静默回退到
-`OPENAI_API_KEY`。如果你想强制使用直接的 OpenAI Images API 路由，
-请显式配置 `models.providers.openai`，并提供 API key、自定义 `baseUrl`
-或 Azure 端点。旧版
-`openai/gpt-image-1` 模型仍然可以显式选择，但新的 OpenAI
+OpenAI 图像生成默认使用 `openai/gpt-image-2`。如果已配置
+`openai-codex` OAuth 配置文件，OpenClaw 会复用 Codex 订阅聊天模型所使用的相同 OAuth 配置文件，并通过 Codex Responses 后端发送图像请求；
+它不会在该请求中静默回退到 `OPENAI_API_KEY`。若要强制使用直接 OpenAI Images API 路由，
+请显式配置 `models.providers.openai`，例如设置 API 密钥、自定义基础 URL
+或 Azure 端点。较旧的
+`openai/gpt-image-1` 模型仍可显式选择，但新的 OpenAI
 图像生成和图像编辑请求应使用 `gpt-image-2`。

-`gpt-image-2` 同时支持文生图生成和通过同一个 `image_generate` 工具进行参考图像
-编辑。OpenClaw 会将 `prompt`、
-`count`、`size`、`quality`、`outputFormat` 和参考图像转发给 OpenAI。
-OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下，
-OpenClaw 会将它们映射到受支持的 `size`，否则工具会将其报告为
-被忽略的覆盖项。
+`gpt-image-2` 通过同一个 `image_generate` 工具同时支持文生图和参考图像编辑。OpenClaw 会将 `prompt`、
+`count`、`size`、`quality`、`outputFormat` 以及参考图像转发给 OpenAI。
+OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；如果可能，
+OpenClaw 会将它们映射为受支持的 `size`，否则工具会将其报告为已忽略的覆盖项。

-OpenAI 特定选项位于 `openai` 对象下：
+OpenAI 专属选项位于 `openai` 对象下：

 ```json
 {
@ -237,67 +245,68 @@ OpenAI 特定选项位于 `openai` 对象下：

 `openai.background` 接受 `transparent`、`opaque` 或 `auto`；透明
 输出要求 `outputFormat` 为 `png` 或 `webp`。`openai.outputCompression`
-适用于 JPEG/WebP 输出。
+适用于 JPEG / WebP 输出。

 生成一张 4K 横向图像：

-```text
+```
 /tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
 ```

 生成两张方形图像：

-```text
+```
 /tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
 ```

 编辑一张本地参考图像：

-```text
+```
 /tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
 ```

 使用多张参考图像进行编辑：

-```text
+```
 /tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
 ```

-如果要通过 Azure OpenAI 部署而不是
-`api.openai.com` 路由 OpenAI 图像生成，请参见 OpenAI 提供商文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。
+若要通过 Azure OpenAI 部署而不是
+`api.openai.com` 路由 OpenAI 图像生成，请参阅 OpenAI 提供商文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。

-MiniMax 图像生成可通过两种内置 MiniMax 凭证路径使用：
+MiniMax 图像生成可通过两种内置 MiniMax 认证路径使用：

- `minimax/image-01` 用于 API key 设置
- `minimax-portal/image-01` 用于 OAuth 设置
+- 用于 API 密钥配置的 `minimax/image-01`
+- 用于 OAuth 配置的 `minimax-portal/image-01`

 ## 提供商能力

 | 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
 | --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
-| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（由工作流定义输出） | 是（1 张） | 是（最多 4 张） |
-| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） |
+| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（工作流定义的输出） | 是（1 张） | 是（最多 4 张） |
+| 编辑 / 参考图像 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） |
 | 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 |
 | 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 |
 | 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K/2K） |

 ### xAI `grok-imagine-image`

-内置的 xAI 提供商会对仅提示词请求使用 `/v1/images/generations`，
-当存在 `image` 或 `images` 时则使用 `/v1/images/edits`。
+内置 xAI 提供商对仅提示词请求使用 `/v1/images/generations`，
+当存在 `image` 或 `images` 时使用 `/v1/images/edits`。

 - 模型：`xai/grok-imagine-image`、`xai/grok-imagine-image-pro`
 - 数量：最多 4 张
- 参考：一个 `image` 或最多五个 `images`
+- 参考图像：一个 `image` 或最多五个 `images`
 - 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2`
 - 分辨率：`1K`、`2K`
- 输出：作为由 OpenClaw 管理的图像附件返回
+- 输出：作为 OpenClaw 管理的图像附件返回

-在这些控制项尚未进入共享的跨提供商 `image_generate` 合同之前，OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user`，或额外的仅原生支持宽高比。
+在这些控制项出现在跨提供商共享的 `image_generate` 合同中之前，
+OpenClaw 有意不公开 xAI 原生的 `quality`、`mask`、`user` 或其他仅原生支持的宽高比。

 ## 相关内容

- [工具概览](/zh-CN/tools) — 所有可用的智能体工具
+- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具
 - [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置
 - [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置
 - [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置
@ -305,5 +314,5 @@ MiniMax 图像生成可通过两种内置 MiniMax 凭证路径使用：
 - [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置
 - [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置
 - [xAI](/zh-CN/providers/xai) — Grok 图像、视频、搜索、代码执行和 TTS 设置
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — `imageGenerationModel` 配置
- [模型](/zh-CN/concepts/models) — 模型配置与故障转移
+- [Configuration Reference](/zh-CN/gateway/config-agents#agent-defaults) — `imageGenerationModel` 配置
+- [Models](/zh-CN/concepts/models) — 模型配置和故障切换
--- a/docs/zh-CN/tools/plugin.md
+++ b/docs/zh-CN/tools/plugin.md
@ -7,20 +7,20 @@ sidebarTitle: Install and Configure
 summary: 安装、配置和管理 OpenClaw 插件
 title: 插件
 x-i18n:
-    generated_at: "2026-04-24T16:35:16Z"
+    generated_at: "2026-04-24T16:58:32Z"
    model: gpt-5.4
    provider: openai
-    source_hash: d7db42c0c8d7d8b3bddda46a8a42fc19b39b093863b1730b8ca66528a95ecb50
+    source_hash: 1f4968e70dc215dc50916f2d180121ce2afbe90e6bb2a85d3fe0bd8d989244fd
    source_path: tools/plugin.md
    workflow: 15
 ---

-插件通过新增能力来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、技能、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等等。有些插件是 **core**（随 OpenClaw 一起提供），另一些是 **external**（由社区发布到 npm）。
+插件通过新增功能来扩展 OpenClaw：渠道、模型提供商、智能体 harness、工具、Skills、语音、实时转写、实时语音、媒体理解、图像生成、视频生成、网页抓取、网页搜索等。有些插件是**核心**插件（随 OpenClaw 一起发布），另一些则是**外部**插件（由社区发布到 npm）。

 ## 快速开始

 <Steps>
-  <Step title="查看已加载的内容">
+  <Step title="查看已加载内容">
    ```bash
    openclaw plugins list
    ```
@ -28,10 +28,10 @@ x-i18n:

  <Step title="安装插件">
    ```bash
-    # 从 npm
+    # 来自 npm
    openclaw plugins install @openclaw/voice-call

-    # 从本地目录或归档文件
+    # 来自本地目录或归档文件
    openclaw plugins install ./my-plugin
    openclaw plugins install ./my-plugin.tgz
    ```
@ -48,7 +48,7 @@ x-i18n:
  </Step>
 </Steps>

-如果你更喜欢聊天原生控制，请启用 `commands.plugins: true` 并使用：
+如果你更喜欢聊天原生的控制方式，请启用 `commands.plugins: true` 并使用：

 ```text
 /plugin install clawhub:@openclaw/voice-call
@ -56,11 +56,11 @@ x-i18n:
 /plugin enable voice-call
 ```

-安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:<pkg>`，或裸包说明符（优先 ClawHub，然后回退到 npm）。
+安装路径使用与 CLI 相同的解析器：本地路径/归档文件、显式 `clawhub:<pkg>`，或裸包规范（优先 ClawHub，其次回退到 npm）。

-如果配置无效，安装通常会以关闭失败的方式结束，并提示你运行 `openclaw doctor --fix`。唯一的恢复例外是一个范围很窄的内置插件重装路径，适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。
+如果配置无效，安装通常会以安全失败的方式终止，并提示你使用 `openclaw doctor --fix`。唯一的恢复例外是一个较窄的内置插件重装路径，适用于选择加入 `openclaw.install.allowInvalidConfigRecovery` 的插件。

-打包的 OpenClaw 安装不会急切安装每个内置插件的运行时依赖树。当一个由 OpenClaw 拥有的内置插件通过插件配置、旧版渠道配置或默认启用的清单处于活动状态时，启动流程只会在导入该插件之前修复该插件声明的运行时依赖。外部插件和自定义加载路径仍然必须通过 `openclaw plugins install` 安装。
+打包发布的 OpenClaw 安装不会急切安装每个内置插件的全部运行时依赖树。当某个由 OpenClaw 拥有的内置插件因插件配置、旧版渠道配置或默认启用的清单而处于活动状态时，启动过程只会在导入该插件前修复该插件声明的运行时依赖。显式禁用仍然优先生效：`plugins.entries.<id>.enabled: false`、`plugins.deny`、`plugins.enabled: false` 和 `channels.<id>.enabled: false` 会阻止该插件/渠道的自动内置运行时依赖修复。外部插件和自定义加载路径仍然必须通过 `openclaw plugins install` 安装。

 ## 插件类型

@ -69,9 +69,9 @@ OpenClaw 可识别两种插件格式：
 | 格式 | 工作方式 | 示例 |
 | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
 | **Native** | `openclaw.plugin.json` + 运行时模块；在进程内执行 | 官方插件、社区 npm 包 |
-| **Bundle** | 兼容 Codex/Claude/Cursor 的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |
+| **Bundle** | 与 Codex/Claude/Cursor 兼容的布局；映射到 OpenClaw 功能 | `.codex-plugin/`、`.claude-plugin/`、`.cursor-plugin/` |

-两者都会显示在 `openclaw plugins list` 中。有关 bundle 的详细信息，请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。
+这两种格式都会显示在 `openclaw plugins list` 中。有关 Bundle 的详细信息，请参阅 [Plugin Bundles](/zh-CN/plugins/bundles)。

 如果你正在编写原生插件，请从 [Building Plugins](/zh-CN/plugins/building-plugins) 和 [插件 SDK 概览](/zh-CN/plugins/sdk-overview) 开始。

@ -81,14 +81,14 @@ OpenClaw 可识别两种插件格式：

 | 插件 | 包 | 文档 |
 | --------------- | ---------------------- | ------------------------------------ |
-| Matrix          | `@openclaw/matrix`     | [Matrix](/zh-CN/channels/matrix)           |
-| Microsoft Teams | `@openclaw/msteams`    | [Microsoft Teams](/zh-CN/channels/msteams) |
-| Nostr           | `@openclaw/nostr`      | [Nostr](/zh-CN/channels/nostr)             |
-| Voice Call      | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call)    |
-| Zalo            | `@openclaw/zalo`       | [Zalo](/zh-CN/channels/zalo)               |
-| Zalo Personal   | `@openclaw/zalouser`   | [Zalo Personal](/zh-CN/plugins/zalouser)   |
+| Matrix | `@openclaw/matrix` | [Matrix](/zh-CN/channels/matrix) |
+| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/zh-CN/channels/msteams) |
+| Nostr | `@openclaw/nostr` | [Nostr](/zh-CN/channels/nostr) |
+| Voice Call | `@openclaw/voice-call` | [Voice Call](/zh-CN/plugins/voice-call) |
+| Zalo | `@openclaw/zalo` | [Zalo](/zh-CN/channels/zalo) |
+| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/zh-CN/plugins/zalouser) |

-### Core（随 OpenClaw 一起提供）
+### 核心（随 OpenClaw 一起发布）

 <AccordionGroup>
  <Accordion title="模型提供商（默认启用）">
@ -100,8 +100,8 @@ OpenClaw 可识别两种插件格式：
  </Accordion>

  <Accordion title="Memory 插件">
-    - `memory-core` — 内置 memory 搜索（默认通过 `plugins.slots.memory`）
-    - `memory-lancedb` — 按需安装的长期 memory，带自动召回/捕获（设置 `plugins.slots.memory = "memory-lancedb"`）
+    - `memory-core` — 内置的内存搜索（通过 `plugins.slots.memory` 默认启用）
+    - `memory-lancedb` — 按需安装的长期记忆，带自动回忆/捕获功能（设置 `plugins.slots.memory = "memory-lancedb"`）
  </Accordion>

  <Accordion title="语音提供商（默认启用）">
@ -109,8 +109,8 @@ OpenClaw 可识别两种插件格式：
  </Accordion>

  <Accordion title="其他">
-    - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时和默认浏览器控制服务的内置浏览器插件（默认启用；替换它之前请先禁用）
-    - `copilot-proxy` — VS Code Copilot Proxy bridge（默认禁用）
+    - `browser` — 用于浏览器工具、`openclaw browser` CLI、`browser.request` Gateway 网关方法、浏览器运行时以及默认浏览器控制服务的内置浏览器插件（默认启用；替换前请先禁用）
+    - `copilot-proxy` — VS Code Copilot Proxy 桥接器（默认禁用）
  </Accordion>
 </AccordionGroup>

@ -132,26 +132,26 @@ OpenClaw 可识别两种插件格式：
 }
 ```

-| 字段 | 描述 |
+| 字段 | 说明 |
 | ---------------- | --------------------------------------------------------- |
-| `enabled`        | 主开关（默认：`true`） |
-| `allow`          | 插件允许列表（可选） |
-| `deny`           | 插件拒绝列表（可选；拒绝优先） |
-| `load.paths`     | 额外的插件文件/目录 |
-| `slots`          | 独占插槽选择器（例如 `memory`、`contextEngine`） |
+| `enabled` | 主开关（默认：`true`） |
+| `allow` | 插件允许列表（可选） |
+| `deny` | 插件拒绝列表（可选；拒绝优先） |
+| `load.paths` | 额外的插件文件/目录 |
+| `slots` | 独占槽位选择器（例如 `memory`、`contextEngine`） |
 | `entries.\<id\>` | 每个插件的开关 + 配置 |

-配置更改 **需要重启 Gateway 网关**。如果 Gateway 网关在启用了配置监视和进程内重启的情况下运行（默认的 `openclaw gateway` 路径），通常会在配置写入后稍等片刻自动执行该重启。对于原生插件运行时代码或生命周期 hook，不存在受支持的热重载路径；在期待更新后的 `register(api)` 代码、`api.on(...)` hook、工具、服务或提供商/运行时 hook 生效之前，请重启正在服务实时渠道的 Gateway 网关进程。
+配置更改**需要重启 Gateway 网关**。如果 Gateway 网关正在以启用配置监视和进程内重启的方式运行（默认的 `openclaw gateway` 路径），那么在配置写入后不久，这个重启通常会自动执行。对于原生插件运行时代码或生命周期钩子，不存在受支持的热重载路径；在期望更新后的 `register(api)` 代码、`api.on(...)` 钩子、工具、服务或提供商/运行时钩子生效之前，请重启正在服务实时渠道的 Gateway 网关进程。

-`openclaw plugins list` 是本地 CLI/配置快照。其中显示为 `loaded` 的插件，表示该插件可从该次 CLI 调用所见的配置/文件中被发现并加载。这并不能证明一个已经运行的远程 Gateway 网关子进程已经重启并加载了同样的插件代码。在 VPS/容器部署中，如果使用了包装进程，请向实际的 `openclaw gateway run` 进程发送重启信号，或者对正在运行的 Gateway 网关使用 `openclaw gateway restart`。
+`openclaw plugins list` 是本地 CLI/配置快照。其中某个插件显示为 `loaded`，表示从该次 CLI 调用所看到的配置/文件来看，这个插件可被发现且可被加载。这并不能证明一个已经运行中的远程 Gateway 网关子进程已重启并载入同一份插件代码。在 VPS/容器部署中，如果存在包装进程，请将重启信号发送给实际的 `openclaw gateway run` 进程，或对正在运行的 Gateway 网关使用 `openclaw gateway restart`。

-<Accordion title="插件状态：已禁用 vs 缺失 vs 无效">
-  - **已禁用**：插件存在，但启用规则将其关闭。配置会被保留。
-  - **缺失**：配置引用了一个插件 id，但发现流程没有找到它。
-  - **无效**：插件存在，但其配置与声明的 schema 不匹配。
+<Accordion title="插件状态：disabled、missing 与 invalid">
+  - **Disabled**：插件存在，但被启用规则关闭。配置会被保留。
+  - **Missing**：配置引用了某个插件 id，但设备发现未找到该插件。
+  - **Invalid**：插件存在，但其配置与声明的 schema 不匹配。
 </Accordion>

-## 发现顺序和优先级
+## 设备发现和优先级

 OpenClaw 按以下顺序扫描插件（先匹配者优先）：

@ -169,44 +169,37 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
  </Step>

  <Step title="内置插件">
-    随 OpenClaw 一起提供。许多默认启用（模型提供商、语音）。
-    其他则需要显式启用。
+    随 OpenClaw 一起发布。许多插件默认启用（模型提供商、语音）。
+    其他插件则需要显式启用。
  </Step>
 </Steps>

 ### 启用规则

 - `plugins.enabled: false` 会禁用所有插件
- `plugins.deny` 总是优先于 allow
+- `plugins.deny` 始终优先于 allow
 - `plugins.entries.\<id\>.enabled: false` 会禁用该插件
- 来自工作区的插件 **默认禁用**（必须显式启用）
+- 来自工作区的插件**默认禁用**（必须显式启用）
 - 内置插件遵循内建的默认启用集合，除非被覆盖
- 独占插槽可以强制启用为该插槽选定的插件
- 某些选择加入的内置插件会在配置命名了某个插件拥有的表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时
+- 独占槽位可以为该槽位强制启用所选插件
+- 某些内置的选择加入型插件会在配置命名了某个由插件拥有的表面时自动启用，例如提供商模型引用、渠道配置或 harness 运行时
 - OpenAI 系列的 Codex 路由保持独立的插件边界：
  `openai-codex/*` 属于 OpenAI 插件，而内置的 Codex
  app-server 插件则通过 `embeddedHarness.runtime: "codex"` 或旧版
  `codex/*` 模型引用来选择

-## 运行时 hook 故障排除
+## 运行时钩子故障排除

-如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或 hook 没有在实时聊天流量中运行，请先检查以下内容：
+如果某个插件出现在 `plugins list` 中，但 `register(api)` 副作用或钩子没有在实时聊天流量中运行，请先检查以下内容：

- 运行 `openclaw gateway status --deep --require-rpc`，并确认活动的
-  Gateway 网关 URL、profile、配置路径和进程就是你正在编辑的那些。
- 在插件安装/配置/代码更改后，重启正在运行的 Gateway 网关。在包装容器中，
-  PID 1 可能只是一个 supervisor；请重启或向子进程
-  `openclaw gateway run` 发送信号。
- 使用 `openclaw plugins inspect <id> --json` 确认 hook 注册和
-  诊断信息。像 `llm_input`、
-  `llm_output` 和 `agent_end` 这样的非内置会话 hook，需要
+- 运行 `openclaw gateway status --deep --require-rpc`，并确认当前活动的 Gateway 网关 URL、profile、配置路径和进程，就是你正在编辑的那些。
+- 在插件安装/配置/代码变更后重启实时 Gateway 网关。在包装容器中，PID 1 可能只是一个 supervisor；请重启或向子进程 `openclaw gateway run` 发送信号。
+- 使用 `openclaw plugins inspect <id> --json` 确认钩子注册和诊断信息。像 `llm_input`、`llm_output` 和 `agent_end` 这类非内置的会话钩子，需要
  `plugins.entries.<id>.hooks.allowConversationAccess=true`。
- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 只会在一次模型尝试生成 assistant 输出之后运行。
- 如需证明实际生效的会话模型，请使用 `openclaw sessions` 或
-  Gateway 网关的会话/状态表面；调试提供商 payload 时，请使用
-  `--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。
+- 对于模型切换，优先使用 `before_model_resolve`。它会在智能体轮次的模型解析之前运行；`llm_output` 仅会在某次模型尝试产生 assistant 输出之后运行。
+- 若要证明会话实际使用的模型，请使用 `openclaw sessions` 或 Gateway 网关的会话/状态表面；在调试提供商负载时，请使用 `--raw-stream --raw-stream-path <path>` 启动 Gateway 网关。

-## 插件 slots（独占类别）
+## 插件槽位（独占类别）

 某些类别是独占的（一次只能激活一个）：

@ -214,39 +207,39 @@ OpenClaw 按以下顺序扫描插件（先匹配者优先）：
 {
  plugins: {
    slots: {
-      memory: "memory-core", // 或使用 "none" 来禁用
-      contextEngine: "legacy", // 或一个插件 id
+      memory: "memory-core", // 或 "none" 以禁用
+      contextEngine: "legacy", // 或某个插件 id
    },
  },
 }
 ```

-| 插槽 | 控制内容 | 默认值 |
+| 槽位 | 控制内容 | 默认值 |
 | --------------- | --------------------- | ------------------- |
-| `memory`        | 活动的 memory 插件 | `memory-core`       |
-| `contextEngine` | 活动的上下文引擎 | `legacy`（内建） |
+| `memory` | 当前活动的 Memory 插件 | `memory-core` |
+| `contextEngine` | 当前活动的上下文引擎 | `legacy`（内建） |

 ## CLI 参考

 ```bash
 openclaw plugins list                       # 精简清单
-openclaw plugins list --enabled            # 仅显示已加载的插件
-openclaw plugins list --verbose            # 每个插件的详细行
-openclaw plugins list --json               # 机器可读的清单
+openclaw plugins list --enabled            # 仅显示已加载插件
+openclaw plugins list --verbose            # 每个插件的详细信息行
+openclaw plugins list --json               # 机器可读清单
 openclaw plugins inspect <id>              # 深度详情
 openclaw plugins inspect <id> --json       # 机器可读格式
-openclaw plugins inspect --all             # 全量表格
+openclaw plugins inspect --all             # 全局表格
 openclaw plugins info <id>                 # inspect 别名
 openclaw plugins doctor                    # 诊断

-openclaw plugins install <package>         # 安装（优先 ClawHub，然后 npm）
+openclaw plugins install <package>         # 安装（优先 ClawHub，其次 npm）
 openclaw plugins install clawhub:<pkg>     # 仅从 ClawHub 安装
 openclaw plugins install <spec> --force    # 覆盖现有安装
 openclaw plugins install <path>            # 从本地路径安装
 openclaw plugins install -l <path>         # 链接（不复制），用于开发
 openclaw plugins install <plugin> --marketplace <source>
 openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
-openclaw plugins install <spec> --pin      # 记录精确解析后的 npm 说明符
+openclaw plugins install <spec> --pin      # 记录精确解析出的 npm spec
 openclaw plugins install <spec> --dangerously-force-unsafe-install
 openclaw plugins update <id-or-npm-spec> # 更新单个插件
 openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
@ -260,31 +253,31 @@ openclaw plugins enable <id>
 openclaw plugins disable <id>
 ```

-内置插件随 OpenClaw 一起提供。许多默认启用（例如内置模型提供商、内置语音提供商，以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable <id>`。
+内置插件随 OpenClaw 一起发布。许多插件默认启用（例如内置模型提供商、内置语音提供商以及内置浏览器插件）。其他内置插件仍然需要执行 `openclaw plugins enable <id>`。

-`--force` 会就地覆盖一个已安装的插件或 hook 包。对于已跟踪 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。该选项不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标。
+`--force` 会就地覆盖现有已安装的插件或 hook pack。对于已跟踪的 npm 插件的常规升级，请使用 `openclaw plugins update <id-or-npm-spec>`。该选项不支持与 `--link` 一起使用，因为后者会复用源路径，而不是复制到受管理的安装目标。

-当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会在启用已安装插件之前，将该插件 id 添加到允许列表中，因此重启后安装内容可以立即被加载。
+当已经设置了 `plugins.allow` 时，`openclaw plugins install` 会在启用插件之前，将已安装的插件 id 添加到该允许列表中，因此重启后安装的插件会立即可加载。

-`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带 dist-tag 或精确版本的 npm 包说明符时，会将包名解析回已跟踪的插件记录，并为后续更新记录新的说明符。传入不带版本的包名时，会将一个精确固定版本的安装切回注册表的默认发布线。如果已安装的 npm 插件已经与解析后的版本以及记录的构件标识一致，OpenClaw 会跳过更新，不会下载、重新安装或重写配置。
+`openclaw plugins update <id-or-npm-spec>` 适用于已跟踪的安装。传入带有 dist-tag 或精确版本的 npm 包 spec 时，会将包名解析回已跟踪的插件记录，并记录新的 spec 以供后续更新使用。传入不带版本的包名时，则会将一个精确固定版本的安装切回注册表的默认发布线。如果已安装的 npm 插件已经与解析出的版本和记录的制品标识匹配，OpenClaw 会跳过更新，不会下载、重装或重写配置。

-`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm 说明符。
+`--pin` 仅适用于 npm。它不支持与 `--marketplace` 一起使用，因为 marketplace 安装会持久化 marketplace 来源元数据，而不是 npm spec。

-`--dangerously-force-unsafe-install` 是一个用于应对内置危险代码扫描器误报的紧急覆盖开关。它允许插件安装和插件更新在内置 `critical` 级别发现之后继续进行，但仍然不会绕过插件 `before_install` 策略阻止或扫描失败阻止。
+`--dangerously-force-unsafe-install` 是一个紧急兜底覆盖项，用于处理内置危险代码扫描器的误报。它允许插件安装和插件更新在遇到内置 `critical` 发现后继续进行，但仍不会绕过插件 `before_install` 策略阻止或扫描失败阻止。

-这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装则改用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。
+这个 CLI 标志仅适用于插件安装/更新流程。由 Gateway 网关支持的 Skills 依赖安装则使用对应的 `dangerouslyForceUnsafeInstall` 请求覆盖项，而 `openclaw skills install` 仍然是独立的 ClawHub Skills 下载/安装流程。

-兼容的 bundle 会参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和由清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。
+兼容的 Bundle 会参与相同的插件 list/inspect/enable/disable 流程。当前运行时支持包括 Bundle Skills、Claude command-skills、Claude `settings.json` 默认值、Claude `.lsp.json` 和清单声明的 `lspServers` 默认值、Cursor command-skills，以及兼容的 Codex hook 目录。

-`openclaw plugins inspect <id>` 还会报告已检测到的 bundle 能力，以及由 bundle 支持的或不支持的 MCP 和 LSP server 条目。
+`openclaw plugins inspect <id>` 还会报告检测到的 Bundle 能力，以及由 Bundle 支持的或不受支持的 MCP 和 LSP 服务器条目。

-Marketplace 来源可以是 `~/.claude/plugins/known_marketplaces.json` 中的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保留在已克隆的 marketplace 仓库内，并且只能使用相对路径来源。
+Marketplace 来源可以是来自 `~/.claude/plugins/known_marketplaces.json` 的 Claude 已知 marketplace 名称、本地 marketplace 根目录或 `marketplace.json` 路径、类似 `owner/repo` 的 GitHub 简写、GitHub 仓库 URL，或 git URL。对于远程 marketplace，插件条目必须保持在克隆的 marketplace 仓库内部，并且只能使用相对路径来源。

 完整详情请参阅 [`openclaw plugins` CLI 参考](/zh-CN/cli/plugins)。

 ## 插件 API 概览

-原生插件会导出一个暴露 `register(api)` 的入口对象。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。
+原生插件会导出一个入口对象，并暴露 `register(api)`。较旧的插件仍可能使用 `activate(api)` 作为旧版别名，但新插件应使用 `register`。

 ```typescript
 export default definePluginEntry({
@ -304,48 +297,48 @@ export default definePluginEntry({
 });
 ```

-OpenClaw 会在插件激活期间加载该入口对象并调用 `register(api)`。加载器仍会为旧插件回退到 `activate(api)`，但内置插件和新的外部插件都应将 `register` 视为公共契约。
+OpenClaw 会加载该入口对象，并在插件激活期间调用 `register(api)`。对于旧插件，加载器仍会回退到 `activate(api)`，但内置插件和新的外部插件都应将 `register` 视为公共契约。

 常见注册方法：

 | 方法 | 注册内容 |
 | --------------------------------------- | --------------------------- |
-| `registerProvider`                      | 模型提供商（LLM） |
-| `registerChannel`                       | 聊天渠道 |
-| `registerTool`                          | 智能体工具 |
-| `registerHook` / `on(...)`              | 生命周期 hook |
-| `registerSpeechProvider`                | 文本转语音 / STT |
+| `registerProvider` | 模型提供商（LLM） |
+| `registerChannel` | 聊天渠道 |
+| `registerTool` | 智能体工具 |
+| `registerHook` / `on(...)` | 生命周期钩子 |
+| `registerSpeechProvider` | 文本转语音 / STT |
 | `registerRealtimeTranscriptionProvider` | 流式 STT |
-| `registerRealtimeVoiceProvider`         | 双向实时语音 |
-| `registerMediaUnderstandingProvider`    | 图像/音频分析 |
-| `registerImageGenerationProvider`       | 图像生成 |
-| `registerMusicGenerationProvider`       | 音乐生成 |
-| `registerVideoGenerationProvider`       | 视频生成 |
-| `registerWebFetchProvider`              | 网页抓取 / 爬取提供商 |
-| `registerWebSearchProvider`             | 网页搜索 |
-| `registerHttpRoute`                     | HTTP 端点 |
-| `registerCommand` / `registerCli`       | CLI 命令 |
-| `registerContextEngine`                 | 上下文引擎 |
-| `registerService`                       | 后台服务 |
+| `registerRealtimeVoiceProvider` | 双向实时语音 |
+| `registerMediaUnderstandingProvider` | 图像/音频分析 |
+| `registerImageGenerationProvider` | 图像生成 |
+| `registerMusicGenerationProvider` | 音乐生成 |
+| `registerVideoGenerationProvider` | 视频生成 |
+| `registerWebFetchProvider` | 网页抓取 / 抓取提供商 |
+| `registerWebSearchProvider` | 网页搜索 |
+| `registerHttpRoute` | HTTP 端点 |
+| `registerCommand` / `registerCli` | CLI 命令 |
+| `registerContextEngine` | 上下文引擎 |
+| `registerService` | 后台服务 |

-类型化生命周期 hook 的 hook guard 行为：
+类型化生命周期钩子的守卫行为：

- `before_tool_call`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。
+- `before_tool_call`：`{ block: true }` 为终结结果；会跳过更低优先级的处理程序。
 - `before_tool_call`：`{ block: false }` 为无操作，不会清除更早的阻止。
- `before_install`：`{ block: true }` 为终止性结果；会跳过更低优先级的处理器。
+- `before_install`：`{ block: true }` 为终结结果；会跳过更低优先级的处理程序。
 - `before_install`：`{ block: false }` 为无操作，不会清除更早的阻止。
- `message_sending`：`{ cancel: true }` 为终止性结果；会跳过更低优先级的处理器。
+- `message_sending`：`{ cancel: true }` 为终结结果；会跳过更低优先级的处理程序。
 - `message_sending`：`{ cancel: false }` 为无操作，不会清除更早的取消。

-原生 Codex app-server 会将 bridge 的 Codex 原生工具事件回传到这个 hook 表面。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 审批。该 bridge 目前还不会重写 Codex 原生工具参数。
+原生 Codex app-server 会将桥接的 Codex 原生工具事件回传到这个 hook 表面中。插件可以通过 `before_tool_call` 阻止原生 Codex 工具，通过 `after_tool_call` 观察结果，并参与 Codex `PermissionRequest` 批准流程。该桥接目前还不会重写 Codex 原生工具参数。

 有关完整的类型化 hook 行为，请参阅 [SDK 概览](/zh-CN/plugins/sdk-overview#hook-decision-semantics)。

 ## 相关内容

 - [Building Plugins](/zh-CN/plugins/building-plugins) — 创建你自己的插件
- [Plugin Bundles](/zh-CN/plugins/bundles) — Codex/Claude/Cursor bundle 兼容性
+- [Plugin Bundles](/zh-CN/plugins/bundles) — 与 Codex/Claude/Cursor 的 Bundle 兼容性
 - [Plugin Manifest](/zh-CN/plugins/manifest) — 清单 schema
 - [Registering Tools](/zh-CN/plugins/building-plugins#registering-agent-tools) — 在插件中添加智能体工具
- [Plugin Internals](/zh-CN/plugins/architecture) — 能力模型和加载流水线
+- [Plugin Internals](/zh-CN/plugins/architecture) — 能力模型和加载管线
 - [Community Plugins](/zh-CN/plugins/community) — 第三方列表
--- a/docs/zh-CN/tools/subagents.md
+++ b/docs/zh-CN/tools/subagents.md
@ -1,24 +1,24 @@
 ---
 read_when:
-    - 你想通过智能体进行后台 / 并行工作
+    - 你希望通过该智能体进行后台/并行工作
    - 你正在更改 `sessions_spawn` 或子智能体工具策略
-    - 你正在实现或排查线程绑定的子智能体会话问题
-summary: 子智能体：启动隔离的智能体运行，并将结果回传到请求者聊天中
+    - 你正在实现或排查线程绑定的子智能体会话
+summary: 子智能体：启动隔离的智能体运行，并将结果回报到请求者聊天中
 title: 子智能体
 x-i18n:
-    generated_at: "2026-04-23T23:05:30Z"
+    generated_at: "2026-04-24T16:58:29Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 23202b1761e372e547b02183cb68056043aed04b5620db8b222cbfc7e6cd97ab
+    source_hash: 471b01c1e6bf689f097e67a7037f35348ac7e8a8a334a83778c6593073332274
    source_path: tools/subagents.md
    workflow: 15
 ---

-子智能体是在现有智能体运行中启动的后台智能体运行。它们会在自己的会话中运行（`agent:<agentId>:subagent:<uuid>`），并在完成后将结果**回传**到请求者聊天渠道。每次子智能体运行都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。
+子智能体是从现有智能体运行中派生出的后台智能体运行。它们在各自独立的会话中运行（`agent:<agentId>:subagent:<uuid>`），并在完成后将其结果**回报**到请求者聊天渠道。每次子智能体运行都会作为一个[后台任务](/zh-CN/automation/tasks)进行跟踪。

-## Slash 命令
+## 斜杠命令

-使用 `/subagents` 检查或控制**当前会话**的子智能体运行：
+使用 `/subagents` 来查看或控制**当前会话**的子智能体运行：

 - `/subagents list`
 - `/subagents kill <id|#|all>`
@ -30,7 +30,7 @@ x-i18n:

 线程绑定控制：

-这些命令可用于支持持久线程绑定的渠道。请参阅下文的**支持线程的渠道**。
+这些命令适用于支持持久线程绑定的渠道。请参见下方的**支持线程的渠道**。

 - `/focus <subagent-label|session-key|session-id|session-label>`
 - `/unfocus`
@ -38,52 +38,62 @@ x-i18n:
 - `/session idle <duration|off>`
 - `/session max-age <duration|off>`

-`/subagents info` 会显示运行元数据（状态、时间戳、会话 id、transcript 路径、清理信息）。
-如需受限且经过安全过滤的回溯视图，请使用 `sessions_history`；如果你需要原始完整 transcript，请检查磁盘上的 transcript 路径。
+`/subagents info` 会显示运行元数据（状态、时间戳、会话 id、转录路径、清理情况）。
+使用 `sessions_history` 获取有边界且经过安全过滤的回溯视图；当你需要原始完整转录时，请检查磁盘上的转录路径。

 ### 启动行为

-`/subagents spawn` 作为用户命令启动一个后台子智能体，而不是内部中继；当运行完成时，它会向请求者聊天发送一条最终完成更新。
+`/subagents spawn` 会以用户命令而非内部转发的方式启动一个后台子智能体，并在运行结束时向请求者聊天回传一次最终完成更新。

 - 启动命令是非阻塞的；它会立即返回一个运行 id。
- 完成时，子智能体会将摘要 / 结果消息回传到请求者聊天渠道。
- 完成投递基于推送。一旦已启动，就不要为了等待其完成而循环轮询 `/subagents list`、
-  `sessions_list` 或 `sessions_history`；仅在调试或干预时按需检查状态。
- 完成时，OpenClaw 会尽力关闭该子智能体会话打开的已跟踪浏览器标签页 / 进程，然后再继续执行回传清理流程。
- 对于手动启动，投递具备弹性：
-  - OpenClaw 会先使用稳定的幂等键尝试直接 `agent` 投递。
-  - 如果直接投递失败，则回退到队列路由。
-  - 如果队列路由仍不可用，则在最终放弃前，回传会以较短的指数退避策略重试。
+- 完成后，子智能体会向请求者聊天渠道回报一条摘要/结果消息。
+- 完成通知采用推送方式。一旦启动，不要仅仅为了等待其完成而循环轮询 `/subagents list`、`sessions_list` 或 `sessions_history`；只在调试或干预时按需检查状态。
+- 完成时，OpenClaw 会尽最大努力在回报清理流程继续之前，关闭该子智能体会话打开的已跟踪浏览器标签页/进程。
+- 对于手动启动，投递是具备韧性的：
+  - OpenClaw 会先尝试使用稳定的幂等键进行直接 `agent` 投递。
+  - 如果直接投递失败，会回退到队列路由。
+  - 如果队列路由仍不可用，则会在最终放弃前通过短时指数退避重试回报。
 - 完成投递会保留已解析的请求者路由：
-  - 在可用时，线程绑定或会话绑定的完成路由优先
-  - 如果完成来源仅提供一个渠道，OpenClaw 会从请求者会话的已解析路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全缺失的 target / account，以便直接投递仍然可用
- 向请求者会话交接的完成内容，是运行时生成的内部上下文（不是用户编写的文本），其中包括：
-  - `Result`（最新可见的 `assistant` 回复文本；否则为经过清理的最新 tool / toolResult 文本；终态失败运行不会复用捕获到的回复文本）
+  - 如果可用，线程绑定或会话绑定的完成路由优先生效
+  - 如果完成来源只提供渠道，OpenClaw 会从请求者会话已解析的路由（`lastChannel` / `lastTo` / `lastAccountId`）中补齐缺失的目标/账号，以便直接投递仍可工作
+- 向请求者会话交接的完成内容是运行时生成的内部上下文（不是用户撰写的文本），其中包括：
+  - `Result`（最新可见的 `assistant` 回复文本；否则为已净化的最新 `tool`/`toolResult` 文本；终态失败的运行不会复用已捕获的回复文本）
  - `Status`（`completed successfully` / `failed` / `timed out` / `unknown`）
-  - 紧凑的运行时 / token 统计
-  - 一条投递说明，告诉请求者智能体要用正常 assistant 语气重写，而不是直接转发原始内部元数据
+  - 紧凑的运行时/令牌统计信息
+  - 一条投递指令，告知请求者智能体用正常助手语气重写（而不是转发原始内部元数据）
 - `--model` 和 `--thinking` 会覆盖该次运行的默认值。
- 使用 `info` / `log` 可在完成后检查详细信息和输出。
- `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久线程绑定会话，请使用 `sessions_spawn` 并设置 `thread: true` 和 `mode: "session"`。
- 对于 ACP harness 会话（Codex、Claude Code、Gemini CLI），请使用 `sessions_spawn` 并设置 `runtime: "acp"`，同时参阅 [ACP 智能体](/zh-CN/tools/acp-agents)，尤其是在调试完成投递或智能体到智能体循环时查看 [ACP 投递模型](/zh-CN/tools/acp-agents#delivery-model)。
+- 使用 `info`/`log` 可在完成后查看详细信息和输出。
+- `/subagents spawn` 是一次性模式（`mode: "run"`）。对于持久的线程绑定会话，请使用带有 `thread: true` 和 `mode: "session"` 的 `sessions_spawn`。
+- 对于 ACP harness 会话（Codex、Claude Code、Gemini CLI），请使用带有 `runtime: "acp"` 的 `sessions_spawn`，并参见 [ACP Agents](/zh-CN/tools/acp-agents)，尤其是在调试完成通知或智能体到智能体循环时的 [ACP delivery model](/zh-CN/tools/acp-agents#delivery-model)。

 主要目标：

- 并行化 “研究 / 长任务 / 慢工具” 类型的工作，而不阻塞主运行。
+- 在不阻塞主运行的情况下并行处理“研究 / 长任务 / 慢工具”工作。
 - 默认保持子智能体隔离（会话隔离 + 可选沙箱隔离）。
- 保持工具接口难以被误用：默认情况下，子智能体**不会**获得会话工具。
- 支持为编排器模式配置可嵌套深度。
+- 保持工具表面不易被误用：默认情况下，子智能体**不会**获得会话工具。
+- 支持可配置的嵌套深度，以适配编排器模式。

-成本说明：每个子智能体默认都有**自己的**上下文和 token 使用量。对于重型或重复性任务，请为子智能体设置更便宜的模型，并让主智能体继续使用更高质量的模型。你可以通过 `agents.defaults.subagents.model` 或按智能体覆盖来配置。如果子智能体确实需要请求者当前 transcript，智能体可以在该次启动中请求 `context: "fork"`。
+成本说明：默认情况下，每个子智能体都有其**自己的**上下文和令牌消耗。对于重型或重复性任务，请为子智能体设置更便宜的模型，同时让主智能体保留更高质量的模型。你可以通过 `agents.defaults.subagents.model` 或按智能体覆盖项来配置这一点。当子级确实需要请求者当前转录时，智能体可以仅在那一次启动时请求 `context: "fork"`。
+
+## 上下文模式
+
+原生子智能体默认以隔离方式启动，除非调用方明确要求分叉当前转录。
+
+| 模式       | 适用场景                                                                 | 行为                                                                                |
+| ---------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `isolated` | 全新研究、独立实现、慢工具工作，或任何可以在任务文本中简要说明的工作     | 创建一个干净的子级转录。这是默认设置，并能将令牌使用保持在较低水平。                |
+| `fork`     | 工作依赖于当前对话、之前的工具结果，或请求者转录中已有的细微指令         | 在子级启动前，将请求者转录分支到子级会话中。                                        |
+
+谨慎使用 `fork`。它用于对上下文敏感的委派，不是清晰编写任务提示的替代方案。

 ## 工具

 使用 `sessions_spawn`：

- 启动一个子智能体运行（`deliver: false`，全局 lane：`subagent`）
- 然后执行一次回传步骤，并将回传回复发布到请求者聊天渠道
- 默认模型：继承调用者，除非你设置了 `agents.defaults.subagents.model`（或按智能体设置 `agents.list[].subagents.model`）；显式的 `sessions_spawn.model` 仍然优先。
- 默认 thinking：继承调用者，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体设置 `agents.list[].subagents.thinking`）；显式的 `sessions_spawn.thinking` 仍然优先。
+- 启动一个子智能体运行（`deliver: false`，全局队列：`subagent`）
+- 然后执行一个回报步骤，并将回报回复发送到请求者聊天渠道
+- 默认模型：继承调用方，除非你设置了 `agents.defaults.subagents.model`（或按智能体设置 `agents.list[].subagents.model`）；显式提供的 `sessions_spawn.model` 仍然优先生效。
+- 默认思考级别：继承调用方，除非你设置了 `agents.defaults.subagents.thinking`（或按智能体设置 `agents.list[].subagents.thinking`）；显式提供的 `sessions_spawn.thinking` 仍然优先生效。
 - 默认运行超时：如果省略 `sessions_spawn.runTimeoutSeconds`，OpenClaw 会在已设置时使用 `agents.defaults.subagents.runTimeoutSeconds`；否则回退到 `0`（无超时）。

 工具参数：
@ -91,58 +101,58 @@ x-i18n:
 - `task`（必填）
 - `label?`（可选）
 - `agentId?`（可选；如果允许，可在另一个智能体 id 下启动）
- `model?`（可选；覆盖子智能体模型；无效值会被跳过，子智能体将使用默认模型运行，并在工具结果中给出警告）
- `thinking?`（可选；覆盖子智能体运行的 thinking 级别）
- `runTimeoutSeconds?`（已设置时默认取 `agents.defaults.subagents.runTimeoutSeconds`，否则为 `0`；设置后，子智能体运行会在 N 秒后中止）
- `thread?`（默认 `false`；当为 `true` 时，请求为该子智能体会话启用渠道线程绑定）
+- `model?`（可选；覆盖子智能体模型；无效值会被跳过，子智能体会在默认模型上运行，并在工具结果中附带警告）
+- `thinking?`（可选；覆盖子智能体运行的思考级别）
+- `runTimeoutSeconds?`（若已设置，则默认使用 `agents.defaults.subagents.runTimeoutSeconds`，否则为 `0`；设置后，子智能体运行会在 N 秒后中止）
+- `thread?`（默认为 `false`；当为 `true` 时，会为该子智能体会话请求渠道线程绑定）
 - `mode?`（`run|session`）
-  - 默认是 `run`
-  - 如果 `thread: true` 且省略 `mode`，默认值会变为 `session`
+  - 默认为 `run`
+  - 如果 `thread: true` 且省略 `mode`，默认会变为 `session`
  - `mode: "session"` 要求 `thread: true`
 - `cleanup?`（`delete|keep`，默认 `keep`）
- `sandbox?`（`inherit|require`，默认 `inherit`；如果目标子运行时不是沙箱隔离的，`require` 会拒绝启动）
- `context?`（`isolated|fork`，默认 `isolated`；仅限原生子智能体）
-  - `isolated` 会创建一个干净的子 transcript，并且是默认值。
-  - `fork` 会将请求者当前 transcript 分叉到子会话中，因此子会话会以相同的对话上下文开始。
-  - 仅在子会话需要当前 transcript 时才使用 `fork`。对于范围明确的工作，请省略 `context`。
- `sessions_spawn` **不接受**渠道投递参数（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。如需投递，请在已启动的运行中使用 `message` / `sessions_send`。
+- `sandbox?`（`inherit|require`，默认 `inherit`；`require` 会在目标子级运行时未启用沙箱时拒绝启动）
+- `context?`（`isolated|fork`，默认 `isolated`；仅适用于原生子智能体）
+  - `isolated` 会创建一个干净的子级转录，并且是默认值。
+  - `fork` 会将请求者当前转录分支到子级会话中，使子级以相同的对话上下文启动。
+  - 仅当子级需要当前转录时才使用 `fork`。对于范围明确的工作，请省略 `context`。
+- `sessions_spawn` **不**接受渠道投递参数（`target`、`channel`、`to`、`threadId`、`replyTo`、`transport`）。如需投递，请从已启动的运行中使用 `message`/`sessions_send`。

 ## 线程绑定会话

-当某个渠道启用了线程绑定时，子智能体可以保持绑定到一个线程，这样该线程中的后续用户消息就会继续路由到同一个子智能体会话。
+当某个渠道启用线程绑定时，子智能体可以保持绑定到某个线程，这样该线程中的后续用户消息会持续路由到同一个子智能体会话。

 ### 支持线程的渠道

- Discord（当前唯一受支持的渠道）：支持持久线程绑定的子智能体会话（`sessions_spawn` 配合 `thread: true`）、手动线程控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSubagentSessions`。
+- Discord（当前唯一受支持的渠道）：支持持久的线程绑定子智能体会话（使用带有 `thread: true` 的 `sessions_spawn`）、手动线程控制（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`），以及适配器键 `channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours` 和 `channels.discord.threadBindings.spawnSubagentSessions`。

 快速流程：

-1. 使用 `sessions_spawn` 启动，并设置 `thread: true`（可选地设置 `mode: "session"`）。
-2. OpenClaw 会在当前激活渠道中创建一个线程，或将某个线程绑定到该会话目标。
-3. 该线程中的回复和后续消息会路由到绑定的会话。
-4. 使用 `/session idle` 查看 / 更新无活动自动取消聚焦策略，使用 `/session max-age` 控制硬性上限。
+1. 使用带有 `thread: true` 的 `sessions_spawn` 启动（也可选择 `mode: "session"`）。
+2. OpenClaw 会在当前渠道中创建一个线程，或将线程绑定到该会话目标。
+3. 该线程中的回复和后续消息会路由到已绑定的会话。
+4. 使用 `/session idle` 查看/更新不活动自动取消聚焦设置，并使用 `/session max-age` 控制硬性上限。
 5. 使用 `/unfocus` 手动解除绑定。

 手动控制：

- `/focus <target>` 将当前线程（或创建一个线程）绑定到某个子智能体 / 会话目标。
- `/unfocus` 移除当前已绑定线程的绑定。
- `/agents` 列出活动运行和绑定状态（`thread:<id>` 或 `unbound`）。
- `/session idle` 和 `/session max-age` 仅对已聚焦的绑定线程有效。
+- `/focus <target>` 会将当前线程（或创建一个线程）绑定到某个子智能体/会话目标。
+- `/unfocus` 会移除当前已绑定线程的绑定关系。
+- `/agents` 会列出活跃运行和绑定状态（`thread:<id>` 或 `unbound`）。
+- `/session idle` 和 `/session max-age` 仅适用于已聚焦的绑定线程。

 配置开关：

 - 全局默认值：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`
- 渠道覆盖和启动自动绑定键是特定于适配器的。请参阅上文的**支持线程的渠道**。
+- 渠道覆盖和启动时自动绑定键是适配器特定的。请参见上方的**支持线程的渠道**。

-有关当前适配器详情，请参阅[配置参考](/zh-CN/gateway/configuration-reference)和 [Slash commands](/zh-CN/tools/slash-commands)。
+当前适配器详情请参见 [Configuration Reference](/zh-CN/gateway/configuration-reference) 和 [Slash commands](/zh-CN/tools/slash-commands)。

 允许列表：

- `agents.list[].subagents.allowAgents`：可通过 `agentId` 作为目标的智能体 id 列表（`["*"]` 表示允许任意目标）。默认：仅允许请求者智能体。
+- `agents.list[].subagents.allowAgents`：可通过 `agentId` 指定的智能体 id 列表（`["*"]` 表示允许任意智能体）。默认值：仅请求者智能体。
 - `agents.defaults.subagents.allowAgents`：当请求者智能体未设置自己的 `subagents.allowAgents` 时使用的默认目标智能体允许列表。
- 沙箱继承保护：如果请求者会话是沙箱隔离的，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。
- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`：当为 true 时，阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式配置文件选择）。默认：false。
+- 沙箱继承保护：如果请求者会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。
+- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`：当为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置档案）。默认值：false。

 发现：

@ -150,17 +160,17 @@ x-i18n:

 自动归档：

- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 之后自动归档（默认：60）。
- 归档使用 `sessions.delete`，并将 transcript 重命名为 `*.deleted.<timestamp>`（同一文件夹内）。
- `cleanup: "delete"` 会在回传后立即归档（仍然通过重命名保留 transcript）。
- 自动归档是尽力而为的；如果 Gateway 网关重启，待处理计时器会丢失。
- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会保留到自动归档时。
- 自动归档同样适用于深度 1 和深度 2 会话。
- 浏览器清理与归档清理是分开的：在运行结束时，已跟踪的浏览器标签页 / 进程会尽力关闭，即使 transcript / 会话记录被保留。
+- 子智能体会话会在 `agents.defaults.subagents.archiveAfterMinutes` 之后自动归档（默认值：60）。
+- 归档使用 `sessions.delete`，并将转录重命名为 `*.deleted.<timestamp>`（同一文件夹）。
+- `cleanup: "delete"` 会在回报后立即归档（仍会通过重命名保留转录）。
+- 自动归档尽力而为；如果 Gateway 网关重启，待处理计时器会丢失。
+- `runTimeoutSeconds` **不会**自动归档；它只会停止运行。会话会保留，直到自动归档发生。
+- 自动归档同样适用于深度 1 和深度 2 的会话。
+- 浏览器清理与归档清理分离：运行结束时，会尽最大努力关闭已跟踪的浏览器标签页/进程，即使转录/会话记录被保留也是如此。

 ## 嵌套子智能体

-默认情况下，子智能体不能再启动自己的子智能体（`maxSpawnDepth: 1`）。你可以将 `maxSpawnDepth: 2` 设为允许一层嵌套，这样就支持**编排器模式**：主智能体 → 编排器子智能体 → 工作型子子智能体。
+默认情况下，子智能体不能再启动自己的子智能体（`maxSpawnDepth: 1`）。你可以通过设置 `maxSpawnDepth: 2` 来启用一层嵌套，这样就允许使用**编排器模式**：主智能体 → 编排器子智能体 → 工作子子智能体。

 ### 如何启用

@ -169,10 +179,10 @@ x-i18n:
  agents: {
    defaults: {
      subagents: {
-        maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
-        maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
-        maxConcurrent: 8, // global concurrency lane cap (default: 8)
-        runTimeoutSeconds: 900, // default timeout for sessions_spawn when omitted (0 = no timeout)
+        maxSpawnDepth: 2, // 允许子智能体启动子级（默认值：1）
+        maxChildrenPerAgent: 5, // 每个智能体会话的最大活跃子级数（默认值：5）
+        maxConcurrent: 8, // 全局并发队列上限（默认值：8）
+        runTimeoutSeconds: 900, // 省略时 sessions_spawn 的默认超时（0 = 无超时）
      },
    },
  },
@ -181,123 +191,114 @@ x-i18n:

 ### 深度级别

-| 深度 | 会话键形状                            | 角色                                          | 可否启动子级？                   |
+| 深度 | 会话键形态                                   | 角色                                          | 可以启动子级？               |
 | ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
-| 0     | `agent:<id>:main`                            | 主智能体                                    | 始终可以                       |
-| 1     | `agent:<id>:subagent:<uuid>`                 | 子智能体（当允许深度 2 时可作为编排器） | 仅当 `maxSpawnDepth >= 2` |
-| 2     | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | 子子智能体（叶子工作者）                   | 永远不可以                        |
+| 0     | `agent:<id>:main`                            | 主智能体                                      | 始终可以                     |
+| 1     | `agent:<id>:subagent:<uuid>`                 | 子智能体（在允许深度 2 时可作为编排器）       | 仅当 `maxSpawnDepth >= 2`    |
+| 2     | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | 子子智能体（叶子工作节点）                    | 永不可以                     |

-### 回传链
+### 回报链

-结果会沿链路向上流动：
+结果会沿链路逐级回传：

-1. 深度 2 工作者完成 → 回传给其父级（深度 1 编排器）
-2. 深度 1 编排器接收回传、综合结果、完成 → 回传给主智能体
-3. 主智能体接收回传并投递给用户
+1. 深度 2 的工作节点完成 → 向其父级（深度 1 编排器）回报
+2. 深度 1 编排器接收回报、综合结果、完成 → 向主智能体回报
+3. 主智能体接收回报并将结果投递给用户

-每一级只会看到来自其直接子级的回传。
+每一层只能看到其直接子级的回报。

-运维指导：
+操作指南：

- 只启动一次子任务，并等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或
-  `exec` sleep 命令构建轮询循环。
- 如果子任务完成事件在你已经发送最终答案之后才到达，
-  正确的后续动作是发送精确的静默 token：`NO_REPLY` / `no_reply`。
+- 子级工作启动一次后，等待完成事件，而不是围绕 `sessions_list`、`sessions_history`、`/subagents list` 或 `exec` sleep 命令构建轮询循环。
+- 如果子级完成事件在你已经发送最终答案之后才到达，正确的后续处理是精确的静默令牌 `NO_REPLY` / `no_reply`。

 ### 按深度划分的工具策略

 - 角色和控制范围会在启动时写入会话元数据。这样可以防止扁平化或恢复后的会话键意外重新获得编排器权限。
- **深度 1（编排器，当 `maxSpawnDepth >= 2` 时）**：会获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子任务。其他会话 / 系统工具仍然被拒绝。
- **深度 1（叶子节点，当 `maxSpawnDepth == 1` 时）**：不提供任何会话工具（当前默认行为）。
- **深度 2（叶子工作者）**：不提供任何会话工具——在深度 2 上，`sessions_spawn` 始终被拒绝。不能再继续启动子级。
+- **深度 1（编排器，当 `maxSpawnDepth >= 2` 时）**：获得 `sessions_spawn`、`subagents`、`sessions_list`、`sessions_history`，以便管理其子级。其他会话/系统工具仍然被拒绝。
+- **深度 1（叶子节点，当 `maxSpawnDepth == 1` 时）**：没有会话工具（当前默认行为）。
+- **深度 2（叶子工作节点）**：没有会话工具——在深度 2 时 `sessions_spawn` 始终被拒绝。无法继续启动更多子级。

-### 按智能体划分的启动数量上限
+### 每个智能体的启动数量限制

-每个智能体会话（任意深度）同时最多只能拥有 `maxChildrenPerAgent`（默认：5）个活动子任务。这可以防止单个编排器出现失控式扇出。
+每个智能体会话（任意深度）同一时间最多只能有 `maxChildrenPerAgent`（默认值：5）个活跃子级。这可以防止单个编排器出现失控扇出。

 ### 级联停止

-停止深度 1 编排器会自动停止它的所有深度 2 子任务：
+停止一个深度 1 编排器会自动停止其所有深度 2 子级：

- 在主聊天中执行 `/stop` 会停止所有深度 1 智能体，并级联停止它们的深度 2 子任务。
- `/subagents kill <id>` 会停止指定的子智能体，并级联停止其子任务。
- `/subagents kill all` 会停止该请求者的所有子智能体，并执行级联停止。
+- 在主聊天中发送 `/stop` 会停止所有深度 1 智能体，并级联停止它们的深度 2 子级。
+- `/subagents kill <id>` 会停止指定的某个子智能体，并级联停止其子级。
+- `/subagents kill all` 会停止该请求者的所有子智能体，并进行级联停止。

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

-子智能体的 auth 是按**智能体 id**解析的，而不是按会话类型：
+子智能体认证按**智能体 id**解析，而不是按会话类型：

- 子智能体会话键是 `agent:<agentId>:subagent:<uuid>`。
- auth 存储会从该智能体的 `agentDir` 加载。
- 主智能体的 auth 配置文件会作为**回退**合并进来；如有冲突，智能体配置文件优先于主配置文件。
+- 子智能体会话键为 `agent:<agentId>:subagent:<uuid>`。
+- 认证存储从该智能体的 `agentDir` 加载。
+- 主智能体的认证配置档案会作为**回退项**合并进来；如果发生冲突，智能体配置档案优先于主配置档案。

-注意：这种合并是追加式的，因此主配置文件始终可作为回退使用。目前尚不支持每个智能体完全隔离的 auth。
+注意：这种合并是增量式的，因此主配置档案始终可作为回退项使用。目前尚不支持每个智能体完全隔离的认证。

-## 回传
+## 回报

-子智能体通过回传步骤进行结果汇报：
+子智能体通过回报步骤进行结果汇报：

- 回传步骤在子智能体会话内部运行（而不是在请求者会话中运行）。
- 如果子智能体回复恰好为 `ANNOUNCE_SKIP`，则不会发布任何内容。
- 如果最新 assistant 文本恰好是静默 token `NO_REPLY` / `no_reply`，
-  即使之前存在可见的进度，也会抑制回传输出。
- 否则，投递行为取决于请求者深度：
-  - 顶层请求者会话使用后续 `agent` 调用，并开启外部投递（`deliver=true`）
-  - 嵌套请求者子智能体会话会接收内部后续注入（`deliver=false`），以便编排器在会话内综合子结果
-  - 如果某个嵌套请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者
- 对于顶层请求者会话，完成模式下的直接投递会先解析任何已绑定的会话 / 线程路由和 hook 覆盖项，然后从请求者会话中存储的路由补全缺失的渠道目标字段。即使完成来源只标识了渠道，这也能让完成消息保持在正确的聊天 / 话题中。
- 在构建嵌套完成结果时，子任务完成聚合会限定在当前请求者运行范围内，以防旧运行中的子任务输出泄漏到当前回传中。
- 在渠道适配器支持的情况下，回传回复会保留线程 / 话题路由。
- 回传上下文会被规范化为稳定的内部事件块：
+- 回报步骤在子智能体会话内部运行（不是在请求者会话中运行）。
+- 如果子智能体精确回复 `ANNOUNCE_SKIP`，则不会发布任何内容。
+- 如果最新的助手文本是精确的静默令牌 `NO_REPLY` / `no_reply`，即使之前存在可见进度，也会抑制回报输出。
+- 否则，投递取决于请求者深度：
+  - 顶层请求者会话使用带外部投递的后续 `agent` 调用（`deliver=true`）
+  - 嵌套的请求者子智能体会话接收内部后续注入（`deliver=false`），以便编排器能够在会话内综合子级结果
+  - 如果嵌套的请求者子智能体会话已不存在，OpenClaw 会在可用时回退到该会话的请求者
+- 对于顶层请求者会话，完成模式下的直接投递会先解析任何已绑定的会话/线程路由和 hook 覆盖项，然后从请求者会话存储的路由中补齐缺失的渠道目标字段。这样即使完成来源只标识了渠道，也能确保完成通知发送到正确的聊天/话题中。
+- 在构建嵌套完成结果时，子级完成聚合被限定在当前请求者运行范围内，防止陈旧的先前运行子级输出泄漏到当前回报中。
+- 在渠道适配器可用时，回报回复会保留线程/话题路由。
+- 回报上下文会被标准化为稳定的内部事件块：
  - 来源（`subagent` 或 `cron`）
-  - 子会话键 / id
-  - 回传类型 + 任务标签
-  - 基于运行时结果派生的状态行（`success`、`error`、`timeout` 或 `unknown`）
-  - 从最新可见 assistant 文本中选择结果内容；否则使用经过清理的最新 tool / toolResult 文本；终态失败运行会报告失败状态，而不会重放已捕获的回复文本
-  - 一条后续说明，描述何时应回复、何时应保持静默
- `Status` 不是从模型输出中推断出来的；它来自运行时结果信号。
- 在超时情况下，如果子任务只执行到了工具调用，回传可以将该历史压缩成简短的部分进展摘要，而不是重放原始工具输出。
+  - 子级会话键/id
+  - 回报类型 + 任务标签
+  - 从运行时结果派生的状态行（`success`、`error`、`timeout` 或 `unknown`）
+  - 从最新可见助手文本中选择的结果内容；否则使用经过净化的最新 `tool`/`toolResult` 文本；终态失败的运行会报告失败状态，而不会重放已捕获的回复文本
+  - 一条后续指令，说明何时应回复、何时应保持静默
+- `Status` 不是从模型输出推断的；它来自运行时结果信号。
+- 在超时时，如果子级只执行到了工具调用阶段，回报可以将那段历史折叠为简短的部分进度摘要，而不是重放原始工具输出。

-回传负载末尾会包含一行统计信息（即使被包裹时也会保留）：
+回报载荷在末尾都包含一行统计信息（即使被包裹）：

- 运行时长（例如 `runtime 5m12s`）
- Token 使用量（输入 / 输出 / 总量）
- 当配置了模型定价（`models.providers.*.models[].cost`）时，显示估算成本
- `sessionKey`、`sessionId` 和 transcript 路径（这样主智能体可以通过 `sessions_history` 获取历史，或直接检查磁盘上的文件）
- 内部元数据仅用于编排；面向用户的回复应重写为正常 assistant 语气。
+- 运行时长（例如，`runtime 5m12s`）
+- 令牌使用量（输入/输出/总计）
+- 配置了模型定价时的预估成本（`models.providers.*.models[].cost`）
+- `sessionKey`、`sessionId` 和转录路径（这样主智能体就可以通过 `sessions_history` 获取历史，或直接检查磁盘上的文件）
+- 内部元数据仅用于编排；面向用户的回复应使用正常助手语气重写。

 `sessions_history` 是更安全的编排路径：

- assistant 回溯会先被规范化：
+- 助手回溯会先进行标准化：
  - 去除 thinking 标签
  - 去除 `<relevant-memories>` / `<relevant_memories>` 脚手架块
-  - 去除纯文本工具调用 XML 负载块，例如 `<tool_call>...</tool_call>`、
-    `<function_call>...</function_call>`、`<tool_calls>...</tool_calls>` 和
-    `<function_calls>...</function_calls>`，包括那些从未正常闭合的截断
-    负载
-  - 去除降级的工具调用 / 结果脚手架和历史上下文标记
-  - 去除泄漏的模型控制 token，例如 `<|assistant|>`、其他 ASCII
-    `<|...|>` token，以及全角变体 `<｜...｜>`
+  - 去除纯文本工具调用 XML 载荷块，如 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>` 和 `<function_calls>...</function_calls>`，包括那些从未正常闭合的截断载荷
+  - 去除降级后的工具调用/结果脚手架和历史上下文标记
+  - 去除泄漏的模型控制令牌，例如 `<|assistant|>`、其他 ASCII `<|...|>` 令牌，以及全角 `<｜...｜>` 变体
  - 去除格式错误的 MiniMax 工具调用 XML
- 类似凭证 / token 的文本会被脱敏
- 过长的块可能会被截断
- 对于非常大的历史，可能会丢弃较早的行，或用
-  `[sessions_history omitted: message too large]` 替换超大的单行
- 当你需要完整的逐字节 transcript 时，回退方案是直接检查磁盘上的原始 transcript
+- 类似凭证/令牌的文本会被脱敏
+- 长内容块可能会被截断
+- 对于非常大的历史，可能会丢弃较旧的行，或用 `[sessions_history omitted: message too large]` 替换超大的某一行
+- 当你需要完整逐字节转录时，回退方式是直接检查磁盘上的原始转录文件

 ## 工具策略（子智能体工具）

-默认情况下，子智能体会获得**除会话工具和系统工具之外的所有工具**：
+默认情况下，子智能体获得**除会话工具**和系统工具之外的**所有工具**：

 - `sessions_list`
 - `sessions_history`
 - `sessions_send`
 - `sessions_spawn`

-这里的 `sessions_history` 仍然是有边界、经过清理的回溯视图；它
-不是原始 transcript 转储。
+这里的 `sessions_history` 也仍然是一个有边界、经过净化的回溯视图；它不是原始转录转储。

-当 `maxSpawnDepth >= 2` 时，深度 1 编排器子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便管理它们的子任务。
+当 `maxSpawnDepth >= 2` 时，深度 1 的编排器子智能体还会额外获得 `sessions_spawn`、`subagents`、`sessions_list` 和 `sessions_history`，以便管理其子级。

 可通过配置覆盖：

@ -313,9 +314,9 @@ x-i18n:
  tools: {
    subagents: {
      tools: {
-        // deny wins
+        // deny 优先生效
        deny: ["gateway", "cron"],
-        // if allow is set, it becomes allow-only (deny still wins)
+        // 如果设置了 allow，则变为仅允许 allow 中的工具（deny 仍然优先生效）
        // allow: ["read", "exec", "process"]
      },
    },
@ -325,27 +326,27 @@ x-i18n:

 ## 并发

-子智能体使用专用的进程内队列 lane：
+子智能体使用专用的进程内队列：

- Lane 名称：`subagent`
- 并发数：`agents.defaults.subagents.maxConcurrent`（默认 `8`）
+- 队列名称：`subagent`
+- 并发度：`agents.defaults.subagents.maxConcurrent`（默认值 `8`）

 ## 停止

- 在请求者聊天中发送 `/stop` 会中止请求者会话，并停止由其启动的所有活动子智能体运行，同时级联停止嵌套子任务。
- `/subagents kill <id>` 会停止指定的子智能体，并级联停止其子任务。
+- 在请求者聊天中发送 `/stop` 会中止请求者会话，并停止所有由其启动的活跃子智能体运行，同时级联停止嵌套子级。
+- `/subagents kill <id>` 会停止指定的某个子智能体，并级联停止其子级。

 ## 限制

- 子智能体回传是**尽力而为**的。如果 Gateway 网关重启，待处理的“回传结果”工作会丢失。
- 子智能体仍然共享同一个 Gateway 网关进程资源；请将 `maxConcurrent` 视为安全阀。
+- 子智能体回报是**尽力而为**的。如果 Gateway 网关重启，待处理的“回报结果”工作会丢失。
+- 子智能体仍共享同一个 Gateway 网关进程资源；应将 `maxConcurrent` 视为安全阀。
 - `sessions_spawn` 始终是非阻塞的：它会立即返回 `{ status: "accepted", runId, childSessionKey }`。
- 子智能体上下文只注入 `AGENTS.md` + `TOOLS.md`（不包括 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。
- 最大嵌套深度为 5（`maxSpawnDepth` 范围：1–5）。对于大多数使用场景，推荐深度 2。
- `maxChildrenPerAgent` 限制每个会话的活动子任务数量（默认：5，范围：1–20）。
+- 子智能体上下文只注入 `AGENTS.md` + `TOOLS.md`（不注入 `SOUL.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md` 或 `BOOTSTRAP.md`）。
+- 最大嵌套深度为 5（`maxSpawnDepth` 范围：1–5）。对于大多数使用场景，推荐使用深度 2。
+- `maxChildrenPerAgent` 会限制每个会话的活跃子级数量（默认值：5，范围：1–20）。

 ## 相关内容

- [ACP 智能体](/zh-CN/tools/acp-agents)
- [多智能体沙箱工具](/zh-CN/tools/multi-agent-sandbox-tools)
- [智能体发送](/zh-CN/tools/agent-send)
+- [ACP agents](/zh-CN/tools/acp-agents)
+- [Multi-agent sandbox tools](/zh-CN/tools/multi-agent-sandbox-tools)
+- [Agent send](/zh-CN/tools/agent-send)