connect

Connect OpenClaw to WhatsApp (Step-by-Step)

Learn how to connect OpenClaw to WhatsApp and chat with AI through your favorite messaging app. Complete beginner guide with QR code authentication.

9 min read
Updated 2026-02-03

What You Will Achieve

By following this guide, you will connect OpenClaw to WhatsApp. Once connected, you can send messages on WhatsApp and receive AI-powered responses. This is perfect for people who use WhatsApp as their primary messaging app and want AI assistance on the go.

How WhatsApp Connection Works

Unlike Telegram and Discord which use bots, WhatsApp connection works differently. OpenClaw connects to WhatsApp Web, the same technology that powers WhatsApp on your computer. You will scan a QR code to link your WhatsApp account, and then OpenClaw can send and receive messages on your behalf.

Important Limitations

WhatsApp has strict policies about automated messaging. Using OpenClaw with WhatsApp is intended for personal use only. Do not use it to spam or send bulk messages, as this may result in your WhatsApp account being banned.

Before You Start

Make sure you have completed these steps:

  1. OpenClaw is installed and running on your computer
  2. You have a WhatsApp account with an active phone number
  3. WhatsApp is installed on your phone and working normally

Check OpenClaw Status First

Before continuing, open your terminal and run openclaw status. You should see "Gateway: running". If not, start OpenClaw first by running openclaw gateway --daemon.

Verify OpenClaw is running:

bash
openclaw status

Expected Result

Gateway: running Port: 18789 Auth: configured

Understanding the Process

Here is what we will do:

  1. Start the WhatsApp channel in OpenClaw
  2. Scan a QR code with your phone (like WhatsApp Web)
  3. Test the connection by sending a message
  4. Configure auto-reply settings (optional)

WhatsApp Web Technology

OpenClaw uses the same connection method as WhatsApp Web. When you scan the QR code, your phone authorizes OpenClaw to access your WhatsApp messages. Your phone must stay connected to the internet for this to work.

Step-by-Step Setup

1

Enable the WhatsApp Channel

First, we need to tell OpenClaw that we want to use WhatsApp. Edit the OpenClaw configuration file.

Open your terminal and edit the config file:

bash
nano ~/.openclaw/openclaw.json

Add the WhatsApp channel configuration:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing"
    }
  }
}

What is dmPolicy?

  • "pairing" (default): New contacts must be approved before getting AI responses
  • "allowlist": Only specific phone numbers can use the bot
  • "open": Anyone can message and get responses (use with caution)

Save the file (Ctrl+O, then Ctrl+X in nano).

Expected Result

Your configuration file now includes WhatsApp settings.

2

Restart the Gateway

For the new channel to work, we need to restart OpenClaw's gateway.

bash
openclaw gateway restart

Wait a few seconds for the gateway to restart with WhatsApp support enabled.

Expected Result

Stopping gateway... Starting gateway... Gateway started successfully Channels: whatsapp (waiting for QR)

3

Display the QR Code

Now we need to get a QR code to scan with your phone.

bash
openclaw channels login --channel whatsapp

A QR code will appear in your terminal. If your terminal does not display it correctly, you can also view it in your browser.

QR Code Not Showing Correctly?

If the QR code looks broken in your terminal, try opening the OpenClaw dashboard in your browser at http://127.0.0.1:18789/ and look for the WhatsApp QR code there.

Expected Result

Scan this QR code with WhatsApp on your phone:

█████████████████████████████ █████████████████████████████ ████ ▄▄▄▄▄ █▀▄▀▄█ ▄▄▄▄▄ ████ ████ █ █ █▄▀ ▀█ █ █ ████ ████ █▄▄▄█ █ ▄▀██ █▄▄▄█ ████ ████▄▄▄▄▄▄▄█▄▀▄█▄▄▄▄▄▄▄▄████ █████████████████████████████

Waiting for scan...

4

Scan the QR Code with Your Phone

Now pick up your phone and scan the QR code.

On your phone:

  1. Open WhatsApp
  2. Tap the three dots menu (top right on Android) or Settings (bottom right on iPhone)
  3. Tap Linked Devices
  4. Tap Link a Device
  5. Your phone's camera will open. Point it at the QR code on your computer screen.

Face ID or Fingerprint

Your phone may ask you to authenticate with Face ID, Touch ID, or your phone passcode before scanning. This is a security feature to prevent unauthorized access.

Expected Result

After scanning, your terminal will show: WhatsApp connected successfully! Logged in as: +1234567890

Important: Keep your phone connected to the internet. If your phone goes offline, the WhatsApp connection will stop working.

5

Verify the Connection

Let us make sure everything is working.

bash
openclaw status

Expected Result

Gateway: running Port: 18789 Auth: configured Channels: whatsapp (connected)

You should see whatsapp (connected) in the channels list.

6

Configure Auto-Reply (Optional)

By default, OpenClaw will only respond to messages from approved contacts. You can configure how it responds by editing the configuration file.

Edit ~/.openclaw/openclaw.json:

Option A: Respond only to specific contacts (allowlist)

This is the safest option. Only phone numbers in the list can get AI responses.

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "+15559876543"]
    }
  }
}

Option B: Use pairing mode (default)

New contacts receive a pairing code that you must approve.

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    }
  }
}

Use With Caution

If you set dmPolicy to open with allowFrom: ["*"], anyone who messages you will get an AI response. This could be confusing for people who do not know about your AI setup.

7

Test Your First Message

Now let us test that AI responses are working!

Option A: Message yourself

You can send a message to yourself on WhatsApp:

  1. Open WhatsApp on your phone
  2. Find your own contact (or message your saved number)
  3. Send a message like "Hello AI!"

Option B: Ask a friend to message you

Have a friend send you a WhatsApp message. If they are not yet approved, they will receive a pairing code.

For new contacts (pairing required):

When someone new messages you, they receive a pairing code. Approve them in your terminal:

bash
openclaw pairing list whatsapp

Expected Result

Pending pairing requests: [1] WhatsApp: +1987654321 (Code: 789012)

bash
openclaw pairing approve whatsapp 789012

Replace 789012 with the actual pairing code shown.

8

Test the AI Response

After pairing is complete, send another message:

  1. Open WhatsApp
  2. Send a message like "What is the weather like today?"

Expected Result

You should receive an AI-generated response within a few seconds.

Congratulations!

You have successfully connected OpenClaw to WhatsApp! You can now chat with AI through WhatsApp on any device.

Common Problems and Solutions

QR code expired

QR codes expire after a short time for security reasons.

Solution: Run the login command again to get a fresh code:

bash
openclaw channels login --channel whatsapp

"WhatsApp disconnected" message

This happens when your phone loses internet connection or WhatsApp is closed.

Solution:

  1. Make sure your phone has internet access
  2. Open WhatsApp on your phone
  3. Run openclaw gateway restart to reconnect

QR code looks corrupted in terminal

Some terminals do not display QR codes correctly.

Solution:

  1. Open your browser
  2. Go to http://127.0.0.1:18789/
  3. Find the WhatsApp section and scan the QR code from there

"Session logged out" error

WhatsApp may log out linked devices periodically for security.

Solution:

  1. Run openclaw channels login to get a new QR code
  2. Scan again with your phone

Phone battery drains quickly

WhatsApp needs to maintain a connection to your phone, which can use battery.

Tips:

  • Keep your phone plugged in when possible
  • Use WiFi instead of mobile data
  • Close other apps you are not using

Messages not being received

Check if WhatsApp on your phone is working correctly.

Solution:

  1. Open WhatsApp on your phone and send a test message to a friend
  2. If that works, restart the OpenClaw gateway: openclaw gateway restart
  3. Check the logs: openclaw logs --limit 20

Bot responds to wrong messages

By default, OpenClaw may respond to all messages.

Solution: Edit ~/.openclaw/openclaw.json to use allowlist mode:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"]
    }
  }
}

Only phone numbers in the allowFrom list will get responses.

Privacy and Security

Your Messages Are Processed

When using OpenClaw with WhatsApp, your messages are sent to AI services for processing. Be mindful of what information you share.

Important security considerations:

  1. End-to-end encryption: WhatsApp messages are encrypted between you and the recipient. However, OpenClaw needs to read the message content to provide AI responses.

  2. Message storage: OpenClaw may temporarily store messages for processing. Check your OpenClaw configuration to understand data retention.

  3. Account security: Never share your QR code screenshots. Anyone who scans your QR code can access your WhatsApp messages.

To disconnect WhatsApp from OpenClaw:

bash
openclaw channels remove --channel whatsapp
openclaw gateway restart

You can also disconnect from your phone:

  1. Open WhatsApp
  2. Go to Linked Devices
  3. Tap on the OpenClaw session
  4. Tap Log Out

Advanced Configuration

All advanced configurations are done by editing ~/.openclaw/openclaw.json.

Disable read receipts

Prevent blue checkmarks from appearing when messages are read:

{
  "channels": {
    "whatsapp": {
      "sendReadReceipts": false
    }
  }
}

Configure group messages

Allow the bot to respond in WhatsApp groups:

{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groups": ["*"]
    }
  }
}

Add acknowledgment reaction

Automatically react to messages when processing:

{
  "channels": {
    "whatsapp": {
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": "mentions"
      }
    }
  }
}

Using WhatsApp on Multiple Devices

One of the benefits of WhatsApp is that it syncs across devices:

  • Phone: Primary device, must stay connected
  • WhatsApp Web: Access from any browser
  • WhatsApp Desktop: Native app for Windows and Mac

Your AI conversations will appear on all your devices. However, remember that the AI only responds through OpenClaw on your computer. If OpenClaw is not running, you will not get AI responses.

What To Do Next

Now that WhatsApp is connected, explore these options:

  1. Connect to Telegram - Add Telegram as another channel
  2. Connect to Discord - Use AI in Discord servers
  3. Multi-Channel Setup - Use all platforms together
  4. Your First Agent - Customize your AI's behavior

Need Help?

If you run into problems not covered here, check our Troubleshooting guide or visit the official OpenClaw documentation.

Last updated: February 3, 2026 | Found an error? Contact us

Related Articles

Connect

Connect OpenClaw to Discord (Step-by-Step)

Connect

Connect OpenClaw to Telegram (Step-by-Step)

Connect

Use OpenClaw on Multiple Channels