chore(i18n): refresh zh-CN translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-29 19:07:39 +00:00
parent 046f5fb880
commit 1746899e10

View File

@ -1,23 +1,23 @@
---
read_when:
- 更改群聊行为或提及门控
- 更改群聊行为或提及门控机制
sidebarTitle: Groups
summary: 各平台的群聊行为Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo
title: 群组
x-i18n:
generated_at: "2026-04-29T10:10:39Z"
generated_at: "2026-04-29T19:06:41Z"
model: gpt-5.5
provider: openai
source_hash: 1f0766149bc208a934c6a07ea409d7ceadc6c5f52f7dab7d3f50d6fc9c383f13
source_hash: 743dc1ce1a0e5dc5c6d66091854cdcbb8d2b8f7e06b5c1d13c272142265fc998
source_path: channels/groups.md
workflow: 16
---
OpenClaw 在各个界面中一致处理群聊Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
OpenClaw 会在各个表面一致地处理群聊Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。
## 初学者简介2 分钟)
OpenClaw “存在”你自己的消息账号中。没有单独的 WhatsApp 机器人用户。如果**你**在某个群组中OpenClaw 就能看到该群组并在那里响应
OpenClaw “存在”你自己的消息账号中。没有单独的 WhatsApp bot 用户。如果**你**在某个群组里OpenClaw 就能看到该群组并在那里回复
默认行为:
@ -48,15 +48,15 @@ otherwise -> reply
## 可见回复
对于群组/渠道房间OpenClaw 默认使用 `messages.groupChat.visibleReplies: "message_tool"`
这意味着智能体仍会处理这一轮,并且可以更新记忆/会话状态,但它的普通最终答案不会自动发回房间。要公开发言,智能体会使用 `message(action=send)`
这意味着智能体仍会处理该轮对话,并且可以更新记忆/会话状态,但它的普通最终答案不会自动发回房间。要公开发言,智能体会使用 `message(action=send)`
对于直接聊天和任何其他来源轮次,使用 `messages.visibleReplies: "message_tool"`在全局应用同的仅工具可见回复行为。`messages.groupChat.visibleReplies` 仍然是针对群组/渠道房间的更具体覆盖项。
对于直接聊天和任何其他来源轮次,使用 `messages.visibleReplies: "message_tool"` 可在全局应用同的仅工具可见回复行为。`messages.groupChat.visibleReplies` 仍然是针对群组/渠道房间的更具体覆盖项。
这取代了旧模式中强制模型在大多数旁观模式轮次回答 `NO_REPLY` 的做法。在仅工具模式中,不产生可见输出只是意味着不调用消息工具。
这取代了旧模式中强制模型在大多数潜伏模式轮次回答 `NO_REPLY` 的做法。在仅工具模式下,没有任何可见动作只是意味着不调用 message 工具。
智能体在仅工具模式中工作时,仍会发送正在输入指示。对于这些轮次,默认群组输入模式会从 “message” 升级为 “instant”因为在智能体决定是否调用消息工具之前可能永远不会有普通助手消息文本。显式输入模式配置仍然优先。
在智能体以仅工具模式工作时,仍会发送输入状态指示。对于这些轮次,默认群组输入状态模式会从 "message" 升级为 "instant",因为在智能体决定是否调用 message 工具之前,可能永远不会有普通的助手消息文本。显式输入状态模式配置仍然优先。
为群组/渠道房间恢复旧版自动最终回复:
恢复群组/渠道房间的旧版自动最终回复:
```json5
{
@ -68,7 +68,7 @@ otherwise -> reply
}
```
要要求每个来源聊天的可见输出都通过消息工具:
要要求每个来源聊天的可见输出都通过 message 工具:
```json5
{
@ -78,70 +78,70 @@ otherwise -> reply
}
```
原生命令Discord、Telegram 以及其他支持原生命令的界面)会绕过 `visibleReplies: "message_tool"`,并始终可见回复,以便渠道原生命令 UI 获得预期响应。这只适用于已验证的原生命令轮次;文本输入的 `/...` 命令和普通聊天轮次仍遵循已配置的群组默认值。
原生命令斜杠命令Discord、Telegram以及其他支持原生命令的表面)会绕过 `visibleReplies: "message_tool"`,并始终可见回复,以便渠道原生命令 UI 获得预期响应。这只适用于已验证的原生命令轮次;文本输入的 `/...` 命令和普通聊天轮次仍遵循已配置的群组默认值。
## 上下文可见性和允许列表
群组安全涉及两个不同控制项
群组安全涉及两种不同控制
- **触发授权**:谁可以触发智能体(`groupPolicy`、`groups`、`groupAllowFrom`、渠道专用允许列表)。
- **触发授权**:谁可以触发智能体(`groupPolicy`、`groups`、`groupAllowFrom`、特定渠道的允许列表)。
- **上下文可见性**:哪些补充上下文会注入模型(回复文本、引用、线程历史、转发元数据)。
默认情况下OpenClaw 优先保证正常聊天行为,并尽量按接收时保留上下文。这意味着允许列表主要决定谁可以触发操作,而不是作为每个引用或历史片段的通用脱敏边界。
默认情况下OpenClaw 优先保持正常聊天行为,并基本按接收状态保留上下文。这意味着允许列表主要决定谁可以触发操作,而不是对每个引用片段或历史片段都适用的通用脱敏边界。
<AccordionGroup>
<Accordion title="当前行为因渠道而异">
- 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤(例如 Slack 线程种、Matrix 回复/线程查找)。
- 其他渠道仍会按接收传递引用/回复/转发上下文。
- 一些渠道已经在特定路径中对补充上下文应用基于发送者的过滤(例如 Slack 线程种、Matrix 回复/线程查找)。
- 其他渠道仍会按接收状态传递引用/回复/转发上下文。
</Accordion>
<Accordion title="加固方向(计划中)">
- `contextVisibility: "all"`(默认)保留当前按接收时处理的行为。
- `contextVisibility: "allowlist"` 将补充上下文过滤为只包含允许列表中的发送者。
- `contextVisibility: "all"`(默认值)保留当前按接收状态处理的行为。
- `contextVisibility: "allowlist"` 将补充上下文过滤为允许列表中的发送者。
- `contextVisibility: "allowlist_quote"``allowlist` 加上一个显式引用/回复例外。
这一加固模型在各渠道中一致实现之前,预期不同界面会有差异。
该加固模型在各渠道中一致实现之前,预计不同表面会存在差异。
</Accordion>
</AccordionGroup>
![群组消息流程](/images/groups-flow.svg)
如果你想……
如果你想要...
| 目标 | 要设置的内容 |
| -------------------------------------------- | ---------------------------------------------------------- |
| 允许所有群组,但@提及时回复 | `groups: { "*": { requireMention: true } }` |
| 允许所有群组,但@提及时回复 | `groups: { "*": { requireMention: true } }` |
| 禁用所有群组回复 | `groupPolicy: "disabled"` |
| 只允许特定群组 | `groups: { "<group-id>": { ... } }`(没有 `"*"` 键) |
| 特定群组 | `groups: { "<group-id>": { ... } }`(没有 `"*"` 键) |
| 只有你可以在群组中触发 | `groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]` |
## 会话键
- 群组会话使用 `agent:<agentId>:<channel>:group:<id>` 会话键(房间/渠道使用 `agent:<agentId>:<channel>:channel:<id>`)。
- Telegram 论坛主题会向群组 ID 添加 `:topic:<threadId>`,因此每个主题都有自己的会话。
- 直接聊天使用主会话(如果已配置,则使用每发送者会话)。
- 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 是默认后端。
这会给你一个智能体“大脑”(共享工作区 + 记忆),但有两种执行姿态:
- **私信**:完整工具(主机)
- **私信**:完整工具(宿主机)
- **群组**:沙箱 + 受限工具
<Note>
如果你需要真正分离的工作区/角色(“个人”和“公共”绝不能混合),请使用第二个智能体 + 绑定。参见[多智能体路由](/zh-CN/concepts/multi-agent)。
如果你需要真正独立的工作区/角色(“个人”和“公共”绝不能混合),请使用第二个智能体 + 绑定。参见 [多智能体路由](/zh-CN/concepts/multi-agent)。
</Note>
<Tabs>
<Tab title="私信在主机上,群组沙箱隔离">
<Tab title="私信在宿主机上,群组在沙箱中">
```json5
{
agents: {
@ -165,8 +165,8 @@ otherwise -> reply
}
```
</Tab>
<Tab title="群组只能看到允许列表中的文件夹">
想要“群组只能看到文件夹 X”而不是“没有主机访问权限”?保持 `workspaceAccess: "none"`,并只将允许列表中的路径挂载到沙箱中
<Tab title="群组只能看到允许列表文件夹">
想要“群组只能看到文件夹 X”而不是“没有宿主机访问权限”?保留 `workspaceAccess: "none"`,并且只将允许列表路径挂载进沙箱
```json5
{
@ -191,16 +191,16 @@ otherwise -> reply
</Tab>
</Tabs>
相关内容
相关:
- 配置键和默认值:[Gateway 网关配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox)
- 调试为什么工具被阻止:[沙箱与工具策略与提权](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated)
- 调试工具为什么被阻止:[沙箱与工具策略与提权](/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>`(小写,空格 -> `-`,保留 `#@+._-`)。
## 群组策略
@ -255,20 +255,20 @@ otherwise -> reply
| ------------- | ------------------------------------------------------------ |
| `"open"` | 群组绕过允许列表;提及门控仍然适用。 |
| `"disabled"` | 完全阻止所有群组消息。 |
| `"allowlist"` | 允许匹配已配置允许列表的群组/房间。 |
| `"allowlist"` | 允许匹配已配置允许列表的群组/房间。 |
<AccordionGroup>
<Accordion title="按渠道说明">
- `groupPolicy` 与提及门控分开(后者要求 @提及)。
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo使用 `groupAllowFrom`(回退:显式 `allowFrom`)。
- 私信配对批准(`*-allowFrom` 存储条目)仅适用于私信访问;群组发送者授权仍显式归属群组允许列表。
- `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` 允许列表。
- 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"`;如果你的群组允许列表为空,群组消息会被阻止。
- 运行时安全:当提供商块完全缺失(不存在 `channels.<provider>`)时,群组策略会回退到故障关闭模式(通常为 `allowlist`),而不是继承 `channels.defaults.groupPolicy`
- 运行时安全:当某个提供商块完全缺失(没有 `channels.<provider>`)时,群组策略会回退到关闭失败模式(通常是 `allowlist`),而不是继承 `channels.defaults.groupPolicy`
</Accordion>
</AccordionGroup>
@ -280,7 +280,7 @@ otherwise -> reply
`groupPolicy`open/disabled/allowlist
</Step>
<Step title="群组允许列表">
群组允许列表(`*.groups`、`*.groupAllowFrom`、渠道专用允许列表)。
群组允许列表(`*.groups`、`*.groupAllowFrom`、特定渠道允许列表)。
</Step>
<Step title="提及门控">
提及门控(`requireMention`、`/activation`)。
@ -291,7 +291,7 @@ otherwise -> reply
群组消息需要提及,除非按群组覆盖。默认值位于每个子系统的 `*.groups."*"` 下。
回复机器人消息时,如果渠道支持回复元数据,则会算作隐式提及。引用机器人消息时,在暴露引用元数据的渠道上也可以算作隐式提及。当前内置案例包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。
回复机器人消息会在渠道支持回复元数据时算作隐式提及。引用机器人消息在暴露引用元数据的渠道上也可以算作隐式提及。当前内置场景包括 Telegram、WhatsApp、Slack、Discord、Microsoft Teams 和 ZaloUser。
```json5
{
@ -331,24 +331,24 @@ otherwise -> reply
<AccordionGroup>
<Accordion title="提及门控说明">
- `mentionPatterns` 是大小写不敏感的安全正则表达式模式;无效模式和不安全的嵌套重复形式会被忽略。
- 提供显式提及的面仍会通过;模式是兜底方案。
- 按智能体覆盖:`agents.list[].groupChat.mentionPatterns`多个智能体共享一个群组时很有用)。
- 仅当可以进行提及检测时,才会强制执行提及门控(原生提及或已配置 `mentionPatterns`
- 群聊提示上下文会在每一轮携带解析的静默回复指令;工作区文件不应重复 `NO_REPLY` 机制。
- 允许静默回复的群组会将干净的空模型轮次或仅推理的模型轮次视为静默,等同于 `NO_REPLY`。直接聊天仍会将空回复视为一次失败的智能体轮次。
- `mentionPatterns`不区分大小写的安全正则表达式模式;无效模式和不安全的嵌套重复形式会被忽略。
- 提供显式提及的面仍会通过;模式是兜底方案。
- 按智能体覆盖:`agents.list[].groupChat.mentionPatterns`(多个智能体共享一个群组时很有用)。
- 只有在可以检测提及时(配置了原生提及或 `mentionPatterns`),才会强制执行提及门控
- 群聊提示上下文会在每一轮携带解析的静默回复指令;工作区文件不应重复 `NO_REPLY` 机制。
- 允许静默回复的群组会将干净的空模型轮次或仅推理轮次视为静默,等同于 `NO_REPLY`。直聊只有在显式允许直接静默回复时才会执行相同逻辑;否则空回复仍会算作失败的智能体轮次。
- Discord 默认值位于 `channels.discord.guilds."*"`(可按 guild/渠道覆盖)。
- 群组历史上下文在各渠道中统一包装,并且**仅待处理**(因提及门控而跳过的消息);使用 `messages.groupChat.historyLimit` 设置全局默认值,使用 `channels.<channel>.historyLimit`(或 `channels.<channel>.accounts.*.historyLimit`)进行覆盖。设`0` 可禁用。
- 群组历史上下文在各渠道中统一包装,并且**仅包含待处理内容**(因提及门控而跳过的消息);使用 `messages.groupChat.historyLimit` 设置全局默认值,使用 `channels.<channel>.historyLimit`(或 `channels.<channel>.accounts.*.historyLimit`)进行覆盖。设为 `0` 可禁用。
</Accordion>
</AccordionGroup>
## 群组/渠道工具限制(可选)
些渠道配置支持限制**特定群组/房间/渠道内**可用的工具。
些渠道配置支持限制**特定群组/房间/渠道内**可用的工具。
- `tools`:允许/拒绝整个群组的工具。
- `toolsBySender`:群组内按发送者覆盖。使用显式键前缀:`id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>` `"*"` 通配符。旧版无前缀键仍被接受,并且仅按 `id:` 匹配。
- `toolsBySender`:群组内按发送者覆盖。使用显式键前缀:`id:<senderId>`、`e164:<phone>`、`username:<handle>`、`name:<displayName>`,以及 `"*"` 通配符。旧版无前缀键仍被接受,并且仅按 `id:` 匹配。
解析顺序(最具体的优先):
@ -388,7 +388,7 @@ otherwise -> reply
```
<Note>
群组/渠道工具限制会在全局/智能体工具策略之外额外应用(拒绝仍然优先)。一些渠道对房间/渠道使用不同的嵌套方式(例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`)。
群组/渠道工具限制会叠加到全局/智能体工具策略之上(拒绝仍然优先)。某些渠道对房间/渠道使用不同的嵌套结构(例如 Discord `guilds.*.channels.*`、Slack `channels.*`、Microsoft Teams `teams.*.channels.*`)。
</Note>
## 群组允许列表
@ -396,7 +396,7 @@ otherwise -> reply
配置 `channels.whatsapp.groups`、`channels.telegram.groups` 或 `channels.imessage.groups` 时,这些键会作为群组允许列表。使用 `"*"` 可允许所有群组,同时仍设置默认提及行为。
<Warning>
常见混淆:私信配对批准不同于群组授权。对于支持私信配对的渠道,配对存储只解锁私信。群组命令仍需要来自配置允许列表的显式群组发送者授权,例如 `groupAllowFrom` 或该渠道文档化的配置兜底项
常见混淆:私信配对批准不同于群组授权。对于支持私信配对的渠道,配对存储只解锁私信。群组命令仍需要来自配置允许列表的显式群组发送者授权,例如 `groupAllowFrom` 或该渠道记录的配置兜底
</Warning>
常见意图(复制/粘贴):
@ -409,7 +409,7 @@ otherwise -> reply
}
```
</Tab>
<Tab title="允许特定群组WhatsApp">
<Tab title="允许特定群组WhatsApp">
```json5
{
channels: {
@ -451,12 +451,12 @@ otherwise -> reply
## 激活(仅所有者)
群组所有者可以切换按群组激活
群组所有者可以切换每个群组的激活方式
- `/activation mention`
- `/activation always`
所有者由 `channels.whatsapp.allowFrom` 决定(未设置时为机器人的自身 E.164)。请将该命令作为独立消息发送。其他表面当前会忽略 `/activation`
所有者由 `channels.whatsapp.allowFrom` 决定(未设置时使用机器人的自身 E.164)。将该命令作为独立消息发送。其他界面目前会忽略 `/activation`
## 上下文字段
@ -466,27 +466,27 @@ otherwise -> reply
- `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 系统提示词规则,请参阅 [WhatsApp](/zh-CN/channels/whatsapp#system-prompts),包括群组和直接提示解析、通配符行为以及账号覆盖语义。
## WhatsApp 细节
请参阅[群组消息](/zh-CN/channels/group-messages),了解 WhatsApp 专属行为(历史注入、提及处理细节)
有关 WhatsApp 专属行为(历史注入、提及处理细节),请参阅[群组消息](/zh-CN/channels/group-messages)。
## 相关