​

Groups

​

Beginner intro (2 minutes)

• Groups are restricted (groupPolicy: "allowlist").
• Replies require a mention unless you explicitly disable mention gating.

TL;DR

• DM access is controlled by *.allowFrom.
• Group access is controlled by *.groupPolicy + allowlists (*.groups, *.groupAllowFrom).
• Reply triggering is controlled by mention gating (requireMention, /activation).

groupPolicy? disabled -> drop groupPolicy? allowlist -> group allowed? no -> drop requireMention? yes -> mentioned? no -> store for context only otherwise -> reply 

​

Session keys

• Group sessions use agent:<agentId>:<channel>:group:<id> session keys (rooms/channels use agent:<agentId>:<channel>:channel:<id>).
• Telegram forum topics add :topic:<threadId> to the group id so each topic has its own session.
• Direct chats use the main session (or per-sender if configured).
• Heartbeats are skipped for group sessions.

​

Pattern: personal DMs + public groups (single agent)

• DMs: full tools (host)
• Groups: sandbox + restricted tools (Docker)

If you need truly separate workspaces/personas (“personal” and “public” must never mix), use a second agent + bindings. See Multi-Agent Routing.

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

• Configuration keys and defaults: Gateway configuration
• Debugging why a tool is blocked: Sandbox vs Tool Policy vs Elevated
• Bind mounts details: Sandboxing

​

Display labels

• UI labels use displayName when available, formatted as <channel>:<token>.
• #room is reserved for rooms/channels; group chats use g-<slug> (lowercase, spaces -> -, keep #@+._-).

​

Group policy

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

• groupPolicy is separate from mention-gating (which requires @mentions).
• WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: use groupAllowFrom (fallback: explicit allowFrom).
• DM pairing approvals (*-allowFrom store entries) apply to DM access only; group sender authorization stays explicit to group allowlists.
• Discord: allowlist uses channels.discord.guilds.<id>.channels.
• Slack: allowlist uses channels.slack.channels.
• Matrix: allowlist uses channels.matrix.groups (room IDs, aliases, or names). Use channels.matrix.groupAllowFrom to restrict senders; per-room users allowlists are also supported.
• Group DMs are controlled separately (channels.discord.dm.*, channels.slack.dm.*).
• Telegram allowlist can match user IDs ("123456789", "telegram:123456789", "tg:123456789") or usernames ("@alice" or "alice"); prefixes are case-insensitive.
• Default is groupPolicy: "allowlist"; if your group allowlist is empty, group messages are blocked.
• Runtime safety: when a provider block is completely missing (channels.<provider> absent), group policy falls back to a fail-closed mode (typically allowlist) instead of inheriting channels.defaults.groupPolicy.

1. groupPolicy (open/disabled/allowlist)
2. group allowlists (*.groups, *.groupAllowFrom, channel-specific allowlist)
3. mention gating (requireMention, /activation)

​

Mention gating (default)

{  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 are case-insensitive safe regex patterns; invalid patterns and unsafe nested-repetition forms are ignored.
• Surfaces that provide explicit mentions still pass; patterns are a fallback.
• Per-agent override: agents.list[].groupChat.mentionPatterns (useful when multiple agents share a group).
• Mention gating is only enforced when mention detection is possible (native mentions or mentionPatterns are configured).
• Discord defaults live in channels.discord.guilds."*" (overridable per guild/channel).
• Group history context is wrapped uniformly across channels and is pending-only (messages skipped due to mention gating); use messages.groupChat.historyLimit for the global default and channels.<channel>.historyLimit (or channels.<channel>.accounts.*.historyLimit) for overrides. Set 0 to disable.

​

Group/channel tool restrictions (optional)

• tools: allow/deny tools for the whole group.
• toolsBySender: per-sender overrides within the group. Use explicit key prefixes: id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, and "*" wildcard. Legacy unprefixed keys are still accepted and matched as id: only.

1. group/channel toolsBySender match
2. group/channel tools
3. default ("*") toolsBySender match
4. default ("*") tools

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

• Group/channel tool restrictions are applied in addition to global/agent tool policy (deny still wins).
• Some channels use different nesting for rooms/channels (e.g., Discord guilds.*.channels.*, Slack channels.*, Microsoft Teams teams.*.channels.*).

​

Group allowlists

1. Disable all group replies

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

2. Allow only specific groups (WhatsApp)

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

3. Allow all groups but require mention (explicit)

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

4. Only the owner can trigger in groups (WhatsApp)

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

​

Activation (owner-only)

• /activation mention
• /activation always

​

Context fields

• ChatType=group
• GroupSubject (if known)
• GroupMembers (if known)
• WasMentioned (mention gating result)
• Telegram forum topics also include MessageThreadId and IsForum.

​

iMessage specifics

• Prefer chat_id:<id> when routing or allowlisting.
• List chats: imsg chats --limit 20.
• Group replies always go back to the same chat_id.

​

WhatsApp specifics