chore(i18n): refresh zh-CN translations

2026-04-24 06:25:17 +00:00 · 2026-04-24 06:25:17 +00:00 · baad75c42b
commit baad75c42b
parent ce0429a4cc
2 changed files with 188 additions and 156 deletions
--- a/docs/zh-CN/channels/nextcloud-talk.md
+++ b/docs/zh-CN/channels/nextcloud-talk.md
@ -1,13 +1,13 @@
 ---
 read_when:
-    - 处理 Nextcloud Talk 渠道功能
-summary: Nextcloud Talk 支持状态、能力和配置
+    - 正在开发 Nextcloud Talk 渠道功能
+summary: Nextcloud Talk 支持状态、功能和配置
 title: Nextcloud Talk
 x-i18n:
-    generated_at: "2026-04-23T20:41:39Z"
+    generated_at: "2026-04-24T06:24:02Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 2eebd6cfd013d3a6e1cf03e2a2167d0657e688c5989f179bb0fec39f866586cb
+    source_hash: 9a3af391ffa445ef1ebc7877a1158c3c6aa7ecc71ceadcb0e783a80b040fe062
    source_path: channels/nextcloud-talk.md
    workflow: 15
 ---
@ -16,11 +16,11 @@ x-i18n:

 ## 内置插件

-Nextcloud Talk 在当前 OpenClaw 版本中作为内置插件提供，因此普通的打包构建无需单独安装。
+Nextcloud Talk 在当前的 OpenClaw 版本中作为内置插件提供，因此普通的打包构建不需要单独安装。

-如果你使用的是较旧版本，或排除了 Nextcloud Talk 的自定义安装，则需要手动安装：
+如果你使用的是较旧的构建版本，或排除了 Nextcloud Talk 的自定义安装，请手动安装：

-通过 CLI 安装（npm registry）：
+通过 CLI 安装（npm 注册表）：

 ```bash
 openclaw plugins install @openclaw/nextcloud-talk
@ -32,14 +32,14 @@ openclaw plugins install @openclaw/nextcloud-talk
 openclaw plugins install ./path/to/local/nextcloud-talk-plugin
 ```

-详情请参阅：[插件](/zh-CN/tools/plugin)
+详情：[插件](/zh-CN/tools/plugin)

 ## 快速设置（初学者）

 1. 确保 Nextcloud Talk 插件可用。
-   - 当前打包的 OpenClaw 版本已内置该插件。
-   - 较旧版本或自定义安装可使用上述命令手动添加。
-2. 在你的 Nextcloud 服务器上创建一个机器人：
+   - 当前打包发布的 OpenClaw 版本已默认内置它。
+   - 较旧/自定义安装可使用上面的命令手动添加。
+2. 在你的 Nextcloud 服务器上，创建一个机器人：

   ```bash
   ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction
@ -49,6 +49,31 @@ openclaw plugins install ./path/to/local/nextcloud-talk-plugin
 4. 配置 OpenClaw：
   - 配置：`channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
   - 或环境变量：`NEXTCLOUD_TALK_BOT_SECRET`（仅默认账户）
+
+   CLI 设置：
+
+   ```bash
+   openclaw channels add --channel nextcloud-talk \
+     --url https://cloud.example.com \
+     --token "<shared-secret>"
+   ```
+
+   等效的显式字段：
+
+   ```bash
+   openclaw channels add --channel nextcloud-talk \
+     --base-url https://cloud.example.com \
+     --secret "<shared-secret>"
+   ```
+
+   基于文件的 secret：
+
+   ```bash
+   openclaw channels add --channel nextcloud-talk \
+     --base-url https://cloud.example.com \
+     --secret-file /path/to/nextcloud-talk-secret
+   ```
+
 5. 重启 Gateway 网关（或完成设置）。

 最小配置：
@ -69,23 +94,23 @@ openclaw plugins install ./path/to/local/nextcloud-talk-plugin
 ## 注意事项

 - 机器人无法主动发起私信。用户必须先给机器人发送消息。
- webhook URL 必须可被 Gateway 网关访问；如果位于代理后方，请设置 `webhookPublicUrl`。
- 机器人 API 不支持媒体上传；媒体将以 URL 形式发送。
- webhook 载荷无法区分私信与房间；设置 `apiUser` + `apiPassword` 可启用房间类型查询（否则私信会被视为房间）。
+- webhook URL 必须可被 Gateway 网关访问；如果位于代理之后，请设置 `webhookPublicUrl`。
+- 机器人 API 不支持媒体上传；媒体会以 URL 形式发送。
+- webhook 负载不会区分私信和房间；设置 `apiUser` + `apiPassword` 可启用房间类型查询（否则私信会被视为房间）。

 ## 访问控制（私信）

 - 默认：`channels.nextcloud-talk.dmPolicy = "pairing"`。未知发送者会收到一个配对码。
- 通过以下命令批准：
+- 通过以下方式批准：
  - `openclaw pairing list nextcloud-talk`
  - `openclaw pairing approve nextcloud-talk <CODE>`
- 公开私信：设置 `channels.nextcloud-talk.dmPolicy="open"`，并同时设置 `channels.nextcloud-talk.allowFrom=["*"]`。
+- 公开私信：`channels.nextcloud-talk.dmPolicy="open"` 加上 `channels.nextcloud-talk.allowFrom=["*"]`。
 - `allowFrom` 仅匹配 Nextcloud 用户 ID；显示名称会被忽略。

 ## 房间（群组）

- 默认：`channels.nextcloud-talk.groupPolicy = "allowlist"`（受提及门控）。
- 使用 `channels.nextcloud-talk.rooms` 将房间加入 allowlist：
+- 默认：`channels.nextcloud-talk.groupPolicy = "allowlist"`（提及门控）。
+- 使用 `channels.nextcloud-talk.rooms` 将房间加入允许列表：

 ```json5
 {
@ -99,7 +124,7 @@ openclaw plugins install ./path/to/local/nextcloud-talk-plugin
 }
 ```

- 若不允许任何房间，请保持 allowlist 为空，或设置 `channels.nextcloud-talk.groupPolicy="disabled"`。
+- 若不允许任何房间，可保持允许列表为空，或设置 `channels.nextcloud-talk.groupPolicy="disabled"`。

 ## 功能

@ -114,39 +139,39 @@ openclaw plugins install ./path/to/local/nextcloud-talk-plugin

 ## 配置参考（Nextcloud Talk）

-完整配置请参阅：[配置](/zh-CN/gateway/configuration)
+完整配置：[配置](/zh-CN/gateway/configuration)

 提供商选项：

 - `channels.nextcloud-talk.enabled`：启用/禁用渠道启动。
 - `channels.nextcloud-talk.baseUrl`：Nextcloud 实例 URL。
- `channels.nextcloud-talk.botSecret`：机器人共享密钥。
- `channels.nextcloud-talk.botSecretFile`：常规文件密钥路径。不接受符号链接。
+- `channels.nextcloud-talk.botSecret`：机器人共享 secret。
+- `channels.nextcloud-talk.botSecretFile`：常规文件 secret 路径。不接受符号链接。
 - `channels.nextcloud-talk.apiUser`：用于房间查询的 API 用户（私信检测）。
- `channels.nextcloud-talk.apiPassword`：用于房间查询的 API/应用密码。
+- `channels.nextcloud-talk.apiPassword`：用于房间查询的 API 密码/应用密码。
 - `channels.nextcloud-talk.apiPasswordFile`：API 密码文件路径。
 - `channels.nextcloud-talk.webhookPort`：webhook 监听端口（默认：8788）。
 - `channels.nextcloud-talk.webhookHost`：webhook 主机（默认：0.0.0.0）。
 - `channels.nextcloud-talk.webhookPath`：webhook 路径（默认：/nextcloud-talk-webhook）。
 - `channels.nextcloud-talk.webhookPublicUrl`：外部可访问的 webhook URL。
 - `channels.nextcloud-talk.dmPolicy`：`pairing | allowlist | open | disabled`。
- `channels.nextcloud-talk.allowFrom`：私信 allowlist（用户 ID）。`open` 需要 `"*"`。
+- `channels.nextcloud-talk.allowFrom`：私信允许列表（用户 ID）。`open` 需要 `"*"`。
 - `channels.nextcloud-talk.groupPolicy`：`allowlist | open | disabled`。
- `channels.nextcloud-talk.groupAllowFrom`：群组 allowlist（用户 ID）。
- `channels.nextcloud-talk.rooms`：按房间设置的配置和 allowlist。
- `channels.nextcloud-talk.historyLimit`：群组历史记录上限（0 表示禁用）。
- `channels.nextcloud-talk.dmHistoryLimit`：私信历史记录上限（0 表示禁用）。
- `channels.nextcloud-talk.dms`：按私信的覆盖配置（`historyLimit`）。
+- `channels.nextcloud-talk.groupAllowFrom`：群组允许列表（用户 ID）。
+- `channels.nextcloud-talk.rooms`：按房间配置的设置和允许列表。
+- `channels.nextcloud-talk.historyLimit`：群组历史记录限制（0 表示禁用）。
+- `channels.nextcloud-talk.dmHistoryLimit`：私信历史记录限制（0 表示禁用）。
+- `channels.nextcloud-talk.dms`：按私信配置的覆盖项（`historyLimit`）。
 - `channels.nextcloud-talk.textChunkLimit`：出站文本分块大小（字符数）。
- `channels.nextcloud-talk.chunkMode`：`length`（默认），或 `newline`，表示先按空行（段落边界）拆分，再按长度分块。
+- `channels.nextcloud-talk.chunkMode`：`length`（默认）或 `newline`，用于在按长度分块前先按空行（段落边界）拆分。
 - `channels.nextcloud-talk.blockStreaming`：为此渠道禁用分块流式传输。
- `channels.nextcloud-talk.blockStreamingCoalesce`：分块流式传输聚合调优。
- `channels.nextcloud-talk.mediaMaxMb`：入站媒体大小上限（MB）。
+- `channels.nextcloud-talk.blockStreamingCoalesce`：分块流式传输合并调优。
+- `channels.nextcloud-talk.mediaMaxMb`：入站媒体上限（MB）。

 ## 相关内容

- [渠道概览](/zh-CN/channels) — 所有支持的渠道
+- [渠道概览](/zh-CN/channels) — 所有受支持的渠道
 - [配对](/zh-CN/channels/pairing) — 私信认证和配对流程
- [群组](/zh-CN/channels/groups) — 群聊行为与提及门控
+- [群组](/zh-CN/channels/groups) — 群聊行为和提及门控
 - [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由
- [安全](/zh-CN/gateway/security) — 访问模型与加固
+- [安全](/zh-CN/gateway/security) — 访问模型和加固措施
--- a/docs/zh-CN/channels/whatsapp.md
+++ b/docs/zh-CN/channels/whatsapp.md
@ -1,29 +1,29 @@
 ---
 read_when:
-    - 处理 WhatsApp/web 渠道行为或收件箱路由
-summary: WhatsApp 渠道支持、访问控制、投递行为与运维操作
+    - 处理 WhatsApp/web 渠道行为或收件箱路由问题
+summary: WhatsApp 渠道支持、访问控制、投递行为和运维
 title: WhatsApp
 x-i18n:
-    generated_at: "2026-04-24T03:37:52Z"
+    generated_at: "2026-04-24T06:24:01Z"
    model: gpt-5.4
    provider: openai
-    source_hash: 0261e132d459c91f5d81d5ad9485acbdf5792e6bfc8cd33bb74e45192df9fd2f
+    source_hash: 51305dbf83109edb64d07bcafd5fe738ff97e3d2c779adfaef2e8406d1d93caf
    source_path: channels/whatsapp.md
    workflow: 15
 ---

-状态：通过 WhatsApp Web（Baileys）达到生产就绪。Gateway 网关管理已关联的会话。
+状态：已可在生产环境中通过 WhatsApp Web（Baileys）使用。Gateway 网关负责已链接的会话。

 ## 安装（按需）

 - 新手引导（`openclaw onboard`）和 `openclaw channels add --channel whatsapp`
-  会在你首次选择 WhatsApp 插件时提示安装。
+  会在你首次选择 WhatsApp 插件时提示安装它。
 - `openclaw channels login --channel whatsapp` 也会在
  插件尚未安装时提供安装流程。
 - 开发渠道 + git checkout：默认使用本地插件路径。
- Stable/Beta：默认使用 npm 包 `@openclaw/whatsapp`。
+- 稳定版 / Beta：默认使用 npm 包 `@openclaw/whatsapp`。

-你仍然可以手动安装：
+仍然可以手动安装：

 ```bash
 openclaw plugins install @openclaw/whatsapp
@ -34,7 +34,7 @@ openclaw plugins install @openclaw/whatsapp
    未知发送者的默认私信策略是配对。
  </Card>
  <Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
-    跨渠道诊断与修复手册。
+    跨渠道诊断与修复操作手册。
  </Card>
  <Card title="Gateway 网关配置" icon="settings" href="/zh-CN/gateway/configuration">
    完整的渠道配置模式与示例。
@ -61,7 +61,7 @@ openclaw plugins install @openclaw/whatsapp

  </Step>

-  <Step title="关联 WhatsApp（QR 码）">
+  <Step title="链接 WhatsApp（QR 码）">

 ```bash
 openclaw channels login --channel whatsapp
@ -71,6 +71,13 @@ openclaw channels login --channel whatsapp

 ```bash
 openclaw channels login --channel whatsapp --account work
+```
+
+    要在登录前挂载现有 / 自定义的 WhatsApp Web 认证目录：
+
+```bash
+openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
+openclaw channels login --channel whatsapp --account work
 ```

  </Step>
@ -83,7 +90,7 @@ openclaw gateway

  </Step>

-  <Step title="批准首次配对请求（如果使用配对模式）">
+  <Step title="批准第一个配对请求（如果使用配对模式）">

 ```bash
 openclaw pairing list whatsapp
@ -96,7 +103,7 @@ openclaw pairing approve whatsapp <CODE>
 </Steps>

 <Note>
-OpenClaw 建议尽可能为 WhatsApp 使用独立号码。（渠道元数据和设置流程已针对这种设置进行了优化，但也支持个人号码设置。）
+OpenClaw 建议在可能的情况下为 WhatsApp 使用单独的号码。（渠道元数据和设置流程已针对这种设置进行优化，但也支持个人号码设置。）
 </Note>

 ## 部署模式
@ -106,7 +113,7 @@ OpenClaw 建议尽可能为 WhatsApp 使用独立号码。（渠道元数据和
    这是最清晰的运维模式：

    - 为 OpenClaw 使用独立的 WhatsApp 身份
-    - 更清晰的私信允许列表和路由边界
+    - 更清晰的私信允许名单和路由边界
    - 更低的自聊混淆概率

    最小策略模式：
@ -131,7 +138,7 @@ OpenClaw 建议尽可能为 WhatsApp 使用独立号码。（渠道元数据和
    - `allowFrom` 包含你的个人号码
    - `selfChatMode: true`

-    在运行时，自聊保护会基于已关联的自身号码和 `allowFrom` 生效。
+    在运行时，自聊保护基于已链接的自身号码和 `allowFrom` 生效。

  </Accordion>

@ -145,54 +152,54 @@ OpenClaw 建议尽可能为 WhatsApp 使用独立号码。（渠道元数据和

 ## 运行时模型

- Gateway 网关管理 WhatsApp socket 和重连循环。
- 出站发送要求目标账户存在活跃的 WhatsApp 监听器。
+- Gateway 网关负责 WhatsApp socket 和重连循环。
+- 出站发送要求目标账户存在一个活动的 WhatsApp 监听器。
 - 状态和广播聊天会被忽略（`@status`、`@broadcast`）。
- 私聊使用私信会话规则（`session.dmScope`；默认 `main` 会将私信合并到智能体主会话）。
+- 直接聊天使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话）。
 - 群组会话彼此隔离（`agent:<agentId>:whatsapp:group:<jid>`）。
- WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` 及其小写变体）。优先使用主机级代理配置，而不是 WhatsApp 渠道专用代理设置。
+- WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` 及其小写变体）。优先使用主机级代理配置，而不是渠道专用的 WhatsApp 代理设置。

-## 访问控制与激活
+## 访问控制和激活

 <Tabs>
  <Tab title="私信策略">
-    `channels.whatsapp.dmPolicy` 控制私聊访问：
+    `channels.whatsapp.dmPolicy` 控制直接聊天访问：

    - `pairing`（默认）
    - `allowlist`
    - `open`（要求 `allowFrom` 包含 `"*"`）
    - `disabled`

-    `allowFrom` 接受 E.164 风格的号码（内部会进行规范化）。
+    `allowFrom` 接受 E.164 风格的号码（内部会进行标准化）。

-    多账户覆盖：对于该账户，`channels.whatsapp.accounts.<id>.dmPolicy`（以及 `allowFrom`）优先于渠道级默认值。
+    多账户覆盖：`channels.whatsapp.accounts.<id>.dmPolicy`（以及 `allowFrom`）会优先于该账户的渠道级默认值。

    运行时行为细节：

    - 配对会持久化到渠道允许存储中，并与已配置的 `allowFrom` 合并
-    - 如果未配置允许列表，则默认允许已关联的自身号码
-    - OpenClaw 永远不会自动配对出站的 `fromMe` 私信（即你从已关联设备发送给自己的消息）
+    - 如果未配置允许名单，则默认允许已链接的自身号码
+    - OpenClaw 永远不会自动配对出站的 `fromMe` 私信（即你从已链接设备发送给自己的消息）

  </Tab>

-  <Tab title="群组策略 + 允许列表">
-    群组访问分为两层：
+  <Tab title="群组策略 + 允许名单">
+    群组访问有两层：

-    1. **群组成员资格允许列表**（`channels.whatsapp.groups`）
+    1. **群组成员资格允许名单**（`channels.whatsapp.groups`）
       - 如果省略 `groups`，则所有群组都有资格
-       - 如果存在 `groups`，它会充当群组允许列表（允许使用 `"*"`）
+       - 如果存在 `groups`，它将作为群组允许名单使用（允许 `"*"`）

    2. **群组发送者策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`）
-       - `open`：绕过发送者允许列表
+       - `open`：绕过发送者允许名单
       - `allowlist`：发送者必须匹配 `groupAllowFrom`（或 `*`）
       - `disabled`：阻止所有群组入站消息

-    发送者允许列表回退：
+    发送者允许名单回退：

-    - 如果未设置 `groupAllowFrom`，运行时会在 `allowFrom` 可用时回退到它
-    - 在提及/回复激活之前，会先评估发送者允许列表
+    - 如果未设置 `groupAllowFrom`，运行时会在可用时回退到 `allowFrom`
+    - 发送者允许名单会在提及 / 回复激活之前进行评估

-    注意：如果根本不存在 `channels.whatsapp` 配置块，运行时群组策略回退值为 `allowlist`（并记录警告），即使设置了 `channels.defaults.groupPolicy` 也是如此。
+    注意：如果根本不存在 `channels.whatsapp` 配置块，运行时群组策略回退值为 `allowlist`（并带有警告日志），即使已设置 `channels.defaults.groupPolicy` 也是如此。

  </Tab>

@ -202,39 +209,39 @@ OpenClaw 建议尽可能为 WhatsApp 使用独立号码。（渠道元数据和
    提及检测包括：

    - 对机器人身份的显式 WhatsApp 提及
-    - 已配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`）
-    - 隐式回复机器人检测（回复发送者与机器人身份匹配）
+    - 已配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
+    - 隐式回复给机器人检测（回复发送者与机器人身份匹配）

    安全说明：

-    - 引用/回复只会满足提及门控；它**不会**授予发送者授权
-    - 当 `groupPolicy: "allowlist"` 时，即使非允许列表发送者回复了允许列表用户的消息，仍然会被阻止
+    - 引用 / 回复只会满足提及门控；它**不会**授予发送者授权
+    - 在 `groupPolicy: "allowlist"` 下，即使非允许名单发送者回复了允许名单用户的消息，仍会被阻止

    会话级激活命令：

    - `/activation mention`
    - `/activation always`

-    `activation` 会更新会话状态（而不是全局配置）。它受 owner 权限控制。
+    `activation` 会更新会话状态（而非全局配置）。它受所有者门控。

  </Tab>
 </Tabs>

-## 个人号码与自聊行为
+## 个人号码和自聊行为

-当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会激活：
+当已链接的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护机制会启用：

 - 跳过自聊轮次的已读回执
- 忽略原本会提醒你自己的 mention-JID 自动触发行为
+- 忽略本会触发提醒你自己的 mention-JID 自动触发行为
 - 如果未设置 `messages.responsePrefix`，自聊回复默认使用 `[{identity.name}]` 或 `[openclaw]`

-## 消息规范化与上下文
+## 消息标准化和上下文

 <AccordionGroup>
-  <Accordion title="入站信封 + 回复上下文">
-    传入的 WhatsApp 消息会封装到共享的入站信封中。
+  <Accordion title="入站封装 + 回复上下文">
+    传入的 WhatsApp 消息会被包装到共享的入站封装中。

-    如果存在引用回复，会附加以下形式的上下文：
+    如果存在引用回复，上下文会按以下形式附加：

    ```text
    [Replying to <sender> id:<stanzaId>]
@ -242,12 +249,12 @@ OpenClaw 建议尽可能为 WhatsApp 使用独立号码。（渠道元数据和
    [/Replying]
    ```

-    如果可用，也会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。
+    回复元数据字段也会在可用时填充（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。

  </Accordion>

-  <Accordion title="媒体占位符与位置/联系人提取">
-    纯媒体入站消息会使用以下占位符进行规范化：
+  <Accordion title="媒体占位符和位置 / 联系人提取">
+    仅包含媒体的入站消息会使用如下占位符进行标准化：

    - `<media:image>`
    - `<media:video>`
@ -255,14 +262,14 @@ OpenClaw 建议尽可能为 WhatsApp 使用独立号码。（渠道元数据和
    - `<media:document>`
    - `<media:sticker>`

-    位置消息正文会使用简洁的坐标文本。位置标签/备注以及联系人/vCard 详情会渲染为带围栏的不受信任元数据，而不是内联提示文本。
+    位置正文使用简洁的坐标文本。位置标签 / 注释以及联系人 / vCard 详情会呈现为带围栏的非受信元数据，而不是内联提示文本。

  </Accordion>

  <Accordion title="待处理群组历史注入">
-    对于群组，当机器人最终被触发时，未处理消息可以被缓冲并作为上下文注入。
+    对于群组，未处理消息可以先缓冲，待机器人最终被触发时作为上下文注入。

-    - 默认上限：`50`
+    - 默认限制：`50`
    - 配置：`channels.whatsapp.historyLimit`
    - 回退：`messages.groupChat.historyLimit`
    - `0` 表示禁用
@ -310,43 +317,43 @@ OpenClaw 建议尽可能为 WhatsApp 使用独立号码。（渠道元数据和
  </Accordion>
 </AccordionGroup>

-## 投递、分块与媒体
+## 投递、分块和媒体

 <AccordionGroup>
  <Accordion title="文本分块">
    - 默认分块限制：`channels.whatsapp.textChunkLimit = 4000`
    - `channels.whatsapp.chunkMode = "length" | "newline"`
-    - `newline` 模式优先按段落边界（空行）拆分，然后回退到按长度安全分块
+    - `newline` 模式优先按段落边界（空行）分块，然后再回退到按长度安全分块
  </Accordion>

  <Accordion title="出站媒体行为">
-    - 支持图片、视频、音频（PTT 语音便笺）和文档负载
-    - `audio/ogg` 会被改写为 `audio/ogg; codecs=opus` 以兼容语音便笺
-    - 视频发送时通过 `gifPlayback: true` 支持动态 GIF 播放
-    - 发送多媒体回复负载时，说明文字会应用到第一个媒体项
+    - 支持图片、视频、音频（PTT 语音便签）和文档负载
+    - `audio/ogg` 会被改写为 `audio/ogg; codecs=opus` 以兼容语音便签
+    - 通过在视频发送时设置 `gifPlayback: true` 支持动画 GIF 播放
+    - 发送多媒体回复负载时，标题说明会应用到第一个媒体项
    - 媒体来源可以是 HTTP(S)、`file://` 或本地路径
  </Accordion>

-  <Accordion title="媒体大小限制与回退行为">
+  <Accordion title="媒体大小限制和回退行为">
    - 入站媒体保存上限：`channels.whatsapp.mediaMaxMb`（默认 `50`）
    - 出站媒体发送上限：`channels.whatsapp.mediaMaxMb`（默认 `50`）
    - 按账户覆盖使用 `channels.whatsapp.accounts.<accountId>.mediaMaxMb`
-    - 图片会自动优化（调整尺寸/质量扫描）以适应限制
-    - 当媒体发送失败时，首项回退会发送文本警告，而不是静默丢弃响应
+    - 图片会自动优化（尺寸调整 / 质量扫描）以适应限制
+    - 媒体发送失败时，首项回退会发送文本警告，而不是静默丢弃响应
  </Accordion>
 </AccordionGroup>

 ## 回复引用

-WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消息。可通过 `channels.whatsapp.replyToMode` 进行控制。
+WhatsApp 支持原生回复引用，即出站回复会以可见方式引用入站消息。使用 `channels.whatsapp.replyToMode` 控制它。

-| 值       | 行为 |
-| -------- | ---- |
-| `"auto"` | 当提供商支持时引用入站消息；否则跳过引用 |
-| `"on"`   | 始终引用入站消息；如果引用被拒绝，则回退为普通发送 |
-| `"off"`  | 从不引用；作为普通消息发送 |
+| 值       | 行为                                                                                |
+| -------- | ----------------------------------------------------------------------------------- |
+| `"auto"` | 当提供商支持时引用入站消息；否则跳过引用                                             |
+| `"on"`   | 始终引用入站消息；如果引用被拒绝，则回退为普通发送                                   |
+| `"off"`  | 从不引用；作为普通消息发送                                                           |

-默认值是 `"auto"`。按账户覆盖使用 `channels.whatsapp.accounts.<id>.replyToMode`。
+默认值为 `"auto"`。按账户覆盖使用 `channels.whatsapp.accounts.<id>.replyToMode`。

 ```json5
 {
@ -360,14 +367,14 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消

 ## 反应级别

-`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用表情反应的广度：
+`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用 emoji 反应的广泛程度：

-| 级别          | 确认反应 | 智能体主动反应 | 描述 |
-| ------------- | -------- | -------------- | ---- |
-| `"off"`       | 否       | 否             | 完全不使用反应 |
-| `"ack"`       | 是       | 否             | 仅确认反应（回复前回执） |
-| `"minimal"`   | 是       | 是（保守）     | 确认 + 在保守指导下使用智能体反应 |
-| `"extensive"` | 是       | 是（鼓励）     | 确认 + 在鼓励指导下使用智能体反应 |
+| 级别          | 确认反应 | 智能体主动反应 | 说明                              |
+| ------------- | -------- | -------------- | --------------------------------- |
+| `"off"`       | 否       | 否             | 完全不使用反应                    |
+| `"ack"`       | 是       | 否             | 仅确认反应（回复前回执）          |
+| `"minimal"`   | 是       | 是（保守）     | 确认反应 + 带保守引导的智能体反应 |
+| `"extensive"` | 是       | 是（鼓励）     | 确认反应 + 带鼓励引导的智能体反应 |

 默认值：`"minimal"`。

@ -385,7 +392,7 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消

 ## 确认反应

-WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送确认反应。
+WhatsApp 支持在收到入站消息时通过 `channels.whatsapp.ackReaction` 立即发送确认反应。
 确认反应受 `reactionLevel` 控制——当 `reactionLevel` 为 `"off"` 时会被抑制。

 ```json5
@ -404,47 +411,47 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时

 行为说明：

- 在接受入站消息后立即发送（在回复之前）
- 失败会被记录日志，但不会阻止正常回复投递
- 群组模式 `mentions` 会在由提及触发的轮次中发送反应；群组激活 `always` 可绕过此检查
- WhatsApp 使用 `channels.whatsapp.ackReaction`（这里不使用旧版 `messages.ackReaction`）
+- 在接受入站消息后立即发送（回复前）
+- 失败会被记录日志，但不会阻塞正常回复投递
+- 群组模式 `mentions` 会在由提及触发的轮次发送反应；群组激活 `always` 可绕过此检查
+- WhatsApp 使用 `channels.whatsapp.ackReaction`（此处不使用旧版 `messages.ackReaction`）

-## 多账户与凭证
+## 多账户和凭证

 <AccordionGroup>
-  <Accordion title="账户选择与默认值">
+  <Accordion title="账户选择和默认值">
    - 账户 id 来自 `channels.whatsapp.accounts`
    - 默认账户选择：如果存在则为 `default`，否则为第一个已配置的账户 id（按排序）
-    - 账户 id 会在内部规范化后用于查找
+    - 账户 id 会在内部标准化后用于查找
  </Accordion>

-  <Accordion title="凭证路径与旧版兼容性">
+  <Accordion title="凭证路径和旧版兼容性">
    - 当前认证路径：`~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
    - 备份文件：`creds.json.bak`
-    - 对于默认账户流程，仍会识别/迁移位于 `~/.openclaw/credentials/` 中的旧版默认认证
+    - `~/.openclaw/credentials/` 中的旧版默认认证仍可识别 / 迁移，用于默认账户流程
  </Accordion>

  <Accordion title="登出行为">
-    `openclaw channels logout --channel whatsapp [--account <id>]` 会清除该账户的 WhatsApp 认证状态。
+    `openclaw channels logout --channel whatsapp [--account <id>]` 会清除此账户的 WhatsApp 认证状态。

    在旧版认证目录中，会保留 `oauth.json`，同时移除 Baileys 认证文件。

  </Accordion>
 </AccordionGroup>

-## 工具、动作与配置写入
+## 工具、操作和配置写入

- 智能体工具支持包括 WhatsApp 反应动作（`react`）。
- 动作门控：
+- 智能体工具支持包括 WhatsApp 反应操作（`react`）。
+- 操作门控：
  - `channels.whatsapp.actions.reactions`
  - `channels.whatsapp.actions.polls`
- 默认启用由渠道发起的配置写入（可通过 `channels.whatsapp.configWrites=false` 禁用）。
+- 默认启用渠道发起的配置写入（可通过 `channels.whatsapp.configWrites=false` 禁用）。

 ## 故障排除

 <AccordionGroup>
-  <Accordion title="未关联（需要 QR 码）">
-    症状：渠道状态报告为未关联。
+  <Accordion title="未链接（需要 QR 码）">
+    症状：渠道状态显示未链接。

    修复：

@ -455,8 +462,8 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时

  </Accordion>

-  <Accordion title="已关联但断开 / 重连循环">
-    症状：已关联账户反复断开或反复尝试重连。
+  <Accordion title="已链接但断开 / 重连循环">
+    症状：账户已链接，但反复断开或重复尝试重连。

    修复：

@ -465,14 +472,14 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时
    openclaw logs --follow
    ```

-    如有需要，使用 `channels login` 重新关联。
+    如有需要，使用 `channels login` 重新链接。

  </Accordion>

-  <Accordion title="发送时没有活跃监听器">
-    当目标账户不存在活跃的 Gateway 网关监听器时，出站发送会快速失败。
+  <Accordion title="发送时没有活动监听器">
+    当目标账户不存在活动的 Gateway 网关监听器时，出站发送会快速失败。

-    请确保 Gateway 网关正在运行，并且账户已关联。
+    请确保 Gateway 网关正在运行，且该账户已链接。

  </Accordion>

@ -481,7 +488,7 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时

    - `groupPolicy`
    - `groupAllowFrom` / `allowFrom`
-    - `groups` 允许列表条目
+    - `groups` 允许名单条目
    - 提及门控（`requireMention` + 提及模式）
    - `openclaw.json`（JSON5）中的重复键：后面的条目会覆盖前面的条目，因此每个作用域只保留一个 `groupPolicy`

@ -494,32 +501,32 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时

 ## 系统提示词

-WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 的群组和私聊系统提示词。
+WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 风格的群组和直接聊天系统提示词。

 群组消息的解析层级：

-首先确定生效的 `groups` 映射：如果账户定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。随后会在得到的这个单一映射上执行提示词查找：
+首先确定生效的 `groups` 映射：如果账户定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。随后提示词查找会在得到的单一映射上执行：

 1. **群组特定系统提示词**（`groups["<groupId>"].systemPrompt`）：如果特定群组条目定义了 `systemPrompt`，则使用它。
 2. **群组通配系统提示词**（`groups["*"].systemPrompt`）：当特定群组条目不存在或未定义 `systemPrompt` 时使用。

-私聊消息的解析层级：
+直接消息的解析层级：

-首先确定生效的 `direct` 映射：如果账户定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。随后会在得到的这个单一映射上执行提示词查找：
+首先确定生效的 `direct` 映射：如果账户定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。随后提示词查找会在得到的单一映射上执行：

-1. **私聊特定系统提示词**（`direct["<peerId>"].systemPrompt`）：如果特定对端条目定义了 `systemPrompt`，则使用它。
-2. **私聊通配系统提示词**（`direct["*"].systemPrompt`）：当特定对端条目不存在或未定义 `systemPrompt` 时使用。
+1. **直接聊天特定系统提示词**（`direct["<peerId>"].systemPrompt`）：如果特定对端条目定义了 `systemPrompt`，则使用它。
+2. **直接聊天通配系统提示词**（`direct["*"].systemPrompt`）：当特定对端条目不存在或未定义 `systemPrompt` 时使用。

-注意：`dms` 仍然是轻量级的按私信历史覆盖桶（`dms.<id>.historyLimit`）；提示词覆盖位于 `direct` 下。
+注意：`dms` 仍然是轻量级的逐私信历史覆盖桶（`dms.<id>.historyLimit`）；提示词覆盖位于 `direct` 下。

-**与 Telegram 多账户行为的区别：** 在 Telegram 中，多账户设置下会有意对所有账户抑制根级 `groups`——即使某些账户没有定义自己的 `groups` 也是如此——以防止机器人接收其未加入群组的消息。WhatsApp 不应用这种保护：对于未定义账户级覆盖的账户，无论配置了多少账户，根级 `groups` 和根级 `direct` 都始终会被继承。在多账户 WhatsApp 设置中，如果你希望按账户设置群组或私聊提示词，请在每个账户下显式定义完整映射，而不要依赖根级默认值。
+**与 Telegram 多账户行为的区别：** 在 Telegram 中，在多账户设置下，根级 `groups` 会被有意抑制——即使某些账户没有定义自己的 `groups` 也是如此——以防止某个机器人接收它并不属于的群组消息。WhatsApp 不应用这一保护：无论配置了多少账户，未定义账户级覆盖的账户始终会继承根级 `groups` 和根级 `direct`。在多账户 WhatsApp 设置中，如果你想要按账户区分群组或直接聊天提示词，请在每个账户下显式定义完整映射，而不要依赖根级默认值。

 重要行为：

- `channels.whatsapp.groups` 同时是按群组的配置映射和聊天级群组允许列表。在根级或账户级作用域下，`groups["*"]` 表示该作用域“允许所有群组进入”。
- 只有在你本来就希望该作用域允许所有群组时，才添加通配群组 `systemPrompt`。如果你仍然只希望固定的一组群组 id 有资格进入，请不要把 `groups["*"]` 用作提示词默认值。应当改为在每个显式加入允许列表的群组条目上重复该提示词。
- 群组准入和发送者授权是两个独立检查。`groups["*"]` 会扩大可进入群组处理流程的群组集合，但它本身不会授权这些群组中的所有发送者。发送者访问仍然由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。
- `channels.whatsapp.direct` 对私信没有同样的副作用。`direct["*"]` 只会在某条私信已经通过 `dmPolicy` 加上 `allowFrom` 或配对存储规则准入后，提供默认的私聊配置。
+- `channels.whatsapp.groups` 既是逐群组配置映射，也是聊天级群组允许名单。在根级或账户级作用域中，`groups["*"]` 表示该作用域“允许所有群组”。
+- 只有在你本来就希望该作用域允许所有群组时，才添加通配群组 `systemPrompt`。如果你仍然只希望固定的一组群组 id 有资格使用，请不要将 `groups["*"]` 用作提示词默认值。相反，应在每个显式列入允许名单的群组条目上重复该提示词。
+- 群组准入和发送者授权是分开的检查。`groups["*"]` 会扩大可进入群组处理流程的群组集合，但它本身并不会授权这些群组中的每个发送者。发送者访问仍然单独由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 控制。
+- `channels.whatsapp.direct` 对私信没有同样的副作用。`direct["*"]` 只会在私信已通过 `dmPolicy` 加上 `allowFrom` 或配对存储规则获准后，提供默认的直接聊天配置。

 示例：

@ -528,31 +535,31 @@ WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 的群组和
  channels: {
    whatsapp: {
      groups: {
-        // 仅在根级作用域下应允许所有群组时使用。
+        // 仅当根级作用域应允许所有群组时使用。
        // 适用于所有未定义自己 groups 映射的账户。
-        "*": { systemPrompt: "所有群组的默认提示词。" },
+        "*": { systemPrompt: "适用于所有群组的默认提示词。" },
      },
      direct: {
        // 适用于所有未定义自己 direct 映射的账户。
-        "*": { systemPrompt: "所有私聊的默认提示词。" },
+        "*": { systemPrompt: "适用于所有直接聊天的默认提示词。" },
      },
      accounts: {
        work: {
          groups: {
-            // 该账户定义了自己的 groups，因此根级 groups 会被完全
+            // 此账户定义了自己的 groups，因此根级 groups 会被完全
            // 替换。若要保留通配符，也需要在这里显式定义 "*"。
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "专注于项目管理。",
            },
-            // 仅在该账户中应允许所有群组时使用。
-            "*": { systemPrompt: "工作群组的默认提示词。" },
+            // 仅当此账户中应允许所有群组时使用。
+            "*": { systemPrompt: "适用于工作群组的默认提示词。" },
          },
          direct: {
-            // 该账户定义了自己的 direct 映射，因此根级 direct 条目会被
+            // 此账户定义了自己的 direct 映射，因此根级 direct 条目会被
            // 完全替换。若要保留通配符，也需要在这里显式定义 "*"。
-            "+15551234567": { systemPrompt: "特定工作私聊的提示词。" },
-            "*": { systemPrompt: "工作私聊的默认提示词。" },
+            "+15551234567": { systemPrompt: "适用于特定工作直接聊天的提示词。" },
+            "*": { systemPrompt: "适用于工作直接聊天的默认提示词。" },
          },
        },
      },
@ -569,10 +576,10 @@ WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 的群组和

 高信号 WhatsApp 字段：

- 访问控制：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`
+- 访问：`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`groups`
 - 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`sendReadReceipts`、`ackReaction`、`reactionLevel`
 - 多账户：`accounts.<id>.enabled`、`accounts.<id>.authDir`、账户级覆盖
- 运维操作：`configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*`
+- 运维：`configWrites`、`debounceMs`、`web.enabled`、`web.heartbeatSeconds`、`web.reconnect.*`
 - 会话行为：`session.dmScope`、`historyLimit`、`dmHistoryLimit`、`dms.<id>.historyLimit`
 - 提示词：`groups.<id>.systemPrompt`、`groups["*"].systemPrompt`、`direct.<id>.systemPrompt`、`direct["*"].systemPrompt`