OpenClaw 群组消息完全指南：WhatsApp 群组配置、@提及激活模式与多 Agent 广播

OpenClaw 支持在群组（WhatsApp 群、Telegram 群、Discord 服务器、Slack 工作区）中作为 AI 成员参与对话。本文重点讲解群组消息的核心配置：激活模式、访问控制、上下文注入，以及多 Agent 广播组。

核心设计原则#

OpenClaw 在群组中的设计目标是：被叫到才说话，不打扰日常聊天。

• 默认模式：只有 @提及才响应（mention 模式）
• 群组会话独立：每个群有独立会话，与个人 DM 会话完全隔离
• 心跳静默：群组会话跳过心跳检测，避免无关消息刷屏

基础配置（以 WhatsApp 为例）#

{
  "channels": {
    "whatsapp": {
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "groupChat": {
          "historyLimit": 50,
          "mentionPatterns": ["@?openclaw", "\\+?15555550123"]
        }
      }
    ]
  }
}

配置说明：

• groups: { "*": ... } — 通配符，对所有群组生效。也可用具体群组 JID 替换
• requireMention: true — 必须 @提及才响应
• mentionPatterns — 正则表达式，匹配显示名称 ping（因为 WhatsApp 有时会去掉视觉上的 @）
• historyLimit: 50 — 注入未触发对话记录的条数上限

激活模式#

切换激活模式（群内命令）#

在群组中发送（仅主人可执行）：

查看当前状态：

@提及识别机制#

WhatsApp 使用两种提及方式，OpenClaw 都能识别：

1. mentionedJids：用户点击联系人 @时，WhatsApp 在消息元数据中附带此字段（最可靠）
2. 正则匹配：通过 mentionPatterns 匹配文本中的显示名称或号码（兜底方案）

推荐同时配置两者，正则作为安全兜底。

群组访问控制（groupPolicy）#

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["120363403215116621@g.us", "120363403215116622@g.us"]
    }
  }
}

未配置 groupAllowFrom 时回退使用 channels.whatsapp.allowFrom。

上下文注入机制#

每次触发响应时，OpenClaw 会将未触发运行的待处理群消息注入到 Agent 上下文中：

关键行为：

• 已在会话中的消息不会重复注入
• 每条消息末尾附加 [from: 发送者名称 (+E164)]，让 Agent 知道在和谁说话
• 查看一次加密/阅后即焚消息后，其中的 @提及仍然有效

会话键（Session Key）格式#

群组会话与 DM 会话完全隔离，使用不同的 Session Key：

在群组中发送的会话级命令（/verbose on、/think high、/new）只影响该群的会话，个人 DM 状态不变。

广播组：同时激活多个 Agent#

广播组允许同一条消息同时触发多个 Agent 响应：

{
  "broadcast": {
    "strategy": "parallel",
    "120363403215116621@g.us": ["alfred", "baerbel"],
    "+15555550123": ["support", "logger"]
  }
}

适用场景：

• 一个 Agent 负责回答用户，另一个 Agent 静默记录对话日志
• 多语言群组中不同 Agent 用不同语言回复
• 支持 + 监控双 Agent 并行运行

多平台群组支持#

mentionPatterns 不只适用于 WhatsApp，Telegram、Discord、Slack、iMessage 也支持：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "groupChat": {
          "mentionPatterns": ["@?myclawd", "claude", "助手"]
        }
      }
    ]
  }
}

全局回退配置（所有 Agent 共用）：

{
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@?openclaw"]
    }
  }
}

常见问题#

群里发消息但 Bot 不响应？

1. 检查 groupPolicy 是否为 allowlist 且群组 JID 未加入白名单
2. 确认 requireMention: true 时是否真的 @了 Bot
3. 检查 mentionPatterns 是否与实际显示名称匹配
4. 用 --verbose 启动 Gateway 查看日志

心跳消息刷到群里？ OpenClaw 对群组会话跳过心跳检测，如果仍收到无关消息，检查是否配置了错误的定时任务或广播逻辑。

原文：Group Messages - OpenClaw | 来源：OpenClaw 官方文档