Connecting OpenClaw to WhatsApp via Baileys | OpenClaw

Note: OpenClaw was previously known as MoltBot and Clawdbot.

WhatsApp is the most-used messaging app in the world. OpenClaw connects to it via Baileys, a reverse-engineered implementation of the WhatsApp Web protocol.

⚠️ Important Disclaimer

WhatsApp does not have an official Bot API. Baileys is an unofficial library. Risks include:

WhatsApp may ban the phone number used
No stability guarantees from WhatsApp
Use a dedicated phone number — not your primary one

For business use cases, consider the official WhatsApp Business API instead.

What You’ll Get

✅ AI assistant in WhatsApp
✅ Direct messages and group chats
✅ Voice message support
✅ Image and document handling
✅ Multi-device (phone + OpenClaw simultaneously)

Step 1: Get a Dedicated Phone Number

Use a separate SIM card or phone number. Good options:

A spare SIM you already have
A virtual number / eSIM
A dedicated business number

Step 2: Configure OpenClaw

Enable the WhatsApp channel

nano ~/.openclaw/openclaw.yaml

channels:
  whatsapp:
    enabled: true

    # Session storage path
    sessionPath: "~/.openclaw/whatsapp-session"

    # Auto-reconnect on disconnect
    autoReconnect: true

    logLevel: "info"

Step 3: First Launch & QR Code

Start OpenClaw

openclaw gateway

Scan the QR code

A QR code will appear in your terminal:

█████████████████████████████████
████ ▄▄▄▄▄ █▀▄▀▄█ ▀█ ▄▄▄▄▄ ████
████ █   █ █▄▀▄ █▀▄█ █   █ ████
...

On your phone:

Open WhatsApp
Go to Settings → Linked Devices → Link a Device
Scan the QR code

Successful connection

[whatsapp] Connected!
[whatsapp] Logged in as: +1-555-0123
[whatsapp] Ready to receive messages

Step 4: Test It

Send a message

From a different number, message the bot:

“Hey, you there?”

OpenClaw should reply within seconds.

Check logs

journalctl -u openclaw -f | grep whatsapp

Advanced Configuration

Incoming message pairing

gateway:
  dmPairing:
    enabled: true
    approvalMode: "manual"

channels:
  whatsapp:
    welcomeMessage: |
      👋 Hey! This is an AI assistant.
      Send any message to get started.

Group chat support

channels:
  whatsapp:
    groups:
      enabled: true
      respondToMentions: true    # Only reply when @mentioned
      respondToCommands: true    # Also respond to /commands

Supported media types

channels:
  whatsapp:
    media:
      images: true        # Handle image messages
      voice: true         # Transcribe voice notes
      documents: true     # Process uploaded files
      maxSizeMB: 10

Reconnection & Session Persistence

OpenClaw stores the WhatsApp session locally. If you restart the server, it reconnects automatically — no need to re-scan the QR code.

# Session is stored here:
ls ~/.openclaw/whatsapp-session/

If the session expires or gets revoked, delete the folder and re-scan:

rm -rf ~/.openclaw/whatsapp-session
openclaw gateway

Troubleshooting

QR code keeps regenerating
Make sure the session folder is writable. Check with ls -la ~/.openclaw/.

Bot stops responding after a few hours
Enable auto-reconnect in your config and verify your autoReconnect: true is set.

Account banned by WhatsApp
This can happen if the bot sends messages too quickly or receives spam reports. Use a dedicated number and set reasonable rate limits.

What’s Next?

Set up Telegram as a backup channel
Install skills to give your bot capabilities
Build automations for scheduled tasks