OpenClaw WhatsApp Setup: The Complete Guide (2026)
Connect WhatsApp to OpenClaw in 4 steps. QR codes, session persistence, ban risks, troubleshooting - everything in one page. Or skip it all with BetterClaw.
WhatsApp is the messaging platform 2 billion people actually live on. That makes it the most powerful channel for an AI agent - you can message your assistant from your phone, anywhere in the world, using the app you already have open.
It’s also the hardest OpenClaw channel to set up. And the most fragile to maintain.
Unlike Telegram (which has a proper Bot API), OpenClaw connects to WhatsApp through the unofficial WhatsApp Web protocol using a library called Baileys. That means QR code scanning instead of pasting a token. Session drops instead of stable connections. And a real risk of getting your account restricted or banned if WhatsApp detects automation patterns.
Setting up a different channel? Telegram setup guide. New to OpenClaw? Read how OpenClaw works first.
WhatsApp Wasn’t Built for AI Agents
Unofficial protocol
OpenClaw uses Baileys, which reverse-engineers WhatsApp Web. It works - 5,000+ active installs - but it’s not sanctioned by Meta.
WhatsApp detects automation
24/7 sessions from server IPs, high message frequency, instant responses - these trigger anti-automation systems. Some users get restricted within days.
Sessions drop
App updates, phone restarts, the 4-device limit, network changes - your agent goes silent until you re-scan the QR code with physical phone access.
Use a spare number
Run WhatsApp on a dedicated spare number, not your primary account. If the account gets restricted, you don’t lose your personal WhatsApp.
None of this means you shouldn’t set it up. Thousands of people run OpenClaw on WhatsApp successfully. Just go in with realistic expectations.
What You Need
OpenClaw v2026.1.29+
Running on Mac Mini, Linux server, or VPS. Node.js v22+ required.
A WhatsApp account on a phone
Ideally a spare number - not your primary account. Cheap prepaid SIM works.
Physical access to the phone
You’ll scan a QR code during setup, and again every time the session drops.
The WhatsApp plugin
Not built-in like Telegram. Install with openclaw plugins install @openclaw/whatsapp.
Enable the WhatsApp Channel
If setting up OpenClaw for the first time, the onboarding wizard (openclaw onboard) offers WhatsApp as a channel option. Select it and the plugin installs automatically.
For an existing installation:
openclaw channels add --channel whatsappOr enable it manually in ~/.openclaw/openclaw.json:
{
"channels": {
"whatsapp": {
"enabled": true,
"dmPolicy": "pairing",
"allowFrom": ["+15551234567"],
"groupPolicy": "allowlist",
"groupAllowFrom": ["+15551234567"]
}
}
}Replace phone numbers with your own in E.164 format (country code + number, like +15551234567). Then restart:
openclaw gateway restartScan the QR Code
This is where WhatsApp setup diverges from every other channel.
There’s no token to paste. No API key. You scan a QR code - just like linking WhatsApp Web on a new computer.
- After restarting the gateway, OpenClaw displays a QR code in your terminal or web dashboard.
- On your phone: WhatsApp → Settings → Linked Devices → Link a Device.
- Scan the QR code.
- If successful, OpenClaw logs a success message and the channel shows as connected.
- Send a test message from another phone to verify.
QR code expired?
They expire in ~60 seconds. Run openclaw channels login --channel whatsapp for a fresh one.
On a remote server?
Access the QR through the web dashboard or pipe it via SSH. Some hosts (like Hostinger) show it in their admin panel.
Configure Access Control
By default, only the linked phone number can message the agent. But if anyone gets your agent’s number, they could interact with it. Lock it down.
Set allowFrom with your phone number in E.164 format:
"allowFrom": ["+15551234567"]For groups, set groupAllowFrom separately - group auth doesn’t inherit DM settings:
"groupAllowFrom": ["+15551234567", "+15559876543"]With pairing mode, new users get a pairing code. Approve from terminal:
openclaw pairing approve whatsapp [CODE]Pairing requests expire after 1 hour. Maximum 3 pending requests per channel.
Make Sessions Survive Restarts
This is the step most guides skip - and the #1 reason agents disconnect.
OpenClaw stores WhatsApp session credentials locally via Baileys. If session files aren’t in a persistent location, every server restart means re-scanning the QR code.
Session data lives in ~/.openclaw/credentials/ by default. Make sure this directory is on persistent storage - not an ephemeral volume, not a Docker container without a mount, not a tmpfs partition.
If using Docker, mount it as a persistent volume:
-v /host/path/openclaw-creds:/home/node/.openclaw/credentialsEven with persistence, sessions can drop for reasons outside your control. Plan for re-linking. On a VPS, back up the credentials directory regularly.
Setup complete. Your WhatsApp agent is live.
Send a test message from another phone to verify. Check openclaw channels status to confirm.
The 8 Problems Everyone Hits with WhatsApp
Session disconnects overnight
Cause: WhatsApp app updated, server restarted without persistent storage, 4-device limit hit, or VPS clock drifted.
Fix: Check Linked Devices on your phone, re-scan QR, verify server clock with timedatectl.
“Account restricted” or banned
Cause: WhatsApp detected automation patterns - datacenter IPs, high frequency, instant responses.
Fix: No reliable fix. Wait 24–72 hours for temp restrictions. Permanent = new number. This is why you use a spare number.
QR code expired before scanning
Cause: QR codes expire in ~60 seconds. Remote server access adds delay.
Fix: Run openclaw channels login --channel whatsapp for a fresh QR. Use web dashboard for faster access on remote servers.
Bot doesn’t respond to messages
Cause: Channel disconnected, allowFrom misconfigured, or phone lost internet.
Fix: Check openclaw channels status, watch openclaw logs --follow, verify allowFrom uses E.164 format.
Bot works in DMs but not groups
Cause: Groups require @mention by default. groupAllowFrom not configured.
Fix: Set requireMention: false or @mention the bot. Add authorized numbers to groupAllowFrom.
Messages received but responses never sent
Cause: AI provider down or rate-limited, or WhatsApp throttling outbound messages.
Fix: Check openclaw logs --follow for API errors. Reduce message frequency if hitting WhatsApp limits.
“Plugin not found: whatsapp”
Cause: WhatsApp plugin not installed. Unlike Telegram, WhatsApp is not built-in.
Fix: Run openclaw plugins install @openclaw/whatsapp or openclaw channels add --channel whatsapp.
Duplicate gateway processes after migration
Cause: Old Clawdbot or Moltbot processes still running.
Fix: Kill old processes, copy data to ~/.openclaw/, restart only the OpenClaw gateway.
WhatsApp Bans Are Real. Here’s How to Minimize the Risk.
OpenClaw uses Baileys to reverse-engineer the WhatsApp Web protocol. Meta doesn’t endorse this. WhatsApp’s Terms of Service prohibit automated use of personal accounts.
People get banned. Not everyone - thousands run it fine for months. But the risk is non-zero and unpredictable.
Use a dedicated spare number. Never risk your primary WhatsApp.
Avoid obvious datacenter IPs. Residential IP (home Mac Mini) is safer than cloud VPS.
Add artificial response delays. Don’t reply instantly to every message.
Keep message volume reasonable. 50 messages/hour will get noticed.
Minimize reconnections. Each re-link is a signal to WhatsApp.
Stay on latest Baileys version. Outdated libraries cause suspicious behavior.
If you get restricted:
Wait. Most temporary restrictions lift in 24–72 hours. Don’t create a new account on the same number immediately - that escalates the restriction. Permanent bans require a new number. More on OpenClaw security risks.
Groups, Reactions, Multi-Account, and Voice
Group Setup
Set groupPolicy: "allowlist" and add members to groupAllowFrom. Group auth is separate from DM pairing.
Ack Reactions
Instant emoji reaction when a message is received (before AI responds). Set ackReaction.emoji: "\uD83D\uDC40" for visual feedback.
Multi-Account
Run multiple WhatsApp accounts using channels.whatsapp.accounts. Each requires its own QR scan and session.
Voice Messages
Send a voice note and OpenClaw processes it through your AI provider. No additional config needed.
"ackReaction": {
"emoji": "\uD83D\uDC40",
"direct": true,
"group": "mentions"
}Honestly, Telegram Is Easier. Here’s the Tradeoff.
Setup
Connection stability
Ban risk
Where your contacts are
Bot API
Proactive messaging
Setup difficulty
| Telegram | ||
|---|---|---|
| Setup | QR code scan, plugin install, session mgmt | Paste a bot token, 2 minutes, done |
| Connection stability | Sessions drop, require phone to re-link | Stable, token-based, survives restarts |
| Ban risk | Real - unofficial protocol, Meta can restrict | Zero - official Bot API |
| Where your contacts are | Everyone (2B users) | Mostly tech-savvy users |
| Bot API | No official personal API (Baileys) | Full official Bot API |
| Proactive messaging | Restrictions on unsolicited messages | Full support |
| Setup difficulty | Harder | Easier |
If your contacts are on Telegram, use Telegram. It’s more stable, easier to configure, and has zero ban risk. If your contacts are on WhatsApp (like most of the world), the extra work is worth it. Or use both - OpenClaw supports multi-channel with shared memory.
Connect WhatsApp in 1 Click. No QR Codes. No Ban Risk.
Let’s review what OpenClaw WhatsApp setup requires: installing a plugin, scanning a QR code with physical phone access, configuring JSON with E.164 numbers, setting up session persistence, managing allowFrom lists, and hoping WhatsApp doesn’t ban your account.
When the session drops (and it will), you grab your phone, re-scan, and hope it reconnects before anyone notices your agent went silent.
Self-Hosted OpenClaw
30+ minutes setup. Ongoing session management. Ban risk.
BetterClaw
Under 60 seconds. Zero maintenance.
Action approval means your agent asks before destructive actions. Encrypted credential storage means no tokens in plain-text files. An instant kill switch means you can pause from your phone.
Already running self-hosted OpenClaw? See the migration guide or compare BetterClaw vs OpenClaw.
$19/month per agent · 1-click WhatsApp connect · No QR codes · No ban risk
OpenClaw WhatsApp Setup - Commands at a Glance
| Install plugin | openclaw plugins install @openclaw/whatsapp |
| Enable channel | openclaw channels add --channel whatsapp |
| Config location | ~/.openclaw/openclaw.json → channels.whatsapp |
| Key config | enabled: true + allowFrom in E.164 format |
| Restart | openclaw gateway restart |
| Show QR | openclaw channels login --channel whatsapp |
| Scan QR | Phone → WhatsApp → Linked Devices → Link |
| Check status | openclaw channels status |
| Approve pairing | openclaw pairing approve whatsapp [CODE] |
| Watch logs | openclaw logs --follow |
| Logout | openclaw channels logout --channel whatsapp |
| Session files | ~/.openclaw/credentials/ |
OpenClaw WhatsApp Setup: Common Questions
Does WhatsApp charge anything for this?
No. The Baileys-based connection is free. You pay for OpenClaw infrastructure and AI model API costs. The WhatsApp Business API (official Meta product) has per-conversation pricing, but OpenClaw’s default integration uses the free web protocol.
Can I use my main WhatsApp number?
Technically yes, but strongly discouraged. If WhatsApp restricts the account due to automation detection, you lose your personal WhatsApp. Always use a spare dedicated number.
How often do sessions drop?
It varies. Some users run for months without disconnection. Others report drops every few days. Common triggers: WhatsApp app updates, server restarts without persistent session storage, and the 4-device linked limit.
Can my agent send messages proactively?
Yes, to contacts you’ve already paired with. Your agent can send morning briefings, reminders, alerts, and scheduled reports. Works best with contacts who have an existing conversation thread.
What happens if I get banned?
Temporary restrictions usually lift in 24–72 hours. Permanent bans require a new phone number. This is why you never use your primary account.
Can I use WhatsApp Business API instead of Baileys?
Some guides reference the WhatsApp Business API for enterprise setups. This requires a Meta Business account, API approval, and per-conversation pricing - but it’s officially sanctioned with zero ban risk. BetterClaw uses properly authorized integrations by default.
Done Reading? Connect WhatsApp in 60 Seconds.
BetterClaw connects WhatsApp, Telegram, Slack, Discord, and 11 more channels with one click. No QR codes. No ban risk. No session drops.
$19/month per agent · 15+ channels · 1-click connect · Zero ban risk