OpenClaw WhatsApp Setup Guide 2026

Want to chat with your AI assistant via WhatsApp? Here’s how to set it up.

Note: WhatsApp integration uses a linked device approach (like WhatsApp Web). It’s not an official API, so there are some limitations.

How It Works

OpenClaw connects to WhatsApp the same way WhatsApp Web does:

1. You scan a QR code
2. Your phone authenticates the connection
3. Messages sync between your phone and OpenClaw

This means:

• Your phone must stay connected to the internet
• Sessions can expire and need re-linking
• It uses your personal WhatsApp number

Initial Setup

Step 1: Enable WhatsApp in OpenClaw

During openclaw onboard:

Select messaging channel: WhatsApp

Or edit your config:

channels:
  whatsapp:
    enabled: true

Step 2: Start the Gateway

openclaw gateway start

You should see a QR code in the terminal.

Step 3: Scan the QR Code

1. Open WhatsApp on your phone
2. Go to Settings → Linked Devices
3. Tap Link a Device
4. Scan the QR code shown in your terminal

Step 4: Test It

Send a message to yourself (use the “Message yourself” feature) or send from another device. OpenClaw should respond.

Common Issues

QR Code Not Showing

Check: Is the gateway running?

openclaw gateway status

Check: WhatsApp channel enabled in config?

Try: Restart the gateway:

openclaw gateway restart

Connection Drops After a Few Hours/Days

WhatsApp sessions expire. This is the most common issue.

Symptoms:

• Messages stop being received
• No errors in logs (silent failure)

Fix:

1. Check if session is still active: openclaw gateway status
2. If disconnected, re-scan the QR code
3. Set up monitoring to detect disconnects

”Logged Out” Error

WhatsApp may log out linked devices if:

• Your phone was offline for too long
• You linked too many devices
• WhatsApp detected unusual activity

Fix: Re-scan the QR code. If it keeps happening:

• Ensure your phone has stable internet
• Reduce the number of linked devices
• Use a dedicated phone/number for OpenClaw

Slow Message Delivery

WhatsApp messages can be delayed if:

• Your phone has poor connectivity
• Battery saver is killing background apps
• WhatsApp is rate-limiting

Improve reliability:

• Keep phone plugged in and on WiFi
• Disable battery optimization for WhatsApp
• Use a dedicated device if possible

Best Practices

Use a Dedicated Number (Recommended)

For serious use, get a second phone number:

• Cheap SIM card (~$5/month)
• Old phone you keep plugged in
• Or a VoIP number that supports WhatsApp

Benefits:

• Your personal WhatsApp stays separate
• More reliable (dedicated device always on)
• Easier to manage

Keep Phone Online

WhatsApp Web/linked devices require your phone to be:

• Connected to the internet
• Not in airplane mode
• WhatsApp app not killed by battery saver

For always-on reliability:

• Use a dedicated device
• Keep it plugged in
• Disable battery optimization

Monitor Connection Status

Set up alerts for when WhatsApp disconnects:

# In OpenClaw config
monitoring:
  alerts:
    - type: channel_disconnect
      channel: whatsapp
      action: notify_telegram

(Requires Telegram as backup channel)

Message Yourself for Testing

WhatsApp has a “Message yourself” feature. Use it for testing without spamming real contacts.

Group Chat Setup

You can use OpenClaw in WhatsApp groups:

1. Add the linked WhatsApp to a group
2. Configure how the bot responds:

channels:
  whatsapp:
    groupBehavior: "mention"  # Only respond when name is mentioned
    # or
    groupBehavior: "all"      # Respond to all messages (chatty)
    # or  
    groupBehavior: "command"  # Only respond to /commands

Warning: “all” mode in active groups will use lots of API tokens.

Security Considerations

Your Account, Your Risk

WhatsApp integration uses your personal account. Be aware:

• OpenClaw can see all your messages (configure filters if needed)
• Messages sent by OpenClaw appear from YOUR number
• WhatsApp’s ToS technically prohibit automation

Limit What OpenClaw Sees

If you don’t want OpenClaw processing all messages:

channels:
  whatsapp:
    onlyFrom:
      - "+1234567890"  # Only process messages from specific numbers

Use a Separate Number for Business

If using OpenClaw for business responses:

• Use WhatsApp Business with a business number
• Keep personal and business separate
• Consider the official WhatsApp Business API (more complex but more reliable)

WhatsApp vs Telegram

Feature	WhatsApp	Telegram
Reliability	Lower (session expires)	Higher (bot API is stable)
Setup	QR code scan	Bot token
Streaming	Limited	Full support
Group features	Basic	Advanced
User base	Larger	Smaller

My recommendation: Use Telegram for your primary OpenClaw interface. Use WhatsApp if:

• Your contacts are only on WhatsApp
• You need to respond to WhatsApp messages specifically
• You’re building a customer service bot

Troubleshooting Checklist

[ ] WhatsApp enabled in config
[ ] Gateway is running
[ ] QR code scanned successfully  
[ ] Phone connected to internet
[ ] WhatsApp not killed by battery saver
[ ] Session hasn't expired (check logs)
[ ] Phone hasn't logged out the device

Alternative: WhatsApp Business API

For businesses needing reliable WhatsApp integration, consider the official WhatsApp Business API:

• More stable (no session expiry)
• Official support
• Costs money (~$0.05-0.15 per conversation)
• Requires business verification

This is a bigger setup but more production-ready.

Need Help?

WhatsApp setup can be tricky. If you’re stuck:

• Check logs: journalctl -u openclaw | grep -i whatsapp
• OpenClaw Discord: Community help
• SetupMyClaw: We can configure WhatsApp during your setup call

Book a setup call →

---

Questions? Email us.