chore(i18n): refresh zh-CN translations

2026-04-23 17:20:45 +00:00 · 2026-04-23 17:20:45 +00:00 · ca25863a28
commit ca25863a28
parent 19b9d70ce9
2 changed files with 204 additions and 205 deletions
--- a/docs/zh-CN/channels/groups.md
+++ b/docs/zh-CN/channels/groups.md
@ -1,104 +1,104 @@
 ---
 read_when:
    - 更改群聊行为或提及门控
-summary: 跨平台群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo）
+summary: 跨不同界面上的群聊行为（Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo）
 title: 群组
 x-i18n:
-    generated_at: "2026-04-21T23:42:09Z"
+    generated_at: "2026-04-23T17:19:18Z"
    model: gpt-5.4
    provider: openai
-    source_hash: a86e202c7e990e040eb092aaef46bc856ee8d39b2e5fe1c733e24f1b35faa824
+    source_hash: 17f61407e916114e75b43ed781c43d9291b9ea5758ae4a7cd27407a0c994d375
    source_path: channels/groups.md
    workflow: 15
 ---

 # 群组

-OpenClaw 在不同平台上的群聊处理方式保持一致：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
+OpenClaw 在不同界面上的群聊处理方式保持一致：Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。

-## 新手简介（2 分钟）
+## 新手介绍（2 分钟）

-OpenClaw “运行”在你自己的消息账号上。不存在单独的 WhatsApp 机器人用户。
-如果**你**在某个群组里，OpenClaw 就能看到该群组并在其中回复。
+OpenClaw “运行”在你自己的消息账号上。没有单独的 WhatsApp 机器人用户。
+如果**你**在某个群组中，OpenClaw 就可以看到该群组并在那里回复。

 默认行为：

- 群组是受限的（`groupPolicy: "allowlist"`）。
- 回复需要提及，除非你明确关闭提及门控。
+- 群组默认受限（`groupPolicy: "allowlist"`）。
+- 回复需要提及，除非你显式禁用提及门控。

-也就是说：在允许名单中的发送者可以通过提及 OpenClaw 来触发它。
+也就是说：在允许列表中的发送者可以通过提及 OpenClaw 来触发它。

 > TL;DR
 >
 > - **私信访问**由 `*.allowFrom` 控制。
-> - **群组访问**由 `*.groupPolicy` + 允许名单（`*.groups`、`*.groupAllowFrom`）控制。
-> - **回复触发**由提及门控控制（`requireMention`、`/activation`）。
+> - **群组访问**由 `*.groupPolicy` + 允许列表（`*.groups`、`*.groupAllowFrom`）控制。
+> - **回复触发**由提及门控（`requireMention`、`/activation`）控制。

-快速流程（群消息会发生什么）：
+快速流程（群组消息的处理过程）：

 ```
-groupPolicy? disabled -> 丢弃
-groupPolicy? allowlist -> 群组允许？否 -> 丢弃
-requireMention? yes -> 被提及？否 -> 仅存储为上下文
-otherwise -> 回复
+groupPolicy? disabled -> drop
+groupPolicy? allowlist -> group allowed? no -> drop
+requireMention? yes -> mentioned? no -> store for context only
+otherwise -> reply
 ```

-## 上下文可见性与允许名单
+## 上下文可见性与允许列表

-群组安全涉及两种不同的控制：
+群组安全涉及两种不同的控制方式：

- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定允许名单）。
+- **触发授权**：谁可以触发智能体（`groupPolicy`、`groups`、`groupAllowFrom`、渠道特定的允许列表）。
 - **上下文可见性**：哪些补充上下文会注入到模型中（回复文本、引用、线程历史、转发元数据）。

-默认情况下，OpenClaw 优先保证正常聊天行为，并尽可能保留接收到的上下文原貌。这意味着允许名单主要决定谁可以触发操作，而不是为每一段引用或历史内容提供统一的脱敏边界。
+默认情况下，OpenClaw 优先保证正常的聊天行为，并尽量保留消息接收时的原始上下文。这意味着，允许列表主要决定谁可以触发操作，而不是对每一段引用或历史片段都进行通用脱敏的边界。

 当前行为因渠道而异：

- 某些渠道已经在特定路径中对补充上下文应用了基于发送者的过滤（例如 Slack 线程预填充、Matrix 回复/线程查询）。
- 其他渠道仍会按接收原样传递引用/回复/转发上下文。
+- 某些渠道已经在特定路径中对补充上下文应用了基于发送者的过滤（例如 Slack 线程初始化、Matrix 回复 / 线程查询）。
+- 其他渠道仍会按接收时原样传递引用 / 回复 / 转发上下文。

 加固方向（计划中）：

- `contextVisibility: "all"`（默认）保持当前按接收原样的行为。
- `contextVisibility: "allowlist"` 将补充上下文过滤为仅来自允许名单发送者。
- `contextVisibility: "allowlist_quote"` 是 `allowlist`，并额外允许一个明确的引用/回复例外。
+- `contextVisibility: "all"`（默认）保持当前按接收时原样处理的行为。
+- `contextVisibility: "allowlist"` 将补充上下文过滤为仅来自允许列表发送者。
+- `contextVisibility: "allowlist_quote"` 在 `allowlist` 基础上额外允许一个显式的引用 / 回复例外。

-在这一加固模型在各渠道中得到一致实现之前，请预期不同平台之间会有差异。
+在这一加固模型尚未在各渠道中一致实现之前，请预期不同界面之间会存在差异。

-![群消息流程](/images/groups-flow.svg)
+![群组消息流程](/images/groups-flow.svg)

 如果你想要……

-| 目标 | 需要设置什么 |
+| 目标 | 需要设置的内容 |
 | -------------------------------------------- | ---------------------------------------------------------- |
-| 允许所有群组，但只在 @提及时回复 | `groups: { "*": { requireMention: true } }` |
-| 禁用所有群组回复 | `groupPolicy: "disabled"` |
-| 仅允许特定群组 | `groups: { "<group-id>": { ... } }`（没有 `"*"` 键） |
-| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` |
+| 允许所有群组，但仅在 `@mentions` 时回复 | `groups: { "*": { requireMention: true } }`                |
+| 禁用所有群组回复 | `groupPolicy: "disabled"`                                  |
+| 仅允许特定群组 | `groups: { "<group-id>": { ... } }`（不使用 `"*"` 键）         |
+| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`，`groupAllowFrom: ["+1555..."]` |

 ## 会话键

- 群组会话使用 `agent:<agentId>:<channel>:group:<id>` 会话键（房间/频道使用 `agent:<agentId>:<channel>:channel:<id>`）。
- Telegram 论坛主题会在群组 id 后追加 `:topic:<threadId>`，因此每个主题都有自己的会话。
- 直接聊天使用主会话（或按配置为每个发送者单独分配）。
+- 群组会话使用 `agent:<agentId>:<channel>:group:<id>` 会话键（房间 / 渠道使用 `agent:<agentId>:<channel>:channel:<id>`）。
+- Telegram 论坛话题会在群组 id 后附加 `:topic:<threadId>`，因此每个话题都有自己的会话。
+- 私聊使用主会话（如果已配置，也可以按发送者分别使用）。
 - 群组会话会跳过心跳。

 <a id="pattern-personal-dms-public-groups-single-agent"></a>

-## 模式：个人私信 + 公开群组（单智能体）
+## 模式：个人私信 + 公开群组（单个智能体）

 可以——如果你的“个人”流量是**私信**，而“公开”流量是**群组**，这种方式效果很好。

-原因是：在单智能体模式下，私信通常会进入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main:<channel>:group:<id>`）。如果你启用沙箱隔离并设置 `mode: "non-main"`，这些群组会话会在配置的沙箱后端中运行，而你的主私信会话仍保留在宿主机上。如果你没有选择后端，默认后端是 Docker。
+原因是：在单智能体模式下，私信通常会进入**主**会话键（`agent:main:main`），而群组始终使用**非主**会话键（`agent:main:<channel>:group:<id>`）。如果你启用沙箱隔离并设置 `mode: "non-main"`，这些群组会话就会在已配置的沙箱后端中运行，而你的主私信会话仍留在主机上。如果你没有自行选择后端，Docker 是默认后端。

-这会给你一个智能体“核心”（共享工作区 + 记忆），但有两种不同的执行姿态：
+这样你就拥有了一个智能体“大脑”（共享工作区 + 记忆），但有两种不同的执行姿态：

- **私信**：完整工具（宿主机）
+- **私信**：完整工具（主机）
 - **群组**：沙箱 + 受限工具

-> 如果你需要真正独立的工作区/人格（“个人”和“公开”绝不能混合），请使用第二个智能体 + 绑定。参见 [多智能体路由](/zh-CN/concepts/multi-agent)。
+> 如果你需要真正独立的工作区 / 人设（“个人”和“公开”绝不能混用），请使用第二个智能体 + 绑定。参见 [Multi-Agent Routing](/zh-CN/concepts/multi-agent)。

-示例（私信在宿主机上，群组在沙箱中运行且仅允许消息类工具）：
+示例（私信在主机上运行，群组在沙箱中运行并仅允许消息工具）：

 ```json5
 {
@ -123,7 +123,7 @@ otherwise -> 回复
 }
 ```

-想要“群组只能看到文件夹 X”，而不是“完全无法访问宿主机”？保留 `workspaceAccess: "none"`，并且只将允许名单中的路径挂载到沙箱中：
+想要实现“群组只能看到文件夹 X”，而不是“完全没有主机访问权限”？保留 `workspaceAccess: "none"`，然后只将允许列表中的路径挂载到沙箱中：

 ```json5
 {
@ -147,18 +147,18 @@ otherwise -> 回复

 相关内容：

- 配置键和默认值：[Gateway 网关配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)
+- 配置键和默认值：[Gateway 配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)
 - 调试为什么某个工具被阻止：[沙箱 vs 工具策略 vs 提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)
 - 绑定挂载详情：[沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts)

 ## 显示标签

 - UI 标签在可用时使用 `displayName`，格式为 `<channel>:<token>`。
- `#room` 保留给房间/频道；群聊使用 `g-<slug>`（小写，空格转为 `-`，保留 `#@+._-`）。
+- `#room` 保留给房间 / 渠道；群聊使用 `g-<slug>`（小写，空格转为 `-`，保留 `#@+._-`）。

 ## 群组策略

-按渠道控制如何处理群组/房间消息：
+控制每个渠道如何处理群组 / 房间消息：

 ```json5
 {
@ -207,36 +207,35 @@ otherwise -> 回复

 | 策略 | 行为 |
 | ------------- | ------------------------------------------------------------ |
-| `"open"` | 群组绕过允许名单；提及门控仍然适用。 |
+| `"open"` | 群组绕过允许列表；提及门控仍然适用。 |
 | `"disabled"` | 完全阻止所有群组消息。 |
-| `"allowlist"` | 仅允许与已配置允许名单匹配的群组/房间。 |
+| `"allowlist"` | 仅允许与已配置允许列表匹配的群组 / 房间。 |

 说明：

- `groupPolicy` 与提及门控是分开的（提及门控要求 @提及）。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 `groupAllowFrom`（回退为显式 `allowFrom`）。
- 私信配对批准（`*-allowFrom` 存储项）仅适用于私信访问；群组发送者授权仍需通过群组允许名单显式控制。
- Discord：允许名单使用 `channels.discord.guilds.<id>.channels`。
- Slack：允许名单使用 `channels.slack.channels`。
- Matrix：允许名单使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查询是尽力而为，运行时无法解析的名称会被忽略。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持按房间设置 `users` 允许名单。
+- `groupPolicy` 与提及门控是分开的（提及门控要求 `@mentions`）。
+- WhatsApp / Telegram / Signal / iMessage / Microsoft Teams / Zalo：使用 `groupAllowFrom`（回退为显式 `allowFrom`）。
+- 私信配对批准（`*-allowFrom` 存储条目）仅适用于私信访问；群组发送者授权仍需通过群组允许列表显式控制。
+- Discord：允许列表使用 `channels.discord.guilds.<id>.channels`。
+- Slack：允许列表使用 `channels.slack.channels`。
+- Matrix：允许列表使用 `channels.matrix.groups`。优先使用房间 ID 或别名；已加入房间的名称查询仅为尽力而为，运行时无法解析的名称会被忽略。使用 `channels.matrix.groupAllowFrom` 限制发送者；也支持按房间配置 `users` 允许列表。
 - 群组私信单独控制（`channels.discord.dm.*`、`channels.slack.dm.*`）。
- Telegram 允许名单可以匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。
- 默认值是 `groupPolicy: "allowlist"`；如果你的群组允许名单为空，则群组消息会被阻止。
+- Telegram 允许列表可匹配用户 ID（`"123456789"`、`"telegram:123456789"`、`"tg:123456789"`）或用户名（`"@alice"` 或 `"alice"`）；前缀不区分大小写。
+- 默认值是 `groupPolicy: "allowlist"`；如果你的群组允许列表为空，群组消息会被阻止。
 - 运行时安全：当某个提供商配置块完全缺失时（`channels.<provider>` 不存在），群组策略会回退到故障关闭模式（通常是 `allowlist`），而不是继承 `channels.defaults.groupPolicy`。

-快速心智模型（群消息的评估顺序）：
+快速心智模型（群组消息的评估顺序）：

-1. `groupPolicy`（open/disabled/allowlist）
-2. 群组允许名单（`*.groups`、`*.groupAllowFrom`、渠道特定允许名单）
+1. `groupPolicy`（open / disabled / allowlist）
+2. 群组允许列表（`*.groups`、`*.groupAllowFrom`、渠道特定允许列表）
 3. 提及门控（`requireMention`、`/activation`）

 ## 提及门控（默认）

-群消息需要提及，除非按群组单独覆盖。默认值按子系统存放在 `*.groups."*"` 下。
+除非按群组覆盖，否则群组消息需要提及。默认值按各子系统存放在 `*.groups."*"` 下。

-回复机器人消息会被视为一次隐式提及，前提是该渠道支持回复元数据。
-引用机器人消息也可以被视为一次隐式提及，前提是该渠道提供引用元数据。当前内置支持的情况包括
-Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。
+如果渠道支持回复元数据，那么回复机器人消息会被视为隐式提及。
+如果渠道暴露引用元数据，那么引用机器人消息也可以被视为隐式提及。当前内置支持的渠道包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。

 ```json5
 {
@ -276,27 +275,27 @@ Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。

 说明：

- `mentionPatterns` 是大小写不敏感的安全正则模式；无效模式和不安全的嵌套重复形式会被忽略。
- 提供显式提及的渠道仍然会通过；这些模式只是回退方案。
+- `mentionPatterns` 是不区分大小写的安全正则模式；无效模式和不安全的嵌套重复形式会被忽略。
+- 提供显式提及的界面仍然会通过；这些模式只是后备方案。
 - 按智能体覆盖：`agents.list[].groupChat.mentionPatterns`（当多个智能体共享一个群组时很有用）。
- 只有在能够检测提及的情况下才会强制执行提及门控（存在原生提及，或已配置 `mentionPatterns`）。
- Discord 默认值位于 `channels.discord.guilds."*"`（可按 guild/channel 覆盖）。
- 群组历史上下文在各渠道中采用统一包装，并且仅包含**待处理消息**（即因提及门控而被跳过的消息）；全局默认值使用 `messages.groupChat.historyLimit`，覆盖值使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）。设为 `0` 可禁用。
+- 只有在可以检测提及时，才会强制执行提及门控（原生提及或已配置 `mentionPatterns`）。
+- Discord 默认值位于 `channels.discord.guilds."*"`（可按 guild / channel 覆盖）。
+- 群组历史上下文会在各渠道间以统一方式包装，并且仅包含**待处理消息**（即因提及门控而被跳过的消息）；全局默认值使用 `messages.groupChat.historyLimit`，覆盖值使用 `channels.<channel>.historyLimit`（或 `channels.<channel>.accounts.*.historyLimit`）。设置为 `0` 可禁用。

-## 群组/频道工具限制（可选）
+## 群组 / 渠道工具限制（可选）

-某些渠道配置支持限制**某个特定群组/房间/频道内**可用的工具。
+某些渠道配置支持限制**特定群组 / 房间 / 渠道内部**可用的工具。

- `tools`：为整个群组允许/拒绝工具。
- `toolsBySender`：群组内按发送者设置覆盖。
+- `tools`：为整个群组允许 / 拒绝工具。
+- `toolsBySender`：群组内按发送者进行覆盖。
  使用显式键前缀：
-  `id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>`，以及 `"*"` 通配符。
-  旧版无前缀键仍然接受，但只会按 `id:` 匹配。
+  `id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>`，以及通配符 `"*"`。
+  旧版无前缀键仍然被接受，但只会按 `id:` 匹配。

-解析顺序（越具体越优先）：
+解析顺序（越具体优先级越高）：

-1. 群组/频道 `toolsBySender` 匹配
-2. 群组/频道 `tools`
+1. 群组 / 渠道 `toolsBySender` 匹配
+2. 群组 / 渠道 `tools`
 3. 默认值（`"*"`）`toolsBySender` 匹配
 4. 默认值（`"*"`）`tools`

@ -322,17 +321,17 @@ Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。

 说明：

- 群组/频道工具限制会与全局/智能体工具策略一并生效（`deny` 仍然优先）。
- 某些渠道对房间/频道使用不同的嵌套结构（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。
+- 群组 / 渠道工具限制会在全局 / 智能体工具策略之外额外应用（`deny` 仍然优先）。
+- 某些渠道对房间 / 渠道使用不同的嵌套结构（例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`）。

-## 群组允许名单
+## 群组允许列表

-当配置了 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会作为群组允许名单。使用 `"*"` 可以允许所有群组，同时仍设置默认的提及行为。
+当配置了 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时，这些键会作为群组允许列表。使用 `"*"` 可允许所有群组，同时仍可设置默认的提及行为。

-常见混淆点：私信配对批准并不等同于群组授权。
-对于支持私信配对的渠道，配对存储仅解锁私信。群组命令仍然需要通过配置允许名单显式授权群组发送者，例如 `groupAllowFrom`，或该渠道文档中说明的配置回退项。
+一个常见误解是：私信配对批准并不等同于群组授权。
+对于支持私信配对的渠道，配对存储只会解锁私信。群组命令仍然需要通过配置允许列表显式进行群组发送者授权，例如 `groupAllowFrom`，或该渠道文档中说明的配置回退项。

-常见意图（可直接复制粘贴）：
+常见意图（可直接复制 / 粘贴）：

 1. 禁用所有群组回复

@ -357,7 +356,7 @@ Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。
 }
 ```

-3. 允许所有群组，但要求提及（显式）
+3. 允许所有群组但要求提及（显式设置）

 ```json5
 {
@ -385,39 +384,39 @@ Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。

 ## 激活（仅所有者）

-群组所有者可以按群组切换激活方式：
+群组所有者可以按群组切换激活模式：

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

-所有者由 `channels.whatsapp.allowFrom` 决定（如果未设置，则使用机器人自身的 E.164）。请将该命令作为单独的一条消息发送。其他平台当前会忽略 `/activation`。
+所有者由 `channels.whatsapp.allowFrom` 决定（若未设置，则使用机器人的自身 E.164）。请将该命令作为单独一条消息发送。其他界面当前会忽略 `/activation`。

 ## 上下文字段

-群组入站载荷会设置：
+群组入站负载会设置：

 - `ChatType=group`
 - `GroupSubject`（如果已知）
 - `GroupMembers`（如果已知）
 - `WasMentioned`（提及门控结果）
- Telegram 论坛主题还会包含 `MessageThreadId` 和 `IsForum`。
+- Telegram 论坛话题还会包含 `MessageThreadId` 和 `IsForum`。

 渠道特定说明：

- BlueBubbles 可以选择在填充 `GroupMembers` 之前，从本地通讯录数据库中补充未命名的 macOS 群组参与者信息。此功能默认关闭，并且只会在常规群组门控通过后运行。
+- BlueBubbles 可以在填充 `GroupMembers` 之前，选择性地从本地联系人数据库中补充未命名的 macOS 群组参与者信息。此功能默认关闭，并且仅在正常群组门控通过后才会运行。

-智能体系统提示会在新群组会话的第一轮加入一段群组介绍。它会提醒模型像人类一样回复、避免使用 Markdown 表格、尽量减少空行、遵循正常聊天的空格习惯，并避免输入字面量 `\n` 序列。
+在新群组会话的第一轮中，智能体系统提示会包含群组介绍。它会提醒模型像人类一样回复、避免使用 Markdown 表格、尽量减少空行、遵循正常聊天间距，并避免输入字面量 `\n` 序列。来自渠道的群组名称和参与者标签会作为带围栏的不受信任元数据呈现，而不是内联系统指令。

 ## iMessage 细节

- 在路由或允许名单中，优先使用 `chat_id:<id>`。
+- 在路由或允许列表中优先使用 `chat_id:<id>`。
 - 列出聊天：`imsg chats --limit 20`。
- 群组回复始终会返回到相同的 `chat_id`。
+- 群组回复始终会返回到同一个 `chat_id`。

 ## WhatsApp 系统提示

-有关标准的 WhatsApp 系统提示规则，包括群组与私聊提示解析、通配符行为和账号覆盖语义，请参见 [WhatsApp](/zh-CN/channels/whatsapp#system-prompts)。
+有关规范的 WhatsApp 系统提示规则，包括群组和私聊提示解析、通配符行为以及账号覆盖语义，请参见 [WhatsApp](/zh-CN/channels/whatsapp#system-prompts)。

 ## WhatsApp 细节

-有关仅限 WhatsApp 的行为（历史注入、提及处理细节），请参见 [群组消息](/zh-CN/channels/group-messages)。
+有关仅适用于 WhatsApp 的行为（历史注入、提及处理细节），请参见 [群组消息](/zh-CN/channels/group-messages)。
--- a/docs/zh-CN/channels/whatsapp.md
+++ b/docs/zh-CN/channels/whatsapp.md
@ -4,25 +4,25 @@ read_when:
 summary: WhatsApp 渠道支持、访问控制、投递行为和运维
 title: WhatsApp
 x-i18n:
-    generated_at: "2026-04-23T07:03:52Z"
+    generated_at: "2026-04-23T17:19:24Z"
    model: gpt-5.4
    provider: openai
-    source_hash: e14735a33ffb48334b920a5e63645abf3445f56481b1ce8b7c128800e2adc981
+    source_hash: 3fb32e2ca2ced699198d92a2fc15aa5f62806540f197e71a332def0f05dd1d25
    source_path: channels/whatsapp.md
    workflow: 15
 ---

 # WhatsApp（Web 渠道）

-状态：通过 WhatsApp Web（Baileys）达到生产可用。Gateway 网关拥有已关联的会话。
+状态：通过 WhatsApp Web（Baileys）达到生产就绪。Gateway 网关负责已关联的会话。

 ## 安装（按需）

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

 仍然可以手动安装：
@ -36,14 +36,14 @@ 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">
    完整的渠道配置模式和示例。
  </Card>
 </CardGroup>

-## 快速开始
+## 快速设置

 <Steps>
  <Step title="配置 WhatsApp 访问策略">
@ -69,7 +69,7 @@ openclaw plugins install @openclaw/whatsapp
 openclaw channels login --channel whatsapp
 ```

-    针对特定账户：
+    对于特定账户：

 ```bash
 openclaw channels login --channel whatsapp --account work
@ -85,7 +85,7 @@ openclaw gateway

  </Step>

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

 ```bash
 openclaw pairing list whatsapp
@ -98,14 +98,14 @@ openclaw pairing approve whatsapp <CODE>
 </Steps>

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

 ## 部署模式

 <AccordionGroup>
  <Accordion title="专用号码（推荐）">
-    这是最清晰的运维模式：
+    这是最简洁的运维模式：

    - 为 OpenClaw 使用单独的 WhatsApp 身份
    - 更清晰的私信允许列表和路由边界
@ -127,7 +127,7 @@ OpenClaw 建议在可能的情况下为 WhatsApp 使用单独的号码。（渠
  </Accordion>

  <Accordion title="个人号码回退方案">
-    新手引导支持个人号码模式，并会写入适合自聊的基线配置：
+    新手引导支持个人号码模式，并会写入一个适合自聊的基线配置：

    - `dmPolicy: "allowlist"`
    - `allowFrom` 包含你的个人号码
@ -147,41 +147,41 @@ 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`）对该账户的优先级高于渠道级默认值。

    运行时行为细节：

-    - 配对会持久化到渠道 allow-store，并与配置的 `allowFrom` 合并
+    - 配对信息会持久化到渠道允许存储中，并与已配置的 `allowFrom` 合并
    - 如果未配置允许列表，则默认允许已关联的自身号码
-    - 出站 `fromMe` 私信永远不会自动配对
+    - 出站的 `fromMe` 私信绝不会自动配对

  </Tab>

  <Tab title="群组策略 + 允许列表">
-    群组访问有两层控制：
+    群组访问有两层：

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

    2. **群组发送者策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`）
@ -192,51 +192,51 @@ OpenClaw 建议在可能的情况下为 WhatsApp 使用单独的号码。（渠
    发送者允许列表回退：

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

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

  </Tab>

  <Tab title="提及 + /activation">
-    默认情况下，群组回复需要被提及。
+    群组回复默认需要被提及。

    提及检测包括：

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

    安全说明：

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

    会话级激活命令：

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

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

  </Tab>
 </Tabs>

 ## 个人号码和自聊行为

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

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

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

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

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

    ```text
    [Replying to <sender> id:<stanzaId>]
@ -249,7 +249,7 @@ OpenClaw 建议在可能的情况下为 WhatsApp 使用单独的号码。（渠
  </Accordion>

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

    - `<media:image>`
    - `<media:video>`
@ -257,12 +257,12 @@ OpenClaw 建议在可能的情况下为 WhatsApp 使用单独的号码。（渠
    - `<media:document>`
    - `<media:sticker>`

-    位置和联系人负载会在路由前规范化为文本上下文。
+    位置消息正文使用简洁的坐标文本。位置标签/评论以及联系人/vCard 详情会被渲染为带围栏的不受信任元数据，而不是内联提示文本。

  </Accordion>

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

    - 默认上限：`50`
    - 配置：`channels.whatsapp.historyLimit`
@ -277,7 +277,7 @@ OpenClaw 建议在可能的情况下为 WhatsApp 使用单独的号码。（渠
  </Accordion>

  <Accordion title="已读回执">
-    默认会为已接受的入站 WhatsApp 消息发送已读回执。
+    对已接受的入站 WhatsApp 消息，默认启用已读回执。

    全局禁用：

@ -316,16 +316,16 @@ OpenClaw 建议在可能的情况下为 WhatsApp 使用单独的号码。（渠

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

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

@ -333,20 +333,20 @@ OpenClaw 建议在可能的情况下为 WhatsApp 使用单独的号码。（渠
    - 入站媒体保存上限：`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`。

@ -360,16 +360,16 @@ WhatsApp 支持原生回复引用，出站回复会可见地引用入站消息
 }
 ```

-## Reaction 级别
+## 反应级别

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

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

 默认值：`"minimal"`。

@ -385,10 +385,10 @@ WhatsApp 支持原生回复引用，出站回复会可见地引用入站消息
 }
 ```

-## 确认 reaction
+## 确认反应

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

 ```json5
 {
@ -406,41 +406,41 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在接收入站消息时

 行为说明：

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

 ## 多账户和凭证

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

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

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

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

  </Accordion>
 </AccordionGroup>

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

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

 ## 故障排除

@ -472,14 +472,14 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在接收入站消息时
  </Accordion>

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

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

  </Accordion>

  <Accordion title="群组消息被意外忽略">
-    请按以下顺序检查：
+    按以下顺序检查：

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

 示例：

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

-## 配置参考指引
+## 配置参考指针

 主要参考：