On this page
💚 Why WhatsApp?
| Advantage | Details |
|---|---|
| Already on your phone | No new app to install. Message your agent the same way you text friends. |
| Voice notes | Hold the mic button, speak your request, get a text response — true hands-free AI. |
| Tap-to-mention | Native @mentions work for activating the agent in group chats. |
| No API fees | Uses Baileys (open-source WhatsApp Web protocol) — no Meta Business API, no per-message costs. |
| SelfChat mode | Message yourself to talk to OpenClaw privately — no separate bot contact needed. |
| End-to-end encrypted | Messages between you and your own WhatsApp number stay encrypted. |
💡 Real user: “My personal bot has replaced at least half the apps I used to operate myself. It lives in my personal WhatsApp and on groups with my friends and family.” — OpenClaw Showcase
🔄 How it works
OpenClaw connects to WhatsApp using Baileys, an open-source library that implements the WhatsApp Web protocol. This means:
- You link OpenClaw as a companion device (like WhatsApp Web or Desktop)
- Your existing WhatsApp number is used — no new phone number needed
- Credentials are stored locally in
~/.openclaw/credentials/ - The connection persists until you unlink or credentials expire
⚠️ Known limitation: WhatsApp sometimes disconnects after extended inactivity or server-side updates. If your agent stops responding, you may need to re-pair by scanning a new QR code. Telegram doesn't have this issue (token-based), which is why many users run both channels.
📱 Setup — QR code pairing
Option A: During onboarding
openclaw onboard
# Select "WhatsApp" when prompted for channel
# Enter your phone number with country code
# A QR code appears in the terminal
# Scan it with WhatsApp: Settings → Linked Devices → Link a Device
Option B: Add WhatsApp to existing setup
openclaw channels login whatsapp
# Follow the QR code flow
Option C: Manual config (after QR pairing)
// ~/.openclaw/openclaw.json
{
"channels": {
"whatsapp": {
"enabled": true,
"dmPolicy": "allowlist",
"allowFrom": ["+40712345678"]
}
}
}
✅ Phone numbers must include country code with the
+ prefix. Example: +40 for Romania, +1 for US, +44 for UK.⚙️ Configuration
DM policies
| Policy | Behavior | Use case |
|---|---|---|
allowlist | Only numbers in allowFrom can message | Recommended — personal use |
pairing | Unknown senders get a pairing code to approve | More flexible, still secure |
open | Anyone can message your agent | ⚠️ Dangerous — burns API credits |
disabled | DMs blocked entirely | Groups-only setup |
Full config example
{
"channels": {
"whatsapp": {
"enabled": true,
"selfChatMode": true,
"dmPolicy": "allowlist",
"allowFrom": ["+40712345678"],
"groupPolicy": "allowlist",
"groupAllowFrom": ["+40712345678"]
}
}
}
💬 SelfChat mode
The most popular WhatsApp setup: message yourself to talk to OpenClaw. No separate bot contact cluttering your chat list.
{
"channels": {
"whatsapp": {
"selfChatMode": true,
"dmPolicy": "allowlist",
"allowFrom": ["+40712345678"]
}
}
}
Open WhatsApp → tap your own name at the top of the chat list (the “Message yourself” chat) → start talking. OpenClaw replies in the same conversation.
✅ Pro tip: Pin the self-chat to the top of your WhatsApp for instant access. Some users set their own profile picture to a lobster emoji for fun.
👥 Group chats
Add your own WhatsApp number to a group, then configure group access:
{
"channels": {
"whatsapp": {
"groupPolicy": "allowlist",
"groupAllowFrom": ["+40712345678"],
"groups": {
"*": {
"requireMention": true
}
}
}
}
}
In groups, the agent only responds when @mentioned (tap-to-mention). This prevents it from jumping into every conversation.
💡 Family group: Many users add OpenClaw to a family WhatsApp group for shared shopping lists, meal planning, and scheduling. The agent responds when @mentioned and can maintain separate context per group.
✨ Supported features
| Feature | Status | Notes |
|---|---|---|
| Text messages | ✅ Full | Rich formatting supported |
| Voice notes | ✅ Full | Send voice → get text response. Transcription via Whisper. |
| Images / photos | ✅ Full | Send and receive with captions |
| Documents / files | ✅ Full | PDFs, spreadsheets, etc. |
| Location sharing | ✅ Full | Share location for context-aware responses |
| Reactions | ✅ Read | Agent can read reactions on messages |
| Tap-to-mention | ✅ Full | Native @mentions for group activation |
| Slash commands | ✅ Full | /status, /model, /reset, etc. |
| Video | ✅ Full | Send and receive video messages |
| Stickers | ⚠️ Limited | Received but not always described accurately |
⏰ Cron delivery to WhatsApp
openclaw cron add \
--name "Morning briefing" \
--cron "0 7 * * *" \
--tz "Europe/Bucharest" \
--session isolated \
--message "Good morning! Send my daily briefing." \
--announce --channel whatsapp \
--to "+40712345678"
For heartbeat delivery, set the target to WhatsApp:
{
"agents": {
"defaults": {
"heartbeat": {
"target": "whatsapp"
}
}
}
}
🔧 Troubleshooting
| Problem | Fix |
|---|---|
| QR code won't scan | Ensure terminal supports QR rendering. Try a larger terminal window. Or use the Control UI at localhost:18789. |
| Disconnected after a while | WhatsApp Web sessions can expire. Re-pair: openclaw channels login whatsapp |
| Messages not arriving | Check your phone's WhatsApp is online (phone must have internet). Check openclaw logs --follow. |
| “Not authorized” error | Your phone number isn't in allowFrom. Add it with the + country code prefix. |
| Agent replies to everyone in group | Set requireMention: true in group config. Agent only responds to @mentions. |
| Credentials lost after restart | Credentials are stored in ~/.openclaw/credentials/. Ensure this directory is persisted (Docker: mount as volume). |
| Two OpenClaw instances conflict | WhatsApp only allows one Web companion per device type. Stop the other instance. |
✅ Best practice: Run both Telegram and WhatsApp. Telegram for reliability (token never expires), WhatsApp for convenience (already on your phone). If WhatsApp disconnects, Telegram keeps working.