群组

OpenClaw 在各个平台上以一致的方式处理群聊:WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams。

新手入门(2 分钟)

OpenClaw "存在"于您自己的消息账号上。没有单独的 WhatsApp 机器人用户。如果您在一个群组中,OpenClaw 就能看到该群组并在那里回复。

默认行为:

群组是受限的(groupPolicy: "allowlist")。
回复需要提及,除非您明确禁用提及限制。

含义:允许列表中的发送者可以通过提及来触发 OpenClaw。

核心要点
私聊访问由 *.allowFrom 控制。
群组访问由 *.groupPolicy + 允许列表(*.groups、*.groupAllowFrom)控制。
回复触发由提及限制(requireMention、/activation)控制。

快速流程(群组消息的处理过程):

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
otherwise -> reply

群组消息流程

如果您想要...

目标	设置内容
允许所有群组但仅在 @ 提及时回复	`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:main:main),而群组始终使用非主会话键(agent:main:<channel>:group:<id>)。如果您启用沙箱并设置 mode: "non-main",这些群组会话将在 Docker 中运行,而主私聊会话保持在主机上。

这为您提供了一个代理"大脑"(共享工作区 + 记忆),但两种执行姿态:

私聊:完整工具(主机)
群组:沙箱 + 受限工具(Docker)

如果您需要真正独立的工作区/角色("个人"和"公共"绝不能混合),请使用第二个代理 + 绑定。参见多代理路由。

示例(私聊在主机上,群组沙箱化 + 仅消息工具):

json5

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // groups/channels are non-main -> sandboxed
        scope: "session", // strongest isolation (one container per group/channel)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // If allow is non-empty, everything else is blocked (deny still wins).
        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
            "~/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", "@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:使用 groupAllowFrom(回退:显式 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";如果群组允许列表为空,群组消息将被阻止。

快速思维模型(群组消息的评估顺序):

groupPolicy(开放/禁用/允许列表)
群组允许列表(*.groups、*.groupAllowFrom、特定频道允许列表)
提及限制(requireMention、/activation)

提及限制(默认)

群组消息需要提及,除非按群组覆盖。默认值在 *.groups."*" 下的每个子系统中。

回复机器人消息算作隐式提及(当频道支持回复元数据时)。这适用于 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 是不区分大小写的正则表达式。
提供显式提及的平台仍然通过;模式是回退方案。
按代理覆盖:agents.list[].groupChat.mentionPatterns(当多个代理共享群组时有用)。
提及限制仅在可以检测提及时强制执行(原生提及或配置了 mentionPatterns)。
Discord 默认值在 channels.discord.guilds."*" 中(可按服务器/频道覆盖)。
群组历史上下文在各频道统一包装,并且仅限待处理(由于提及限制而跳过的消息);使用 messages.groupChat.historyLimit 作为全局默认值,使用 channels.<channel>.historyLimit(或 channels.<channel>.accounts.*.historyLimit) 进行覆盖。设置 0 以禁用。

群组/频道工具限制(可选)

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

tools:整个群组的允许/拒绝工具。
toolsBySender:群组内按发送者覆盖(键是发送者 ID/用户名/邮箱/电话号码,取决于频道)。使用 "*" 作为通配符。

解析顺序(最具体的优先):

群组/频道 toolsBySender 匹配
群组/频道 tools
默认("*") toolsBySender 匹配
默认("*") tools

示例(Telegram):

json5

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

注意事项:

群组/频道工具限制在全局/代理工具策略之上应用(拒绝仍然优先)。
某些频道对房间/频道使用不同的嵌套(例如,Discord guilds.*.channels.*、Slack channels.*、MS 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 确定(或未设置时使用机器人自身的 E.164)。作为独立消息发送命令。其他平台目前忽略 /activation。

上下文字段

群组入站负载设置:

ChatType=group
GroupSubject(如果已知)
GroupMembers(如果已知)
WasMentioned(提及限制结果)
Telegram 论坛主题还包括 MessageThreadId 和 IsForum。

代理系统提示在新群组会话的第一轮包含群组介绍。它提醒模型像人类一样回复,避免 Markdown 表格,并避免输入字面的 \n 序列。

iMessage 特性

路由或允许列表时优先使用 chat_id:<id>。
列出聊天:imsg chats --limit 20。
群组回复始终返回到相同的 chat_id。

WhatsApp 特性

有关 WhatsApp 专属行为(历史注入、提及处理详情),请参见群组消息。

群组 ​

新手入门(2 分钟) ​

会话键 ​

模式:个人私聊 + 公共群组(单一代理) ​

显示标签 ​

群组策略 ​

提及限制(默认) ​

群组/频道工具限制(可选) ​

群组允许列表 ​

激活(仅所有者) ​

上下文字段 ​

iMessage 特性 ​

WhatsApp 特性 ​

群组

新手入门(2 分钟)

会话键

模式:个人私聊 + 公共群组(单一代理)

显示标签

群组策略

提及限制(默认)

群组/频道工具限制(可选)

群组允许列表

激活(仅所有者)

上下文字段

iMessage 特性

WhatsApp 特性