How to Setup a WhatsApp Channel with OpenClaw

Published: March 9, 2026

Category: OpenClaw Channels

Tags: OpenClaw, WhatsApp, Setup Guide, QR Code, Baileys

---

Introduction

WhatsApp is the world's most popular messaging platform with over 2 billion users worldwide. Setting up WhatsApp as an OpenClaw channel allows your AI assistant to communicate with the largest possible audience while maintaining the privacy and security that WhatsApp users expect.

This comprehensive guide will walk you through setting up WhatsApp with OpenClaw, from initial configuration to troubleshooting common issues.

Prerequisites

Before starting, ensure you have:
- OpenClaw Gateway installed and running
- A phone number that can receive WhatsApp messages
- Access to WhatsApp on your mobile device
- Basic understanding of terminal/command line operations

Understanding WhatsApp Integration

OpenClaw uses the Baileys library to connect with WhatsApp. This approach:
- Preserves end-to-end encryption for all messages
- Requires QR code pairing for security
- Stores session data locally on your machine
- Supports groups, media, and reactions just like the official app

Step-by-Step Setup Process

Step 1: Configure WhatsApp Channel

First, add WhatsApp to your OpenClaw configuration:

1. Open your OpenClaw configuration file:
   bash
nano ~/.openclaw/openclaw.json


2. Add the WhatsApp channel configuration:
   json
{
"channels": {
"whatsapp": {
"enabled": true,
"sessionDir": "~/.openclaw/whatsapp-session",
"allowFrom": ["+1234567890"],
"groups": {
"*": {
"requireMention": true
}
}
}
}
}


Configuration Options Explained:
- enabled: Enable/disable the WhatsApp channel
- sessionDir: Where WhatsApp session data is stored
- allowFrom: Phone numbers allowed to message your bot
- groups: Group chat settings (requireMention prevents spam)

Step 2: Start the Gateway

Launch OpenClaw with WhatsApp enabled:

openclaw gateway --port 18789 --verbose

You should see startup logs indicating WhatsApp is initializing:

[WhatsApp] Initializing Baileys client...
[WhatsApp] Waiting for QR code generation...


Step 3: Generate QR Code

The Gateway will generate a QR code for pairing. You'll see:

[WhatsApp] QR Code generated. Please scan with WhatsApp mobile app.
[WhatsApp] QR Code expires in 60 seconds.

To view the QR code:
1. Open the Web Control UI: http://localhost:18789
2. Navigate to the WhatsApp section
3. A QR code will be displayed on screen

Step 4: Scan QR Code with WhatsApp

On your mobile device:

1. Open WhatsApp
2. Go to Settings → Linked Devices
3. Tap Link a Device
4. Point your camera at the QR code on your screen
5. Wait for confirmation

Step 5: Verify Connection

After successful scanning, you should see:

[WhatsApp] Successfully authenticated!
[WhatsApp] Session saved to ~/.openclaw/whatsapp-session
[WhatsApp] Ready to receive messages.

Step 6: Test Your Setup

Send a test message from an allowed number:

1. From your phone, send a WhatsApp message to the connected number
2. OpenClaw should process the message and respond
3. Check the Gateway logs for confirmation

Example test message:

You: Hello OpenClaw
OpenClaw: Hello! I'm your OpenClaw assistant. How can I help you today?


Advanced Configuration

Group Chat Settings

Configure how OpenClaw behaves in WhatsApp groups:

{
  "channels": {
    "whatsapp": {
      "groups": {
        "family-group": {
          "requireMention": false,
          "allowAdminOnly": true
        },
        "work-group": {
          "requireMention": true,
          "mentionPatterns": ["@bot", "@assistant"]
        }
      }
    }
  }
}

Media Handling

Enable media support for images, videos, and documents:

{
  "channels": {
    "whatsapp": {
      "media": {
        "enabled": true,
        "maxSizeMB": 16,
        "autoDownload": true
      }
    }
  }
}

Security Configuration

Restrict who can interact with your assistant:

{
  "channels": {
    "whatsapp": {
      "allowFrom": [
        "+1234567890",
        "+1987654321"
      ],
      "blockFrom": [
        "+1555555555"
      ]
    }
  }
}

Troubleshooting Common Issues

QR Code Not Generating

Problem: No QR code appears in the Web UI

Solutions:
1. Check Gateway logs for errors
2. Ensure port 18789 is accessible
3. Clear browser cache and reload
4. Restart the Gateway service

QR Code Expired

Problem: "QR Code expired" message

Solutions:
1. Wait for automatic regeneration (60-second cycle)
2. Restart the WhatsApp channel manually
3. Check system time synchronization

Connection Failed

Problem: "Connection failed" after scanning

Solutions:
1. Verify internet connectivity
2. Check WhatsApp Business API limitations
3. Ensure phone number isn't already in use
4. Try scanning with better lighting conditions

Messages Not Being Received

Problem: OpenClaw not responding to messages

Solutions:
1. Check allowlist configuration
2. Verify the sender's phone number is allowed
3. Check group mention requirements
4. Review Gateway logs for processing errors

Session Persistence Issues

Problem: Having to re-scan QR code frequently

Solutions:
1. Ensure session directory has write permissions
2. Check disk space availability
3. Verify session file integrity
4. Consider using a persistent volume for Docker deployments

Best Practices

Security

• Use allowlists - Only allow known phone numbers
• Configure group policies - Prevent unwanted group interactions
• Monitor logs - Regular security audits
• Keep sessions secure - Protect session data files

Performance

• Optimize media settings - Balance quality vs. performance
• Configure appropriate timeouts - Prevent hanging connections
• Use connection pooling - For high-volume scenarios
• Monitor resource usage - Track memory and CPU consumption

Maintenance

• Regular updates - Keep OpenClaw and Baileys current
• Backup sessions - Preserve authentication data
• Monitor connection health - Set up alerts for disconnections
• Clean up old sessions - Remove unused authentication data

Advanced Features

Webhook Integration

Set up webhooks for external integrations:

{
  "channels": {
    "whatsapp": {
      "webhooks": {
        "onMessage": "https://your-app.com/webhook/message",
        "onStatus": "https://your-app.com/webhook/status"
      }
    }
  }
}

Custom Message Handling

Implement custom message processing:

// Custom message handler
function handleWhatsAppMessage(message, sender) {
  if (message.text.startsWith("/")) {
    // Process command
    return processCommand(message.text, sender);
  }
  // Default processing
  return processWithAI(message.text);
}

Business Account Integration

For WhatsApp Business API:

{
  "channels": {
    "whatsapp": {
      "business": {
        "enabled": true,
        "webhookVerifyToken": "your-verify-token",
        "apiVersion": "v16.0"
      }
    }
  }
}

Monitoring and Analytics

Monitor connection health:
bash
openclaw status --channel whatsapp


Track message volume:
json
{
"channels": {
"whatsapp": {
"analytics": {
"enabled": true,
"trackMessages": true,
"trackResponseTime": true
}
}
}
}


Next Steps

Now that you have WhatsApp configured, you can:

1. Set up additional channels - Check our Telegram, Discord, and Slack guides
2. Configure advanced features - Explore media handling and group management
3. Implement custom workflows - Create specialized message processing
4. Monitor performance - Set up logging and analytics

Related Guides:
- How to Setup Telegram Channel - Fastest channel to configure
- How to Setup Discord Channel - Perfect for communities
- How to Setup Slack Channel - Enterprise collaboration

---

Deep Layer provides cloud hosting for OpenClaw deployments, including WhatsApp channel setup and management.