OpenClaw Group Messages: Read Team Context Without Hijacking the Room

Group chat is where useful context lives and where agents can become annoying fast. A direct message is simple: one person asks, one agent replies. A team room is different. There are side comments, old decisions, multiple senders, jokes, approvals, and half-finished context that the agent should understand without acting like every line is a ticket.

OpenClaw's group-message model is built around that distinction. It can let an agent read the room, wake only when mentioned, keep group state separate from personal DMs, and restrict what tools are available inside a shared chat. The goal is not to make the agent louder. The goal is to make it useful when the team actually pulls it in.

The docs describe group chats across Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and related surfaces. The WhatsApp group-message page goes deeper on activation, pending history, sender labels, and per-group sessions. The operating rule is the same everywhere: group access, reply triggering, session scope, and tool access are separate controls. Treat them separately.

Start with the safety model

OpenClaw does not treat a group like a normal DM. Group access is controlled by groupPolicy and allowlists. Reply triggering is controlled by mention gating. Direct-message access is still handled by each channel's DM policy and allowFrom style settings.

That separation matters because "can see the group" and "can act on behalf of the group" are not the same permission. The docs describe the quick flow clearly: disabled group policy drops the message, allowlist policy checks whether the group or sender is allowed, mention gating decides whether the message should trigger a reply, and unmentioned chatter can be stored as context instead of becoming work.

If you only remember one config habit, make it this: allow the room deliberately and require mentions by default. Open groups without mention gating are how an agent becomes a meeting participant nobody invited.

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: {
        "*": { requireMention: true },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#ops": { allow: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
}

In that example, WhatsApp groups are allowlisted and require a mention. Slack is also allowlisted by channel. The agent gets safe mention patterns so display-name pings can still work when a surface does not preserve native mention metadata cleanly.

OpenClaw validates config strictly. Unknown keys, malformed types, and invalid values can stop the Gateway from accepting the config. That is annoying in the moment and healthy in production. A group-chat mistake should fail loudly before the agent starts answering in the wrong room.

Mention gating keeps the room sane

Default group behavior is conservative. Groups are restricted, and replies require a mention unless you explicitly disable that gate. On WhatsApp, mention mode can be triggered by native mentions, safe regex patterns, or the bot's E.164 number appearing in the text. always mode wakes the agent on every message, but the docs still expect it to stay quiet unless it has something meaningful to add.

I would use always only for carefully chosen operator rooms. Most teams want the agent to hear context, not narrate every thread. If people know they can type @openclaw when they need help, the room keeps its normal human rhythm.

For WhatsApp groups, owners can toggle activation with standalone commands:

/activation mention
/activation always
/status

The ownership rule is important. The docs tie that command to the owner number from channels.whatsapp.allowFrom, or the bot's own E.164 when unset. Do not let every group member change whether the agent wakes on every message.

Context is pending, not a transcript dump

The feature that makes group messages useful is not just replying. It is pending context. The WhatsApp-specific docs say pending-only group messages that did not trigger a run are prefixed under a context block, while the triggering line is separated as the current message. Messages already in the session are not re-injected.

That design solves a real operator problem. The agent can see what happened since its last reply without pretending every unmentioned message was a request. It can answer the person who finally tagged it with the thread context already attached.

Sender surfacing is part of that same model. Group batches include a trailing sender marker such as [from: Sender Name (+E164)], so the agent knows who is speaking. The group system prompt also tells the agent it is replying inside a group and, when metadata is available, includes group subject and members.

This is where group agents start to feel competent. They do not barge in, but when called, they understand the last few turns and address the right person.

Separate sessions protect the DM

Group sessions do not reuse the personal DM session. The docs describe keys shaped like agent:<agentId>:<channel>:group:<id>, with Telegram forum topics adding a topic thread suffix. Direct chats use the main or per-sender session, depending on configuration.

That means group-level commands are scoped to that group session. On WhatsApp, standalone commands such as /verbose on, /trace on, /think high, /new, /reset, and /compact apply to the group thread, not the personal DM. Heartbeats are skipped for group sessions so the agent does not create scheduled noise in a shared room.

This sounds like plumbing until the first incident. If a team room asks the agent to debug a support issue, that state should not bleed into the founder's private DM. If a group turns on verbose debugging, it should not make the personal assistant verbose everywhere else. Session keys are the quiet boundary that keeps those worlds apart.

Sandbox group work when the room is public

The groups docs call out a useful pattern for single-agent setups: personal DMs can stay on-host while public groups run as non-main sessions in a sandbox. Since group sessions use non-main session keys, sandbox.mode: "non-main" lets the same agent brain use different execution posture by conversation type.

That is the right mental model for shared rooms. The group can ask questions, summarize context, or coordinate lightweight actions, but it does not automatically deserve the same host access as the owner's private DM.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

In this pattern, groups get messaging and session tools, while runtime, filesystem, UI, node, cron, and gateway tools are denied. The docs are clear that tool restrictions apply in addition to global and agent policy. Deny still wins.

You can also mount a specific folder read-only into the sandbox if a group needs shared documents. Keep workspaceAccess: "none", then bind only the folder you actually want the group session to see. A team room should not inherit your whole home directory because someone typed a useful question.

Use group-level tool rules for exceptions

Some channel configs support tools and toolsBySender inside a specific group, room, or channel. The docs define sender keys with explicit prefixes such as id:, e164:, username:, and name:, plus the * wildcard. Resolution prefers the most specific matching sender rule before falling back to group and default rules.

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

That example denies exec broadly in Telegram groups, denies exec, read, and write in one specific group, then grants an explicit sender exception. I would keep exceptions rare and documented. If a group needs many sender-specific tool overrides, the room probably needs a separate agent, not a clever config block.

Do not confuse context with authority

The current docs separate trigger authorization from context visibility. Trigger authorization decides who can cause the agent to act. Context visibility describes what supplemental context may reach the model, such as replies, quotes, thread history, or forwarded metadata. The docs note that behavior is currently channel-specific and that some hardening modes are planned rather than universal today.

That is the practical warning: do not treat allowlists as a perfect redaction boundary for every quoted or historical snippet across every channel. If a room has sensitive material, restrict the room, restrict senders, keep mention gating on, and restrict tools. If the risk is higher than that, split the workspace or agent instead of hoping one setting does all the work.

Verify before inviting the team

Before you add OpenClaw to a real group, run a boring smoke test:

# Send an @openclaw ping in the group.
# Confirm the reply names the sender or responds to the right person.
# Send a second ping and verify pending context was included once.
# Check verbose gateway logs for inbound group IDs and [from: ...] markers.

I also check four things manually. First, an unmentioned message should not produce a visible reply when mention gating is on. Second, an explicit mention should include enough recent context to answer well. Third, the reply should address the right sender. Fourth, a group command should change only that group session, not a private DM.

If any of those fail, fix the group setup before you invite more people. Group agents are social infrastructure. They need to be predictable, quiet by default, and visibly useful when called.

The operator rule

Let the agent read team context only after you have decided who can trigger it, when it may speak, what session it owns, and what tools it can reach. OpenClaw gives you those controls separately because real rooms need separate boundaries.

Use allowlists to choose the room. Use mention gating to choose the moment. Use pending context so the agent understands the conversation without hijacking it. Use per-group sessions so group state stays out of DMs. Use sandbox and tool policy when a shared room should never touch the host.

That is the difference between an AI teammate and a chatty integration. One helps when invited. The other slowly teaches everyone to ignore it.

Want the complete guide? Get ClawKit — $9.99