群组 - OpenClaw

OpenClaw 在支持群组的渠道中统一应用相同的群组规则，包括 Discord、iMessage、Matrix、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp 和 Zalo。对于应始终开启、仅提供安静上下文，除非智能体明确发送可见消息的房间，请参阅环境房间事件。

新手简介（2 分钟）

OpenClaw“存在”于你自己的消息账户中。它没有单独的 WhatsApp Bot 用户：如果你在某个群组中，OpenClaw 就能看到该群组并在其中回复。默认行为：

群组受到限制（groupPolicy: "allowlist"）；群组发送者在加入允许列表之前会被阻止。
回复需要提及，除非你为某个群组禁用提及门控。
最终回复文本会自动发布到房间（visibleReplies: "automatic"）。

换句话说：允许列表中的发送者可以通过提及 OpenClaw 来触发它。

简而言之

私信访问权限由 *.allowFrom 控制。
群组访问权限由 *.groupPolicy + 允许列表（*.groups、*.groupAllowFrom）控制。
回复触发由提及门控（requireMention、/activation）控制。

快速流程（群组消息的处理过程）：

groupPolicy？disabled -> 丢弃
groupPolicy？allowlist -> 群组是否允许？否 -> 丢弃
requireMention？yes -> 是否提及？否 -> 仅存储为上下文
提及/回复/命令/私信 -> 用户请求
始终开启的群组闲聊 -> 用户请求，或配置后作为房间事件

可见回复

对于普通的群组/渠道请求，OpenClaw 默认为 messages.groupChat.visibleReplies: "automatic"：最终的助手文本会作为可见回复发布到房间。当共享房间应让智能体通过调用 message(action=send) 自行决定何时发言时，请使用 messages.groupChat.visibleReplies: "message_tool"。此模式最适合能可靠使用工具的模型（例如 GPT-5.6 Sol）。如果模型未调用该工具并返回了实质性的最终文本，OpenClaw 会将该文本保留为私密内容，而不是发布到房间。对于无法可靠遵循仅通过工具交付要求的模型或运行时，请使用 "automatic"：普通的最终文本会直接发布到房间，智能体仍可调用 message(action=send) 来发送无法随最终文本一起交付的文件、图像或其他附件。如果当前工具策略不允许使用消息工具，OpenClaw 会回退到自动发送可见回复，而不是静默抑制响应。openclaw doctor 会对此不匹配情况发出警告。对于直接聊天和任何其他来源事件，messages.visibleReplies: "message_tool" 会在全局应用相同的仅工具行为；messages.groupChat.visibleReplies 仍是针对群组/渠道房间的更具体覆盖设置。内部 WebChat 直接轮次默认自动交付最终回复，使 Pi 和 Codex 获得相同的可见回复契约。仅工具模式取代了旧有做法，即强制模型在大多数潜水模式轮次中回答 NO_REPLY。在仅工具模式下，提示词不会定义 NO_REPLY 契约；不产生任何可见内容只意味着不调用消息工具。插件拥有的对话绑定属于例外。插件绑定线程并接管入站轮次后，插件返回的回复就是可见的绑定响应；它不需要 message(action=send)。该回复是插件运行时输出，而不是模型的私密最终文本。对于直接群组请求，仍会发送输入状态指示器。启用后，环境式始终开启房间事件会保持严格且安静，除非智能体调用消息工具。会话默认抑制详细的工具/进度摘要。调试时，使用 /verbose on（或 /verbose full）为当前会话显示这些摘要，使用 /verbose off 恢复为仅显示最终回复的行为。详细状态按会话设置，并且在直接聊天、群组、渠道和论坛主题中的行为相同。若要将未提及智能体的始终开启群组闲聊作为安静的房间上下文提交，而不是作为用户请求，请使用环境房间事件：

{
  messages: {
    groupChat: {
      unmentionedInbound: "room_event",
    },
  },
}

默认值为 unmentionedInbound: "user_request"。包含提及的消息、命令、中止请求和私信仍属于用户请求。若要要求群组/渠道请求的可见输出必须通过消息工具发送：

{
  messages: {
    groupChat: {
      visibleReplies: "message_tool",
    },
  },
}

若要对每个来源聊天实施此要求：

{
  messages: {
    visibleReplies: "message_tool",
  },
}

文件保存后，Gateway 网关无需重启即可采用 messages 配置更改。仅在禁用配置重新加载（gateway.reload.mode: "off"）时才需要重启。命令轮次会绕过 visibleReplies: "message_tool"，并始终以可见方式回复：原生斜杠命令（Discord、Telegram 以及其他支持原生命令的界面）和已授权的文本 /... 命令都会将响应发布到来源聊天。群组中未授权的文本 /... 轮次仍仅通过消息工具处理；普通聊天轮次遵循配置的默认值。

上下文可见性和允许列表

群组安全涉及两种不同的控制：

触发授权：谁可以触发智能体（groupPolicy、groups、groupAllowFrom、渠道专用允许列表）。
上下文可见性：哪些补充上下文会注入模型（回复/引用文本、线程历史记录、转发元数据）。

默认情况下，OpenClaw 会按收到时的原样保留上下文：允许列表决定谁能触发操作，而不是决定模型可以看到哪些引用内容或历史片段。若还要过滤补充上下文，请设置 contextVisibility：

模式	行为
`"all"`（默认）	按收到时的原样保留补充上下文。
`"allowlist"`	仅注入来自允许列表发送者的历史记录/线程/引用/转发上下文。
`"allowlist_quote"`	`allowlist`，并保留从任何发送者处明确引用或回复的消息。

可按渠道（channels.<channel>.contextVisibility）、按账户（channels.<channel>.accounts.<accountId>.contextVisibility）或全局（channels.defaults.contextVisibility）设置。获取补充上下文的渠道（Discord、Feishu、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp）会在构建入站上下文时应用该策略；未知的策略组合会采用故障关闭方式并省略上下文。这些模式仅过滤渠道提供的补充上下文。工具策略和仅所有者可用的工具清单仍根据当前轮次的原始请求者选择，而不是根据提示词中出现的每个发送者选择。请参阅请求者范围的控制和提示词上下文。

如果你希望……

目标	要设置的内容
允许所有群组，但仅在 @提及时回复	`groups: { "*": { requireMention: true } }`
禁用所有群组回复	`groupPolicy: "disabled"`
仅允许特定群组	`groups: { "<group-id>": { ... } }`（无 `"*"` 键）
仅你可以在群组中触发智能体	`groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]`
跨渠道复用一组受信任发送者	`groupAllowFrom: ["accessGroup:operators"]`

有关可复用的发送者允许列表，请参阅访问组。

会话键

群组会话使用 agent:<agentId>:<channel>:group:<id> 会话键（房间/渠道使用 agent:<agentId>:<channel>:channel:<id>）。
Telegram 论坛主题会将 :topic:<threadId> 添加到群组 ID，使每个主题都有自己的会话。
直接聊天使用主会话（如果配置了 session.dmScope，则使用按发送者划分的会话）。
Heartbeat 在配置的 Heartbeat 会话中运行（默认：智能体主会话）；群组会话不会运行自己的 Heartbeat。

模式：个人私信 + 公共群组（单个智能体）

可以——如果你的“个人”流量是私信，而“公共”流量是群组，这种模式会很有效。原因是：在单智能体模式下，私信通常进入主会话键（agent:main:main），而群组始终使用非主会话键（agent:main:<channel>:group:<id>）。如果使用 mode: "non-main" 启用沙箱隔离，这些群组会话会在配置的沙箱后端中运行，而你的主私信会话仍在主机上运行。如果未选择后端，则默认使用 Docker。这样你会拥有一个智能体“大脑”（共享工作区 + 记忆），但有两种执行方式：

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

如果需要真正独立的工作区/角色设定（“个人”和“公共”绝不能混合），请使用第二个智能体 + 绑定。请参阅多智能体路由。

私信在主机上运行，群组在沙箱中运行
群组仅能看到允许列表中的文件夹

{
  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"，并仅将允许列表中的路径挂载到沙箱：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: [
            // 主机路径:容器路径:模式
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

显示标签

UI 标签会在可用时使用 displayName，格式为 <channel>:<token>。
#room 保留用于房间/渠道；群聊使用 g-<slug>（小写，空格 -> -，保留 #@+._-）。特别长的不透明 ID 会缩短为稳定令牌，以避免在 UI 中泄露完整的路由 ID。

群组策略

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

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // Telegram 数字用户 ID（设置时会将 @username 解析为 ID）
    },
    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: { enabled: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { enabled: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

策略	行为
`"open"`	群组绕过允许列表；提及门控仍然适用。
`"disabled"`	完全阻止所有群组消息。
`"allowlist"`	仅允许与已配置允许列表匹配的群组/房间。

各渠道说明

groupPolicy 与提及门控（要求 @提及）相互独立。
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo：使用 groupAllowFrom（回退：显式 allowFrom）。
Signal：groupAllowFrom 可以匹配入站 Signal 群组 ID 或发送者的电话号码/UUID。
私信配对审批（*-allowFrom 存储条目）仅适用于私信访问；群组发送者授权仍须在群组允许列表中明确配置。
Discord：允许列表使用 channels.discord.guilds.<id>.channels。
Slack：允许列表使用 channels.slack.channels。
Matrix：允许列表使用 channels.matrix.groups。使用房间 ID（!room:server）或别名（#alias:server）；仅当配置了 channels.matrix.dangerouslyAllowNameMatching: true 时，房间名称键才会匹配，无法解析的条目在运行时会被忽略。使用 channels.matrix.groupAllowFrom 限制发送者；也支持每个房间的 users 允许列表。
群组私信单独控制（channels.discord.dm.*、channels.slack.dm.*：groupEnabled、groupChannels）。
Telegram：发送者允许列表仅接受数字用户 ID（"123456789"；telegram:/tg: 前缀会以不区分大小写的方式移除）。@username 条目在运行时不匹配并会记录警告；设置时会将 @username 解析为 ID。负数聊天 ID 应放在 channels.telegram.groups 下，而不是发送者允许列表中。
默认值为 groupPolicy: "allowlist"；如果群组允许列表为空，群组消息会被阻止。
运行时安全：当提供商配置块完全缺失（不存在 channels.<provider>）时，群组策略会以失败关闭方式设为 allowlist，而不是继承 channels.defaults.groupPolicy，并且 Gateway 网关会为每个账号记录一次该回退。

快速理解模型（群组消息的评估顺序）：

groupPolicy

groupPolicy（open/disabled/allowlist）。

群组允许列表

群组允许列表（*.groups、*.groupAllowFrom、渠道特定的允许列表）。

提及门控

提及门控（requireMention、/activation）。

提及门控（默认）

除非按群组覆盖，否则群组消息必须包含提及。默认值位于每个子系统的 *.groups."*" 下。支持的隐式提及事实因渠道而异：

事实	当前内置生成方
回复 Bot	Discord、Microsoft Teams、QQ Bot、Slack、Telegram
引用 Bot	WhatsApp、Zalo Personal
Bot 加入话题	Mattermost、Slack、Tlon

渠道生成的每项事实默认启用。将对应的 implicitMentions 标志设为 false，可阻止该事实绕过提及门控；原生显式提及不受影响。对于不生成该事实的渠道，此标志不起作用。

{
  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: {
    entries: {
      main: {
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    },
  },
}

限定已配置提及模式的范围

已配置的 mentionPatterns 是正则表达式回退触发器。当平台不提供原生 Bot 提及，或希望将 openclaw: 之类的纯文本视为提及时，请使用这些模式。原生平台提及与此独立：当 Discord、Slack、Telegram、Matrix、Signal 或其他渠道可以确定消息明确提及了 Bot 时，即使已配置的正则表达式模式被拒绝，该原生提及仍会触发。默认情况下，只要渠道将提供商和会话事实传入提及检测，已配置的提及模式就会生效。为避免宽泛模式唤醒每个群组中的智能体，请使用 channels.<channel>.mentionPatterns 按渠道限定其范围。当某个渠道应默认关闭正则表达式提及模式，并通过 allowIn 为特定房间启用时，请使用 mode: "deny"：

{
  messages: {
    groupChat: {
      mentionPatterns: ["\\bopenclaw\\b", "\\bops bot\\b"],
    },
  },
  channels: {
    slack: {
      mentionPatterns: {
        mode: "deny",
        allowIn: ["C0123OPS"],
      },
    },
  },
}

当正则表达式提及模式应广泛应用时，请使用默认的 mode: "allow"（或省略 mode），然后使用 denyIn 在嘈杂的房间中将其关闭：

{
  messages: {
    groupChat: {
      mentionPatterns: ["\\bopenclaw\\b"],
    },
  },
  channels: {
    telegram: {
      mentionPatterns: {
        denyIn: ["-1001234567890", "-1001234567890:topic:42"],
      },
    },
  },
}

策略解析：

字段	效果
`mode: "allow"`	除非会话 ID 位于 `denyIn` 中，否则启用正则表达式提及模式。这是默认设置。
`mode: "deny"`	除非会话 ID 位于 `allowIn` 中，否则禁用正则表达式提及模式。
`allowIn`	在拒绝模式下启用正则表达式提及模式的会话 ID。
`denyIn`	禁用正则表达式提及模式的会话 ID。如果二者包含相同 ID，`denyIn` 优先于 `allowIn`。

目前支持的范围限定正则表达式策略：

渠道	`allowIn` / `denyIn` 中使用的 ID
Discord	Discord 频道 ID。
Matrix	Matrix 房间 ID。
Slack	Slack 频道 ID。
Telegram	群聊 ID，或论坛话题的 `chatId:topic:threadId`。
WhatsApp	WhatsApp 会话 ID，例如 `123@g.us`。

当渠道支持多个账号时，账号级渠道配置可在 channels.<channel>.accounts.<accountId>.mentionPatterns 下设置相同策略。对于该账号，账号策略优先于顶层渠道策略。

提及门控说明

mentionPatterns 是不区分大小写的安全正则表达式模式；无效模式和不安全的嵌套重复形式会被忽略（并记录警告）。
模式优先级：agents.entries.*.groupChat.mentionPatterns（多个智能体共享群组时很有用）覆盖 messages.groupChat.mentionPatterns；两者均未设置时，模式根据智能体身份的名称/表情符号生成。
仅当可以进行提及检测时（存在原生提及或已配置 mentionPatterns），才会执行提及门控。
将群组或发送者加入允许列表不会禁用提及门控；当所有消息都应触发时，请将该群组的 requireMention 设为 false。
自动群聊提示上下文会在每轮中携带解析后的静默回复指令；工作区文件不应重复 NO_REPLY 机制。
允许自动静默回复的群组会将完全为空或仅含推理的模型轮次视为静默，等同于 NO_REPLY。直接聊天永远不会收到 NO_REPLY 指引，仅使用消息工具的群组回复则通过不调用 message(action=send) 保持安静。
始终开启的环境群组闲聊默认使用用户请求语义。将 messages.groupChat.unmentionedInbound: "room_event" 设为以安静上下文形式提交。有关设置示例，请参阅环境房间事件。
房间事件不会存储为虚假用户请求，来自未使用消息工具的房间事件的私有助手文本也不会作为聊天历史重放。
Discord 默认值位于 channels.discord.guilds."*" 中（可按服务器/频道覆盖）。
群组历史上下文在各渠道中采用统一封装。启用提及门控的群组会保留待处理的已跳过消息；当渠道支持时，始终开启的群组还可能保留最近处理的房间消息。使用 messages.groupChat.historyLimit 设置全局默认值，并使用 channels.<channel>.historyLimit（或 channels.<channel>.accounts.*.historyLimit）进行覆盖。设为 0 可禁用。

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

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

tools：允许/拒绝整个群组使用工具（allow、alsoAllow、deny；拒绝优先）。
toolsBySender：群组内按发送者覆盖。使用显式键前缀：channel:<channelId>:<senderId>、id:<senderId>、e164:<phone>、username:<handle>、name:<displayName> 和 "*" 通配符。渠道 ID 使用规范的 OpenClaw 渠道 ID；teams 等别名会规范化为 msteams。仍接受旧版无前缀键，但仅按 id: 匹配，并会记录弃用警告。

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

群组 toolsBySender

匹配群组/渠道 toolsBySender。

群组 tools

群组/渠道 tools。

默认 toolsBySender

匹配默认（"*"）toolsBySender。

默认 tools

默认（"*"）tools。

示例（Telegram）：

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

群组/渠道工具限制会在全局/智能体工具策略之外额外应用（拒绝规则仍优先）。部分渠道对房间/频道采用不同的嵌套结构（例如 Discord guilds.*.channels.*、Slack channels.*、Microsoft Teams teams.*.channels.*）。

群组允许列表

配置 channels.whatsapp.groups、channels.telegram.groups 或 channels.imessage.groups 后，其中的键将作为群组允许列表。使用 "*" 可允许所有群组，同时仍可设置默认的提及行为。

常见误区：私信配对批准与群组授权并不相同。对于支持私信配对的渠道，配对存储仅会解锁私信。群组命令仍需通过配置允许列表明确授权群组发送者，例如 groupAllowFrom，或该渠道文档中说明的配置回退方案。

常见配置意图（可复制/粘贴）：

禁用所有群组回复
仅允许特定群组（WhatsApp）
允许所有群组，但要求提及
仅所有者可触发（WhatsApp）

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

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

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

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

激活（仅限所有者）

群组所有者可通过单独发送以下消息，切换各群组的激活状态：

/activation mention
/activation always

/activation 是受核心所有者权限控制的命令，仅适用于群聊。所有者是指发送者与 commands.ownerAllowFrom 匹配；渠道 allowFrom 列表仅控制普通渠道和命令访问权限。对于会读取所存模式的渠道（Google Chat、QQ Bot、Telegram、WhatsApp），该模式会覆盖相应群组的 requireMention；所有渠道中的群组系统提示词引言都会反映当前激活的模式。

上下文字段

群组入站载荷会设置：

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

在新群组会话的首轮（以及 /activation 更改后），智能体系统提示词会包含群组引言。它会提醒模型像人一样回复、尽量减少空行并遵循正常的聊天间距，同时避免键入字面量 \n 序列。对于声明的表格模式无法保留原生表格或原始表格的渠道，还会劝阻使用 Markdown 表格。来自渠道的群组名称和参与者标签会呈现为围栏包裹的不受信任元数据，而不是内联系统指令。

iMessage 细节

进行路由或允许列表配置时，优先使用 chat_id:<id>。
列出聊天：imsg chats --limit 20。
群组回复始终发回同一 chat_id。

WhatsApp 系统提示词

有关规范的 WhatsApp 系统提示词规则，请参阅 WhatsApp，其中包括群组和私聊提示词解析、通配符行为及账户覆盖语义。

WhatsApp 细节

有关仅适用于 WhatsApp 的行为（历史记录注入、提及处理细节），请参阅群组消息。

概览

消息平台

Developer and self-hosted

Regional platforms

配置

群组

新手简介（2 分钟）

可见回复

上下文可见性和允许列表

会话键

模式：个人私信 + 公共群组（单个智能体）

显示标签

群组策略

提及门控（默认）

限定已配置提及模式的范围

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

群组允许列表

激活（仅限所有者）

上下文字段

iMessage 细节

WhatsApp 系统提示词

WhatsApp 细节

相关内容

​新手简介（2 分钟）

​可见回复

​上下文可见性和允许列表

​会话键

​模式：个人私信 + 公共群组（单个智能体）

​显示标签

​群组策略

​提及门控（默认）

​限定已配置提及模式的范围

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

​群组允许列表

​激活（仅限所有者）

​上下文字段

​iMessage 细节

​WhatsApp 系统提示词

​WhatsApp 细节

​相关内容

新手简介（2 分钟）

可见回复

上下文可见性和允许列表

会话键

模式：个人私信 + 公共群组（单个智能体）

显示标签

群组策略

提及门控（默认）

限定已配置提及模式的范围

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

群组允许列表

激活（仅限所有者）

上下文字段

iMessage 细节

WhatsApp 系统提示词

WhatsApp 细节

相关内容