群组

OpenClaw 在各渠道中以一致的方式处理群聊：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams、Zalo。

新手入门（2 分钟）

OpenClaw "住"在你自己的消息账号里。没有单独的 WhatsApp Bot 用户。如果你在一个群组里，OpenClaw 就能看到并在那个群里回复。

默认行为：

群组受到限制（groupPolicy: "allowlist"）
回复需要 @提及，除非你明确禁用提及门控

简言之：白名单内的发送者 @提及 OpenClaw 后，它才会回复。

要点
私信访问由 *.allowFrom 控制
群组访问由 *.groupPolicy + 白名单（*.groups、*.groupAllowFrom）控制
回复触发由提及门控（requireMention、/activation）控制

群组消息处理流程：

groupPolicy 为 disabled -> 丢弃
groupPolicy 为 allowlist -> 群组不在允许列表中 -> 丢弃
requireMention 为 yes -> 未被提及 -> 仅存入上下文
否则 -> 回复

如果你想要……

目标	配置方式
允许所有群组但只在 @提及时回复	`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）

可以——这在你的"个人"流量是私信、"公开"流量是群组时效果很好。

原因：单 Agent 模式下，私信通常落入主会话（agent:main:main），而群组始终使用非主会话（agent:main:<channel>:group:<id>）。如果你以 mode: "non-main" 启用沙箱，这些群组会话在 Docker 中运行，而主私信会话保持在宿主机上。

这样你就有一个 Agent "大脑"（共享工作区 + 记忆），但两种执行态：

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

如果你需要真正独立的工作区/人格（"个人"和"公开"绝对不能混用），请使用第二个 Agent + bindings。参见多 Agent 路由。

示例（私信在宿主机，群组沙箱化 + 仅限消息类工具）：

json5

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // 群组/频道是非主会话 -> 沙箱化
        scope: "session", // 最强隔离（每个群组/频道一个容器）
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // 若 allow 非空，其他均被拦截（deny 仍优先生效）
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

想要"群组只能访问 X 目录"而非"禁止所有宿主访问"？保持 workspaceAccess: "none" 并仅将允许的路径挂载到沙箱：

json5

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // hostPath:containerPath:mode
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

显示标签

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

群组策略

按渠道控制群组/房间消息的处理方式：

json5

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // Telegram 用户数字 ID（向导可解析 @username）
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["user@org.com"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: { channels: { help: { allow: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
    },
  },
}

策略	行为
`"open"`	群组绕过白名单；提及门控仍然生效
`"disabled"`	完全屏蔽所有群组消息
`"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 白名单
群组私信分开控制（channels.discord.dm.*、channels.slack.dm.*）
Telegram 白名单可匹配用户 ID（"123456789"、"telegram:123456789"、"tg:123456789"）或用户名（"@alice" 或 "alice"）；前缀不区分大小写
默认为 groupPolicy: "allowlist"；若群组白名单为空，则群组消息被拦截
运行时安全：当提供商块完全缺失（channels.<provider> 不存在）时，群组策略回退为故障关闭模式（通常为 allowlist），而非继承 channels.defaults.groupPolicy

群组消息评估顺序的心智模型：

groupPolicy（open/disabled/allowlist）
群组白名单（*.groups、*.groupAllowFrom、渠道专属白名单）
提及门控（requireMention、/activation）

提及门控（默认）

群组消息默认需要提及，除非按群组覆盖。默认值位于各子系统的 *.groups."*" 下。

回复 Bot 的消息算作隐式提及（当渠道支持回复元数据时）。适用于 Telegram、WhatsApp、Slack、Discord 和 Microsoft Teams。

json5

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { requireMention: false },
      },
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false },
      },
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}

注意事项：

mentionPatterns 为不区分大小写的安全正则表达式；无效模式和不安全的嵌套重复形式会被忽略
提供显式提及的渠道仍可正常通过；模式是备用方案
按 Agent 覆盖：agents.list[].groupChat.mentionPatterns（多个 Agent 共享一个群组时很有用）
提及门控仅在提及检测可行时生效（原生提及或已配置 mentionPatterns）
Discord 默认值位于 channels.discord.guilds."*"（可按 guild/channel 覆盖）
群组历史上下文在各渠道中统一包装，且仅限挂起消息（因提及门控被跳过的消息）；使用 messages.groupChat.historyLimit 设置全局默认，使用 channels.<channel>.historyLimit（或 channels.<channel>.accounts.*.historyLimit）按渠道覆盖；设为 0 禁用

群组/频道工具限制（可选）

部分渠道配置支持限制特定群组/房间/频道内可用的工具。

tools：为整个群组设置工具 allow/deny
toolsBySender：群组内按发送者覆盖使用明确的键前缀： id:<senderId>、e164:<phone>、username:<handle>、name:<displayName>，以及 "*" 通配符旧版无前缀键仍被接受，仅匹配 id:

解析顺序（最具体优先）：

群组/频道 toolsBySender 匹配
群组/频道 tools
默认（"*"）toolsBySender 匹配
默认（"*"）tools

示例（Telegram）：

json5

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "id:123456789": { alsoAllow: ["exec"] },
          },
        },
      },
    },
  },
}

注意事项：

群组/频道工具限制在全局/Agent 工具策略之外额外生效（deny 仍然优先）
部分渠道对房间/频道使用不同的嵌套方式（如 Discord 的 guilds.*.channels.*、Slack 的 channels.*、Microsoft Teams 的 teams.*.channels.*）

群组白名单

当 channels.whatsapp.groups、channels.telegram.groups 或 channels.imessage.groups 已配置时，其键充当群组白名单。使用 "*" 允许所有群组同时设置默认提及行为。

常用配置（复制即用）：

禁用所有群组回复

json5

{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}

仅允许特定群组（WhatsApp）

json5

{
  channels: {
    whatsapp: {
      groups: {
        "123@g.us": { requireMention: true },
        "456@g.us": { requireMention: false },
      },
    },
  },
}

允许所有群组但显式要求提及

json5

{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

仅群主可在群组中触发（WhatsApp）

json5

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

激活（仅群主）

群主可切换按群组的激活模式：

/activation mention
/activation always

群主由 channels.whatsapp.allowFrom 确定（未配置时使用 Bot 自身的 E.164 号码）。将命令作为独立消息发送。其他渠道目前忽略 /activation。

上下文字段

群组入站载荷包含：

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

渠道专属说明：

BlueBubbles 可选择在正常群组门控通过后，从本地 macOS 通讯录数据库为无名称的群组参与者补充 GroupMembers。默认关闭。

Agent 系统提示在新群组会话的第一轮包含一段群组说明，提醒模型像人类一样回复、避免 Markdown 表格，以及避免输入字面量 \n 序列。

iMessage 专项说明

路由或白名单时优先使用 chat_id:<id>
列出聊天：imsg chats --limit 20
群组回复始终回到相同的 chat_id

WhatsApp 专项说明

WhatsApp 专属行为（历史注入、提及处理详情）参见群组消息。

群组 ​

新手入门（2 分钟） ​

会话密钥 ​

模式：个人私信 + 公开群组（单 Agent） ​

显示标签 ​

群组策略 ​

提及门控（默认） ​

群组/频道工具限制（可选） ​

群组白名单 ​

激活（仅群主） ​

上下文字段 ​

iMessage 专项说明 ​

WhatsApp 专项说明 ​

群组

新手入门（2 分钟）

会话密钥

模式：个人私信 + 公开群组（单 Agent）

显示标签

群组策略

提及门控（默认）

群组/频道工具限制（可选）

群组白名单

激活（仅群主）

上下文字段

iMessage 专项说明

WhatsApp 专项说明