If you want an AI agent in the chat app you already check all day, OpenClaw WhatsApp support is one of the more practical routes. It lets a self-hosted OpenClaw gateway receive and send WhatsApp messages through a linked WhatsApp Web session, then route those messages into the same agent loop, tools, memory, and access controls you use for other channels.
The important detail is this: OpenClaw does not treat WhatsApp like a generic webhook project. It is not Twilio. It is not a from-scratch Meta Cloud API bot. The current OpenClaw channel uses WhatsApp Web through the external @openclaw/whatsapp plugin, backed by Baileys. That difference changes the setup. You scan a QR code, keep the gateway running, control who can talk to the agent, and watch transport health like an operator.
That is a good trade for personal agents, internal operators, and small teams. It is also the part most generic WhatsApp bot tutorials miss.
What the OpenClaw WhatsApp channel actually is
OpenClaw’s docs describe the WhatsApp channel as production-ready via WhatsApp Web using Baileys. The gateway owns the linked session and reconnect loop. There is no separate Twilio WhatsApp channel in this model, and the WhatsApp runtime ships outside the core OpenClaw package as an external plugin.
In practice, that means the Gateway becomes the owner of the WhatsApp socket. A message comes in through the linked WhatsApp account, OpenClaw checks the channel’s access rules, maps the conversation to a session, and then passes the request into the agent. Replies go back through the active WhatsApp listener for that account.
This is very different from the official WhatsApp Business Platform path. Meta’s Cloud API uses webhook endpoints, app permissions, phone number IDs, access tokens, and subscribed webhook fields. Meta’s webhook docs say the messages webhook carries incoming messages and outgoing message statuses, and failed webhook delivery can be retried for up to 7 days. That model is right for many business apps. It is not the shape OpenClaw chose for its WhatsApp channel.
OpenClaw’s shape is simpler for a self-hosted assistant: link a WhatsApp identity, lock down sender access, and run the Gateway.
Before you start: use the right WhatsApp number
The docs recommend a separate WhatsApp number for OpenClaw. That is the advice I would follow for any setup you expect to keep.
A dedicated number gives the agent a clean identity. It makes allowlists easier to reason about, keeps personal chats out of the agent’s blast radius, and reduces self-chat confusion. If the agent is meant to answer your own private requests from your phone, a personal-number setup can work. OpenClaw supports that too, including selfChatMode. But a dedicated number is cleaner once groups, scheduled messages, approvals, or multiple accounts enter the picture.
Think of the number as part of the agent boundary. If the same WhatsApp account is also your real personal inbox, every configuration mistake feels more expensive.
Install the WhatsApp channel plugin
The easiest path is through OpenClaw’s normal channel flow. The docs say openclaw onboard, openclaw channels add --channel whatsapp, and openclaw channels login --channel whatsapp can prompt for plugin installation when the WhatsApp plugin is missing.
If you want the manual command, install it from ClawHub:
openclaw plugins install clawhub:@openclaw/whatsappFor stable and beta installs, OpenClaw tries ClawHub first and falls back to npm. Dev checkouts use the local plugin path. You normally do not need to pin a package version unless you are building a reproducible server image and want every dependency frozen.
After installation, add the channel:
openclaw channels add --channel whatsappFor multi-account setups, name the account early:
openclaw channels add --channel whatsapp --account workThat account name matters later because channel config, auth state, pairing, and troubleshooting can all be account-scoped.
Configure access before you scan the QR
Do not connect WhatsApp first and think about access later. Set a narrow policy up front. A minimal config might look like this:
{
channels: {
whatsapp: {
dmPolicy: "pairing",
allowFrom: ["+15551234567"],
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
},
},
}The practical options are:
pairing: unknown DM senders request access and wait for approval.allowlist: only configured or already approved senders get in.open: public only when the effective allowlist includes"*".disabled: block DMs.
For most people, pairing is the best starting point. It lets you avoid editing config for every first contact, but it still blocks unknown senders until you approve them. Open access is rarely the right move for an agent that can use tools, remember context, or trigger actions.
Groups need separate thought. OpenClaw’s WhatsApp docs split group access into membership allowlists and sender policy. That is worth keeping: a group can be eligible, while only trusted senders inside that group can activate the agent. In shared chats, that extra check keeps casual noise from turning into agent work.
Link WhatsApp with QR login
Once the plugin and access policy are in place, start QR login:
openclaw channels login --channel whatsappFor a named account:
openclaw channels login --channel whatsapp --account workOpenClaw’s WhatsApp login is QR-only. On a local machine, that is simple enough. On a remote VPS, plan the QR path before running the command. Terminal QR rendering, screenshots, or chat attachments can expire before you scan them, especially if you are working through a slow remote shell. Have the phone ready and know where the QR will appear.
If you need a custom auth directory, attach it before login:
openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account workTreat that auth directory like a credential. It is a linked device session. Do not leave it world-readable, sync it casually, or paste it into support tickets.
Start the gateway and approve the first sender
After the account is linked, start the Gateway:
openclaw gatewayIf your DM policy is pairing, the first unknown sender does not immediately reach the agent. OpenClaw creates a DM access request. The docs make a useful distinction here: WhatsApp QR login links the WhatsApp account to OpenClaw; DM pairing approves a person who messages that account. Those are separate flows.
You can approve from the Control UI under Settings -> Channels -> DM access requests, or use the CLI:
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>Pairing codes are short-lived. OpenClaw’s pairing docs say they expire after 1 hour, and pending DM pairing requests are capped at 3 per channel account. That cap is a small but useful guardrail. If an exposed number starts receiving random messages, the pending request list cannot grow forever.
How WhatsApp messages move through OpenClaw
The runtime model is more interesting than the install command. OpenClaw tracks transport activity and application-message activity separately. A quiet but connected session should not be restarted just because nobody sent a message recently. Reconnects happen when the transport stops behaving, or when message silence crosses OpenClaw’s internal thresholds.
For an operator, this matters because “no reply” does not always mean the agent is broken. It might be an access rule. It might be a group mention rule. It might be the WhatsApp transport. It might be a stale local client hurting the event loop. The troubleshooting path starts with proving which layer is failing.
OpenClaw also makes some deliberate routing choices:
- Status and broadcast chats are ignored.
- Outbound sends require an active WhatsApp listener for the target account.
- Direct chats use DM session rules.
- With the default group scope, group sessions are isolated per group JID.
- WhatsApp Channel or Newsletter JIDs can be explicit outbound targets when configured as native targets.
The clean part is that WhatsApp becomes another OpenClaw channel. The serious part is that every channel still has its own delivery weirdness, identity model, and security surface.
Groups, mentions, and session isolation
WhatsApp groups deserve a separate setup pass. A private DM bot and a group-visible agent are not the same product.
Start with group allowlists. Then decide who inside the group can activate the agent. Then decide whether the agent should require a mention. In common OpenClaw configuration, group messages require a mention by default. That is usually correct. It prevents the agent from treating every bit of group chatter as a request.
The default group session behavior is also sensible: each group gets its own isolated session based on the group JID. That avoids mixing one group’s conversation with another group’s context. If you are running operational groups, incident groups, or customer-facing rooms, that separation is not optional housekeeping. It is the difference between helpful memory and embarrassing context bleed.
Use a simple rollout:
- Test one trusted DM sender.
- Add one test group with mention required.
- Confirm the agent sees mentions and ignores unmentioned chatter.
- Add scheduled or tool-heavy workflows only after access rules are boring.
Troubleshooting the common failures
Start with the OpenClaw command ladder:
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probeFor WhatsApp specifically, the docs call out a few fast checks:
- If WhatsApp is connected but DMs get no reply, run
openclaw pairing list whatsappand check whether the sender still needs approval. - If group messages are ignored, check the group policy, group allowlist, and mention requirement.
- If QR login times out with a 408, inspect gateway proxy environment variables such as
HTTPS_PROXY,HTTP_PROXY, andNO_PROXY. - If reconnect loops continue, probe channel status, watch logs, restart the gateway, and relink only if the loop persists.
- If replies are delayed, run
openclaw doctor --fix; the docs note that stale local TUI clients can degrade the Gateway event loop.
The best troubleshooting habit is to avoid relinking too early. Relinking might be necessary, but it should come after access policy, logs, probe status, and host connectivity have been checked. Otherwise you can replace a clear config problem with a fresh auth problem.
OpenClaw WhatsApp vs Meta Cloud API
If your goal is a business messaging product, the official WhatsApp Business Platform deserves a look. Meta’s webhook model is built around server endpoints, permissions, subscribed fields, app review, message statuses, template workflows, and business account events. It is the official road for many customer-support and marketing systems.
OpenClaw’s WhatsApp channel is better understood as a self-hosted assistant channel. It uses a linked WhatsApp Web session, so the operational questions are different:
- Is the linked session alive?
- Which WhatsApp account owns this channel?
- Who is allowed to DM it?
- Which groups are eligible?
- Does the group require a mention?
- Which OpenClaw session receives the message?
That is not a weakness. It is the point. For a personal agent, a founder’s private ops bot, or an internal team assistant, building a full Cloud API app can be too much machinery. OpenClaw gives you the channel quickly, while still forcing you to make explicit access decisions.
There is one caveat worth saying plainly: Baileys itself states that it is not affiliated with, authorized by, or endorsed by WhatsApp. Do not use this setup for spam, bulk outreach, or anything that would abuse the platform. OpenClaw is best here as a controlled assistant endpoint, not a blasting engine.
Recommended production checklist
Before you depend on WhatsApp for real work, run through this list:
- Use a dedicated WhatsApp number when possible.
- Keep
dmPolicyonpairingorallowlist. - Add group access only after DM testing passes.
- Require mentions in groups unless there is a strong reason not to.
- Keep auth state private and backed up carefully.
- Run
openclaw channels status --probeafter setup. - Document which account name maps to which WhatsApp number.
- Review plugin hook settings before exposing inbound WhatsApp content to other plugins.
That last point is easy to miss. Inbound WhatsApp messages can contain personal content, phone numbers, group identifiers, sender names, and session correlation fields. OpenClaw’s docs say WhatsApp does not broadcast inbound message_received hook payloads to plugins unless you opt in. Keep it that way unless you know exactly which plugin needs the data.
FAQ about OpenClaw WhatsApp
Does OpenClaw use Twilio for WhatsApp?
No. The OpenClaw docs state that there is no separate Twilio WhatsApp channel. The current channel is production-ready through WhatsApp Web using Baileys.
Is this the same as the WhatsApp Cloud API?
No. The Cloud API is Meta’s official webhook and Graph API path for WhatsApp Business Platform apps. OpenClaw’s WhatsApp channel links a WhatsApp Web session to the Gateway.
Can I use my personal WhatsApp number?
Yes. OpenClaw supports personal-number and self-chat setups. Still, a dedicated number is the better long-term choice because it gives the agent a clearer identity and cleaner access boundaries.
Why is my first WhatsApp DM not reaching the agent?
If dmPolicy is set to pairing, an unknown sender must be approved first. Check openclaw pairing list whatsapp or the Control UI’s DM access requests page.
Why does the bot ignore WhatsApp group messages?
Check three things: whether the group is allowed, whether the sender is allowed by group policy, and whether the message mentions the agent. Group mention gating is often the missing piece.
What should I monitor after setup?
Watch openclaw channels status --probe, Gateway logs, pairing requests, and reconnect patterns. If sends fail, confirm the target account has an active WhatsApp listener.
Final take
Connecting WhatsApp to an AI agent sounds like a webhook task until you look at OpenClaw’s design. Here, WhatsApp is a linked channel owned by the Gateway. That makes setup faster, but it also makes access control and session health the real work.
Start narrow. Link one number, allow one sender, test one DM, then add groups on purpose. Once that is stable, WhatsApp becomes what it should be: a familiar front door to a self-hosted AI agent you control.
