OpenClaw 对 WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams、Zalo 等所有支持的平台提供一致的群组处理机制。本文深度解析群组配置的每个细节。
核心设计原则
OpenClaw「住」在你自己的消息账号里——没有独立的 Bot 账号。如果你在某个群组，OpenClaw 就能在那个群组里响应。
默认行为：
- 群组被限制（
groupPolicy: "allowlist"） - 回复需要被 @提及
群组消息处理流程
groupPolicy = disabled? → 丢弃
groupPolicy = allowlist → 群组在允许列表中? 否 → 丢弃
requireMention = true → 被提及? 否 → 仅存入上下文，不触发回复
否则 → 触发 Agent 回复
快速配置速查：
| 目标 | 配置 |
|---|---|
| 允许所有群组但仅 @提及响应 | groups: { "*": { requireMention: true } } |
| 禁止所有群组回复 | groupPolicy: "disabled" |
| 仅允许特定群组 | ���配置具体群组 ID，不含 "*" 通配符 |
| 仅主人可以在群组触发 | groupPolicy: "allowlist" + groupAllowFrom: ["+1555..."] |
多平台群组策略配置
json
{
"channels": {
"whatsapp": {
"groupPolicy": "allowlist",
"groupAllowFrom": ["+15551234567"],
"groups": {
"*": { "requireMention": true },
"123@g.us": { "requireMention": false }
}
}
}
}Telegram
json
{
"channels": {
"telegram": {
"groupPolicy": "allowlist",
"groupAllowFrom": ["123456789"],
"groups": {
"*": { "requireMention": true },
"-1001234567890": { "requireMention": false }
}
}
}
}iMessage
json
{
"channels": {
"imessage": {
"groupPolicy": "allowlist",
"groupAllowFrom": ["chat_id:123"],
"groups": {
"chat_id:123": { "requireMention": true }
}
}
}
}iMessage 路由推荐使用 chat_id:<id> 格式，可用 imsg chats --limit 20 列出群组 ID。
@提及识别配置
json
{
"agents": {
"list": [
{
"id": "main",
"groupChat": {
"mentionPatterns": ["@openclaw", "openclaw", "\\+15555550123"],
"historyLimit": 50
}
}
]
}
}注意事项：
mentionPatterns是大小写不敏感的正则表达式- 平台提供的原生 @提及（
mentionedJids）仍然有效，mentionPatterns是补充 - 多 Agent 场景：每个 Agent 单独设置
mentionPatterns - 回复 Bot 消息本身被视为隐式提及（Telegram、WhatsApp、Slack、Discord、Teams 支持）
全局回退（所有 Agent 共用）：
json
{
"messages": {
"groupChat": {
"mentionPatterns": ["@openclaw"],
"historyLimit": 30
}
}
}群组工具权限控制
按群组限制工具
json
{
"channels": {
"telegram": {
"groups": {
"*": { "tools": { "deny": ["exec"] } },
"-1001234567890": {
"tools": { "deny": ["exec", "read", "write"] },
"toolsBySender": {
"id:123456789": { "alsoAllow": ["exec"] }
}
}
}
}
}
}权限解析优先级（从高到低）
toolsBySender精确匹配（最高优先级）- 群组/频道级
tools - 默认
"*"toolsBySender - 默认
"*"tools
toolsBySender 键格式：
| 前缀 | 示例 | 匹配依据 |
|---|---|---|
id: | id:123456789 | 发送者 ID |
e164: | e164:+15555550123 | E.164 电话号码 |
username: | username:johndoe | 用户名 |
name: | name:John Doe | 显示名称 |
"*" | "*" | 所有用户（通配） |
不同平台的配置键差异：
| 平台 | 配置路径 |
|---|---|
| Discord | channels.discord.guilds.*.channels.* |
| Slack | channels.slack.channels.* |
| MS Teams | channels.msteams.teams.*.channels.* |
单 Agent 双模式运行：个人 DM + 公开群组
这是一个非常实用的架构模式——一个 Agent「大脑」，DM 和群组使用不同的执行策略：
json
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "session",
"workspaceAccess": "none"
}
}
},
"tools": {
"sandbox": {
"tools": {
"allow": ["group:messaging", "group:sessions"],
"deny": ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"]
}
}
}
}工作原理：
| 会话类型 | Session Key | 执行环境 | 可用工具 |
|---|---|---|---|
| DM | agent:main:main | 宿主机（全权限） | 所有工具 |
| 群组 | agent:main:<channel>:group:<id> | Docker 沙箱 | 仅消息相关工具 |
优点：共享同一个工作区和长期记忆，同时对公开群组实施严格工具隔离。
更进一步——挂载特定目录给群组沙箱：
json
{
"agents": {
"defaults": {
"sandbox": {
"mode": "non-main",
"scope": "session",
"workspaceAccess": "none",
"docker": {
"binds": [
"/home/user/SharedDocs:/data:ro"
]
}
}
}
}
}群组中的 Agent 只能只读访问 /data，主工作区完全隔离。
Agent 系统提示中的群组上下文
群组会话第一轮自动注入系统提示：
你正在 WhatsApp 群「<群名称>」中回复。
群成员：Alice (+44...), Bob (+43...), ...
激活模式：仅触发模式（被提及时响应）
请根据消息上下文中标注的发送者来称呼对方。
此外，系统提示还会提醒 Agent：
- 像真实人类一样回复
- 避免 Markdown 表格（移动端渲染不佳）
- 不要输出字面
\n换行符
原文：Groups - OpenClaw | 来源：OpenClaw 官方文档