chore(i18n): refresh zh-CN translations

2026-04-22 22:34:24 +00:00 · 2026-04-22 22:34:24 +00:00 · 8b0f41c613
commit 8b0f41c613
parent 990a0e6456
3 changed files with 955 additions and 945 deletions
--- a/docs/zh-CN/concepts/models.md
+++ b/docs/zh-CN/concepts/models.md
@ -1,47 +1,47 @@
 ---
 read_when:
    - 添加或修改模型 CLI（`models list/set/scan/aliases/fallbacks`）
-    - 更改模型回退行为或选择 UX
+    - 更改模型回退行为或选择体验
    - 更新模型扫描探测项（工具/图像）
 summary: 模型 CLI：列出、设置、别名、回退、扫描、状态
 title: 模型 CLI
 x-i18n:
-    generated_at: "2026-04-22T19:54:32Z"
+    generated_at: "2026-04-22T22:26:04Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 99174b625d265fe4743f4e0ca7ea3897bb446a485dde0841e101fe136a08558a
+    source_hash: 18d915f3f761aaff5efc3bf752f5abddeb625e1a386ab3d701f46fd92244f20e
    source_path: concepts/models.md
    workflow: 15
 ---

 # 模型 CLI

-关于凭证配置文件轮换、冷却时间及其与回退机制的交互方式，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
-提供商快速概览与示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。
+有关凭证配置文件轮换、冷却时间及其与回退如何交互的信息，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
+快速提供商概览 + 示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。

 ## 模型选择的工作方式

 OpenClaw 按以下顺序选择模型：

 1. **主** 模型（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
-2. `agents.defaults.model.fallbacks` 中的 **回退模型**（按顺序）。
-3. **提供商凭证回退** 会在切换到下一个模型之前，于提供商内部发生。
+2. `agents.defaults.model.fallbacks` 中的**回退**模型（按顺序）。
+3. **提供商凭证故障切换**会先在提供商内部发生，然后才会切换到下一个模型。

 相关项：

- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（也包含别名）。
- `agents.defaults.imageModel` **仅在** 主模型无法接受图像时使用。
+- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（以及别名）。
+- `agents.defaults.imageModel` **仅在**主模型无法接受图像时使用。
 - `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会依次回退到 `agents.defaults.imageModel`，然后是已解析的会话/默认模型。
- `agents.defaults.imageGenerationModel` 用于共享的图像生成功能。如果省略，`image_generate` 仍可推断出一个带凭证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也要同时配置该提供商的凭证/API 密钥。
- `agents.defaults.musicGenerationModel` 用于共享的音乐生成功能。如果省略，`music_generate` 仍可推断出一个带凭证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也要同时配置该提供商的凭证/API 密钥。
- `agents.defaults.videoGenerationModel` 用于共享的视频生成功能。如果省略，`video_generate` 仍可推断出一个带凭证的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也要同时配置该提供商的凭证/API 密钥。
- 每个智能体的默认值可通过 `agents.list[].model` 及其绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。
+- `agents.defaults.imageGenerationModel` 用于共享的图像生成功能。如果省略，`image_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。
+- `agents.defaults.musicGenerationModel` 用于共享的音乐生成功能。如果省略，`music_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。
+- `agents.defaults.videoGenerationModel` 用于共享的视频生成功能。如果省略，`video_generate` 仍可推断出一个有凭证支持的默认提供商。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。
+- 每个智能体的默认值可以通过 `agents.list[].model` 加上绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。

 ## 快速模型策略

- 将你的主模型设为你可用的、最新一代中能力最强的模型。
+- 将你的主模型设为你可用的最新一代中能力最强的模型。
 - 对成本/延迟敏感的任务和风险较低的聊天，使用回退模型。
- 对启用了工具的智能体或不可信输入，避免使用较旧/较弱的模型层级。
+- 对启用了工具的智能体或不受信任的输入，避免使用较旧/较弱档位的模型。

 ## 新手引导（推荐）

@ -51,7 +51,8 @@ OpenClaw 按以下顺序选择模型：
 openclaw onboard
 ```

-它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code（Codex）订阅**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。
+它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex)
+subscription**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。

 ## 配置键名（概览）

@ -63,23 +64,36 @@ openclaw onboard
 - `agents.defaults.models`（允许列表 + 别名 + 提供商参数）
 - `models.providers`（写入 `models.json` 的自定义提供商）

-模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为 `zai/*`。
+模型引用会被标准化为小写。像 `z.ai/*` 这样的提供商别名会标准化为
+`zai/*`。

 提供商配置示例（包括 OpenCode）位于
 [/providers/opencode](/zh-CN/providers/opencode)。

+### 安全地编辑允许列表
+
+手动更新 `agents.defaults.models` 时，请使用追加式写入：
+
+```bash
+openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge
+```
+
+`openclaw config set` 会保护模型/提供商映射，避免被意外覆盖。当对 `agents.defaults.models`、`models.providers` 或 `models.providers.<id>.models` 进行普通对象赋值且会移除现有条目时，该操作会被拒绝。对追加式更改使用 `--merge`；仅当提供的值应成为完整目标值时才使用 `--replace`。
+
+交互式提供商设置和 `openclaw configure --section model` 也会将按提供商范围选择的内容合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商时，不会丢失无关的模型条目。
+
 ## “Model is not allowed”（以及为什么回复会停止）

-如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时，OpenClaw 会返回：
+如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择了不在该允许列表中的模型时，OpenClaw 会返回：

 ```
 Model "provider/model" is not allowed. Use /model to list available models.
 ```

-这会发生在生成正常回复**之前**，因此消息看起来会像是“没有响应”。修复方法是以下之一：
+这会在正常回复生成**之前**发生，因此消息会让人感觉它“没有响应”。修复方法是以下之一：

- 将该模型添加到 `agents.defaults.models`，或者
- 清除允许列表（移除 `agents.defaults.models`），或者
+- 将该模型添加到 `agents.defaults.models`，或
+- 清除允许列表（移除 `agents.defaults.models`），或
 - 从 `/model list` 中选择一个模型。

 允许列表示例配置：
@ -98,9 +112,9 @@ Model "provider/model" is not allowed. Use /model to list available models.

 ## 在聊天中切换模型（`/model`）

-你可以为当前会话切换模型，而无需重启：
+你可以在不重启的情况下为当前会话切换模型：

-```text
+```
 /model
 /model list
 /model 3
@ -110,26 +124,26 @@ Model "provider/model" is not allowed. Use /model to list available models.

 说明：

- `/model`（以及 `/model list`）是紧凑的编号选择器（模型家族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，带有提供商和模型下拉菜单，以及一个提交步骤。
+- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。
+- 在 Discord 中，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个“提交”步骤。
 - `/models add` 默认可用，可通过 `commands.modelsWrite=false` 禁用。
- 启用后，`/models add <provider> <modelId>` 是最快路径；仅输入 `/models add` 时，会在支持的情况下启动一个从提供商开始的引导式流程。
- 执行 `/models add` 后，无需重启 Gateway 网关，新模型就会在 `/models` 和 `/model` 中可用。
- `/model <#>` 会从该选择器中选择。
+- 启用后，`/models add <provider> <modelId>` 是最快路径；仅输入 `/models add` 会在支持的情况下启动一个“先选提供商”的引导流程。
+- 在执行 `/models add` 后，新模型会立即在 `/models` 和 `/model` 中可用，无需重启 Gateway 网关。
+- `/model <#>` 会从该选择器中进行选择。
 - `/model` 会立即持久化新的会话选择。
- 如果智能体处于空闲状态，下一次运行会立即使用新模型。
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并且只会在一个干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续某个重试机会或下一次用户轮次。
- `/model status` 是详细视图（凭证候选项，以及在已配置时提供商端点 `baseUrl` + `api` 模式）。
- 模型引用通过按**第一个** `/` 分割来解析。输入 `/model <ref>` 时请使用 `provider/model`。
+- 如果智能体处于空闲状态，下次运行会立即使用新模型。
+- 如果某次运行已在进行中，OpenClaw 会将实时切换标记为待处理，并只会在一个干净的重试点重启到新模型。
+- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到稍后的重试机会或下一个用户轮次。
+- `/model status` 是详细视图（凭证候选项，以及在已配置时显示的提供商端点 `baseUrl` + `api` 模式）。
+- 模型引用通过按**第一个** `/` 进行拆分来解析。输入 `/model <ref>` 时请使用 `provider/model`。
 - 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。
- 如果你省略了提供商，OpenClaw 会按以下顺序解析输入：
+- 如果你省略提供商，OpenClaw 会按以下顺序解析输入：
  1. 别名匹配
  2. 对该精确无前缀模型 ID 的唯一已配置提供商匹配
-  3. 已弃用的回退：使用已配置的默认提供商  
-     如果该提供商不再暴露已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露一个陈旧的、已移除提供商默认值。
+  3. 已弃用的回退：使用已配置的默认提供商
+     如果该提供商已不再公开配置中的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露陈旧且已移除提供商的默认值。

-完整命令行为/配置：[/tools/slash-commands](/zh-CN/tools/slash-commands)。
+完整命令行为/配置： [斜杠命令](/zh-CN/tools/slash-commands)。

 示例：

@ -166,7 +180,7 @@ openclaw models image-fallbacks clear

 ### `models list`

-默认显示已配置的模型。常用标志：
+默认显示已配置模型。有用的标志：

 - `--all`：完整目录
 - `--local`：仅本地提供商
@ -174,16 +188,16 @@ openclaw models image-fallbacks clear
 - `--plain`：每行一个模型
 - `--json`：机器可读输出

-`--all` 会在配置凭证之前，先包含由内置提供商拥有的静态目录条目，因此仅用于发现的视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。
+`--all` 会在配置凭证之前包含内置的、由提供商拥有的静态目录条目，因此仅发现视图可以显示那些在你添加匹配提供商凭证之前不可用的模型。

 ### `models status`

-显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内发出警告）。`--plain` 仅打印已解析的主模型。
-OAuth 状态始终会显示（也会包含在 `--json` 输出中）。如果某个已配置的提供商没有凭证，`models status` 会打印一个 **Missing auth** 小节。
-JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的生效凭证，包括由环境变量提供的凭证）。`auth.oauth` 仅表示凭证存储中的配置文件健康状态；仅使用环境变量的提供商不会出现在其中。
-自动化场景请使用 `--check`（缺失/过期时退出码为 `1`，即将过期时为 `2`）。
-使用 `--probe` 可进行实时凭证检查；探测行可以来自凭证配置文件、环境变量凭证或 `models.json`。
-如果显式的 `auth.order.<provider>` 省略了一个已存储的配置文件，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果凭证存在，但无法为该提供商解析出可探测的模型，则探测会报告 `status: no_model`。
+显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 过期状态（默认在 24 小时内到期时发出警告）。`--plain` 仅打印已解析的主模型。
+OAuth 状态始终会显示（也会包含在 `--json` 输出中）。如果某个已配置提供商没有凭证，`models status` 会打印一个 **缺少凭证** 部分。JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的生效凭证，包括由环境变量支持的凭证）。`auth.oauth` 仅表示凭证存储配置文件的健康状态；仅使用环境变量的提供商不会出现在其中。
+自动化场景请使用 `--check`（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。
+使用 `--probe` 可执行实时凭证检查；探测行可来自凭证配置文件、环境变量凭证或 `models.json`。
+如果显式 `auth.order.<provider>` 省略了一个已存储配置文件，探测会报告
+`excluded_by_auth_order`，而不是尝试它。如果凭证存在，但无法为该提供商解析出可探测模型，则探测会报告 `status: no_model`。

 凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常是最可预测的；也支持复用 Claude CLI，以及现有的 Anthropic OAuth/token 配置文件。

@ -196,7 +210,7 @@ openclaw models status

 ## 扫描（OpenRouter 免费模型）

-`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型是否支持工具和图像。
+`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型对工具和图像的支持情况。

 关键标志：

@ -205,12 +219,13 @@ openclaw models status
 - `--max-age-days <days>`：跳过较旧模型
 - `--provider <name>`：提供商前缀筛选
 - `--max-candidates <n>`：回退列表大小
- `--set-default`：将 `agents.defaults.model.primary` 设为第一个选中项
- `--set-image`：将 `agents.defaults.imageModel.primary` 设为第一个图像选中项
+- `--set-default`：将 `agents.defaults.model.primary` 设为第一个选择项
+- `--set-image`：将 `agents.defaults.imageModel.primary` 设为第一个图像选择项

-探测需要 OpenRouter API 密钥（来自凭证配置文件或 `OPENROUTER_API_KEY`）。如果没有密钥，请使用 `--no-probe` 仅列出候选项。
+探测需要 OpenRouter API 密钥（来自凭证配置文件或
+`OPENROUTER_API_KEY`）。没有密钥时，请使用 `--no-probe` 仅列出候选项。

-扫描结果按以下顺序排序：
+扫描结果按以下条件排序：

 1. 图像支持
 2. 工具延迟
@ -228,25 +243,25 @@ openclaw models status

 ## 模型注册表（`models.json`）

-`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认路径为 `~/.openclaw/agents/<agentId>/agent/models.json`）。默认会合并该文件，除非 `models.mode` 设为 `replace`。
+`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认是 `~/.openclaw/agents/<agentId>/agent/models.json`）。默认情况下，此文件会被合并，除非 `models.mode` 设为 `replace`。

-对于匹配的提供商 ID，合并模式优先级如下：
+匹配提供商 ID 的合并模式优先级：

 - 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。
- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中**不是** SecretRef 管理时才优先。
- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。
+- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中**不是**由 SecretRef 管理时优先。
+- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的秘密值。
 - 由 SecretRef 管理的提供商请求头值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。
- 智能体中为空或缺失的 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
- 其他提供商字段会从配置和已规范化的目录数据中刷新。
+- 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
+- 其他提供商字段会从配置和标准化目录数据中刷新。

-标记持久化以源为准：OpenClaw 会从活动源配置快照（解析前）写入标记，而不是从已解析的运行时密钥值写入。
-只要 OpenClaw 重新生成 `models.json`，这一规则都会适用，包括 `openclaw agent` 这样的命令驱动路径。
+标记持久化以源为准：OpenClaw 会根据当前源配置快照（预解析）写入标记，而不是根据运行时已解析的秘密值写入。
+这适用于 OpenClaw 重新生成 `models.json` 的任何情况，包括像 `openclaw agent` 这样的命令驱动路径。

 ## 相关内容

- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由与凭证
- [模型回退](/zh-CN/concepts/model-failover) — 回退链
- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置
- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置
- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名
+- [Model Providers](/zh-CN/concepts/model-providers) — 提供商路由和凭证
+- [Model Failover](/zh-CN/concepts/model-failover) — 回退链
+- [Image Generation](/zh-CN/tools/image-generation) — 图像模型配置
+- [Music Generation](/zh-CN/tools/music-generation) — 音乐模型配置
+- [Video Generation](/zh-CN/tools/video-generation) — 视频模型配置
+- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名
--- a/docs/zh-CN/gateway/configuration-reference.md
+++ b/docs/zh-CN/gateway/configuration-reference.md
--- a/docs/zh-CN/gateway/configuration.md
+++ b/docs/zh-CN/gateway/configuration.md
@ -2,32 +2,32 @@
 read_when:
    - 首次设置 OpenClaw
    - 查找常见配置模式
-    - 导航到特定配置章节
+    - 跳转到特定配置章节
 summary: 配置概览：常见任务、快速设置，以及完整参考的链接
 title: 配置
 x-i18n:
-    generated_at: "2026-04-22T21:30:52Z"
+    generated_at: "2026-04-22T22:25:42Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 36162008b66dcaaac6d51882f20d74aebd9b637bfddde00395cdfbd5721e3d20
+    source_hash: 2296617a25a339048cb1df7b895fec35e96b0740851c89add907fc49307e08d1
    source_path: gateway/configuration.md
    workflow: 15
 ---

 # 配置

-OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
+OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置文件。

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

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

-有关每个可用字段，请参阅[完整参考](/zh-CN/gateway/configuration-reference)。
+请参阅[完整参考](/zh-CN/gateway/configuration-reference)以查看所有可用字段。

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

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

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

 Schema 工具说明：

- `openclaw config schema` 会输出与 Control UI 和配置校验使用的同一套 JSON Schema。
- 将该 schema 输出视为 `openclaw.json` 的规范机器可读契约；本概览和配置参考只是对其进行总结。
- 字段 `title` 和 `description` 的值会被带入 schema 输出，供编辑器和表单工具使用。
- 嵌套对象、通配符（`*`）和数组项（`[]`）条目会在存在匹配字段文档时继承相同的文档元数据。
- `anyOf` / `oneOf` / `allOf` 组合分支也会继承相同的文档元数据，因此联合/交叉变体会保留相同的字段帮助信息。
- `config.schema.lookup` 会返回一个标准化的配置路径，其中包含一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界及类似校验字段）、匹配的 UI 提示元数据，以及直属子节点摘要，供下钻式工具使用。
- 当 Gateway 网关 可以加载当前 manifest 注册表时，运行时插件/渠道 schema 也会被合并进来。
- `pnpm config:docs:check` 会检测面向文档的配置基线产物与当前 schema 表面之间的漂移。
+- `openclaw config schema` 会输出与控制 UI
+  和配置校验所使用的同一套 JSON Schema。
+- 请将该 schema 输出视为 `openclaw.json` 的规范性机器可读契约；
+  本概览和配置参考只是对其进行总结。
+- 字段 `title` 和 `description` 的值会被带入 schema 输出，
+  供编辑器和表单工具使用。
+- 嵌套对象、通配符（`*`）和数组项（`[]`）条目会继承相同的
+  文档元数据，前提是存在匹配的字段文档。
+- `anyOf` / `oneOf` / `allOf` 组合分支同样会继承相同的文档
+  元数据，因此联合 / 交叉变体会保留相同的字段帮助信息。
+- `config.schema.lookup` 会返回一个规范化的配置路径，以及一个浅层
+  schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界
+  及类似校验字段）、匹配的 UI 提示元数据，以及直接子项摘要，
+  供下钻式工具使用。
+- 当 Gateway 网关 能加载当前 manifest 注册表时，运行时插件 / 渠道 schema
+  也会被合并进去。
+- `pnpm config:docs:check` 会检测面向文档的配置基线产物
+  与当前 schema 表面之间的漂移。

 当校验失败时：

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

-Gateway 网关 在成功启动后还会保留一份受信任的“最近一次已知正常”副本。如果
-`openclaw.json` 之后在 OpenClaw 外部被修改且不再通过校验，启动
-和热重载会将损坏文件保留为带时间戳的 `.clobbered.*` 快照，
-恢复最近一次已知正常的副本，并记录包含恢复原因的醒目警告。
-如果在原本有效的 JSON 配置前意外插入了一行状态/日志内容，
-Gateway 网关 启动和 `openclaw doctor --fix` 也可以剥离该前缀，
-将被污染的文件保留为 `.clobbered.*`，并继续使用恢复后的
+Gateway 网关 还会在成功启动后保留一份可信的“上次已知正常”副本。如果
+`openclaw.json` 之后在 OpenClaw 之外被修改，且不再通过校验，那么启动
+和热重载都会将损坏的文件保留为带时间戳的 `.clobbered.*` 快照，
+恢复“上次已知正常”副本，并记录一条醒目的警告，说明恢复原因。
+如果某条状态 / 日志行被意外追加在原本有效的 JSON
+配置前面，Gateway 网关 启动和 `openclaw doctor --fix` 可以剥离该前缀，
+将污染后的文件保留为 `.clobbered.*`，并继续使用恢复后的
 JSON。
-下一次主智能体回合还会收到一条系统事件警告，告知其该
-配置已被恢复，且不得盲目重写。最近一次已知正常副本的提升
-会在校验通过的启动后以及接受的热重载后更新，其中包括
-由 OpenClaw 自身写入且持久化文件哈希仍与已接受
-写入匹配的配置。若候选内容包含被遮蔽的密钥占位符
-（如 `***`）或被截短的令牌值，则不会执行提升。
+下一次主智能体回合也会收到一条 system-event 警告，告知其配置已被
+恢复，且不得盲目重写。已验证启动后，以及已接受的热重载后，
+“上次已知正常”提升也会更新，其中包括由 OpenClaw 写入、且持久化文件哈希
+仍与已接受写入匹配的配置。若候选内容中包含已脱敏的密钥
+占位符，例如 `***` 或缩短后的 token 值，则会跳过提升。

 ## 常见任务

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

    - [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp`
    - [Telegram](/zh-CN/channels/telegram) — `channels.telegram`
@ -143,7 +152,7 @@ JSON。
  </Accordion>

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

    ```json5
    {
@ -162,11 +171,12 @@ JSON。
    }
    ```

-    - `agents.defaults.models` 定义模型目录，并作为 `/model` 的 allowlist。
+    - `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` 控制 transcript/tool 图像缩小尺寸（默认值为 `1200`）；在大量截图的运行中，较低的值通常会减少视觉 token 使用量。
-    - 在聊天中切换模型，请参阅[模型 CLI](/zh-CN/concepts/models)；有关凭证轮换和回退行为，请参阅[模型故障切换](/zh-CN/concepts/model-failover)。
-    - 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。
+    - `agents.defaults.imageMaxDimensionPx` 控制 transcript / tool 图像缩放下采样（默认值为 `1200`）；较低的值通常会减少以截图为主的运行中的视觉 token 使用量。
+    - 参见[模型 CLI](/zh-CN/concepts/models)，了解如何在聊天中切换模型；参见[模型故障切换](/zh-CN/concepts/model-failover)，了解凭证轮换和回退行为。
+    - 对于自定义 / 自托管 provider，请参见参考中的[自定义 providers](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。

  </Accordion>

@ -174,18 +184,18 @@ JSON。
    私信访问通过每个渠道的 `dmPolicy` 进行控制：

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

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

-    有关每个渠道的详细信息，请参阅[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)。
+    每个渠道的详细信息请参阅[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)。

  </Accordion>

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

    ```json5
    {
@ -207,9 +217,9 @@ JSON。
    }
    ```

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

  </Accordion>

@ -224,24 +234,24 @@ JSON。
          skills: ["github", "weather"],
        },
        list: [
-          { id: "writer" }, // 继承 github、weather
-          { id: "docs", skills: ["docs-search"] }, // 替换默认值
-          { id: "locked-down", skills: [] }, // 不使用任何 Skills
+          { id: "writer" }, // inherits github, weather
+          { id: "docs", skills: ["docs-search"] }, // replaces defaults
+          { id: "locked-down", skills: [] }, // no skills
        ],
      },
    }
    ```

-    - 省略 `agents.defaults.skills` 可使默认情况下的 Skills 不受限制。
-    - 省略 `agents.list[].skills` 将继承默认值。
-    - 设置 `agents.list[].skills: []` 表示不使用任何 Skills。
-    - 请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及
+    - 省略 `agents.defaults.skills` 表示默认情况下 Skills 不受限制。
+    - 省略 `agents.list[].skills` 表示继承默认值。
+    - 设置 `agents.list[].skills: []` 表示不启用任何 Skills。
+    - 参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)，以及
      [配置参考](/zh-CN/gateway/configuration-reference#agents-defaults-skills)。

  </Accordion>

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

    ```json5
    {
@ -265,8 +275,8 @@ JSON。

    - 设置 `gateway.channelHealthCheckMinutes: 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` 可为单个渠道或账户禁用自动重启，而无需禁用全局监控。
+    - 参见[健康检查](/zh-CN/gateway/health)了解运维调试内容，并查看[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。

  </Accordion>

@ -292,9 +302,9 @@ JSON。
    ```

    - `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/configuration-reference#session)。
+    - `threadBindings`：thread-bound 会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
+    - 参见[会话管理](/zh-CN/concepts/session)了解作用域、身份关联和发送策略。
+    - 参见[完整参考](/zh-CN/gateway/configuration-reference#session)了解所有字段。

  </Accordion>

@ -314,14 +324,14 @@ JSON。
    }
    ```

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

    完整指南请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)，所有选项请参阅[完整参考](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)。

  </Accordion>

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

    在 Gateway 网关 配置中设置：

@ -341,43 +351,43 @@ JSON。
    }
    ```

-    等效 CLI：
+    对应的 CLI 命令：

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

-    作用如下：
+    这样做的作用：

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

    端到端流程：

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

-    运行说明：
+    运维说明：

-    - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它发布一个绑定到该 Gateway 网关 的新 relay 注册。
+    - 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它可以发布一个绑定到该 Gateway 网关 的新 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_ALLOW_HTTP=true` 仍然是仅限 local loopback 的开发逃生口；不要在配置中持久化 HTTP relay URL。

-    完整端到端流程请参阅[iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型请参阅[认证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)。
+    端到端流程请参阅[iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型请参阅[身份验证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)。

  </Accordion>

-  <Accordion title="设置 heartbeat（周期性签到）">
+  <Accordion title="设置 heartbeat（周期性报到）">
    ```json5
    {
      agents: {
@ -393,8 +403,8 @@ JSON。

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

  </Accordion>

@ -413,9 +423,9 @@ JSON。
    }
    ```

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

  </Accordion>

@ -444,20 +454,20 @@ JSON。
    ```

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

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

  </Accordion>

  <Accordion title="配置多智能体路由">
-    运行多个隔离的智能体，并分别使用各自的工作区和会话：
+    使用不同的 workspace 和会话运行多个相互隔离的智能体：

    ```json5
    {
@ -474,7 +484,7 @@ JSON。
    }
    ```

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

  </Accordion>

@ -492,12 +502,12 @@ JSON。
    }
    ```

-    - **单个文件**：替换其所在的对象
-    - **文件数组**：按顺序深度合并（后者优先）
-    - **同级键**：在 include 之后合并（覆盖被 include 的值）
-    - **嵌套 include**：支持，最多 10 层深
+    - **单个文件**：替换所在的整个对象
+    - **文件数组**：按顺序深度合并（后者覆盖前者）
+    - **同级键**：在 include 之后合并（覆盖已包含的值）
+    - **嵌套 include**：最多支持 10 层嵌套
    - **相对路径**：相对于包含它的文件解析
-    - **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误信息
+    - **错误处理**：对缺失文件、解析错误和循环 include 提供明确错误

  </Accordion>
 </AccordionGroup>
@ -506,26 +516,26 @@ JSON。

 Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——对于大多数设置，无需手动重启。

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

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

 ### 重载模式

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

 ```json5
 {
@ -535,63 +545,63 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
 }
 ```

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

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

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

 <Note>
-`gateway.reload` 和 `gateway.remote` 是例外——更改它们 **不会** 触发重启。
+`gateway.reload` 和 `gateway.remote` 是例外——更改它们**不会**触发重启。
 </Note>

 ## 配置 RPC（程序化更新）

 <Note>
-控制平面写入 RPC（`config.apply`、`config.patch`、`update.run`）会按 `deviceId+clientIp` 进行限流：**每 60 秒最多 3 个请求**。达到限制时，RPC 会返回 `UNAVAILABLE` 和 `retryAfterMs`。
+控制平面写入 RPC（`config.apply`、`config.patch`、`update.run`）会按每个 `deviceId+clientIp` 限速为**每 60 秒 3 次请求**。被限流时，RPC 会返回 `UNAVAILABLE` 并附带 `retryAfterMs`。
 </Note>

-安全/默认流程：
+安全 / 默认流程：

 - `config.schema.lookup`：检查单个路径范围的配置子树，返回一个浅层
-  schema 节点、匹配的提示元数据以及直属子节点摘要
- `config.get`：获取当前快照和哈希
- `config.patch`：推荐的部分更新路径
+  schema 节点、匹配的提示元数据，以及直接子项摘要
+- `config.get`：获取当前快照 + 哈希
+- `config.patch`：首选的部分更新路径
 - `config.apply`：仅用于完整配置替换
- `update.run`：显式执行自更新 + 重启
+- `update.run`：显式自更新 + 重启

-当你不是要替换整个配置时，优先使用 `config.schema.lookup`
+如果你不是要替换整个配置，优先使用 `config.schema.lookup`
 然后再使用 `config.patch`。

 <AccordionGroup>
  <Accordion title="config.apply（完整替换）">
-    校验并写入完整配置，然后一步完成 Gateway 网关 重启。
+    在一步内校验并写入完整配置，然后重启 Gateway 网关。

    <Warning>
-    `config.apply` 会替换**整个配置**。如需部分更新，请使用 `config.patch`；如需更新单个键，请使用 `openclaw config set`。
+    `config.apply` 会替换**整个配置**。部分更新请使用 `config.patch`，单个键请使用 `openclaw config set`。
    </Warning>

    参数：

-    - `raw`（字符串）— 整个配置的 JSON5 载荷
-    - `baseHash`（可选）— 来自 `config.get` 的配置哈希（配置已存在时为必需）
+    - `raw`（字符串）— 整个配置的 JSON5 负载
+    - `baseHash`（可选）— 来自 `config.get` 的配置哈希（配置已存在时为必填）
    - `sessionKey`（可选）— 重启后唤醒 ping 使用的会话键
-    - `note`（可选）— 用于重启哨兵的备注
-    - `restartDelayMs`（可选）— 重启前延迟（默认值为 2000）
+    - `note`（可选）— 写入重启哨兵的说明
+    - `restartDelayMs`（可选）— 重启前延迟（默认 2000）

-    当已有重启处于待处理/进行中时，重启请求会被合并，并且两次重启周期之间会应用 30 秒冷却时间。
+    当某个重启已在等待中 / 进行中时，重启请求会被合并处理，并且两次重启周期之间会有 30 秒冷却时间。

    ```bash
-    openclaw gateway call config.get --params '{}'  # 获取 payload.hash
+    openclaw gateway call config.get --params '{}'  # capture payload.hash
    openclaw gateway call config.apply --params '{
      "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
      "baseHash": "<hash>",
@ -605,16 +615,16 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
    将部分更新合并到现有配置中（JSON merge patch 语义）：

    - 对象递归合并
-    - `null` 删除键
-    - 数组整体替换
+    - `null` 删除一个键
+    - 数组会整体替换

    参数：

-    - `raw`（字符串）— 只包含待更改键的 JSON5
-    - `baseHash`（必需）— 来自 `config.get` 的配置哈希
+    - `raw`（字符串）— 只包含要更改键名的 JSON5
+    - `baseHash`（必填）— 来自 `config.get` 的配置哈希
    - `sessionKey`、`note`、`restartDelayMs` — 与 `config.apply` 相同

-    重启行为与 `config.apply` 一致：待处理重启会被合并，且两次重启周期之间有 30 秒冷却时间。
+    重启行为与 `config.apply` 一致：会合并待处理的重启请求，并在两次重启周期之间应用 30 秒冷却时间。

    ```bash
    openclaw gateway call config.patch --params '{
@ -628,12 +638,12 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改——

 ## 环境变量

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

 - 当前工作目录中的 `.env`（如果存在）
 - `~/.openclaw/.env`（全局回退）

-这两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量：
+这两个文件都不会覆盖已有的环境变量。你也可以在配置中设置内联环境变量：

 ```json5
 {
@ -645,7 +655,7 @@ OpenClaw 会从父进程读取环境变量，此外还会读取：
 ```

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

 ```json5
 {
@ -655,11 +665,11 @@ OpenClaw 会从父进程读取环境变量，此外还会读取：
 }
 ```

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

 <Accordion title="在配置值中替换环境变量">
-  可在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量：
+  你可以在任意配置字符串值中通过 `${VAR_NAME}` 引用环境变量：

 ```json5
 {
@ -670,10 +680,10 @@ OpenClaw 会从父进程读取环境变量，此外还会读取：

 规则：

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

 </Accordion>
@ -711,15 +721,15 @@ OpenClaw 会从父进程读取环境变量，此外还会读取：
 }
 ```

-有关 SecretRef 的详细信息（包括用于 `env` / `file` / `exec` 的 `secrets.providers`），请参阅[密钥管理](/zh-CN/gateway/secrets)。
-支持的凭证路径列在 [SecretRef 凭证表面](/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)。
+完整的优先级和来源请参阅[环境变量](/zh-CN/help/environment)。

 ## 完整参考

-有关完整的逐字段参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。
+如需查看按字段逐项说明的完整参考，请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。

 ---