chore(i18n): refresh zh-CN translations

docs/zh-CN/gateway/cli-backends.md

@@ -1,39 +1,39 @@
 ---
 read_when:
     - 当 API 提供商失败时，你希望有一个可靠的回退方案
-    - 你正在运行 Codex CLI 或其他本地 AI CLI，并且想要复用它们
-    - 你想了解用于 CLI 后端工具访问的 MCP loopback bridge
-summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退机制
+    - 你正在运行 Codex CLI 或其他本地 AI CLI，并希望复用它们
+    - 你想了解用于 CLI 后端工具访问的 MCP loopback 桥接机制
+summary: CLI 后端：带有可选 MCP 工具桥接的本地 AI CLI 回退方案
 title: CLI 后端
 x-i18n:
-    generated_at: "2026-04-25T06:52:28Z"
+    generated_at: "2026-04-25T12:32:55Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 09e184bb99a6c354738c3d770460bc2f282a31c41d2cbce4c1e021ae828ba27c
+    source_hash: 07a4651d7faf1ebafc66bda2e3ade6e541d59c9827f314169e1593e07f0bc2f5
     source_path: gateway/cli-backends.md
     workflow: 15
 ---
 
-OpenClaw 可以在 API 提供商不可用、被限流或暂时异常时运行**本地 AI CLI** 作为**纯文本回退机制**。这是一种有意保持保守的设计：
+OpenClaw 可以在 API 提供商不可用、受到速率限制或暂时行为异常时，将 **本地 AI CLI** 作为 **纯文本回退方案** 运行。这种设计是有意保持保守的：
 
-- **OpenClaw 工具不会被直接注入**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP bridge 接收 Gateway 网关工具。
-- 对支持它的 CLI 提供 **JSONL 流式传输**。
-- **支持会话**（因此后续轮次能保持连贯）。
-- 如果 CLI 接受图像路径，**图像可以透传**。
+- **OpenClaw 工具不会被直接注入**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。
+- 对支持的 CLI 提供 **JSONL 流式传输**。
+- **支持会话**（因此后续轮次可以保持连贯）。
+- 如果 CLI 接受图片路径，**图片也可以透传**。
 
-这被设计为一种**安全网**，而不是主要路径。当你想要“不管怎样都能工作”的文本响应，而不依赖外部 API 时，可以使用它。
+这被设计为一种 **安全兜底机制**，而不是主要路径。当你想要获得“不依赖外部 API 也始终可用”的文本响应时，可以使用它。
 
-如果你想要一个具备 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。
+如果你需要带有 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。
 
-## 对初学者友好的快速开始
+## 面向初学者的快速开始
 
-你可以**无需任何配置**使用 Codex CLI（内置的 OpenAI 插件会注册一个默认后端）：
+你可以在 **无需任何配置** 的情况下使用 Codex CLI（内置的 OpenAI 插件会注册一个默认后端）：
 
 ```bash
 openclaw agent --message "hi" --model codex-cli/gpt-5.5
 ```
 
-如果你的 Gateway 网关 运行在 `launchd`/`systemd` 下并且 `PATH` 很精简，只需添加命令路径：
+如果你的 Gateway 网关运行在 launchd/systemd 下，且 `PATH` 很精简，只需添加命令路径：
 
 ```json5
 {
@@ -49,13 +49,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
 }
 ```
 
-就是这样。除了 CLI 本身之外，不需要密钥，也不需要额外的认证配置。
+就这些。除了 CLI 本身之外，不需要密钥，也不需要额外的认证配置。
 
-如果你在 Gateway 网关 主机上将内置 CLI 后端用作**主消息提供商**，当你的配置在模型引用中或在 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。
+如果你在 Gateway 网关主机上将某个内置 CLI 后端用作 **主要消息提供商**，当你的配置在模型引用中或在 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。
 
-## 将它用作回退机制
+## 将其用作回退方案
 
-将一个 CLI 后端添加到你的回退列表中，这样它只会在主模型失败时运行：
+将 CLI 后端加入你的回退列表，这样它只会在主模型失败时运行：
 
 ```json5
 {
@@ -76,8 +76,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
 
 注意：
 
-- 如果你使用 `agents.defaults.models`（允许列表），你也必须把你的 CLI 后端模型包含进去。
-- 如果主提供商失败（认证、限流、超时），OpenClaw 将接着尝试 CLI 后端。
+- 如果你使用 `agents.defaults.models`（允许列表），你也必须把 CLI 后端模型包含进去。
+- 如果主提供商失败（认证、速率限制、超时），OpenClaw 会接着尝试 CLI 后端。
 
 ## 配置概览
 
@@ -87,8 +87,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
 agents.defaults.cliBackends
 ```
 
-每个条目都以一个**provider id** 为键（例如 `codex-cli`、`my-cli`）。
-这个 provider id 会成为你的模型引用左侧部分：
+每个条目都以一个 **provider id** 作为键（例如 `codex-cli`、`my-cli`）。
+这个 provider id 会成为模型引用左侧部分：
 
 ```
 <provider>/<model>
@@ -118,7 +118,9 @@ agents.defaults.cliBackends
           sessionMode: "existing",
           sessionIdFields: ["session_id", "conversation_id"],
           systemPromptArg: "--system",
-          // 类似 Codex 的 CLI 也可以改为指向一个提示文件：
+          // 对于带有专用 prompt-file 标志的 CLI：
+          // systemPromptFileArg: "--system-file",
+          // 类似 Codex 的 CLI 也可以改为指向一个 prompt 文件：
           // systemPromptFileConfigArg: "-c",
           // systemPromptFileConfigKey: "model_instructions_file",
           systemPromptWhen: "first",
@@ -134,27 +136,23 @@ agents.defaults.cliBackends
 
 ## 工作原理
 
-1. 根据提供商前缀（`codex-cli/...`）**选择一个后端**。
-2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。
-3. 如果支持，则使用会话 id **执行 CLI**，以便保持历史一致。
-   内置的 `claude-cli` 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活，
-   并通过 stream-json stdin 发送后续轮次。
-4. **解析输出**（JSON 或纯文本）并返回最终文本。
-5. 按后端**持久化会话 id**，以便后续轮次复用同一个 CLI 会话。
+1. 根据提供商前缀（`codex-cli/...`）**选择后端**。
+2. 使用相同的 OpenClaw prompt 和工作区上下文 **构建系统提示词**。
+3. 用会话 id（如果支持）**执行 CLI**，以便历史保持一致。  
+   内置的 `claude-cli` 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活，并通过 stream-json stdin 发送后续轮次。
+4. **解析输出**（JSON 或纯文本），并返回最终文本。
+5. 按后端 **持久化会话 id**，这样后续轮次会复用同一个 CLI 会话。
 
 <Note>
-内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，允许使用 OpenClaw 风格的 Claude CLI，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将 `claude -p` 的用法视为该集成的受认可方式。
+内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 `claude -p` 的用法视为此集成的许可方式。
 </Note>
 
-内置的 OpenAI `codex-cli` 后端会通过 Codex 的 `model_instructions_file` 配置覆盖项（`-c
-model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 不提供类似 Claude 的
-`--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装后的提示词写入临时文件。
+内置的 OpenAI `codex-cli` 后端会通过 Codex 的 `model_instructions_file` 配置覆盖项将 OpenClaw 的系统提示词传递进去（`-c
+model_instructions_file="..."`）。Codex 不提供类似 Claude 的 `--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装后的提示词写入一个临时文件。
 
-内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw Skills 快照：一种是在追加的系统提示词中包含精简版的 OpenClaw Skills 目录，另一种是通过 `--plugin-dir` 传入一个临时 Claude Code 插件。该插件仅包含对此智能体/会话符合条件的 Skills，因此 Claude Code 的原生技能解析器会看到与 OpenClaw 否则会在提示词中声明的相同过滤结果。对于运行过程，Skill 环境变量/API 密钥覆盖仍然由 OpenClaw 应用于子进程环境。
+内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw Skills 快照：一种是追加到系统提示词中的精简版 OpenClaw Skills 目录，另一种是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件仅包含对该智能体/会话符合条件的 Skills，因此 Claude Code 的原生技能解析器看到的过滤结果，与 OpenClaw 原本会在提示词中通告的一致。针对 Skill 的环境变量/API 密钥覆盖，仍然会由 OpenClaw 应用到该次运行的子进程环境中。
 
-Claude CLI 也有它自己的非交互权限模式。OpenClaw 会将其映射到现有的 exec 策略，而不是增加 Claude 专用配置：当生效的请求 exec 策略为 YOLO（`tools.exec.security: "full"` 和
-`tools.exec.ask: "off"`）时，OpenClaw 会添加 `--permission-mode bypassPermissions`。
-对于该智能体，按智能体配置的 `agents.list[].tools.exec` 会覆盖全局 `tools.exec`。如果要强制使用不同的 Claude 模式，请在 `agents.defaults.cliBackends.claude-cli.args` 和匹配的 `resumeArgs` 下设置显式原始后端参数，例如 `--permission-mode default` 或 `--permission-mode acceptEdits`。
+Claude CLI 也有自己的非交互式权限模式。OpenClaw 会把它映射到现有的执行策略，而不是增加 Claude 专用配置：当实际请求的执行策略为 YOLO（`tools.exec.security: "full"` 且 `tools.exec.ask: "off"`）时，OpenClaw 会添加 `--permission-mode bypassPermissions`。针对该智能体的 `agents.list[].tools.exec` 设置会覆盖全局 `tools.exec`。如果要强制使用不同的 Claude 模式，请在 `agents.defaults.cliBackends.claude-cli.args` 以及对应的 `resumeArgs` 下设置显式原始后端参数，例如 `--permission-mode default` 或 `--permission-mode acceptEdits`。
 
 在 OpenClaw 可以使用内置的 `claude-cli` 后端之前，Claude Code 本身必须已经在同一台主机上登录：
 
@@ -164,58 +162,52 @@ claude auth status --text
 openclaw models auth login --provider anthropic --method cli --set-default
 ```
 
-仅当 `claude` 二进制文件不在 `PATH` 中时，才使用 `agents.defaults.cliBackends.claude-cli.command`。
+只有在 `claude` 二进制文件不在 `PATH` 中时，才使用 `agents.defaults.cliBackends.claude-cli.command`。
 
 ## 会话
 
-- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或
-  `sessionArgs`（占位符 `{sessionId}`），用于需要将该 ID 插入多个标志的情况。
-- 如果 CLI 使用**恢复子命令**且标志不同，请设置
-  `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput`
-  （用于非 JSON 恢复）。
+- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或 `sessionArgs`（占位符 `{sessionId}`），用于需要将该 ID 插入多个标志的情况。
+- 如果 CLI 使用带有不同标志的 **resume 子命令**，请设置 `resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput`（用于非 JSON 的恢复输出）。
 - `sessionMode`：
-  - `always`：始终发送会话 id（如果未存储则生成新的 UUID）。
-  - `existing`：仅在之前已存储会话 id 时发送。
-  - `none`：从不发送会话 id。
-- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"`，
-  以及 `input: "stdin"`，因此只要它处于活动状态，后续轮次就会复用存活的 Claude 进程。现在 warm stdio 已是默认行为，包括省略传输字段的自定义配置也是如此。如果 Gateway 网关 重启或空闲进程退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。恢复前，已存储的会话 id 会针对现有且可读的项目转录记录进行验证，因此虚假的绑定会以 `reason=transcript-missing` 被清除，而不是在 `--resume` 下静默启动一个新的 Claude CLI 会话。
-- 已存储的 CLI 会话属于提供商拥有的连续性。隐式的每日会话重置不会切断它们；`/reset` 和显式的 `session.reset` 策略仍会切断。
+  - `always`：始终发送会话 id（如果没有已存储值，就生成一个新的 UUID）。
+  - `existing`：仅在之前存储过会话 id 时才发送。
+  - `none`：永不发送会话 id。
+- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"` 和 `input: "stdin"`，这样后续轮次在 Claude 进程仍然活跃时会复用这个实时 Claude 进程。现在 warm stdio 已是默认行为，包括那些省略了传输字段的自定义配置。如果 Gateway 网关重启，或者空闲进程退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。已存储的会话 id 会先针对一个现有且可读取的项目 transcript 进行验证，然后才会恢复，因此对于伪绑定，会以 `reason=transcript-missing` 清除，而不是在 `--resume` 下悄悄开启一个新的 Claude CLI 会话。
+- 已存储的 CLI 会话属于提供商拥有的连续性。隐式的每日会话重置不会切断它们；`/reset` 和显式的 `session.reset` 策略仍然会切断。
 
 序列化说明：
 
-- `serialize: true` 会保持同一通道中的运行按顺序执行。
-- 大多数 CLI 会在一个提供商通道上串行执行。
-- 当所选认证身份发生变化时，OpenClaw 会丢弃已存储 CLI 会话的复用，包括 auth profile id、静态 API 密钥、静态令牌，或当 CLI 暴露该信息时的 OAuth 账户身份发生变化。OAuth 访问令牌和刷新令牌的轮换不会切断已存储 CLI 会话。如果某个 CLI 不暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。
+- `serialize: true` 会让同一 lane 上的运行保持有序。
+- 大多数 CLI 会在单个 provider lane 上串行执行。
+- 当所选认证身份发生变化时，OpenClaw 会放弃复用已存储的 CLI 会话，包括 auth profile id、静态 API 密钥、静态令牌或 CLI 暴露出的 OAuth 账户身份发生变化的情况。OAuth 访问令牌和刷新令牌的轮换不会切断已存储的 CLI 会话。如果某个 CLI 不暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。
 
-## 图像（透传）
+## 图片（透传）
 
-如果你的 CLI 接受图像路径，请设置 `imageArg`：
+如果你的 CLI 接受图片路径，请设置 `imageArg`：
 
 ```json5
 imageArg: "--image",
 imageMode: "repeat"
 ```
 
-OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，这些
-路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会把文件路径追加到提示词中（路径注入），这对于那些能够从纯路径自动加载本地文件的 CLI 已经足够。
+OpenClaw 会把 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传递。如果缺少 `imageArg`，OpenClaw 会把文件路径追加到提示词中（路径注入），这对于那些能从普通路径自动加载本地文件的 CLI 来说已经足够。
 
 ## 输入 / 输出
 
 - `output: "json"`（默认）会尝试解析 JSON 并提取文本 + 会话 id。
-- 对于 Gemini CLI JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。
-- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及会话
-  标识符（如果存在）。
+- 对于 Gemini CLI 的 JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。
+- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并在存在时提取最终的智能体消息以及会话标识符。
 - `output: "text"` 会将 stdout 视为最终响应。
 
 输入模式：
 
-- `input: "arg"`（默认）会将提示词作为最后一个 CLI 参数传入。
+- `input: "arg"`（默认）会将提示词作为最后一个 CLI 参数传递。
 - `input: "stdin"` 会通过 stdin 发送提示词。
-- 如果提示词非常长，并且设置了 `maxPromptArgChars`，则会使用 stdin。
+- 如果提示词很长且设置了 `maxPromptArgChars`，则会改用 stdin。
 
 ## 默认值（由插件拥有）
 
-内置的 OpenAI 插件还会为 `codex-cli` 注册一个默认值：
+内置的 OpenAI 插件也会为 `codex-cli` 注册一个默认值：
 
 - `command: "codex"`
 - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
@@ -226,7 +218,7 @@ OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，
 - `imageArg: "--image"`
 - `sessionMode: "existing"`
 
-内置的 Google 插件还会为 `google-gemini-cli` 注册一个默认值：
+内置的 Google 插件也会为 `google-gemini-cli` 注册一个默认值：
 
 - `command: "gemini"`
 - `args: ["--output-format", "json", "--prompt", "{prompt}"]`
@@ -237,8 +229,7 @@ OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，
 - `sessionMode: "existing"`
 - `sessionIdFields: ["session_id", "sessionId"]`
 
-前提条件：本地 Gemini CLI 必须已安装，并且在 `PATH` 中可作为
-`gemini` 使用（`brew install gemini-cli` 或
+前提条件：本地 Gemini CLI 必须已安装，并且能以 `gemini` 的名称在 `PATH` 中使用（`brew install gemini-cli` 或
 `npm install -g @google/gemini-cli`）。
 
 Gemini CLI JSON 说明：
@@ -246,22 +237,21 @@ Gemini CLI JSON 说明：
 - 回复文本从 JSON 的 `response` 字段读取。
 - 当 `usage` 不存在或为空时，用量会回退到 `stats`。
 - `stats.cached` 会被标准化为 OpenClaw `cacheRead`。
-- 如果 `stats.input` 缺失，OpenClaw 会根据
+- 如果缺少 `stats.input`，OpenClaw 会根据
   `stats.input_tokens - stats.cached` 推导输入 token 数。
 
 仅在需要时覆盖（常见情况：使用绝对 `command` 路径）。
 
 ## 由插件拥有的默认值
 
-CLI 后端默认值现在是插件表面的一部分：
+CLI 后端默认值现在已成为插件表面的一部分：
 
-- 插件使用 `api.registerCliBackend(...)` 注册它们。
-- 后端的 `id` 会成为模型引用中的提供商前缀。
-- `agents.defaults.cliBackends.<id>` 中的用户配置仍会覆盖插件默认值。
-- 后端特定的配置清理由插件通过可选的
-  `normalizeConfig` 钩子继续拥有。
+- 插件通过 `api.registerCliBackend(...)` 注册它们。
+- 后端的 `id` 会成为模型引用中的 provider 前缀。
+- `agents.defaults.cliBackends.<id>` 下的用户配置仍然会覆盖插件默认值。
+- 后端特定的配置清理由插件通过可选的 `normalizeConfig` 钩子继续负责。
 
-需要极小提示词/消息兼容性垫片的插件，可以声明双向文本转换，而无需替换提供商或 CLI 后端：
+需要做轻量提示词/消息兼容性适配的插件，可以声明双向文本转换，而无需替换某个 provider 或 CLI 后端：
 
 ```typescript
 api.registerTextTransforms({
@@ -278,54 +268,47 @@ api.registerTextTransforms({
 });
 ```
 
-`input` 会重写传递给 CLI 的系统提示词和用户提示词。`output`
-会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式 assistant 增量内容和已解析的最终文本。
+`input` 会重写传递给 CLI 的系统提示词和用户提示词。`output` 会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式输出的助手增量以及解析后的最终文本。
 
 对于输出与 Claude Code stream-json 兼容的 JSONL 的 CLI，请在该后端配置上设置
 `jsonlDialect: "claude-stream-json"`。
 
-## 捆绑 MCP 覆盖层
+## 打包 MCP 覆盖层
 
-CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 来选择加入一个自动生成的 MCP 配置覆盖层。
+CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 来选择启用一个生成的 MCP 配置覆盖层。
 
-当前的内置行为：
+当前内置行为：
 
 - `claude-cli`：生成的严格 MCP 配置文件
-- `codex-cli`：针对 `mcp_servers` 的内联配置覆盖；生成的
-  OpenClaw loopback server 会标记为 Codex 的按服务器工具批准模式，
-  因此 MCP 调用不会因本地批准提示而卡住
+- `codex-cli`：为 `mcp_servers` 提供内联配置覆盖；生成的 OpenClaw loopback 服务器会标记为 Codex 的按服务器工具审批模式，因此 MCP 调用不会卡在本地审批提示上
 - `google-gemini-cli`：生成的 Gemini 系统设置文件
 
 启用 bundle MCP 后，OpenClaw 会：
 
 - 启动一个 loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程
-- 使用按会话生成的令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证
-- 将工具访问范围限定在当前会话、账户和渠道上下文内
+- 使用按会话分配的令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证
+- 将工具访问范围限制在当前会话、账户和渠道上下文内
 - 为当前工作区加载已启用的 bundle-MCP 服务器
 - 将它们与任何现有的后端 MCP 配置/设置结构合并
-- 使用所属扩展提供的后端集成模式重写启动配置
+- 使用所属扩展中由后端拥有的集成模式重写启动配置
 
-如果没有启用任何 MCP 服务器，当后端选择加入 bundle MCP 时，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。
+如果没有启用任何 MCP 服务器，只要后端选择启用 bundle MCP，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。
 
-按会话范围的内置 MCP 运行时会被缓存，以便在同一会话内复用；在空闲 `mcp.sessionIdleTtlMs` 毫秒后会被回收（默认 10 分钟；设置为 `0` 可禁用）。一次性嵌入式运行（例如认证探测、slug 生成和活动 Memory 召回）会在运行结束时请求清理，因此 stdio 子进程和 Streamable HTTP/SSE 流不会在运行结束后继续存在。
+按会话作用域的内置 MCP 运行时会被缓存，以便在同一会话内复用；在空闲 `mcp.sessionIdleTtlMs` 毫秒后会被回收（默认 10 分钟；设为 `0` 可禁用）。像认证探测、slug 生成和活动内存召回这类一次性嵌入式运行，会在运行结束时请求清理，因此 stdio 子进程和 Streamable HTTP/SSE 流不会在运行结束后继续存活。
 
 ## 限制
 
-- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用直接注入
-  CLI 后端协议。只有在后端选择加入
-  `bundleMcp: true` 时，后端才能看到 Gateway 网关工具。
-- **流式传输是后端特定的。** 有些后端会流式输出 JSONL；另一些则会缓冲
-  直到退出。
+- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用直接注入 CLI 后端协议。只有在后端选择启用 `bundleMcp: true` 时，它们才会看到 Gateway 网关工具。
+- **流式传输是后端特定的。** 有些后端会流式输出 JSONL；另一些则会缓冲到退出时才输出。
 - **结构化输出** 取决于 CLI 的 JSON 格式。
-- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），其结构化程度低于初始的 `--json` 运行。不过 OpenClaw 会话本身仍会正常工作。
+- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），其结构化程度低于初始的 `--json` 运行。但 OpenClaw 会话本身仍可正常工作。
 
 ## 故障排除
 
 - **找不到 CLI**：将 `command` 设置为完整路径。
-- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射为 CLI 模型。
-- **没有会话连续性**：确保已设置 `sessionArg`，并且 `sessionMode` 不是
-  `none`（Codex CLI 当前无法使用 JSON 输出恢复）。
-- **图像被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。
+- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
+- **没有会话连续性**：确保设置了 `sessionArg`，并且 `sessionMode` 不是 `none`（Codex CLI 目前无法使用 JSON 输出进行恢复）。
+- **图片被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。
 
 ## 相关内容
 

docs/zh-CN/gateway/config-agents.md

@@ -2,19 +2,19 @@
 read_when:
     - 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills）
     - 配置多智能体路由和绑定
-    - 调整会话、消息传递和 talk 模式行为
-summary: 智能体默认设置、多智能体路由、会话、消息和 talk 配置
+    - 调整会话、消息传递和对话模式行为
+summary: 智能体默认设置、多智能体路由、会话、消息和对话配置
 title: 配置 — 智能体
 x-i18n:
-    generated_at: "2026-04-25T10:04:03Z"
+    generated_at: "2026-04-25T12:32:52Z"
     model: gpt-5.4
     provider: openai
-    source_hash: e5b3adcd4c809595a51ffd536fc62d9f72ac16fe249b6e23ee0560bc4076eba5
+    source_hash: 1601dc5720f6a82fb947667ed9c0b4612c5187572796db5deb7a28dd13be3528
     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)。
 
 ## 智能体默认设置
 
@@ -30,7 +30,7 @@ x-i18n:
 
 ### `agents.defaults.repoRoot`
 
-可选的仓库根目录，会显示在系统提示中的 Runtime 行。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。
+可选的仓库根目录，会显示在系统提示词的 Runtime 行中。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。
 
 ```json5
 {
@@ -40,8 +40,7 @@ x-i18n:
 
 ### `agents.defaults.skills`
 
-可选的默认 Skills 允许列表，用于未设置
-`agents.list[].skills` 的智能体。
+为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。
 
 ```json5
 {
@@ -50,21 +49,20 @@ x-i18n:
     list: [
       { id: "writer" }, // 继承 github、weather
       { id: "docs", skills: ["docs-search"] }, // 替换默认值
-      { id: "locked-down", skills: [] }, // 无 Skills
+      { id: "locked-down", skills: [] }, // 不使用任何 Skills
     ],
   },
 }
 ```
 
-- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。
-- 省略 `agents.list[].skills` 以继承默认值。
-- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。
-- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它
-  不会与默认值合并。
+- 省略 `agents.defaults.skills`，则默认不限制 Skills。
+- 省略 `agents.list[].skills`，则继承默认值。
+- 将 `agents.list[].skills: []` 设置为空数组，则不使用任何 Skills。
+- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。
 
 ### `agents.defaults.skipBootstrap`
 
-禁用工作区引导文件（`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
 {
@@ -74,10 +72,10 @@ x-i18n:
 
 ### `agents.defaults.contextInjection`
 
-控制何时将工作区引导文件注入到系统提示中。默认值：`"always"`。
+控制何时将工作区引导文件注入系统提示词。默认值：`"always"`。
 
-- `"continuation-skip"`：安全的续接轮次（在助手完成响应之后）会跳过工作区引导内容的重新注入，从而减小提示体积。Heartbeat 运行和压缩后的重试仍会重建上下文。
-- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅对完全自行管理提示生命周期的智能体使用此选项（自定义上下文引擎、自行构建上下文的原生运行时，或专门的不使用引导的工作流）。Heartbeat 和压缩恢复轮次同样会跳过注入。
+- `"continuation-skip"`：在安全的续接轮次中（即助手已完成一次响应之后），会跳过重新注入工作区引导内容，从而减少提示词大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
+- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅建议对那些完全自行管理提示词生命周期的智能体使用此选项（例如自定义上下文引擎、自行构建上下文的原生运行时，或专门设计为无引导的工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。
 
 ```json5
 {
@@ -87,7 +85,7 @@ x-i18n:
 
 ### `agents.defaults.bootstrapMaxChars`
 
-单个工作区引导文件在截断前的最大字符数。默认值：`12000`。
+每个工作区引导文件在截断前允许的最大字符数。默认值：`12000`。
 
 ```json5
 {
@@ -97,7 +95,7 @@ x-i18n:
 
 ### `agents.defaults.bootstrapTotalMaxChars`
 
-所有工作区引导文件注入内容的总最大字符数。默认值：`60000`。
+所有工作区引导文件合计注入的最大总字符数。默认值：`60000`。
 
 ```json5
 {
@@ -107,11 +105,11 @@ x-i18n:
 
 ### `agents.defaults.bootstrapPromptTruncationWarning`
 
-控制当引导上下文被截断时，向智能体显示的警告文本。
+控制当引导上下文被截断时，是否向智能体可见地注入警告文本。
 默认值：`"once"`。
 
-- `"off"`：绝不向系统提示中注入警告文本。
-- `"once"`：每种唯一的截断签名仅注入一次警告（推荐）。
+- `"off"`：绝不向系统提示词中注入警告文本。
+- `"once"`：每种唯一的截断特征仅注入一次警告（推荐）。
 - `"always"`：只要存在截断，就在每次运行时都注入警告。
 
 ```json5
@@ -120,9 +118,9 @@ x-i18n:
 }
 ```
 
-### 上下文预算归属图
+### 上下文预算归属映射
 
-OpenClaw 有多个高容量的提示/上下文预算，这些预算会按子系统有意拆分，而不是全部通过一个通用开关来控制。
+OpenClaw 有多个高容量的提示词/上下文预算，它们被有意按子系统拆分，而不是全部通过一个通用开关统一控制。
 
 - `agents.defaults.bootstrapMaxChars` /
   `agents.defaults.bootstrapTotalMaxChars`：
@@ -131,9 +129,9 @@ OpenClaw 有多个高容量的提示/上下文预算，这些预算会按子系
   一次性的 `/new` 和 `/reset` 启动前导内容，包括最近的每日
   `memory/*.md` 文件。
 - `skills.limits.*`：
-  注入到系统提示中的精简 Skills 列表。
+  注入系统提示词中的紧凑 Skills 列表。
 - `agents.defaults.contextLimits.*`：
-  有界的运行时摘录和由运行时拥有的注入块。
+  有界的运行时摘录和由运行时注入的内容块。
 - `memory.qmd.limits.*`：
   已索引的 memory 搜索片段和注入大小控制。
 
@@ -144,8 +142,7 @@ OpenClaw 有多个高容量的提示/上下文预算，这些预算会按子系
 
 #### `agents.defaults.startupContext`
 
-控制在空白 `/new` 和 `/reset`
-运行时注入的首轮启动前导内容。
+控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。
 
 ```json5
 {
@@ -166,7 +163,7 @@ OpenClaw 有多个高容量的提示/上下文预算，这些预算会按子系
 
 #### `agents.defaults.contextLimits`
 
-有界运行时上下文面的共享默认值。
+为有界运行时上下文表面提供共享默认值。
 
 ```json5
 {
@@ -183,15 +180,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
 {
@@ -217,8 +213,8 @@ OpenClaw 有多个高容量的提示/上下文预算，这些预算会按子系
 
 #### `skills.limits.maxSkillsPromptChars`
 
-注入到系统提示中的精简 Skills 列表的全局上限。此项
-不会影响按需读取 `SKILL.md` 文件。
+注入系统提示词中的紧凑 Skills 列表的全局上限。
+这不会影响按需读取 `SKILL.md` 文件。
 
 ```json5
 {
@@ -232,7 +228,7 @@ OpenClaw 有多个高容量的提示/上下文预算，这些预算会按子系
 
 #### `agents.list[].skillsLimits.maxSkillsPromptChars`
 
-Skills 提示预算的按智能体覆盖项。
+针对 Skills 提示词预算的按智能体覆盖项。
 
 ```json5
 {
@@ -251,11 +247,11 @@ Skills 提示预算的按智能体覆盖项。
 
 ### `agents.defaults.imageMaxDimensionPx`
 
-在调用提供商之前，transcript/tool 图像块中图像最长边的最大像素尺寸。
+在调用提供商之前，转录内容/工具图像块中图片最长边的最大像素尺寸。
 默认值：`1200`。
 
-较低的值通常会减少视觉 token 使用量和以截图为主的运行请求负载大小。
-较高的值会保留更多视觉细节。
+对于包含大量截图的运行，较低的值通常会减少视觉 token 使用量和请求负载大小。
+较高的值则能保留更多视觉细节。
 
 ```json5
 {
@@ -265,7 +261,7 @@ Skills 提示预算的按智能体覆盖项。
 
 ### `agents.defaults.userTimezone`
 
-用于系统提示上下文的时区（不是消息时间戳）。会回退到主机时区。
+用于系统提示词上下文的时区（不影响消息时间戳）。如果未设置，则回退为主机时区。
 
 ```json5
 {
@@ -275,7 +271,7 @@ Skills 提示预算的按智能体覆盖项。
 
 ### `agents.defaults.timeFormat`
 
-系统提示中的时间格式。默认值：`auto`（操作系统偏好）。
+系统提示词中的时间格式。默认值：`auto`（操作系统偏好）。
 
 ```json5
 {
@@ -332,52 +328,52 @@ Skills 提示预算的按智能体覆盖项。
 }
 ```
 
-- `model`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
-  - 字符串形式仅设置主模型。
-  - 对象形式设置主模型以及按顺序的故障切换模型。
-- `imageModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
-  - 用作 `image` 工具路径中的视觉模型配置。
-  - 当所选/默认模型无法接受图像输入时，也用作回退路由。
-- `imageGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
-  - 用于共享的图像生成能力，以及任何未来会生成图像的工具/插件接口。
-  - 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`，用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-2`。
-  - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证（例如：`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。
+- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+  - 字符串形式只设置主模型。
+  - 对象形式会设置主模型以及按顺序排列的故障切换模型。
+- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+  - 作为 `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。
+  - 如果你直接选择某个 provider/model，也要配置匹配的提供商凭证（例如，`google/*` 需要 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 需要 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 需要 `FAL_KEY`）。
   - 如果省略，`image_generate` 仍可推断出一个基于已认证提供商的默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。
-- `musicGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
   - 用于共享的音乐生成能力和内置的 `music_generate` 工具。
-  - 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。
+  - 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。
   - 如果省略，`music_generate` 仍可推断出一个基于已认证提供商的默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。
-  - 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API 密钥。
-- `videoGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+  - 如果你直接选择某个 provider/model，也要配置匹配的提供商凭证/API 密钥。
+- `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`。
+  - 常见值：`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 密钥。
+  - 如果你直接选择某个 provider/model，也要配置匹配的提供商凭证/API 密钥。
   - 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
-- `pdfModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
+- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
   - 用于 `pdf` 工具的模型路由。
-  - 如果省略，PDF 工具会回退到 `imageModel`，再回退到已解析的会话/默认模型。
-- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
-- `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。
+  - 如果省略，PDF 工具会依次回退到 `imageModel`，再回退到已解析的会话/默认模型。
+- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具使用的默认 PDF 大小限制。
+- `pdfMaxPages`：`pdf` 工具在提取回退模式中考虑的默认最大页数。
 - `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
 - `elevatedDefault`：智能体的默认增强输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
-- `model.primary`：格式为 `provider/model`（例如，使用 API 密钥访问时可用 `openai/gpt-5.4`，使用 Codex OAuth 时可用 `openai-codex/gpt-5.5`）。如果你省略提供商，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`（例如，`openai/gpt-5.4` 用于 API 密钥访问，或 `openai-codex/gpt-5.5` 用于 Codex OAuth）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是暴露一个陈旧且已移除提供商的默认值。
+- `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)。
 - `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 中设置（例如 `{ cacheRetention: "long" }`）。
-- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 id）按键覆盖。详见 [提示缓存](/zh-CN/reference/prompt-caching)。
-- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果与生成的请求键冲突，则额外请求体优先；非原生 completions 路由之后仍会剥离仅限 OpenAI 的 `store`。
-- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。省略 `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`；通过运行时配置选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧式运行时提供商前缀。关于它与 provider/model 选择的区别，参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
+- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 和回退模型的添加/删除命令）会保存为规范的对象形式，并尽可能保留现有的回退列表。
+- `maxConcurrent`：跨会话并行运行的最大智能体数量（每个会话本身仍然是串行的）。默认值：`4`。
 
 ### `agents.defaults.embeddedHarness`
 
-`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。
-大多数部署应保持默认的 OpenClaw Pi 运行时。
-当可信插件提供原生 harness 时，可以使用此项，例如内置的
+`embeddedHarness` 控制由哪个底层执行器来运行嵌入式智能体轮次。
+大多数部署应保留默认的 OpenClaw Pi 运行时。
+当受信任的插件提供原生 harness 时可使用它，例如内置的
 Codex 应用服务器 harness。关于其心智模型，请参见
 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
 
@@ -395,14 +391,14 @@ Codex 应用服务器 harness。关于其心智模型，请参见
 }
 ```
 
-- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册为 `codex`。
-- `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 固定。配置/环境变量变更会影响新会话或已重置的会话，不会影响现有 transcript。具有 transcript 历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会报告生效的运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
-- 此项只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。
+- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册的是 `codex`。
+- `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 仍使用各自的 provider/model 设置。
 
-**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时适用）：
+**内置别名简写**（仅当模型存在于 `agents.defaults.models` 中时生效）：
 
 | 别名                | 模型                                               |
 | ------------------- | -------------------------------------------------- |
@@ -418,12 +414,12 @@ Codex 应用服务器 harness。关于其心智模型，请参见
 你配置的别名始终优先于默认值。
 
 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 模型默认启用 `tool_stream` 以支持工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设为 `false` 可禁用它。
+当未设置显式思考级别时，Anthropic Claude 4.6 模型默认使用 `adaptive` 思考模式。
 
 ### `agents.defaults.cliBackends`
 
-用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备用方案。
+用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时，它可作为备份使用。
 
 ```json5
 {
@@ -441,6 +437,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
           sessionArg: "--session",
           sessionMode: "existing",
           systemPromptArg: "--system",
+          // 或者当 CLI 接受提示词文件参数时，使用 systemPromptFileArg。
           systemPromptWhen: "first",
           imageArg: "--image",
           imageMode: "repeat",
@@ -451,13 +448,13 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 }
 ```
 
-- CLI 后端以文本为主；工具始终禁用。
-- 设置了 `sessionArg` 时支持会话。
+- CLI 后端以文本为主；工具始终被禁用。
+- 当设置了 `sessionArg` 时，支持会话。
 - 当 `imageArg` 接受文件路径时，支持图像透传。
 
 ### `agents.defaults.systemPromptOverride`
 
-用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控的提示实验。
+用固定字符串替换整个由 OpenClaw 组装的系统提示词。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅包含空白字符的值会被忽略。适合用于受控的提示词实验。
 
 ```json5
 {
@@ -471,7 +468,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 
 ### `agents.defaults.promptOverlays`
 
-按模型家族应用的、与提供商无关的提示覆盖层。GPT-5 家族模型 id 会在不同提供商之间接收共享的行为契约；`personality` 仅控制友好的交互风格层。
+按模型家族应用的、与提供商无关的提示词叠加层。GPT-5 系列模型 id 会在不同提供商之间接收共享的行为契约；`personality` 仅控制友好的交互风格层。
 
 ```json5
 {
@@ -488,12 +485,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 ```
 
 - `"friendly"`（默认）和 `"on"` 会启用友好的交互风格层。
-- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍保持启用。
-- 当这个共享设置未设置时，仍会读取旧版的 `plugins.entries.openai.config.personality`。
+- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍然启用。
+- 当这个共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。
 
 ### `agents.defaults.heartbeat`
 
-周期性 Heartbeat 运行。
+定期 Heartbeat 运行。
 
 ```json5
 {
@@ -503,13 +500,13 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
         every: "30m", // 0m 表示禁用
         model: "openai/gpt-5.4-mini",
         includeReasoning: false,
-        includeSystemPromptSection: true, // 默认：true；false 会省略系统提示中的 Heartbeat 部分
-        lightContext: false, // 默认：false；true 仅保留工作区引导文件中的 HEARTBEAT.md
-        isolatedSession: false, // 默认：false；true 会让每次 heartbeat 都在全新会话中运行（无对话历史）
+        includeSystemPromptSection: true, // 默认：true；false 会从系统提示词中省略 Heartbeat 部分
+        lightContext: false, // 默认：false；true 只保留工作区引导文件中的 HEARTBEAT.md
+        isolatedSession: false, // 默认：false；true 会让每次 heartbeat 在一个全新会话中运行（无对话历史）
         session: "main",
         to: "+15555550123",
         directPolicy: "allow", // allow（默认）| block
-        target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ...
+        target: "none", // 默认：none | 可选值：last | whatsapp | telegram | discord | ...
         prompt: "Read HEARTBEAT.md if it exists...",
         ackMaxChars: 300,
         suppressToolErrorWarnings: false,
@@ -521,14 +518,14 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 ```
 
 - `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `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 越多。
+- `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。
+- 按智能体设置：使用 `agents.list[].heartbeat`。当任一智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 heartbeat。
+- Heartbeat 会运行完整的智能体轮次——更短的间隔会消耗更多 token。
 
 ### `agents.defaults.compaction`
 
@@ -538,7 +535,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
     defaults: {
       compaction: {
         mode: "safeguard", // default | safeguard
-        provider: "my-provider", // 已注册 compaction 提供商插件的 id（可选）
+        provider: "my-provider", // 已注册的 compaction 提供商插件 id（可选）
         timeoutSeconds: 900,
         reserveTokensFloor: 24000,
         keepRecentTokens: 50000,
@@ -547,7 +544,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
         qualityGuard: { enabled: true, maxRetries: 1 },
         postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入
         model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖
-        notifyUser: true, // 在 compaction 开始和完成时发送简短通知（默认：false）
+        notifyUser: true, // 在 compaction 开始和完成时发送简短通知给用户（默认：false）
         memoryFlush: {
           enabled: true,
           softThresholdTokens: 6000,
@@ -560,21 +557,21 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 }
 ```
 
-- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
-- `provider`：已注册 compaction 提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
-- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。
-- `keepRecentTokens`：Pi 截断点预算，用于按原样保留最近的 transcript 尾部。手动 `/compact` 在显式设置时会遵循此值；否则手动 compaction 是一个硬检查点。
-- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预先添加内置的、不透明标识符保留指导。
-- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。
-- `qualityGuard`：对 safeguard 摘要进行输出格式异常时重试的检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。
-- `postCompactionSections`：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 前的静默智能体轮次，用于存储持久 memory。当工作区为只读时会跳过。
+- `mode`：`default` 或 `safeguard`（对长历史进行分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
+- `provider`：已注册的 compaction 提供商插件 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置的 LLM 摘要。在失败时会回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
+- `timeoutSeconds`：OpenClaw 在中止前允许单次 compaction 操作运行的最长秒数。默认值：`900`。
+- `keepRecentTokens`：Pi 切分点预算，用于逐字保留最近的转录尾部。手动 `/compact` 在显式设置时会遵循该值；否则，手动 compaction 是一个硬检查点。
+- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要前附加内置的不透明标识符保留指引。
+- `identifierInstructions`：可选的自定义标识符保留文本，在 `identifierPolicy=custom` 时使用。
+- `qualityGuard`：针对 safeguard 摘要的输出格式错误重试检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。
+- `postCompactionSections`：compaction 后重新注入的可选 `AGENTS.md` H2/H3 章节名。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置或显式设置为该默认组合时，较旧的 `Every Session`/`Safety` 标题也会作为旧版回退被接受。
+- `model`：可选的仅用于 compaction 摘要的 `provider/model-id` 覆盖项。当主会话应继续使用一个模型，而 compaction 摘要应改由另一个模型运行时，请使用此项；未设置时，compaction 使用会话的主模型。
+- `notifyUser`：为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如，“Compacting context...” 和 “Compaction complete”）。默认禁用，以保持 compaction 静默。
+- `memoryFlush`：在自动 compaction 之前执行的静默智能体轮次，用于存储持久记忆。工作区为只读时会跳过。
 
 ### `agents.defaults.contextPruning`
 
-在将内容发送给 LLM 之前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。
+在发送给 LLM 之前，从内存上下文中裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。
 
 ```json5
 {
@@ -596,25 +593,25 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 }
 ```
 
-<Accordion title="`cache-ttl` 模式行为">
+<Accordion title="cache-ttl 模式行为">
 
-- `mode: "cache-ttl"` 会启用修剪流程。
-- `ttl` 控制何时可再次运行修剪（在上次缓存触碰之后）。
-- 修剪会先对过大的工具结果进行软修剪，如仍有需要，再对更旧的工具结果执行硬清除。
+- `mode: "cache-ttl"` 会启用裁剪流程。
+- `ttl` 控制距离上次缓存触碰后，多久才能再次运行裁剪。
+- 裁剪会先对过大的工具结果执行软裁剪，如仍有需要，再对更旧的工具结果执行硬清除。
 
-**软修剪**会保留开头和结尾，并在中间插入 `...`。
+**软裁剪** 会保留开头和结尾，并在中间插入 `...`。
 
-**硬清除**会用占位符替换整个工具结果。
+**硬清除** 会用占位文本替换整个工具结果。
 
 注意：
 
-- 图像块永远不会被修剪/清除。
-- 比例是基于字符的（近似值），不是精确 token 计数。
-- 如果助手消息少于 `keepLastAssistants` 条，则会跳过修剪。
+- 图像块永远不会被裁剪/清除。
+- 比例按字符计算（近似值），不是精确 token 数。
+- 如果助手消息少于 `keepLastAssistants` 条，则会跳过裁剪。
 
 </Accordion>
 
-行为细节请参见 [会话修剪](/zh-CN/concepts/session-pruning)。
+行为细节参见 [会话裁剪](/zh-CN/concepts/session-pruning)。
 
 ### 分块流式传输
 
@@ -633,12 +630,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 ```
 
 - 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。
-- 渠道覆盖项：`channels.<channel>.blockStreamingCoalesce`（以及按账户的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
-- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。
+- 渠道覆盖：`channels.<channel>.blockStreamingCoalesce`（以及按账号变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
+- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500ms。按智能体覆盖：`agents.list[].humanDelay`。
 
-行为和分块细节请参见 [流式传输](/zh-CN/concepts/streaming)。
+行为和分块细节参见 [流式传输](/zh-CN/concepts/streaming)。
 
-### 输入中指示器
+### 正在输入指示器
 
 ```json5
 {
@@ -651,16 +648,16 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 }
 ```
 
-- 默认值：直接聊天/提及时为 `instant`，未被提及的群聊中为 `message`。
+- 默认值：直接聊天/提及时使用 `instant`，未提及的群聊使用 `message`。
 - 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
 
-参见 [输入中指示器](/zh-CN/concepts/typing-indicators)。
+参见 [正在输入指示器](/zh-CN/concepts/typing-indicators)。
 
 <a id="agentsdefaultssandbox"></a>
 
 ### `agents.defaults.sandbox`
 
-嵌入式智能体的可选沙箱隔离。完整指南请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
+嵌入式智能体的可选沙箱隔离。完整指南参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
 
 ```json5
 {
@@ -760,7 +757,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 **后端：**
 
 - `docker`：本地 Docker 运行时（默认）
-- `ssh`：基于通用 SSH 的远程运行时
+- `ssh`：通用 SSH 支持的远程运行时
 - `openshell`：OpenShell 运行时
 
 当选择 `backend: "openshell"` 时，运行时特定设置会移动到
@@ -772,7 +769,7 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 - `command`：SSH 客户端命令（默认：`ssh`）
 - `workspaceRoot`：用于按作用域工作区的远程绝对根目录
 - `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
-- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其写入临时文件
+- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其实体化为临时文件
 - `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
 
 **SSH 认证优先级：**
@@ -780,12 +777,12 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 - `identityData` 优先于 `identityFile`
 - `certificateData` 优先于 `certificateFile`
 - `knownHostsData` 优先于 `knownHostsFile`
-- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前，从当前启用的 secrets 运行时快照中解析
+- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前，从当前激活的 secrets 运行时快照中解析
 
 **SSH 后端行为：**
 
-- 在创建或重新创建后，先进行一次远程工作区初始化
-- 然后保持远程 SSH 工作区为规范工作区
+- 在创建或重建后为远程工作区执行一次初始化填充
+- 随后保持远程 SSH 工作区为规范工作区
 - 通过 SSH 路由 `exec`、文件工具和媒体路径
 - 不会自动将远程更改同步回主机
 - 不支持沙箱浏览器容器
@@ -830,29 +827,29 @@ Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `ada
 
 **OpenShell 模式：**
 
-- `mirror`：在执行前将本地内容初始化到远程，执行后再同步回本地；本地工作区保持为规范工作区
-- `remote`：在创建沙箱时仅将本地内容初始化到远程一次，之后保持远程工作区为规范工作区
+- `mirror`：在执行前将本地内容同步到远程，在执行后再同步回来；本地工作区保持为规范工作区
+- `remote`：在创建沙箱时只向远程初始化一次，之后保持远程工作区为规范工作区
 
-在 `remote` 模式下，在 OpenClaw 外部于主机本地进行的编辑，在初始化步骤之后不会自动同步到沙箱中。
-传输层通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。
+在 `remote` 模式下，在 OpenClaw 外部对主机本地所做的编辑，在初始化步骤之后不会自动同步到沙箱中。
+传输方式是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。
 
-**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。
+**`setupCommand`** 会在容器创建后执行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。
 
-**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。
-`"host"` 会被阻止。默认也会阻止 `"container:<id>"`，除非你显式设置
-`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗操作）。
+**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"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 网络）。只有在你明确需要全局 bridge 连通性时，才设置为 `bridge`。
-- `cdpSourceRange` 可选地将容器边界处的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。
-- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
+- `network` 默认为 `openclaw-sandbox-browser`（专用桥接网络）。只有在你明确希望使用全局桥接连接时，才设置为 `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>`
@@ -874,13 +871,13 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有
   - `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
     默认启用；如果 WebGL/3D 使用场景需要，可通过
     `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些默认标志。
-  - 如果你的工作流依赖扩展，可通过
+  - 如果你的工作流依赖扩展，可使用
     `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。
   - `--renderer-process-limit=2` 可通过
-    `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 修改；设置为 `0` 可使用 Chromium 的默认进程限制。
-  - 此外，当启用 `noSandbox` 时还会添加 `--no-sandbox`。
-  - 这些默认值是容器镜像基线；若要更改容器默认值，请使用带有自定义
-    入口点的自定义浏览器镜像。
+    `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 更改；设置为 `0` 则使用 Chromium 的
+    默认进程上限。
+  - 当启用 `noSandbox` 时，还会附加 `--no-sandbox`。
+  - 这些默认值是容器镜像基线；如果要更改容器默认值，请使用带有自定义入口点的自定义浏览器镜像。
 
 </Accordion>
 
@@ -890,7 +887,7 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有
 
 ```bash
 scripts/sandbox-setup.sh           # 主沙箱镜像
-scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
+scripts/sandbox-browser-setup.sh   # 可选浏览器镜像
 ```
 
 ### `agents.list`（按智能体覆盖）
@@ -910,7 +907,7 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
         reasoningDefault: "on", // 按智能体覆盖推理可见性
         fastModeDefault: false, // 按智能体覆盖快速模式
         embeddedHarness: { runtime: "auto", fallback: "pi" },
-        params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params
+        params: { cacheRetention: "none" }, // 按键覆盖匹配 defaults.models 的 params
         skills: ["docs-search"], // 设置后会替换 agents.defaults.skills
         identity: {
           name: "Samantha",
@@ -943,20 +940,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`）。
+- `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）。
+- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。
+- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅相同智能体）。
+- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些会在无沙箱环境下运行的目标。
+- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认：false）。
 
 ---
 
@@ -981,14 +978,14 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 
 ### 绑定匹配字段
 
-- `type`（可选）：普通路由用 `route`（缺失时默认即为 route），持久 ACP 对话绑定用 `acp`。
+- `type`（可选）：普通路由使用 `route`（缺失时默认为 route），持久 ACP 对话绑定使用 `acp`。
 - `match.channel`（必填）
-- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户）
+- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号）
 - `match.peer`（可选；`{ kind: direct|group|channel, id }`）
 - `match.guildId` / `match.teamId`（可选；特定于渠道）
-- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
+- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
 
-**确定性的匹配顺序：**
+**确定性匹配顺序：**
 
 1. `match.peer`
 2. `match.guildId`
@@ -997,9 +994,9 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 5. `match.accountId: "*"`（整个渠道范围）
 6. 默认智能体
 
-在每一层级内，第一个匹配的 `bindings` 条目获胜。
+在每一层级中，第一个匹配的 `bindings` 条目获胜。
 
-对于 `type: "acp"` 条目，OpenClaw 会按精确的对话身份（`match.channel` + account + `match.peer.id`）进行解析，不使用上述 route 绑定层级顺序。
+对于 `type: "acp"` 条目，OpenClaw 会按精确对话身份（`match.channel` + account + `match.peer.id`）解析，不使用上述 route 绑定层级顺序。
 
 ### 按智能体访问配置
 
@@ -1050,7 +1047,7 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 
 </Accordion>
 
-<Accordion title="无文件系统访问（仅消息传递）">
+<Accordion title="无文件系统访问（仅消息）">
 
 ```json5
 {
@@ -1096,7 +1093,7 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 
 </Accordion>
 
-有关优先级细节，请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。
+优先级细节请参见 [多智能体沙箱隔离与工具](/zh-CN/tools/multi-agent-sandbox-tools)。
 
 ---
 
@@ -1122,7 +1119,7 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
     },
     resetTriggers: ["/new", "/reset"],
     store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
-    parentForkMaxTokens: 100000, // 父线程 token 数超过此值时跳过父线程 fork（0 表示禁用）
+    parentForkMaxTokens: 100000, // 超过该 token 数时跳过父线程分叉（0 表示禁用）
     maintenance: {
       mode: "warn", // warn | enforce
       pruneAfter: "30d",
@@ -1137,7 +1134,7 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
       idleHours: 24, // 默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用）
       maxAgeHours: 0, // 默认按小时计算的硬性最大时长（`0` 表示禁用）
     },
-    mainKey: "main", // 旧字段（运行时始终使用 "main"）
+    mainKey: "main", // 旧版字段（运行时始终使用 "main"）
     agentToAgent: { maxPingPongTurns: 5 },
     sendPolicy: {
       rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
@@ -1150,32 +1147,32 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 <Accordion title="会话字段详情">
 
 - **`scope`**：群聊上下文的基础会话分组策略。
-  - `per-sender`（默认）：在一个渠道上下文内，每个发送者都有隔离的会话。
-  - `global`：一个渠道上下文中的所有参与者共享同一个会话（仅在明确需要共享上下文时使用）。
-- **`dmScope`**：私信的分组方式。
+  - `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`**：创建 fork 出来的线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。
-  - 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父 transcript 历史。
-  - 设置为 `0` 可禁用此保护，并始终允许从父会话 fork。
-- **`mainKey`**：旧字段。运行时始终对主直接聊天桶使用 `"main"`。
-- **`agentToAgent.maxPingPongTurns`**：在智能体到智能体交互期间，智能体之间允许的最大来回回复轮次（整数，范围：`0`–`5`）。`0` 表示禁用乒乓式链式回复。
-- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 仍可作为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 优先。
+  - `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。
+- **`identityLinks`**：将规范 id 映射到带提供商前缀的对端，用于跨渠道共享会话。
+- **`reset`**：主要重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 的空闲后重置。当两者都已配置时，以先到期者为准。
+- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍可作为 `direct` 的别名使用。
+- **`parentForkMaxTokens`**：创建分叉线程会话时，允许父会话的最大 `totalTokens`（默认 `100000`）。
+  - 如果父会话的 `totalTokens` 超过此值，OpenClaw 会启动一个全新的线程会话，而不是继承父转录历史。
+  - 设置为 `0` 可禁用此保护，并始终允许从父会话分叉。
+- **`mainKey`**：旧版字段。运行时始终对主私聊桶使用 `"main"`。
+- **`agentToAgent.maxPingPongTurns`**：在智能体到智能体交换期间，智能体之间允许的最大来回回复轮次（整数，范围：`0`–`5`）。`0` 会禁用这种来回链式交互。
+- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，其中旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则优先。
 - **`maintenance`**：会话存储清理 + 保留控制。
-  - `mode`：`warn` 仅发出警告；`enforce` 会执行清理。
-  - `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。
-  - `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。
-  - `rotateBytes`：当 `sessions.json` 超过此大小时进行轮转（默认 `10mb`）。
-  - `resetArchiveRetention`：`*.reset.<timestamp>` transcript 归档的保留时长。默认与 `pruneAfter` 相同；设置为 `false` 可禁用。
-  - `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的产物/会话。
+  - `mode`：`warn` 仅发出警告；`enforce` 会实际执行清理。
+  - `pruneAfter`：陈旧条目的年龄截止值（默认 `30d`）。
+  - `maxEntries`：`sessions.json` 中允许的最大条目数（默认 `500`）。
+  - `rotateBytes`：当 `sessions.json` 超过该大小时进行轮换（默认 `10mb`）。
+  - `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留期。默认等于 `pruneAfter`；设置为 `false` 可禁用。
+  - `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的工件/会话。
   - `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。
 - **`threadBindings`**：线程绑定会话功能的全局默认值。
-  - `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
+  - `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
   - `idleHours`：默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖）
   - `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；提供商可覆盖）
 
@@ -1215,15 +1212,15 @@ 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` |
+| `{model}` | 简短模型名称 | `claude-opus-4-6` |
 | `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
 | `{provider}` | 提供商名称 | `anthropic` |
 | `{thinkingLevel}` | 当前思考级别 | `high`、`low`、`off` |
@@ -1233,18 +1230,18 @@ scripts/sandbox-browser-setup.sh   # 可选的浏览器镜像
 
 ### 确认反应
 
-- 默认为当前活动智能体的 `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 上会在回复后移除确认反应。
+- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上回复后移除确认反应。
 - `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。
-  在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则状态反应保持启用。
-  在 Telegram 上，需显式设置为 `true` 才会启用生命周期状态反应。
+  在 Slack 和 Discord 上，未设置时只要确认反应处于激活状态，就会保持启用状态反应。
+  在 Telegram 上，必须显式设为 `true` 才会启用生命周期状态反应。
 
-### 入站防抖
+### 入站去抖
 
-将来自同一发送者的快速纯文本消息批量合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
+将来自同一发送者的快速连续纯文本消息合并为一个智能体轮次。媒体/附件会立即触发发送。控制命令会绕过去抖。
 
 ### TTS（文本转语音）
 
@@ -1294,19 +1291,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`（需显式开启）。
+- `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`。
+- 内置语音提供商由插件拥有。如果设置了 `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 服务器，并放宽模型/语音校验。
 
 ---
 
-## Talk
+## 对话
 
-Talk 模式（macOS/iOS/Android）的默认设置。
+对话模式的默认值（macOS/iOS/Android）。
 
 ```json5
 {
@@ -1334,20 +1331,20 @@ Talk 模式（macOS/iOS/Android）的默认设置。
 }
 ```
 
-- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。
-- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅为兼容保留，会自动迁移到 `talk.providers.<provider>` 中。
+- 当配置了多个对话提供商时，`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`。
 - `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
-- 仅当未配置 Talk API 密钥时，才会使用 `ELEVENLABS_API_KEY` 回退。
-- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。
-- `providers.mlx.modelId` 选择 macOS 本地 MLX helper 使用的 Hugging Face 仓库。若省略，macOS 使用 `mlx-community/Soprano-80M-bf16`。
-- macOS 上的 MLX 播放会通过内置的 `openclaw-mlx-tts` helper 运行；若其不存在，则使用 `PATH` 上的可执行文件；开发时可通过 `OPENCLAW_MLX_TTS_BIN` 覆盖 helper 路径。
-- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间再发送 transcript。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
+- 只有在未配置 Talk API 密钥时，才会应用 `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 运行；如果该 helper 不存在，则使用 `PATH` 上的可执行文件；开发时可用 `OPENCLAW_MLX_TTS_BIN` 覆盖 helper 路径。
+- `silenceTimeoutMs` 控制对话模式在用户静音后等待多久才发送转录内容。未设置时会保留平台默认暂停窗口（`macOS 和 Android 上为 700 ms，iOS 上为 900 ms`）。
 
 ---
 
 ## 相关内容
 
-- [配置参考](/zh-CN/gateway/configuration-reference) —— 其他所有配置键
-- [配置](/zh-CN/gateway/configuration) —— 常见任务和快速设置
+- [配置参考](/zh-CN/gateway/configuration-reference) — 所有其他配置键
+- [配置](/zh-CN/gateway/configuration) — 常见任务和快速设置
 - [配置示例](/zh-CN/gateway/configuration-examples)