群组 – OpenClaw - Open Source AI Coding Assistant

文档

群组

适用范围

在以下情况使用此页面：

更改群组聊天行为或提及限制

Moltbot 在所有表面上一致地处理群组聊天：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams。

初学者介绍（2 分钟）

Moltbot “生活"在您自己的消息帐户上。没有单独的 WhatsApp 机器人用户。如果您在群组中，Moltbot 可以看到该群组并在那里响应。

默认行为：

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

翻译：允许的发件人可以通过提及 Moltbot 来触发它。

TL;DR
DM 访问由 *.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

Group message flow

如果您想要…

目标	设置内容
允许所有群组但仅在 @mentions 时回复	`groups: { "*": { requireMention: true } }`
禁用所有群组回复	`groupPolicy: "disabled"`
仅特定群组	`groups: { "<group-id>": { ... } }`（无 `"*"` 键）
只有您可以在群组中触发	`groupPolicy: "allowlist"`、`groupAllowFrom: ["+1555..."]`

会话键

群组会话使用 agent:<agentId>:<channel>:group:<id> 会话键（房间/通道使用 agent:<agentId>:<channel>:channel:<id>）。
Telegram 论坛主题将 :topic:<threadId> 添加到群组 id，以便每个主题都有自己的会话。
直接聊天使用主会话（或如果配置则为每发件人）。
群组会话跳过心跳。

模式：个人 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
            "~/FriendsShared:/data:ro"
          ]
        }
      }
    }
  }
}

显示标签

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

群组策略

按通道控制如何处理群组/房间消息：

{
  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: ["[email protected]"]
    },
    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 允许列表。
群组 DM 单独控制（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）

提及限制（默认）

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

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

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "[email protected]": { requireMention: false }
      }
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false }
      }
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false }
      }
    }
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@clawd", "moltbot", "\\+15555550123"],
          historyLimit: 50
        }
      }
    ]
  }
}

注意：

mentionPatterns 是不区分大小写的正则表达式。
提供显式提及的表面仍然通过；模式是回退。
每代理覆盖：agents.list[].groupChat.mentionPatterns（当多个代理共享一个群组时很有用）。
仅当可以检测提及（本机提及或配置了 mentionPatterns）时，才强制执行提及限制。
Discord 默认值位于 channels.discord.guilds."*" 中（可按公会/频道覆盖）。
群组历史上下文在通道之间统一包装，并且 仅待处理（由于提及限制而跳过的消息）；使用 messages.groupChat.historyLimit 作为全局默认值，使用 channels.<channel>.historyLimit（或 channels.<channel>.accounts.*.historyLimit）进行覆盖。设置为 0 以禁用。

群组允许列表

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

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

禁用所有群组回复

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

仅允许特定群组（WhatsApp）

{
  channels: {
    whatsapp: {
      groups: {
        "[email protected]": { requireMention: true },
        "[email protected]": { requireMention: false }
      }
    }
  }
}

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

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

只有所有者可以在群组中触发（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 特定的行为（历史注入、提及处理详细信息），请参阅群组消息。

模型提供程序群组消息（WhatsApp web 通道）