OpenClaw Group Chats Guide: groupPolicy vs groups vs groupAllowFrom vs requireMention, and Why Your Bot Ignores the Room

An OpenClaw agent answers in a group only after four checks pass, in this order: groupPolicy, the group allowlist under groups, the sender list in groupAllowFrom, and mention gating through requireMention. The defaults block every group until you list it, then reply only when someone mentions the bot. For a room other people can type in, keep mentions required, deny exec for "*", and run group sessions in a sandbox with mode: "non-main".

You added the bot to the team Telegram group, pasted -1001234567890 into groupAllowFrom, restarted the gateway, and typed "hey can you summarize this thread." Nothing. Not an error, not a typing indicator. The bot answers you in DMs within two seconds, so you start suspecting the Telegram token.

The token is fine. That chat ID is in the wrong list.

I worked from the official Groups page, the Telegram access control page and the mention gating and history config reference, as published on November 7, 2026. Key names and defaults below come from those pages. Where I recommend something the docs don't, I say so.

Four gates, checked in order

Every inbound group message walks the same path on Discord, iMessage, Matrix, Microsoft Teams, QQBot, Signal, Slack, Telegram, WhatsApp and Zalo. A message that fails a gate stops there.

One trap sits outside the table. If a channel's provider block is missing from config entirely, its group policy falls back to allowlist rather than inheriting your defaults, so a brand-new channel starts closed to groups no matter what you set elsewhere.

groups lists rooms, groupAllowFrom lists people

This is the bug from the opening, and it is the one I see most. On Telegram, channels.telegram.groups decides which groups are allowed. Its keys are negative chat IDs like -1001234567890, or "*" for all of them. groupAllowFrom decides which senders inside those groups can trigger the agent, and it takes numeric Telegram user IDs only. The docs say plainly that it is not a group allowlist and should not contain group chat IDs. Non-numeric entries are ignored, and @username entries don't match at runtime.

channels: {
  telegram: {
    groupPolicy: "allowlist",
    groupAllowFrom: ["123456789"],          // people: your numeric user ID
    groups: {
      "-1001234567890": { requireMention: true },   // rooms: the group chat ID
    },
  },
}

To find the chat ID, forward a group message to @userinfobot or @getidsbot, or watch chat.id scroll past in openclaw logs --follow while someone posts. Once the group is allowed, /whoami@<bot_username> works too.

Telegram adds one more requirement before any of this matters: ordinary group messages reach the bot only if you disable privacy mode or make the bot a group admin. Without that, OpenClaw never sees the message, and no config change will help.

Other channels shift the names around. WhatsApp, Signal, iMessage, Teams and Zalo use groupAllowFrom with the same fallback to allowFrom. Signal's list matches a group ID or a sender's phone number or UUID. For iMessage, prefer chat_id:<id> keys; imsg chats --limit 20 lists them. And DM pairing never authorizes a group. Approving someone's DM does not let them trigger the bot in a room; group triggers still need an explicit sender allowlist such as groupAllowFrom.

What counts as a mention

Native platform mentions always count. Text patterns count as a fallback, and they are case-insensitive regexes:

agents: {
  entries: {
    main: {
      groupChat: {
        mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
        historyLimit: 50,
      },
    },
  },
}

Precedence runs from the agent's groupChat.mentionPatterns, to messages.groupChat.mentionPatterns, to patterns OpenClaw derives from the agent's identity.name and identity.emoji. That last step surprises people. Name your agent "Max" in a room where a human is also called Max and the bot will answer half of their messages. An explicit mentionPatterns: [] stops the derivation. Invalid or unsafe patterns are skipped with a warning, so a typo in a regex looks exactly like the bot ignoring you.

Some platforms also produce implicit mentions. Replying to the bot counts on Discord, Teams, QQBot, Slack and Telegram. Quoting it counts on LINE, WhatsApp and Zalo personal. On Mattermost, Slack and Tlon, the bot having joined a thread counts; set implicitMentions: false on LINE, Mattermost, Slack or Tlon to stop that.

Unmentioned messages are not thrown away. They are kept as context, up to historyLimit (set globally at messages.groupChat.historyLimit, per channel at channels.<channel>.historyLimit, and 0 disables it). When someone finally mentions the bot, it has read the last 50 messages, which is usually what "summarize this thread" needs.

/activation always, owner only

Sending /activation always in a group makes every message a trigger; /activation mention puts gating back. Only an owner can do it, meaning a sender who matches commands.ownerAllowFrom. The stored mode overrides requireMention, but only on Google Chat, QQBot, Telegram and WhatsApp. On Slack or Discord you change requireMention in config instead.

My opinion, and the docs don't take a side: always belongs in a two-person room, you and the bot, or a room built for the bot. In a twelve-person channel it turns every "lol" into a model call and every model call into a reply nobody asked for. If you want the agent to read everything but speak rarely, set messages.groupChat.unmentionedInbound: "room_event", which treats unmentioned chatter as quiet room context while mentions, commands and DMs stay user requests.

Typing, then silence

The bot shows the typing indicator, the log says dispatch complete (queuedFinal=false, replies=0), and the room gets nothing.

That is almost always visibleReplies: "message_tool", set at messages.visibleReplies or messages.groupChat.visibleReplies. In that mode the agent's final text stays private, and only an explicit message(action=send) call posts to the room (Claude CLI runs call it mcp__openclaw__message). A model that is weak at tool calling answers you in its head and never sends. The fixes, from the docs: switch to a model with stronger tool calling, delete the override, or set messages.groupChat.visibleReplies back to "automatic", the default. The gateway hot-reloads messages config, so you usually don't need a restart.

Lock down tools per group

A group config entry takes its own tools block (allow, alsoAllow, deny; deny wins) and a toolsBySender map for exceptions:

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

Resolution goes from most specific to least: the group's toolsBySender, the group's tools, then the default toolsBySender and default tools. Sender keys take prefixes: id:, e164:, username:, name:, channel:<channelId>:, or "*".

Use id: for anything that grants a tool. Usernames and display names can be changed by the person they belong to, so a name: key that grants exec is a grant to whoever renames themselves to match. If your config predates the prefixes, openclaw doctor --fix migrates the old unprefixed keys. For the wider allow and deny model, see the tool allow/deny guide.

Sessions, and the groupScope trap

Each group gets its own session, keyed agent:<agentId>:<channel>:group:<id> (rooms and channels use :channel:<id>, and Telegram forum topics append :topic:<threadId>). DMs use the main session. Group sessions don't run their own heartbeats.

That split is what makes the docs' recommended pattern work. Set agents.defaults.sandbox to mode: "non-main" with scope: "session" and workspaceAccess: "none", and every group runs inside a sandbox while your DMs keep full tools on the host. The docs pair it with a tools.sandbox.tools allow list of group:messaging and group:sessions, and a deny list of group:runtime, group:fs, group:ui, nodes, cron and gateway.

Then someone sets session.groupScope: "main" so the family chat can share the agent's main conversation, and that room is now main. The non-main sandbox no longer covers it. It gets host tools and your DM history, and nothing about admission or mention gating changes to warn you. I would only use groupScope: "main" for a room where every member already has access to your DMs. If two personas must never mix, use a second agent with bindings.

Threads the bot started

requireMentionInBotThreads: false lets people reply in a thread or forum topic the bot created without @-ing it again, while the rest of the channel still needs a mention, and the docs say a bot replying in someone else's thread does not become its creator, so this never leaks into threads humans started.

Who supplied the context

Gates 1 to 4 decide who can trigger the agent. A separate setting, contextVisibility, decides whose words reach the model as supplemental context, such as quoted text or thread history. The default "all" passes everything through. "allowlist" keeps only context from allowlisted senders, and "allowlist_quote" does the same but still includes the one message being replied to.

In an open community channel I would set allowlist_quote. A stranger can't trigger your agent, but under "all" they can still write the thread history it reads when you do.

Where each setting fits (and where it does not)

groupPolicy: "allowlist" with listed groups fits almost everyone. Keep it.

groupPolicy: "open" fits a bot meant to be added to strangers' groups, such as a public utility bot, with mention gating left on and tools stripped. For a personal agent with access to your files it is the wrong choice; the security audit flags open groups combined with elevated tools for a reason.

groupAllowFrom wins when only you, or a short list of operators, should trigger the agent in a shared room. It loses when the whole team should be able to ask; leave it at the allowFrom fallback and rely on mentions and per-group tool denies.

requireMention: false or /activation always fits a room built for the bot. Anywhere busier, prefer unmentionedInbound: "room_event".

visibleReplies: "message_tool" fits agents that should decide whether to speak at all, on models you have tested for tool calling. On anything else it produces the silent bot.

Final verdict

Leave groupPolicy at allowlist, put room IDs under groups and human user IDs under groupAllowFrom, keep requireMention: true on "*", and deny exec there too. Sandbox groups with mode: "non-main" and don't undo it with groupScope: "main". Then open your config and search for -100. If it shows up inside a groupAllowFrom array, you have found why the bot ignores the room.