群组

OpenClaw 在所有支持群组的频道上应用相同的群组规则，包括 Discord、iMessage、Matrix、Microsoft Teams、QQBot、Signal、Slack、Telegram、WhatsApp 和 Zalo。

对于应当提供安静上下文、除非代理明确发送可见消息的常开房间，请参阅环境房间事件。

新手入门（2 分钟）¶

OpenClaw “运行”在你自己的消息账户上。没有单独的 WhatsApp 机器人用户：如果你在某个群组中，OpenClaw 就能看到该群组并在那里回复。

默认行为：

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

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

快速流程（群组消息会发生什么）：

groupPolicy? disabled -> drop
groupPolicy? allowlist -> group allowed? no -> drop
requireMention? yes -> mentioned? no -> store for context only
mention/reply/command/DM -> user request
always-on group chatter -> user request, or room event when configured

机器人创建的线程¶

使用 requireMentionInBotThreads 仅在接收机器人创建的线程或主题中覆盖提及门控：

• false 接受已确认的机器人创建线程中未提及的后续消息。
• true 在那里要求提及，即使房间通常接受所有消息。仅回复、引用和过去的机器人参与不满足该要求；原生提及、已配置的提及模式和授权命令保留其正常行为。
• 省略时保留频道现有的提及和隐式回复行为。

例如，保持 Discord 父频道启用提及门控，同时开放机器人自己的线程，并对 Slack 应用相同策略。将这些字段合并到你现有的频道配置中，保留其凭据和允许列表：

{
  channels: {
    discord: {
      intents: { messageContent: true },
      guilds: {
        "123456789012345678": {
          requireMention: true,
          requireMentionInBotThreads: false,
        },
      },
    },
    slack: {
      requireMention: true,
      requireMentionInBotThreads: false,
    },
  },
}

该设置使用每个频道现有的配置范围；账户范围配置在支持时使用 accounts.<id> 下的对应路径。要进行更窄范围的更改，请在现有允许的频道条目上设置该选项。参见 Discord 示例 和 Slack 示例。

未知或不可用的所有权保留普通提及规则。现有有界缓存可能丢失旧的所有权证据；请参阅频道文档了解其限制。机器人在他人的线程中回复不会使其成为创建者。发送者、频道和机器人访问限制仍然适用。显式会话绑定保留其自身的路由激活规则。

这些规则管理新消息的准入。已被接受的回合保留其捕获的策略；更改提及规则或发送者允许列表不会抑制其回复。

传输层必须先传递未提及的消息，OpenClaw 才能应用该策略：

• Discord 需要在开发者门户和 OpenClaw 账户配置中都启用 Message Content Intent。
• Microsoft Teams 需要 ChannelMessage.Read.Group RSC 权限。
• Slack 需要频道成员身份以及匹配的 message.channels 或 message.groups 事件订阅。
• Telegram 需要禁用隐私模式或群组管理员状态。

当前 Google Chat 交互 webhook 不提供普通未提及的空间消息或线程所有者元数据，因此不会暴露此选项。仅提供引用、直接对话或没有原生线程的渠道也会保留其现有提及行为。外部插件需要实现共享的线程提及策略。

可见回复¶

对于普通群组/频道请求，OpenClaw 默认使用 messages.groupChat.visibleReplies: "automatic"：最终助手文本会作为可见回复发布到房间。

当可见答案必须通过 message(action=send) 发送时，使用 messages.groupChat.visibleReplies: "message_tool"。这选择的是投递方式，而不是是否必须回复。它最适合能够可靠遵循仅工具投递的模型。如果模型遗漏工具并返回实质性最终文本，OpenClaw 会保持该文本私密，并尝试有界投递恢复，而不是直接发布。

对于不能可靠遵循仅工具投递的模型或运行时，使用 "automatic"：普通文本最终回复会直接发布到房间，并且代理仍可以调用 message(action=send) 来发送无法随最终文本一起携带的文件、图像或其他附件。

如果当前工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，而不是静默抑制响应。openclaw doctor 会警告此不匹配。

对于直接聊天和任何其他源事件，messages.visibleReplies: "message_tool" 会全局应用相同的仅工具行为；messages.groupChat.visibleReplies 仍然是针对群组/频道房间的更具体覆盖。内部 WebChat 直接回合默认使用自动最终回复投递，以便 Pi 和 Codex 获得相同的可见回复契约。

默认情况下，已接受的群组/频道请求需要回复。若要允许对未指向的请求选择性静默，请显式设置 agents.defaults.silentReply.group: "allow" 或相应的 surfaces.<id>.silentReply.group 覆盖；参见静默回复。在 "automatic" 模式下，该选择会启用 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",
  },
}

网关会在文件保存后无需重启即可获取 messages 配置更改。仅在配置重载被禁用（gateway.reload.mode: "off"）时才需要重启。

命令回合会绕过 visibleReplies: "message_tool" 并始终可见回复：原生斜杠命令（Discord、Telegram 以及其他支持原生命令的表面）和已授权的文本 /... 命令都会将其响应发布到源聊天。群组中未授权的文本 /... 回合保持仅消息工具；普通聊天回合遵循配置的默认值。

上下文可见性与允许列表¶

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

• 触发授权：谁可以触发代理（groupPolicy、groups、groupAllowFrom、渠道特定允许列表）。
• 上下文可见性：注入到模型中的补充上下文是什么（回复/引用文本、线程历史、转发元数据）。

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

可按渠道设置（channels.<channel>.contextVisibility）、按账户设置（channels.<channel>.accounts.<accountId>.contextVisibility）或全局设置（channels.defaults.contextVisibility）。获取补充上下文的渠道（Discord、Feishu、iMessage、Matrix、Mattermost、Microsoft Teams、QQBot、Signal、Slack、Telegram、WhatsApp）在构建入站上下文时应用该策略；未知策略组合会失败关闭并省略上下文。

这些模式仅过滤渠道提供的补充上下文。工具策略和仅限所有者的工具清单仍从当前回合的原始请求者选择，而不是提示中代表的每个发送者。参见请求者范围控制与提示上下文。

如果你想……

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

会话密钥¶

• 默认情况下，群组会话使用 agent:<agentId>:<channel>:group:<id> 会话密钥（房间/频道使用 agent:<agentId>:<channel>:channel:<id>）。
• Telegram 论坛话题会在群组 ID 后追加 :topic:<threadId>，使每个话题拥有自己的会话。
• 私聊使用主会话（如果配置了 session.dmScope，则使用按发送者划分的会话）。
• 心跳在已配置的心跳会话中运行（默认：代理主会话）；群组会话不会运行自己的心跳。

当可信房间需要共享代理的主对话时，将绑定的 session.groupScope 设置为 "main"：

{
  bindings: [
    {
      agentId: "main",
      match: { channel: "slack", peer: { kind: "channel", id: "C0123TEAM" } },
      session: { groupScope: "main" },
    },
  ],
}

全局 session.groupScope 支持 "per-group"（默认）或 "main"。 这不会改变群组准入、提及门控或回复路由。

模式：个人私信 + 公共群组（单代理）¶

是的——如果你的“个人”流量是 私信，而“公共”流量是 群组，这会很有效。

原因：在单代理模式下，私信通常会进入 主 会话密钥（agent:main:main），而群组在默认 groupScope: "per-group" 下使用 非主 会话密钥（agent:main:<channel>:group:<id>）。如果你使用 mode: "non-main" 启用沙箱，这些群组会话将在已配置的沙箱后端中运行，而你的主私信会话仍保留在主机上。如果你未选择后端，Docker 是默认后端。

这让你拥有一个代理“大脑”（共享工作区 + 内存），但有两种执行姿态：

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

{
  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"],
      },
    },
  },
}

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

相关：

• 配置键和默认值：网关配置
• 调试工具被阻止的原因：沙箱 vs 工具策略 vs 提升权限
• 绑定挂载详情：沙箱化

显示标签¶

• UI 标签在可用时使用 displayName，格式为 <channel>:<token>。
• #room 保留给房间/频道；群聊使用 g-<slug>（小写，空格 -> -，保留 #@+._-）。非常长的不透明 ID 会被缩短为稳定令牌，而不是将完整路由 ID 泄露到 UI 中。

群组策略¶

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

{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // numeric Telegram user id (setup resolves @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: { 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 },
      },
    },
  },
}

快速心智模型（群消息的评估顺序）：

1. groupPolicy

groupPolicy（open/disabled/allowlist）。

2. 群组允许列表

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

3. 提及门控

提及门控（requireMention、/activation）。

提及门控（默认）¶

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

支持的隐式提及事实因渠道而异：

当渠道产生该事实时，每个事实默认启用。在捆绑渠道中，LINE、Mattermost、Slack 和 Tlon 会读取对应的 implicitMentions 标志；将其设置为 false 可阻止该事实绕过提及门控。LINE 仅从共享的 channels.defaults.implicitMentions 块读取它；它不接受自己的渠道级或账户级 implicitMentions 块。原生显式提及不受影响。上述其他捆绑生产者目前不读取 implicitMentions，因此它们的事实始终算作提及，且该标志无法关闭它们。对于不产生该事实的渠道，该标志也没有效果。

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

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

已配置的 mentionPatterns 是正则回退触发器。当平台未暴露原生机器人提及时， 或当你希望像 openclaw: 这样的纯文本也算作提及时，使用它们。原生平台提及是独立的： 当 Discord、Slack、Telegram、Matrix、Signal 或其他渠道能够证明消息 明确提及了机器人时，即使已配置的正则模式被拒绝，该原生提及仍会触发。

默认情况下，已配置的提及模式适用于渠道将提供商和会话事实传入提及检测的所有位置。为避免宽泛模式在每个群组中唤醒代理，使用 channels.<channel>.mentionPatterns 按渠道限定它们。

当正则提及模式在某个渠道中应默认关闭时，使用 mode: "deny"，然后通过 allowIn 为特定房间选择加入：

{
  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"],
      },
    },
  },
}

策略解析：

| 字段 | 效果 |

当前支持的限定范围正则策略：

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

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

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

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

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

1. 群组 toolsBySender

群组/频道 toolsBySender 匹配。

2. 群组 tools

群组/频道 tools。

3. 默认 toolsBySender

默认（"*"）toolsBySender 匹配。

4. 默认 tools

默认（"*"）tools。

示例（Telegram）：

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

群组允许列表¶

当配置了 channels.whatsapp.groups、channels.telegram.groups 或 channels.imessage.groups 时，这些键会作为群组允许列表。使用 "*" 允许所有群组，同时仍可设置默认提及行为。

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

{
  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、QQBot、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 系统提示词规则，包括群组和直接提示词解析、通配符行为以及账户覆盖语义