Setting up the OpenClaw WhatsApp integration sounds simple. Install a plugin, scan a QR code, done. But if you’ve tried it and ended up with a bot that ignores messages, locks itself out, or disconnects every few hours – you’re not alone. The WhatsApp integration is one of OpenClaw’s most powerful features and also the one that trips people up the most.
This guide covers the actual setup process, the three decisions that determine whether your integration holds up in production, and the access control options that most tutorials skip entirely.
How OpenClaw WhatsApp Works
OpenClaw connects to WhatsApp via the Baileys library, which runs as a WhatsApp Web client. Your gateway maintains the session, handles reconnects, and routes incoming messages to your AI agent. It’s not the Meta Business API – it uses the same WhatsApp Web protocol your browser uses.
That matters for a few reasons. First, you don’t need a WhatsApp Business API account or Meta approval. Second, the connection is tied to a phone number, which means it needs a real SIM or a VoIP number that WhatsApp accepts. Third, if that number’s WhatsApp session expires or gets banned, the whole integration goes down.
The plugin is maintained separately from the core OpenClaw gateway. You install it on demand:
openclaw plugins install @openclaw/whatsappOr, if you’re using the onboarding flow:
openclaw channels add --channel whatsappBoth paths install the plugin and walk you through initial configuration.
Not sure if your setup is production-ready?
Getting the WhatsApp integration stable takes more than following a tutorial. We set it up correctly the first time.
The Phone Number Decision (Get This Wrong and You’ll Regret It)
Before you touch any configuration, decide which number OpenClaw will use. This is the decision most guides skip, and it’s the one that causes the most headaches later.
OpenClaw recommends a dedicated number – separate from your personal WhatsApp account. Here’s why that recommendation exists:
When you link your personal number, every message you send and receive runs through OpenClaw’s session. That includes personal chats. The bot has access to your full conversation history and can accidentally respond to the wrong thread. Setting up proper allowlists becomes more complex because you’re trying to carve out exceptions to your own number.
A dedicated number keeps the boundaries clean. OpenClaw gets one identity. Your personal messages stay separate. Allowlists become straightforward. When something breaks, you know exactly what to look at.
For the dedicated number, a cheap VoIP number works if WhatsApp accepts it for verification. Google Voice numbers sometimes work, but WhatsApp has been inconsistent about allowing them. A low-cost SIM from a prepaid carrier is the most reliable option if you want zero friction.
OpenClaw WhatsApp Setup: Step by Step
Once you have a number ready, the setup sequence is four steps.
Step 1: Configure access policy first. Do this before you link the number. Add a channels.whatsapp block to your OpenClaw gateway config:
{
channels: {
whatsapp: {
dmPolicy: "pairing",
allowFrom: ["+15551234567"],
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"]
}
}
}The allowFrom array controls which numbers can send messages to your bot. If you skip this, the default behavior in pairing mode lets anyone who knows your number initiate a conversation – which is probably not what you want for a business automation.
Step 2: Link the number.
openclaw channels login --channel whatsappThis opens a QR code in your terminal. Scan it with WhatsApp on the phone tied to your dedicated number. If you’re using a named account:
openclaw channels login --channel whatsapp --account workStep 3: Start the gateway.
openclaw gatewayStep 4: Handle the first pairing request. If you’re using pairing mode (the default), the first message from an unknown number generates a pairing request instead of a response. Approve it from your terminal:
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>Pairing requests expire after one hour. After approval, that number goes on your allowlist and conversations work normally going forward.
OpenClaw WhatsApp Access Policies Explained
The access control system has four modes, and picking the right one depends on your use case.
Pairing mode is the default. Unknown senders get a pairing request rather than an immediate response. Good for customer-facing bots where you want to screen who gets access without building a full allowlist upfront.
Allowlist mode is tighter. Only numbers in allowFrom can trigger the bot at all. Everything else is silently ignored. Use this for internal team automations or when you’re connecting OpenClaw to a business number that handles real customer conversations.
Open mode accepts messages from anyone. This requires you to explicitly set allowFrom: ["*"]. It’s the right choice for public-facing bots, but come back and review your rate limiting and cost controls before you enable it – an uncapped open bot on WhatsApp can burn through API credits fast.
Disabled mode shuts down inbound completely. Useful if you want OpenClaw to send messages via WhatsApp (outbound only) without accepting any replies.
Group chats have a separate policy layer. The groupPolicy setting controls who can trigger the bot in group conversations. Even if a group is allowed, you can restrict which members the bot will respond to using groupAllowFrom. And by default, the bot only responds in groups when explicitly mentioned – which is the behavior you want for most setups.
Want the right config for your specific use case?
Whether it’s customer service, team automation, or a hybrid setup – we’ll get the config right for your use case.
Why OpenClaw WhatsApp Disconnects (and How to Keep It Stable)
The most common support question about OpenClaw WhatsApp isn’t about setup – it’s about stability. The connection drops overnight and nobody can figure out why.
A few patterns cause most of these disconnects:
Session expiry. WhatsApp Web sessions do expire, especially if the linked phone doesn’t connect to the internet for an extended period. The phone needs to stay online (not just the server running OpenClaw). If your dedicated number is on a SIM card in a drawer somewhere, pull it out and make sure the phone checks in periodically.
IP reputation issues. Running OpenClaw on a residential IP is usually fine. Shared hosting IPs or datacenter IPs associated with spam can trigger WhatsApp’s security checks and force a re-authentication. If you’re deploying on a VPS and seeing frequent disconnects, this is worth investigating.
Outbound-only usage patterns. Some setups use OpenClaw to send notifications via WhatsApp without expecting any replies. But if the session goes completely idle on inbound, some configurations don’t maintain the keep-alive signals properly. Add a simple health check or use OpenClaw’s heartbeat system to ping the gateway periodically.
Multiple logins on the same number. If someone opens WhatsApp Web on a browser with the same number your OpenClaw instance is using, it can kick your session. WhatsApp Web allows a limited number of linked devices. Keep track of what’s linked.
When a disconnect happens, the recovery is usually just relinking:
openclaw channels login --channel whatsappBut if it’s happening frequently, the root cause is almost always one of the patterns above.
Common Use Cases Worth Setting Up
The OpenClaw WhatsApp integration works well for a few specific patterns that businesses actually use:
Customer Q&A on a business number. Point a dedicated business number at OpenClaw with a knowledge base skill. Common questions get answered instantly, 24/7. Unusual questions get flagged for human follow-up. This pairs naturally with the cron system for sending daily summaries of unresolved conversations.
Internal team notifications. OpenClaw can send structured updates to a WhatsApp group – daily reports, alert triggers, status updates. Use allowlist mode and restrict to your team’s numbers. This is lighter than building a full Slack/Discord integration if your team already lives in WhatsApp.
Appointment and follow-up flows. Trigger outbound WhatsApp messages from cron jobs or other automations. Combine with the multi-channel setup guide if you need the same automation running across WhatsApp and another channel simultaneously.
One thing worth being clear about: OpenClaw’s WhatsApp integration is not a marketing broadcast tool. Sending bulk unsolicited messages via WhatsApp Web puts your number at serious risk of being banned. Keep it to conversations with people who’ve opted in or initiated contact.
What to Check Before You Call It Done
Before you hand off a WhatsApp integration to production, run through this list:
- Access policy is explicitly configured (not relying on defaults)
- The linked phone stays online and periodically connects to mobile data or WiFi
- You’ve tested the pairing flow with a real number from a different phone
- Group chat policy matches your intent (mention-only vs. always active)
- You know how to relink if the session drops
- API cost controls are in place if you’re using open mode
The integration is genuinely useful once it’s stable. Getting to stable just requires being deliberate about the configuration decisions upfront – not treating it as a quick plug-and-play add-on.
Skip the trial and error
If you’d rather have a working WhatsApp integration by tomorrow instead of spending a weekend debugging access policies, that’s exactly what we do.