Configure OpenClaw Group Access: 2-Minute Setup Guide

OpenClaw handles group chats across various platforms like Discord, iMessage, and WhatsApp by using your own accounts. This means you don’t have to set up a separate bot user to get things running in your favorite messaging apps.

Getting Started with OpenClaw Group Chats

OpenClaw functions directly through your existing messaging accounts, so there is no need for a separate WhatsApp bot user. If you are a member of a group, OpenClaw can see the messages in that group and provide responses.

1. Groups are restricted by default using the groupPolicy: "allowlist" setting.
2. Replies generally require a mention unless you choose to turn off mention gating.

This setup means that only senders on your allowlist can trigger OpenClaw by mentioning it.

1. DM access is managed through the *.allowFrom configuration.
2. Group access is managed via *.groupPolicy and allowlists like *.groups or *.groupAllowFrom.
3. Reply triggering is managed by mention gating settings such as requireMention or /activation.

Here is the logic flow for how a group message is processed:

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

Managing Context Visibility and Allowlists

When you use OpenClaw in groups, you have control over who can trigger the agent and what parts of the conversation it can see. These settings help you maintain privacy while ensuring the agent has enough context to be helpful.

1. Trigger authorization determines who is allowed to call the agent using settings like groupPolicy, groups, or groupAllowFrom.
2. Context visibility controls what supplemental data, such as thread history or quoted text, is sent to the model.

By default, OpenClaw prioritizes natural chat behavior and keeps context as it is received. This means allowlists are primarily used to decide who can trigger actions, rather than acting as a strict filter for every piece of historical text or quoted snippet.

Current behavior depends on the specific channel:

1. Some channels already filter supplemental context based on the sender, such as Slack thread seeding or Matrix reply lookups.
2. Other channels pass through quote, reply, and forward context exactly as they are received.

There is a plan to harden this model in the future:

1. contextVisibility: "all" will keep the current behavior where context is passed as-received.
2. contextVisibility: "allowlist" will filter supplemental context so it only includes allowlisted senders.
3. contextVisibility: "allowlist_quote" will function like the allowlist setting but add one exception for explicit quotes or replies.

Until these updates are applied consistently across all channels, you might notice some differences depending on the platform you are using.

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

Understanding Group Session Keys

OpenClaw uses unique session keys to keep your conversations organized and ensure messages are routed correctly. These keys help the system distinguish between standard group chats, specific forum topics, and direct messages.

1. Group sessions use keys formatted as agent:<agentId>:<channel>:group:<id>, while rooms or channels use agent:<agentId>:<channel>:channel:<id>.
2. Telegram forum topics include :topic:<threadId> in the group ID so that every topic maintains its own session.
3. Direct chats typically use the main session key unless you have configured them to be per-sender.
4. Heartbeats are automatically skipped for any group sessions.

Configuring Personal DMs and Public Groups for a Single Agent

You can set up a single OpenClaw agent to handle both your private DMs and public group chats with different security levels. This works well because DMs and groups use different session keys, allowing you to apply different execution rules to each.

In single-agent mode, your DMs usually land in the main session key (agent:main:main), while groups always use non-main session keys. If you enable sandboxing with mode: "non-main", those group sessions will run in a Docker container while your main DM session stays on the host.

This gives you one agent “brain” with a shared workspace and memory, but two different ways of running:

1. DMs: You have access to full tools on the host.
2. Groups: These are restricted to a sandbox with limited tools.

If you need to keep your personal and public workspaces or personas completely separate, you should use a second agent with bindings. You can find more details on this in the Multi-Agent Routing documentation.

Example of DMs on the host and groups in a sandbox with messaging-only tools:

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

If you want groups to only see a specific folder instead of having no host access at all, you can keep workspaceAccess: "none" and mount only allowlisted paths into the sandbox:

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

Related documentation:

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

Understand OpenClaw Display labels

When you are managing multiple chats across different platforms, you need a clear way to identify them in the UI. OpenClaw handles this by using specific naming patterns so you always know the context of every conversation.

1. UI labels will use the displayName property whenever it is available.
2. These labels are typically formatted as <channel>:<token> to give you a quick overview of the source.
3. If you are working with rooms or channels, the #room prefix is reserved specifically for those types of interactions.
4. For group chats, the system uses a g-<slug> format which converts the name to lowercase and replaces spaces with dashes.
5. This slugging process preserves specific characters like #@+._- to keep the identifiers recognizable.

Configure OpenClaw Group policy

You have full control over how your bot interacts with group and room messages on a per-channel basis. By adjusting the JSON configuration, you can decide exactly which groups are allowed to trigger your Gateway and which ones should be ignored.

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

1. Use the “open” policy if you want groups to bypass allowlists, though keep in mind that mention-gating still applies.
2. Set the policy to “disabled” if you want to block all group messages entirely for that specific channel.
3. Choose “allowlist” to only permit groups or rooms that match your specific configuration settings.
4. Note that the system is designed to be secure by default, so an empty allowlist will result in blocked messages.

There are several important technical details you should keep in mind while setting up your group rules:

1. The groupPolicy setting is handled separately from mention-gating, which specifically requires @mentions to function.
2. For platforms like WhatsApp, Telegram, Signal, iMessage, Microsoft Teams, and Zalo, you should use the groupAllowFrom field.
3. If groupAllowFrom is not found, the system will use the explicit allowFrom as a fallback.
4. DM pairing approvals are stored for DM access only; group sender authorization must always remain explicit in your group allowlists.
5. On Discord, the allowlist specifically uses the channels.discord.guilds.<id>.channels path.
6. For Slack, you will configure your allowlist using channels.slack.channels.
7. Matrix users should prefer using room IDs or aliases in channels.matrix.groups because joined-room name lookup is a best-effort process.
8. You can also use channels.matrix.groupAllowFrom to restrict specific senders, and per-room users allowlists are supported.
9. Group DMs are controlled by their own separate settings like channels.discord.dm.* or channels.slack.dm.*.
10. The Telegram allowlist is flexible and matches user IDs like “123456789” or usernames like “@alice” with case-insensitive prefixes.
11. If a provider block is completely missing from your config, the system uses a fail-closed mode instead of inheriting default policies.
12. This runtime safety ensures that your Gateway does not accidentally expose groups if you forget a configuration section.

When a group message arrives, you can visualize the evaluation order like this:

1. First, the system checks the groupPolicy to see if it is open, disabled, or restricted to an allowlist.
2. Next, it looks at the specific group allowlists such as .groups or .groupAllowFrom.
3. Then, it evaluates mention gating requirements like the requireMention setting.
4. Finally, it checks for any specific /activation commands that might be required for the bot to respond.

Manage OpenClaw Mention Gating

You can manage how your bot interacts in group settings by using OpenClaw mention gating to ensure it only responds when called upon. This feature helps the bot stay relevant and avoids unnecessary interruptions in your group conversations.

1. Group messages require a mention by default unless you choose to override this setting for a specific group.
2. You can set these defaults for each subsystem under the *.groups."*" path in your configuration.
3. When a channel supports reply metadata, replying to a bot message counts as an implicit mention.
4. Quoting a bot message also counts as an implicit mention on platforms like Telegram, WhatsApp, Slack, Discord, Microsoft Teams, and ZaloUser.
5. Use the following JSON structure to manage these settings across your different channels:

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

6. Note that mentionPatterns are case-insensitive safe regex patterns; any invalid patterns or unsafe nested-repetition forms will be ignored by the system.
7. If a platform provides explicit mentions, those will always pass; your custom patterns are only used as a fallback.
8. You can apply a per-agent override using agents.list[].groupChat.mentionPatterns, which is very useful when multiple agents are sharing the same group.
9. OpenClaw only enforces mention gating when mention detection is possible, either through native platform mentions or your configured mentionPatterns.
10. For Discord users, the default settings live in channels.discord.guilds."*" and you can override them for specific guilds or channels.
11. Group history context is wrapped uniformly across all channels and is pending-only, meaning it only includes messages that were skipped because of mention gating.
12. Use messages.groupChat.historyLimit for the global default and channels.<channel>.historyLimit (or the account-specific version) for overrides.
13. If you want to disable this history feature entirely, simply set the value to 0.

Set Tool Restrictions for Groups

You might want to control which tools are accessible in specific channels or for certain users within a group. OpenClaw provides flexible configuration options to restrict tool usage based on the group context or the message sender.

1. Use the tools setting to allow or deny specific tools for an entire group.
2. Use toolsBySender if you need to create overrides for specific people within that group.
3. When identifying senders, use explicit key prefixes like id:<senderId>, e164:<phone>, username:<handle>, or name:<displayName>.
4. You can also use the "*" wildcard for broader matching across senders.
5. Legacy keys that do not have a prefix are still accepted but the system will match them as id: only.
6. The system resolves these rules in a specific order where the most specific match wins: first it checks the group toolsBySender, then the group tools, followed by the default toolsBySender, and finally the default tools.
7. Here is an example of how you can configure these restrictions for Telegram:

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

8. These group and channel tool restrictions are applied on top of your global or agent tool policies.
9. Always remember that a “deny” rule will take precedence over an “allow” rule in the final policy.
10. Keep in mind that some channels use different nesting for rooms and channels, such as Discord using guilds.*.channels.*, Slack using channels.*, and Microsoft Teams using teams.*.channels.*.

Manage Group allowlists in OpenClaw

Setting up group permissions ensures your OpenClaw bot only interacts where it is supposed to. When you define keys under channels.whatsapp.groups, channels.telegram.groups, or channels.imessage.groups, these act as a strict allowlist for your groups.

1. You can use "*" as a wildcard to allow all groups while still defining how the bot should handle mentions by default.
2. It is a common point of confusion, but remember that DM pairing approval is different from group authorization.
3. For channels that support DM pairing, the pairing store only unlocks direct messages.
4. Group commands always require explicit authorization from config allowlists like groupAllowFrom or the specific fallback settings for that channel.

Here are some common JSON configurations you can copy and paste:

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

Toggle Activation as an owner

If you are the group owner, you have the power to change how the bot reacts to messages in real-time. You can use simple commands to switch between requiring a mention or having the bot always active.

1. Use the command /activation mention to make the bot respond only when tagged.
2. Use the command /activation always to let the bot respond to every message in the group.

The owner is identified by the channels.whatsapp.allowFrom setting, or the bot’s own E.164 number if that is not set. You should send these commands as standalone messages. Note that other platforms currently ignore the /activation command.

Use OpenClaw context fields for group data

When you’re working with OpenClaw context fields, you get a clear picture of the inbound message metadata to help you handle group dynamics. These fields are automatically populated to ensure your agent understands the environment of the conversation.

1. OpenClaw sets the ChatType to group for all inbound group payloads.
2. You can access the GroupSubject and GroupMembers fields when that information is available from the source.
3. The WasMentioned field provides you with the specific result of the mention gating check.
4. If you are working with Telegram forum topics, the payload also includes MessageThreadId and IsForum.
5. If you use BlueBubbles, it can optionally enrich unnamed macOS group participants from your local Contacts database before it populates GroupMembers.
6. This enrichment feature is disabled by default and only runs after the standard group gating passes are complete.
7. The agent system prompt includes a group intro during the first turn of a new group session.
8. This prompt tells the model to act like a human and avoid using Markdown tables.
9. It also suggests minimizing empty lines and following normal chat spacing.
10. Finally, it warns the model to avoid typing literal \n sequences in its responses.

Configure iMessage routing and chat IDs

Managing iMessage requires you to focus on specific chat identifiers and CLI tools to keep your routing accurate. You’ll mostly use unique IDs to make sure your messages reach the correct destination.

1. You should prefer using the format chat_id:<id> whenever you are routing messages or setting up an allowlist.
2. To see a list of your available chats, you can use the CLI command imsg chats —limit 20.
3. When you send a reply to a group, OpenClaw ensures the message always goes back to that same chat_id.
4. This keeps your conversation threads organized and correctly mapped for every interaction.

Understand WhatsApp group message behavior

WhatsApp has its own set of rules for things like history and mentions that differ from other platforms. You should refer to the specific documentation to understand how these features work within the Gateway.

1. You can find more about WhatsApp-only behavior, like history injection and specific mention handling, in the Group messages documentation.
2. These details help you understand how the Gateway manages specific WhatsApp interactions and ensures data flows correctly.