OpenClaw WhatsApp setup: QR pairing, access policy, and groups

An OpenClaw WhatsApp setup is not finished when the QR code scans. That only links the account. The useful safety boundary comes next: decide who can start a DM, which groups the agent may enter, and where each conversation is routed. Start with a dedicated number if you can. It makes the first week of testing much less stressful.

OpenClaw’s current WhatsApp channel is production-ready through WhatsApp Web and Baileys. The Gateway owns the linked session, reconnect loop, and message delivery. It is not a Twilio channel, and it should not be treated like an unattended public bot.

What you need before connecting WhatsApp

Have a working OpenClaw Gateway, a phone that can scan a WhatsApp linked-device QR code, and a clear answer to one question: is this a personal assistant number or a separate work number?

A separate number is the safer default. It keeps personal conversations out of an early agent experiment and gives you a clean allowlist. Use it to test routing, groups, and permissions without mixing in private chats.

If you are still deciding where OpenClaw fits, read what OpenClaw is and how its Gateway model works first. A WhatsApp connection is a message channel into that Gateway, not a separate assistant that happens to share your phone.

Install and link the WhatsApp channel

The onboarding flow can install the channel when you select it. For an existing installation, add the channel and log in:

openclaw channels add --channel whatsapp
openclaw channels login --channel whatsapp

If the plugin is missing, the channel commands offer the install flow. The documented manual path is:

openclaw plugins install clawhub:@openclaw/whatsapp

The QR login links the WhatsApp account to the Gateway. It does not approve strangers to message the agent. On a remote server, make sure the live QR can reach your phone before starting the command. A screenshot or terminal output that arrives late can be useless because the code may expire.

Start or restart the Gateway after linking:

openclaw gateway

For a second account, add an account name to the login command:

openclaw channels login --channel whatsapp --account work

That separation is worth using when one account is personal and another is for a team or customer workflow.

Choose the access policy before the first message

The documented default DM policy is pairing for unknown senders. That gives you a review step instead of letting every new number create an agent session. A conservative starting configuration looks like this:

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

The phone number in the example is a placeholder. Replace it with the people who should be able to reach the agent. Do not copy an allowlist from an example into production and assume it is safe.

Situation	DM policy	Group policy	Why
First test with a dedicated number	pairing	allowlist	You review new senders and keep groups closed by default.
Personal self-chat workflow	allowlist with your own number	allowlist	The agent can answer your own messages without opening DMs broadly.
Small trusted team	allowlist	allowlist	Every permitted sender and group is explicit.
Public or large community	Do not start here	Do not start here	A messaging channel is an input surface, not a comment box.

For a personal-number fallback, OpenClaw documents a self-chat-friendly baseline using dmPolicy: "allowlist", your own number in allowFrom, and selfChatMode: true. Treat that as a different operating mode. It is convenient, but it also puts your ordinary WhatsApp account closer to agent behavior.

Approve DMs separately from QR login

There are two approvals that people often collapse into one. The QR code authenticates the WhatsApp account to the Gateway. Pairing approves a sender to use the agent.

With dmPolicy: "pairing", inspect and approve the request after the sender messages the account:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

The official channel documentation says DM access requests expire after one hour and are capped at three per account. Review them while the request is still fresh. If a number is unfamiliar, decline it rather than trying to infer intent from a greeting.

OpenClaw 2026.8.1 also added structured questions that can be answered through cards, messaging buttons, or plain text, with a skip path. That makes a deliberate approval habit more valuable: the channel can become an interaction surface, not only a text relay. See the 2026.8.1 release notes for the exact release scope.

Keep group conversations narrow

Group chat is where a helpful assistant can become noisy or risky fastest. Use groupPolicy: "allowlist" and add groups one at a time after you have tested direct messages. Do not use a group as a place to discover who should be allowed.

OpenClaw keeps direct chats under its DM session rules and, by default, isolates group sessions per group. That is useful for keeping one group’s context out of another, but it does not replace access control. Configure group admission first, then decide whether the agent should require a mention, what system prompt applies, and which actions are available in that group.

If you need a broader phone-level overview, connect OpenClaw to your phone covers the everyday workflow. For the security model behind the choices here, use the site’s OpenClaw safety guide. The practical rule is simple: open a little access, observe the resulting behavior, then expand.

Test delivery and recovery before adding automations

Send a harmless direct message from an approved number after the Gateway starts. Then test one permitted group. Check that replies land in the intended account and that the right session receives the context.

The WhatsApp runtime tracks transport activity separately from application-message activity. A quiet chat alone should not cause a reconnect. An inactive or missing listener for the target account causes outbound sends to fail fast. That is better than silently claiming a message was sent, but it also means scheduled work needs a real delivery check.

Use this short test sequence:

1. Link the account and start the Gateway.
2. Send a direct message from an approved sender.
3. Confirm a pairing request appears for an unapproved sender instead of an agent reply.
4. Add one trusted group to the allowlist and test with an ordinary text question.
5. Restart the Gateway once and confirm the linked account reconnects.
6. Only then add reminders, cron jobs, or message-sending tools.

The operational lesson is simple: a clean QR scan proves very little by itself. Verify delivery, sender approval, and recovery before you put an agent in a live conversation.

FAQ

Does OpenClaw use the WhatsApp Business API?

No. The current documented channel runs through WhatsApp Web with Baileys, and the Gateway owns the linked session. The official channel page explicitly says there is no separate Twilio WhatsApp channel.

Should I link my personal WhatsApp number?

You can, but a dedicated number is safer for initial testing. It separates private conversations from the agent’s DM and group rules. If you do use a personal number, start with your own number in an explicit allowlist and test self-chat behavior before adding anyone else.

Why did a sender need approval after I scanned the QR code?

QR login links the account. Pairing controls who may use the agent through that account. They protect different boundaries.

Can OpenClaw reply in WhatsApp groups?

Yes, once the group is admitted by your group policy and configured for the account. Start with a specific group allowlist rather than broad group access, then test mentions and routing with low-risk requests.

The reliable OpenClaw WhatsApp setup

Use the QR to link a dedicated account, keep DMs on pairing or an explicit allowlist, admit groups individually, and test a restart before you automate delivery. That sequence is slower than a five-minute demo. It is also how you keep a convenient agent channel from becoming an uncontrolled one.

Sources: OpenClaw WhatsApp channel documentation | OpenClaw pairing documentation | OpenClaw 2026.8.1 release notes