群组

Clawdbot 在各个渠道（WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams）中以一致的方式处理群聊。

入门介绍（2 分钟）

Clawdbot “生活”在您自己的消息帐户中。没有单独的 WhatsApp 机器人用户。如果您在群组中，Clawdbot 就可以看到该群组并在那里做出回应。

默认行为：

群组是受限的（groupPolicy: "allowlist"）。
除非您明确禁用提及过滤（mention gating），否则回复需要提及（mention）。

换句话说：白名单中的发送者可以通过提及 Clawdbot 来触发它。

TL;DR

私聊（DM）访问由 *.allowFrom 控制。

群组访问由 *.groupPolicy + 白名单（*.groups, *.groupAllowFrom）控制。

回复触发由提及过滤（requireMention, /activation）控制。

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

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

群组消息流�程

如果您想...

目标	如何设置
允许所有群组，但仅在 @提及时回复	`groups: { "*": { requireMention: true } }`
禁用所有群组回复	`groupPolicy: "disabled"`
仅特定群组	`groups: { "<group-id>": { ... } }` (没有 `"*"` 键)
仅您可以触发群组	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

会话密钥 (Session keys)

群组会话使用 agent:<agentId>:<channel>:group:<id> 会话密钥（房间/频道使用 agent:<agentId>:<channel>:channel:<id>）。
Telegram 论坛主题在群组 ID 中添加 :topic:<threadId>，因此每个主题都有自己的会话。
私聊使用主会话（或按发送者配置，如果已设置）。
群组会话会跳过心跳（Heartbeats）。

模式：个人私聊 + 公共群组（单 Agent）

是的 —— 如果您的“个人”流量是私聊，而您的“公共”流量是群组，这种模式会非常有效。

原因：在单 Agent 模式下，私聊通常进入 主（main） 会话密钥（agent:main:main），而群组始终使用 非主（non-main） 会话密钥（agent:main:<channel>:group:<id>）。如果您通过 mode: "non-main" 启用沙箱，这些群组会话将在 Docker 中运行，而您的主私聊会话则保留在主机上。

这为您提供了一个 Agent “大脑”（共享工作区 + 内存），但具有两种执行姿态：

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

如果您需要真正独立的工作区/人设（“个人”和“公共”绝对不能混淆），请使用第二个 Agent + 绑定。参见多 Agent 路由。

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

{
  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
            "~/FriendsShared:/data:ro"
          ]
        }
      }
    }
  }
}

显示标签 (Display labels)

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

群组策略 (Group policy)

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

{
  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 (open/disabled/allowlist)
群组白名单 (*.groups, *.groupAllowFrom, 渠道特定白名单)
提及过滤 (requireMention, /activation)

提及过滤 (Mention gating, 默认)

除非针对每个群组进行覆盖，否则群组消息需要提及。默认值位于 *.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: ["@clawd", "clawdbot", "\\+15555550123"],
          historyLimit: 50
        }
      }
    ]
  }
}

注意：

mentionPatterns 是不区分大小写的正则表达式。
提供显式提及的渠道仍然会通过；模式是一个回退。
按 Agent 覆盖：agents.list[].groupChat.mentionPatterns（当多个 Agent 共享一个群组时很有用）。
提及过滤仅在可以进行提及检测时（原生提及或配置了 mentionPatterns）强制执行。
Discord 默认值位于 channels.discord.guilds."*"（可按服务器/频道覆盖）。
群组历史上下文在各个渠道中统一包装，并且是 仅限待定 (pending-only)（因提及过滤而被跳过的消息）；全局默认值使用 messages.groupChat.historyLimit，覆盖使用 channels.<channel>.historyLimit（或 channels.<channel>.accounts.*.historyLimit）。设置为 0 禁用。

群组白名单 (Group allowlists)

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

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

禁用所有群组回复

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

仅允许特定群组 (WhatsApp)

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

允许所有群组但需要提及（显式）

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

只有所有者可以在群组中触发 (WhatsApp)

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

激活 (Activation, 仅限所有者)

群组所有者可以切换每个群组的激活状态：

/activation mention
/activation always

所有者由 channels.whatsapp.allowFrom 决定（如果未设置，则为机器人自身的 E.164）。将命令作为独立消息发送。其他渠道目前忽略 /activation。

上下文关联字段 (Context fields)

群组入站负载设置：

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

Agent 系统提示词在新的群组会话的第一轮对话中包含一个群组介绍。它提醒模型要像人类一样回应，避免使用 Markdown 表格，并避免输入字面量 \n 序列。

iMessage 特定说明

在路由或设置白名单时优先使用 chat_id:<id>。
列出聊天：imsg chats --limit 20。
群组回复始终返回到同一个 chat_id。

WhatsApp 特定说明

参见群组消息了解 WhatsApp 专有行为（历史注入、提及处理细节）。

群组

入门介绍（2 分钟）​

会话密钥 (Session keys)​

模式：个人私聊 + 公共群组（单 Agent）​

显示标签 (Display labels)​

群组策略 (Group policy)​

提及过滤 (Mention gating, 默认)​

群组白名单 (Group allowlists)​

激活 (Activation, 仅限所有者)​

上下文关联字段 (Context fields)​

iMessage 特定说明​

WhatsApp 特定说明​