Groups

OpenClaw xử lý group chat một cách nhất quán trên tất cả các nền tảng: WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Microsoft Teams.

Giới thiệu cho người mới (2 phút)

OpenClaw “sống” trên chính tài khoản nhắn tin của các bạn. Không có bot WhatsApp riêng biệt nào cả. Nếu các bạn ở trong một nhóm, OpenClaw có thể thấy nhóm đó và trả lời ở đó.

Hành vi mặc định:

Các nhóm bị hạn chế (groupPolicy: "allowlist").
Phải mention mới trả lời, trừ khi các bạn tắt mention gating.

Nói cách khác: những người trong allowlist có thể kích hoạt OpenClaw bằng cách mention nó.

TL;DR

Truy cập DM được kiểm soát bởi *.allowFrom.

Truy cập nhóm được kiểm soát bởi *.groupPolicy + allowlist (*.groups, *.groupAllowFrom).

Kích hoạt trả lời được kiểm soát bởi mention gating (requireMention, /activation).

Luồng xử lý nhanh (điều gì xảy ra với tin nhắn nhóm):

groupPolicy? disabled -> bỏ qua
groupPolicy? allowlist -> nhóm được phép? không -> bỏ qua
requireMention? có -> có mention? không -> chỉ lưu để làm context
còn lại -> trả lời

Luồng xử lý tin nhắn nhóm

Nếu các bạn muốn…

Mục đích	Cài đặt gì
Cho phép tất cả nhóm nhưng chỉ trả lời khi @mention	`groups: { "*": { requireMention: true } }`
Tắt tất cả trả lời trong nhóm	`groupPolicy: "disabled"`
Chỉ cho phép nhóm cụ thể	`groups: { "<group-id>": { ... } }` (không có key `"*"`)
Chỉ mình bạn mới kích hoạt được trong nhóm	`groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]`

Session keys

Group session dùng session key dạng agent:<agentId>:<channel>:group:<id> (room/channel dùng agent:<agentId>:<channel>:channel:<id>).
Telegram forum topic thêm :topic:<threadId> vào group id để mỗi topic có session riêng.
Chat trực tiếp dùng main session (hoặc theo người gửi nếu được cấu hình).
Heartbeat bị bỏ qua cho group session.

Pattern: DM cá nhân + nhóm công khai (single agent)

Có — cách này hoạt động tốt nếu traffic “cá nhân” của các bạn là DM và traffic “công khai” là nhóm.

Tại sao: ở chế độ single-agent, DM thường rơi vào session key main (agent:main:main), trong khi nhóm luôn dùng session key non-main (agent:main:<channel>:group:<id>). Nếu các bạn bật sandboxing với mode: "non-main", các group session đó sẽ chạy trong Docker trong khi DM session chính vẫn ở trên host.

Điều này cho các bạn một “bộ não” agent (workspace + memory chung), nhưng hai tư thế thực thi:

DM: full tools (host)
Nhóm: sandbox + restricted tools (Docker)

Nếu các bạn cần workspace/persona thực sự tách biệt (“cá nhân” và “công khai” không được trộn lẫn), hãy dùng agent thứ hai + binding. Xem Multi-Agent Routing.

Ví dụ (DM trên host, nhóm sandboxed + chỉ messaging tools):

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // groups/channels là non-main -> sandboxed
        scope: "session", // cách ly mạnh nhất (một container cho mỗi group/channel)
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        // Nếu allow không rỗng, mọi thứ khác bị chặn (deny vẫn thắng).
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

Muốn “nhóm chỉ thấy được thư mục X” thay vì “không truy cập host”? Giữ workspaceAccess: "none" và chỉ mount các đường dẫn trong allowlist vào sandbox:

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

Liên quan:

Các key cấu hình và giá trị mặc định: Gateway configuration
Debug tại sao tool bị chặn: Sandbox vs Tool Policy vs Elevated
Chi tiết bind mount: Sandboxing

Display labels

Label UI dùng displayName khi có, định dạng <channel>:<token>.
#room dành riêng cho room/channel; group chat dùng g-<slug> (chữ thường, khoảng trắng -> -, giữ #@+._-).

Group policy

Kiểm soát cách xử lý tin nhắn nhóm/room cho mỗi channel:

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

Policy	Hành vi
`"open"`	Nhóm bỏ qua allowlist; mention-gating vẫn áp dụng.
`"disabled"`	Chặn hoàn toàn tất cả tin nhắn nhóm.
`"allowlist"`	Chỉ cho phép nhóm/room khớp với allowlist đã cấu hình.

Lưu ý:

groupPolicy tách biệt với mention-gating (yêu cầu @mention).
WhatsApp/Telegram/Signal/iMessage/Microsoft Teams: dùng groupAllowFrom (fallback: allowFrom tường minh).
Discord: allowlist dùng channels.discord.guilds.<id>.channels.
Slack: allowlist dùng channels.slack.channels.
Matrix: allowlist dùng channels.matrix.groups (room ID, alias, hoặc tên). Dùng channels.matrix.groupAllowFrom để hạn chế người gửi; allowlist users theo từng room cũng được hỗ trợ.
Group DM được kiểm soát riêng (channels.discord.dm.*, channels.slack.dm.*).
Telegram allowlist có thể khớp user ID ("123456789", "telegram:123456789", "tg:123456789") hoặc username ("@alice" hoặc "alice"); prefix không phân biệt chữ hoa/thường.
Mặc định là groupPolicy: "allowlist"; nếu group allowlist rỗng, tin nhắn nhóm bị chặn.

Mô hình tư duy nhanh (thứ tự đánh giá cho tin nhắn nhóm):

groupPolicy (open/disabled/allowlist)
group allowlist (*.groups, *.groupAllowFrom, allowlist theo channel)
mention gating (requireMention, /activation)

Mention gating (mặc định)

Tin nhắn nhóm yêu cầu mention trừ khi bị ghi đè theo từng nhóm. Giá trị mặc định nằm ở mỗi subsystem dưới *.groups."*".

Trả lời tin nhắn bot được tính là mention ngầm (khi channel hỗ trợ metadata trả lời). Áp dụng cho Telegram, WhatsApp, Slack, Discord và 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: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}

Lưu ý:

mentionPatterns là regex không phân biệt chữ hoa/thường.
Các nền tảng cung cấp mention tường minh vẫn được chấp nhận; pattern là fallback.
Ghi đè theo agent: agents.list[].groupChat.mentionPatterns (hữu ích khi nhiều agent chia sẻ một nhóm).
Mention gating chỉ được áp dụng khi có thể phát hiện mention (mention native hoặc mentionPatterns được cấu hình).
Discord mặc định nằm ở channels.discord.guilds."*" (có thể ghi đè theo guild/channel).
Group history context được bọc đồng nhất trên các channel và là pending-only (tin nhắn bị bỏ qua do mention gating); dùng messages.groupChat.historyLimit cho giá trị mặc định toàn cục và channels.<channel>.historyLimit (hoặc channels.<channel>.accounts.*.historyLimit) để ghi đè. Đặt 0 để tắt.

Hạn chế tool theo nhóm/channel (tùy chọn)

Một số cấu hình channel hỗ trợ hạn chế tool nào có sẵn bên trong một nhóm/room/channel cụ thể.

tools: cho phép/từ chối tool cho toàn bộ nhóm.
toolsBySender: ghi đè theo người gửi trong nhóm (key là sender ID/username/email/số điện thoại tùy channel). Dùng "*" làm wildcard.

Thứ tự phân giải (cụ thể nhất thắng):

group/channel toolsBySender khớp
group/channel tools
mặc định ("*") toolsBySender khớp
mặc định ("*") tools

Ví dụ (Telegram):

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

Lưu ý:

Hạn chế tool theo nhóm/channel được áp dụng thêm vào tool policy toàn cục/agent (deny vẫn thắng).
Một số channel dùng nesting khác cho room/channel (ví dụ: Discord guilds.*.channels.*, Slack channels.*, MS Teams teams.*.channels.*).

Group allowlist

Khi channels.whatsapp.groups, channels.telegram.groups, hoặc channels.imessage.groups được cấu hình, các key hoạt động như group allowlist. Dùng "*" để cho phép tất cả nhóm trong khi vẫn đặt hành vi mention mặc định.

Các ý định phổ biến (copy/paste):

Tắt tất cả trả lời nhóm

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

Chỉ cho phép nhóm cụ thể (WhatsApp)

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

Cho phép tất cả nhóm nhưng yêu cầu mention (tường minh)

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

Chỉ owner mới kích hoạt được trong nhóm (WhatsApp)

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

Activation (chỉ owner)

Owner nhóm có thể bật/tắt activation theo từng nhóm:

/activation mention
/activation always

Owner được xác định bởi channels.whatsapp.allowFrom (hoặc E.164 của chính bot khi không đặt). Gửi lệnh dưới dạng tin nhắn độc lập. Các nền tảng khác hiện tại bỏ qua /activation.

Context fields

Payload inbound của nhóm đặt:

ChatType=group
GroupSubject (nếu biết)
GroupMembers (nếu biết)
WasMentioned (kết quả mention gating)
Telegram forum topic cũng bao gồm MessageThreadId và IsForum.

System prompt của agent bao gồm phần giới thiệu nhóm ở lượt đầu tiên của group session mới. Nó nhắc model trả lời như con người, tránh bảng Markdown, và tránh gõ chuỗi \n theo nghĩa đen.

Đặc thù iMessage

Ưu tiên chat_id:<id> khi routing hoặc allowlist.
Liệt kê chat: imsg chats --limit 20.
Trả lời nhóm luôn quay về cùng một chat_id.

Đặc thù WhatsApp

Xem Group messages cho hành vi chỉ dành cho WhatsApp (history injection, chi tiết xử lý mention).