Complete OpenClaw WhatsApp Integration Guide: From Configuration to Practice

Honestly, the first time I successfully chatted with AI on WhatsApp, it felt pretty magical. My most-used messaging app could suddenly invoke an AI assistant directly, without switching between applications.

If you also want to use OpenClaw on WhatsApp, this article will walk you through the configuration step-by-step. WhatsApp integration is slightly more complex than Telegram, but once you understand the principles, the whole process takes just 5-10 minutes.

Why Integrate AI with WhatsApp?

Before we begin, you might wonder: why not just use Telegram or the Web interface?

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

Actually, each platform has its own advantages. For me, choosing WhatsApp comes down to a few key reasons:

• Usage habits: WhatsApp is my daily messaging tool, where all my family and friends are
• Seamless integration: No need to open a separate AI app, just ask questions in the chat interface
• Linked Devices: WhatsApp’s multi-device feature is mature and stable
• Privacy control: Data stays on your own server, not passing through third parties

Of course, Telegram has its benefits too, like more open APIs and a richer bot ecosystem. Which one to choose depends on your specific use case.

Preparation: Check Your Environment

Before starting the integration, confirm a few prerequisites:

Required Conditions

1. OpenClaw installed and running - If not yet installed, check out the previous installation guide
2. WhatsApp account on your phone - Needs to be the primary account for QR code scanning
3. Gateway is running - Ensure openclaw gateway is started
4. Stable network - Network connectivity needed during QR code scanning

Technical Note

One detail to note: if you’re using the Bun runtime, you might encounter compatibility issues when connecting WhatsApp or Telegram. The official recommendation is to run the Gateway with Node.js for better stability.

Verify your runtime environment:

# Check Node.js version
node --version

# Confirm Gateway is running
ps aux | grep openclaw

Three Integration Methods

OpenClaw offers three methods to connect WhatsApp. I’ll introduce them in order of recommendation.

Method 1: Onboard Wizard (Simplest)

This is the most straightforward method, suitable for first-time configuration.

If you haven’t completed initial setup, run directly:

openclaw onboard --install-daemon

During the wizard process, you’ll be asked which messaging channels to connect. Select WhatsApp, then:

1. The terminal will display a QR code
2. Open WhatsApp on your phone, go to “Settings” → “Linked Devices”
3. Tap “Link a Device” and scan the QR code
4. After successful scanning, the terminal will show connection completed

The whole process is quick, taking 1-2 minutes. I was pretty nervous the first time I scanned, worried it wouldn’t work, but it connected right away.

Method 2: Channels Login Command

If you’ve already completed onboarding and just want to add the WhatsApp channel separately, use this command:

openclaw channels login

After running, here’s what happens:

1. Terminal displays QR code (or shows in Web interface)
2. Scan with WhatsApp
3. Connection established, starts receiving messages

The advantage of this method is it’s quick and direct, without entering the full configuration flow.

Method 3: Web Interface Configuration (Most Flexible)

If you want more granular control over configuration, you can set it up through the Web interface.

Access OpenClaw’s control panel (default is http://localhost:18789), then:

Step 1: Enter Configuration Page

Navigate to Settings → Config, click the RAW button in the upper right, entering the raw configuration editor.

Step 2: Add WhatsApp Configuration

Add WhatsApp configuration in the channels section:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+8613800138000"],
      "groupPolicy": "allowlist",
      "mediaMaxMb": 50,
      "debounceMs": 0
    }
  }
}

Let me explain what these configuration items mean:

• dmPolicy: Direct message policy, allowlist means only whitelist users allowed
• allowFrom: Whitelist, fill in your own phone number (international format with country code)
• groupPolicy: Group message policy, setting to allowlist is safer
• mediaMaxMb: Maximum media file size allowed to receive (MB)
• debounceMs: Message debounce delay (milliseconds), usually set to 0

Step 3: Save and Scan

Click the Update button in the upper right to save configuration, then return to the Channels page where you’ll see a QR code. Scan it with WhatsApp.

Detailed Configuration Explanation

Let’s dive deeper into those configuration items mentioned earlier.

Permission Management: Who Can Message Your AI?

dmPolicy and groupPolicy are two critical security configurations.

dmPolicy (Direct Message Policy) has three options:

• allowlist: Only numbers on the whitelist can send messages (recommended)
• denylist: Anyone except blacklist can send
• open: Anyone can send (not recommended unless you know what you’re doing)

I use allowlist myself, only adding my own and family members’ numbers. After all, AI has system access permissions—I don’t want strangers sending random messages.

allowFrom Phone Number Format

Numbers must use international format, including country code:

"allowFrom": [
  "+8613800138000",    // China number
  "+14155552671",      // US number
  "+447700900000"      // UK number
]

Don’t forget the plus sign + and country code, or it won’t be recognized.

groupPolicy (Group Policy)

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

If you want to use AI in WhatsApp groups, you need to configure group policy. Honestly though, I don’t recommend opening AI permissions in groups unless it’s a completely trusted private group.

You can configure like this:

"groupPolicy": "allowlist",
"allowFrom": ["group-id"]

Group IDs can be found in logs, or set to open first, send a message, then see the ID in logs.

Message Routing: How AI Processes Your Messages

OpenClaw automatically routes WhatsApp messages to the AI model for processing. The flow works like this:

1. You send a message on WhatsApp
2. OpenClaw Gateway receives the message
3. Checks if sender is on whitelist
4. If approved, forwards to AI model
5. AI generates response
6. Response sent to WhatsApp

This process is fast, usually completing within 1-2 seconds (depending on AI model response speed).

Media File Handling

The mediaMaxMb setting determines how large files can be received. The default 50MB is generally sufficient.

Currently supported media types in OpenClaw include:

• Images (JPG, PNG, etc.)
• Audio files
• Documents (PDF, TXT, etc.)

If your AI is configured with vision capabilities (like GPT-4V), it can recognize image content when you send pictures.

QR Code Scanning Steps Explained

Regardless of which method you use, you’ll eventually need to scan a QR code. This step is simple, but there are a few details to note.

Mobile Device Operations

1. Open WhatsApp app
2. Tap “More options” in the upper right (three dots)
3. Select “Linked Devices”
4. Tap “Link a Device”
5. May need to verify fingerprint or enter password
6. When camera opens, aim at the QR code on your computer

Computer-Side Considerations

• QR code validity: QR codes usually expire after 1-2 minutes, refresh and regenerate if scanning fails
• Clarity: Ensure QR code displays clearly, terminal font shouldn’t be too small
• Network: Network connection needed at the moment of scanning, ensure both phone and computer are online

The first time I scanned, the terminal font was too small and the QR code was blurry, taking several attempts to succeed. Later I discovered enlarging the terminal window solved it.

Connection Success Indicators

After successful scanning, you’ll see:

• Mobile side: OpenClaw appears in the “Linked Devices” list
• Computer side: Terminal shows “WhatsApp connected” or similar message
• Web interface: Channels page shows WhatsApp as green (connected)

Testing and Verification

After connection completes, test immediately to ensure everything works.

Send First Message

Send yourself a message on WhatsApp, like:

Hello, can you hear me?

If configured correctly, AI should reply within a few seconds. The first time I received a reply, I smiled at my phone screen for a while—so amazing.

Check Different Message Types

Try these operations:

• Text messages: Ask AI a question
• Images: Send an image, have AI describe the content (requires vision model)
• Documents: Send PDF or TXT files
• Voice: If supported, try voice-to-text

Check Logs

If problems occur, checking logs can help troubleshoot:

# View OpenClaw logs
openclaw gateway --port 18789

Logs will show received messages, processing flow, error messages, etc.

Troubleshooting Common Issues

When installing software, problems are inevitable. I’ve listed the pitfalls I’ve encountered and their solutions.

Issue 1: No Response After QR Code Scanning

Possible causes:

• QR code expired
• Network connection issues
• WhatsApp version too old

Solutions:

Alibaba Cloud - Top choice for developers, exclusive 15% off for Lighthouse servers

Get 15% Discount →Ad

1. Refresh QR code and rescan
2. Check network connection on both phone and computer
3. Update WhatsApp to latest version

Issue 2: Connection Failed with status=515 Error

This is a fairly common error, specifically mentioned in official documentation.

Full error message:

WhatsApp login failed: status=515 Unknown Stream Errored (restart required)

Solutions:

1. Return to Settings → Config
2. Click Update button in upper right (even if no config changes)
3. Return to Channels page to check connection status
4. If still not working, restart Gateway

# Restart Gateway
pkill -f openclaw
openclaw gateway --port 18789

Issue 3: Message Sent, AI Doesn’t Reply

Possible causes:

• Sender not on whitelist
• AI model configuration issues
• API key invalid

Troubleshooting steps:

1. Check if number format is correct (international format)
2. View logs, confirm message was received
3. Test if AI responds normally in Web interface
4. Verify API key is valid

Issue 4: Permission Denied

Symptoms: After sending message, receive “Permission denied” or no reply

Solutions:

• Confirm your number is in allowFrom list
• Check number format (including country code)
• If group message, check groupPolicy settings

Issue 5: Cannot Send Media Files

Possible causes:

• File exceeds mediaMaxMb limit
• File format not supported
• Network upload failed

Solutions:

• Increase mediaMaxMb setting
• Try compressing file
• Check network connection

Issue 6: Disconnected After Gateway Restart

Symptoms: After restarting computer or Gateway, WhatsApp disconnects

Solutions:

1. Should automatically reconnect normally
2. If not, rerun openclaw channels login
3. Rescan to reconnect
4. Or check if daemon started properly

Advanced Tips

After basic functionality is set up, you can explore some advanced configurations.

Multi-Device Management

WhatsApp allows multiple devices connected simultaneously. If you have OpenClaw installed on multiple computers, you can connect separately, and messages will sync to all devices.

However note: for the same WhatsApp account, OpenClaw can only connect once. To connect multiple computers, you need different WhatsApp accounts.

Custom Reply Strategy

You can set debounceMs in configuration to control message debouncing:

"debounceMs": 1000

This way if you send multiple messages consecutively, AI will wait 1 second before processing them together, avoiding frequent API calls.

Message Filtering

If you want to ignore certain message types, you can set filter rules in Skills configuration. For example, only respond to messages starting with “AI”.

Railway - Modern deployment platform, zero-config, go live in minutes

Start Now →Ad

Performance Optimization

If message volume is large, consider:

• Reducing mediaMaxMb limit to save bandwidth
• Adjusting debounceMs to avoid frequent requests
• Using faster AI models

Security Recommendations

After WhatsApp integration, several security considerations are essential:

1. Strictly Control Whitelist

Only add trusted numbers to the allowFrom list. Remember, these numbers can execute system commands through AI (if relevant skills are enabled)—that’s significant permission.

2. Regularly Check Connected Devices

In WhatsApp’s “Linked Devices”, regularly check which devices are online. If you find unrecognized ones, remove immediately.

3. Confirmation for Sensitive Operations

For operations like deleting files or modifying configurations, recommend adding double-confirmation mechanisms in skills to avoid mistakes.

4. Don’t Connect on Public Devices

If in internet cafes, libraries, or other public places, don’t scan to connect WhatsApp. Devices may be monitored, leading to account exposure.

5. Regularly Update OpenClaw

Keep OpenClaw updated to the latest version, ensuring security patches are applied promptly:

npm update -g openclaw
# or
pnpm update -g openclaw

Final Thoughts

Alright, by now you should have successfully integrated WhatsApp with OpenClaw. Let’s recap the process:

WhatsApp vs Telegram: How to Choose?

If you’re still torn about which platform to use, here’s some advice:

Choose WhatsApp if:

• WhatsApp is your primary daily communication tool
• Need to share AI with family and friends
• Value the stability of Linked Devices

Choose Telegram if:

• Want more open API capabilities
• Need to use bot ecosystem
• Have requirements for channels and group features

Honestly, you can configure both. OpenClaw supports multi-channel simultaneous operation—you can integrate both WhatsApp and Telegram, choosing the appropriate platform for specific scenarios.

What to Do Next?

After successful connection, you can:

• Explore OpenClaw’s Skills feature to add more AI capabilities
• Try sending images and documents to test multimodal functionality
• Research custom reply logic
• If interested, develop your own skill plugins

One last reminder: while WhatsApp integration is convenient, pay attention to security. Carefully manage the whitelist, don’t open AI permissions to untrusted people.

Have fun, and check documentation or ask the community if you have questions!

References:

• OpenClaw Official Documentation
• How to Link WhatsApp Devices
• OpenClaw Community Forum

10 min read · Published on: Feb 5, 2026 · Modified on: Feb 5, 2026

Easton

AI & Intelligence