Use this file to discover all available pages before exploring further.

Groups

OpenClaw treats group chats consistently across surfaces: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.

Beginner intro (2 minutes)

OpenClaw "lives" on your own messaging accounts. There is no separate WhatsApp bot user. If you are in a group, OpenClaw can see that group and respond there.

Default behavior:

Groups are restricted (
text
groupPolicy: "allowlist"
).
Replies require a mention unless you explicitly disable mention gating.
Normal final replies in groups/channels are private by default. Visible room output uses the
text
message
tool.

Translation: allowlisted senders can trigger OpenClaw by mentioning it.

note

**TL;DR**

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

Quick flow (what happens to a group message):


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

Visible replies

For group/channel rooms, OpenClaw defaults to

text

messages.groupChat.visibleReplies: "message_tool"

. That means the agent still processes the turn and can update memory/session state, but its normal final answer is not automatically posted back into the room. To speak visibly, the agent uses

text

message(action=send)

If the message tool is unavailable under the active tool policy, OpenClaw falls back to automatic visible replies instead of silently suppressing the response.

text

openclaw doctor

warns about this mismatch.

For direct chats and any other source turn, use

text

messages.visibleReplies: "message_tool"

to apply the same tool-only visible-reply behavior globally.

text

messages.groupChat.visibleReplies

remains the more specific override for group/channel rooms.

This replaces the old pattern of forcing the model to answer

text

NO_REPLY

for most lurk-mode turns. In tool-only mode, doing nothing visible simply means not calling the message tool.

Typing indicators are still sent while the agent works in tool-only mode. The default group typing mode is upgraded from "message" to "instant" for these turns because there may never be normal assistant message text before the agent decides whether to call the message tool. Explicit typing-mode config still wins.

To restore legacy automatic final replies for group/channel rooms:


json5
{
  messages: {
    groupChat: {
      visibleReplies: "automatic",
    },
  },
}

The gateway hot-reloads

text

messages

config after the file is saved. Restart only when file watching or config reload is disabled in the deployment.

To require visible output to go through the message tool for every source chat:


json5
{
  messages: {
    visibleReplies: "message_tool",
  },
}

Native slash commands (Discord, Telegram, and other surfaces with native command support) bypass

text

visibleReplies: "message_tool"

and always reply visibly so the channel-native command UI gets the response it expects. This applies to validated native command turns only; text-typed

text

/...

commands and ordinary chat turns still follow the configured group default.

Context visibility and allowlists

Two different controls are involved in group safety:

Trigger authorization: who can trigger the agent (
text
groupPolicy
,
text
groups
,
text
groupAllowFrom
, channel-specific allowlists).
Context visibility: what supplemental context is injected into the model (reply text, quotes, thread history, forwarded metadata).

By default, OpenClaw prioritizes normal chat behavior and keeps context mostly as received. This means allowlists primarily decide who can trigger actions, not a universal redaction boundary for every quoted or historical snippet.

Group message flow

If you want...

Goal	What to set
Allow all groups but only reply on @mentions	text `groups: { "*": { requireMention: true } }`
Disable all group replies	text `groupPolicy: "disabled"`
Only specific groups	text `groups: { "<group-id>": { ... } }` (no text `"*"` key)
Only you can trigger in groups	text `groupPolicy: "allowlist"` , text `groupAllowFrom: ["+1555..."]`

Session keys

Group sessions use
text
agent:<agentId>:<channel>:group:<id>
session keys (rooms/channels use
text
agent:<agentId>:<channel>:channel:<id>
).
Telegram forum topics add
text
: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)

Yes — this works well if your "personal" traffic is DMs and your "public" traffic is groups.

Why: in single-agent mode, DMs typically land in the main session key (

text

agent:main:main

), while groups always use non-main session keys (

text

agent:main:<channel>:group:<id>

). If you enable sandboxing with

text

mode: "non-main"

, those group sessions run in the configured sandbox backend while your main DM session stays on-host. Docker is the default backend if you do not choose one.

This gives you one agent "brain" (shared workspace + memory), but two execution postures:

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

note

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

```json5} { 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"], }, }, }, } ``` Want "groups can only see folder X" instead of "no host access"? Keep `workspaceAccess: "none"` and mount only allowlisted paths into the sandbox:


text
```json5}
{
  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
text
displayName
when available, formatted as
text
<channel>:<token>
.
text
#room
is reserved for rooms/channels; group chats use
text
g-<slug>
(lowercase, spaces ->
text
-
, keep
text
#@+._-
).

Group policy

Control how group/room messages are handled per channel:


json5
{
  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": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}

Policy	Behavior
text `"open"`	Groups bypass allowlists; mention-gating still applies.
text `"disabled"`	Block all group messages entirely.
text `"allowlist"`	Only allow groups/rooms that match the configured allowlist.

Quick mental model (evaluation order for group messages):

groupPolicy

`groupPolicy` (open/disabled/allowlist).

Group allowlists

Group allowlists (`*.groups`, `*.groupAllowFrom`, channel-specific allowlist).

Mention gating

Mention gating (`requireMention`, `/activation`).

Mention gating (default)

Group messages require a mention unless overridden per group. Defaults live per subsystem under

text

*.groups."*"

Replying to a bot message counts as an implicit mention when the channel supports reply metadata. Quoting a bot message can also count as an implicit mention on channels that expose quote metadata. Current built-in cases include Telegram, WhatsApp, Slack, Discord, Microsoft Teams, and ZaloUser.


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

Group/channel tool restrictions (optional)

Some channel configs support restricting which tools are available inside a specific group/room/channel.

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

Resolution order (most specific wins):

Group toolsBySender

Group/channel `toolsBySender` match.

Group tools

Group/channel `tools`.

Default toolsBySender

Default (`"*"`) `toolsBySender` match.

Default tools

Default (`"*"`) `tools`.

Example (Telegram):


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

note

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

When

text

channels.whatsapp.groups

text

channels.telegram.groups

, or

text

channels.imessage.groups

is configured, the keys act as a group allowlist. Use

text

"*"

to allow all groups while still setting default mention behavior.

warning

Common confusion: DM pairing approval is not the same as group authorization. For channels that support DM pairing, the pairing store unlocks DMs only. Group commands still require explicit group sender authorization from config allowlists such as `groupAllowFrom` or the documented config fallback for that channel.

Common intents (copy/paste):

```json5} { channels: { whatsapp: { groupPolicy: "disabled" } }, } ``` ```json5} { channels: { whatsapp: { groups: { "123@g.us": { requireMention: true }, "456@g.us": { requireMention: false }, }, }, }, } ``` ```json5} { channels: { whatsapp: { groups: { "*": { requireMention: true } }, }, }, } ``` ```json5} { channels: { whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["+15551234567"], groups: { "*": { requireMention: true } }, }, }, } ```

Activation (owner-only)

Group owners can toggle per-group activation:

text
/activation mention
text
/activation always

Owner is determined by

text

channels.whatsapp.allowFrom

(or the bot's self E.164 when unset). Send the command as a standalone message. Other surfaces currently ignore

text

/activation

Context fields

Group inbound payloads set:

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

Channel-specific notes:

BlueBubbles can optionally enrich unnamed macOS group participants from the local Contacts database before populating
text
GroupMembers
. This is off by default and only runs after normal group gating passes.

The agent system prompt includes a group intro on the first turn of a new group session. It reminds the model to respond like a human, avoid Markdown tables, minimize empty lines and follow normal chat spacing, and avoid typing literal

text

\n

sequences. Channel-sourced group names and participant labels are rendered as fenced untrusted metadata, not inline system instructions.

iMessage specifics

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

WhatsApp system prompts

See WhatsApp for the canonical WhatsApp system prompt rules, including group and direct prompt resolution, wildcard behavior, and account override semantics.

WhatsApp specifics

See Group messages for WhatsApp-only behavior (history injection, mention handling details).

OpenClaw Docs

Groups

Beginner intro (2 minutes)

note

Visible replies

Context visibility and allowlists

Session keys

Pattern: personal DMs + public groups (single agent)

note

Display labels

Group policy

groupPolicy

Group allowlists

Mention gating

Mention gating (default)

Group/channel tool restrictions (optional)

Group toolsBySender

Group tools

Default toolsBySender

Default tools

note

Group allowlists

warning

Activation (owner-only)

Context fields

iMessage specifics

WhatsApp system prompts

WhatsApp specifics

Related