popularchannels20 min read• March 2026

$ cat whatsapp-integration.md

export WhatsAppIntegration

/** Your OpenClaw AI, accessible from WhatsApp — anywhere, anytime */

table-of-contents.ts

const sections = [

]

section_01_architecture.md

🏗️## How It Works: The Gateway Architecture

WhatsApp does not provide a free official API for individuals, so OpenClaw uses a Gateway Architecture. The openclaw-messenger-gateway creates a virtual browser (Chromium) that logs into WhatsApp Web on your behalf and bridges messages to your OpenClaw instance.

▸

You → sends a WhatsApp message to yourself (or a dedicated number)

▸

Gateway → intercepts the message via WhatsApp Web

▸

OpenClaw → processes the request with your chosen AI model

▸

Reply → arrives back in your WhatsApp chat

// 💡 Pro tip: Use a secondary phone number (e.g., Google Voice or a cheap SIM) for a dedicated AI WhatsApp number rather than your personal number.

section_02_prerequisites.md

## ✅ Prerequisites

☐OpenClaw running and accessible (see Getting Started)

☐A WhatsApp account (dedicated secondary number recommended)

☐Docker installed on your host machine

☐Node.js 18+ (if running gateway without Docker)

☐Your server running 24/7 (VPS or always-on machine)

section_03_install.sh

## 📦 Install the WhatsApp Gateway

The OpenClaw messenger gateway is a separate service that runs alongside your main OpenClaw instance.

Option A: Docker (Recommended)

# Pull and start the gateway

$ docker pull ghcr.io/clawdbot/openclaw-messenger-gateway:latest

$ docker run -d \

--name openclaw-gateway \

-p 3001:3001 \

-e OPENCLAW_URL=http://YOUR_OPENCLAW_IP:18789 \

-v gateway-sessions:/app/sessions \

ghcr.io/clawdbot/openclaw-messenger-gateway:latest

Option B: Node.js

$ git clone https://github.com/clawdbot/openclaw-messenger-gateway

$ cd openclaw-messenger-gateway && npm install

$ cp .env.example .env

# Edit .env with your OpenClaw URL, then:

$ npm start

section_04_pair.md

## 📱 Pair Your WhatsApp Account

Once the gateway is running, you need to authenticate it with your WhatsApp account by scanning a QR code.

Step 1: Open the pairing UI

Navigate to http://YOUR_SERVER_IP:3001 in your browser.

Step 2: Scan the QR code

Open WhatsApp on your phone → Settings → Linked Devices → Link a Device. Scan the QR code shown in the gateway UI.

Step 3: Wait for confirmation

The UI should show Connected ✓ within 10 seconds. The session is saved to disk so it survives restarts.

// ⚠️ The QR code expires after 60 seconds. If it expires, refresh the page to get a new one.

section_05_config.yaml

## ⚙️ Connect to OpenClaw

In your OpenClaw configuration file, add the WhatsApp channel:

# openclaw/config.yaml

channels:

whatsapp:

enabled: true

gateway_url: "http://localhost:3001"

allowed_numbers:

- "+1234567890" # YOUR number

section_06_security.md

🔐## Secure Your Bot (Critical!)

This is the most important section. Giving an AI access to your WhatsApp means anyone who messages your number could interact with it. OpenClaw uses an Access Control List (ACL) — it ignores all messages from numbers not on the whitelist.

// Finding unauthorized attempt logs:

$ docker logs openclaw 2>&1 | grep "SECURITY"

[SECURITY] Unauthorized message from: +9876543210. Ignoring.

⚠️ NEVER leave allowed_numbers empty or set to * on a production server. This gives anyone unlimited AI access at your expense.

section_07_test.md

## 🧪 Test & Go Live

Send a message from your authorized WhatsApp number and check for a response:

// Your WhatsApp message:

You: "Hello! What's the weather like in Tokyo right now?"

// OpenClaw response (~10 seconds):

OpenClaw: "Currently in Tokyo: 12°C, partly cloudy..."

section_08_troubleshoot.md

## 🔧 Troubleshooting

Session Dies After Reboot

The -v gateway-sessions:/app/sessions Docker volume saves your WhatsApp session. If the session still drops, re-scan the QR code. Consider using --restart always on the Docker container.

QR Code Not Appearing

Check that port 3001 is accessible. If behind a firewall, run: sudo ufw allow 3001 temporarily during setup. Remember to restrict it afterward.

Messages Not Reaching OpenClaw

Verify the OPENCLAW_URL environment variable is correct. Check: curl http://YOUR_OPENCLAW_IP:18789/health should return OK.

WhatsApp Account Banned

WhatsApp occasionally bans accounts using unofficial gateways. This is rare with low-volume personal use, but a dedicated secondary number significantly reduces this risk.

next_steps.md

## 🚀 Next Steps

Your OpenClaw is now on WhatsApp! Explore more channels and secure your setup:

export TelegramSetup

// Add Telegram as a second channel

export VPSSecurityGuide

// Lock down your server first