Most people set up OpenClaw on Telegram because that is what the default onboarding suggests. But WhatsApp has 2.7 billion monthly active users, and the people you interact with most (family, clients, colleagues) are almost certainly already there. Connecting OpenClaw to WhatsApp puts your AI agent inside the app everyone already uses, which means less friction when you want to share it with others or use it on the go.
The setup takes about 10 minutes if OpenClaw is already installed. You edit one configuration block, scan a QR code, and send a test message. This guide covers the full process, the tradeoffs versus Telegram, and the security implications of giving an AI agent access to your WhatsApp account.
Before You Start
You need three things in place:
-
OpenClaw installed and running on your machine or VPS. If you have not done this yet, follow our OpenClaw setup guide first. That guide covers installation, workspace files, memory, and Telegram configuration.
-
A WhatsApp account on your phone. Both personal and WhatsApp Business accounts work. OpenClaw connects through the same protocol as WhatsApp Web, so any account that supports linked devices will work.
-
Your phone number in international format. You will need it for the allowlist configuration. For a US number, that looks like
+15551234567. For a UK number,+447700900000. Include the country code with no spaces.
If you want OpenClaw running 24/7 (so it responds to WhatsApp messages even when your laptop is closed), you will need it deployed on a VPS. Our Hostinger deployment guide walks through that setup.
Step 1: Add the WhatsApp Channel Configuration
Open your openclaw.json configuration file. If you set up OpenClaw using the standard installation, this file lives at ~/.openclaw/openclaw.json.
Add the WhatsApp channel block inside the channels section:
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
groupPolicy: "disabled",
mediaMaxMb: 50,
},
},
}
Replace +15551234567 with your actual phone number in international format.
Here is what each setting does:
| Setting | Value | What It Controls |
|---|---|---|
dmPolicy | "allowlist" | Only numbers in allowFrom can message the agent |
allowFrom | Your phone number | Which numbers are authorized |
groupPolicy | "disabled" | Blocks group messages initially |
mediaMaxMb | 50 | Maximum file size for images, documents, and voice notes |
We recommend starting with groupPolicy: "disabled" and a single number in allowFrom. You can open this up later once you trust the setup.
Step 2: Scan the QR Code
Run the WhatsApp channel login command from your terminal:
openclaw channels login --channel whatsapp
A QR code will appear in your terminal. On your phone:
- Open WhatsApp
- Go to Settings > Linked Devices (or tap the three dots menu on Android)
- Tap Link a Device
- Point your camera at the terminal QR code
The terminal should confirm the connection within a few seconds. If the QR code expires before you scan it, re-run the command to generate a fresh one.
After pairing, start the gateway:
openclaw gateway
You should see OpenClaw appear as a linked device in your WhatsApp settings. The connection persists for roughly 30 days before you need to re-scan.
Step 3: Test the Connection
Open WhatsApp on your phone and send a message to yourself (your own number) or to the linked device. Type something simple:
“What time is it?”
If the agent responds, the connection is working. Try a few more tests to verify different capabilities:
Text test:
“Summarize what you know about me from your memory”
Voice note test: Send a short voice message. OpenClaw transcribes audio using Whisper and processes it like text.
Image test: Send a photo and ask “What is in this image?” OpenClaw can process images if your configured model supports vision.
If nothing comes back, jump to the troubleshooting section below.
Step 4: Configure Group Access
Once direct messages work, you can optionally enable WhatsApp group support. This lets you add OpenClaw to a family group chat, a team channel, or a project group.
Update your configuration:
{
channels: {
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+15551234567"],
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567", "+15559876543"],
},
},
}
In groups, OpenClaw only responds when mentioned by name or when someone replies directly to one of its messages. This prevents the agent from jumping into every conversation. The groupAllowFrom list controls which group members can trigger the agent. People not on the list are ignored even if they mention the bot.
After updating the config, restart the gateway:
openclaw gateway restart
WhatsApp vs Telegram: When to Use Which
If you already have OpenClaw on Telegram and you are wondering whether to add WhatsApp, here is the honest breakdown.
Choose WhatsApp when:
- Your family, clients, or colleagues already use it and will not install Telegram
- You want to share the agent with non-technical people who would find a Telegram bot confusing
- You need voice note input (WhatsApp voice notes are natural for most users)
- You are building a business-facing agent where clients message you on WhatsApp
Stick with Telegram when:
- You want a dedicated bot account with its own identity (Telegram bots get their own username and profile)
- You need richer group management features (Telegram groups support up to 200,000 members, admin controls, topic threads)
- You want multiple bots in the same group without them conflicting
- Privacy matters more than convenience (Telegram bots do not expose your personal phone number)
The biggest practical difference: Telegram gives your agent its own separate identity via a bot token, while WhatsApp links to your personal number. On WhatsApp, your agent is you as far as other people can see. That is fine for personal use but creates confusion in professional contexts where people think they are messaging a human.
You can run both channels simultaneously. Many OpenClaw users keep Telegram as their power-user interface and WhatsApp as the channel they share with family or clients.
Security: What WhatsApp Access Means
Connecting OpenClaw to WhatsApp gives your AI agent access to your messaging account. This deserves more thought than most setup guides give it.
Your phone number is visible. Unlike Telegram bots (which use a token and never expose your personal number), WhatsApp connections are tied to your real phone number. Anyone in your allowFrom list or in an allowed group can see it. For personal use this is fine. For business use, consider getting a second number.
Linked device access is broad. When you scan the QR code, OpenClaw gets the same access as a WhatsApp Web session. It can read incoming messages, send outgoing messages, and access media. It cannot read old messages that were sent before the linking happened.
Group interactions carry prompt injection risk. If your agent is in a WhatsApp group, anyone in that group can try to manipulate it through crafted messages. The groupAllowFrom setting limits who the agent responds to, but the agent still reads all group messages for context. Use a strong model (GPT-5 or Claude Opus) that handles adversarial inputs well, and keep the agent out of groups with untrusted members.
Recommendations for staying safe:
- Start with
dmPolicy: "allowlist"and only your own number - Keep
groupPolicy: "disabled"until you specifically need group access - Check WhatsApp Settings > Linked Devices periodically to verify only expected devices are connected
- Store API keys and model tokens in
.envfiles, never in workspace files the agent might surface in a conversation - If using OpenClaw for business, use a dedicated WhatsApp Business number rather than your personal one
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| QR code appears but scanning fails | QR expired (they last about 60 seconds) | Re-run openclaw channels login --channel whatsapp |
| No response after scanning | Gateway not running | Run openclaw gateway and check for errors |
| Agent does not reply to messages | Your number is not in allowFrom | Verify the number format includes country code with + prefix |
| ”Status 515” error in terminal | WhatsApp connection dropped | Restart gateway; if it persists, re-scan the QR code |
| Voice notes not transcribed | Whisper not configured | Check your model provider supports audio transcription |
| Group messages ignored | groupPolicy set to "disabled" | Update to "allowlist" and add authorized numbers to groupAllowFrom |
| Agent responds to everyone in group | groupAllowFrom set to ["*"] | Replace with specific phone numbers |
If you hit an issue not listed here, run openclaw doctor in your terminal. This diagnostic command checks your configuration, connectivity, and channel status.
What to Do After Setup
Once WhatsApp is connected, here are three practical next steps:
1. Connect a tool. OpenClaw becomes far more useful when it can do things beyond answering questions. Our HubSpot integration guide shows how to build a CRM skill. The same pattern works for any API.
2. Configure memory. If you have not already set up persistent memory, your agent will forget conversations between sessions. Our memory configuration guide covers the setup.
3. Set up a heartbeat. OpenClaw can wake up every 30 minutes and do things proactively: check your calendar, summarize unread messages, or monitor a dashboard. The heartbeat configuration is covered in Step 8 of our setup guide.
Frequently Asked Questions
Do I need a separate phone number to use OpenClaw on WhatsApp?
No. OpenClaw links to your existing WhatsApp account the same way WhatsApp Web does. You use your current number and scan a QR code. For personal use, your regular number works perfectly. For business use where you want to keep client interactions separate, a dedicated WhatsApp Business number on a second SIM or virtual number service is worth considering.
Can I run WhatsApp and Telegram channels at the same time?
Yes. OpenClaw supports multiple channels simultaneously. Add both whatsapp and telegram blocks to your openclaw.json channels configuration. Messages from each channel are handled independently. Many users keep Telegram for personal power-use and WhatsApp for sharing the agent with family or clients who prefer it.
Does this work with WhatsApp Business accounts?
Yes. The setup process is identical for personal WhatsApp and WhatsApp Business. The QR code pairing works the same way on both. WhatsApp Business gives you additional features like business profiles and quick replies in the app itself, but OpenClaw treats both account types the same.
How do I fix “no response” after scanning the QR code?
Three things to check. First, confirm the gateway is running (openclaw gateway in your terminal). Second, verify your phone number in allowFrom uses the correct international format with + prefix and country code. Third, check the terminal output for error messages. The most common cause is a typo in the phone number format.
Can OpenClaw read voice notes and images sent on WhatsApp?
Yes to both. Voice notes are transcribed using Whisper (or your configured speech-to-text provider) and processed as text. Images are analyzed if your model supports vision (GPT-5, Claude Opus, and Gemini all do). You can also send documents like PDFs and spreadsheets. The default file size limit is 50MB, configurable via mediaMaxMb in your config.
What happens if someone in a WhatsApp group tries to manipulate the agent?
OpenClaw reads all group messages for context but only responds to authorized senders listed in groupAllowFrom. An unauthorized person’s message will be in the context window but will not trigger a response. For prompt injection specifically, stronger models (GPT-5, Claude Opus) are more resistant. If you are concerned, keep the agent out of groups with untrusted members or set groupPolicy: "disabled".
How often do I need to re-scan the QR code?
WhatsApp linked device sessions typically last about 30 days. OpenClaw will notify you when the session is about to expire. If the connection drops earlier (power outage, server restart), you may need to re-scan sooner. On a VPS with stable uptime, monthly re-authentication is normal.
Can I add OpenClaw to a WhatsApp group?
Yes. Set groupPolicy to "allowlist" in your configuration and add the phone numbers of group members who should be able to interact with the agent to groupAllowFrom. In groups, the agent only responds when explicitly mentioned or when someone replies to its messages. This prevents it from interrupting every conversation.
Key Takeaways
- Connect WhatsApp to OpenClaw by adding a
whatsappchannel block toopenclaw.jsonand scanning a QR code from your phone - Start with
dmPolicy: "allowlist"and only your own number before opening access to groups or additional users - WhatsApp works best for sharing your agent with non-technical family members or business contacts already on the platform
- Telegram remains better for power users who want a dedicated bot identity and richer group management
- WhatsApp links to your real phone number, unlike Telegram bots, so consider a dedicated number for business use
SFAI Labs
