What you need
- OpenClaw installed and running
With an AI model connected. New here? Start with the install guide.
- A phone with WhatsApp
Signed in to the number OpenClaw will use. Ideally a separate number (see below).
- About 15 minutes
And a computer that stays on if you want replies around the clock.
Use a dedicated WhatsApp number
OpenClaw connects as a linked device on WhatsApp Web, the same way WhatsApp Desktop does. The official docs recommend giving your assistant its own number.
- Your assistant is a separate contact you message
- Clean routing, with no mix-up with your personal chats
- Protects your main account
- Easy to share with family or a team
- Supported as a fallback
- More complex routing and permissions
- The assistant sits inside your own account
- Higher stakes if something goes wrong
A second SIM or eSIM, or a spare phone running WhatsApp or WhatsApp Business, works well. WhatsApp doesn't officially support third-party clients, so a separate number also keeps your main account out of harm's way.
Install the WhatsApp plugin
If you chose WhatsApp during openclaw onboard, it's already installed. Otherwise:
openclaw plugins install @openclaw/whatsappLink WhatsApp with the QR code
- Start the login on the computer running OpenClaw:
A QR code appears in the terminal.Terminal
openclaw channels login --channel whatsapp - On the phone with the OpenClaw number, open WhatsApp and go to Settings › Linked devices › Link a device.
- Scan the QR code. WhatsApp shows the new linked device, and OpenClaw now owns that session.
Scan within a few seconds of it appearing. On a remote server, scan directly from your SSH terminal window, because screenshots and forwarded images often expire before you scan them. If it times out, just run the command again.
Lock down who can message it
Add access rules to ~/.openclaw/openclaw.json. Use full international numbers with + and country code. Or use the config builder below.
{
channels: {
whatsapp: {
dmPolicy: "pairing", // or "allowlist"
allowFrom: ["+94771234567"], // approved senders
groupPolicy: "allowlist",
groupAllowFrom: ["+94771234567"],
},
},
}allowFrom can talk to it. Everyone else is ignored.Restart the gateway so the change takes effect:
openclaw gateway restartMessage it and approve yourself
From your own phone, send the OpenClaw number a WhatsApp message. With pairing on, it replies with a pairing code. Approve it on the computer:
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>- Pairing requests expire after 1 hour.
- Up to 3 requests can wait at once per account.
- This approval is separate from the QR login in step 2.
Test it
Working? Now build a daily routine with our first workflow tutorial.
WhatsApp config builder
Enter the numbers that should reach your assistant, one per line, with country code.
Use OpenClaw in WhatsApp groups
- Add the OpenClaw number to a WhatsApp group like any contact.
- Allow the people who may use it there with
groupAllowFrom, and keepgroupPolicy: "allowlist". - Mention it by @-mentioning the OpenClaw number. OpenClaw attaches proper WhatsApp mentions when it replies to people.
Each group gets its own separate session, so a family group and a work group never share context.
How OpenClaw behaves on WhatsApp
| Situation | What happens |
|---|---|
| Direct messages | Go to your main assistant session, so it remembers context from your other channels |
| Group chats | Each group has its own isolated session |
| Status updates and broadcasts | Ignored completely |
| Mentions | @+number mentions of group members are attached automatically |
| Behind a proxy | Respects the HTTPS_PROXY and HTTP_PROXY environment variables |
Connect WhatsApp on Docker or a VPS
Run the login through the CLI container and scan the QR code shown in your terminal:
docker compose run --rm openclaw-cli channels login --channel whatsappMake your SSH terminal window large enough to show the whole QR code. See the Docker guide and VPS guide.
Fix common WhatsApp problems
QR code expiredRun openclaw channels login --channel whatsapp again and scan straight away from the terminal.
QR code looks brokenWiden your terminal window or reduce the font size so the whole code shows.
It doesn't reply to meCheck openclaw pairing list whatsapp for a waiting request, or add your number to allowFrom. Numbers need the + and country code.
Ignored in groupsAdd the senders to groupAllowFrom and restart the gateway.
Logged out / device removedWhatsApp may unlink devices that are removed or inactive. Log in again with the QR code.
Stopped after moving serversWhatsApp credentials change over time, so restored sessions can fall out of sync. Re-link with the QR code.
More fixes: troubleshooting guide.
OpenClaw WhatsApp questions
How does OpenClaw connect to WhatsApp?
OpenClaw links to WhatsApp as a linked device using WhatsApp Web, the same way WhatsApp Desktop does. You log in by scanning a QR code with openclaw channels login --channel whatsapp.
Do I need a separate number for OpenClaw on WhatsApp?
It's strongly recommended. A dedicated number keeps your assistant separate from your personal chats and protects your main account. Using your personal number is possible but more complex.
Do I need Twilio or the WhatsApp Business API?
No. OpenClaw's WhatsApp channel uses WhatsApp Web's linked-device login, so there's no Twilio account or Business API setup.
How do I stop strangers using my OpenClaw WhatsApp?
Keep dmPolicy set to pairing so unknown senders must be approved with openclaw pairing approve whatsapp, or switch to allowlist and list only your numbers in allowFrom.
Can OpenClaw work in WhatsApp groups?
Yes. Add the OpenClaw number to a group, allow members with groupAllowFrom, and mention it. Each group has its own separate session.
Why did OpenClaw stop responding on WhatsApp?
The linked device may have been logged out, or your number isn't approved. Re-run the QR login, check openclaw pairing list whatsapp and make sure the gateway is running.