💬 WhatsApp Setup
Connect WhatsApp to your OpenClaw assistant
⚠️ Important: WhatsApp Uses Your Personal Number
Unlike Telegram or Discord, WhatsApp doesn't have a "bot" system. OpenClaw connects using the Baileys library, which links to your WhatsApp account similar to WhatsApp Web. Messages will come from YOUR phone number, and people you message can see your account.
How It Works
OpenClaw uses the Baileys library to connect to WhatsApp's web protocol. You'll scan a QR code once (like logging into WhatsApp Web), and OpenClaw maintains the session. Your phone doesn't need to stay connected after initial setup.
Start the WhatsApp Channel Setup
Run the channel login command:
openclaw channels login whatsapp
This will display a QR code in your terminal.
Scan the QR Code
- Open WhatsApp on your phone
- Go to Settings → Linked Devices
- Tap "Link a Device"
- Scan the QR code shown in your terminal
QR code will appear in your terminal
Once scanned, OpenClaw will save the session credentials to ~/.openclaw/credentials/whatsapp/
Configure Allowed Contacts
Restrict who can trigger your OpenClaw via WhatsApp:
channels:
whatsapp:
allowedUsers:
- "1234567890@s.whatsapp.net" # Phone number format
# Phone number format: country code + number + @s.whatsapp.net
# Example: +1 (555) 123-4567 → "15551234567@s.whatsapp.net"
Start OpenClaw
openclaw gateway # WhatsApp should show as connected # Check status: openclaw status
Test It Out
Send yourself a WhatsApp message (or have an allowed contact message you). OpenClaw will respond!
Note: Responses come from your WhatsApp number, so it looks like you're replying to yourself or others.
Session Persistence
Once linked, the session persists in ~/.openclaw/credentials/whatsapp/. You don't need to re-scan unless you logout from "Linked Devices" on your phone or the session expires (rare).
Phone Number Format
Finding the Correct Format
WhatsApp IDs use the format: [country code][number]@s.whatsapp.net
# Examples: +1 (555) 123-4567 → "15551234567@s.whatsapp.net" +44 7911 123456 → "447911123456@s.whatsapp.net" +55 11 98765-4321 → "5511987654321@s.whatsapp.net" # For groups: "123456789-1234567890@g.us"
Group Chat Setup
Adding OpenClaw to Groups
Since your number IS the bot, you're already in any groups you're part of. Configure which groups OpenClaw should respond in:
channels:
whatsapp:
allowedGroups:
- "123456789-1234567890@g.us" # Group ID
groupPrefix: "!" # Only respond to messages starting with !
To find a group's ID, check the OpenClaw logs when a message is sent in that group.
⚠️ Group Chat Caution
In group chats, OpenClaw responds AS YOU. Other members will see messages coming from your account. Consider using a prefix (like !) so it only responds to explicit commands.
Troubleshooting
QR code expired?
QR codes expire after ~60 seconds. Run the login command again to get a fresh one:
openclaw channels login whatsapp
Session keeps disconnecting?
- Check your phone's internet connection
- Make sure you haven't logged out from "Linked Devices"
- WhatsApp limits linked devices — remove unused ones
- Delete
~/.openclaw/credentials/whatsapp/and re-link
"Logged out" after phone restart?
WhatsApp Web sessions can be invalidated if your phone loses connection for too long. Re-scan the QR code to reconnect.
Alternative: Use a Secondary Number
If you want a dedicated "bot" number, you can:
- Get a cheap prepaid SIM
- Use a VoIP number that supports WhatsApp (some do)
- Register WhatsApp on an old phone, then link to OpenClaw
Related Guides
- Telegram Setup — Alternative: true bot account
- Security Checklist — Secure your installation
- Raspberry Pi Setup — 24/7 hosting