OpenClaw in WhatsApp groups

The goal the docs state for WhatsApp groups is simple: let OpenClaw sit in a group, wake up only when pinged, and keep that thread separate from the personal DM session. The cross-channel group model supplies the policy and mention gating; WhatsApp adds activation modes, a group allowlist, per-group session keys and a specific way of injecting the messages the agent did not answer. Here is the behaviour, the config that makes display-name pings work, the activation command, how to use and test it, and the known considerations.

Behaviour

• Two activation modes: mention, the default, needs a real WhatsApp mention, a configured regex pattern, the bot’s number digits anywhere in the text, or a quoted reply to one of the bot’s messages, except in shared-number self-chat setups; always wakes the agent on every message while the injected prompt tells it to reply only when it adds value and otherwise return the exact silent token. Defaults come from the mention requirement in the groups config and can be overridden per group with the activation command.
• When a groups map is set, only listed group JIDs are admitted, with a wildcard to allow all and unlisted groups dropped with a log hint; the group policy is open, disabled or allowlist, the default allowlist using the group allow-from list with the explicit allow-from list as fallback, so groups are blocked until senders are added.
• Session keys have the shape agent, WhatsApp, group and JID, with a thread suffix for non-default accounts, so directives such as verbose, trace or a thinking level sent as standalone messages apply to that group only while personal DM state is untouched.
• Context injection is pending-only: the group messages, fifty by default, that did not trigger a run are prefixed under a since-your-last-reply block with the triggering line under a current-message block, the pending window is cleared after the run, messages already in the session are not re-injected, each line carries the sender label inside the envelope, and sender identity plus group subject and members ride in the untrusted metadata block. Ephemeral and view-once wrappers are unwrapped before extracting text and mentions, so pings inside them still trigger.

Goal: let OpenClaw sit in WhatsApp groups, wake up only when pinged, and keep that thread separate from the personal DM session.

Config and prompt

The docs’ example makes display-name pings work even when WhatsApp strips the visual at-sign from the text body: a wildcard group requiring a mention, a history limit of fifty for the pending window, and agent mention patterns for an optional at-sign before the name plus the bot’s number. The regexes are case-insensitive under the same safe-regex guardrails as other config surfaces, canonical mentions still arrive as mentioned JIDs when someone taps the contact so the number fallback is a safety net, and the pending window resolves from the account’s history limit, then the channel’s, then the global group-chat limit, then fifty. The first turn of a group session, and any turn after the activation mode changes, injects activation guidance into the system prompt, trigger-only or always-on plus an instruction to address the specific sender, and the persistent group-chat delivery guidance is always included.

Use, test, know

• Add the WhatsApp account running OpenClaw to the group, ping it by name or number, and only allowlisted senders trigger it unless the policy is open; the prompt includes the pending context and sender-labelled lines so the agent addresses the right person, and session directives including new, reset and compact apply only to that group when sent as standalone messages.
• The activation command is owner-only: mention or always, accepted only from owner numbers, the allow-from list or the bot’s own number when unset, ignored and stored as context from anyone else; a standalone status command in the group shows the current mode. A manual smoke test is a ping that gets a reply naming the sender, a second ping that shows the history block, and a check that the block is cleared on the next turn, with verbose Gateway logs showing inbound entries from the group JID.
• Heartbeats run in the main session and never in groups; echo suppression remembers the combined prompt per session so the bot’s own delivered messages do not retrigger it and an identical repeated batch can be skipped as an echo; a missing session-store entry only means the group has not triggered a run yet; and typing indicators follow the agent’s typing mode, starting immediately when visible replies are message-tool-only so members see the agent working.

OpenClaw group chats is the cross-channel model this behaviour sits on, and OpenClaw on WhatsApp the channel post with the system-prompt rules for direct and group chats.

Why pending-only matters

Injecting only the messages that did not trigger a run keeps the context honest: the model sees what the room said since its last reply, labelled by sender, without re-reading what it already answered. OpenClaw sessions explains the per-group keys that make directives local, and OpenClaw thinking levels the level a group can set for itself without touching your DMs.

On Diali

On Diali the WhatsApp channel is the account you link from the dashboard, so the assistant sits in whichever groups that number is in; mention-only activation is the default, and the owner numbers for the activation command are the ones on the allowlist you set. Hosted OpenClaw on Diali is the assistant and Connect your first channel in five minutes how the account is linked.

• Mention by default; always with the silent token in reserve.
• One session per group; directives stay local.
• Pending messages in, cleared after the run.