OpenClaw in WhatsApp Groups: Setup, Permissions, and Best Practices

Adding OpenClaw to a WhatsApp Group

OpenClaw connects to WhatsApp through the WhatsApp Web bridge (using the Baileys library). The same WhatsApp session that handles direct messages also works in groups — you do not need a separate setup for group functionality.

To enable group support, add these environment variables to your .env file:

# Enable group message handling
OPENCLAW_WA_GROUPS_ENABLED=true

# Whitelist specific groups (recommended)
# Use group JIDs — find them in logs when the agent joins a group
OPENCLAW_WA_GROUP_WHITELIST=120363012345678901@g.us,120363098765432109@g.us

# Or allow all groups (not recommended for production)
# OPENCLAW_WA_GROUP_WHITELIST=*

After adding the environment variables, restart OpenClaw. Then add the phone number that OpenClaw uses to your WhatsApp group. You will see a log entry confirming the group was detected:

[INFO] WhatsApp: Joined group "Team Chat" (120363012345678901@g.us)

If you do not see this log entry, check that the group JID is in your whitelist and that OPENCLAW_WA_GROUPS_ENABLED is set to true.

Mention Triggers and Trigger Words

In group chats, you almost never want the agent to respond to every message. That would be noisy, expensive, and annoying. Instead, OpenClaw uses triggers to decide when to respond.

@Mention trigger (default): The agent only responds when someone mentions its WhatsApp contact name in the message. For example, if the agent's WhatsApp name is "Atlas," then "@Atlas what's the schedule for tomorrow?" triggers a response, but "what's the schedule for tomorrow?" does not.

Custom trigger words: You can define custom words or phrases that trigger the agent:

# Custom trigger words (comma-separated)
OPENCLAW_WA_GROUP_TRIGGERS=!ask,!help,hey atlas

# Now these messages will trigger the agent:
# "!ask what's the revenue this month?"
# "!help I need the client list"
# "hey atlas can you schedule a meeting?"

Reply trigger: If someone replies directly to one of the agent's previous messages in the group, the agent treats that as a trigger and responds, maintaining conversational continuity.

All-messages mode: Setting OPENCLAW_WA_GROUP_RESPOND_ALL=true makes the agent respond to every message in the group. This is useful for small, dedicated groups (like a 2-person team chat) but not recommended for groups with more than 3-4 members.

Group Permissions

You can control who in a group is allowed to trigger the agent. This prevents unauthorized users from consuming your API credits or accessing your agent's capabilities.

# Only allow specific phone numbers to trigger the agent in groups
OPENCLAW_WA_GROUP_ALLOWED_USERS=1234567890@s.whatsapp.net,0987654321@s.whatsapp.net

# Or restrict to group admins only
OPENCLAW_WA_GROUP_ADMIN_ONLY=true

When a non-permitted user tries to trigger the agent, you can configure the behavior:

# Options: ignore (default), reply_denied, reply_custom
OPENCLAW_WA_GROUP_DENIED_ACTION=ignore

# Custom denial message
OPENCLAW_WA_GROUP_DENIED_MESSAGE=Sorry, I can only respond to admins in this group.

For business groups where the agent interacts with clients, you will typically use admin-only mode. For internal team groups, you might allow all members. For mixed groups, use the allowed users whitelist.

Privacy Considerations

Running an AI agent in a group chat raises privacy questions that you need to address proactively:

Message reading: By default, OpenClaw reads all messages in whitelisted groups for context, even those that do not trigger a response. This means the AI model sees group messages as part of its context window. If group members are sharing sensitive information they do not want processed by an AI, this is a problem.

You can disable passive reading:

# Disable passive reading — agent only sees messages that trigger it
OPENCLAW_WA_GROUP_PASSIVE=false

Inform group members: Best practice is to inform all group members that an AI agent is present. Pin a message explaining what the agent does, how to trigger it, and what data it processes. In some jurisdictions, this may be legally required.

Memory in groups: By default, OpenClaw can store memories from group conversations. If you do not want group content saved to memory files, disable it:

OPENCLAW_WA_GROUP_MEMORY_WRITE=false

Data processing: Remember that messages sent to the agent are processed by your AI model provider (Anthropic, OpenAI, etc.). Review the provider's data policy and ensure it is compatible with the sensitivity of your group conversations.

The 3.22 Echo Bug

OpenClaw version 3.22.0 shipped with a bug that affected group deployments. The bug caused the agent to detect its own outgoing messages as incoming messages, creating an infinite feedback loop. The agent would send a response, detect that response as a new message, generate another response, detect that one, and so on — rapidly burning through API credits.

The root cause was a missing sender check in the group message handler. The handler processed all messages in whitelisted groups, including messages sent by the agent itself.

Symptoms:

• The agent sends multiple rapid responses to a single message
• Responses reference the agent's own previous responses
• API costs spike dramatically
• The group is flooded with agent messages

Fix: Update to OpenClaw 3.22.1 or later. The fix adds a sender origin check that filters out messages from the agent's own phone number before processing.

# Update OpenClaw
docker compose pull
docker compose up -d

If you cannot update immediately, a workaround is to set OPENCLAW_WA_GROUP_RESPOND_ALL=false and rely on @mention triggers, which are less susceptible to the echo bug because the agent does not @mention itself in responses.

Admin Controls

Operators can manage the agent's group behavior without restarting OpenClaw by using in-chat admin commands:

# Pause the agent in the current group
@Atlas !pause

# Resume the agent
@Atlas !resume

# Change the trigger word temporarily
@Atlas !trigger !bot

# Show current group settings
@Atlas !settings

# Clear the agent's memory of this group's conversation
@Atlas !forget-group

Admin commands are only available to users listed in OPENCLAW_WA_GROUP_ALLOWED_USERS or group admins when OPENCLAW_WA_GROUP_ADMIN_ONLY=true.

For operators managing multiple groups, the OpenClaw web UI provides a group management panel where you can see all connected groups, their whitelist status, trigger configuration, and message statistics. This is accessible at http://your-server:3000/admin/groups.

Best Practices

After deploying OpenClaw to hundreds of WhatsApp groups, here are the practices that work best:

• Always use a whitelist. Never set OPENCLAW_WA_GROUP_WHITELIST=* in production. A whitelist prevents the agent from accidentally responding in groups you did not intend it to be in.
• Use @mention triggers. They are the most natural interaction pattern for group chats. People are already accustomed to @mentioning others in groups.
• Set a clear agent name. The WhatsApp contact name should make it obvious that it is a bot. "Atlas AI" or "TeamBot" is better than a generic person's name.
• Pin an intro message. When the agent joins a group, pin a message explaining: who it is, how to trigger it, what it can do, and what data it processes.
• Disable passive reading for sensitive groups. If the group discusses confidential business matters, disable passive reading to minimize data exposure.
• Monitor API costs. Group deployments can be expensive if the group is active and the agent is triggered frequently. Set up cost alerts with your AI model provider.
• Update past 3.22.0. If you are on version 3.22.0, update immediately to avoid the echo bug.
• Test in a small group first. Create a test group with 2-3 people and verify everything works before deploying to a production group.
• Set rate limits. Use OPENCLAW_WA_GROUP_RATE_LIMIT=10 to limit the agent to 10 responses per minute per group. This prevents runaway costs and message flooding.