chore(i18n): refresh zh-CN translations

2026-04-25 20:15:53 +00:00 · 2026-04-25 20:15:53 +00:00 · ff8a323c88
commit ff8a323c88
parent 85b4c5b9d5
4 changed files with 622 additions and 622 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 配置
+    - 调整会话、消息传递和通话模式行为
+summary: 智能体默认值、多智能体路由、会话、消息和通话配置
 title: 配置 — 智能体
 x-i18n:
-    generated_at: "2026-04-25T18:33:45Z"
+    generated_at: "2026-04-25T20:12:47Z"
    model: gpt-5.4
    provider: openai
-    source_hash: d017648f522fe7be7cfca2691735132f60888c8c1ac6d84689ab327e9187e965
+    source_hash: 0f072438d8445e494b296d2d48f31841292f55758270c2f8095df5c89a6ba013
    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,7 +40,7 @@ x-i18n:

 ### `agents.defaults.skills`

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

 ```json5
 {
@ -49,7 +49,7 @@ x-i18n:
    list: [
      { id: "writer" }, // 继承 github、weather
      { id: "docs", skills: ["docs-search"] }, // 替换默认值
-      { id: "locked-down", skills: [] }, // 无 Skills
+      { id: "locked-down", skills: [] }, // 没有 Skills
    ],
  },
 }
@ -57,12 +57,12 @@ x-i18n:

 - 省略 `agents.defaults.skills`，则默认 Skills 不受限制。
 - 省略 `agents.list[].skills`，则继承默认值。
- 设置 `agents.list[].skills: []` 表示不启用任何 Skills。
+- 设置 `agents.list[].skills: []` 表示没有 Skills。
 - 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。

 ### `agents.defaults.skipBootstrap`

-禁用自动创建工作区 bootstrap 文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
+禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。

 ```json5
 {
@ -72,10 +72,10 @@ x-i18n:

 ### `agents.defaults.contextInjection`

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

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

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

 ### `agents.defaults.bootstrapMaxChars`

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

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

 ### `agents.defaults.bootstrapTotalMaxChars`

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

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

 ### `agents.defaults.bootstrapPromptTruncationWarning`

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

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

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

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

-OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统有意拆分，而不是全部通过一个通用开关控制。
+OpenClaw 有多个高容量的提示 / 上下文预算，这些预算是有意按子系统拆分的，而不是全部通过一个通用旋钮来控制。

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

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

 - `agents.list[].skillsLimits.maxSkillsPromptChars`
 - `agents.list[].contextLimits.*`

 #### `agents.defaults.startupContext`

-控制在纯 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。
+控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。

 ```json5
 {
@ -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` 摘录上限。
+- `postCompactionMaxChars`：在压缩后刷新注入期间，`AGENTS.md` 摘录的上限。

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

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

 ```json5
 {
@ -213,8 +212,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统

 #### `skills.limits.maxSkillsPromptChars`

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

 ```json5
 {
@ -228,7 +226,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统

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

-针对 Skills 提示预算的按智能体覆盖。
+按智能体覆盖 Skills 提示预算。

 ```json5
 {
@ -247,8 +245,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统

 ### `agents.defaults.imageMaxDimensionPx`

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

 较低的值通常会减少视觉 token 使用量以及以截图为主的运行中的请求负载大小。
 较高的值则会保留更多视觉细节。
@ -261,7 +258,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统

 ### `agents.defaults.userTimezone`

-用于系统提示上下文的时区（不影响消息时间戳）。如果未设置，则回退到主机时区。
+系统提示上下文所用的时区（不影响消息时间戳）。回退到主机时区。

 ```json5
 {
@ -309,7 +306,7 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
-      params: { cacheRetention: "long" }, // 全局默认 provider 参数
+      params: { cacheRetention: "long" }, // 全局默认提供商参数
      embeddedHarness: {
        runtime: "pi", // pi | auto | 已注册的 harness id，例如 codex
        fallback: "pi", // pi | none
@ -330,51 +327,51 @@ OpenClaw 有多个高容量提示/上下文预算，这些预算会按子系统

 - `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
  - 字符串形式仅设置主模型。
-  - 对象形式设置主模型以及按顺序的故障切换模型。
+  - 对象形式设置主模型以及按顺序排列的故障转移模型。
 - `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
-  - 作为 `image` 工具路径的视觉模型配置使用。
-  - 当所选/默认模型无法接受图像输入时，也会用作回退路由。
+  - 用作 `image` 工具路径的视觉模型配置。
+  - 当所选 / 默认模型无法接受图像输入时，也会用作回退路由。
 - `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，或 `openai/gpt-image-1.5` 用于支持透明背景的 OpenAI PNG/WebP 输出。
-  - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证（例如，`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。
-  - 如果省略，`image_generate` 仍可推断出一个具备凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。
+  - 用于共享的图像生成功能，以及任何将来会生成图像的工具 / 插件表面。
+  - 常见值：`google/gemini-3.1-flash-image-preview`（用于原生 Gemini 图像生成）、`fal/fal-ai/flux/dev`（用于 fal）、`openai/gpt-image-2`（用于 OpenAI Images），或 `openai/gpt-image-1.5`（用于支持透明背景的 OpenAI PNG/WebP 输出）。
+  - 如果你直接选择某个 provider / model，也要配置匹配的提供商凭证，例如：`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` / `openai/gpt-image-1.5` 使用 `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.6`。
-  - 如果省略，`music_generate` 仍可推断出一个具备凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。
-  - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API 密钥。
+  - 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。
+  - 如果省略，`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` 仍可推断出一个具备凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。
-  - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API 密钥。
+  - 常见值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
+  - 如果省略，`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`，然后再回退到已解析的会话/默认模型。
+  - 如果省略，PDF 工具会回退到 `imageModel`，再回退到已解析的会话 / 默认模型。
 - `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
 - `pdfMaxPages`：`pdf` 工具在提取回退模式下默认考虑的最大页数。
- `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
+- `verboseDefault`：智能体的默认详细输出级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
 - `elevatedDefault`：智能体的默认增强输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
- `model.primary`：格式为 `provider/model`（例如，`openai/gpt-5.5` 用于 API 密钥访问，或 `openai-codex/gpt-5.5` 用于 Codex OAuth）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是暴露一个陈旧的、已移除提供商默认值。
- `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` 会拒绝会移除现有允许列表条目的替换操作。
-  - 提供商作用域的配置/新手引导流程会将所选提供商模型合并到该映射中，并保留已配置的无关提供商。
-  - 对于直接使用的 OpenAI Responses 模型，服务端压缩会自动启用。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
+- `model.primary`：格式为 `provider/model`（例如，使用 API key 访问时为 `openai/gpt-5.5`，使用 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 模型合并到这个映射中，并保留已配置的其他无关提供商。
+  - 对于直接使用的 OpenAI Responses 模型，会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
 - `params`：应用于所有模型的全局默认提供商参数。设置在 `agents.defaults.params`（例如 `{ cacheRetention: "long" }`）。
- `params` 的合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后 `agents.list[].params`（匹配的智能体 id）会按键覆盖。详见 [Prompt Caching](/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`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧式运行时提供商前缀。关于它与提供商/模型选择的区别，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
- 会变更这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退项添加/删除命令）会保存为规范对象形式，并尽可能保留现有回退列表。
- `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 以及其他执行后端。关于这与 provider / model 选择的区别，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
+- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及 fallback add / remove 命令）会保存规范的对象形式，并尽可能保留现有的回退列表。
+- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话仍然串行）。默认值：4。

 ### `agents.defaults.embeddedHarness`

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

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

 - `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册为 `codex`。
- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略时默认值为 `"pi"`，这样旧配置在没有插件 harness 接管运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略时默认值为 `"none"`，这样缺少 harness 时会直接失败，而不是静默使用 PI。运行时覆盖不会从更宽作用域继承 fallback；如果你有意需要该兼容回退，请在显式 runtime 旁边一并设置 `fallback: "pi"`。所选插件 harness 的失败始终会直接暴露。
+- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略 `fallback` 时默认是 `"pi"`，这样旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略 `fallback` 时默认是 `"none"`，这样在缺少 harness 时会失败，而不是静默改用 PI。运行时覆盖项不会继承更广作用域中的 fallback；如果你确实希望保留这种兼容回退，需要与显式运行时一起设置 `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 选择会按会话 id 固定。配置/环境变量变更会影响新的或已重置的会话，不会影响现有转录。带有转录历史但未记录固定值的旧会话会被视为固定到 PI。`/status` 会报告生效的运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
- 这仅控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。
+- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以显式设置 `embeddedHarness.fallback: "none"` 以增强可读性；这是显式插件运行时的默认值。
+- 在第一次内嵌运行后，harness 选择会按会话 id 固定。配置 / 环境变量的更改会影响新会话或已重置的会话，不会影响现有 transcript。具有 transcript 历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会报告实际运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
+- 这仅控制内嵌聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider / model 设置。

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

 | 别名                | 模型                                       |
 | ------------------- | ------------------------------------------ |
@ -411,15 +408,15 @@ Codex 应用服务器 harness。关于其心智模型，参见
 | `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` 思考。
+Z.AI GLM-4.x 模型会自动启用 thinking 模式，除非你设置 `--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 模型在未设置显式 thinking 级别时，默认使用 `adaptive` thinking。

 ### `agents.defaults.cliBackends`

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

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

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

 ### `agents.defaults.systemPromptOverride`

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

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

 ### `agents.defaults.promptOverlays`

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

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

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

 ### `agents.defaults.heartbeat`

@ -497,16 +494,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
  agents: {
    defaults: {
      heartbeat: {
-        every: "30m", // 0m 表示禁用
+        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
-        includeSystemPromptSection: true, // 默认：true；false 会从系统提示中省略 Heartbeat 部分
-        lightContext: false, // 默认：false；true 只保留工作区 bootstrap 文件中的 HEARTBEAT.md
-        isolatedSession: false, // 默认：false；true 会让每次 heartbeat 在全新会话中运行（无对话历史）
+        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
+        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
+        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        session: "main",
        to: "+15555550123",
-        directPolicy: "allow", // allow（默认） | block
-        target: "none", // 默认：none | 可选值：last | whatsapp | telegram | discord | ...
+        directPolicy: "allow", // allow (default) | block
+        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
@ -517,14 +514,14 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
 }
 ```

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

 ### `agents.defaults.compaction`
@ -535,16 +532,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
-        provider: "my-provider", // 已注册 compaction provider 插件的 id（可选）
+        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
-        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用
+        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
-        postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入
-        model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖
-        notifyUser: true, // compaction 开始和完成时发送简短通知（默认：false）
+        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
+        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
+        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
@ -558,20 +555,20 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
 ```

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

 ### `agents.defaults.contextPruning`

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

 ```json5
 {
@ -579,7 +576,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
-        ttl: "1h", // 时长（ms/s/m/h），默认单位：分钟
+        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
@ -595,23 +592,23 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti

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

- `mode: "cache-ttl"` 会启用修剪流程。
- `ttl` 控制下次允许再次执行修剪的时间间隔（自上次缓存触碰后算起）。
- 如有需要，修剪会先对过大的工具结果执行软截断，然后再对更旧的工具结果执行硬清除。
+- `mode: "cache-ttl"` 会启用修剪过程。
+- `ttl` 控制多久之后才允许再次运行修剪（从上次缓存触碰之后开始计算）。
+- 修剪会先对过大的工具结果做软截断，必要时再对更旧的工具结果做硬清除。

 **软截断**会保留开头和结尾，并在中间插入 `...`。

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

-注意：
+注意事项：

- 图像区块永远不会被截断/清除。
- 各比例基于字符数（近似），而不是精确 token 数。
+- 图像块永远不会被截断 / 清除。
+- 比例基于字符数（近似），不是精确的 token 数。
 - 如果 assistant 消息少于 `keepLastAssistants` 条，则会跳过修剪。

 </Accordion>

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

 ### 分块流式传输

@ -623,19 +620,19 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
-      humanDelay: { mode: "natural" }, // off | natural | custom（使用 minMs/maxMs）
+      humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)
    },
  },
 }
 ```

- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。
- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
+- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才能启用分块回复。
+- 渠道覆盖项：`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
 {
@ -648,16 +645,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
 }
 ```

- 默认值：直接聊天/提及时使用 `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
 {
@ -703,7 +700,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
-          // 也支持 SecretRefs / 内联内容：
+          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
@ -769,19 +766,19 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
 - `command`：SSH 客户端命令（默认：`ssh`）
 - `workspaceRoot`：用于按作用域工作区的远程绝对根目录
 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其写入临时文件
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
+- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRef，OpenClaw 会在运行时将其实体化为临时文件
+- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略选项

 **SSH 认证优先级：**

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

 **SSH 后端行为：**

- 在创建或重新创建后，初始化一次远程工作区
+- 在创建或重新创建后，会先为远程工作区执行一次初始化
 - 然后保持远程 SSH 工作区为规范副本
 - 通过 SSH 路由 `exec`、文件工具和媒体路径
 - 不会自动将远程更改同步回主机
@ -789,7 +786,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti

 **工作区访问：**

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

@ -812,10 +809,10 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
-          gateway: "lab", // 可选
-          gatewayEndpoint: "https://lab.example", // 可选
-          policy: "strict", // 可选的 OpenShell 策略 id
-          providers: ["openai"], // 可选
+          gateway: "lab", // optional
+          gatewayEndpoint: "https://lab.example", // optional
+          policy: "strict", // optional OpenShell policy id
+          providers: ["openai"], // optional
          autoProviders: true,
          timeoutSeconds: 120,
        },
@ -827,29 +824,29 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时默认使用 `adapti

 **OpenShell 模式：**

- `mirror`：在执行前从本地初始化远程，执行后同步回本地；本地工作区保持为规范副本
- `remote`：在创建沙箱时仅初始化一次远程，之后保持远程工作区为规范副本
+- `mirror`：在执行前将本地内容同步到远程，执行后再同步回本地；本地工作区保持为规范副本
+- `remote`：在创建沙箱时仅向远程初始化一次，之后保持远程工作区为规范副本

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

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

-**容器默认使用 `network: "none"`**——如果智能体需要出站访问，请设置为 `"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`** 会挂载额外的主机目录；全局和按智能体的绑定会合并。
+**`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`。
- `cdpSourceRange` 可选地将 CDP 入站流量在容器边界限制到某个 CIDR 范围（例如 `172.21.0.1/32`）。
- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
+- `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>`
@ -869,19 +866,20 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时效
  - `--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`
-    会重新启用扩展。
+    默认启用；如果工作流中的 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 的
+    `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 修改；设为 `0` 可使用 Chromium 的
    默认进程限制。
-  - 以及当启用 `noSandbox` 时附加 `--no-sandbox`。
-  - 这些默认值是容器镜像的基线；如需更改容器默认值，请使用带有自定义入口点的自定义浏览器镜像。
+  - 另外，当启用 `noSandbox` 时会附加 `--no-sandbox`。
+  - 这些默认值属于容器镜像基线；如需更改容器默认值，请使用自定义浏览器镜像和自定义
+    entrypoint。

 </Accordion>

-浏览器沙箱隔离和 `sandbox.docker.binds` 仅适用于 Docker。
+浏览器沙箱隔离和 `sandbox.docker.binds` 仅支持 Docker。

 构建镜像：

@ -890,7 +888,7 @@ scripts/sandbox-setup.sh           # 主沙箱镜像
 scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 ```

-### `agents.list`（按智能体覆盖）
+### `agents.list`（按智能体覆盖项）

 ```json5
 {
@ -902,13 +900,13 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
-        model: "anthropic/claude-opus-4-6", // 或 { primary, fallbacks }
-        thinkingDefault: "high", // 按智能体覆盖思考级别
-        reasoningDefault: "on", // 按智能体覆盖推理可见性
-        fastModeDefault: false, // 按智能体覆盖快速模式
+        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
+        thinkingDefault: "high", // per-agent thinking level override
+        reasoningDefault: "on", // per-agent reasoning visibility override
+        fastModeDefault: false, // per-agent fast mode override
        embeddedHarness: { runtime: "auto", fallback: "pi" },
-        params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params
-        skills: ["docs-search"], // 设置时会替换 agents.defaults.skills
+        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
+        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
@ -940,20 +938,20 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 ```

 - `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`。所选提供商/模型配置决定了哪些值有效；对于 Google Gemini，`adaptive` 会保留由提供商控制的动态思考（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）。
+- `default`：如果设置了多个，以第一个为准（会记录警告）。如果一个都没设置，则列表中的第一项是默认值。
+- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 同时覆盖两者（`[]` 会禁用全局 fallback）。仅覆盖 `primary` 的 cron 作业仍会继承默认 fallback，除非你设置 `fallbacks: []`。
+- `params`：按智能体划分的流参数，会合并覆盖到 `agents.defaults.models` 中所选模型条目之上。用它可以为特定智能体覆盖 `cacheRetention`、`temperature` 或 `maxTokens` 等参数，而无需复制整个模型目录。
+- `skills`：可选的按智能体 Skills 允许列表。如果省略，则当设置了 `agents.defaults.skills` 时，该智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示没有 Skills。
+- `thinkingDefault`：可选的按智能体默认 thinking 级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有按消息或按会话的覆盖项时，会覆盖此智能体的 `agents.defaults.thinkingDefault`。所选 provider / model 配置决定哪些值有效；对于 Google Gemini，`adaptive` 会保留由提供商控制的动态 thinking（在 Gemini 3 / 3.1 上省略 `thinkingLevel`，在 Gemini 2.5 上使用 `thinkingBudget: -1`）。
+- `reasoningDefault`：可选的按智能体默认 reasoning 可见性（`on | off | stream`）。当没有按消息或按会话的 reasoning 覆盖项时生效。
+- `fastModeDefault`：可选的按智能体 fast mode 默认值（`true | false`）。当没有按消息或按会话的 fast-mode 覆盖项时生效。
+- `embeddedHarness`：可选的按智能体低级 harness 策略覆盖项。使用 `{ runtime: "codex" }` 可让某一个智能体只使用 Codex，而其他智能体在 `auto` 模式下继续保留默认的 PI fallback。
+- `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）。

 ---

@ -978,11 +976,11 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像

 ### 绑定匹配字段

- `type`（可选）：`route` 用于普通路由（缺失时默认是 route），`acp` 用于持久化 ACP 对话绑定。
+- `type`（可选）：正常路由使用 `route`（未填写 type 时默认是 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 }`

 **确定性匹配顺序：**
@ -990,17 +988,17 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 1. `match.peer`
 2. `match.guildId`
 3. `match.teamId`
-4. `match.accountId`（精确匹配，无 peer/guild/team）
-5. `match.accountId: "*"`（整个渠道）
+4. `match.accountId`（精确匹配，无 peer / guild / team）
+5. `match.accountId: "*"`（整个渠道范围）
 6. 默认智能体

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

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

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

-<Accordion title="完全访问（无沙箱）">
+<Accordion title="完全访问权限（无沙箱）">

 ```json5
 {
@ -1093,7 +1091,7 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像

 </Accordion>

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

 ---

@ -1119,22 +1117,22 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
-    parentForkMaxTokens: 100000, // 父线程超过此 token 数时跳过父线程分叉（0 表示禁用）
+    parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
-      resetArchiveRetention: "30d", // 时长或 false
-      maxDiskBytes: "500mb", // 可选硬预算
-      highWaterBytes: "400mb", // 可选清理目标
+      resetArchiveRetention: "30d", // duration or false
+      maxDiskBytes: "500mb", // optional hard budget
+      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
-      idleHours: 24, // 默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用）
-      maxAgeHours: 0, // 默认按小时计算的最大生命周期上限（`0` 表示禁用）
+      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
+      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
-    mainKey: "main", // 旧版字段（运行时始终使用 "main"）
+    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
@ -1146,35 +1144,35 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像

 <Accordion title="会话字段详情">

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

 </Accordion>

@ -1185,7 +1183,7 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 ```json5
 {
  messages: {
-    responsePrefix: "🦞", // 或 "auto"
+    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
@ -1200,7 +1198,7 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
      },
    },
    inbound: {
-      debounceMs: 2000, // 0 表示禁用
+      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
@ -1212,36 +1210,36 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像

 ### 响应前缀

-按渠道/账号覆盖：`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`           |
-| `{modelFull}`     | 完整模型标识符   | `anthropic/claude-opus-4-6` |
-| `{provider}`      | 提供商名称       | `anthropic`                 |
-| `{thinkingLevel}` | 当前思考级别     | `high`、`low`、`off`        |
-| `{identity.name}` | 智能体身份名称   | （与 `"auto"` 相同）        |
+| 变量              | 说明           | 示例                        |
+| ----------------- | -------------- | --------------------------- |
+| `{model}`         | 短模型名称     | `claude-opus-4-6`           |
+| `{modelFull}`     | 完整模型标识符 | `anthropic/claude-opus-4-6` |
+| `{provider}`      | 提供商名称     | `anthropic`                 |
+| `{thinkingLevel}` | 当前 thinking 级别 | `high`、`low`、`off`    |
+| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同）        |

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

 ### 确认反应

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

 ### 入站防抖

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

 ### TTS（文本转语音）

@ -1291,19 +1289,19 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 }
 ```

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

 ---

-## talk
+## 通话

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

 ```json5
 {
@ -1325,21 +1323,23 @@ Talk 模式的默认设置（macOS/iOS/Android）。
      },
      system: {},
    },
+    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
 }
 ```

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

 ---

--- a/docs/zh-CN/gateway/configuration-reference.md
+++ b/docs/zh-CN/gateway/configuration-reference.md
--- a/docs/zh-CN/install/updating.md
+++ b/docs/zh-CN/install/updating.md
@ -2,18 +2,18 @@
 read_when:
    - 更新 OpenClaw
    - 更新后出现问题
-summary: 安全更新 OpenClaw（全局安装或源码），以及回滚策略
-title: 更新
+summary: 安全更新 OpenClaw（全局安装或源码安装），以及回滚策略
+title: 更新中
 x-i18n:
-    generated_at: "2026-04-25T01:02:44Z"
+    generated_at: "2026-04-25T20:12:46Z"
    model: gpt-5.4
    provider: openai
-    source_hash: af88eaa285145dd5fc370b28c0f9d91069b815c75ec416df726cfce4271a6b54
+    source_hash: edb0fb8514130fbac2d5300dbfef85b8cfea8fafb80cc644eb9054f94131a6d4
    source_path: install/updating.md
    workflow: 15
 ---

-让 OpenClaw 保持最新。
+保持 OpenClaw 为最新版本。

 ## 推荐：`openclaw update`

@ -23,7 +23,7 @@ x-i18n:
 openclaw update
 ```

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

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

-`--channel beta` 会优先选择 beta，但当 beta 标签缺失，或其版本早于最新稳定版时，运行时会回退到 stable/latest。若你想针对一次性的包更新使用原始 npm beta dist-tag，请使用 `--tag beta`。
+`--channel beta` 会优先选择 beta，但当 beta 标签缺失或比最新 stable 版本更旧时，运行时会回退到 stable/latest。若你想在一次性包更新中使用原始的 npm beta dist-tag，请使用 `--tag beta`。

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

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

 ```bash
 curl -fsSL https://openclaw.ai/install.sh | bash
 ```

-添加 `--no-onboard` 可跳过新手引导。对于源码安装，传入 `--install-method git --no-onboard`。
+添加 `--no-onboard` 可跳过新手引导。对于源码安装，请传入 `--install-method git --no-onboard`。

-## 另一种方式：手动使用 npm、pnpm 或 bun
+## 备选方案：手动使用 npm、pnpm 或 bun

 ```bash
 npm i -g openclaw@latest
@ -59,28 +59,28 @@ bun add -g openclaw@latest

 ### 全局 npm 安装与运行时依赖

-OpenClaw 会将打包后的全局安装视为运行时只读，即使当前用户对全局包目录有写权限也是如此。内置插件的运行时依赖会被暂存到一个可写的运行时目录，而不是直接修改包目录树。这样可以避免 `openclaw update` 与正在运行的 Gateway 网关或本地智能体发生竞争，尤其是在同一次安装期间修复插件依赖时。
+OpenClaw 会将打包后的全局安装在运行时视为只读，即使当前用户对全局包目录具有写权限也是如此。内置插件的运行时依赖会被暂存到可写的运行时目录中，而不是直接修改包树。这样可以避免 `openclaw update` 与正在运行的 Gateway 网关或本地智能体发生竞争，因为后者可能在同一次安装期间修复插件依赖。

-某些 Linux 的 npm 配置会将全局包安装到由 root 拥有的目录下，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过同一个外部暂存路径支持这种布局。
+某些 Linux 的 npm 配置会将全局包安装到 root 拥有的目录下，例如 `/usr/lib/node_modules/openclaw`。OpenClaw 通过相同的外部暂存路径支持这种布局。

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

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

-如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供 `$STATE_DIRECTORY` 时优先使用它，否则回退到 `~/.openclaw/plugin-runtime-deps`。
+如果未设置 `OPENCLAW_PLUGIN_STAGE_DIR`，OpenClaw 会在 systemd 提供 `$STATE_DIRECTORY` 时优先使用它，否则回退到 `~/.openclaw/plugin-runtime-deps`。修复步骤会将该暂存区视为由 OpenClaw 管理的本地包根目录，并忽略用户的 npm prefix/global 设置，因此全局安装的 npm 配置不会将内置插件依赖重定向到 `~/node_modules` 或全局包树中。

 ### 内置插件运行时依赖

-打包安装会将内置插件运行时依赖保留在只读包目录树之外。在启动时以及运行 `openclaw doctor --fix` 期间，OpenClaw 仅会为以下内置插件修复运行时依赖：在配置中处于活动状态、通过旧版渠道配置处于活动状态，或在其内置清单默认设置中启用的插件。
+打包安装会将内置插件运行时依赖保留在只读包树之外。在启动时以及执行 `openclaw doctor --fix` 期间，OpenClaw 只会为以下内置插件修复运行时依赖：在配置中处于活动状态、通过旧版渠道配置处于活动状态，或由其内置清单默认启用的插件。

-显式禁用具有最高优先级。已禁用的插件或渠道不会仅因为存在于安装包中就被修复其运行时依赖。外部插件和自定义加载路径仍需使用 `openclaw plugins install` 或 `openclaw plugins update`。
+显式禁用优先。已禁用的插件或渠道，不会仅因为它存在于包中就修复其运行时依赖。外部插件和自定义加载路径仍需使用 `openclaw plugins install` 或 `openclaw plugins update`。

 ## 自动更新器

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

 ```json5
 {
@ -98,11 +98,11 @@ ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp

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

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

 ## 更新后

@ -114,7 +114,7 @@ Gateway 网关 还会在启动时记录更新提示（可通过 `update.checkOnS
 openclaw doctor
 ```

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

 ### 重启 Gateway 网关

@ -140,9 +140,9 @@ openclaw doctor
 openclaw gateway restart
 ```

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

-### 固定到某个提交（源码）
+### 固定提交（源码）

 ```bash
 git fetch origin
@ -151,17 +151,17 @@ pnpm install && pnpm build
 openclaw gateway restart
 ```

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

 ## 如果你卡住了

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

 ## 相关内容

- [安装概览](/zh-CN/install) — 所有安装方式
+- [Install Overview](/zh-CN/install) — 所有安装方式
 - [Doctor](/zh-CN/gateway/doctor) — 更新后的健康检查
- [迁移](/zh-CN/install/migrating) — 主要版本迁移指南
+- [Migrating](/zh-CN/install/migrating) — 主要版本迁移指南
--- a/docs/zh-CN/nodes/talk.md
+++ b/docs/zh-CN/nodes/talk.md
@ -1,14 +1,14 @@
 ---
 read_when:
-    - 在 macOS/iOS/Android 上实现通话模式
+    - 在 macOS / iOS / Android 上实现通话模式
    - 更改语音 / TTS / 打断行为
-summary: 通话模式：与已配置的 TTS 提供商进行连续语音对话
+summary: 通话模式：使用已配置的 TTS 提供商进行连续语音对话
 title: 通话模式
 x-i18n:
-    generated_at: "2026-04-25T19:17:43Z"
+    generated_at: "2026-04-25T20:12:47Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 5f2130c58870000faa6c818587f4a487948f189b777426a81764e37c39204f51
+    source_hash: afdddaa81c0a09076eaeeafd25295b0c02681f03b273ec4afe4ea2afa692dc2a
    source_path: nodes/talk.md
    workflow: 15
 ---
@ -22,15 +22,15 @@ x-i18n:

 ## 行为（macOS）

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

 ## 回复中的语音指令

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

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

 规则：

- 仅第一行非空行有效。
+- 仅第一条非空行有效。
 - 未知键会被忽略。
 - `once: true` 仅应用于当前这次回复。
 - 如果没有 `once`，该语音会成为通话模式新的默认语音。
@ -48,8 +48,8 @@ x-i18n:

 - `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`）
@ -70,6 +70,7 @@ x-i18n:
      },
      system: {},
    },
+    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
@ -79,38 +80,39 @@ x-i18n:
 默认值：

 - `interruptOnSpeech`：true
- `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 语音）。
+- `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 profile）。
- `outputFormat`：在 macOS/iOS 上默认为 `pcm_44100`，在 Android 上默认为 `pcm_24000`（设置为 `mp3_*` 可强制使用 MP3 流式传输）
+- `providers.elevenlabs.apiKey`：会回退到 `ELEVENLABS_API_KEY`（如果可用，也可使用 Gateway 网关 shell 配置文件中的值）。
+- `speechLocale`：可选的 BCP 47 区域设置 ID，用于 `iOS` / `macOS` 上设备端通话语音识别。不设置则使用设备默认值。
+- `outputFormat`：在 `macOS` / `iOS` 上默认是 `pcm_44100`，在 `Android` 上默认是 `pcm_24000`（设置 `mp3_*` 可强制使用 MP3 流式传输）

 ## macOS UI

- 菜单栏开关：**通话**
- 配置标签页：**通话模式**分组（voice id + 打断开关）
+- 菜单栏开关：**Talk**
+- 配置标签页：**Talk Mode** 分组（voice id + 打断开关）
 - 悬浮层：
-  - **监听中**：云朵会随着麦克风音量脉动
-  - **思考中**：下沉动画
-  - **朗读中**：放射状波纹
+  - **Listening**：云朵随麦克风音量脉动
+  - **Thinking**：下沉动画
+  - **Speaking**：向外辐射的圆环
  - 点击云朵：停止朗读
  - 点击 X：退出通话模式

 ## Android UI

- Voice 标签页开关：**通话**
+- 语音标签页开关：**Talk**
 - 手动 **Mic** 和 **Talk** 是互斥的运行时采集模式。
- 当应用离开前台或用户离开 Voice 标签页时，手动 Mic 会停止。
- 通话模式会持续运行，直到被关闭或 Android 节点断开连接，并且在启用期间使用 Android 麦克风前台服务类型。
+- 当应用离开前台或用户离开语音标签页时，手动 Mic 会停止。
+- Talk Mode 会持续运行，直到被关闭或 Android 节点断开连接，并且在启用期间使用 Android 麦克风前台服务类型。

 ## 说明

 - 需要语音和麦克风权限。
- 通过会话键 `main` 使用 `chat.send`。
+- 使用会话键 `main` 对 `chat.send` 发起调用。
 - Gateway 网关会使用当前启用的通话提供商，通过 `talk.speak` 解析通话播放。只有在该 RPC 不可用时，Android 才会回退到本地系统 TTS。
- macOS 本地 MLX 播放会在存在时使用内置的 `openclaw-mlx-tts` helper，或使用 `PATH` 上的可执行文件。开发期间可设置 `OPENCLAW_MLX_TTS_BIN` 来指向自定义 helper 二进制文件。
+- `macOS` 本地 MLX 播放会在可用时使用内置的 `openclaw-mlx-tts` helper，或者使用 `PATH` 上的可执行文件。开发时可设置 `OPENCLAW_MLX_TTS_BIN`，指向自定义 helper 二进制文件。
 - `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` 流式传输。