Complete Guide to Connecting OpenClaw to WhatsApp

Why Connect WhatsApp

WhatsApp is one of the most widely used messaging apps in the world. Connecting OpenClaw to WhatsApp means you can chat with your AI assistant right inside the app you already use every day. No extra apps to open, no new URLs to remember — sending a message to your AI is as natural as texting a friend.

OpenClaw connects to WhatsApp through the WhatsApp Web protocol, similar to how logging into WhatsApp Web on a computer works. Let's walk through the entire setup.

Prerequisites

Before getting started, make sure:

• OpenClaw is installed and running (see the installation guide)
• At least one AI model provider is configured (e.g., Anthropic Claude)
• You have a working WhatsApp account
• The WhatsApp app on your phone is up to date

Add the WhatsApp Channel via the Onboard Wizard

If you're still in the initial setup phase, the openclaw onboard wizard will ask which channels you'd like to connect — simply select WhatsApp.

If you've already finished the initial setup and want to add the WhatsApp channel separately, run:

openclaw channel add whatsapp

This command starts the WhatsApp channel configuration flow.

Scan the QR Code to Pair

After running the channel add command, a QR code will appear in your terminal. Use your phone's WhatsApp to scan it and complete the pairing:

1. Open WhatsApp on your phone
2. Go to Settings > Linked Devices (iOS) or Menu > Linked Devices (Android)
3. Tap Link a Device
4. Point your phone's camera at the QR code displayed in the terminal

Once the scan is successful, the terminal will confirm the connection. The entire process usually takes just a few seconds.

If the QR code expires (typically after 60 seconds), press Enter to generate a new one.

Verify the Configuration

After pairing, OpenClaw automatically updates the configuration file. You can check ~/.config/openclaw/openclaw.json5 to confirm the WhatsApp channel was added:

{
  channels: {
    whatsapp: {
      enabled: true,
      autoReply: true,
      // Conversation settings
      allowedNumbers: [],  // Empty array = all numbers allowed
      ignoreGroups: true   // Ignore group messages by default
    }
  }
}

Key configuration options:

• autoReply: When set to true, the bot replies automatically to incoming messages. Set to false to require a specific prefix to trigger responses.
• allowedNumbers: Restricts which phone numbers can chat with the AI. Leave empty for no restrictions. For security, consider adding only your own number.
• ignoreGroups: Whether to ignore messages from group chats. It's recommended to keep this true initially to avoid unexpected replies in groups.

Test Message Sending and Receiving

Make sure the OpenClaw Gateway is running:

openclaw up

Then have another WhatsApp account (or ask a friend) send a message to your WhatsApp number. If everything is configured correctly, OpenClaw will generate a reply through the AI model and send it back automatically.

You can also test by messaging yourself. In WhatsApp, find the "yourself" conversation (the self-messaging feature) and send a message to see if the AI replies.

The Dashboard is also useful for monitoring message flow:

openclaw dashboard

The Dashboard displays message logs for all channels, making it easy to confirm that messages are flowing correctly.

Troubleshooting

QR code scans but nothing happens

• Make sure your phone and computer are on the same network
• Check that WhatsApp is updated to the latest version
• Try restarting the OpenClaw service and scanning again

Messages are sent but no reply comes back

Start by checking the Gateway logs:

openclaw logs

Common causes include:

• The AI model provider's API key is invalid or the balance is depleted
• The network can't reach the API endpoint (especially in certain network environments)
• autoReply is set to false

Connection drops frequently

The WhatsApp Web connection can sometimes drop due to network instability. OpenClaw has a built-in auto-reconnect mechanism, but if disconnections are frequent, check the following:

• Is WhatsApp on your phone staying online?
• Is your phone's network connection stable?
• Are you logged into WhatsApp Web on other devices? (A maximum of 4 linked devices are supported)

Run the diagnostic command for more details:

openclaw doctor

Don't want the bot to reply in groups

Make sure ignoreGroups is set to true in the configuration file. If you'd like to enable AI replies in specific groups only, configure a group allowlist:

{
  channels: {
    whatsapp: {
      ignoreGroups: false,
      allowedGroups: ["group-id-1", "group-id-2"]
    }
  }
}

Security Recommendations

• Use allowedNumbers to restrict which numbers can interact with the AI, preventing strangers from running up your API bill
• Regularly check the message logs in the Dashboard to watch for unusual activity
• Avoid sending sensitive personal information in conversations with the AI assistant

Wrapping Up

WhatsApp is one of the most popular channels for OpenClaw, and the setup process is quite straightforward. Once paired, it requires virtually no maintenance — OpenClaw handles connection keep-alive and message routing automatically. If you encounter issues, check the OpenClaw official documentation or search for related issues on the OpenClaw GitHub repository. For more channel integration guides, visit OpenClaw.