chore(i18n): refresh zh-CN translations

2026-04-25 07:54:30 +00:00 · 2026-04-25 07:54:30 +00:00 · d856fbf3d8
commit d856fbf3d8
parent 882933eec0
6 changed files with 1078 additions and 962 deletions
--- a/docs/zh-CN/gateway/config-agents.md
+++ b/docs/zh-CN/gateway/config-agents.md
@ -1,22 +1,22 @@
 ---
 read_when:
-    - 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills）
+    - 调整智能体默认值（模型、思考、工作区、心跳、媒体、Skills）
    - 配置多智能体路由和绑定
-    - 调整会话、消息传递和 talk 模式行为
-summary: 智能体默认设置、多智能体路由、会话、消息和 talk 配置
+    - 调整会话、消息投递和 talk 模式行为
+summary: 智能体默认值、多智能体路由、会话、消息和 talk 配置
 title: 配置 — 智能体
 x-i18n:
-    generated_at: "2026-04-25T06:22:40Z"
+    generated_at: "2026-04-25T07:51:42Z"
    model: gpt-5.4
    provider: openai
-    source_hash: a3a67914120f567c1d0e4740a320cd285c21ddeb05cbffbec1b9c6ea1e950a6e
+    source_hash: ec43da7bb26dc2b0e99e972d0373b9b3f4dd443cc4ed95fc9807bc4d04483e45
    source_path: gateway/config-agents.md
    workflow: 15
 ---

-`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下的智能体作用域配置键。关于渠道、工具、Gateway 网关运行时以及其他顶层键，请参见 [配置参考](/zh-CN/gateway/configuration-reference)。
+在 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下按智能体作用域划分的配置键。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。

-## 智能体默认设置
+## 智能体默认值

 ### `agents.defaults.workspace`

@ -30,7 +30,7 @@ x-i18n:

 ### `agents.defaults.repoRoot`

-可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区向上遍历并自动检测。
+可选的仓库根目录，会显示在系统提示中的 Runtime 行。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。

 ```json5
 {
@ -40,25 +40,25 @@ x-i18n:

 ### `agents.defaults.skills`

-对于未设置 `agents.list[].skills` 的智能体，可选的默认 Skills 允许列表。
+为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。

 ```json5
 {
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
-      { id: "writer" }, // inherits github, weather
-      { id: "docs", skills: ["docs-search"] }, // replaces defaults
-      { id: "locked-down", skills: [] }, // no skills
+      { id: "writer" }, // 继承 github、weather
+      { id: "docs", skills: ["docs-search"] }, // 替换默认值
+      { id: "locked-down", skills: [] }, // 没有 Skills
    ],
  },
 }
 ```

- 默认情况下，如需不限制 Skills，请省略 `agents.defaults.skills`。
- 省略 `agents.list[].skills` 以继承默认值。
- 将 `agents.list[].skills: []` 设为空 Skills。
- 非空的 `agents.list[].skills` 列表是该智能体的最终集合；它不会与默认值合并。
+- 省略 `agents.defaults.skills` 表示默认不限制 Skills。
+- 省略 `agents.list[].skills` 表示继承默认值。
+- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。
+- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。

 ### `agents.defaults.skipBootstrap`

@ -72,10 +72,10 @@ x-i18n:

 ### `agents.defaults.contextInjection`

-控制何时将工作区引导文件注入到系统提示词中。默认值：`"always"`。
+控制何时将工作区引导文件注入到系统提示中。默认值：`"always"`。

- `"continuation-skip"`：安全的延续轮次（在助手完成响应之后）会跳过再次注入工作区引导内容，以减少提示词大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅应对完全自行管理其提示词生命周期的智能体使用此选项（自定义上下文引擎、自行构建上下文的原生运行时，或专门的不使用引导文件的工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。
+- `"continuation-skip"`：安全的续接轮次（在一次已完成的助手响应之后）会跳过工作区引导内容的重新注入，从而减小提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
+- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅对完全自行管理提示生命周期的智能体使用此选项（自定义上下文引擎、自行构建上下文的原生运行时，或专门的不使用引导文件的工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。

 ```json5
 {
@ -85,7 +85,7 @@ x-i18n:

 ### `agents.defaults.bootstrapMaxChars`

-每个工作区引导文件在截断前允许的最大字符数。默认值：`12000`。
+每个工作区引导文件在被截断前允许的最大字符数。默认值：`12000`。

 ```json5
 {
@ -95,7 +95,7 @@ x-i18n:

 ### `agents.defaults.bootstrapTotalMaxChars`

-跨所有工作区引导文件注入的最大总字符数。默认值：`60000`。
+在所有工作区引导文件中注入的总最大字符数。默认值：`60000`。

 ```json5
 {
@ -105,12 +105,11 @@ x-i18n:

 ### `agents.defaults.bootstrapPromptTruncationWarning`

-控制当引导上下文被截断时，向智能体显示的警告文本。
-默认值：`"once"`。
+控制在引导上下文被截断时，智能体可见的警告文本。默认值：`"once"`。

- `"off"`：绝不向系统提示词中注入警告文本。
- `"once"`：对于每个唯一的截断签名仅注入一次警告（推荐）。
- `"always"`：只要存在截断，每次运行都注入警告。
+- `"off"`：绝不将警告文本注入系统提示。
+- `"once"`：对每个唯一的截断签名注入一次警告（推荐）。
+- `"always"`：只要存在截断，就在每次运行时注入警告。

 ```json5
 {
@ -120,20 +119,20 @@ x-i18n:

 ### 上下文预算归属映射

-OpenClaw 有多个高容量的提示词 / 上下文预算，它们会有意按子系统拆分，而不是全部通过一个通用开关统一控制。
+OpenClaw 有多个高容量的提示 / 上下文预算，它们被有意按子系统拆分，而不是全部流经一个通用开关。

 - `agents.defaults.bootstrapMaxChars` /
  `agents.defaults.bootstrapTotalMaxChars`：
-  常规工作区引导内容注入。
+  常规工作区引导注入。
 - `agents.defaults.startupContext.*`：
  一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日
  `memory/*.md` 文件。
 - `skills.limits.*`：
-  注入到系统提示词中的精简 Skills 列表。
+  注入到系统提示中的精简 Skills 列表。
 - `agents.defaults.contextLimits.*`：
-  有界运行时摘录和注入的由运行时拥有的块。
+  有界的运行时摘录和由运行时拥有的注入块。
 - `memory.qmd.limits.*`：
-  已索引的记忆搜索片段和注入大小控制。
+  已索引的内存搜索片段与注入大小限制。

 仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖项：

@ -163,7 +162,7 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，它们会有意按

 #### `agents.defaults.contextLimits`

-用于有界运行时上下文表面的共享默认值。
+有界运行时上下文表面的共享默认值。

 ```json5
 {
@ -180,14 +179,14 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，它们会有意按
 }
 ```

- `memoryGetMaxChars`：`memory_get` 摘录的默认上限；在添加截断元数据和继续提示之前生效。
+- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接提示前的默认上限。
 - `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。
 - `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。
 - `postCompactionMaxChars`：在压缩后刷新注入期间使用的 `AGENTS.md` 摘录上限。

 #### `agents.list[].contextLimits`

-共享 `contextLimits` 开关的按智能体覆盖项。省略的字段会继承自 `agents.defaults.contextLimits`。
+用于共享 `contextLimits` 开关的按智能体覆盖项。省略的字段会继承自 `agents.defaults.contextLimits`。

 ```json5
 {
@ -213,7 +212,7 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，它们会有意按

 #### `skills.limits.maxSkillsPromptChars`

-注入到系统提示词中的精简 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。
+注入到系统提示中的精简 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。

 ```json5
 {
@ -227,7 +226,7 @@ OpenClaw 有多个高容量的提示词 / 上下文预算，它们会有意按

 #### `agents.list[].skillsLimits.maxSkillsPromptChars`

-Skills 提示词预算的按智能体覆盖项。
+Skills 提示预算的按智能体覆盖项。

 ```json5
 {
@ -246,10 +245,10 @@ Skills 提示词预算的按智能体覆盖项。

 ### `agents.defaults.imageMaxDimensionPx`

-在调用提供商之前，transcript / 工具图片块中图片最长边的最大像素尺寸。
+在调用提供商之前，转录 / 工具图像块中图像最长边的最大像素尺寸。
 默认值：`1200`。

-较低的值通常会减少视觉 token 使用量以及请求负载大小，适合包含大量截图的运行。
+较低的值通常会减少视觉 token 使用量和以截图为主的运行中的请求负载大小。
 较高的值会保留更多视觉细节。

 ```json5
@ -260,7 +259,7 @@ Skills 提示词预算的按智能体覆盖项。

 ### `agents.defaults.userTimezone`

-系统提示词上下文所用的时区（不影响消息时间戳）。默认回退到主机时区。
+系统提示上下文使用的时区（不影响消息时间戳）。会回退到主机时区。

 ```json5
 {
@ -270,7 +269,7 @@ Skills 提示词预算的按智能体覆盖项。

 ### `agents.defaults.timeFormat`

-系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。
+系统提示中的时间格式。默认值：`auto`（操作系统偏好）。

 ```json5
 {
@ -308,9 +307,9 @@ Skills 提示词预算的按智能体覆盖项。
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
-      params: { cacheRetention: "long" }, // global default provider params
+      params: { cacheRetention: "long" }, // 全局默认提供商参数
      embeddedHarness: {
-        runtime: "pi", // pi | auto | registered harness id, e.g. codex
+        runtime: "pi", // pi | auto | 已注册的 harness id，例如 codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
@ -327,53 +326,53 @@ Skills 提示词预算的按智能体覆盖项。
 }
 ```

- `model`：既可以接受字符串（`"provider/model"`），也可以接受对象（`{ primary, fallbacks }`）。
-  - 字符串形式仅设置主模型。
-  - 对象形式设置主模型以及按顺序排列的故障切换模型。
- `imageModel`：既可以接受字符串（`"provider/model"`），也可以接受对象（`{ primary, fallbacks }`）。
+- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。
+  - 字符串形式只设置主模型。
+  - 对象形式设置主模型以及按顺序排列的故障转移模型。
+- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。
  - 作为 `image` 工具路径的视觉模型配置使用。
-  - 当选定 / 默认模型不能接受图片输入时，也会用作回退路由。
- `imageGenerationModel`：既可以接受字符串（`"provider/model"`），也可以接受对象（`{ primary, fallbacks }`）。
-  - 用于共享的图片生成功能，以及任何未来会生成图片的工具 / 插件表面。
-  - 典型值：用于原生 Gemini 图片生成的 `google/gemini-3.1-flash-image-preview`，用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-2`。
-  - 如果你直接选择某个 provider / model，也要配置匹配的 provider 凭证（例如 `google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。
-  - 如果省略，`image_generate` 仍然可以推断一个由认证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider id 顺序尝试其余已注册的图片生成 provider。
- `musicGenerationModel`：既可以接受字符串（`"provider/model"`），也可以接受对象（`{ primary, fallbacks }`）。
-  - 用于共享的音乐生成功能和内置的 `music_generate` 工具。
+  - 当选中的 / 默认模型无法接受图像输入时，也用作回退路由。
+- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。
+  - 用于共享的图像生成能力，以及未来任何生成图像的工具 / 插件表面。
+  - 典型值：`google/gemini-3.1-flash-image-preview` 用于原生 Gemini 图像生成，`fal/fal-ai/flux/dev` 用于 fal，或 `openai/gpt-image-2` 用于 OpenAI Images。
+  - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证（例如，`google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 需要 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 需要 `FAL_KEY`）。
+  - 如果省略，`image_generate` 仍可推断一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的图像生成提供商。
+- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。
+  - 用于共享的音乐生成能力和内置的 `music_generate` 工具。
  - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。
-  - 如果省略，`music_generate` 仍然可以推断一个由认证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider id 顺序尝试其余已注册的音乐生成 provider。
-  - 如果你直接选择某个 provider / model，也要配置匹配的 provider 认证 / API key。
- `videoGenerationModel`：既可以接受字符串（`"provider/model"`），也可以接受对象（`{ primary, fallbacks }`）。
-  - 用于共享的视频生成功能和内置的 `video_generate` 工具。
+  - 如果省略，`music_generate` 仍可推断一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的音乐生成提供商。
+  - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API key。
+- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。
+  - 用于共享的视频生成能力和内置的 `video_generate` 工具。
  - 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
-  - 如果省略，`video_generate` 仍然可以推断一个由认证支持的 provider 默认值。它会先尝试当前默认 provider，然后按 provider id 顺序尝试其余已注册的视频生成 provider。
-  - 如果你直接选择某个 provider / model，也要配置匹配的 provider 认证 / API key。
-  - 内置的 Qwen 视频生成 provider 最多支持 1 个输出视频、1 张输入图片、4 个输入视频、10 秒时长，以及 provider 级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
- `pdfModel`：既可以接受字符串（`"provider/model"`），也可以接受对象（`{ primary, fallbacks }`）。
+  - 如果省略，`video_generate` 仍可推断一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的视频生成提供商。
+  - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证 / API key。
+  - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
+- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）两种形式。
  - 用于 `pdf` 工具的模型路由。
-  - 如果省略，PDF 工具会回退到 `imageModel`，然后回退到已解析的会话 / 默认模型。
- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
+  - 如果省略，PDF 工具会回退到 `imageModel`，然后再回退到解析后的会话 / 默认模型。
+- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb`，`pdf` 工具使用的默认 PDF 大小上限。
 - `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。
- `verboseDefault`：智能体的默认详细级别。值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
- `elevatedDefault`：智能体的默认增强输出级别。值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
- `model.primary`：格式为 `provider/model`（例如，使用 API key 访问时为 `openai/gpt-5.4`，或使用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试对该精确模型 id 的唯一已配置 provider 匹配，最后才回退到已配置的默认 provider（这是已弃用的兼容行为，因此建议优先使用明确的 `provider/model`）。如果该 provider 不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / model，而不是暴露一个过时且已移除 provider 的默认值。
- `models`：`/model` 使用的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（provider 特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body` / `extraBody`）。
-  - 安全编辑：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝执行会删除现有允许列表条目的替换操作。
-  - 按 provider 作用域的 configure / onboarding 流程会把选中的 provider 模型合并到此映射中，并保留已经配置的无关 provider。
-  - 对于直接使用的 OpenAI Responses 模型，会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。请参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
+- `verboseDefault`：智能体的默认详细输出级别。可选值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
+- `elevatedDefault`：智能体的默认增强输出级别。可选值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
+- `model.primary`：格式为 `provider/model`（例如，使用 API key 访问时为 `openai/gpt-5.4`，或使用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果你省略 provider，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置 provider，最后才回退到已配置的默认 provider（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该 provider 不再提供已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider / model，而不是暴露一个过期且已移除 provider 的默认值。
+- `models`：为 `/model` 配置的模型目录和允许列表。每个条目都可以包含 `alias`（快捷名称）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body` / `extraBody`）。
+  - 安全编辑：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝可能删除现有允许列表条目的替换操作。
+  - 按 provider 作用域的配置 / 新手引导流程会把所选 provider 模型合并到该映射中，并保留已配置的其他无关 provider。
+  - 对于直接使用的 OpenAI Responses 模型，服务端压缩会自动启用。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
 - `params`：应用到所有模型的全局默认 provider 参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 id）再按键覆盖。详见 [提示词缓存](/zh-CN/reference/prompt-caching)。
- `params.extra_body` / `params.extraBody`：高级透传 JSON，会合并进用于 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，则以额外请求体为准；非原生 completions 路由之后仍会剥离 OpenAI 专用的 `store`。
- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。未指定运行时时，默认为 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册插件 harness 认领受支持的模型，或使用某个已注册 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动 PI 回退。显式插件运行时（如 `codex`）默认会以失败关闭，除非你在同一覆盖作用域中设置 `fallback: "pi"`。请将模型引用保持为标准的 `provider/model`；通过运行时配置来选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧式的运行时 provider 前缀。关于它与 provider / model 选择有何不同，请参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退 add / remove 命令）会保存为标准对象形式，并尽可能保留现有的回退列表。
- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍然串行）。默认值：4。
+- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配智能体 id）再按键覆盖。详情参见 [提示缓存](/zh-CN/reference/prompt-caching)。
+- `params.extra_body` / `params.extraBody`：高级透传 JSON，会合并进 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，额外请求体优先；非原生 completions 路由之后仍会剥离 OpenAI 专用的 `store`。
+- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。未指定 runtime 时，默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册的插件 harness 认领其支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。显式插件运行时（例如 `codex`）默认是失败即关闭，除非你在相同覆盖作用域中设置 `fallback: "pi"`。保持模型引用使用标准形式 `provider/model`；通过运行时配置而不是旧版运行时 provider 前缀来选择 Codex、Claude CLI、Gemini CLI 和其他执行后端。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 了解它与 provider / model 选择的区别。
+- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退 add / remove 命令）会保存为标准对象形式，并尽可能保留现有回退列表。
+- `maxConcurrent`：跨会话并行运行的最大智能体数量（每个会话内部仍然串行）。默认值：4。

 ### `agents.defaults.embeddedHarness`

-`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。
-大多数部署都应保持默认的 OpenClaw Pi 运行时。
-当某个受信任的插件提供原生 harness 时使用它，例如内置的
-Codex 应用服务器 harness。关于其心智模型，请参见
+`embeddedHarness` 用于控制哪个底层执行器运行嵌入式智能体轮次。
+大多数部署应保持默认的 OpenClaw Pi 运行时。
+当受信任的插件提供原生 harness 时使用它，例如内置的
+Codex 应用服务器 harness。关于其概念模型，参见
 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。

 ```json5
@ -390,35 +389,35 @@ Codex 应用服务器 harness。关于其心智模型，请参见
 }
 ```

- `runtime`：`"auto"`、`"pi"` 或某个已注册的插件 harness id。内置的 Codex 插件注册的是 `codex`。
- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 下，若省略则默认回退为 `"pi"`，这样旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，若省略则默认回退为 `"none"`，这样缺少 harness 时会失败，而不是静默使用 PI。运行时覆盖不会从更广泛的作用域继承 fallback；如果你确实想要这种兼容性回退，请在显式运行时旁边一起设置 `fallback: "pi"`。已选中的插件 harness 失败总是会直接显示出来。
+- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册为 `codex`。
+- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，若省略 `fallback`，默认是 `"pi"`，这样旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，若省略 `fallback`，默认是 `"none"`，这样缺少 harness 时会失败，而不是静默使用 PI。运行时覆盖不会从更宽泛的作用域继承 fallback；当你明确需要该兼容回退时，请与显式 runtime 一起设置 `fallback: "pi"`。选中的插件 harness 一旦失败，总是会直接暴露错误。
 - 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会覆盖该进程的 fallback。
- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以显式设置 `embeddedHarness.fallback: "none"` 以提升可读性；对于显式插件运行时，这本就是默认值。
- 在第一次嵌入式运行之后，harness 选择会按 session id 固定。配置 / 环境变量的更改会影响新的或已重置的会话，不会影响现有 transcript。具有 transcript 历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会报告实际运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider / model 设置。
+- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。为了提升可读性，你也可以显式设置 `embeddedHarness.fallback: "none"`；这本就是显式插件运行时的默认值。
+- 在第一次嵌入式运行后，harness 选择会按 session id 固定。配置 / 环境变量更改只影响新的或已重置的会话，不影响现有转录。具有转录历史但没有记录固定信息的旧会话，会被视为固定到 PI。`/status` 会报告实际运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
+- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用它们各自的 provider / model 设置。

-**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）：
+**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时生效）：

-| 别名 | 模型 |
+| 别名                | 模型                                               |
 | ------------------- | -------------------------------------------------- |
-| `opus` | `anthropic/claude-opus-4-6` |
-| `sonnet` | `anthropic/claude-sonnet-4-6` |
-| `gpt` | `openai/gpt-5.4` 或已配置的 Codex OAuth GPT-5.5 |
-| `gpt-mini` | `openai/gpt-5.4-mini` |
-| `gpt-nano` | `openai/gpt-5.4-nano` |
-| `gemini` | `google/gemini-3.1-pro-preview` |
-| `gemini-flash` | `google/gemini-3-flash-preview` |
-| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
+| `opus`              | `anthropic/claude-opus-4-6`                        |
+| `sonnet`            | `anthropic/claude-sonnet-4-6`                      |
+| `gpt`               | `openai/gpt-5.4` 或已配置的 Codex OAuth GPT-5.5    |
+| `gpt-mini`          | `openai/gpt-5.4-mini`                              |
+| `gpt-nano`          | `openai/gpt-5.4-nano`                              |
+| `gemini`            | `google/gemini-3.1-pro-preview`                    |
+| `gemini-flash`      | `google/gemini-3-flash-preview`                    |
+| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview`             |

 你配置的别名始终优先于默认值。

 Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
 Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设置为 `false` 可禁用它。
-Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `adaptive` 思考。
+Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `adaptive` 思考模式。

 ### `agents.defaults.cliBackends`

-用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API provider 失败时，可作为备份方案。
+用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时，可作为备份。

 ```json5
 {
@ -446,13 +445,13 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 }
 ```

- CLI 后端以文本为主；工具始终被禁用。
- 当设置了 `sessionArg` 时支持会话。
- 当 `imageArg` 接受文件路径时，支持图片透传。
+- CLI 后端以文本为主；工具始终禁用。
+- 设置了 `sessionArg` 时支持会话。
+- 当 `imageArg` 接受文件路径时，支持图像透传。

 ### `agents.defaults.systemPromptOverride`

-用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别设置（`agents.defaults.systemPromptOverride`），也可按智能体设置（`agents.list[].systemPromptOverride`）。按智能体设置的值优先；空值或仅空白的值会被忽略。适用于受控的提示词实验。
+用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅包含空白的值会被忽略。适用于受控的提示实验。

 ```json5
 {
@ -466,7 +465,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada

 ### `agents.defaults.promptOverlays`

-按模型家族应用的、与 provider 无关的提示词叠加层。GPT-5 家族模型 id 会在各 provider 间接收共享的行为契约；`personality` 仅控制友好的交互风格层。
+按模型家族应用的、与 provider 无关的提示叠加层。GPT-5 家族模型 id 会跨 provider 接收共享的行为契约；`personality` 只控制友好的交互风格层。

 ```json5
 {
@ -483,7 +482,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 ```

 - `"friendly"`（默认）和 `"on"` 会启用友好的交互风格层。
- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍然启用。
+- `"off"` 只禁用友好层；带标签的 GPT-5 行为契约仍保持启用。
 - 当这个共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。

 ### `agents.defaults.heartbeat`
@ -515,14 +514,14 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 }
 ```

- `every`：时长字符串（ms / s / m / h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。
- `includeSystemPromptSection`：设为 false 时，会从系统提示词中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。
+- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 凭证）或 `1h`（OAuth 凭证）。设置为 `0m` 可禁用。
+- `includeSystemPromptSection`：设为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入到引导上下文中。默认值：`true`。
 - `suppressToolErrorWarnings`：设为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。
- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最长时间（秒）。留空则使用 `agents.defaults.timeoutSeconds`。
- `directPolicy`：direct / 私信投递策略。`allow`（默认）允许投递到直接目标。`block` 会阻止投递到直接目标，并发出 `reason=dm-blocked`。
- `lightContext`：设为 true 时，Heartbeat 运行使用轻量引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。
- `isolatedSession`：设为 true 时，每次 Heartbeat 都在一个全新的会话中运行，不带任何先前的对话历史。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降低到约 2–5K token。
- 按智能体设置：使用 `agents.list[].heartbeat`。当任何智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。
+- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最大秒数。若不设置，则使用 `agents.defaults.timeoutSeconds`。
+- `directPolicy`：直接 / 私信投递策略。`allow`（默认）允许直接目标投递。`block` 会阻止直接目标投递，并发出 `reason=dm-blocked`。
+- `lightContext`：设为 true 时，Heartbeat 运行会使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。
+- `isolatedSession`：设为 true 时，每次 Heartbeat 都会在一个全新会话中运行，不带任何先前的对话历史。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。每次 Heartbeat 的 token 成本可从约 100K 降至约 2–5K。
+- 按智能体设置：使用 `agents.list[].heartbeat`。如果任意智能体定义了 `heartbeat`，**则只有这些智能体** 会运行 Heartbeat。
 - Heartbeat 会运行完整的智能体轮次——间隔越短，消耗的 token 越多。

 ### `agents.defaults.compaction`
@ -555,21 +554,21 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 }
 ```

- `mode`：`default` 或 `safeguard`（针对长历史记录的分块摘要）。请参见 [Compaction](/zh-CN/concepts/compaction)。
- `provider`：已注册 compaction provider 插件的 id。设置后，将调用该 provider 的 `summarize()`，而不是使用内置 LLM 摘要。在失败时会回退到内置实现。设置 provider 会强制使用 `mode: "safeguard"`。请参见 [Compaction](/zh-CN/concepts/compaction)。
- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。
- `keepRecentTokens`：Pi 切分点预算，用于将最近的 transcript 尾部原样保留。手动 `/compact` 会在显式设置时遵守此值；否则手动 compaction 是一个硬检查点。
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要时预置内置的不透明标识符保留指导。
- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。
- `qualityGuard`：针对 safeguard 摘要的输出格式错误重试检查。在 safeguard 模式下默认启用；设为 `enabled: false` 可跳过审计。
- `postCompactionSections`：可选的 `AGENTS.md` H2 / H3 章节名称，在 compaction 后重新注入。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置，或显式设置为该默认对时，也会接受旧版 `Every Session` / `Safety` 标题作为兼容性回退。
- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当主会话应保持使用某个模型，而 compaction 摘要应使用另一个模型时，请使用此项；未设置时，compaction 使用会话的主模型。
- `notifyUser`：设为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认禁用，以保持 compaction 静默。
- `memoryFlush`：在自动 compaction 前执行的静默智能体轮次，用于存储持久记忆。当工作区为只读时会跳过。
+- `mode`：`default` 或 `safeguard`（针对长历史记录的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
+- `provider`：已注册压缩 provider 插件的 id。设置后，会调用该 provider 的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置 provider 会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
+- `timeoutSeconds`：OpenClaw 中止一次压缩操作前允许的最大秒数。默认值：`900`。
+- `keepRecentTokens`：Pi 切分点预算，用于把最近的转录尾部按原文保留。手动 `/compact` 在显式设置时会遵循此值；否则手动压缩就是一个硬检查点。
+- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在压缩摘要时预先添加内置的不透明标识符保留指导。
+- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的自定义标识符保留文本。
+- `qualityGuard`：对 safeguard 摘要执行输出格式错误后的重试检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。
+- `postCompactionSections`：压缩后要重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。当未设置，或显式设置为该默认对时，也会接受旧版的 `Every Session` / `Safety` 标题作为兼容回退。
+- `model`：仅用于压缩摘要的可选 `provider/model-id` 覆盖。若你希望主会话保持使用某个模型，而压缩摘要使用另一个模型，就用它；若未设置，压缩会使用会话的主模型。
+- `notifyUser`：设为 `true` 时，会在压缩开始和完成时向用户发送简短通知（例如，“正在压缩上下文...” 和 “上下文压缩完成”）。默认关闭，以保持压缩静默进行。
+- `memoryFlush`：在自动压缩前执行一次静默的智能体轮次，以存储持久记忆。当工作区为只读时会跳过。

 ### `agents.defaults.contextPruning`

-在发送给 LLM 之前，从内存中的上下文里裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。
+在把内容发送给 LLM 之前，从内存上下文中修剪 **旧的工具结果**。**不会** 修改磁盘上的会话历史。

 ```json5
 {
@ -591,25 +590,25 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 }
 ```

-<Accordion title="cache-ttl 模式行为">
+<Accordion title="`cache-ttl` 模式行为">

- `mode: "cache-ttl"` 会启用裁剪流程。
- `ttl` 控制距离上次缓存触碰后，多久才允许再次运行裁剪。
- 裁剪会先对过大的工具结果执行软裁剪，如仍有需要，再对更旧的工具结果执行硬清除。
+- `mode: "cache-ttl"` 会启用修剪流程。
+- `ttl` 控制何时可以再次运行修剪（在上次缓存触碰之后）。
+- 修剪会先对过大的工具结果执行软修剪；如仍有需要，再对更旧的工具结果执行硬清除。

-**软裁剪**会保留开头 + 结尾，并在中间插入 `...`。
+**软修剪** 会保留开头和结尾，并在中间插入 `...`。

-**硬清除**会用占位符替换整个工具结果。
+**硬清除** 会用占位符替换整个工具结果。

 说明：

- 图片块永远不会被裁剪 / 清除。
- 比例按字符计算（近似值），不是精确的 token 数。
- 如果 assistant 消息少于 `keepLastAssistants` 条，则跳过裁剪。
+- 图像块永远不会被修剪 / 清除。
+- 比例基于字符数（近似值），而不是精确 token 数。
+- 如果助手消息少于 `keepLastAssistants` 条，则会跳过修剪。

 </Accordion>

-行为细节请参见 [会话裁剪](/zh-CN/concepts/session-pruning)。
+行为详情参见 [会话修剪](/zh-CN/concepts/session-pruning)。

 ### 分块流式传输

@ -628,12 +627,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 ```

 - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账户的变体）。Signal / Slack / Discord / Google Chat 默认使用 `minChars: 1500`。
- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。
+- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账号的变体）。Signal / Slack / Discord / Google Chat 默认使用 `minChars: 1500`。
+- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。

-行为和分块细节请参见 [流式传输](/zh-CN/concepts/streaming)。
+行为和分块细节参见 [流式传输](/zh-CN/concepts/streaming)。

-### 输入中指示器
+### 正在输入指示器

 ```json5
 {
@ -646,16 +645,16 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 }
 ```

- 默认值：对于直接聊天 / 提及使用 `instant`，对于未被提及的群聊使用 `message`。
+- 默认值：直接聊天 / 提及时使用 `instant`，未被提及的群聊使用 `message`。
 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。

-请参见 [输入中指示器](/zh-CN/concepts/typing-indicators)。
+参见 [正在输入指示器](/zh-CN/concepts/typing-indicators)。

 <a id="agentsdefaultssandbox"></a>

 ### `agents.defaults.sandbox`

-嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
+嵌入式智能体的可选沙箱隔离。完整指南参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。

 ```json5
 {
@ -755,39 +754,39 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 **后端：**

 - `docker`：本地 Docker 运行时（默认）
- `ssh`：通用 SSH 支持的远程运行时
+- `ssh`：通用的基于 SSH 的远程运行时
 - `openshell`：OpenShell 运行时

-当选择 `backend: "openshell"` 时，运行时特定设置会移动到
+当选择 `backend: "openshell"` 时，运行时专用设置会移至
 `plugins.entries.openshell.config`。

 **SSH 后端配置：**

 - `target`：`user@host[:port]` 形式的 SSH 目标
- `command`：SSH 客户端命令（默认：`ssh`）
- `workspaceRoot`：用于按作用域工作区的远程绝对根目录
+- `command`：SSH 客户端命令（默认值：`ssh`）
+- `workspaceRoot`：用于按作用域划分工作区的远程绝对根目录
 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件
+- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其物化为临时文件
 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关

-**SSH 认证优先级：**
+**SSH 凭证优先级：**

 - `identityData` 优先于 `identityFile`
 - `certificateData` 优先于 `certificateFile`
 - `knownHostsData` 优先于 `knownHostsFile`
- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前活跃的 secrets 运行时快照中解析
+- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前活动的 secrets 运行时快照中解析

 **SSH 后端行为：**

- 在创建或重建后，会先为远程工作区执行一次初始化
- 随后保持远程 SSH 工作区为标准副本
+- 在创建或重建后，对远程工作区执行一次初始化
+- 然后保持远程 SSH 工作区为标准状态
 - 通过 SSH 路由 `exec`、文件工具和媒体路径
- 不会自动将远程更改同步回主机
+- 不会自动把远程更改同步回主机
 - 不支持沙箱浏览器容器

 **工作区访问：**

- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区
+- `none`：每个作用域的沙箱工作区位于 `~/.openclaw/sandboxes` 下
 - `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent`
 - `rw`：智能体工作区以读写方式挂载到 `/workspace`

@ -825,29 +824,29 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada

 **OpenShell 模式：**

- `mirror`：在执行前将本地内容初始化到远程，执行后再同步回本地；本地工作区保持为标准副本
- `remote`：在创建沙箱时仅初始化一次远程内容，随后保持远程工作区为标准副本
+- `mirror`：在执行前把本地内容初始化到远程，执行后再同步回本地；本地工作区保持为标准状态
+- `remote`：在创建沙箱时只对远程执行一次初始化，之后保持远程工作区为标准状态

-在 `remote` 模式下，初始化之后，在 OpenClaw 外部于主机本地进行的编辑不会自动同步进沙箱。
-传输通过 SSH 进入 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。
+在 `remote` 模式下，于 OpenClaw 之外在主机本地进行的编辑，在初始化步骤之后不会自动同步到沙箱中。
+传输方式是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。

 **`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。

-**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设为 `"bridge"`（或自定义 bridge 网络）。
-`"host"` 被阻止。默认也会阻止 `"container:<id>"`，除非你显式设置
-`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急破窗选项）。
+**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。
+`"host"` 会被阻止。`"container:<id>"` 默认也会被阻止，除非你显式设置
+`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急放行）。

-**入站附件** 会暂存到当前工作区中的 `media/inbound/*`。
+**入站附件** 会被暂存到活动工作区中的 `media/inbound/*`。

-**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。
+**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。

-**沙箱浏览器**（`sandbox.browser.enabled`）：容器中的 Chromium + CDP。noVNC URL 会注入到系统提示词中。不需要在 `openclaw.json` 中启用 `browser.enabled`。
-默认情况下，noVNC 观察者访问使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。
+**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。
+noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短期有效的 token URL（而不是在共享 URL 中暴露密码）。

- `allowHostControl: false`（默认）会阻止沙箱会话以主机浏览器为目标。
- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连通性时，才设置为 `bridge`。
- `cdpSourceRange` 可选地在容器边界将 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
+- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。
+- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连通性时才设置为 `bridge`。
+- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。
+- `sandbox.browser.binds` 仅会把额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
 - 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优：
  - `--remote-debugging-address=127.0.0.1`
  - `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
@ -865,14 +864,17 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
  - `--renderer-process-limit=2`
  - `--no-zygote`
  - `--metrics-recording-only`
-  - `--disable-extensions`（默认启用）
-  - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu` 默认启用；如果 WebGL / 3D 使用场景需要，可通过
-    `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。
-  - 如果你的工作流依赖扩展，可通过 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。
+  - 默认启用 `--disable-extensions`
+  - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
+    默认启用；如果 WebGL / 3D 使用场景需要，可通过
+    `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用它们。
+  - 如果你的工作流依赖扩展，`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 会重新启用扩展。
  - `--renderer-process-limit=2` 可通过
-    `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 修改；设为 `0` 可使用 Chromium 的默认进程限制。
-  - 当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。
-  - 这些默认值是容器镜像的基线；如果你想更改容器默认值，请使用带有自定义入口点的自定义浏览器镜像。
+    `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 更改；设置为 `0` 会使用 Chromium 的
+    默认进程限制。
+  - 另外，当启用 `noSandbox` 时，还会加上 `--no-sandbox` 和 `--disable-setuid-sandbox`。
+  - 这些默认值是容器镜像基线；如需更改容器默认行为，请使用自定义浏览器镜像和自定义
+    入口点。

 </Accordion>

@ -881,8 +883,8 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 构建镜像：

 ```bash
-scripts/sandbox-setup.sh           # main sandbox image
-scripts/sandbox-browser-setup.sh   # optional browser image
+scripts/sandbox-setup.sh           # 主沙箱镜像
+scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 ```

 ### `agents.list`（按智能体覆盖）
@ -934,27 +936,27 @@ scripts/sandbox-browser-setup.sh   # optional browser image
 }
 ```

- `id`：稳定的智能体 id（必填）。
- `default`：如果设置了多个，则第一个生效（会记录警告）。如果一个都未设置，则列表中的第一个条目为默认值。
- `model`：字符串形式仅覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 可禁用全局回退）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。
- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。用于智能体特定覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。
- `skills`：可选的按智能体 Skills 允许列表。如果省略，则在 `agents.defaults.skills` 已设置时继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。
- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选的 provider / 模型配置文件控制哪些值有效；对于 Google Gemini，`adaptive` 会保留 provider 自有的动态思考（在 Gemini 3 / 3.1 上省略 `thinkingLevel`，在 Gemini 2.5 上使用 `thinkingBudget: -1`）。
- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。当未设置按消息或按会话的 reasoning 覆盖时生效。
- `fastModeDefault`：可选的按智能体 fast mode 默认值（`true | false`）。当未设置按消息或按会话的 fast-mode 覆盖时生效。
- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某个智能体仅使用 Codex，而其他智能体在 `auto` 模式下继续使用默认的 PI 回退。
- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 并设置 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
+- `id`：稳定的智能体 id（必需）。
+- `default`：若设置了多个，首个生效（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。
+- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 会禁用全局回退）。仅覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。
+- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。可用于像 `cacheRetention`、`temperature` 或 `maxTokens` 这样的智能体特定覆盖，而不必复制整个模型目录。
+- `skills`：可选的按智能体 Skills 允许列表。如果省略，智能体会在设置了 `agents.defaults.skills` 时继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。
+- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或按会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选 provider / model 配置决定哪些值有效；对于 Google Gemini，`adaptive` 会保持 provider 自有的动态思考（在 Gemini 3 / 3.1 上省略 `thinkingLevel`，在 Gemini 2.5 上使用 `thinkingBudget: -1`）。
+- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。当未设置按消息或按会话推理覆盖时生效。
+- `fastModeDefault`：可选的按智能体快速模式默认值（`true | false`）。当未设置按消息或按会话快速模式覆盖时生效。
+- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某个智能体仅使用 Codex，而其他智能体继续使用默认的 `auto` 模式 PI 回退。
+- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
 - `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。
 - `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name` / `emoji`。
- `subagents.allowAgents`：`sessions_spawn` 可用的智能体 id 允许列表（`["*"]` = 任意；默认：仅限相同智能体）。
- 沙箱继承保护：如果请求者会话处于沙箱中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。
- `subagents.requireAgentId`：设为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。
+- `subagents.allowAgents`：`sessions_spawn` 允许的智能体 id 列表（`["*"]` = 任意；默认：仅同一智能体）。
+- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些将以非沙箱方式运行的目标。
+- `subagents.requireAgentId`：设为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认值：false）。

 ---

 ## 多智能体路由

-在一个 Gateway 网关中运行多个隔离的智能体。请参见 [多智能体](/zh-CN/concepts/multi-agent)。
+在一个 Gateway 网关中运行多个彼此隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。

 ```json5
 {
@ -973,11 +975,11 @@ scripts/sandbox-browser-setup.sh   # optional browser image

 ### 绑定匹配字段

- `type`（可选）：正常路由使用 `route`（缺失时默认为 route），持久 ACP 对话绑定使用 `acp`
- `match.channel`（必填）
- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户）
+- `type`（可选）：普通路由使用 `route`（未指定时默认即为 route），持久 ACP 对话绑定使用 `acp`。
+- `match.channel`（必需）
+- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号）
 - `match.peer`（可选；`{ kind: direct|group|channel, id }`）
- `match.guildId` / `match.teamId`（可选；渠道特定）
+- `match.guildId` / `match.teamId`（可选；特定渠道）
 - `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }`

 **确定性的匹配顺序：**
@ -986,14 +988,14 @@ scripts/sandbox-browser-setup.sh   # optional browser image
 2. `match.guildId`
 3. `match.teamId`
 4. `match.accountId`（精确匹配，无 peer / guild / team）
-5. `match.accountId: "*"`（渠道范围）
+5. `match.accountId: "*"`（整个渠道）
 6. 默认智能体

-在每一层级内，首个匹配的 `bindings` 条目获胜。
+在每一层内，首个匹配的 `bindings` 条目胜出。

-对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + account + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。
+对于 `type: "acp"` 条目，OpenClaw 会按精确会话标识（`match.channel` + account + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。

-### 按智能体访问配置
+### 按智能体划分的访问配置

 <Accordion title="完全访问（无沙箱）">

@ -1042,7 +1044,7 @@ scripts/sandbox-browser-setup.sh   # optional browser image

 </Accordion>

-<Accordion title="无文件系统访问（仅消息传递）">
+<Accordion title="无文件系统访问（仅消息）">

 ```json5
 {
@ -1088,7 +1090,7 @@ scripts/sandbox-browser-setup.sh   # optional browser image

 </Accordion>

-优先级细节请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。
+有关优先级细节，参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。

 ---

@ -1142,34 +1144,34 @@ scripts/sandbox-browser-setup.sh   # optional browser image
 <Accordion title="会话字段详情">

 - **`scope`**：群聊上下文的基础会话分组策略。
-  - `per-sender`（默认）：在一个渠道上下文内，每个发送者都有独立的会话。
-  - `global`：一个渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。
+  - `per-sender`（默认）：在某个渠道上下文中，每个发送者都有独立的隔离会话。
+  - `global`：某个渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。
 - **`dmScope`**：私信的分组方式。
  - `main`：所有私信共享主会话。
-  - `per-peer`：按跨渠道的发送者 id 隔离。
+  - `per-peer`：按发送者 id 跨渠道隔离。
  - `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
-  - `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户）。
- **`identityLinks`**：将标准 id 映射到带 provider 前缀的 peer，用于跨渠道共享会话。
- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。如果两者都已配置，则以先到期者为准。
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。
- **`parentForkMaxTokens`**：创建分叉线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。
-  - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个全新的线程会话，而不是继承父 transcript 历史。
-  - 设为 `0` 可禁用此保护，并始终允许从父会话分叉。
- **`mainKey`**：旧版字段。运行时始终对主直接聊天桶使用 `"main"`。
- **`agentToAgent.maxPingPongTurns`**：智能体到智能体交换期间，代理之间最大来回回复轮数（整数，范围：`0`–`5`）。`0` 会禁用这种来回链式交互。
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一条 deny 优先生效。
+  - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号场景）。
+- **`identityLinks`**：将规范 id 映射到带 provider 前缀的 peer，用于跨渠道共享会话。
+- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在空闲 `idleMinutes` 后重置。如果两者都配置，先到期者生效。
+- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍可作为 `direct` 的别名。
+- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话最大 `totalTokens`（默认 `100000`）。
+  - 如果父会话的 `totalTokens` 超过该值，OpenClaw 会启动一个新的线程会话，而不是继承父级转录历史。
+  - 设置为 `0` 可禁用此保护，并始终允许父级分叉。
+- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。
+- **`agentToAgent.maxPingPongTurns`**：在智能体到智能体交互期间，智能体之间允许的最大往返回复轮数（整数，范围：`0`–`5`）。`0` 会禁用 ping-pong 链式交互。
+- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。首个 deny 规则胜出。
 - **`maintenance`**：会话存储清理 + 保留控制。
-  - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。
-  - `pruneAfter`：陈旧条目的时间截止值（默认 `30d`）。
-  - `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。
-  - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮转（默认 `10mb`）。
-  - `resetArchiveRetention`：`*.reset.<timestamp>` transcript 归档的保留期。默认与 `pruneAfter` 相同；设为 `false` 可禁用。
-  - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的工件 / 会话。
+  - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。
+  - `pruneAfter`：过期条目的时间阈值（默认 `30d`）。
+  - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。
+  - `rotateBytes`：当 `sessions.json` 超过此大小时轮转（默认 `10mb`）。
+  - `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留时长。默认与 `pruneAfter` 相同；设置为 `false` 可禁用。
+  - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下记录警告；在 `enforce` 模式下会优先删除最旧的产物 / 会话。
  - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。
 - **`threadBindings`**：线程绑定会话功能的全局默认值。
  - `enabled`：主默认开关（provider 可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
-  - `idleHours`：默认的无活动自动取消聚焦时长（小时）（`0` 禁用；provider 可覆盖）
-  - `maxAgeHours`：默认的硬性最大存活时长（小时）（`0` 禁用；provider 可覆盖）
+  - `idleHours`：默认的按空闲时间自动取消聚焦小时数（`0` 为禁用；provider 可覆盖）
+  - `maxAgeHours`：默认的硬最大存在时长小时数（`0` 为禁用；provider 可覆盖）

 </Accordion>

@ -1207,36 +1209,36 @@ scripts/sandbox-browser-setup.sh   # optional browser image

 ### 响应前缀

-按渠道 / 账户覆盖：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
+按渠道 / 账号覆盖：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。

-解析顺序（最具体者优先）：账户 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。
+解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。

 **模板变量：**

-| 变量 | 描述 | 示例 |
+| 变量 | 说明 | 示例 |
 | ----------------- | ---------------------- | --------------------------- |
-| `{model}` | 短模型名 | `claude-opus-4-6` |
+| `{model}` | 模型短名称 | `claude-opus-4-6` |
 | `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
-| `{provider}` | provider 名称 | `anthropic` |
-| `{thinkingLevel}` | 当前思考级别 | `high`, `low`, `off` |
+| `{provider}` | 提供商名称 | `anthropic` |
+| `{thinkingLevel}` | 当前思考级别 | `high`、`low`、`off` |
 | `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |

 变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。

 ### 确认反应

- 默认使用当前智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。
+- 默认为活动智能体的 `identity.emoji`，否则为 `"👀"`。设置为 `""` 可禁用。
 - 按渠道覆盖：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
- 解析顺序：账户 → 渠道 → `messages.ackReaction` → identity 回退值。
- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。
- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，回复后移除确认反应。
+- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。
+- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。
+- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除确认反应。
 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 反应。
-  在 Slack 和 Discord 上，未设置时，如果确认反应处于启用状态，则保持 Status 反应启用。
-  在 Telegram 上，需要显式设为 `true` 才会启用生命周期 Status 反应。
+  在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则保持 Status 反应启用。
+  在 Telegram 上，必须显式设置为 `true` 才会启用生命周期 Status 反应。

-### 入站防抖
+### 入站去抖

-将来自同一发送者的快速纯文本消息批处理为一个智能体轮次。媒体 / 附件会立即刷新。控制命令会绕过防抖。
+将来自同一发送者的快速连续纯文本消息批处理为一次智能体轮次。媒体 / 附件会立即刷新。控制命令会绕过去抖。

 ### TTS（文本转语音）

@ -1286,19 +1288,19 @@ scripts/sandbox-browser-setup.sh   # optional browser image
 }
 ```

- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好设置，`/tts status` 会显示实际状态。
- `summaryModel` 会覆盖自动摘要所使用的 `agents.defaults.model.primary`。
+- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示实际状态。
+- `summaryModel` 会为自动摘要覆盖 `agents.defaults.model.primary`。
 - `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需主动启用）。
 - API key 会回退到 `ELEVENLABS_API_KEY` / `XI_API_KEY` 和 `OPENAI_API_KEY`。
- 内置语音 provider 由插件拥有。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS provider 插件，例如用于 Edge TTS 的 `microsoft`。旧版 provider id `edge` 可作为 `microsoft` 的别名使用。
- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序是配置，然后 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。
- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型 / 声音校验。
+- 内置语音提供商由插件负责。如果设置了 `plugins.allow`，请包含你要使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 provider id `edge` 仍可作为 `microsoft` 的别名使用。
+- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置，然后 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。
+- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型 / 语音校验。

 ---

-## talk
+## Talk

-Talk 模式的默认设置（macOS / iOS / Android）。
+Talk 模式的默认值（macOS / iOS / Android）。

 ```json5
 {
@ -1315,6 +1317,10 @@ Talk 模式的默认设置（macOS / iOS / Android）。
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
+      mlx: {
+        modelId: "mlx-community/Soprano-80M-bf16",
+      },
+      system: {},
    },
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
@ -1322,13 +1328,15 @@ Talk 模式的默认设置（macOS / iOS / Android）。
 }
 ```

- `talk.provider` 在配置了多个 Talk provider 时，必须与 `talk.providers` 中的某个键匹配。
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅为兼容用途，并会自动迁移到 `talk.providers.<provider>`。
- Voice ID 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
+- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。
+- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，并会自动迁移到 `talk.providers.<provider>` 中。
+- 语音 id 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
- 仅在未配置 Talk API key 时，才会应用 `ELEVENLABS_API_KEY` 回退。
+- 只有在未配置 Talk API key 时，才会使用 `ELEVENLABS_API_KEY` 回退。
 - `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。
- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多久才发送 transcript。未设置时，会保留平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
+- `providers.mlx.modelId` 用于选择 macOS 本地 MLX helper 所使用的 Hugging Face 仓库。如果省略，macOS 会使用 `mlx-community/Soprano-80M-bf16`。
+- macOS MLX 播放会在存在时通过内置的 `openclaw-mlx-tts` helper 运行，否则使用 `PATH` 上的可执行文件；开发时可通过 `OPENCLAW_MLX_TTS_BIN` 覆盖 helper 路径。
+- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间再发送转录。未设置时会保持平台默认暂停窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。

 ---

--- a/docs/zh-CN/gateway/configuration-reference.md
+++ b/docs/zh-CN/gateway/configuration-reference.md
@ -2,52 +2,52 @@
 read_when:
    - 你需要精确到字段级别的配置语义或默认值
    - 你正在验证渠道、模型、Gateway 网关或工具配置块
-summary: Gateway 网关配置参考，涵盖核心 OpenClaw 键名、默认值以及指向专用子系统参考文档的链接
+summary: Gateway 网关 配置参考，涵盖核心 OpenClaw 键名、默认值，以及指向各专用子系统参考文档的链接
 title: 配置参考
 x-i18n:
-    generated_at: "2026-04-25T07:01:14Z"
+    generated_at: "2026-04-25T07:51:42Z"
    model: gpt-5.4
    provider: openai
-    source_hash: a0f69861c754e0f6d3e41ac357fa56612b90da69249c6f24ec9f6ade21acc1d3
+    source_hash: fd4ebfce263df22d2daa8e0a01e8ab7f590f86b424c534a85d39a25cee98e053
    source_path: gateway/configuration-reference.md
    workflow: 15
 ---

 `~/.openclaw/openclaw.json` 的核心配置参考。若需面向任务的概览，请参阅 [配置](/zh-CN/gateway/configuration)。

-本页涵盖 OpenClaw 的主要配置面，并在某个子系统拥有更深入的独立参考时提供跳转链接。由渠道和插件自行维护的命令目录，以及更底层的 memory / QMD 调节项，位于各自的页面，而不在本页中说明。
+本页涵盖 OpenClaw 的主要配置面，并在某个子系统有自己更深入的参考文档时提供外链。由渠道和插件自行维护的命令目录，以及深入的内存/QMD 调节项，分别位于各自页面，而不是集中放在本页。

-代码事实来源：
+代码层面的真实来源：

- `openclaw config schema` 会输出用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置 / 插件 / 渠道元数据
- `config.schema.lookup` 会返回一个按路径限定范围的 schema 节点，供下钻工具使用
- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 表面校验配置文档基线哈希
+- `openclaw config schema` 会打印用于验证和 Control UI 的实时 JSON Schema，并在可用时合并内置/插件/渠道元数据
+- `config.schema.lookup` 会返回一个按路径划分的 schema 节点，供下钻工具使用
+- `pnpm config:docs:check` / `pnpm config:docs:gen` 会根据当前 schema 面，校验配置文档基线哈希值

-专门的深度参考：
+专门的深入参考文档：

 - [内存配置参考](/zh-CN/reference/memory-config)，适用于 `agents.defaults.memorySearch.*`、`memory.qmd.*`、`memory.citations`，以及位于 `plugins.entries.memory-core.config.dreaming` 下的 dreaming 配置
- [斜杠命令](/zh-CN/tools/slash-commands)，用于查看当前内置 + 随附的命令目录
- 各自所属的渠道 / 插件页面，用于查看特定渠道的命令面
+- [斜杠命令](/zh-CN/tools/slash-commands)，适用于当前内置 + 内置打包的命令目录
+- 各自所属的渠道/插件页面，适用于渠道特定的命令面

-配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段都是可选的——省略时，OpenClaw 会使用安全的默认值。
+配置格式为 **JSON5**（允许注释和尾随逗号）。所有字段均为可选——省略时，OpenClaw 会使用安全的默认值。

 ---

 ## 渠道

-每个渠道的配置键已移至专门页面——请参阅
-[配置 — 渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`，
-其中包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage，以及其他
+各渠道配置键已迁移到专门页面——请参阅
+[配置——渠道](/zh-CN/gateway/config-channels)，了解 `channels.*`，
+包括 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 及其他
 内置渠道（认证、访问控制、多账号、提及门控）。

 ## 智能体默认值、多智能体、会话和消息

-已移至专门页面——请参阅
-[配置 — 智能体](/zh-CN/gateway/config-agents)，了解：
+已迁移到专门页面——请参阅
+[配置——智能体](/zh-CN/gateway/config-agents)，内容包括：

 - `agents.defaults.*`（工作区、模型、思考、心跳、内存、媒体、Skills、沙箱）
 - `multiAgent.*`（多智能体路由和绑定）
- `session.*`（会话生命周期、压缩、清理）
+- `session.*`（会话生命周期、压缩、修剪）
 - `messages.*`（消息投递、TTS、Markdown 渲染）
 - `talk.*`（Talk 模式）
  - `talk.silenceTimeoutMs`：未设置时，Talk 会在发送转录内容前保留平台默认的停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）
@ -55,15 +55,15 @@ x-i18n:
 ## 工具和自定义提供商

 工具策略、实验性开关、由提供商支持的工具配置，以及自定义
-提供商 / base-URL 设置已移至专门页面——请参阅
-[配置 — 工具和自定义提供商](/zh-CN/gateway/config-tools)。
+提供商 / base-URL 设置，已迁移到专门页面——请参阅
+[配置——工具和自定义提供商](/zh-CN/gateway/config-tools)。

 ## MCP

 由 OpenClaw 管理的 MCP 服务器定义位于 `mcp.servers` 下，
-由嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、
-`show`、`set` 和 `unset` 命令可管理该配置块，且在编辑配置时不会连接到
-目标服务器。
+供嵌入式 Pi 和其他运行时适配器使用。`openclaw mcp list`、
+`show`、`set` 和 `unset` 命令可在编辑配置时管理该配置块，
+且不会连接目标服务器。

 ```json5
 {
@ -87,12 +87,15 @@ x-i18n:
 }
 ```

- `mcp.servers`：为暴露已配置 MCP 工具的运行时定义具名 stdio 或远程 MCP 服务器。
- `mcp.sessionIdleTtlMs`：用于会话作用域内置 MCP 运行时的空闲 TTL。
-  一次性嵌入式运行会请求在运行结束时清理；该 TTL 是面向
+- `mcp.servers`：为暴露已配置 MCP 工具的运行时提供命名的 stdio 或远程 MCP 服务器定义。
+- `mcp.sessionIdleTtlMs`：面向会话作用域的内置 MCP 运行时的空闲 TTL。
+  一次性嵌入式运行会请求在运行结束时清理；该 TTL 是
  长生命周期会话和未来调用方的兜底机制。
+- `mcp.*` 下的变更会通过释放缓存的会话 MCP 运行时来热应用。
+  下一次工具发现/使用时会根据新配置重新创建它们，因此已移除的
+  `mcp.servers` 条目会立即被回收，而不是等到空闲 TTL 到期。

-运行时行为请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和
+有关运行时行为，请参阅 [MCP](/zh-CN/cli/mcp#openclaw-as-an-mcp-client-registry) 和
 [CLI 后端](/zh-CN/gateway/cli-backends#bundle-mcp-overlays)。

 ## Skills
@ -120,13 +123,14 @@ x-i18n:
 }
 ```

- `allowBundled`：仅适用于内置 Skills 的可选允许列表（不影响托管 / 工作区 Skills）。
- `load.extraDirs`：额外的共享 Skills 根目录（优先级最低）。
- `install.preferBrew`：为 `true` 时，若 `brew` 可用，则优先使用 Homebrew 安装器，然后再回退到其他安装器类型。
+- `allowBundled`：仅适用于内置 Skills 的可选允许列表（托管/工作区 Skills 不受影响）。
+- `load.extraDirs`：额外的共享 Skill 根目录（优先级最低）。
+- `install.preferBrew`：当为 true 且存在 `brew` 时，优先使用 Homebrew 安装器，
+  然后才回退到其他安装器类型。
 - `install.nodeManager`：用于 `metadata.openclaw.install`
  规范的 Node 安装器偏好（`npm` | `pnpm` | `yarn` | `bun`）。
- `entries.<skillKey>.enabled: false`：即使某个 skill 已内置 / 已安装，也会将其禁用。
- `entries.<skillKey>.apiKey`：为声明了主环境变量的 skill 提供的便捷配置（明文字符串或 SecretRef 对象）。
+- `entries.<skillKey>.enabled: false`：即使 Skill 已内置/安装，也会禁用该 Skill。
+- `entries.<skillKey>.apiKey`：为声明主环境变量的 Skill 提供的便捷字段（明文字符串或 SecretRef 对象）。

 ---

@ -156,40 +160,40 @@ x-i18n:

 - 从 `~/.openclaw/extensions`、`<workspace>/.openclaw/extensions` 以及 `plugins.load.paths` 加载。
 - 设备发现支持原生 OpenClaw 插件，以及兼容的 Codex bundle 和 Claude bundle，包括无 manifest 的 Claude 默认布局 bundle。
- **配置更改需要重启 Gateway 网关。**
- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先生效。
- `plugins.entries.<id>.apiKey`：插件级 API 密钥便捷字段（当插件支持时）。
+- **配置变更需要重启 Gateway 网关。**
+- `allow`：可选允许列表（仅加载列出的插件）。`deny` 优先。
+- `plugins.entries.<id>.apiKey`：插件级 API key 便捷字段（当插件支持时）。
 - `plugins.entries.<id>.env`：插件作用域的环境变量映射。
- `plugins.entries.<id>.hooks.allowPromptInjection`：为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持 bundle 提供的钩子目录。
- `plugins.entries.<id>.hooks.allowConversationAccess`：为 `true` 时，受信任的非内置插件可从 `llm_input`、`llm_output` 和 `agent_end` 等类型化钩子中读取原始对话内容。
- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任该插件，使其可为后台子智能体运行请求按次生效的 `provider` 和 `model` 覆盖。
- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖可使用的规范 `provider/model` 目标可选允许列表。仅在你明确希望允许任意模型时才使用 `"*"`。
- `plugins.entries.<id>.config`：插件定义的配置对象（在可用时由原生 OpenClaw 插件 schema 验证）。
- 渠道插件的账号 / 运行时设置位于 `channels.<id>` 下，应由所属插件 manifest 中的 `channelConfigs` 元数据描述，而不是由中心化的 OpenClaw 选项注册表描述。
- `plugins.entries.firecrawl.config.webFetch`：Firecrawl 网页抓取提供商设置。
-  - `apiKey`：Firecrawl API 密钥（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey`，或 `FIRECRAWL_API_KEY` 环境变量。
+- `plugins.entries.<id>.hooks.allowPromptInjection`：当为 `false` 时，核心会阻止 `before_prompt_build`，并忽略旧版 `before_agent_start` 中会修改提示词的字段，同时保留旧版 `modelOverride` 和 `providerOverride`。适用于原生插件钩子，以及受支持的由 bundle 提供的钩子目录。
+- `plugins.entries.<id>.hooks.allowConversationAccess`：当为 `true` 时，受信任的非内置插件可以从类型化钩子（如 `llm_input`、`llm_output` 和 `agent_end`）中读取原始对话内容。
+- `plugins.entries.<id>.subagent.allowModelOverride`：显式信任此插件，使其可为后台子智能体运行请求按次运行的 `provider` 和 `model` 覆盖。
+- `plugins.entries.<id>.subagent.allowedModels`：受信任子智能体覆盖的规范 `provider/model` 目标可选允许列表。仅当你确实想允许任意模型时，才使用 `"*"`。
+- `plugins.entries.<id>.config`：插件定义的配置对象（可在可用时由原生 OpenClaw 插件 schema 验证）。
+- 渠道插件的账号/运行时设置位于 `channels.<id>` 下，应由所属插件 manifest 的 `channelConfigs` 元数据描述，而不是由 OpenClaw 的中央选项注册表描述。
+- `plugins.entries.firecrawl.config.webFetch`：Firecrawl web-fetch 提供商设置。
+  - `apiKey`：Firecrawl API key（接受 SecretRef）。会回退到 `plugins.entries.firecrawl.config.webSearch.apiKey`、旧版 `tools.web.fetch.firecrawl.apiKey` 或 `FIRECRAWL_API_KEY` 环境变量。
  - `baseUrl`：Firecrawl API 基础 URL（默认值：`https://api.firecrawl.dev`）。
  - `onlyMainContent`：仅提取页面主体内容（默认值：`true`）。
-  - `maxAgeMs`：最大缓存时长，单位为毫秒（默认值：`172800000` / 2 天）。
-  - `timeoutSeconds`：抓取请求超时秒数（默认值：`60`）。
- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok 网页搜索）设置。
+  - `maxAgeMs`：最大缓存时长（毫秒）（默认值：`172800000` / 2 天）。
+  - `timeoutSeconds`：抓取请求超时时间（秒）（默认值：`60`）。
+- `plugins.entries.xai.config.xSearch`：xAI X Search（Grok web 搜索）设置。
  - `enabled`：启用 X Search 提供商。
-  - `model`：搜索所使用的 Grok 模型（例如 `"grok-4-1-fast"`）。
- `plugins.entries.memory-core.config.dreaming`：memory dreaming 设置。阶段和阈值请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
-  - `enabled`：dreaming 总开关（默认值 `false`）。
+  - `model`：用于搜索的 Grok 模型（例如 `"grok-4-1-fast"`）。
+- `plugins.entries.memory-core.config.dreaming`：内存 dreaming 设置。有关阶段和阈值，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
+  - `enabled`：dreaming 总开关（默认值为 `false`）。
  - `frequency`：每次完整 dreaming 扫描的 cron 频率（默认值为 `"0 3 * * *"`）。
  - 阶段策略和阈值属于实现细节（不是面向用户的配置键）。
- 完整的 memory 配置位于 [内存配置参考](/zh-CN/reference/memory-config)：
+- 完整的内存配置位于 [内存配置参考](/zh-CN/reference/memory-config)：
  - `agents.defaults.memorySearch.*`
  - `memory.backend`
  - `memory.citations`
  - `memory.qmd.*`
  - `plugins.entries.memory-core.config.dreaming`
- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为经过清理的智能体设置来应用，而不是作为原始 OpenClaw 配置补丁来应用。
- `plugins.slots.memory`：选择当前生效的 memory 插件 id，或设为 `"none"` 以禁用 memory 插件。
- `plugins.slots.contextEngine`：选择当前生效的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。
+- 已启用的 Claude bundle 插件也可以通过 `settings.json` 提供嵌入式 Pi 默认值；OpenClaw 会将其作为经过清理的智能体设置应用，而不是作为原始 OpenClaw 配置补丁应用。
+- `plugins.slots.memory`：选择当前活动的内存插件 id，或使用 `"none"` 禁用内存插件。
+- `plugins.slots.contextEngine`：选择当前活动的上下文引擎插件 id；默认值为 `"legacy"`，除非你安装并选择了其他引擎。
 - `plugins.installs`：由 CLI 管理的安装元数据，供 `openclaw plugins update` 使用。
-  - 包括 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
+  - 包含 `source`、`spec`、`sourcePath`、`installPath`、`version`、`resolvedName`、`resolvedVersion`、`resolvedSpec`、`integrity`、`shasum`、`resolvedAt`、`installedAt`。
  - 将 `plugins.installs.*` 视为托管状态；优先使用 CLI 命令，而不是手动编辑。

 请参阅 [插件](/zh-CN/tools/plugin)。
@ -205,8 +209,8 @@ x-i18n:
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
-      // dangerouslyAllowPrivateNetwork: true, // only for trusted private-network access
-      // allowPrivateNetwork: true, // legacy alias
+      // dangerouslyAllowPrivateNetwork: true, // 仅在受信任的私有网络访问场景下选择启用
+      // allowPrivateNetwork: true, // 旧版别名
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
@ -243,35 +247,35 @@ x-i18n:
 ```

 - `evaluateEnabled: false` 会禁用 `act:evaluate` 和 `wait --fn`。
- `tabCleanup` 会在空闲一段时间后，或当某个
-  会话超过其上限时，回收已跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为
+- `tabCleanup` 会在空闲超时后，或当某个
+  会话超过其上限时，回收被跟踪的主智能体标签页。将 `idleMinutes: 0` 或 `maxTabsPerSession: 0` 设为
  0，可分别禁用这些单独的清理模式。
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此浏览器导航默认保持严格限制。
- 仅当你明确信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性 / 发现检查期间同样受私有网络阻止规则约束。
+- `ssrfPolicy.dangerouslyAllowPrivateNetwork` 在未设置时为禁用状态，因此默认情况下浏览器导航保持严格限制。
+- 仅当你明确愿意信任私有网络浏览器导航时，才设置 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`。
+- 在严格模式下，远程 CDP 配置文件端点（`profiles.*.cdpUrl`）在可达性/设备发现检查期间，也会受到相同的私有网络阻止限制。
 - `ssrfPolicy.allowPrivateNetwork` 仍作为旧版别名受支持。
 - 在严格模式下，使用 `ssrfPolicy.hostnameAllowlist` 和 `ssrfPolicy.allowedHostnames` 进行显式例外配置。
- 远程配置文件仅支持附加模式（禁用 start / stop / reset）。
+- 远程配置文件为仅附加模式（禁用 start/stop/reset）。
 - `profiles.*.cdpUrl` 接受 `http://`、`https://`、`ws://` 和 `wss://`。
-  当你希望 OpenClaw 发现 `/json/version` 时，请使用 HTTP(S)；使用 WS(S)
-  则适用于你的提供商直接提供 DevTools WebSocket URL 的情况。
- `existing-session` 配置文件使用 Chrome MCP 而非 CDP，并且可以附加到
+  当你希望 OpenClaw 发现 `/json/version` 时，使用 HTTP(S)；当你的提供商直接提供 DevTools WebSocket URL 时，
+  使用 WS(S)。
+- `existing-session` 配置文件使用 Chrome MCP 而不是 CDP，并且可以附加到
  所选主机上，或通过已连接的浏览器节点附加。
- `existing-session` 配置文件可设置 `userDataDir`，以定位特定的
-  Chromium 系浏览器配置文件，例如 Brave 或 Edge。
+- `existing-session` 配置文件可以设置 `userDataDir`，以定位特定的
+  基于 Chromium 的浏览器配置文件，例如 Brave 或 Edge。
 - `existing-session` 配置文件保留当前 Chrome MCP 路由限制：
-  使用基于快照 / ref 的操作，而不是基于 CSS 选择器的定位；仅支持单文件上传
+  使用 snapshot/ref 驱动的操作，而不是 CSS 选择器定位；单文件上传
  钩子；不支持对话框超时覆盖；不支持 `wait --load networkidle`；也不支持
  `responsebody`、PDF 导出、下载拦截或批量操作。
- 本地托管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下
-  才需要显式设置 `cdpUrl`。
- 本地托管配置文件可设置 `executablePath`，以覆盖该配置文件的全局
+- 本地受管的 `openclaw` 配置文件会自动分配 `cdpPort` 和 `cdpUrl`；仅在远程 CDP 场景下
+  才显式设置 `cdpUrl`。
+- 本地受管配置文件可以设置 `executablePath`，以覆盖该配置文件的全局
  `browser.executablePath`。可借此让一个配置文件运行在 Chrome 中，另一个运行在 Brave 中。
- 自动检测顺序：默认浏览器（如果是 Chromium 系）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
- `browser.executablePath` 接受 `~` 作为你的操作系统主目录。
- 控制服务：仅限 loopback（端口由 `gateway.port` 派生，默认值为 `18791`）。
- `extraArgs` 会将额外的启动标志附加到本地 Chromium 启动参数中（例如
-  `--disable-gpu`、窗口大小设置或调试标志）。
+- 自动检测顺序：默认浏览器（若为基于 Chromium）→ Chrome → Brave → Edge → Chromium → Chrome Canary。
+- `browser.executablePath` 接受 `~`，表示你操作系统的 home 目录。
+- 控制服务：仅 loopback（端口由 `gateway.port` 派生，默认值为 `18791`）。
+- `extraArgs` 会为本地 Chromium 启动追加额外的启动标志（例如
+  `--disable-gpu`、窗口尺寸设置或调试标志）。

 ---

@ -289,7 +293,7 @@ x-i18n:
 }
 ```

- `seamColor`：原生应用 UI 外观的强调色（Talk 模式气泡着色等）。
+- `seamColor`：原生应用 UI 外框的强调色（Talk Mode 气泡着色等）。
 - `assistant`：Control UI 身份覆盖。回退到当前活动智能体身份。

 ---
@ -341,14 +345,14 @@ x-i18n:
    allowRealIpFallback: false,
    nodes: {
      pairing: {
-        // 可选。默认未设置 / 已禁用。
+        // 可选。默认未设置/已禁用。
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
      allowCommands: ["canvas.navigate"],
      denyCommands: ["system.run"],
    },
    tools: {
-      // 额外的 /tools/invoke HTTP 拒绝列表
+      // 附加的 /tools/invoke HTTP 拒绝项
      deny: ["browser"],
      // 从默认 HTTP 拒绝列表中移除工具
      allow: ["gateway"],
@ -367,70 +371,71 @@ x-i18n:

 <Accordion title="Gateway 网关字段详情">

- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关会拒绝启动。
+- `mode`：`local`（运行 Gateway 网关）或 `remote`（连接到远程 Gateway 网关）。除非为 `local`，否则 Gateway 网关拒绝启动。
 - `port`：用于 WS + HTTP 的单一复用端口。优先级：`--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`。
 - `bind`：`auto`、`loopback`（默认）、`lan`（`0.0.0.0`）、`tailnet`（仅 Tailscale IP）或 `custom`。
- **旧版 bind 别名**：请在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
- **Docker 注意事项**：默认的 `loopback` bind 会在容器内部监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关将无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或设置 `bind: "custom"` 并配合 `customBindHost: "0.0.0.0"`），以在所有接口上监听。
- **认证**：默认必需。非 loopback bind 必须启用 Gateway 网关认证。实际来说，这意味着需要共享 token / password，或使用配置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知反向代理。新手引导向导默认会生成一个 token。
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。当两者都已配置但未设置 mode 时，启动以及服务安装 / 修复流程会失败。
- `gateway.auth.mode: "none"`：显式无认证模式。仅应在可信的本地 local loopback 设置中使用；新手引导提示中不会故意提供此选项。
- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)）。该模式要求 **非 loopback** 的代理来源；同主机上的 loopback 反向代理不满足 trusted-proxy 认证条件。
- `gateway.auth.allowTailscale`：为 `true` 时，Tailscale Serve 身份头可满足 Control UI / WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点 **不会** 使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。此无 token 流程假定 Gateway 网关主机是可信的。当 `tailscale.mode = "serve"` 时，默认值为 `true`。
+- **旧版 bind 别名**：在 `gateway.bind` 中使用 bind 模式值（`auto`、`loopback`、`lan`、`tailnet`、`custom`），不要使用 host 别名（`0.0.0.0`、`127.0.0.1`、`localhost`、`::`、`::1`）。
+- **Docker 注意事项**：默认的 `loopback` bind 会在容器内监听 `127.0.0.1`。使用 Docker bridge 网络（`-p 18789:18789`）时，流量会到达 `eth0`，因此 Gateway 网关无法访问。请使用 `--network host`，或设置 `bind: "lan"`（或 `bind: "custom"` 且 `customBindHost: "0.0.0.0"`）以监听所有接口。
+- **认证**：默认必需。非 loopback bind 要求 Gateway 网关认证。实际这意味着使用共享 token/password，或使用配置了 `gateway.auth.mode: "trusted-proxy"` 的身份感知型反向代理。新手引导向导默认会生成一个 token。
+- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`（包括 SecretRef），请将 `gateway.auth.mode` 显式设置为 `token` 或 `password`。当两者都已配置但未设置 mode 时，启动和服务安装/修复流程都会失败。
+- `gateway.auth.mode: "none"`：显式无认证模式。仅用于受信任的本地 local loopback 设置；新手引导提示中不会提供该选项，这是有意设计。
+- `gateway.auth.mode: "trusted-proxy"`：将认证委托给身份感知型反向代理，并信任来自 `gateway.trustedProxies` 的身份头（参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)）。此模式要求**非 loopback** 的代理来源；同主机 loopback 反向代理不满足 trusted-proxy 认证要求。
+- `gateway.auth.allowTailscale`：当为 `true` 时，Tailscale Serve 身份头可满足 Control UI/WebSocket 认证（通过 `tailscale whois` 验证）。HTTP API 端点**不会**使用该 Tailscale 头认证；它们仍遵循 Gateway 网关的常规 HTTP 认证模式。该无 token 流程假定 Gateway 网关主机受信任。当 `tailscale.mode = "serve"` 时，默认值为 `true`。
 - `gateway.auth.rateLimit`：可选的认证失败限流器。按客户端 IP 和认证作用域生效（共享密钥和设备 token 分别独立跟踪）。被阻止的尝试会返回 `429` + `Retry-After`。
-  - 在异步 Tailscale Serve Control UI 路径上，相同 `{scope, clientIp}` 的失败尝试会在写入失败记录前进行串行化。因此，来自同一客户端的并发错误尝试，可能会在第二个请求时触发限流，而不是两个都作为普通不匹配直接通过竞争路径。
-  - `gateway.auth.rateLimit.exemptLoopback` 默认值为 `true`；如果你明确希望对 localhost 流量也进行限流（例如测试环境或严格代理部署），请设为 `false`。
- 来自浏览器源的 WS 认证尝试始终会在禁用 loopback 豁免的情况下受到节流限制（作为针对基于浏览器的 localhost 暴力破解的纵深防御）。
- 在 loopback 上，这些浏览器源锁定会按规范化后的 `Origin`
-  值分别隔离，因此来自某个 localhost origin 的重复失败不会自动
-  锁定另一个 origin。
- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公开访问，需要认证）。
- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。当预期浏览器客户端来自非 loopback 源时，这是必需的。
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为那些有意依赖 Host 头 origin 策略的部署启用基于 Host 头的 origin 回退。
- `remote.transport`：`ssh`（默认）或 `direct`（ws / wss）。对于 `direct`，`remote.url` 必须为 `ws://` 或 `wss://`。
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量中的紧急放行覆盖项，允许通过明文 `ws://` 连接到受信任的私有网络
-  IP；默认情况下，明文连接仍仅限 loopback。没有对应的 `openclaw.json`
-  配置项，且诸如
-  `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` 之类的浏览器私有网络配置也不会影响 Gateway 网关
+  - 在异步 Tailscale Serve Control UI 路径中，同一 `{scope, clientIp}` 的失败尝试会在写入失败记录前被串行化。因此，同一客户端的并发错误尝试可能会在第二个请求时触发限流，而不是两个请求都像普通不匹配那样竞态通过。
+  - `gateway.auth.rateLimit.exemptLoopback` 默认为 `true`；若你明确希望连 localhost 流量也被限流（例如测试环境或严格代理部署），请设置为 `false`。
+- 来自浏览器源的 WS 认证尝试始终会被限流，且禁用 loopback 豁免（作为防御纵深，防止基于浏览器的 localhost 暴力破解）。
+- 在 loopback 上，这些来自浏览器源的锁定会按归一化后的 `Origin`
+  值彼此隔离，因此来自某个 localhost 源的重复失败不会自动
+  锁定另一个源。
+- `tailscale.mode`：`serve`（仅 tailnet，loopback bind）或 `funnel`（公网，需要认证）。
+- `controlUi.allowedOrigins`：用于 Gateway 网关 WebSocket 连接的显式浏览器源允许列表。若预期浏览器客户端来自非 loopback 源，则必须设置。
+- `controlUi.dangerouslyAllowHostHeaderOriginFallback`：危险模式，为有意依赖 Host 头源策略的部署启用 Host 头源回退。
+- `remote.transport`：`ssh`（默认）或 `direct`（ws/wss）。对于 `direct`，`remote.url` 必须是 `ws://` 或 `wss://`。
+- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`：客户端进程环境变量中的紧急放行开关，
+  允许使用明文 `ws://` 连接受信任的私有网络
+  IP；默认仍仅允许 loopback 使用明文。`openclaw.json`
+  中没有对应项，且浏览器私有网络配置，例如
+  `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`，不会影响 Gateway 网关
  WebSocket 客户端。
- `gateway.remote.token` / `.password`：远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。
- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，官方 / TestFlight iOS 构建在将基于 relay 的注册发布到 Gateway 网关后会使用它。此 URL 必须与编译进 iOS 构建中的 relay URL 一致。
- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间，单位为毫秒。默认值为 `10000`。
- 基于 relay 的注册会委托给特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并将一个以注册为作用域的发送授权转发给 Gateway 网关。另一台 Gateway 网关无法复用该已存储的注册。
+- `gateway.remote.token` / `.password` 是远程客户端凭证字段。它们本身不会配置 Gateway 网关认证。
+- `gateway.push.apns.relay.baseUrl`：外部 APNs relay 的基础 HTTPS URL，供官方/TestFlight iOS 构建在向 Gateway 网关发布基于 relay 的注册后使用。该 URL 必须与编译进 iOS 构建中的 relay URL 一致。
+- `gateway.push.apns.relay.timeoutMs`：Gateway 网关到 relay 的发送超时时间（毫秒）。默认值：`10000`。
+- 基于 relay 的注册会委托给特定的 Gateway 网关身份。已配对的 iOS 应用会获取 `gateway.identity.get`，在 relay 注册中包含该身份，并向 Gateway 网关转发一个作用于该注册的发送授权。另一个 Gateway 网关无法复用该已存储注册。
 - `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`：用于覆盖上述 relay 配置的临时环境变量。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃生口，用于 loopback HTTP relay URL。生产 relay URL 应保持为 HTTPS。
- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔，单位为分钟。设为 `0` 可全局禁用健康监控重启。默认值：`5`。
- `gateway.channelStaleEventThresholdMinutes`：过期 socket 阈值，单位为分钟。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
- `gateway.channelMaxRestartsPerHour`：滚动一小时内每个渠道 / 账号允许的最大健康监控重启次数。默认值：`10`。
- `channels.<provider>.healthMonitor.enabled`：渠道级退出配置，用于在保持全局监控启用时禁用该渠道的健康监控重启。
+- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`：仅供开发使用的逃生开关，用于允许使用 loopback HTTP relay URL。生产环境 relay URL 应保持使用 HTTPS。
+- `gateway.channelHealthCheckMinutes`：渠道健康监控间隔（分钟）。设为 `0` 可全局禁用健康监控重启。默认值：`5`。
+- `gateway.channelStaleEventThresholdMinutes`：陈旧套接字阈值（分钟）。请保持其大于或等于 `gateway.channelHealthCheckMinutes`。默认值：`30`。
+- `gateway.channelMaxRestartsPerHour`：每个渠道/账号在滚动一小时内允许的最大健康监控重启次数。默认值：`10`。
+- `channels.<provider>.healthMonitor.enabled`：渠道级退出设置，可在保留全局监控启用的同时禁用健康监控重启。
 - `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`：多账号渠道的账号级覆盖。设置后，其优先级高于渠道级覆盖。
- 仅当 `gateway.auth.*` 未设置时，本地 Gateway 网关调用路径才可以将 `gateway.remote.*` 用作回退。
- 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但未能解析，则解析将以关闭方式失败（不会被远程回退掩盖）。
- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。仅列出你控制的代理。loopback 条目对同主机代理 / 本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们 **不会** 让 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。
- `allowRealIpFallback`：为 `true` 时，当缺少 `X-Forwarded-For` 时，Gateway 网关接受 `X-Real-IP`。默认值为 `false`，以保持默认关闭的失效策略。
- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR / IP 允许列表，用于自动批准首次节点设备配对且未请求任何作用域的情况。未设置时为禁用状态。这不会自动批准 operator / browser / Control UI / WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许 / 拒绝整形。
- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名（扩展默认拒绝列表）。
- `gateway.tools.allow`：将工具名从默认 HTTP 拒绝列表中移除。
+- 本地 Gateway 网关调用路径仅在 `gateway.auth.*` 未设置时，才可回退使用 `gateway.remote.*`。
+- 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但未解析成功，解析将以关闭方式失败（不会用远程回退来掩盖问题）。
+- `trustedProxies`：终止 TLS 或注入转发客户端头的反向代理 IP。仅列出你控制的代理。loopback 条目对于同主机代理/本地检测设置仍然有效（例如 Tailscale Serve 或本地反向代理），但它们**不会**使 loopback 请求符合 `gateway.auth.mode: "trusted-proxy"` 的条件。
+- `allowRealIpFallback`：当为 `true` 时，若缺少 `X-Forwarded-For`，Gateway 网关会接受 `X-Real-IP`。默认值为 `false`，以实现失败即关闭的行为。
+- `gateway.nodes.pairing.autoApproveCidrs`：可选的 CIDR/IP 允许列表，用于自动批准首次节点设备配对，前提是不请求任何作用域。未设置时为禁用状态。它不会自动批准 operator/browser/Control UI/WebChat 配对，也不会自动批准角色、作用域、元数据或公钥升级。
+- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`：在配对和允许列表评估之后，对已声明节点命令进行全局允许/拒绝整形。
+- `gateway.tools.deny`：对 HTTP `POST /tools/invoke` 额外阻止的工具名称（扩展默认拒绝列表）。
+- `gateway.tools.allow`：从默认 HTTP 拒绝列表中移除工具名称。

 </Accordion>

 ### OpenAI 兼容端点

- Chat Completions：默认禁用。使用 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
+- Chat Completions：默认禁用。通过 `gateway.http.endpoints.chatCompletions.enabled: true` 启用。
 - Responses API：`gateway.http.endpoints.responses.enabled`。
 - Responses URL 输入加固：
  - `gateway.http.endpoints.responses.maxUrlParts`
  - `gateway.http.endpoints.responses.files.urlAllowlist`
  - `gateway.http.endpoints.responses.images.urlAllowlist`
-    空的允许列表会被视为未设置；如需禁用 URL 抓取，请使用 `gateway.http.endpoints.responses.files.allowUrl=false`
-    和 / 或 `gateway.http.endpoints.responses.images.allowUrl=false`。
+    空允许列表会被视为未设置；请使用 `gateway.http.endpoints.responses.files.allowUrl=false`
+    和/或 `gateway.http.endpoints.responses.images.allowUrl=false` 来禁用 URL 抓取。
 - 可选的响应加固头：
-  - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [受信任代理认证](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）
+  - `gateway.http.securityHeaders.strictTransportSecurity`（仅对你控制的 HTTPS 源设置；参见 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth#tls-termination-and-hsts)）

 ### 多实例隔离

-在同一主机上运行多个 Gateway 网关时，请使用唯一端口和状态目录：
+在同一主机上运行多个 Gateway 网关时，请使用唯一的端口和状态目录：

 ```bash
 OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@ -440,7 +445,7 @@ openclaw gateway --port 19001

 便捷标志：`--dev`（使用 `~/.openclaw-dev` + 端口 `19001`）、`--profile <name>`（使用 `~/.openclaw-<name>`）。

-请参阅 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。
+参见 [多个 Gateway 网关](/zh-CN/gateway/multiple-gateways)。

 ### `gateway.tls`

@ -458,11 +463,11 @@ openclaw gateway --port 19001
 }
 ```

- `enabled`：在 Gateway 网关监听器处启用 TLS 终止（HTTPS / WSS）（默认值：`false`）。
- `autoGenerate`：在未配置显式文件时自动生成本地自签名证书 / 密钥对；仅供本地 / 开发使用。
+- `enabled`：在 Gateway 网关监听器上启用 TLS 终止（HTTPS/WSS）（默认值：`false`）。
+- `autoGenerate`：当未配置显式文件时，自动生成本地自签名 cert/key 对；仅用于本地/开发环境。
 - `certPath`：TLS 证书文件的文件系统路径。
- `keyPath`：TLS 私钥文件的文件系统路径；请限制其访问权限。
- `caPath`：用于客户端验证或自定义信任链的可选 CA bundle 路径。
+- `keyPath`：TLS 私钥文件的文件系统路径；请保持权限受限。
+- `caPath`：可选的 CA bundle 路径，用于客户端验证或自定义信任链。

 ### `gateway.reload`

@ -479,16 +484,16 @@ openclaw gateway --port 19001
 ```

 - `mode`：控制在运行时如何应用配置编辑。
-  - `"off"`：忽略实时编辑；更改需要显式重启。
-  - `"restart"`：配置更改时始终重启 Gateway 网关进程。
-  - `"hot"`：在不重启的情况下于进程内应用更改。
+  - `"off"`：忽略实时编辑；变更需要显式重启。
+  - `"restart"`：配置变更时始终重启 Gateway 网关进程。
+  - `"hot"`：在不重启的情况下于进程内应用变更。
  - `"hybrid"`（默认）：先尝试热重载；若有需要则回退为重启。
- `debounceMs`：应用配置更改前的防抖窗口，单位为毫秒（非负整数）。
- `deferralTimeoutMs`：在强制重启前等待正在进行中的操作完成的最长时间，单位为毫秒（默认值：`300000` = 5 分钟）。
+- `debounceMs`：应用配置变更前的防抖窗口（毫秒）（非负整数）。
+- `deferralTimeoutMs`：在强制重启前等待进行中操作完成的最长时间（毫秒）（默认值：`300000` = 5 分钟）。

 ---

-## Hooks
+## 钩子

 ```json5
 {
@ -522,21 +527,21 @@ openclaw gateway --port 19001
 ```

 认证：`Authorization: Bearer <token>` 或 `x-openclaw-token: <token>`。
-拒绝使用查询字符串 hook token。
+拒绝使用查询字符串中的 hook token。

-验证和安全说明：
+验证与安全说明：

- `hooks.enabled=true` 要求提供非空的 `hooks.token`。
+- `hooks.enabled=true` 要求 `hooks.token` 为非空。
 - `hooks.token` 必须与 `gateway.auth.token` **不同**；复用 Gateway 网关 token 会被拒绝。
 - `hooks.path` 不能为 `/`；请使用专用子路径，例如 `/hooks`。
 - 如果 `hooks.allowRequestSessionKey=true`，请约束 `hooks.allowedSessionKeyPrefixes`（例如 `["hook:"]`）。
- 如果某个映射或 preset 使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该显式启用。
+- 如果某个映射或预设使用模板化的 `sessionKey`，请设置 `hooks.allowedSessionKeyPrefixes` 和 `hooks.allowRequestSessionKey=true`。静态映射键不需要该显式启用。

 **端点：**

 - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
 - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
-  - 仅当 `hooks.allowRequestSessionKey=true`（默认值：`false`）时，才接受请求负载中的 `sessionKey`。
+  - 仅当 `hooks.allowRequestSessionKey=true` 时，才接受请求负载中的 `sessionKey`（默认值：`false`）。
 - `POST /hooks/<name>` → 通过 `hooks.mappings` 解析
  - 通过模板渲染得到的映射 `sessionKey` 值会被视为外部提供，因此同样要求 `hooks.allowRequestSessionKey=true`。

@ -544,24 +549,24 @@ openclaw gateway --port 19001

 - `match.path` 匹配 `/hooks` 之后的子路径（例如 `/hooks/gmail` → `gmail`）。
 - `match.source` 匹配通用路径中的某个负载字段。
- 类似 `{{messages[0].subject}}` 这样的模板会从负载中读取值。
- `transform` 可以指向一个返回 hook 动作的 JS / TS 模块。
-  - `transform.module` 必须是相对路径，并且必须保持在 `hooks.transformsDir` 内（绝对路径和路径遍历会被拒绝）。
- `agentId` 会路由到特定智能体；未知 ID 会回退到默认值。
- `allowedAgentIds`：限制显式路由（`*` 或省略 = 允许全部，`[]` = 全部拒绝）。
+- 像 `{{messages[0].subject}}` 这样的模板会从负载中读取。
+- `transform` 可以指向一个返回 hook 动作的 JS/TS 模块。
+  - `transform.module` 必须是相对路径，并保持在 `hooks.transformsDir` 范围内（绝对路径和路径遍历会被拒绝）。
+- `agentId` 会路由到指定智能体；未知 ID 会回退到默认值。
+- `allowedAgentIds`：限制显式路由（`*` 或省略 = 全部允许，`[]` = 全部拒绝）。
 - `defaultSessionKey`：可选的固定会话键，用于未显式提供 `sessionKey` 的 hook 智能体运行。
- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。
- `allowedSessionKeyPrefixes`：显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任何映射或 preset 使用模板化 `sessionKey` 时，它就成为必需项。
- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认值为 `last`。
- `model`：为本次 hook 运行覆盖 LLM（如果设置了模型目录，则该模型必须被允许）。
+- `allowRequestSessionKey`：允许 `/hooks/agent` 调用方以及由模板驱动的映射会话键设置 `sessionKey`（默认值：`false`）。
+- `allowedSessionKeyPrefixes`：用于显式 `sessionKey` 值（请求 + 映射）的可选前缀允许列表，例如 `["hook:"]`。当任意映射或预设使用模板化 `sessionKey` 时，它就成为必填项。
+- `deliver: true` 会将最终回复发送到某个渠道；`channel` 默认为 `last`。
+- `model` 会覆盖此次 hook 运行使用的 LLM（如果设置了模型目录，则必须在允许范围内）。

 </Accordion>

 ### Gmail 集成

- 内置 Gmail preset 使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
+- 内置 Gmail 预设使用 `sessionKey: "hook:gmail:{{messages[0].id}}"`。
 - 如果你保留这种按消息路由的方式，请设置 `hooks.allowRequestSessionKey: true`，并约束 `hooks.allowedSessionKeyPrefixes` 以匹配 Gmail 命名空间，例如 `["hook:", "hook:gmail:"]`。
- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该 preset，而不是使用模板化默认值。
+- 如果你需要 `hooks.allowRequestSessionKey: false`，请用静态 `sessionKey` 覆盖该预设，而不是使用模板化默认值。

 ```json5
 {
@ -585,7 +590,7 @@ openclaw gateway --port 19001
 ```

 - 配置后，Gateway 网关会在启动时自动启动 `gog gmail watch serve`。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可禁用。
- 不要在 Gateway 网关运行的同时单独再运行一个 `gog gmail watch serve`。
+- 不要与 Gateway 网关同时单独运行另一个 `gog gmail watch serve`。

 ---

@ -601,17 +606,17 @@ openclaw gateway --port 19001
 }
 ```

- 通过 Gateway 网关端口下的 HTTP 提供可由智能体编辑的 HTML / CSS / JS 和 A2UI：
+- 在 Gateway 网关端口下通过 HTTP 提供可由智能体编辑的 HTML/CSS/JS 和 A2UI：
  - `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
  - `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
 - 仅限本地：请保持 `gateway.bind: "loopback"`（默认）。
- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，都需要 Gateway 网关认证（token / password / trusted-proxy）。
- 节点 WebView 通常不会发送认证头；当节点已完成配对并连接后，Gateway 网关会为 canvas / A2UI 访问公布节点作用域的 capability URL。
- Capability URL 绑定到当前活动的节点 WS 会话，并会很快过期。不使用基于 IP 的回退。
- 会向所提供的 HTML 中注入 live-reload 客户端。
- 为空时会自动创建初始 `index.html`。
+- 非 loopback bind：canvas 路由与其他 Gateway 网关 HTTP 面一样，需要 Gateway 网关认证（token/password/trusted-proxy）。
+- 节点 WebView 通常不会发送认证头；节点完成配对并连接后，Gateway 网关会为 canvas/A2UI 访问公布节点作用域能力 URL。
+- 能力 URL 绑定到当前活动的节点 WS 会话，并且很快过期。不使用基于 IP 的回退。
+- 会将 live-reload 客户端注入到所提供的 HTML 中。
+- 为空时会自动创建起始 `index.html`。
 - 也会在 `/__openclaw__/a2ui/` 提供 A2UI。
- 更改需要重启 Gateway 网关。
+- 变更需要重启 Gateway 网关。
 - 对于大型目录或出现 `EMFILE` 错误时，请禁用 live reload。

 ---
@ -630,11 +635,11 @@ openclaw gateway --port 19001
 }
 ```

- `minimal`（默认）：在 TXT 记录中省略 `cliPath` + `sshPort`。
- `full`：包含 `cliPath` + `sshPort`。
+- `minimal`（默认）：在 TXT 记录中省略 `cliPath` 和 `sshPort`。
+- `full`：包含 `cliPath` 和 `sshPort`。
 - 主机名默认为 `openclaw`。可通过 `OPENCLAW_MDNS_HOSTNAME` 覆盖。

-### 广域网（DNS-SD）
+### 广域（DNS-SD）

 ```json5
 {
@ -644,7 +649,7 @@ openclaw gateway --port 19001
 }
 ```

-会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。若需跨网络设备发现，请与 DNS 服务器（推荐 CoreDNS）+ Tailscale 分离 DNS 配合使用。
+会在 `~/.openclaw/dns/` 下写入一个单播 DNS-SD 区域。若需跨网络设备发现，请配合 DNS 服务器（推荐 CoreDNS）和 Tailscale split DNS 一起使用。

 设置：`openclaw dns setup --apply`。

@ -669,7 +674,7 @@ openclaw gateway --port 19001
 }
 ```

- 仅当进程环境中缺少某个键时，才会应用内联环境变量。
+- 仅当进程环境中缺少该键时，才会应用内联环境变量。
 - `.env` 文件：当前工作目录下的 `.env` + `~/.openclaw/.env`（两者都不会覆盖现有变量）。
 - `shellEnv`：从你的登录 shell 配置文件中导入缺失的预期键名。
 - 完整优先级请参阅 [环境](/zh-CN/help/environment)。
@ -686,38 +691,38 @@ openclaw gateway --port 19001
 }
 ```

- 仅匹配全大写名称：`[A-Z_][A-Z0-9_]*`。
- 缺失 / 为空的变量会在加载配置时抛出错误。
- 使用 `$${VAR}` 可转义为字面量 `${VAR}`。
- 对 `$include` 同样有效。
+- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`。
+- 缺失/为空的变量会在加载配置时抛出错误。
+- 使用 `$${VAR}` 来转义，得到字面量 `${VAR}`。
+- 适用于 `$include`。

 ---

 ## 密钥

-SecretRef 是增量式支持的：明文值仍然可用。
+SecretRef 采用增量方式：明文值仍然可用。

 ### `SecretRef`

-使用一种对象结构：
+使用以下对象结构：

 ```json5
 { source: "env" | "file" | "exec", provider: "default", id: "..." }
 ```

-校验规则：
+验证规则：

 - `provider` 模式：`^[a-z][a-z0-9_-]{0,63}$`
 - `source: "env"` 的 id 模式：`^[A-Z][A-Z0-9_]{0,127}$`
- `source: "file"` 的 id：绝对 JSON pointer（例如 `"/providers/openai/apiKey"`）
+- `source: "file"` 的 id：绝对 JSON 指针（例如 `"/providers/openai/apiKey"`）
 - `source: "exec"` 的 id 模式：`^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `source: "exec"` 的 id 不能包含以 `/` 分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝）
+- `source: "exec"` 的 id 不得包含以斜杠分隔的 `.` 或 `..` 路径段（例如 `a/../b` 会被拒绝）

-### 支持的凭证表面
+### 支持的凭证面

- 规范矩阵：[SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)
+- 规范矩阵：[SecretRef 凭证面](/zh-CN/reference/secretref-credential-surface)
 - `secrets apply` 以受支持的 `openclaw.json` 凭证路径为目标。
- `auth-profiles.json` 中的 ref 也包含在运行时解析和审计覆盖范围内。
+- `auth-profiles.json` 中的引用会被纳入运行时解析和审计覆盖范围。

 ### 密钥提供商配置

@ -750,13 +755,13 @@ SecretRef 是增量式支持的：明文值仍然可用。
 说明：

 - `file` 提供商支持 `mode: "json"` 和 `mode: "singleValue"`（在 singleValue 模式下，`id` 必须为 `"value"`）。
- 当无法验证 Windows ACL 时，file 和 exec 提供商路径会以关闭方式失败。仅对无法验证但你信任的路径设置 `allowInsecurePath: true`。
- `exec` 提供商要求 `command` 为绝对路径，并通过 stdin / stdout 上的协议负载工作。
- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时仍校验其解析后的目标路径。
- 如果配置了 `trustedDirs`，则受信任目录检查会应用于解析后的目标路径。
- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传递所需变量。
- SecretRef 会在激活时解析为内存中的快照，之后请求路径只读取该快照。
- 激活期间会应用活跃表面过滤：启用表面上的未解析 ref 会导致启动 / 重载失败，而未激活的表面则会被跳过并附带诊断信息。
+- 当 Windows ACL 验证不可用时，file 和 exec 提供商路径会以关闭方式失败。仅对无法验证但受信任的路径设置 `allowInsecurePath: true`。
+- `exec` 提供商要求使用绝对 `command` 路径，并通过 stdin/stdout 使用协议负载。
+- 默认情况下，符号链接命令路径会被拒绝。设置 `allowSymlinkCommand: true` 可允许符号链接路径，同时验证解析后的目标路径。
+- 如果配置了 `trustedDirs`，则受信任目录检查会应用到解析后的目标路径。
+- `exec` 子进程环境默认最小化；请通过 `passEnv` 显式传入所需变量。
+- SecretRef 会在激活时解析到内存快照中，之后请求路径只读取该快照。
+- 激活期间会应用活动面过滤：已启用面的未解析引用会导致启动/重载失败，而非活动面会被跳过并输出诊断信息。

 ---

@ -778,13 +783,13 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- 每个智能体的 profile 存储在 `<agentDir>/auth-profiles.json`。
- `auth-profiles.json` 支持静态凭证模式下的值级 ref（`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
- OAuth 模式 profile（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。
- 静态运行时凭证来自内存中的已解析快照；发现旧版静态 `auth.json` 条目时会进行清理。
- 旧版 OAuth 导入来自 `~/.openclaw/credentials/oauth.json`。
- 请参阅 [OAuth](/zh-CN/concepts/oauth)。
- Secrets 运行时行为以及 `audit/configure/apply` 工具：请参阅 [Secrets 管理](/zh-CN/gateway/secrets)。
+- 按智能体划分的配置文件存储在 `<agentDir>/auth-profiles.json`。
+- `auth-profiles.json` 支持值级引用（静态凭证模式下，`api_key` 使用 `keyRef`，`token` 使用 `tokenRef`）。
+- OAuth 模式配置文件（`auth.profiles.<id>.mode = "oauth"`）不支持由 SecretRef 支持的 auth-profile 凭证。
+- 静态运行时凭证来自已解析的内存快照；发现旧版静态 `auth.json` 条目时会将其清除。
+- 旧版 OAuth 会从 `~/.openclaw/credentials/oauth.json` 导入。
+- 参见 [OAuth](/zh-CN/concepts/oauth)。
+- 密钥运行时行为及 `audit/configure/apply` 工具：参见 [密钥管理](/zh-CN/gateway/secrets)。

 ### `auth.cooldowns`

@ -806,20 +811,20 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- `billingBackoffHours`：当某个 profile 因真正的
-  计费 / 余额不足错误而失败时的基础退避时间（单位：小时，默认值：`5`）。即使在 `401` / `403` 响应中，明确的计费文本
-  仍可能归入这里，但提供商特定的文本
-  匹配器仍只作用于拥有它们的提供商（例如 OpenRouter
-  `Key limit exceeded`）。可重试的 HTTP `402` 用量窗口或
-  组织 / 工作区支出上限消息则仍归入 `rate_limit` 路径。
- `billingBackoffHoursByProvider`：按提供商覆盖计费退避小时数的可选配置。
- `billingMaxHours`：计费退避指数增长的上限小时数（默认值：`24`）。
- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础退避分钟数（默认值：`10`）。
- `authPermanentMaxMinutes`：`auth_permanent` 退避增长的上限分钟数（默认值：`60`）。
- `failureWindowHours`：用于退避计数器的滚动时间窗口，单位为小时（默认值：`24`）。
- `overloadedProfileRotations`：对于过载错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认值：`1`）。诸如 `ModelNotReadyException` 之类的提供商繁忙形态归入此类。
- `overloadedBackoffMs`：在重试过载提供商 / profile 轮换前的固定延迟（默认值：`0`）。
- `rateLimitedProfileRotations`：对于限流错误，在切换到模型回退前，同一提供商 auth-profile 允许的最大轮换次数（默认值：`1`）。该限流桶包括提供商形态的文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。
+- `billingBackoffHours`：当某个配置文件因真实的
+  账单/额度不足错误而失败时，基础回退时间（小时）（默认值：`5`）。明确的账单文本
+  即使出现在 `401`/`403` 响应中，仍可能归入这里，但提供商特定的文本
+  匹配器仍限定在其所属提供商范围内（例如 OpenRouter
+  的 `Key limit exceeded`）。可重试的 HTTP `402` 使用窗口或
+  组织/工作区支出上限消息则仍归入 `rate_limit` 路径。
+- `billingBackoffHoursByProvider`：按提供商覆盖账单回退小时数的可选配置。
+- `billingMaxHours`：账单回退指数增长的小时上限（默认值：`24`）。
+- `authPermanentBackoffMinutes`：高置信度 `auth_permanent` 失败的基础回退时间（分钟）（默认值：`10`）。
+- `authPermanentMaxMinutes`：`auth_permanent` 回退增长的分钟上限（默认值：`60`）。
+- `failureWindowHours`：用于回退计数器的滚动窗口（小时）（默认值：`24`）。
+- `overloadedProfileRotations`：在切换到模型回退前，针对过载错误允许的同一提供商 auth-profile 轮换最大次数（默认值：`1`）。例如 `ModelNotReadyException` 这类提供商繁忙形态就归入这里。
+- `overloadedBackoffMs`：在重试过载提供商/配置文件轮换前的固定延迟（毫秒）（默认值：`0`）。
+- `rateLimitedProfileRotations`：在切换到模型回退前，针对限流错误允许的同一提供商 auth-profile 轮换最大次数（默认值：`1`）。该限流桶包括提供商形态文本，例如 `Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 和 `resource exhausted`。

 ---

@ -840,8 +845,8 @@ SecretRef 是增量式支持的：明文值仍然可用。

 - 默认日志文件：`/tmp/openclaw/openclaw-YYYY-MM-DD.log`。
 - 设置 `logging.file` 可使用稳定路径。
- 使用 `--verbose` 时，`consoleLevel` 会提升为 `debug`。
- `maxFileBytes`：在抑制写入前日志文件允许的最大大小，单位为字节（正整数；默认值：`524288000` = 500 MB）。生产部署请使用外部日志轮转。
+- 使用 `--verbose` 时，`consoleLevel` 会提升到 `debug`。
+- `maxFileBytes`：在抑制写入前允许的最大日志文件大小（字节）（正整数；默认值：`524288000` = 500 MB）。生产部署请使用外部日志轮转。

 ---

@ -886,22 +891,22 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- `enabled`：instrumentation 输出的总开关（默认值：`true`）。
- `flags`：启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 这样的通配符）。
- `stuckSessionWarnMs`：当某个会话仍处于 processing 状态时，发出会话卡住警告的年龄阈值，单位为毫秒。
- `otel.enabled`：启用 OpenTelemetry 导出流水线（默认值：`false`）。
+- `enabled`：仪表输出的总开关（默认值：`true`）。
+- `flags`：用于启用定向日志输出的标志字符串数组（支持 `"telegram.*"` 或 `"*"` 之类的通配符）。
+- `stuckSessionWarnMs`：当会话持续处于处理中状态时，发出卡住会话警告的时间阈值（毫秒）。
+- `otel.enabled`：启用 OpenTelemetry 导出管线（默认值：`false`）。
 - `otel.endpoint`：用于 OTel 导出的 collector URL。
 - `otel.protocol`：`"http/protobuf"`（默认）或 `"grpc"`。
- `otel.headers`：随 OTel 导出请求发送的额外 HTTP / gRPC 元数据头。
+- `otel.headers`：随 OTel 导出请求发送的额外 HTTP/gRPC 元数据头。
 - `otel.serviceName`：资源属性的服务名称。
- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或 log 导出。
+- `otel.traces` / `otel.metrics` / `otel.logs`：启用 trace、metrics 或日志导出。
 - `otel.sampleRate`：trace 采样率，范围 `0`–`1`。
- `otel.flushIntervalMs`：定期刷新 telemetry 的间隔，单位为毫秒。
- `otel.captureContent`：显式启用将原始内容捕获为 OTEL span 属性。默认关闭。布尔值 `true` 会捕获非 system 的消息 / 工具内容；对象形式可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
- `OPENCLAW_OTEL_PRELOADED=1`：用于那些已注册全局 OpenTelemetry SDK 的主机的环境开关。此时 OpenClaw 会跳过插件自有的 SDK 启动 / 关闭流程，同时保持诊断监听器处于活动状态。
- `cacheTrace.enabled`：为嵌入式运行记录缓存 trace 快照（默认值：`false`）。
- `cacheTrace.filePath`：缓存 trace JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存 trace 输出中包含哪些内容（默认全部为 `true`）。
+- `otel.flushIntervalMs`：定期刷新遥测数据的时间间隔（毫秒）。
+- `otel.captureContent`：用于 OTel span 属性的原始内容捕获选择性启用项。默认关闭。布尔值 `true` 会捕获非 system 的消息/工具内容；对象形式则可让你显式启用 `inputMessages`、`outputMessages`、`toolInputs`、`toolOutputs` 和 `systemPrompt`。
+- `OPENCLAW_OTEL_PRELOADED=1`：适用于已经注册了全局 OpenTelemetry SDK 的主机的环境开关。OpenClaw 随后会跳过插件自有的 SDK 启动/关闭，同时保持诊断监听器处于活动状态。
+- `cacheTrace.enabled`：为嵌入式运行记录缓存跟踪快照（默认值：`false`）。
+- `cacheTrace.filePath`：缓存跟踪 JSONL 的输出路径（默认值：`$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`）。
+- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`：控制缓存跟踪输出中包含哪些内容（默认均为 `true`）。

 ---

@ -923,12 +928,12 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- `channel`：用于 npm / git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。
- `checkOnStart`：在 Gateway 网关启动时检查 npm 更新（默认值：`true`）。
+- `channel`：适用于 npm/git 安装的发布渠道——`"stable"`、`"beta"` 或 `"dev"`。
+- `checkOnStart`：Gateway 网关启动时检查 npm 更新（默认值：`true`）。
 - `auto.enabled`：为包安装启用后台自动更新（默认值：`false`）。
- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟小时数（默认值：`6`；最大值：`168`）。
- `auto.stableJitterHours`：stable 渠道额外的发布扩散时间窗口，单位为小时（默认值：`12`；最大值：`168`）。
- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率，单位为小时（默认值：`1`；最大值：`24`）。
+- `auto.stableDelayHours`：stable 渠道自动应用前的最小延迟（小时）（默认值：`6`；最大值：`168`）。
+- `auto.stableJitterHours`：stable 渠道额外发布扩散窗口（小时）（默认值：`12`；最大值：`168`）。
+- `auto.betaCheckIntervalHours`：beta 渠道检查运行频率（小时）（默认值：`1`；最大值：`24`）。

 ---

@ -961,21 +966,21 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- `enabled`：全局 ACP 功能开关（默认值：`false`）。
- `dispatch.enabled`：ACP 会话轮次分发的独立开关（默认值：`true`）。设为 `false` 可保留 ACP 命令可用，同时阻止执行。
- `backend`：默认 ACP 运行时 backend id（必须与已注册的 ACP 运行时插件匹配）。
+- `enabled`：全局 ACP 功能门控（默认值：`false`）。
+- `dispatch.enabled`：ACP 会话轮次分发的独立门控（默认值：`true`）。设为 `false` 可在保留 ACP 命令可用的同时阻止执行。
+- `backend`：默认 ACP 运行时后端 id（必须与已注册的 ACP 运行时插件匹配）。
 - `defaultAgent`：当 spawn 未指定显式目标时，ACP 目标智能体 id 的回退值。
- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 允许列表；空列表表示没有额外限制。
+- `allowedAgents`：允许用于 ACP 运行时会话的智能体 id 列表；空值表示无额外限制。
 - `maxConcurrentSessions`：同时处于活动状态的 ACP 会话最大数量。
- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口，单位为毫秒。
- `stream.maxChunkChars`：流式分块投影在拆分前允许的最大块大小。
- `stream.repeatSuppression`：每轮抑制重复的状态 / 工具行（默认值：`true`）。
- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终结事件后再输出。
- `stream.hiddenBoundarySeparator`：在隐藏工具事件后的可见文本之前使用的分隔符（默认值：`"paragraph"`）。
+- `stream.coalesceIdleMs`：流式文本的空闲合并刷新窗口（毫秒）。
+- `stream.maxChunkChars`：拆分流式块投影前的最大块大小。
+- `stream.repeatSuppression`：按轮次抑制重复的状态/工具行（默认值：`true`）。
+- `stream.deliveryMode`：`"live"` 表示增量流式传输；`"final_only"` 表示缓冲到轮次终止事件后再输出。
+- `stream.hiddenBoundarySeparator`：隐藏工具事件后、可见文本前的分隔符（默认值：`"paragraph"`）。
 - `stream.maxOutputChars`：每个 ACP 轮次投影的智能体输出最大字符数。
- `stream.maxSessionUpdateChars`：投影的 ACP 状态 / 更新行最大字符数。
- `stream.tagVisibility`：标签名称到布尔可见性覆盖的记录，用于流式事件。
- `runtime.ttlMinutes`：ACP 会话工作进程在可被清理前的空闲 TTL，单位为分钟。
+- `stream.maxSessionUpdateChars`：投影的 ACP 状态/更新行最大字符数。
+- `stream.tagVisibility`：记录 tag 名称到布尔可见性覆盖值的映射，用于流式事件。
+- `runtime.ttlMinutes`：ACP 会话工作进程在可清理前的空闲 TTL（分钟）。
 - `runtime.installCommand`：在引导 ACP 运行时环境时执行的可选安装命令。

 ---
@ -992,11 +997,11 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- `cli.banner.taglineMode` 控制横幅标语样式：
-  - `"random"`（默认）：轮换的有趣 / 季节性标语。
-  - `"default"`：固定的中性标语（`All your chats, one OpenClaw.`）。
-  - `"off"`：不显示标语文本（仍会显示横幅标题 / 版本）。
- 若要隐藏整个横幅（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。
+- `cli.banner.taglineMode` 控制 banner 标语样式：
+  - `"random"`（默认）：轮换显示有趣/季节性标语。
+  - `"default"`：固定中性标语（`All your chats, one OpenClaw.`）。
+  - `"off"`：不显示标语文本（仍显示 banner 标题/版本）。
+- 若要隐藏整个 banner（而不只是标语），请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。

 ---

@ -1026,7 +1031,7 @@ SecretRef 是增量式支持的：明文值仍然可用。

 ## Bridge protocol（旧版节点，历史参考）（旧版，已移除）

-当前构建不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前校验会失败；`openclaw doctor --fix` 可清除未知键）。
+当前构建已不再包含 TCP bridge。节点通过 Gateway 网关 WebSocket 连接。`bridge.*` 键已不再属于配置 schema 的一部分（在移除前验证会失败；`openclaw doctor --fix` 可以清除未知键）。

 <Accordion title="旧版 bridge 配置（历史参考）">

@ -1066,11 +1071,11 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- `sessionRetention`：完成的独立 cron 运行会话在从 `sessions.json` 清理前保留多久。也控制已归档且已删除的 cron transcript 的清理。默认值：`24h`；设为 `false` 可禁用。
- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在触发清理前的最大大小。默认值：`2_000_000` 字节。
- `runLog.keepLines`：触发运行日志清理时保留的最新行数。默认值：`2000`。
- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略，则不发送认证头。
- `webhook`：已弃用的旧版回退 webhook URL（http / https），仅用于仍保留 `notify: true` 的已存储作业。
+- `sessionRetention`：在从 `sessions.json` 修剪前，保留已完成的隔离 cron 运行会话多长时间。也控制已归档的已删除 cron 转录内容的清理。默认值：`24h`；设为 `false` 可禁用。
+- `runLog.maxBytes`：每个运行日志文件（`cron/runs/<jobId>.jsonl`）在触发修剪前的最大大小。默认值：`2_000_000` 字节。
+- `runLog.keepLines`：触发运行日志修剪时保留的最新行数。默认值：`2000`。
+- `webhookToken`：用于 cron webhook POST 投递（`delivery.mode = "webhook"`）的 bearer token；若省略则不会发送认证头。
+- `webhook`：已弃用的旧版回退 webhook URL（http/https），仅用于仍保留 `notify: true` 的已存储任务。

 ### `cron.retry`

@ -1086,11 +1091,11 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- `maxAttempts`：一次性作业在暂时性错误下的最大重试次数（默认值：`3`；范围：`0`–`10`）。
- `backoffMs`：每次重试尝试使用的退避延迟数组，单位为毫秒（默认值：`[30000, 60000, 300000]`；1–10 个条目）。
- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则会重试所有暂时性类型。
+- `maxAttempts`：一次性任务在瞬时错误下的最大重试次数（默认值：`3`；范围：`0`–`10`）。
+- `backoffMs`：每次重试尝试对应的回退延迟数组（毫秒）（默认值：`[30000, 60000, 300000]`；1–10 个条目）。
+- `retryOn`：触发重试的错误类型——`"rate_limit"`、`"overloaded"`、`"network"`、`"timeout"`、`"server_error"`。省略则重试所有瞬时类型。

-仅适用于一次性 cron 作业。周期性作业使用单独的失败处理方式。
+仅适用于一次性 cron 任务。周期性任务使用单独的失败处理机制。

 ### `cron.failureAlert`

@ -1108,11 +1113,11 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- `enabled`：启用 cron 作业失败告警（默认值：`false`）。
- `after`：连续失败多少次后触发告警（正整数，最小值：`1`）。
- `cooldownMs`：同一作业重复告警之间的最小毫秒间隔（非负整数）。
+- `enabled`：为 cron 任务启用失败告警（默认值：`false`）。
+- `after`：在触发告警前的连续失败次数（正整数，最小值：`1`）。
+- `cooldownMs`：同一任务重复告警之间的最小间隔（毫秒）（非负整数）。
 - `mode`：投递模式——`"announce"` 通过渠道消息发送；`"webhook"` 向已配置的 webhook 发送 POST。
- `accountId`：用于限定告警投递范围的可选账号或渠道 id。
+- `accountId`：可选的账号或渠道 id，用于限定告警投递范围。

 ### `cron.failureDestination`

@ -1129,16 +1134,16 @@ SecretRef 是增量式支持的：明文值仍然可用。
 }
 ```

- 所有作业共享的 cron 失败通知默认目标。
- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认值为 `"announce"`。
- `channel`：announce 投递的渠道覆盖值。`"last"` 会复用最后一次已知投递渠道。
+- 所有任务共用的 cron 失败通知默认目标。
+- `mode`：`"announce"` 或 `"webhook"`；当存在足够的目标数据时，默认使用 `"announce"`。
+- `channel`：announce 投递的渠道覆盖值。`"last"` 会复用上次已知的投递渠道。
 - `to`：显式的 announce 目标或 webhook URL。webhook 模式下为必填。
 - `accountId`：可选的投递账号覆盖值。
- 每个作业的 `delivery.failureDestination` 会覆盖此全局默认值。
- 当既未设置全局也未设置每作业失败目标时，那些已通过 `announce` 投递的作业在失败时会回退到其主 announce 目标。
- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的作业，除非该作业的主 `delivery.mode` 为 `"webhook"`。
+- 单个任务的 `delivery.failureDestination` 会覆盖该全局默认值。
+- 当全局和单任务失败目标都未设置时，已经通过 `announce` 投递的任务在失败时会回退到其主 announce 目标。
+- `delivery.failureDestination` 仅支持 `sessionTarget="isolated"` 的任务，除非该任务的主 `delivery.mode` 为 `"webhook"`。

-请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)。独立的 cron 执行会作为[后台任务](/zh-CN/automation/tasks)进行跟踪。
+请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。隔离的 cron 执行会作为 [后台任务](/zh-CN/automation/tasks) 跟踪。

 ---

@ -1146,34 +1151,34 @@ SecretRef 是增量式支持的：明文值仍然可用。

 在 `tools.media.models[].args` 中展开的模板占位符：

-| Variable           | 说明 |
-| ------------------ | ---- |
-| `{{Body}}`         | 完整的入站消息正文 |
-| `{{RawBody}}`      | 原始正文（不含历史 / 发送者包装） |
-| `{{BodyStripped}}` | 去除群组提及后的正文 |
-| `{{From}}`         | 发送者标识符 |
-| `{{To}}`           | 目标标识符 |
-| `{{MessageSid}}`   | 渠道消息 id |
-| `{{SessionId}}`    | 当前会话 UUID |
-| `{{IsNewSession}}` | 新建会话时为 `"true"` |
-| `{{MediaUrl}}`     | 入站媒体伪 URL |
-| `{{MediaPath}}`    | 本地媒体路径 |
-| `{{MediaType}}`    | 媒体类型（image/audio/document/…） |
-| `{{Transcript}}`   | 音频转录文本 |
-| `{{Prompt}}`       | CLI 条目的已解析媒体提示词 |
-| `{{MaxChars}}`     | CLI 条目的已解析最大输出字符数 |
-| `{{ChatType}}`     | `"direct"` 或 `"group"` |
-| `{{GroupSubject}}` | 群组主题（尽力而为） |
-| `{{GroupMembers}}` | 群组成员预览（尽力而为） |
-| `{{SenderName}}`   | 发送者显示名称（尽力而为） |
-| `{{SenderE164}}`   | 发送者电话号码（尽力而为） |
+| Variable           | 描述                                       |
+| ------------------ | ------------------------------------------------- |
+| `{{Body}}`         | 完整的传入消息正文                         |
+| `{{RawBody}}`      | 原始正文（无历史记录/发送者包装）             |
+| `{{BodyStripped}}` | 已去除群组提及的正文                 |
+| `{{From}}`         | 发送者标识符                                 |
+| `{{To}}`           | 目标标识符                            |
+| `{{MessageSid}}`   | 渠道消息 id                                |
+| `{{SessionId}}`    | 当前会话 UUID                              |
+| `{{IsNewSession}}` | 创建新会话时为 `"true"`                 |
+| `{{MediaUrl}}`     | 传入媒体伪 URL                          |
+| `{{MediaPath}}`    | 本地媒体路径                                  |
+| `{{MediaType}}`    | 媒体类型（image/audio/document/…）               |
+| `{{Transcript}}`   | 音频转录内容                                  |
+| `{{Prompt}}`       | CLI 条目的已解析媒体提示词             |
+| `{{MaxChars}}`     | CLI 条目的已解析最大输出字符数         |
+| `{{ChatType}}`     | `"direct"` 或 `"group"`                           |
+| `{{GroupSubject}}` | 群组主题（尽力而为）                       |
+| `{{GroupMembers}}` | 群组成员预览（尽力而为）               |
+| `{{SenderName}}`   | 发送者显示名称（尽力而为）                 |
+| `{{SenderE164}}`   | 发送者电话号码（尽力而为）                 |
 | `{{Provider}}`     | 提供商提示（whatsapp、telegram、discord 等） |

 ---

-## 配置 include（`$include`）
+## 配置包含（`$include`）

-将配置拆分到多个文件中：
+将配置拆分为多个文件：

 ```json5
 // ~/.openclaw/openclaw.json
@ -1188,14 +1193,14 @@ SecretRef 是增量式支持的：明文值仍然可用。

 **合并行为：**

- 单个文件：替换其所在的包含对象。
- 文件数组：按顺序进行深度合并（后者覆盖前者）。
- 同级键：在 include 之后合并（覆盖 include 中的值）。
- 嵌套 include：最多 10 层。
- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径 / `../` 形式最终解析后仍位于该边界内时，才允许使用。
- 由 OpenClaw 发起、且只更改由单文件 include 支持的某一个顶层 section 的写入，会直接写回该 include 文件。例如，`plugins install` 会将 `plugins: { $include: "./plugins.json5" }` 的更新写入 `plugins.json5`，并保持 `openclaw.json` 不变。
- 根级 include、include 数组，以及带有同级覆盖的 include，对于由 OpenClaw 发起的写入来说是只读的；这些写入会以关闭方式失败，而不会将配置展平。
- 错误：对于缺失文件、解析错误和循环 include，都有清晰的报错信息。
+- 单个文件：替换其所在的对象。
+- 文件数组：按顺序深度合并（后者覆盖前者）。
+- 同级键：在包含项之后合并（覆盖已包含的值）。
+- 嵌套包含：最多 10 层。
+- 路径：相对于包含它的文件解析，但必须保持在顶层配置目录（`openclaw.json` 的 `dirname`）内。仅当绝对路径/`../` 形式最终仍解析到该边界内时才允许。
+- 当 OpenClaw 自有写入仅变更一个由单文件 include 支持的顶层 section 时，会直接写回该包含文件。例如，`plugins install` 会更新 `plugins: { $include: "./plugins.json5" }` 中的 `plugins.json5`，并保持 `openclaw.json` 不变。
+- 根级 includes、include 数组，以及带有同级覆盖的 includes 对 OpenClaw 自有写入来说是只读的；这些写入会以关闭方式失败，而不是将配置拍平。
+- 错误：对缺失文件、解析错误和循环包含提供清晰的错误消息。

 ---

--- a/docs/zh-CN/gateway/configuration.md
+++ b/docs/zh-CN/gateway/configuration.md
@ -2,32 +2,34 @@
 read_when:
    - 首次设置 OpenClaw
    - 查找常见配置模式
-    - 导航到特定配置章节
-summary: 配置概览：常见任务、快速设置，以及完整参考的链接
+    - 前往特定配置章节
+summary: 配置概览：常见任务、快速设置，以及指向完整参考的链接
 title: 配置
 x-i18n:
-    generated_at: "2026-04-25T03:24:36Z"
+    generated_at: "2026-04-25T07:51:43Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 2749fca881115d1d1915271af2d06037cfe87d6c4caf96dc46d8bf893a0669c6
+    source_hash: a8ffe1972fc7680d4cfc55a24fd6fc3869af593faf8c1137369dad0dbefde43a
    source_path: gateway/configuration.md
    workflow: 15
 ---

-OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
-生效的配置路径必须是常规文件。对于由 OpenClaw 管理的写入操作，不支持使用符号链接的 `openclaw.json`
-布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
+OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置文件。
+当前生效的配置路径必须是普通文件。对于由 OpenClaw 管理的写入操作，不支持将 `openclaw.json`
+设为符号链接；原子写入可能会替换该路径，
+而不是保留符号链接。如果你将配置保存在默认状态目录之外，
+请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。

-如果文件缺失，OpenClaw 会使用安全默认值。添加配置的常见原因包括：
+如果该文件不存在，OpenClaw 会使用安全默认值。常见的添加配置原因包括：

- 连接渠道并控制谁可以向机器人发送消息
+- 连接渠道，并控制谁可以向机器人发送消息
 - 设置模型、工具、沙箱隔离或自动化（cron、hooks）
 - 调整会话、媒体、网络或 UI

 请参阅[完整参考](/zh-CN/gateway/configuration-reference)了解所有可用字段。

 <Tip>
-**刚接触配置？** 可先使用 `openclaw onboard` 进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南，获取可直接复制粘贴的完整配置。
+**刚开始接触配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [Configuration Examples](/zh-CN/gateway/configuration-examples) 指南，获取可直接复制粘贴的完整配置。
 </Tip>

 ## 最小配置
@ -57,53 +59,54 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5
    ```
  </Tab>
  <Tab title="Control UI">
-    打开 [http://127.0.0.1:18789](http://127.0.0.1:18789) 并使用 **配置** 标签页。
-    Control UI 会根据实时配置 schema 渲染表单，其中包含字段
-    `title` / `description` 文档元数据，以及可用时的插件和渠道 schema，
-    同时提供 **Raw JSON** 编辑器作为兜底方案。对于下钻式
-    UI 和其他工具，Gateway 网关 还提供 `config.schema.lookup`，
-    用于获取单个路径范围的 schema 节点及其直接子节点摘要。
+    打开 [http://127.0.0.1:18789](http://127.0.0.1:18789) 并使用 **配置** 选项卡。
+    Control UI 会根据实时配置 schema 渲染表单，其中包括字段
+    `title` / `description` 文档元数据，以及在可用时包含插件和渠道 schema，
+    并提供 **Raw JSON** 编辑器作为兜底方式。对于下钻式
+    UI 和其他工具，网关还提供 `config.schema.lookup`，
+    用于获取单个路径范围内的 schema 节点及其直接子节点摘要。
  </Tab>
  <Tab title="直接编辑">
-    直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关 会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
+    直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
  </Tab>
 </Tabs>

 ## 严格校验

 <Warning>
-OpenClaw 仅接受完全匹配 schema 的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关 **拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。
+OpenClaw 只接受完全匹配 schema 的配置。未知键、错误类型或无效值都会导致 Gateway 网关**拒绝启动**。根级别唯一的例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。
 </Warning>

-`openclaw config schema` 会打印供 Control UI
-和校验使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径范围节点及其
-子节点摘要，用于下钻式工具。字段 `title`/`description` 的文档元数据
-会贯穿嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/
-`oneOf`/`allOf` 分支。运行时插件和渠道 schema 会在
-manifest 注册表加载后合并进来。
+`openclaw config schema` 会打印 Control UI
+和校验所使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径范围内的节点及其
+子节点摘要，供下钻式工具使用。字段 `title`/`description` 文档元数据
+会延续到嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/
+`oneOf`/`allOf` 分支中。加载 manifest 注册表后，
+运行时插件和渠道 schema 也会合并进来。

 当校验失败时：

- Gateway 网关 不会启动
+- Gateway 网关不会启动
 - 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`）
 - 运行 `openclaw doctor` 查看具体问题
- 运行 `openclaw doctor --fix`（或 `--yes`）应用修复
+- 运行 `openclaw doctor --fix`（或 `--yes`）以应用修复

-Gateway 网关 在每次成功启动后都会保留一份可信的最近一次正常配置副本。
-如果之后 `openclaw.json` 校验失败（或丢失 `gateway.mode`、明显缩小、
-或前面意外插入了一行日志），OpenClaw 会将损坏的文件保留为
-`.clobbered.*`，恢复最近一次正常配置副本，并记录恢复原因。
-下一次智能体回合还会收到系统事件警告，这样主智能体就不会盲目重写已恢复的配置。
-如果候选配置包含诸如 `***` 之类的已脱敏密钥占位符，则不会将其提升为最近一次正常配置。
+每次成功启动后，Gateway 网关都会保留一份可信的最近一次正确副本。
+如果之后 `openclaw.json` 校验失败（或缺少 `gateway.mode`、内容
+明显缩小，或文件开头意外插入了一行日志），OpenClaw 会将损坏文件
+保存为 `.clobbered.*`，恢复最近一次正确副本，并记录恢复原因。
+下一次智能体轮次还会收到系统事件警告，这样主智能体
+就不会盲目重写已恢复的配置。当候选配置包含已脱敏的密钥占位符（例如 `***`）时，
+不会将其提升为最近一次正确副本。
 当所有校验问题都限定在 `plugins.entries.<id>...` 范围内时，OpenClaw
-不会执行整文件恢复。它会保持当前配置继续生效，并显示插件局部失败，
-这样插件 schema 或宿主版本不匹配就不会回滚无关的用户设置。
+不会执行整文件恢复。它会保留当前配置继续生效，并暴露插件局部失败，
+这样插件 schema 或主机版本不匹配就不会回滚其他无关的用户设置。

 ## 常见任务

 <AccordionGroup>
  <Accordion title="设置一个渠道（WhatsApp、Telegram、Discord 等）">
-    每个渠道在 `channels.<provider>` 下都有自己的配置章节。设置步骤请参阅对应渠道页面：
+    每个渠道在 `channels.<provider>` 下都有自己的配置区段。设置步骤请参阅对应的专用渠道页面：

    - [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp`
    - [Telegram](/zh-CN/channels/telegram) — `channels.telegram`
@ -116,7 +119,7 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    - [iMessage](/zh-CN/channels/imessage) — `channels.imessage`
    - [Mattermost](/zh-CN/channels/mattermost) — `channels.mattermost`

-    所有渠道都共享相同的私信策略模式：
+    所有渠道共享相同的私信策略模式：

    ```json5
    {
@ -134,7 +137,7 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
  </Accordion>

  <Accordion title="选择并配置模型">
-    设置主模型以及可选的回退模型：
+    设置主模型和可选回退模型：

    ```json5
    {
@ -153,31 +156,31 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    }
    ```

-    - `agents.defaults.models` 定义模型目录，并充当 `/model` 的 allowlist。
-    - 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加 allowlist 条目，而不会移除现有模型。若普通替换会移除条目，则会被拒绝，除非你传入 `--replace`。
+    - `agents.defaults.models` 定义模型目录，并作为 `/model` 的 allowlist。
+    - 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 可在不移除现有模型的情况下添加 allowlist 条目。普通替换如果会移除条目，则会被拒绝，除非你传入 `--replace`。
    - 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
-    - `agents.defaults.imageMaxDimensionPx` 控制转录/工具图像的缩放下限（默认 `1200`）；较低的值通常会在大量截图的运行中减少视觉 token 使用量。
-    - 请参阅[Models CLI](/zh-CN/concepts/models)了解如何在聊天中切换模型，并参阅[模型故障切换](/zh-CN/concepts/model-failover)了解凭证轮换和回退行为。
-    - 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
+    - `agents.defaults.imageMaxDimensionPx` 控制转录记录/工具图像的缩放上限（默认 `1200`）；较低的值通常会减少截图较多运行中的视觉 token 使用量。
+    - 关于在聊天中切换模型，请参阅 [Models CLI](/zh-CN/concepts/models)；关于凭证轮换和回退行为，请参阅 [Model Failover](/zh-CN/concepts/model-failover)。
+    - 对于自定义/自托管提供商，请参阅参考中的 [Custom providers](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。

  </Accordion>

  <Accordion title="控制谁可以向机器人发送消息">
-    私信访问权限通过每个渠道的 `dmPolicy` 控制：
+    私信访问通过每个渠道的 `dmPolicy` 控制：

-    - `"pairing"`（默认）：未知发送者会收到一个一次性配对码以供批准
+    - `"pairing"`（默认）：未知发送者会收到一次性配对码以供批准
    - `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对的允许存储）
    - `"open"`：允许所有传入私信（要求 `allowFrom: ["*"]`）
    - `"disabled"`：忽略所有私信

    对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的 allowlist。

-    请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)了解各渠道的详细信息。
+    每个渠道的详细信息请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)。

  </Accordion>

  <Accordion title="设置群聊提及门控">
-    群组消息默认**要求提及**。可按智能体配置模式：
+    群消息默认**要求提及**。可按智能体配置模式：

    ```json5
    {
@ -201,12 +204,12 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次

    - **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
    - **文本模式**：`mentionPatterns` 中的安全正则模式
-    - 请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)了解各渠道覆盖项和自聊模式。
+    - 每个渠道的覆盖项和自聊模式请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)。

  </Accordion>

  <Accordion title="按智能体限制 Skills">
-    对共享基线使用 `agents.defaults.skills`，然后通过 `agents.list[].skills` 覆盖特定
+    使用 `agents.defaults.skills` 作为共享基线，然后通过 `agents.list[].skills` 覆盖特定
    智能体：

    ```json5
@ -224,16 +227,16 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    }
    ```

-    - 省略 `agents.defaults.skills` 则默认 Skills 不受限制。
-    - 省略 `agents.list[].skills` 则继承默认值。
-    - 设置 `agents.list[].skills: []` 表示不启用任何 Skills。
+    - 若默认不限制 Skills，请省略 `agents.defaults.skills`。
+    - 若要继承默认值，请省略 `agents.list[].skills`。
+    - 将 `agents.list[].skills: []` 设为空即可禁用所有 Skills。
    - 请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及
-      [配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。
+      [Configuration Reference](/zh-CN/gateway/config-agents#agents-defaults-skills)。

  </Accordion>

  <Accordion title="调整网关渠道健康监控">
-    控制网关对看起来已停滞渠道的重启激进程度：
+    控制网关对看起来陈旧的渠道执行重启的积极程度：

    ```json5
    {
@ -255,14 +258,14 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    }
    ```

-    - 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。
+    - 将 `gateway.channelHealthCheckMinutes: 0` 设为 0，可全局禁用健康监控重启。
    - `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。
-    - 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled`，可只为某一个渠道或账户禁用自动重启，而无需关闭全局监控。
-    - 请参阅[健康检查](/zh-CN/gateway/health)了解运维调试，并参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。
+    - 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled`，可仅为某个渠道或账户禁用自动重启，而不禁用全局监控。
+    - 关于运维调试，请参阅 [Health Checks](/zh-CN/gateway/health)；关于所有字段，请参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)。

  </Accordion>

-  <Accordion title="配置会话与重置">
+  <Accordion title="配置会话和重置">
    会话控制对话连续性和隔离性：

    ```json5
@ -283,10 +286,10 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    }
    ```

-    - `dmScope`: `main`（共享） | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
+    - `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
    - `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
-    - 请参阅[会话管理](/zh-CN/concepts/session)了解作用域、身份关联和发送策略。
-    - 请参阅[完整参考](/zh-CN/gateway/config-agents#session)了解所有字段。
+    - 关于作用域、身份链接和发送策略，请参阅 [Session Management](/zh-CN/concepts/session)。
+    - 关于所有字段，请参阅[完整参考](/zh-CN/gateway/config-agents#session)。

  </Accordion>

@ -308,14 +311,14 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次

    请先构建镜像：`scripts/sandbox-setup.sh`

-    请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)了解完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。
+    完整指南请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)，所有选项请参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)。

  </Accordion>

  <Accordion title="为官方 iOS 构建启用基于 relay 的推送">
    基于 relay 的推送在 `openclaw.json` 中配置。

-    在 Gateway 网关 配置中设置以下内容：
+    在网关配置中设置以下内容：

    ```json5
    {
@ -324,7 +327,7 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
          apns: {
            relay: {
              baseUrl: "https://relay.example.com",
-              // 可选。默认值：10000
+              // Optional. Default: 10000
              timeoutMs: 10000,
            },
          },
@ -333,43 +336,43 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    }
    ```

-    对应的 CLI 写法：
+    等效 CLI：

    ```bash
    openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
    ```

-    其作用如下：
+    作用如下：

-    - 让网关可以通过外部 relay 发送 `push.test`、唤醒提示以及重连唤醒。
-    - 使用由已配对 iOS 应用转发的、按注册范围限定的发送授权。Gateway 网关 不需要部署范围的 relay token。
-    - 将每个基于 relay 的注册绑定到 iOS 应用所配对的 Gateway 网关 身份，因此其他网关无法复用已存储的注册。
-    - 本地/手动构建的 iOS 版本仍然直接使用 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发版本。
+    - 让网关能够通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。
+    - 使用由已配对 iOS 应用转发的注册级发送授权。网关不需要部署范围的 relay token。
+    - 将每个基于 relay 的注册绑定到 iOS 应用配对时所对应的网关身份，因此其他网关无法复用已存储的注册信息。
+    - 本地/手动构建的 iOS 版本仍然使用直接 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发版本。
    - 必须与官方/TestFlight iOS 构建中内置的 relay 基础 URL 一致，这样注册和发送流量才能到达同一个 relay 部署。

    端到端流程：

    1. 安装一个使用相同 relay 基础 URL 编译的官方/TestFlight iOS 构建。
    2. 在网关上配置 `gateway.push.apns.relay.baseUrl`。
-    3. 将 iOS 应用与网关配对，并让节点会话和操作员会话都连接成功。
-    4. iOS 应用会获取网关身份，使用 App Attest 和应用回执向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的网关。
-    5. Gateway 网关 会存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。
+    3. 将 iOS 应用与网关配对，并让节点会话和操作员会话都建立连接。
+    4. iOS 应用获取网关身份，使用 App Attest 和应用收据向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的网关。
+    5. 网关存储 relay 句柄和发送授权，然后将其用于 `push.test`、唤醒提示和重连唤醒。

    运维说明：

-    - 如果你将 iOS 应用切换到另一个网关，请重新连接该应用，以便它发布一个绑定到该网关的新 relay 注册。
+    - 如果你将 iOS 应用切换到另一个网关，请重新连接该应用，以便它能够发布绑定到该网关的新 relay 注册。
    - 如果你发布了一个指向不同 relay 部署的新 iOS 构建，应用会刷新其缓存的 relay 注册，而不是复用旧的 relay 来源。

    兼容性说明：

-    - `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。
-    - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然只是一个仅限 local loopback 的开发兜底方案；不要在配置中持久化 HTTP relay URL。
+    - `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍然可作为临时环境变量覆盖项使用。
+    - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然是仅限 loopback 的开发逃生开关；不要在配置中持久保存 HTTP relay URL。

-    请参阅[iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[认证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解 relay 安全模型。
+    关于端到端流程，请参阅 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)；关于 relay 安全模型，请参阅 [Authentication and trust flow](/zh-CN/platforms/ios#authentication-and-trust-flow)。

  </Accordion>

-  <Accordion title="设置 heartbeat（定期 check-in）">
+  <Accordion title="设置心跳（定期检查）">
    ```json5
    {
      agents: {
@ -383,9 +386,9 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    }
    ```

-    - `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。
+    - `every`：时长字符串（`30m`、`2h`）。设为 `0m` 可禁用。
    - `target`：`last` | `none` | `<channel-id>`（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`）
-    - `directPolicy`：用于私信风格 heartbeat 目标的 `allow`（默认）或 `block`
+    - `directPolicy`：对于私信风格的心跳目标，可设为 `allow`（默认）或 `block`
    - 完整指南请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。

  </Accordion>
@ -405,14 +408,14 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    }
    ```

-    - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。
+    - `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设为 `false` 可禁用）。
    - `runLog`：按大小和保留行数清理 `cron/runs/<jobId>.jsonl`。
-    - 功能概览和 CLI 示例请参阅[cron 作业](/zh-CN/automation/cron-jobs)。
+    - 功能概览和 CLI 示例请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)。

  </Accordion>

  <Accordion title="设置 webhook（hooks）">
-    在 Gateway 网关 上启用 HTTP webhook 端点：
+    在 Gateway 网关上启用 HTTP webhook 端点：

    ```json5
    {
@ -436,20 +439,20 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    ```

    安全说明：
-    - 将所有 hook/webhook 负载内容都视为不受信任输入。
+    - 将所有 hook/webhook 负载内容视为不可信输入。
    - 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关 token。
    - Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 会被拒绝。
-    - `hooks.path` 不能是 `/`；请将 webhook 入口保持在专用子路径下，例如 `/hooks`。
-    - 保持不安全内容绕过标志关闭（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非你是在进行严格限定范围的调试。
-    - 如果你启用了 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes` 来限制调用方可选的会话键。
-    - 对于由 hook 驱动的智能体，优先选择更强的现代模型层级和严格的工具策略（例如仅消息传递，并尽可能启用沙箱隔离）。
+    - `hooks.path` 不能是 `/`；请将 webhook 入口保留在专用子路径下，例如 `/hooks`。
+    - 保持不安全内容绕过标志处于禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非你是在进行严格限定范围的调试。
+    - 如果你启用了 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选的 session key。
+    - 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格工具策略（例如仅消息传递，并尽可能启用沙箱隔离）。

    所有映射选项和 Gmail 集成请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)。

  </Accordion>

  <Accordion title="配置多智能体路由">
-    运行多个彼此隔离、拥有独立工作区和会话的智能体：
+    运行多个相互隔离的智能体，并为它们设置独立工作区和会话：

    ```json5
    {
@ -466,11 +469,11 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    }
    ```

-    绑定规则和每个智能体的访问配置请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)。
+    绑定规则和每个智能体的访问配置请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)。

  </Accordion>

-  <Accordion title="将配置拆分为多个文件（$include）">
+  <Accordion title="将配置拆分到多个文件中（$include）">
    使用 `$include` 组织大型配置：

    ```json5
@ -484,48 +487,48 @@ Gateway 网关 在每次成功启动后都会保留一份可信的最近一次
    }
    ```

-    - **单文件**：替换所在的整个对象
-    - **文件数组**：按顺序深度合并（后者优先）
-    - **同级键**：在 include 之后合并（覆盖已包含的值）
-    - **嵌套 include**：支持，最多 10 层
+    - **单个文件**：替换包含它的对象
+    - **文件数组**：按顺序深度合并（后者覆盖前者）
+    - **同级键**：在 include 之后合并（覆盖被包含的值）
+    - **嵌套 include**：最多支持 10 层嵌套
    - **相对路径**：相对于包含它的文件解析
-    - **由 OpenClaw 管理的写入**：当某次写入仅更改单个顶层部分，
-      且该部分由单文件 include 支持，例如 `plugins: { $include: "./plugins.json5" }`，
+    - **由 OpenClaw 管理的写入**：当一次写入只修改一个由单文件 include
+      支持的顶层区段时，例如 `plugins: { $include: "./plugins.json5" }`，
      OpenClaw 会更新该被包含文件，并保持 `openclaw.json` 不变
    - **不支持的透传写入**：根级 include、include 数组，以及带有
-      同级覆盖的 include，在由 OpenClaw 管理的写入中会以失败关闭，而不是
-      将配置拍平成单个文件
-    - **错误处理**：对缺失文件、解析错误和循环 include 提供明确错误信息
+      同级覆盖项的 include，在由 OpenClaw 管理的写入中会以封闭失败方式处理，
+      而不是将配置拍平
+    - **错误处理**：对于缺失文件、解析错误和循环 include，会提供清晰错误

  </Accordion>
 </AccordionGroup>

 ## 配置热重载

-Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——大多数设置都不需要手动重启。
+Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——大多数设置都不需要手动重启。

-直接编辑文件会被视为不受信任，直到通过校验为止。监视器会等待
-编辑器临时写入/重命名的抖动稳定下来，读取最终文件，并通过恢复
-最近一次正常配置来拒绝无效的外部编辑。由 OpenClaw 管理的
-配置写入在写入前也会通过相同的 schema 闸门；像删除 `gateway.mode`
-或将文件缩小到原来一半以下这类破坏性覆盖会被拒绝，
+直接编辑文件会在通过校验前被视为不可信。监视器会等待
+编辑器的临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复最近一次正确配置
+来拒绝无效的外部编辑。由 OpenClaw 管理的
+配置写入在写入前也会经过相同的 schema 校验；像删除 `gateway.mode` 或将文件缩小超过一半
+这样的破坏性覆盖会被拒绝，
 并保存为 `.rejected.*` 以供检查。

 插件局部校验失败是例外：如果所有问题都位于
-`plugins.entries.<id>...` 之下，重载会保持当前配置并报告该插件问题，
+`plugins.entries.<id>...` 下，重载会保留当前配置并报告插件问题，
 而不是恢复 `.last-good`。

 如果你在日志中看到 `Config auto-restored from last-known-good` 或
-`config reload restored last-known-good config`，请检查 `openclaw.json`
-旁边对应的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行
-`openclaw config validate`。恢复检查清单请参阅[Gateway 网关 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
+`config reload restored last-known-good config`，请检查与之对应的
+位于 `openclaw.json` 旁边的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行
+`openclaw config validate`。恢复检查清单请参阅 [Gateway 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。

 ### 重载模式

 | 模式 | 行为 |
 | ---------------------- | --------------------------------------------------------------------------------------- |
 | **`hybrid`**（默认） | 立即热应用安全更改。对于关键更改会自动重启。 |
-| **`hot`** | 仅热应用安全更改。需要重启时会记录警告——由你来处理。 |
+| **`hot`** | 只热应用安全更改。当需要重启时记录警告——由你自行处理。 |
 | **`restart`** | 任何配置更改都会重启 Gateway 网关，无论是否安全。 |
 | **`off`** | 禁用文件监视。更改会在下次手动重启时生效。 |

@ -539,17 +542,17 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——

 ### 哪些可以热应用，哪些需要重启

-大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。
+大多数字段都可以在不停机的情况下热应用。在 `hybrid` 模式下，需要重启的更改会被自动处理。

 | 类别 | 字段 | 需要重启？ |
 | ------------------- | ----------------------------------------------------------------- | --------------- |
-| 渠道 | `channels.*`、`web`（WhatsApp）——所有内置渠道和渠道插件 | 否 |
-| 智能体与模型 | `agent`、`agents`、`models`、`routing` | 否 |
+| 渠道 | `channels.*`、`web`（WhatsApp）——所有内置和插件渠道 | 否 |
+| 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 |
 | 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 |
-| 会话与消息 | `session`、`messages` | 否 |
-| 工具与媒体 | `tools`、`browser`、`skills`、`audio`、`talk` | 否 |
-| UI 与杂项 | `ui`、`logging`、`identity`、`bindings` | 否 |
-| Gateway 网关 服务器 | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **是** |
+| 会话和消息 | `session`、`messages` | 否 |
+| 工具和媒体 | `tools`、`browser`、`skills`、`mcp`、`audio`、`talk` | 否 |
+| UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 |
+| Gateway 网关服务器 | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **是** |
 | 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** |

 <Note>
@ -558,32 +561,32 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——

 ### 重载规划

-当你编辑一个通过 `$include` 引用的源文件时，OpenClaw 会根据源文件作者编写的布局
+当你编辑通过 `$include` 引用的源文件时，OpenClaw 会根据源文件编写时的布局
 来规划重载，而不是根据已拍平的内存视图。
 这样即使某个
-单独的顶层部分位于其自己的包含文件中，例如
-`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用还是重启）也仍然可预测。
-如果源布局存在歧义，重载规划会以失败关闭。
+单独的顶层区段位于自己的被包含文件中，例如
+`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用还是重启）也能保持可预测。
+如果源布局存在歧义，重载规划会以封闭失败方式处理。

-## Config RPC（程序化更新）
+## 配置 RPC（程序化更新）

-对于通过 Gateway 网关 API 写入配置的工具，建议优先使用以下流程：
+对于通过网关 API 写入配置的工具，建议使用以下流程：

 - 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子节点
  摘要）
- 使用 `config.get` 获取当前快照以及 `hash`
+- 使用 `config.get` 获取当前快照和 `hash`
 - 使用 `config.patch` 进行部分更新（JSON merge patch：对象合并，`null`
-  删除，数组整体替换）
+  删除，数组替换）
 - 仅当你确实打算替换整个配置时才使用 `config.apply`
 - 使用 `update.run` 执行显式自更新并重启

 <Note>
-控制平面写入（`config.apply`、`config.patch`、`update.run`）会按
-每个 `deviceId+clientIp` 在 60 秒内限制为 3 次请求。
-重启请求会被合并，然后在两次重启周期之间强制 30 秒冷却时间。
+控制平面写入（`config.apply`、`config.patch`、`update.run`）会
+按每个 `deviceId+clientIp` 在 60 秒内限制为 3 次请求。
+重启请求会合并处理，然后在两次重启周期之间强制执行 30 秒冷却时间。
 </Note>

-部分 patch 示例：
+部分补丁示例：

 ```bash
 openclaw gateway call config.get --params '{}'  # capture payload.hash
@ -599,7 +602,7 @@ openclaw gateway call config.patch --params '{

 ## 环境变量

-OpenClaw 会从父进程读取环境变量，另外还会读取：
+OpenClaw 会从父进程读取环境变量，此外还会读取：

 - 当前工作目录中的 `.env`（如果存在）
 - `~/.openclaw/.env`（全局回退）
@ -615,8 +618,8 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
 }
 ```

-<Accordion title="导入 shell 环境变量（可选）">
-  如果启用且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名：
+<Accordion title="导入 Shell 环境变量（可选）">
+  如果启用，并且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键：

 ```json5
 {
@ -626,7 +629,7 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
 }
 ```

-对应的环境变量：`OPENCLAW_LOAD_SHELL_ENV=1`
+环境变量等价形式：`OPENCLAW_LOAD_SHELL_ENV=1`
 </Accordion>

 <Accordion title="在配置值中替换环境变量">
@ -642,14 +645,14 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
 规则：

 - 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`
- 缺失或为空的环境变量会在加载时报错
- 使用 `$${VAR}` 转义以输出字面量
- 在 `$include` 文件中也可用
+- 缺失或为空的变量会在加载时报错
+- 使用 `$${VAR}` 可输出字面量
+- 在 `$include` 文件中同样有效
 - 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"`

 </Accordion>

-<Accordion title="SecretRef（env、file、exec）">
+<Accordion title="密钥引用（env、file、exec）">
  对于支持 SecretRef 对象的字段，你可以使用：

 ```json5
@ -682,22 +685,22 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
 }
 ```

-SecretRef 详情（包括适用于 `env`/`file`/`exec` 的 `secrets.providers`）见[密钥管理](/zh-CN/gateway/secrets)。
-支持的凭证路径列于 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)。
+有关 SecretRef 的详细信息（包括用于 `env`/`file`/`exec` 的 `secrets.providers`），请参阅 [Secrets Management](/zh-CN/gateway/secrets)。
+支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。
 </Accordion>

-完整的优先级和来源请参阅[环境](/zh-CN/help/environment)。
+完整的优先级和来源请参阅 [Environment](/zh-CN/help/environment)。

 ## 完整参考

-如需完整的逐字段参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。
+如需完整的逐字段参考，请参阅 **[Configuration Reference](/zh-CN/gateway/configuration-reference)**。

 ---

-_相关内容：[配置示例](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_
+_相关内容：[Configuration Examples](/zh-CN/gateway/configuration-examples) · [Configuration Reference](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_

-## 相关
+## 相关内容

- [配置参考](/zh-CN/gateway/configuration-reference)
- [配置示例](/zh-CN/gateway/configuration-examples)
- [Gateway 网关 运行手册](/zh-CN/gateway)
+- [Configuration reference](/zh-CN/gateway/configuration-reference)
+- [Configuration examples](/zh-CN/gateway/configuration-examples)
+- [Gateway 网关运行手册](/zh-CN/gateway)
--- a/docs/zh-CN/nodes/talk.md
+++ b/docs/zh-CN/nodes/talk.md
@ -1,36 +1,36 @@
 ---
 read_when:
    - 在 macOS/iOS/Android 上实现通话模式
-    - 更改语音/TTS/打断行为
-summary: 通话模式：使用 ElevenLabs TTS 的连续语音对话
+    - 更改语音 / TTS / 打断行为
+summary: 通话模式：与已配置的 TTS 提供商进行连续语音对话
 title: 通话模式
 x-i18n:
-    generated_at: "2026-04-23T22:59:08Z"
+    generated_at: "2026-04-25T07:51:42Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 49286cd39a104d4514eb1df75627a2f64182313b11792bb246f471178a702198
+    source_hash: 84c99149c43bfe9fa4866b20271089d88d7e3d2f5abe6d16477a26915dad7829
    source_path: nodes/talk.md
    workflow: 15
 ---

-通话模式是一个连续语音对话循环：
+通话模式是一个连续的语音对话循环：

 1. 监听语音
-2. 将转写结果发送给模型（主会话，`chat.send`）
-3. 等待回复
-4. 通过已配置的 Talk 提供商朗读回复（`talk.speak`）
+2. 将转录文本发送给模型（主会话，`chat.send`）
+3. 等待响应
+4. 通过已配置的通话提供商播报响应（`talk.speak`）

 ## 行为（macOS）

- 启用通话模式时，显示**常驻悬浮层**。
- **Listening → Thinking → Speaking** 阶段切换。
- 在**短暂停顿**（静音窗口）时，会发送当前转写内容。
- 回复会**写入 WebChat**（与键入时相同）。
- **语音打断**（默认开启）：如果助手正在说话时用户开始说话，我们会停止播放，并为下一次提示记录打断时间戳。
+- 启用通话模式后，会显示**常驻覆盖层**。
+- 在**监听 → 思考 → 播报**阶段之间切换。
+- 当出现**短暂停顿**（静音窗口）时，会发送当前转录文本。
+- 回复会被**写入 WebChat**（与手动输入相同）。
+- **语音打断**（默认开启）：如果助手正在播报时用户开始说话，我们会停止播放，并为下一个提示记录打断时间戳。

 ## 回复中的语音指令

-助手可以在回复开头添加**单行 JSON** 来控制语音：
+助手可以在回复前添加**单独的一行 JSON** 来控制语音：

 ```json
 { "voice": "<voice-id>", "once": true }
@ -38,18 +38,18 @@ x-i18n:

 规则：

- 仅首个非空行有效。
+- 仅第一行非空行有效。
 - 未知键会被忽略。
 - `once: true` 仅应用于当前这条回复。
 - 如果没有 `once`，该语音会成为通话模式的新默认语音。
- 在 TTS 播放前，这一行 JSON 会被移除。
+- 该 JSON 行会在 TTS 播放前被移除。

 支持的键：

 - `voice` / `voice_id` / `voiceId`
 - `model` / `model_id` / `modelId`
- `speed`、`rate`（WPM）、`stability`、`similarity`、`style`、`speakerBoost`
- `seed`、`normalize`、`lang`、`output_format`、`latency_tier`
+- `speed`, `rate`（WPM）, `stability`, `similarity`, `style`, `speakerBoost`
+- `seed`, `normalize`, `lang`, `output_format`, `latency_tier`
 - `once`

 ## 配置（`~/.openclaw/openclaw.json`）
@ -57,10 +57,19 @@ x-i18n:
 ```json5
 {
  talk: {
-    voiceId: "elevenlabs_voice_id",
-    modelId: "eleven_v3",
-    outputFormat: "mp3_44100_128",
-    apiKey: "elevenlabs_api_key",
+    provider: "elevenlabs",
+    providers: {
+      elevenlabs: {
+        voiceId: "elevenlabs_voice_id",
+        modelId: "eleven_v3",
+        outputFormat: "mp3_44100_128",
+        apiKey: "elevenlabs_api_key",
+      },
+      mlx: {
+        modelId: "mlx-community/Soprano-80M-bf16",
+      },
+      system: {},
+    },
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
@ -70,34 +79,37 @@ x-i18n:
 默认值：

 - `interruptOnSpeech`：true
- `silenceTimeoutMs`：未设置时，通话模式会在发送转写前使用平台默认暂停窗口（macOS 和 Android 为 `700 ms`，iOS 为 `900 ms`）
- `voiceId`：回退到 `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`（或者在 API 密钥可用时使用第一个 ElevenLabs 语音）
- `modelId`：未设置时默认使用 `eleven_v3`
- `apiKey`：回退到 `ELEVENLABS_API_KEY`（或者在可用时使用 Gateway 网关 shell profile）
- `outputFormat`：macOS/iOS 默认 `pcm_44100`，Android 默认 `pcm_24000`（设置 `mp3_*` 可强制使用 MP3 流式传输）
+- `silenceTimeoutMs`：未设置时，通话模式会在发送转录文本前使用平台默认的停顿窗口（`macOS` 和 Android 上为 `700 ms`，iOS 上为 `900 ms`）
+- `provider`：选择当前启用的通话提供商。对于 macOS 本地播放路径，使用 `elevenlabs`、`mlx` 或 `system`。
+- `providers.<provider>.voiceId`：对于 ElevenLabs，会回退到 `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`（如果提供了 API key，也可回退到第一个 ElevenLabs 语音）。
+- `providers.elevenlabs.modelId`：未设置时默认为 `eleven_v3`。
+- `providers.mlx.modelId`：未设置时默认为 `mlx-community/Soprano-80M-bf16`。
+- `providers.elevenlabs.apiKey`：会回退到 `ELEVENLABS_API_KEY`（如果可用，也可回退到 Gateway 网关 shell 配置文件）。
+- `outputFormat`：在 macOS/iOS 上默认为 `pcm_44100`，在 Android 上默认为 `pcm_24000`（设置为 `mp3_*` 可强制使用 MP3 流式传输）

 ## macOS UI

- 菜单栏切换项：**Talk**
- 配置标签页：**Talk Mode** 分组（voice id + 打断开关）
- 悬浮层：
-  - **Listening**：云朵随麦克风电平脉动
-  - **Thinking**：下沉动画
-  - **Speaking**：向外扩散的圆环
-  - 点击云朵：停止朗读
+- 菜单栏开关：**通话**
+- 配置标签页：**通话模式**分组（语音 id + 打断开关）
+- 覆盖层：
+  - **监听中**：云朵会随麦克风电平脉动
+  - **思考中**：下沉动画
+  - **播报中**：向外辐射的圆环
+  - 点击云朵：停止播报
  - 点击 X：退出通话模式

 ## 说明

- 需要 Speech 和 Microphone 权限。
- 对会话键 `main` 使用 `chat.send`。
- Gateway 网关会通过活动的 Talk 提供商使用 `talk.speak` 解析通话播放。仅当该 RPC 不可用时，Android 才会回退到本地系统 TTS。
- `eleven_v3` 的 `stability` 仅验证为 `0.0`、`0.5` 或 `1.0`；其他模型接受 `0..1`。
- 设置 `latency_tier` 时，仅验证 `0..4`。
- Android 支持 `pcm_16000`、`pcm_22050`、`pcm_24000` 和 `pcm_44100` 输出格式，以支持低延迟 `AudioTrack` 流式传输。
+- 需要语音识别和麦克风权限。
+- 使用针对会话键 `main` 的 `chat.send`。
+- Gateway 网关通过当前启用的通话提供商，使用 `talk.speak` 来解析通话播放。Android 仅在该 RPC 不可用时回退到本地系统 TTS。
+- macOS 本地 MLX 播放会在存在时使用内置的 `openclaw-mlx-tts` 辅助程序，或者使用 `PATH` 上的可执行文件。开发期间可设置 `OPENCLAW_MLX_TTS_BIN` 指向自定义辅助二进制文件。
+- `eleven_v3` 的 `stability` 会校验为 `0.0`、`0.5` 或 `1.0`；其他模型接受 `0..1`。
+- 设置了 `latency_tier` 时，会校验为 `0..4`。
+- Android 支持 `pcm_16000`、`pcm_22050`、`pcm_24000` 和 `pcm_44100` 输出格式，以实现低延迟 `AudioTrack` 流式传输。

 ## 相关内容

 - [语音唤醒](/zh-CN/nodes/voicewake)
- [音频和语音便笺](/zh-CN/nodes/audio)
+- [音频和语音笔记](/zh-CN/nodes/audio)
 - [媒体理解](/zh-CN/nodes/media-understanding)
--- a/docs/zh-CN/plugins/google-meet.md
+++ b/docs/zh-CN/plugins/google-meet.md
@ -1,36 +1,37 @@
 ---
 read_when:
-    - 你希望一个 OpenClaw 智能体加入 Google Meet 通话
-    - 你希望一个 OpenClaw 智能体创建新的 Google Meet 通话
+    - 你希望一个 OpenClaw 智能体加入一个 Google Meet 通话
+    - 你希望一个 OpenClaw 智能体创建一个新的 Google Meet 通话
    - 你正在将 Chrome、Chrome 节点或 Twilio 配置为 Google Meet 传输方式
 summary: Google Meet 插件：通过 Chrome 或 Twilio 加入明确指定的 Meet URL，并使用实时语音默认设置
 title: Google Meet 插件
 x-i18n:
-    generated_at: "2026-04-25T07:33:11Z"
+    generated_at: "2026-04-25T07:51:46Z"
    model: gpt-5.4
    provider: openai
-    source_hash: b1188bafd278197a094d37a4fe3310971a03852560a293edafe987b8618e1a09
+    source_hash: 3329ea25e94eb20403464d041cd34de731b7620deeac6b32248655e885cd3729
    source_path: plugins/google-meet.md
    workflow: 15
 ---

 OpenClaw 的 Google Meet 参会支持——该插件在设计上是显式的：

- 它只加入明确指定的 `https://meet.google.com/...` URL。
+- 它只会加入一个明确指定的 `https://meet.google.com/...` URL。
 - 它可以通过 Google Meet API 创建一个新的 Meet 空间，然后加入返回的 URL。
 - `realtime` 语音是默认模式。
 - 当需要更深入的推理或工具时，实时语音可以回调到完整的 OpenClaw 智能体。
- 智能体通过 `mode` 选择加入行为：实时收听/回话使用 `realtime`，如果要加入/控制浏览器但不使用实时语音桥接，则使用 `transcribe`。
- 认证起始方式可以是个人 Google OAuth，或一个已经登录的 Chrome 配置文件。
+- 智能体使用 `mode` 选择加入行为：使用 `realtime` 进行实时收听/回话，或使用 `transcribe` 在没有实时语音桥接的情况下加入/控制浏览器。
+- 认证从个人 Google OAuth 或已登录的 Chrome 配置文件开始。
 - 没有自动的同意提示播报。
 - 默认的 Chrome 音频后端是 `BlackHole 2ch`。
- Chrome 可以在本地运行，也可以在已配对的节点主机上运行。
- Twilio 接受拨入号码，以及可选的 PIN 或 DTMF 序列。
- CLI 命令是 `googlemeet`；`meet` 保留用于更广泛的智能体电话会议工作流。
+- Chrome 可以在本地运行，也可以在配对的节点主机上运行。
+- Twilio 接受一个拨入号码，以及可选的 PIN 或 DTMF 序列。
+- CLI 命令是 `googlemeet`；`meet` 保留给更广泛的智能体电话会议工作流。

 ## 快速开始

-安装本地音频依赖，并配置一个后端实时语音提供商。OpenAI 是默认选项；Google Gemini Live 也可用，配置为 `realtime.provider: "google"`：
+安装本地音频依赖，并配置一个后端实时语音提供商。OpenAI 是默认项；Google Gemini Live 也可用，配合
+`realtime.provider: "google"`：

 ```bash
 brew install blackhole-2ch sox
@ -39,20 +40,20 @@ export OPENAI_API_KEY=sk-...
 export GEMINI_API_KEY=...
 ```

-`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的安装程序要求重启后 macOS 才会暴露该设备：
+`blackhole-2ch` 会安装 `BlackHole 2ch` 虚拟音频设备。Homebrew 的安装程序要求重启，之后 macOS 才会暴露该设备：

 ```bash
 sudo reboot
 ```

-重启后，验证这两个部分：
+重启后，验证这两部分：

 ```bash
 system_profiler SPAudioDataType | grep -i BlackHole
 command -v rec play
 ```

-启用插件：
+启用该插件：

 ```json5
 {
@ -73,7 +74,9 @@ command -v rec play
 openclaw googlemeet setup
 ```

-设置输出旨在让智能体可读。它会报告 Chrome 配置文件、音频桥接、节点固定、延迟实时介绍，以及在配置了 Twilio 委派时，`voice-call` 插件和 Twilio 凭证是否已就绪。把任何 `ok: false` 检查项都视为在让智能体加入前的阻塞项。脚本或机器可读输出请使用 `openclaw googlemeet setup --json`。
+设置输出旨在让智能体可读。它会报告 Chrome 配置文件、音频桥接、节点固定、延迟的实时介绍，以及在配置了 Twilio 委派时，`voice-call` 插件和 Twilio 凭证是否已准备就绪。
+在请求智能体加入之前，将任何 `ok: false` 检查视为阻塞项。
+对于脚本或机器可读输出，请使用 `openclaw googlemeet setup --json`。

 加入会议：

@ -107,13 +110,16 @@ openclaw googlemeet create --no-join
 `googlemeet create` 有两条路径：

 - API 创建：当配置了 Google Meet OAuth 凭证时使用。这是最具确定性的路径，不依赖浏览器 UI 状态。
- 浏览器回退：当缺少 OAuth 凭证时使用。OpenClaw 会使用固定的 Chrome 节点，打开 `https://meet.google.com/new`，等待 Google 重定向到真实的会议代码 URL，然后返回该 URL。这一路径要求节点上的 OpenClaw Chrome 配置文件已经登录 Google。
-  浏览器自动化会处理 Meet 自己的首次运行麦克风提示；该提示不会被视为 Google 登录失败。
-  加入和创建流程也会尽量复用已有的 Meet 标签页，而不是打开新的标签页。匹配时会忽略无害的 URL 查询字符串，例如 `authuser`，因此智能体重试时应聚焦到已打开的会议，而不是创建第二个 Chrome 标签页。
+- 浏览器回退：当 OAuth 凭证缺失时使用。OpenClaw 会使用固定的 Chrome 节点，打开 `https://meet.google.com/new`，等待 Google 重定向到真实的会议代码 URL，然后返回该 URL。此路径要求节点上的 OpenClaw Chrome 配置文件已登录 Google。
+  浏览器自动化会处理 Meet 自身的首次运行麦克风提示；该提示不会被视为 Google 登录失败。
+  加入和创建流程也会尝试复用已有的 Meet 标签页，而不是打开新标签页。匹配时会忽略诸如 `authuser` 之类无害的 URL 查询字符串，因此智能体重试应聚焦到已打开的会议，而不是创建第二个 Chrome 标签页。

-命令/工具输出包含一个 `source` 字段（`api` 或 `browser`），这样智能体可以说明使用了哪条路径。默认情况下，`create` 会加入新会议，并返回 `joined: true` 以及加入会话。若只想生成 URL，可在 CLI 上使用 `create --no-join`，或向工具传入 `"join": false`。
+命令/工具输出包含一个 `source` 字段（`api` 或 `browser`），这样智能体就可以说明使用了哪条路径。
+`create` 默认会加入新会议，并返回 `joined: true` 以及加入会话。若只想生成 URL，请在 CLI 上使用
+`create --no-join`，或向工具传入 `"join": false`。

-或者告诉智能体：“创建一个 Google Meet，用实时语音加入它，然后把链接发给我。” 智能体应调用 `google_meet`，并使用 `action: "create"`，然后分享返回的 `meetingUri`。
+或者告诉智能体：“创建一个 Google Meet，使用实时语音加入，然后把链接发给我。”
+智能体应调用 `google_meet` 并使用 `action: "create"`，然后分享返回的 `meetingUri`。

 ```json
 {
@ -123,20 +129,21 @@ openclaw googlemeet create --no-join
 }
 ```

-如果只需观察/浏览器控制式加入，请设置 `"mode": "transcribe"`。这不会启动双工实时模型桥接，因此它不会在会议中回话。
+若要进行仅观察/浏览器控制的加入，请设置 `"mode": "transcribe"`。这不会启动双工实时模型桥接，因此它不会在会议中回话。

-在实时会话期间，`google_meet` 的状态会包含浏览器和音频桥接健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近输入/输出时间戳、字节计数以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在可行时进行处理。登录、主持人准入以及浏览器/操作系统权限提示会作为手动操作上报，并附带原因和消息，供智能体转达。
+在实时会话期间，`google_meet` 状态会包含浏览器和音频桥接健康信息，例如 `inCall`、`manualActionRequired`、`providerConnected`、
+`realtimeReady`、`audioInputActive`、`audioOutputActive`、最近输入/输出时间戳、字节计数器以及桥接关闭状态。如果出现安全的 Meet 页面提示，浏览器自动化会在能够处理时进行处理。登录、主持人准入，以及浏览器/操作系统权限提示都会作为手动操作上报，并带有原因和消息，供智能体转达。

-Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，为 OpenClaw 所用的麦克风/扬声器路径选择 `BlackHole 2ch`。若要获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足以完成首次冒烟测试，但可能产生回声。
+Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，为 OpenClaw 使用的麦克风/扬声器路径选择 `BlackHole 2ch`。为了获得干净的双工音频，请使用单独的虚拟设备或类似 Loopback 的音频图；单个 BlackHole 设备足以完成首次冒烟测试，但可能会产生回声。

 ### 本地 Gateway 网关 + Parallels Chrome

-你**不**需要在 macOS VM 中部署完整的 OpenClaw Gateway 网关或模型 API 密钥，只是为了让 VM 承载 Chrome。你可以在本地运行 Gateway 网关和智能体，然后在 VM 中运行一个节点主机。只需在 VM 中启用一次内置插件，这样节点就会声明 Chrome 命令：
+你**不**需要在 macOS VM 中运行完整的 OpenClaw Gateway 网关或模型 API 密钥，只是为了让 VM 托管 Chrome。请在本地运行 Gateway 网关和智能体，然后在 VM 中运行一个节点主机。只需在 VM 中启用一次内置插件，这样节点就会通告 Chrome 命令：

 各部分运行位置：

 - Gateway 网关主机：OpenClaw Gateway 网关、智能体工作区、模型/API 密钥、实时提供商，以及 Google Meet 插件配置。
- Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及一个已登录 Google 的 Chrome 配置文件。
+- Parallels macOS VM：OpenClaw CLI/节点主机、Google Chrome、SoX、BlackHole 2ch，以及已登录 Google 的 Chrome 配置文件。
 - VM 中不需要：Gateway 网关服务、智能体配置、OpenAI/GPT 密钥或模型提供商设置。

 安装 VM 依赖：
@ -145,13 +152,13 @@ Chrome 会以已登录的 Chrome 配置文件身份加入。在 Meet 中，为 O
 brew install blackhole-2ch sox
 ```

-安装 BlackHole 后重启 VM，以便 macOS 暴露 `BlackHole 2ch`：
+安装 BlackHole 后重启 VM，这样 macOS 才会暴露 `BlackHole 2ch`：

 ```bash
 sudo reboot
 ```

-重启后，验证 VM 可以看到该音频设备和 SoX 命令：
+重启后，验证 VM 可以看到音频设备和 SoX 命令：

 ```bash
 system_profiler SPAudioDataType | grep -i BlackHole
@ -170,14 +177,14 @@ openclaw plugins enable google-meet
 openclaw node run --host <gateway-host> --port 18789 --display-name parallels-macos
 ```

-如果 `<gateway-host>` 是 LAN IP 且你没有使用 TLS，那么除非你为这个受信任的私有网络显式启用纯文本 WebSocket，否则节点会拒绝连接：
+如果 `<gateway-host>` 是局域网 IP 且你未使用 TLS，那么除非你为该可信私有网络显式启用，否则节点会拒绝明文 WebSocket：

 ```bash
 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
  openclaw node run --host <gateway-lan-ip> --port 18789 --display-name parallels-macos
 ```

-将节点安装为 LaunchAgent 时，也要使用同一个环境变量：
+将节点安装为 LaunchAgent 时，使用相同的环境变量：

 ```bash
 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
@ -185,16 +192,18 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
 openclaw node restart
 ```

-`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境变量，不是 `openclaw.json` 设置。`openclaw node install` 会在安装命令中存在该变量时，将它存储到 LaunchAgent 环境中。
+`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` 是进程环境变量，不是
+`openclaw.json` 设置。`openclaw node install` 会在安装命令中检测到该变量存在时，将其存储到 LaunchAgent 环境中。

-从 Gateway 网关主机批准该节点：
+在 Gateway 网关主机上批准该节点：

 ```bash
 openclaw devices list
 openclaw devices approve <requestId>
 ```

-确认 Gateway 网关能看到该节点，并且它同时声明了 `googlemeet.chrome` 和浏览器能力/`browser.proxy`：
+确认 Gateway 网关能看到该节点，并且它同时通告了 `googlemeet.chrome`
+和浏览器能力/`browser.proxy`：

 ```bash
 openclaw nodes status
@ -230,7 +239,7 @@ openclaw nodes status
 }
 ```

-现在可以从 Gateway 网关主机像平常一样加入：
+现在从 Gateway 网关主机正常加入：

 ```bash
 openclaw googlemeet join https://meet.google.com/abc-defg-hij
@ -238,54 +247,67 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij

 或者让智能体使用 `google_meet` 工具，并设置 `transport: "chrome-node"`。

-如果要进行一条命令的冒烟测试，创建或复用会话、说出已知短语，并打印会话健康状态：
+若要执行一个单命令冒烟测试，用于创建或复用会话、说出已知短语并打印会话健康状态：

 ```bash
 openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij
 ```

-在加入过程中，OpenClaw 浏览器自动化会填写访客名称，点击“加入”/“请求加入”，并在出现该提示时接受 Meet 首次运行的“使用麦克风”选择。在仅浏览器的会议创建过程中，如果 Meet 没有暴露使用麦克风按钮，它也可以在不使用麦克风的情况下继续通过同一个提示。
-如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要麦克风/摄像头权限，或 Meet 卡在自动化无法解决的提示上，`join`/`test-speech` 结果会报告 `manualActionRequired: true`，并附带 `manualActionReason` 和 `manualActionMessage`。智能体应停止重试加入，转达那条确切消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后再重试。
+在加入期间，OpenClaw 浏览器自动化会填写访客名称，点击 Join/Ask to join，并在该提示出现时接受 Meet 首次运行的“Use microphone”选择。在仅浏览器的会议创建期间，如果 Meet 没有显示使用麦克风按钮，它也可以在没有麦克风的情况下继续通过相同提示。
+如果浏览器配置文件未登录、Meet 正在等待主持人准入、Chrome 需要麦克风/摄像头权限，或者 Meet 卡在自动化无法解决的提示上，加入/`test-speech` 结果会报告
+`manualActionRequired: true`，并附带 `manualActionReason` 和
+`manualActionMessage`。智能体应停止重试加入，报告该确切消息以及当前的 `browserUrl`/`browserTitle`，并且只在手动浏览器操作完成后再重试。

-如果省略 `chromeNode.node`，只有在恰好存在一个已连接节点同时声明 `googlemeet.chrome` 和浏览器控制时，OpenClaw 才会自动选择它。如果连接了多个具备能力的节点，请将 `chromeNode.node` 设置为节点 id、显示名称或远程 IP。
+如果省略了 `chromeNode.node`，只有在恰好有一个已连接节点同时通告 `googlemeet.chrome` 和浏览器控制能力时，OpenClaw 才会自动选择。
+如果连接了多个具备能力的节点，请将 `chromeNode.node` 设置为节点 id、显示名称或远程 IP。

 常见故障检查：

- `No connected Google Meet-capable node`：在 VM 中启动 `openclaw node run`，批准配对，并确保已在 VM 中运行 `openclaw plugins enable google-meet` 和 `openclaw plugins enable browser`。还要确认 Gateway 网关主机允许这两个节点命令：`gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`。
- `BlackHole 2ch audio device not found on the node`：在 VM 中安装 `blackhole-2ch` 并重启 VM。
- Chrome 打开了但无法加入：在 VM 中登录浏览器配置文件，或者保持设置 `chrome.guestName` 以便访客加入。访客自动加入使用 OpenClaw 通过节点浏览器代理执行的浏览器自动化；请确保节点浏览器配置指向你想使用的配置文件，例如 `browser.defaultProfile: "user"`，或一个已命名的现有会话配置文件。
- 重复的 Meet 标签页：保持启用 `chrome.reuseExistingTab: true`。OpenClaw 会先为相同的 Meet URL 激活现有标签页，再打开新标签页；浏览器会议创建也会复用正在进行中的 `https://meet.google.com/new` 或 Google 账户提示标签页，而不是再打开一个。
- 没有音频：在 Meet 中，将麦克风/扬声器路由到 OpenClaw 使用的虚拟音频设备路径；要获得干净的双工音频，请使用独立的虚拟设备或类似 Loopback 的路由。
+- `No connected Google Meet-capable node`：在 VM 中启动 `openclaw node run`，
+  批准配对，并确保已在 VM 中运行 `openclaw plugins enable google-meet` 和
+  `openclaw plugins enable browser`。还要确认 Gateway 网关主机允许这两个节点命令，即
+  `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`。
+- `BlackHole 2ch audio device not found on the node`：在 VM 中安装 `blackhole-2ch`
+  并重启 VM。
+- Chrome 已打开但无法加入：在 VM 中登录浏览器配置文件，或保持设置
+  `chrome.guestName` 用于访客加入。访客自动加入使用 OpenClaw 浏览器自动化并通过节点浏览器代理运行；请确保节点浏览器配置指向你想要的配置文件，例如
+  `browser.defaultProfile: "user"` 或某个命名的 existing-session 配置文件。
+- 重复的 Meet 标签页：保持启用 `chrome.reuseExistingTab: true`。OpenClaw 会先为相同的 Meet URL 激活现有标签页，再打开新标签页，而浏览器会议创建也会在打开另一个标签页之前复用正在进行中的 `https://meet.google.com/new` 或 Google 账号提示标签页。
+- 没有音频：在 Meet 中，将麦克风/扬声器路由到 OpenClaw 使用的虚拟音频设备路径；使用单独的虚拟设备或类似 Loopback 的路由，以获得干净的双工音频。

 ## 安装说明

-Chrome 实时默认模式使用两个外部工具：
+Chrome 实时默认配置使用两个外部工具：

- `sox`：命令行音频工具。插件使用它的 `rec` 和 `play` 命令来实现默认的 8 kHz G.711 mu-law 音频桥接。
- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 `BlackHole 2ch` 音频设备，供 Chrome/Meet 路由使用。
+- `sox`：命令行音频工具。该插件使用它的 `rec` 和 `play`
+  命令来实现默认的 8 kHz G.711 mu-law 音频桥接。
+- `blackhole-2ch`：macOS 虚拟音频驱动。它会创建 `BlackHole 2ch`
+  音频设备，供 Chrome/Meet 路由使用。

-OpenClaw 不捆绑或重新分发这两个软件包。文档要求用户通过 Homebrew 将它们作为主机依赖安装。SoX 的许可证为 `LGPL-2.0-only AND GPL-2.0-only`；BlackHole 为 GPL-3.0。如果你要构建一个将 BlackHole 与 OpenClaw 一起捆绑的安装器或设备，请查阅 BlackHole 上游许可条款，或从 Existential Audio 获取单独许可。
+OpenClaw 不会捆绑或重新分发这两个软件包。文档要求用户通过 Homebrew 将它们作为主机依赖进行安装。SoX 的许可为
+`LGPL-2.0-only AND GPL-2.0-only`；BlackHole 为 GPL-3.0。如果你构建了一个将 BlackHole 与 OpenClaw 一起捆绑的安装程序或设备，请查看 BlackHole 上游许可条款，或从 Existential Audio 获取单独许可。

 ## 传输方式

 ### Chrome

-Chrome 传输方式会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，插件会在启动前检查 `BlackHole 2ch`。如果已配置，它还会在打开 Chrome 之前运行音频桥接健康检查命令和启动命令。当 Chrome/音频位于 Gateway 网关主机上时使用 `chrome`；当 Chrome/音频位于已配对节点上（例如 Parallels macOS VM）时使用 `chrome-node`。
+Chrome 传输会在 Google Chrome 中打开 Meet URL，并以已登录的 Chrome 配置文件身份加入。在 macOS 上，插件会在启动前检查是否存在 `BlackHole 2ch`。
+如果已配置，它还会在打开 Chrome 之前运行一个音频桥接健康检查命令和启动命令。当 Chrome/音频位于 Gateway 网关主机上时，请使用 `chrome`；当 Chrome/音频位于配对节点（例如 Parallels macOS VM）上时，请使用 `chrome-node`。

 ```bash
 openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome
 openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node
 ```

-将 Chrome 的麦克风和扬声器音频通过本地 OpenClaw 音频桥接进行路由。如果未安装 `BlackHole 2ch`，加入会因设置错误而失败，而不是在没有音频路径的情况下静默加入。
+通过本地 OpenClaw 音频桥接来路由 Chrome 麦克风和扬声器音频。如果未安装 `BlackHole 2ch`，加入将因设置错误而失败，而不是在没有音频路径的情况下静默加入。

 ### Twilio

-Twilio 传输方式是一种严格的拨号计划，并委派给 Voice Call 插件。它不会解析 Meet 页面来查找电话号码。
+Twilio 传输是一种严格的拨号方案，委派给 Voice Call 插件。它不会解析 Meet 页面来提取电话号码。

-当无法使用 Chrome 参会，或你希望使用电话拨入作为回退方案时，请使用此方式。Google Meet 必须为该会议公开电话拨入号码和 PIN；OpenClaw 不会从 Meet 页面中发现这些信息。
+当无法使用 Chrome 参会，或者你希望使用电话拨入作为回退方案时，请使用此方式。Google Meet 必须为该会议提供电话拨入号码和 PIN；OpenClaw 不会从 Meet 页面中发现这些信息。

-在 Gateway 网关主机上启用 Voice Call 插件，而不是在 Chrome 节点上：
+在 Gateway 网关主机上启用 Voice Call 插件，而不是在 Chrome 节点上启用：

 ```json5
 {
@ -310,7 +332,7 @@ Twilio 传输方式是一种严格的拨号计划，并委派给 Voice Call 插
 }
 ```

-通过环境变量或配置提供 Twilio 凭证。环境变量可以让密钥不出现在 `openclaw.json` 中：
+通过环境变量或配置提供 Twilio 凭证。使用环境变量可以将密钥保留在 `openclaw.json` 之外：

 ```bash
 export TWILIO_ACCOUNT_SID=AC...
@ -318,7 +340,7 @@ export TWILIO_AUTH_TOKEN=...
 export TWILIO_FROM_NUMBER=+15550001234
 ```

-启用 `voice-call` 后，重启或重新加载 Gateway 网关；在已经运行的 Gateway 网关进程重新加载之前，插件配置变更不会生效。
+启用 `voice-call` 后，重启或重新加载 Gateway 网关；插件配置变更在已运行的 Gateway 网关进程重新加载前不会生效。

 然后验证：

@ -328,7 +350,8 @@ openclaw plugins list | grep -E 'google-meet|voice-call'
 openclaw googlemeet setup
 ```

-当 Twilio 委派连接完成后，`googlemeet setup` 会包含成功的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查项。
+当 Twilio 委派配置正确时，`googlemeet setup` 会包含成功的
+`twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查。

 ```bash
 openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -350,9 +373,10 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \

 OAuth 对于创建 Meet 链接来说是可选的，因为 `googlemeet create` 可以回退到浏览器自动化。当你需要官方 API 创建、空间解析或 Meet Media API 预检时，请配置 OAuth。

-Google Meet API 访问使用用户 OAuth：创建一个 Google Cloud OAuth 客户端，请求所需作用域，授权一个 Google 账户，然后将得到的刷新令牌存储在 Google Meet 插件配置中，或提供 `OPENCLAW_GOOGLE_MEET_*` 环境变量。
+Google Meet API 访问使用用户 OAuth：创建一个 Google Cloud OAuth 客户端，请求所需作用域，授权一个 Google 账号，然后将生成的刷新令牌存储在 Google Meet 插件配置中，或提供
+`OPENCLAW_GOOGLE_MEET_*` 环境变量。

-OAuth 不会替代 Chrome 加入路径。使用浏览器参会时，`chrome` 和 `chrome-node` 传输方式仍然通过已登录的 Chrome 配置文件、BlackHole/SoX，以及一个已连接节点来加入。OAuth 仅用于官方 Google Meet API 路径：创建会议空间、解析空间，以及运行 Meet Media API 预检。
+OAuth 不会替代 Chrome 加入路径。使用浏览器参会时，`chrome` 和 `chrome-node` 传输仍然通过已登录的 Chrome 配置文件、BlackHole/SoX 以及已连接节点来加入。OAuth 仅用于官方 Google Meet API 路径：创建会议空间、解析空间，以及运行 Meet Media API 预检。

 ### 创建 Google 凭证

@ -361,13 +385,13 @@ OAuth 不会替代 Chrome 加入路径。使用浏览器参会时，`chrome` 和
 1. 创建或选择一个 Google Cloud 项目。
 2. 为该项目启用 **Google Meet REST API**。
 3. 配置 OAuth 同意屏幕。
-   - 对 Google Workspace 组织来说，**Internal** 最简单。
-   - **External** 适用于个人/测试设置；当应用处于 Testing 状态时，把每个将授权该应用的 Google 账户添加为测试用户。
+   - 对于 Google Workspace 组织，**Internal** 最简单。
+   - **External** 适用于个人/测试设置；当应用处于 Testing 状态时，将每个会授权该应用的 Google 账号添加为测试用户。
 4. 添加 OpenClaw 请求的作用域：
   - `https://www.googleapis.com/auth/meetings.space.created`
   - `https://www.googleapis.com/auth/meetings.space.readonly`
   - `https://www.googleapis.com/auth/meetings.conference.media.readonly`
-5. 创建一个 OAuth 客户端 ID。
+5. 创建一个 OAuth client ID。
   - 应用类型：**Web application**。
   - 已获授权的重定向 URI：

@ -375,22 +399,22 @@ OAuth 不会替代 Chrome 加入路径。使用浏览器参会时，`chrome` 和
     http://localhost:8085/oauth2callback
     ```

-6. 复制客户端 ID 和客户端密钥。
+6. 复制 client ID 和 client secret。

-`meetings.space.created` 是 Google Meet `spaces.create` 所必需的。
-`meetings.space.readonly` 允许 OpenClaw 将 Meet URL/代码解析为空间。
-`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体相关工作；Google 可能要求加入 Developer Preview 才能实际使用 Media API。
-如果你只需要基于浏览器的 Chrome 加入方式，可以完全跳过 OAuth。
+Google Meet `spaces.create` 需要 `meetings.space.created`。
+`meetings.space.readonly` 允许 OpenClaw 将 Meet URL/代码解析为会议空间。
+`meetings.conference.media.readonly` 用于 Meet Media API 预检和媒体相关工作；实际使用 Media API 时，Google 可能要求加入开发者预览。
+如果你只需要基于浏览器的 Chrome 加入，请完全跳过 OAuth。

 ### 生成刷新令牌

-配置 `oauth.clientId`，可选配置 `oauth.clientSecret`，或将它们作为环境变量传入，然后运行：
+配置 `oauth.clientId`，并可选配置 `oauth.clientSecret`，或者将它们作为环境变量传入，然后运行：

 ```bash
 openclaw googlemeet auth login --json
 ```

-该命令会输出一个带有刷新令牌的 `oauth` 配置块。它使用 PKCE、位于 `http://localhost:8085/oauth2callback` 的 localhost 回调，以及通过 `--manual` 启用的手动复制/粘贴流程。
+该命令会打印一个包含刷新令牌的 `oauth` 配置块。它使用 PKCE、本地回调 `http://localhost:8085/oauth2callback`，以及配合 `--manual` 的手动复制/粘贴流程。

 示例：

@ -400,7 +424,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \
 openclaw googlemeet auth login --json
 ```

-当浏览器无法访问本地回调时，使用手动模式：
+当浏览器无法访问本地回调时，请使用手动模式：

 ```bash
 OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \
@ -408,7 +432,7 @@ OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \
 openclaw googlemeet auth login --json --manual
 ```

-JSON 输出包含：
+JSON 输出包括：

 ```json
 {
@ -423,7 +447,7 @@ JSON 输出包含：
 }
 ```

-将 `oauth` 对象存储到 Google Meet 插件配置中：
+将 `oauth` 对象存储在 Google Meet 插件配置下：

 ```json5
 {
@ -444,50 +468,51 @@ JSON 输出包含：
 }
 ```

-如果你不希望刷新令牌出现在配置中，优先使用环境变量。如果配置和环境值同时存在，插件会优先解析配置，然后再回退到环境变量。
+如果你不希望将刷新令牌放入配置中，优先使用环境变量。
+如果配置值和环境变量值同时存在，插件会优先解析配置，然后再回退到环境变量。

-OAuth 同意内容包括 Meet 空间创建、Meet 空间读取权限，以及 Meet conference media 读取权限。如果你是在支持会议创建之前完成认证的，请重新运行 `openclaw googlemeet auth login --json`，以便刷新令牌包含 `meetings.space.created` 作用域。
+OAuth 同意内容包括 Meet 空间创建、Meet 空间读取访问以及 Meet 会议媒体读取访问。如果你在会议创建支持存在之前就完成了认证，请重新运行 `openclaw googlemeet auth login --json`，以便刷新令牌具备 `meetings.space.created` 作用域。

-### 使用 Doctor 验证 OAuth
+### 用 Doctor 验证 OAuth

-当你需要快速、无密钥暴露的健康检查时，请运行 OAuth Doctor：
+当你想要进行快速、无密钥暴露的健康检查时，请运行 OAuth Doctor：

 ```bash
 openclaw googlemeet doctor --oauth --json
 ```

-这不会加载 Chrome 运行时，也不需要已连接的 Chrome 节点。它会检查 OAuth 配置是否存在，以及刷新令牌是否可以生成访问令牌。JSON 报告仅包含状态字段，例如 `ok`、`configured`、`tokenSource`、`expiresAt` 和检查消息；它不会打印访问令牌、刷新令牌或客户端密钥。
+这不会加载 Chrome 运行时，也不需要已连接的 Chrome 节点。它会检查 OAuth 配置是否存在，以及刷新令牌是否能够生成访问令牌。JSON 报告只包含诸如 `ok`、`configured`、`tokenSource`、`expiresAt` 和检查消息等状态字段；不会打印访问令牌、刷新令牌或 client secret。

 常见结果：

 | 检查项               | 含义                                                                                    |
 | -------------------- | --------------------------------------------------------------------------------------- |
-| `oauth-config`       | 存在 `oauth.clientId` 加 `oauth.refreshToken`，或存在已缓存的访问令牌。                |
-| `oauth-token`        | 已缓存的访问令牌仍然有效，或刷新令牌已生成新的访问令牌。                                |
-| `meet-spaces-get`    | 可选的 `--meeting` 检查解析了一个现有 Meet 空间。                                       |
-| `meet-spaces-create` | 可选的 `--create-space` 检查创建了一个新的 Meet 空间。                                  |
+| `oauth-config`       | 存在 `oauth.clientId` 加 `oauth.refreshToken`，或存在缓存的访问令牌。                  |
+| `oauth-token`        | 缓存的访问令牌仍然有效，或刷新令牌已生成新的访问令牌。                                  |
+| `meet-spaces-get`    | 可选的 `--meeting` 检查已解析一个现有 Meet 空间。                                       |
+| `meet-spaces-create` | 可选的 `--create-space` 检查已创建一个新的 Meet 空间。                                  |

-若还要验证 Google Meet API 已启用，以及存在 `spaces.create` 作用域，请运行带副作用的创建检查：
+若还要证明 Google Meet API 已启用以及具备 `spaces.create` 作用域，请运行带副作用的创建检查：

 ```bash
 openclaw googlemeet doctor --oauth --create-space --json
 openclaw googlemeet create --no-join --json
 ```

-`--create-space` 会创建一个一次性的 Meet URL。当你需要确认 Google Cloud 项目已启用 Meet API，且已授权账户具备 `meetings.space.created` 作用域时，请使用它。
+`--create-space` 会创建一个一次性的 Meet URL。当你需要确认 Google Cloud 项目已启用 Meet API，且授权账号具备 `meetings.space.created` 作用域时，请使用它。

-若要验证对现有会议空间的读取权限：
+若要证明对现有会议空间的读取访问权限：

 ```bash
 openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json
 openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij
 ```

-`doctor --oauth --meeting` 和 `resolve-space` 可证明对已授权 Google 账户可访问的现有空间具备读取权限。这些检查返回 `403` 通常意味着 Google Meet REST API 未启用、已同意的刷新令牌缺少所需作用域，或该 Google 账户无法访问该 Meet 空间。刷新令牌错误意味着需要重新运行 `openclaw googlemeet auth login --json`，并存储新的 `oauth` 配置块。
+`doctor --oauth --meeting` 和 `resolve-space` 可以证明对授权 Google 账号有权访问的现有空间具有读取权限。这些检查返回 `403` 通常意味着 Google Meet REST API 未启用、已同意的刷新令牌缺少所需作用域，或该 Google 账号无权访问该 Meet 空间。刷新令牌错误则意味着需要重新运行 `openclaw googlemeet auth login --json` 并存储新的 `oauth` 块。

-浏览器回退模式不需要 OAuth 凭证。在该模式下，Google 认证来自所选节点上已登录的 Chrome 配置文件，而不是 OpenClaw 配置。
+浏览器回退不需要任何 OAuth 凭证。在该模式下，Google 认证来自所选节点上已登录的 Chrome 配置文件，而不是 OpenClaw 配置。

-以下环境变量可作为回退值使用：
+以下环境变量可作为回退值：

 - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID`
 - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` 或 `GOOGLE_MEET_CLIENT_SECRET`
@ -510,7 +535,7 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij
 openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij
 ```

-在 Meet 创建 conference record 之后，列出会议工件和出勤情况：
+在 Meet 创建了会议记录后，列出会议产物和出席情况：

 ```bash
 openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij
@ -518,9 +543,9 @@ openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij
 openclaw googlemeet export --meeting https://meet.google.com/abc-defg-hij --output ./meet-export
 ```

-在使用 `--meeting` 时，`artifacts` 和 `attendance` 默认使用最新的 conference record。如果你想获取该会议的所有保留记录，请传入 `--all-conference-records`。
+使用 `--meeting` 时，`artifacts` 和 `attendance` 默认使用最新的会议记录。如果你希望获取该会议的所有保留记录，请传入 `--all-conference-records`。

-Calendar 查找可以在读取 Meet 工件之前，先从 Google Calendar 解析会议 URL：
+在读取 Meet 产物之前，日历查找可以先从 Google Calendar 解析会议 URL：

 ```bash
 openclaw googlemeet latest --today
@ -529,10 +554,10 @@ openclaw googlemeet artifacts --event "Weekly sync"
 openclaw googlemeet attendance --today --format csv --output attendance.csv
 ```

-`--today` 会在今天的 `primary` 日历中搜索带有 Google Meet 链接的 Calendar 事件。使用 `--event <query>` 搜索匹配的事件文本，使用 `--calendar <id>` 指定非主日历。Calendar 查找需要一次新的 OAuth 登录，并包含 Calendar events readonly 作用域。
+`--today` 会在今天的 `primary` 日历中搜索带有 Google Meet 链接的 Calendar 事件。使用 `--event <query>` 搜索匹配的事件文本，使用 `--calendar <id>` 指定非主日历。日历查找需要一次新的 OAuth 登录，并包含 Calendar events readonly 作用域。
 `calendar-events` 会预览匹配的 Meet 事件，并标记 `latest`、`artifacts`、`attendance` 或 `export` 将选择的事件。

-如果你已经知道 conference record id，可以直接指定：
+如果你已经知道 conference record id，可以直接指定它：

 ```bash
 openclaw googlemeet latest --meeting https://meet.google.com/abc-defg-hij
@ -540,7 +565,7 @@ openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --jso
 openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json
 ```

-写出可读报告：
+输出可读报告：

 ```bash
 openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 \
@ -551,13 +576,32 @@ openclaw googlemeet attendance --conference-record conferenceRecords/abc123 \
  --format csv --output meet-attendance.csv
 openclaw googlemeet export --conference-record conferenceRecords/abc123 \
  --include-doc-bodies --zip --output meet-export
+openclaw googlemeet export --conference-record conferenceRecords/abc123 \
+  --include-doc-bodies --dry-run
 ```

-`artifacts` 会返回 conference record 元数据，以及当 Google 为该会议公开这些内容时的参会者、录制、转录、结构化 transcript-entry 和 smart-note 资源元数据。对大型会议，可使用 `--no-transcript-entries` 跳过条目查询。`attendance` 会将参会者展开为 participant-session 行，包含首次/最后出现时间、总会话时长、迟到/提前离开标记，以及按已登录用户或显示名称合并后的重复参会者资源。传入 `--no-merge-duplicates` 可保持原始参会者资源分离，传入 `--late-after-minutes` 可调整迟到判定，传入 `--early-before-minutes` 可调整提前离开判定。
+`artifacts` 会返回会议记录元数据，以及当 Google 为该会议提供时的参会者、录制、转录、结构化 transcript-entry 和 smart-note 资源元数据。对于大型会议，使用 `--no-transcript-entries` 可跳过条目查询。`attendance` 会将参会者展开为 participant-session 行，包含首次/最后出现时间、总会话时长、迟到/提前离会标记，以及按已登录用户或显示名称合并的重复参会者资源。传入 `--no-merge-duplicates` 可保持原始参会者资源彼此分离，传入 `--late-after-minutes` 可调整迟到判定，传入 `--early-before-minutes` 可调整提前离会判定。

-`export` 会写出一个文件夹，其中包含 `summary.md`、`attendance.csv`、`transcript.md`、`artifacts.json` 和 `attendance.json`。传入 `--zip` 还会在该文件夹旁边写出一个可移植归档。传入 `--include-doc-bodies` 可通过 Google Drive `files.export` 导出链接的 transcript 和 smart-note Google Docs 文本；这需要一次新的 OAuth 登录，并包含 Drive Meet readonly 作用域。不使用 `--include-doc-bodies` 时，导出内容仅包含 Meet 元数据和结构化 transcript 条目。
+`export` 会写出一个文件夹，包含 `summary.md`、`attendance.csv`、
+`transcript.md`、`artifacts.json`、`attendance.json` 和 `manifest.json`。
+`manifest.json` 会记录所选输入、导出选项、会议记录、输出文件、计数、令牌来源、使用的 Calendar 事件（若有），以及任何部分检索警告。传入 `--zip` 还会在文件夹旁边额外写出一个便携归档。传入 `--include-doc-bodies` 可通过 Google Drive `files.export` 导出关联的转录和 smart-note Google Docs 文本；这需要一次新的 OAuth 登录，并包含 Drive Meet readonly 作用域。若不使用 `--include-doc-bodies`，导出内容仅包含 Meet 元数据和结构化转录条目。如果 Google 返回部分产物失败，例如 smart-note 列表、transcript-entry 或 Drive 文档正文错误，摘要和清单会保留该警告，而不是让整个导出失败。
+使用 `--dry-run` 可获取相同的产物/出席数据，并打印 manifest JSON，而不会创建文件夹或 ZIP。这在写出大型导出之前，或者当智能体只需要计数、所选记录和警告时非常有用。

-针对真实保留会议运行受保护的 live 冒烟测试：
+智能体也可以通过 `google_meet` 工具创建相同的打包结果：
+
+```json
+{
+  "action": "export",
+  "conferenceRecord": "conferenceRecords/abc123",
+  "includeDocumentBodies": true,
+  "outputDir": "meet-export",
+  "zip": true
+}
+```
+
+设置 `"dryRun": true` 可只返回导出清单并跳过文件写入。
+
+针对真实的保留会议运行受保护的实时冒烟测试：

 ```bash
 OPENCLAW_LIVE_TEST=1 \
@ -565,15 +609,33 @@ OPENCLAW_GOOGLE_MEET_LIVE_MEETING=https://meet.google.com/abc-defg-hij \
 pnpm test:live -- extensions/google-meet/google-meet.live.test.ts
 ```

+实时冒烟测试环境：
+
+- `OPENCLAW_LIVE_TEST=1` 启用受保护的实时测试。
+- `OPENCLAW_GOOGLE_MEET_LIVE_MEETING` 指向一个保留的 Meet URL、代码或
+  `spaces/{id}`。
+- `OPENCLAW_GOOGLE_MEET_CLIENT_ID` 或 `GOOGLE_MEET_CLIENT_ID` 提供 OAuth
+  client id。
+- `OPENCLAW_GOOGLE_MEET_REFRESH_TOKEN` 或 `GOOGLE_MEET_REFRESH_TOKEN` 提供
+  refresh token。
+- 可选：`OPENCLAW_GOOGLE_MEET_CLIENT_SECRET`、
+  `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN` 和
+  `OPENCLAW_GOOGLE_MEET_ACCESS_TOKEN_EXPIRES_AT` 使用相同的回退名称，只是不带 `OPENCLAW_` 前缀。
+
+基础的产物/出席实时冒烟测试需要
+`https://www.googleapis.com/auth/meetings.space.readonly` 和
+`https://www.googleapis.com/auth/meetings.conference.media.readonly`。Calendar 查找需要 `https://www.googleapis.com/auth/calendar.events.readonly`。Drive 文档正文导出需要
+`https://www.googleapis.com/auth/drive.meet.readonly`。
+
 创建一个新的 Meet 空间：

 ```bash
 openclaw googlemeet create
 ```

-该命令会打印新的 `meeting uri`、来源以及加入会话。有 OAuth 凭证时，它会使用官方 Google Meet API。没有 OAuth 凭证时，它会回退为使用固定的 Chrome 节点上已登录的浏览器配置文件。智能体可以使用带 `action: "create"` 的 `google_meet` 工具，一步完成创建和加入。若只创建 URL，请传入 `"join": false`。
+该命令会打印新的 `meeting uri`、来源和加入会话。有 OAuth 凭证时，它使用官方 Google Meet API。没有 OAuth 凭证时，它会回退为使用固定的 Chrome 节点上已登录的浏览器配置文件。智能体可以通过 `google_meet` 工具并使用 `action: "create"` 来一步完成创建和加入。若只创建 URL，请传入 `"join": false`。

-来自浏览器回退路径的 JSON 输出示例：
+浏览器回退的 JSON 输出示例：

 ```json
 {
@ -593,7 +655,7 @@ openclaw googlemeet create
 }
 ```

-如果浏览器回退路径在创建 URL 前遇到 Google 登录或 Meet 权限阻塞，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化细节，而不是普通字符串：
+如果浏览器回退在创建 URL 之前遇到 Google 登录或 Meet 权限阻塞，Gateway 网关方法会返回失败响应，而 `google_meet` 工具会返回结构化细节，而不是纯字符串：

 ```json
 {
@ -611,9 +673,10 @@ openclaw googlemeet create
 }
 ```

-当智能体看到 `manualActionRequired: true` 时，它应报告 `manualActionMessage` 以及浏览器节点/标签页上下文，并停止打开新的 Meet 标签页，直到操作员完成浏览器步骤。
+当智能体看到 `manualActionRequired: true` 时，它应报告
+`manualActionMessage` 以及浏览器节点/标签页上下文，并停止继续打开新的 Meet 标签页，直到操作人员完成浏览器步骤。

-来自 API 创建的 JSON 输出示例：
+API 创建的 JSON 输出示例：

 ```json
 {
@ -634,13 +697,14 @@ openclaw googlemeet create
 }
 ```

-默认情况下，创建 Meet 后会立即加入。`chrome` 或 `chrome-node` 传输方式仍然需要一个已登录 Google 的 Chrome 配置文件，才能通过浏览器加入。如果该配置文件已登出，OpenClaw 会报告 `manualActionRequired: true` 或浏览器回退错误，并要求操作员先完成 Google 登录再重试。
+默认情况下，创建 Meet 后会立即加入。`chrome` 或 `chrome-node` 传输仍然需要一个已登录 Google 的 Chrome 配置文件，才能通过浏览器加入。如果该配置文件已登出，OpenClaw 会报告 `manualActionRequired: true` 或浏览器回退错误，并要求操作人员先完成 Google 登录后再重试。

-只有在确认你的 Cloud 项目、OAuth 主体和会议参与者都已加入 Google Workspace Developer Preview Program for Meet media APIs 后，才设置 `preview.enrollmentAcknowledged: true`。
+只有在确认你的 Cloud 项目、OAuth 主体和会议参与者均已加入用于 Meet 媒体 API 的 Google Workspace Developer Preview Program 后，才将 `preview.enrollmentAcknowledged: true` 设为 true。

 ## 配置

-常见的 Chrome 实时路径只需要启用该插件、BlackHole、SoX 和一个后端实时语音提供商密钥。OpenAI 是默认值；设置 `realtime.provider: "google"` 可使用 Google Gemini Live：
+常见的 Chrome 实时路径只需要启用插件、BlackHole、SoX，以及一个后端实时语音提供商密钥。OpenAI 是默认项；设置
+`realtime.provider: "google"` 可使用 Google Gemini Live：

 ```bash
 brew install blackhole-2ch sox
@ -671,15 +735,18 @@ export GEMINI_API_KEY=...
 - `chromeNode.node`：`chrome-node` 的可选节点 id/名称/IP
 - `chrome.audioBackend: "blackhole-2ch"`
 - `chrome.guestName: "OpenClaw Agent"`：在已登出的 Meet 访客界面中使用的名称
- `chrome.autoJoin: true`：在 `chrome-node` 上通过 OpenClaw 浏览器自动化尽力填写访客名称并点击立即加入
+- `chrome.autoJoin: true`：在 `chrome-node` 上通过 OpenClaw 浏览器自动化尽力填写访客名称并点击 Join Now
 - `chrome.reuseExistingTab: true`：激活现有 Meet 标签页，而不是打开重复标签页
 - `chrome.waitForInCallMs: 20000`：等待 Meet 标签页报告已在通话中，然后再触发实时介绍
- `chrome.audioInputCommand`：将 8 kHz G.711 mu-law 音频写到 stdout 的 SoX `rec` 命令
- `chrome.audioOutputCommand`：从 stdin 读取 8 kHz G.711 mu-law 音频的 SoX `play` 命令
+- `chrome.audioInputCommand`：SoX `rec` 命令，将 8 kHz G.711 mu-law
+  音频写到 stdout
+- `chrome.audioOutputCommand`：SoX `play` 命令，从 stdin 读取 8 kHz G.711 mu-law
+  音频
 - `realtime.provider: "openai"`
 - `realtime.toolPolicy: "safe-read-only"`
- `realtime.instructions`：简短口语回复，较深入回答使用 `openclaw_agent_consult`
- `realtime.introMessage`：当实时桥接连接时的简短口头就绪检查；将其设为 `""` 可静默加入
+- `realtime.instructions`：简短的口头回复，较深入的回答使用
+  `openclaw_agent_consult`
+- `realtime.introMessage`：当实时桥接连接时，进行简短的口头就绪检查；将其设为 `""` 可静默加入

 可选覆盖项：

@ -725,7 +792,7 @@ export GEMINI_API_KEY=...
 }
 ```

-`voiceCall.enabled` 默认为 `true`；使用 Twilio 传输方式时，它会将实际 PSTN 呼叫和 DTMF 委派给 Voice Call 插件。如果未启用 `voice-call`，Google Meet 仍然可以验证并记录拨号计划，但无法发起 Twilio 呼叫。
+`voiceCall.enabled` 默认为 `true`；使用 Twilio 传输时，它会将实际的 PSTN 呼叫和 DTMF 委派给 Voice Call 插件。如果未启用 `voice-call`，Google Meet 仍然可以验证和记录拨号方案，但无法发起 Twilio 呼叫。

 ## 工具

@ -740,15 +807,17 @@ export GEMINI_API_KEY=...
 }
 ```

-当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。当 Chrome 运行在已配对节点（例如 Parallels VM）上时，使用 `transport: "chrome-node"`。这两种情况下，实时模型和 `openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭证保留在那里。
+当 Chrome 运行在 Gateway 网关主机上时，使用 `transport: "chrome"`。当 Chrome 运行在配对节点（例如 Parallels VM）上时，使用
+`transport: "chrome-node"`。在这两种情况下，实时模型和 `openclaw_agent_consult` 都运行在 Gateway 网关主机上，因此模型凭证会保留在那里。

-使用 `action: "status"` 可列出活动会话或检查某个会话 ID。使用带 `sessionId` 和 `message` 的 `action: "speak"` 可让实时智能体立即发言。使用 `action: "test_speech"` 可创建或复用会话，触发一个已知短语，并在 Chrome 主机可报告时返回 `inCall` 健康状态。使用 `action: "leave"` 可将某个会话标记为结束。
+使用 `action: "status"` 可列出活动会话或检查某个会话 ID。使用
+`action: "speak"` 并传入 `sessionId` 和 `message`，可让实时智能体立即发言。使用 `action: "test_speech"` 可创建或复用会话、触发一段已知短语，并在 Chrome 主机能够报告时返回 `inCall` 健康状态。使用 `action: "leave"` 可将会话标记为已结束。

-可用时，`status` 包含 Chrome 健康信息：
+`status` 在可用时包含 Chrome 健康状态：

- `inCall`：Chrome 看起来已进入 Meet 通话
- `micMuted`：尽力检测的 Meet 麦克风状态
- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限授予或浏览器控制修复，之后语音才能工作
+- `inCall`：Chrome 似乎已进入 Meet 通话
+- `micMuted`：尽力获取的 Meet 麦克风状态
+- `manualActionRequired` / `manualActionReason` / `manualActionMessage`：浏览器配置文件需要手动登录、Meet 主持人准入、权限授予或浏览器控制修复，否则语音无法工作
 - `providerConnected` / `realtimeReady`：实时语音桥接状态
 - `lastInputAt` / `lastOutputAt`：最近一次从桥接接收或发送音频的时间

@ -762,25 +831,27 @@ export GEMINI_API_KEY=...

 ## 实时智能体咨询

-Chrome 实时模式针对实时语音循环进行了优化。实时语音提供商会听取会议音频，并通过配置的音频桥接进行发言。当实时模型需要更深入的推理、最新信息或普通 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。
+Chrome 实时模式针对实时语音回路进行了优化。实时语音提供商会听取会议音频，并通过配置的音频桥接发声。当实时模型需要更深入的推理、当前信息或常规 OpenClaw 工具时，它可以调用 `openclaw_agent_consult`。

-咨询工具会在后台运行常规 OpenClaw 智能体，附带最近会议转录上下文，并向实时语音会话返回简洁的口语回答。随后语音模型可以将该回答说回会议中。它与 Voice Call 共用同一个实时咨询工具。
+咨询工具会在后台运行常规 OpenClaw 智能体，带上最近的会议转录上下文，并向实时语音会话返回简洁的口头回答。随后语音模型可以将该回答说回会议中。它与 Voice Call 共用同一个实时咨询工具。

-`realtime.toolPolicy` 控制咨询运行方式：
+`realtime.toolPolicy` 控制咨询运行：

- `safe-read-only`：暴露咨询工具，并将常规智能体限制为使用 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。
- `owner`：暴露咨询工具，并允许常规智能体使用普通智能体工具策略。
- `none`：不向实时语音模型暴露咨询工具。
+- `safe-read-only`：暴露咨询工具，并将常规智能体限制为
+  `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和
+  `memory_get`。
+- `owner`：暴露咨询工具，并让常规智能体使用正常的智能体工具策略。
+- `none`：不要将咨询工具暴露给实时语音模型。

-咨询会话键按每个 Meet 会话划分作用域，因此在同一次会议期间，后续咨询调用可以复用之前的咨询上下文。
+咨询会话键会按每个 Meet 会话进行作用域隔离，因此后续咨询调用可以在同一场会议期间复用先前的咨询上下文。

-如果要在 Chrome 完全加入通话后强制执行一次口头就绪检查：
+若要在 Chrome 完全加入通话后强制执行一次口头就绪检查：

 ```bash
 openclaw googlemeet speak meet_... "Say exactly: I'm here and listening."
 ```

-若要执行完整的加入并发言冒烟测试：
+完整的加入并发言冒烟测试：

 ```bash
 openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
@ -788,9 +859,9 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
  --message "Say exactly: I'm here and listening."
 ```

-## Live 测试检查清单
+## 实时测试检查清单

-在将会议交给无人值守智能体之前，使用以下顺序：
+在将会议交给无人值守的智能体之前，请使用以下顺序：

 ```bash
 openclaw googlemeet setup
@ -800,15 +871,15 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \
  --message "Say exactly: Google Meet speech test complete."
 ```

-预期的 `chrome-node` 状态：
+预期的 Chrome-node 状态：

 - `googlemeet setup` 全部为绿色。
- 当 `chrome-node` 是默认传输方式或某个节点已固定时，`googlemeet setup` 包含 `chrome-node-connected`。
+- 当 `chrome-node` 是默认传输方式或已固定某个节点时，`googlemeet setup` 会包含 `chrome-node-connected`。
 - `nodes status` 显示所选节点已连接。
- 所选节点同时声明 `googlemeet.chrome` 和 `browser.proxy`。
- Meet 标签页加入通话，并且 `test-speech` 返回包含 `inCall: true` 的 Chrome 健康状态。
+- 所选节点同时通告 `googlemeet.chrome` 和 `browser.proxy`。
+- Meet 标签页已加入通话，并且 `test-speech` 返回的 Chrome 健康状态中包含 `inCall: true`。

-对于远程 Chrome 主机（例如 Parallels macOS VM），这是在 Gateway 网关或 VM 更新后最短的安全检查：
+对于远程 Chrome 主机，例如 Parallels macOS VM，在更新 Gateway 网关或 VM 后，这是最短且安全的检查方式：

 ```bash
 openclaw googlemeet setup
@ -819,9 +890,9 @@ openclaw nodes invoke \
  --params '{"action":"setup"}'
 ```

-这可以证明 Gateway 网关插件已加载，VM 节点已使用当前令牌连接，并且 Meet 音频桥接可用，然后智能体才会打开真实会议标签页。
+这可以证明 Gateway 网关插件已加载、VM 节点已使用当前令牌连接，并且 Meet 音频桥接在智能体打开真实会议标签页之前已可用。

-对于 Twilio 冒烟测试，请使用一个公开电话拨入详情的会议：
+对于 Twilio 冒烟测试，请使用一个会公开电话拨入详情的会议：

 ```bash
 openclaw googlemeet setup
@ -833,27 +904,29 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \

 预期的 Twilio 状态：

- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和 `twilio-voice-call-credentials` 检查项。
- Gateway 网关重新加载后，CLI 中可用 `voicecall`。
- 返回的会话具有 `transport: "twilio"` 和 `twilio.voiceCallId`。
- `googlemeet leave <sessionId>` 会挂断已委派的语音通话。
+- `googlemeet setup` 包含绿色的 `twilio-voice-call-plugin` 和
+  `twilio-voice-call-credentials` 检查。
+- Gateway 网关重新加载后，CLI 中可以使用 `voicecall`。
+- 返回的会话具有 `transport: "twilio"` 和一个 `twilio.voiceCallId`。
+- `googlemeet leave <sessionId>` 会挂断委派的语音呼叫。

 ## 故障排除

 ### 智能体看不到 Google Meet 工具

-确认插件已在 Gateway 网关配置中启用，并重新加载 Gateway 网关：
+确认该插件已在 Gateway 网关配置中启用，并重新加载 Gateway 网关：

 ```bash
 openclaw plugins list | grep google-meet
 openclaw googlemeet setup
 ```

-如果你刚刚修改了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。正在运行的智能体只能看到当前 Gateway 网关进程注册的插件工具。
+如果你刚刚编辑了 `plugins.entries.google-meet`，请重启或重新加载 Gateway 网关。
+正在运行的智能体只能看到由当前 Gateway 网关进程注册的插件工具。

 ### 没有已连接的 Google Meet 可用节点

-在节点主机上运行：
+在节点主机上，运行：

 ```bash
 openclaw plugins enable google-meet
@ -870,7 +943,7 @@ openclaw devices approve <requestId>
 openclaw nodes status
 ```

-该节点必须已连接，并列出 `googlemeet.chrome` 和 `browser.proxy`。
+该节点必须已连接，并列出 `googlemeet.chrome` 以及 `browser.proxy`。
 Gateway 网关配置必须允许这些节点命令：

 ```json5
@ -884,7 +957,7 @@ Gateway 网关配置必须允许这些节点命令：
 ```

 如果 `googlemeet setup` 的 `chrome-node-connected` 检查失败，或者 Gateway 网关日志报告
-`gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启该节点。对于 LAN Gateway 网关，通常意味着：
+`gateway token mismatch`，请使用当前 Gateway 网关令牌重新安装或重启节点。对于局域网 Gateway 网关，通常意味着：

 ```bash
 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
@ -895,7 +968,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \
  --force
 ```

-然后重新加载节点服务，并再次运行：
+然后重新加载节点服务，并重新运行：

 ```bash
 openclaw googlemeet setup
@ -904,30 +977,38 @@ openclaw nodes status --connected

 ### 浏览器已打开，但智能体无法加入

-运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果它报告 `manualActionRequired: true`，请向操作员显示 `manualActionMessage`，并在浏览器操作完成前停止重试。
+运行 `googlemeet test-speech` 并检查返回的 Chrome 健康状态。如果它报告
+`manualActionRequired: true`，请将 `manualActionMessage` 展示给操作人员，并在浏览器操作完成前停止重试。

 常见的手动操作：

 - 登录 Chrome 配置文件。
- 从 Meet 主持人账户批准该访客加入。
+- 从 Meet 主持账号准许访客加入。
 - 当 Chrome 原生权限提示出现时，授予 Chrome 麦克风/摄像头权限。
 - 关闭或修复卡住的 Meet 权限对话框。

-不要仅因为 Meet 显示 “Do you want people to hear you in the meeting?” 就报告“未登录”。这是 Meet 的音频选择过渡页；OpenClaw 会在可用时通过浏览器自动化点击 **Use microphone**，然后继续等待真正的会议状态。对于仅创建的浏览器回退路径，OpenClaw 可能会点击 **Continue without microphone**，因为创建 URL 不需要实时音频路径。
+不要仅仅因为 Meet 显示“Do you want people to hear you in the meeting?” 就报告“未登录”。这是 Meet 的音频选择过渡页；OpenClaw 会在可用时通过浏览器自动化点击 **Use microphone**，并继续等待真正的会议状态。对于仅创建的浏览器回退，因为创建 URL 不需要实时音频路径，OpenClaw 可能会点击 **Continue without microphone**。

 ### 会议创建失败

-配置了 OAuth 凭证时，`googlemeet create` 会优先使用 Google Meet API `spaces.create` 端点。没有 OAuth 凭证时，它会回退到固定的 Chrome 节点浏览器。请确认：
+配置了 OAuth 凭证时，`googlemeet create` 会优先使用 Google Meet API 的 `spaces.create` 端点。没有 OAuth 凭证时，它会回退到固定的 Chrome 节点浏览器。请确认：

- 对于 API 创建：已配置 `oauth.clientId` 和 `oauth.refreshToken`，或存在对应的 `OPENCLAW_GOOGLE_MEET_*` 环境变量。
- 对于 API 创建：刷新令牌是在支持创建功能后生成的。较旧的令牌可能缺少 `meetings.space.created` 作用域；请重新运行 `openclaw googlemeet auth login --json` 并更新插件配置。
- 对于浏览器回退：`defaultTransport: "chrome-node"` 和 `chromeNode.node` 指向一个已连接节点，并且该节点具有 `browser.proxy` 和 `googlemeet.chrome`。
+- 对于 API 创建：已配置 `oauth.clientId` 和 `oauth.refreshToken`，或存在匹配的 `OPENCLAW_GOOGLE_MEET_*` 环境变量。
+- 对于 API 创建：刷新令牌是在加入创建支持后生成的。较旧的令牌可能缺少 `meetings.space.created` 作用域；请重新运行
+  `openclaw googlemeet auth login --json` 并更新插件配置。
+- 对于浏览器回退：`defaultTransport: "chrome-node"` 和
+  `chromeNode.node` 指向一个已连接节点，并且该节点具有 `browser.proxy` 和
+  `googlemeet.chrome`。
 - 对于浏览器回退：该节点上的 OpenClaw Chrome 配置文件已登录 Google，并且可以打开 `https://meet.google.com/new`。
- 对于浏览器回退：重试会复用现有的 `https://meet.google.com/new` 或 Google 账户提示标签页，而不是打开新标签页。如果智能体超时，请重试工具调用，而不是手动再打开另一个 Meet 标签页。
- 对于浏览器回退：如果工具返回 `manualActionRequired: true`，请使用返回的 `browser.nodeId`、`browser.targetId`、`browserUrl` 和 `manualActionMessage` 来指导操作员。在该操作完成前，不要循环重试。
- 对于浏览器回退：如果 Meet 显示 “Do you want people to hear you in the meeting?”，请保持该标签页打开。OpenClaw 应通过浏览器自动化点击 **Use microphone**，或者在仅创建回退路径中点击 **Continue without microphone**，然后继续等待生成的 Meet URL。如果无法做到，错误中应提到 `meet-audio-choice-required`，而不是 `google-login-required`。
+- 对于浏览器回退：重试会复用已有的 `https://meet.google.com/new`
+  或 Google 账号提示标签页，而不是打开新标签页。如果智能体超时，请重试工具调用，而不是手动再打开一个 Meet 标签页。
+- 对于浏览器回退：如果工具返回 `manualActionRequired: true`，请使用返回的
+  `browser.nodeId`、`browser.targetId`、`browserUrl` 和
+  `manualActionMessage` 来引导操作人员。在该操作完成前，不要循环重试。
+- 对于浏览器回退：如果 Meet 显示“Do you want people to hear you in the
+  meeting?”，请保持标签页打开。OpenClaw 应通过浏览器自动化点击 **Use microphone**，或者在仅创建回退场景下点击 **Continue without microphone**，并继续等待生成的 Meet URL。如果无法完成，错误应提及 `meet-audio-choice-required`，而不是 `google-login-required`。

-### 智能体已加入但没有说话
+### 智能体已加入但不说话

 检查实时路径：

@ -936,32 +1017,35 @@ openclaw googlemeet setup
 openclaw googlemeet doctor
 ```

-使用 `mode: "realtime"` 进行收听/回话。`mode: "transcribe"` 会有意不启动双工实时语音桥接。
+使用 `mode: "realtime"` 进行收听/回话。`mode: "transcribe"` 则是有意不启动双工实时语音桥接。

 还要验证：

- Gateway 网关主机上有可用的实时提供商密钥，例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。
- `BlackHole 2ch` 在 Chrome 主机上可见。
- Chrome 主机上存在 `rec` 和 `play`。
+- Gateway 网关主机上有可用的实时提供商密钥，例如
+  `OPENAI_API_KEY` 或 `GEMINI_API_KEY`。
+- 在 Chrome 主机上可以看到 `BlackHole 2ch`。
+- 在 Chrome 主机上存在 `rec` 和 `play`。
 - Meet 的麦克风和扬声器已通过 OpenClaw 使用的虚拟音频路径进行路由。

-`googlemeet doctor [session-id]` 会打印会话、节点、通话中状态、手动操作原因、实时提供商连接、`realtimeReady`、音频输入/输出活动、最近音频时间戳、字节计数以及浏览器 URL。当你需要原始 JSON 时，请使用 `googlemeet status [session-id]`。当你需要在不暴露令牌的情况下验证 Google Meet OAuth 刷新时，请使用 `googlemeet doctor --oauth`；如果你还需要 Google Meet API 证明，可再加上 `--meeting` 或 `--create-space`。
+`googlemeet doctor [session-id]` 会打印会话、节点、in-call 状态、手动操作原因、实时提供商连接状态、`realtimeReady`、音频输入/输出活动、最近音频时间戳、字节计数器以及浏览器 URL。
+当你需要原始 JSON 时，请使用 `googlemeet status [session-id]`。当你需要验证 Google Meet OAuth 刷新且不暴露令牌时，请使用
+`googlemeet doctor --oauth`；当你还需要 Google Meet API 证明时，可额外使用 `--meeting` 或 `--create-space`。

-如果某个智能体已超时，而你能看到一个已打开的 Meet 标签页，请在不打开新标签页的情况下检查该标签页：
+如果某个智能体超时，而你已经看到一个 Meet 标签页处于打开状态，请在不打开新标签页的情况下检查该标签页：

 ```bash
 openclaw googlemeet recover-tab
 openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij
 ```

-等效的工具动作是 `recover_current_tab`。它会聚焦并检查已配置 Chrome 节点上的现有 Meet 标签页。它不会打开新标签页，也不会创建新会话；它会报告当前阻塞因素，例如登录、准入、权限或音频选择状态。CLI 命令会连接到已配置的 Gateway 网关，因此 Gateway 网关必须正在运行，且 Chrome 节点必须已连接。
+对应的工具操作是 `recover_current_tab`。它会聚焦并检查配置的 Chrome 节点上现有的 Meet 标签页。它不会打开新标签页，也不会创建新会话；它会报告当前阻塞项，例如登录、准入、权限或音频选择状态。该 CLI 命令会与已配置的 Gateway 网关通信，因此 Gateway 网关必须正在运行，并且 Chrome 节点必须已连接。

 ### Twilio 设置检查失败

 当 `voice-call` 未被允许或未启用时，`twilio-voice-call-plugin` 会失败。
-将其添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，然后重新加载 Gateway 网关。
+请将其添加到 `plugins.allow`，启用 `plugins.entries.voice-call`，并重新加载 Gateway 网关。

-当 Twilio 后端缺少 account SID、auth token 或主叫号码时，`twilio-voice-call-credentials` 会失败。在 Gateway 网关主机上设置以下内容：
+当 Twilio 后端缺少 account SID、auth token 或主叫号码时，`twilio-voice-call-credentials` 会失败。在 Gateway 网关主机上设置这些值：

 ```bash
 export TWILIO_ACCOUNT_SID=AC...
@ -977,13 +1061,13 @@ openclaw voicecall setup
 openclaw voicecall smoke
 ```

-默认情况下，`voicecall smoke` 仅执行就绪性检查。若要对特定号码执行 dry-run：
+默认情况下，`voicecall smoke` 仅用于就绪性检查。若要对某个特定号码执行 dry-run：

 ```bash
 openclaw voicecall smoke --to "+15555550123"
 ```

-只有在你明确要发起真实的外呼通知电话时，才添加 `--yes`：
+只有当你明确希望发起真实的外呼通知电话时，才添加 `--yes`：

 ```bash
 openclaw voicecall smoke --to "+15555550123" --yes
@ -991,7 +1075,7 @@ openclaw voicecall smoke --to "+15555550123" --yes

 ### Twilio 呼叫已开始，但始终未进入会议

-确认 Meet 事件公开了电话拨入详情。传入准确的拨入号码和 PIN，或自定义 DTMF 序列：
+确认 Meet 事件公开了电话拨入详情。传入准确的拨入号码和 PIN，或者一个自定义 DTMF 序列：

 ```bash
 openclaw googlemeet join https://meet.google.com/abc-defg-hij \
@ -1004,20 +1088,21 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \

 ## 说明

-Google Meet 的官方媒体 API 偏向接收，因此向 Meet 通话中发言仍然需要一个参会者路径。这个插件让这条边界保持可见：
+Google Meet 的官方媒体 API 偏向接收，因此要在 Meet 通话中发言，仍然需要一个参会者路径。该插件让这一边界保持可见：
 Chrome 负责浏览器参会和本地音频路由；Twilio 负责电话拨入参会。

 Chrome 实时模式需要以下之一：

 - `chrome.audioInputCommand` 加 `chrome.audioOutputCommand`：OpenClaw 拥有实时模型桥接，并在这些命令与所选实时语音提供商之间传输 8 kHz G.711 mu-law 音频。
- `chrome.audioBridgeCommand`：一个外部桥接命令拥有整个本地音频路径，并且必须在启动或验证其守护进程后退出。
+- `chrome.audioBridgeCommand`：一个外部桥接命令拥有完整的本地音频路径，并且必须在启动或验证其守护进程后退出。

-若要获得干净的双工音频，请将 Meet 输出和 Meet 麦克风通过独立的虚拟设备或类似 Loopback 的虚拟设备图进行路由。单个共享的 BlackHole 设备可能会把其他参会者的声音回传到通话中。
+为了获得干净的双工音频，请将 Meet 输出和 Meet 麦克风路由到不同的虚拟设备，或使用类似 Loopback 的虚拟设备图。单个共享的 BlackHole 设备可能会将其他参会者的声音回送到通话中。

-`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥接。`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委派的 Twilio 会话，`leave` 还会挂断底层语音通话。
+`googlemeet speak` 会触发 Chrome 会话的活动实时音频桥接。
+`googlemeet leave` 会停止该桥接。对于通过 Voice Call 插件委派的 Twilio 会话，`leave` 还会挂断底层语音呼叫。

-## 相关
+## 相关内容

- [Voice call plugin](/zh-CN/plugins/voice-call)
- [Talk mode](/zh-CN/nodes/talk)
+- [Voice call 插件](/zh-CN/plugins/voice-call)
+- [Talk 模式](/zh-CN/nodes/talk)
 - [构建插件](/zh-CN/plugins/building-plugins)
--- a/docs/zh-CN/tools/image-generation.md
+++ b/docs/zh-CN/tools/image-generation.md
@ -6,23 +6,23 @@ read_when:
 summary: 使用已配置的提供商（OpenAI、OpenAI Codex OAuth、Google Gemini、OpenRouter、fal、MiniMax、ComfyUI、Vydra、xAI）生成和编辑图像
 title: 图像生成
 x-i18n:
-    generated_at: "2026-04-24T23:42:15Z"
+    generated_at: "2026-04-25T07:51:43Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 8cfa462ba943e816d26215898bcf201fe118c96a618f2d340b0db22cc1409f56
+    source_hash: 02369928fecac147729ca586cd39e1a88791219ffe26d8e94429d0ea4b1af411
    source_path: tools/image-generation.md
    workflow: 15
 ---

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

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

 ## 快速开始

-1. 为至少一个提供商设置 API 密钥（例如 `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,16 +38,17 @@ x-i18n:
 ```

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

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

-智能体会自动调用 `image_generate`。无需配置工具允许列表——只要有可用提供商，它默认就会启用。
+智能体会自动调用 `image_generate`。不需要工具允许列表——只要有可用提供商，它就会默认启用。

 ## 常见路由

@ -58,24 +59,24 @@ Codex OAuth 使用同一个 `openai/gpt-image-2` 模型引用。当配置了
 | 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` 等输出提示参数会被转发；当提供商不支持时，工具结果中会报告这些参数已被忽略。
+同一个 `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` |
+| OpenAI | `gpt-image-2` | 是（最多 4 张图像） | `OPENAI_API_KEY` 或 OpenAI Codex OAuth |
+| OpenRouter | `google/gemini-3.1-flash-image-preview` | 是（最多 5 张输入图像） | `OPENROUTER_API_KEY` |
 | Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
 | fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` |
 | MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） |
-| ComfyUI | `workflow` | 是（1 张图片，由工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
+| ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | 云端需 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
 | Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` |
-| xAI | `grok-imagine-image` | 是（最多 5 张图片） | `XAI_API_KEY` |
+| xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` |

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

 ```
 /tool image_generate action=list
@ -84,11 +85,11 @@ Codex OAuth 使用同一个 `openai/gpt-image-2` 模型引用。当配置了
 ## 工具参数

 <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">
@ -96,11 +97,11 @@ Codex OAuth 使用同一个 `openai/gpt-image-2` 模型引用。当配置了
 </ParamField>

 <ParamField path="image" type="string">
-用于编辑模式的单个参考图路径或 URL。
+编辑模式下的单张参考图路径或 URL。
 </ParamField>

 <ParamField path="images" type="string[]">
-用于编辑模式的多个参考图（最多 5 张）。
+编辑模式下的多张参考图（最多 5 张）。
 </ParamField>

 <ParamField path="size" type="string">
@ -128,7 +129,7 @@ Codex OAuth 使用同一个 `openai/gpt-image-2` 模型引用。当配置了
 </ParamField>

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

 <ParamField path="filename" type="string">
@ -136,12 +137,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` 则记录请求值到应用值的转换。

 ## 配置

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

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

-注意：
+说明：

 - 每次调用的 `model` 覆盖是精确的：OpenClaw 只会尝试该提供商 / 模型，
-  不会继续尝试配置的主模型 / 后备模型或自动检测到的
+  不会继续尝试已配置的主模型 / 回退模型或自动检测到的
  提供商。
- 自动检测具备认证感知能力。只有当 OpenClaw 实际能够认证某个提供商时，
+- 自动检测会感知认证状态。只有当 OpenClaw 实际能够对某个提供商进行认证时，
  该提供商默认值才会进入候选列表。
 - 自动检测默认启用。若你希望图像
-  生成只使用显式的 `model`、`primary` 和 `fallbacks`
+  生成仅使用显式的 `model`、`primary` 和 `fallbacks`
  条目，请设置
  `agents.defaults.mediaGenerationAutoProviderFallback: false`。
- 使用 `action: "list"` 可查看当前已注册的提供商、它们的
-  默认模型，以及认证环境变量提示。
+- 使用 `action: "list"` 可查看当前已注册的提供商、
+  其默认模型以及认证环境变量提示。

 ### 图像编辑

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

 ```
-"将这张照片生成水彩风格版本" + image: "/path/to/photo.jpg"
+"把这张照片生成成水彩画风格" + image: "/path/to/photo.jpg"
 ```

 OpenAI、OpenRouter、Google 和 xAI 通过 `images` 参数最多支持 5 张参考图。fal、MiniMax 和 ComfyUI 支持 1 张。

 ### OpenRouter 图像模型

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

 ```json5
 {
@ -217,26 +218,28 @@ 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 配置文件，OpenClaw 会复用同一个用于 Codex
-订阅聊天模型的 OAuth 配置文件，并通过 Codex Responses 后端发送图像请求；
-它不会在该请求中静默回退到
-`OPENAI_API_KEY`。若要强制直接路由到 OpenAI Images API，
-请显式配置 `models.providers.openai`，提供 API 密钥、自定义 base URL
-或 Azure 端点。较旧的
+`openai-codex` OAuth 配置文件，OpenClaw 会复用同一个 OAuth
+配置文件——也就是 Codex 订阅聊天模型使用的那个——并通过
+Codex Responses 后端发送图像请求。旧版 Codex 基础 URL，例如
+`https://chatgpt.com/backend-api`，会在图像请求中规范化为
+`https://chatgpt.com/backend-api/codex`。它不会
+静默回退到该请求的 `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 会向 OpenAI 转发 `prompt`、
-`count`、`size`、`quality`、`outputFormat` 和参考图像。
-OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下，
-OpenClaw 会将它们映射为受支持的 `size`，否则工具会报告它们
-作为被忽略的覆盖参数。
+`gpt-image-2` 通过同一个 `image_generate` 工具同时支持文生图
+和参考图编辑。OpenClaw 会将 `prompt`、
+`count`、`size`、`quality`、`outputFormat` 以及参考图像转发给 OpenAI。
+OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下
+OpenClaw 会将它们映射为受支持的 `size`，否则工具会将其报告为
+已忽略的覆盖项。

 OpenAI 专用选项位于 `openai` 对象下：

@ -257,7 +260,7 @@ OpenAI 专用选项位于 `openai` 对象下：
 输出要求 `outputFormat` 为 `png` 或 `webp`。`openai.outputCompression`
 适用于 JPEG/WebP 输出。

-生成一张 4K 横版图像：
+生成一张 4K 横向图像：

 ```
 /tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
@ -269,7 +272,7 @@ OpenAI 专用选项位于 `openai` 对象下：
 /tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
 ```

-编辑一张本地参考图像：
+编辑一张本地参考图：

 ```
 /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
@ -281,43 +284,43 @@ OpenAI 专用选项位于 `openai` 对象下：
 /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
 ```

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

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

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

 ## 提供商能力

 | 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
 | --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
 | 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） | 是（最多 4 张） |
-| 编辑 / 参考图 | 是（最多 5 张图片） | 是（最多 5 张图片） | 是（1 张图片） | 是（1 张图片，主体参考） | 是（1 张图片，由工作流配置） | 否 | 是（最多 5 张图片） |
+| 编辑 / 参考图 | 是（最多 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 管理的图像附件返回

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

 ## 相关内容

- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具
+- [工具概览](/zh-CN/tools) — 所有可用的智能体工具
 - [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置
 - [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置
 - [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置
@ -325,5 +328,5 @@ OpenClaw 有意不公开 xAI 原生的 `quality`、`mask`、`user` 或
 - [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置
 - [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置
 - [xAI](/zh-CN/providers/xai) — Grok 图像、视频、搜索、代码执行和 TTS 设置
- [Configuration Reference](/zh-CN/gateway/config-agents#agent-defaults) — `imageGenerationModel` 配置
+- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — `imageGenerationModel` 配置
 - [Models](/zh-CN/concepts/models) — 模型配置和故障切换