Group Chats

OpenClaw's group chat model is: don't be "always-on" in public rooms by default. Most channels default to requiring @mention (or matching mention patterns) to trigger a reply, and group conversations use independent session keys to avoid polluting the main DM session.

This significantly reduces:

- Noise (bots interrupting)

- Prompt injection attack surface (strangers can use the bot as a tool)

- Multi-person conversation context confusion

Group chats use independent session keys, for example:

- WhatsApp: ''agent:<agentId>:whatsapp:group:<jid>''

- Telegram: ''agent:<agentId>:telegram:group:<chatId>'' (topics append '':topic:<threadId>'')

- Discord: ''agent:<agentId>:discord:channel:<channelId>'' (threads append '':thread:<threadId>'')

- Slack: ''agent:<agentId>:slack:channel:<channelId>''

DMs default to folding into the agent's main session (see ''/concepts/session'').

Default strategy: OpenClaw only triggers an agent run when mentioned in a group.

Trigger sources (vary by channel capabilities):

- Native mentions (Telegram/Discord/Slack/WhatsApp in some scenarios)

- ''messages.groupChat.mentionPatterns'' (global)

- ''agents.list[].groupChat.mentionPatterns'' (per-agent override)

When mention gating blocks a message in a group, OpenClaw places it in a pending history buffer (see below) so that recent messages are injected as context on the next trigger.

You can disable requireMention per group (making that group always-on):

- Telegram: ''channels.telegram.groups.<chatId>.requireMention=false''

- WhatsApp: ''channels.whatsapp.groups.<jid>.requireMention=false''

- Discord: ''channels.discord.guilds.<guildId>.channels.<channel>.requireMention=false''

- Slack: ''channels.slack.channels.<channel>.requireMention=false''

Security tip: For any room that "might have strangers", keep ''requireMention=true''.

Allowlist forms vary by channel, but the principle is consistent: when you start explicitly configuring ''groups/guilds/channels'', it typically becomes an allowlist.

- Telegram:

- Don't write ''channels.telegram.groups'': allow all groups (then mention gating decides whether to trigger).

- Write ''channels.telegram.groups'': only allow listed groups or ''"*"''.

- WhatsApp:

- ''channels.whatsapp.groups'' is the group allowlist (use ''"*"'' to allow all groups).

- Discord:

- ''channels.discord.guilds'' is the guild allowlist; if ''channels'' is defined in a guild, only listed channels are allowed.

- Slack:

- ''channels.slack.groupPolicy'' + ''channels.slack.channels'' control the channel allowlist.

Many channels have two layers of group access control:

- Which groups/channels are allowed (the above allowlist)

- ''In allowed groups, which senders can trigger'' (''groupPolicy'' + ''groupAllowFrom'' or per-room ''users'')

Example for Telegram:

{
  channels: {
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: {
        "-1001234567890": { requireMention: true }
      }
    }
  }
}

When ''groupPolicy="allowlist"'' and there's no ''groupAllowFrom'', it defaults to blocking (fail-closed).

When a group message doesn't trigger a reply (no mention / blocked by allowlist), OpenClaw stores these messages as pending and injects them into the prompt on the next trigger:

[Chat messages since your last reply - for context]
...
[/Chat messages since your last reply - for context]

[Current message - respond to this]
...
[/Current message - respond to this]

Important characteristics:

- pending-only: only injects messages "after your last reply but not processed".

- Doesn't re-inject messages already written to the transcript.

- The current message undergoes directive stripping; the history block remains unchanged.

Limits:

- Global: ''messages.groupChat.historyLimit''

- Channel override: ''channels.telegram.historyLimit'' / ''channels.slack.historyLimit'' / ''channels.whatsapp.historyLimit'', etc.

- Set to ''0'' to disable.

Some channels support the ''/activation'' command (affects only the current session):

- ''/activation mention'': requires mention (default)

- ''/activation always'': reply to all messages

Notes:

- This command usually only works for authorized senders (owner/allowlist).

Group messages don't let the model "decide who should reply"; instead, deterministic routing is done through ''bindings''.

Common strategies:

- "One group, one agent": In ''bindings'', match by ''peer.kind="group"'' + ''peer.id'' to point to a specific agent.

- "Assign agent by channel account": match by ''accountId''.

- "Broadcast groups": the same trigger message runs multiple agents (see ''/broadcast-groups'').

- You set ''requireMention=false'' but still no reply: most likely ''groupPolicy="allowlist"'' and no ''groupAllowFrom'' / group allowlist configured.

- Discord: ''requireMention'' must be written under ''channels.discord.guilds'' or a specific channel; top-level ''channels.discord.requireMention'' is ignored.

- Telegram: After disabling BotFather privacy mode, you need to remove and re-add the bot to the group for settings to take effect.

- ''/concepts/session''

- ''/concepts/messages''

- ''/concepts/channel-routing''

- ''/gateway/configuration''