OpenClaw 🦞

群组

群组

OpenClaw 跨表面一致地处理群组聊天：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams、Zalo。

初学者介绍（2 分钟）

OpenClaw"居住"在您自己的消息账户上。没有单独的 WhatsApp 机器人用户。 如果您在群组中，OpenClaw 可以看到该群组并在那里回复。

默认行为：

  • 群组受限（groupPolicy: "allowlist"）。
  • 除非您明确禁用提及门控，否则回复需要提及。

翻译：允许列表的发送者可以通过提及触发 OpenClaw。

太长不看

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

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

groupPolicy? disabled -> 丢弃
groupPolicy? allowlist -> 群组允许？否 -> 丢弃
requireMention? 是 -> 提及？否 -> 仅存储为上下文
否则 -> 回复

群组消息流程

如果您想要...

目标设置什么
允许所有群组但仅在 @提及时回复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>，因此每个主题都有自己的会话。
  • 直接聊天使用主会话（或每发送者如果配置）。
  • 心跳对群组会话跳过。

模式：个人 DM + 公共群组（单代理）

是的——如果您的"个人"流量是DM而您的"公共"流量是群组，这效果很好。

原因：在单代理模式下，DM 通常落在主会话键（agent:main:main），而群组总是使用非主会话键（agent:main:<channel>:group:<id>）。如果您启用沙盒化与 mode: "non-main"，这些群组会话在 Docker 中运行而您的主 DM 会话保留在主机上。

这给您一个代理"大脑"（共享工作区 + 内存），但两个执行姿态：

  • DM：完整工具（主机）
  • 群组：沙盒 + 受限工具（Docker）

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

示例（DM 在主机上，群组沙盒化 + 仅消息工具）：

{
  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: [
            // hostPath:containerPath:mode
            "/home/user/FriendsShared:/data:ro",
          ],
        },
      },
    },
  },
}

相关内容：

显示标签

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

群组策略

控制每个渠道如何处理群组/房间消息：

{
  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）。
  • DM 配对批准（*-allowFrom 存储条目）仅适用于 DM 访问；群组发送者授权保持对群组允许列表显式。
  • Discord：允许列表使用 channels.discord.guilds.<id>.channels。
  • Slack：允许列表使用 channels.slack.channels。
  • Matrix：允许列表使用 channels.matrix.groups（房间 ID、别名或名称）。使用 channels.matrix.groupAllowFrom 限制发送者；也支持每房间 users 允许列表。
  • 群组 DM 单独控制（channels.discord.dm.*、channels.slack.dm.*）。
  • Telegram 允许列表可以匹配用户 ID（"123456789"、"telegram:123456789"、"tg:123456789"）或用户名（"@alice" 或 "alice"）；前缀不区分大小写。
  • 默认是 groupPolicy: "allowlist"；如果您的群组允许列表为空，群组消息被阻止。
  • 运行时安全：当提供者块完全缺失（channels.<provider> 不存在）时，群组策略回退到故障关闭模式（通常是 allowlist）而不是继承 channels.defaults.groupPolicy。

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

  1. groupPolicy（open/disabled/allowlist）
  2. 群组允许列表（*.groups、*.groupAllowFrom、渠道特定允许列表）
  3. 提及门控（requireMention、/activation）

提及门控（默认）

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

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

{
  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:<senderId>、e164:<phone>、username:<handle>、name:<displayName> 和 "*" 通配符。 旧版无前缀键仍然被接受并仅匹配为 id:。

解析顺序（最具体获胜）：

  1. 群组/频道 toolsBySender 匹配
  2. 群组/频道 tools
  3. 默认（"*"）toolsBySender 匹配
  4. 默认（"*"）tools

示例（Telegram）：

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

注意：

  • 群组/频道工具限制应用于全局/代理工具策略之外（deny 仍然获胜）。
  • 一些渠道对房间/频道使用不同的嵌套（例如 Discord guilds.*.channels.*、Slack channels.*、MS Teams teams.*.channels.*）。

群组允许列表

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

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

  1. 禁用所有群组回复
{
  channels: { whatsapp: { groupPolicy: "disabled" } },
}
  1. 仅允许特定群组（WhatsApp）
{
  channels: {
    whatsapp: {
      groups: {
        "123@g.us": { requireMention: true },
        "456@g.us": { requireMention: false },
      },
    },
  },
}
  1. 允许所有群组但需要提及（显式）
{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  1. 仅所有者可以在群组中触发（WhatsApp）
{
  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 专用行为（历史注入、提及处理详情）。