WhatsApp Bot Setup

Overview

OpenClaw integrates with WhatsApp via WhatsApp Web using the Baileys library. This is the most popular channel for OpenClaw deployments.

Quick Setup

1. Configure WhatsApp Channel

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+15555550123"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

2. Pair via QR Code

openclaw channels login

This will display a QR code. Scan it with your WhatsApp mobile app:

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

3. Start the Gateway

openclaw gateway

Access Control

Direct Messages

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123", "+15555550456"]
    }
  }
}

Group Mentions

{
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}

Features

• ✅ Direct messages
• ✅ Group chats with mention activation
• ✅ Image and media sending/receiving
• ✅ Document sharing
• ✅ Voice note transcription
• ✅ QR code pairing (no API key needed)

Session Persistence

WhatsApp sessions are stored in ~/.openclaw/state/. Back up this directory to preserve your WhatsApp connection across restarts.

Troubleshooting

QR code expired

Run openclaw channels login again to generate a new QR code.

Disconnected frequently

• Ensure your phone has a stable internet connection
• Keep the WhatsApp app running in the background
• Check openclaw gateway status for errors

Messages not sending

• Verify the phone number format includes country code
• Check allowFrom configuration

Next Steps

• Telegram Deployment — Telegram setup
• AI Agent — Configure agent behavior
• Security — Access control best practices