Managing WhatsApp Group Chats with OpenClaw

I’ve often found that putting an AI agent into a group chat is a recipe for chaos. It either ignores everyone or, worse, replies to every single message, cluttering the thread and burning through API credits. Managing context while keeping group conversations separate from personal DMs is usually a headache. I want my agent to be smart enough to stay quiet until it’s actually needed.

What You’ll Need

• A WhatsApp account running OpenClaw.
• The ~/.openclaw/openclaw.json configuration file.
• Owner-level access to the WhatsApp account (for activation commands).
• Group admin permissions (to add the bot account to the group).

Quick Start

Setting up your agent to handle WhatsApp groups takes about five minutes. Here is the path to get it running.

1. Update your configuration

Add a groupChat block to your ~/.openclaw/openclaw.json. This ensures the agent recognizes its name even if WhatsApp strips the visual @ symbol.

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw", "\\+?15555550123"],
        },
      },
    ],
  },
}

2. Join and trigger

Add your WhatsApp account to the target group. By default, the groupPolicy is set to allowlist, so only senders in your allowFrom list can trigger the agent. You can change this to open in your config if you want anyone in the group to be able to ping the agent.

To get a response, simply say @openclaw followed by your message. The agent will see the last 50 messages for context, but it only replies when it identifies a mention or its phone number in the text.

3. Manage activation modes

If you are the owner, you can change how the agent behaves directly within the group chat using these commands:

• /activation mention: The agent only wakes up when pinged.
• /activation always: The agent reads every message but only replies if it can add value (otherwise it stays silent).

4. Use group-specific commands

Group sessions are independent of your personal DMs. You can send commands as standalone messages to adjust the agent’s behavior for that specific group:

• /verbose on or /think high to change output depth.
• /status to see the current activation mode.

Troubleshooting

The agent isn’t replying to anyone. Check your channels.whatsapp.groupPolicy. It defaults to allowlist. If the group members aren’t in your allowFrom list, the agent will ignore them. Set the policy to open to allow everyone to interact with it.

The agent is replying to its own messages or being too noisy. Check your mentionPatterns. If they are too broad, the agent might trigger accidentally. Also, ensure requireMention is set to true in your group config.

Commands sent in the group are affecting my private DM session. This shouldn’t happen. Session keys for groups are scoped specifically to the group JID (e.g., agent:<agentId>:whatsapp:group:<jid>). If you feel the state is messy, send /reset or /new inside the group to clear that specific session without touching your DMs.

The agent doesn’t know who is talking. OpenClaw automatically suffixes messages with [from: Sender Name (+E164)]. If the agent still seems confused, verify that the group metadata is available to the bot account.

If you need more help getting your group settings dialed in, check out the AI Setup Assistant.

What’s Next

• WhatsApp Channel Configuration
• Agent Session Management
• Command Reference
• Setting up Mention Patterns