Have you ever wished your AI assistant could just text you, like a friend who’s always awake and ready to help? That’s exactly what happens when you connect OpenClaw to WhatsApp. Instead of opening a website or a fancy app, you open the WhatsApp chat you already use every day, and your AI agent is right there waiting.

But let’s be honest, the first time you try to connect OpenClaw to WhatsApp, it can feel confusing. There are terminal commands, QR codes, and settings with names like “dmPolicy” that sound more like robot language than something a regular person should deal with. 

Luckily, this article is for you if you’re brand new to OpenClaw, brand new to WhatsApp bots, or just someone who wants a simple, step-by-step walkthrough on how to connect OpenClaw to WhatsApp. 

So grab a coffee, open your terminal, and let’s log in and get started.

What You Need to Connect OpenClaw to WhatsApp

But before you connect OpenClaw to WhatsApp, there are a few things you need to have ready. Skip one, and things won’t come together right.

• A machine to run OpenClaw on. This can be a Mac, a Windows computer, or a Linux machine. OpenClaw can use hosted models, subscription-backed models, gateway models, or even local models. The important part is that your data and “state” (your settings and history) live on your own machine, not some far-away company’s server.
• A WhatsApp account with the app installed on your phone. You’ll need this because WhatsApp uses your phone to confirm it’s really you.
• A dedicated WhatsApp number (optional, but recommended). You don’t have to use a brand-new number just for OpenClaw, but it keeps things neat, since setup and background data are built with a dedicated number in mind. If you’d rather use your personal number, that’s fine too; OpenClaw supports personal-number and “self-chat” setups just as well.

Once you’ve checked off these three things, you’re ready to get started.

Step I. Install the WhatsApp Plugin

The first real step to connect OpenClaw to WhatsApp is installing something called the WhatsApp plugin. Think of a plugin as an extra tool that snaps onto OpenClaw so it can talk to WhatsApp specifically. 

OpenClaw supports WhatsApp through two main engine choices: Baileys and whatsmeow. Both connect your AI agent to WhatsApp without needing a real phone open, acting like an official app on your network.

Baileys

Baileys is built on JavaScript and Node.js and connects straight to WhatsApp Web through secure WebSockets. It is the native choice for OpenClaw, easy to set up, and a natural fit for small personal setups, though it uses more memory and carries a higher ban risk since Meta flags unofficial web apps more easily.

Whatsmeow

Whatsmeow is built on Go and uses a native client protocol instead of simulating a web browser. It suits bots that run 24/7, production projects, and servers, and it connects to OpenClaw through a Go-based bridge. It is more stable, lighter on memory, and closer to how the official app behaves, which lowers ban risk, but it takes more effort to set up since you need to compile or run a separate Go binary.

Here’s the easy part: you usually don’t have to install it separately. If you run any of these three commands:

openclaw onboard
openclaw channels add --channel whatsapp
openclaw channels login --channel whatsapp

…OpenClaw notices you’re trying to use WhatsApp for the first time, and offers to install the plugin right then and there. It’s a bit like when your phone asks, “You need this app to open that file, want me to download it?”

• If you’re using a dev checkout (a more advanced, developer-style setup), OpenClaw uses a plugin already installed at a local path on your computer.
• If you’re using the regular stable or beta version, it grabs @openclaw/whatsapp from ClawHub first, and falls back to npm (a big online library of tools) if that does not work.
• If you ever want to install it yourself, without waiting for a prompt, you can just type:

openclaw plugins install clawhub:@openclaw/whatsapp

And that’s it; the plugin is in place, and you’re one big step closer to being done.

Step II. Configure Access Policy (before or after linking)

Here’s a step you might skip, and later regret skipping. Before or after you link your account, decide who is actually allowed to message your OpenClaw bot. This is called your “access policy.” These are rules for who can knock on the door and who gets let in.

Here’s an example of what that setup looks like:

{channels: {whatsapp: {

  dmPolicy: "pairing",

  allowFrom: ["+15551234567"],

  groupPolicy: "allowlist",

  groupAllowFrom: ["+15551234567"],

}}}

Don’t worry, this isn’t as scary as it looks. Let’s break down dmPolicy, which controls direct messages:

• pairing (this is the default): if someone new messages your bot, they have to ask for permission first, and you (the owner) approve them.
• allowlist: only the phone numbers you’ve listed in allowFrom are allowed to chat with your bot. Everyone else is ignored.
• open: anyone can message your bot, but only if you’ve set allowFrom to include “*”, which means “everyone.”
• disabled: nobody can send direct messages to your bot at all.

Choosing the right setting here matters a lot, especially if you plan to connect OpenClaw to WhatsApp using your personal number. You don’t want random strangers chatting with your AI assistant!

Step III. Link WhatsApp via QR

This is the moment where the magic happens. Here’s where you truly connect OpenClaw to WhatsApp for real. Open your terminal and type:

openclaw channels login --channel whatsapp

This pops up a QR code, kind of like the ones you scan at a restaurant to see the menu. Open WhatsApp on your phone, go to Linked Devices, and scan that code. Once it scans successfully, your phone and OpenClaw are officially linked.

A quick heads-up: this login step only works with a QR code, no typing a username or password. If you’re setting this up on a remote or “headless” machine you can’t see in person, make sure you have a solid way to actually see and scan that QR code before you start, since codes shown in a terminal, a screenshot, or a chat message can expire quickly.

If you have more than one WhatsApp account you want to use, you can name it, like this:

openclaw channels login --channel whatsapp --account work

And if you want to attach an existing or custom folder for your login information before you link, you can run:

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth

openclaw channels login --channel whatsapp --account work

Once this step is done, you’ve technically managed to connect OpenClaw to WhatsApp. But wait a minute, there’s still a bit more to do before everything runs smoothly.

Step IV. Start the Gateway

Now that your phone and OpenClaw know about each other, you need to start what’s called the “gateway.” Think of it like the front desk of a hotel. Always awake, always watching, and making sure messages get delivered back and forth correctly.

To start it, type:

openclaw gateway

This single command keeps things alive and manages reconnecting automatically if something goes wrong, like your internet dropping for a second. Without the gateway running, your messages won’t go anywhere, even if you already successfully connected OpenClaw to WhatsApp in the earlier steps.

Step V. Approve the First Pairing Request (if using pairing mode)

Remember the “pairing” option from Step II? If you chose it (or left it as the default), then whenever someone new tries to connect OpenClaw to WhatsApp and message your bot, they need your approval before the conversation can begin.

To see who’s waiting for approval, type:

openclaw pairing list whatsapp

Then, to approve a specific person, type:

openclaw pairing approve whatsapp <CODE>

Just swap for the actual code shown to you. Remember: pairing requests don’t last forever. They expire after one hour, and you can only have up to three pending at once per account, so don’t leave someone hanging too long!

Step VI. Choose a Deployment Pattern

At this point, you’ve basically finished the technical part of the setup. But now it’s time to think about how you want to use it going forward. There are two common patterns.

a) Dedicated number (recommended)

Use a completely separate WhatsApp identity just for OpenClaw, instead of your own personal number. Your DM allowlists and routing rules stay much cleaner, and you avoid any confusing mix-ups where OpenClaw might get confused chatting with your own number.

b) Personal-number fallback.

If you’d rather not juggle two numbers, OpenClaw fully supports your own personal number. During onboarding, it automatically sets up a “self-chat-friendly” baseline, using settings like dmPolicy: “allowlist”, adding your number to allowFrom, and turning on selfChatMode: true, so messages from you, to you, are treated as expected and normal, not spam.

Either way works fine. It depends on how tidy you want your setup to be.

Step VII. Runtime Behavior Worth Knowing

Once you’ve fully managed to connect OpenClaw to WhatsApp, it helps to understand a few background behaviors so nothing catches you off guard later.

• Outbound sends need an active listener. If the gateway isn’t actively running and connected, OpenClaw can’t send messages out; it fails quickly instead of getting stuck.
• Status and broadcast chats are ignored. OpenClaw won’t try to respond to WhatsApp “Status” updates or “Broadcast” messages.
• The watchdog is smart, not jumpy. A background “watchdog” keeps an eye on the connection but won’t restart everything just because things went quiet. It only reconnects when there’s real evidence the connection broke. The watchdog tracks two signals independently, raw WhatsApp Web transport activityandapplication-message activity, and forces reconnect when transport frames stop arriving OR when application messages stay silent past 4x the normal message timeout.
• Proxy settings are respected. If your computer uses a proxy (a middleman for internet traffic), OpenClaw’s connection follows the same proxy environment variables your system already uses, like HTTPS_PROXY, HTTP_PROXY, and NO_PROXY.

Optional OpenClaw to WhatsApp Features

Now that the core setup is finished, here are some extra features you can turn on if you want to get more out of your bot.

a) Group chats. 

To let OpenClaw respond inside WhatsApp groups, not just private messages, set a group allowlist (channels.whatsapp.groups) plus a sender policy (groupPolicy and groupAllowFrom). By default, someone has to actually mention your bot by name before it replies; it won’t jump into every conversation uninvited.

b) Voice calls (experimental). 

Powered by a tool called MeowCaller, turned off by default. You enable it with actions.calls: true, and it needs its own separate “linked device” pairing. It can’t reuse the same login info as your regular connection.

c) Reactions and approvals. 

OpenClaw can use WhatsApp reactions, like 👍 or 👎, to represent approval prompts, plus customizable “ack” and status reactions so you can see at a glance what’s happening.

d) Media handling. 

Your bot isn’t limited to text. It can send and receive images, videos, voice notes, and documents, with a default size limit of 50MB per file (channels.whatsapp.mediaMaxMb).

OpenClaw to WhatsApp Troubleshooting Quick Reference

Even with the best instructions, sometimes things don’t go perfectly on the first try. Here’s a simple table to help you troubleshoot common hiccups when you connect OpenClaw to WhatsApp.

Symptom	Fix
Not linked	Run openclaw channels login –channel whatsapp, then check with openclaw channels status
Reconnect loop / 408 timeouts	Adjust web.whatsapp.keepAliveIntervalMs and connectTimeoutMs; also try running openclaw doctor
QR login times out behind a proxy	Double-check that your gateway is correctly using your proxy environment variables, and make sure NO_PROXY isn’t accidentally blocking mmg.whatsapp.net.
No active listener when sending	Make sure the gateway is actually running, and that your account is properly linked
Group messages ignored	Go through this checklist in order: groupPolicy, groupAllowFrom or allowFrom, the groups allowlist, and mention gating rules

One more small but important note: the WhatsApp gateway is designed to run on Node, not Bun, which is currently flagged as unreliable for stable WhatsApp or Telegram operation. Stick with Node to avoid headaches.

Connect OpenClaw to WhatsApp in a Minute

Now, do you see just how simple it is to connect OpenClaw to WhatsApp once you understand each piece?

To connect OpenClaw to WhatsApp in a nutshell:

• You install the WhatsApp plugin (often automatically)
• Set your access policy so you control who can message your bot
• Run the login command to scan a QR code with your phone
• Start the gateway so everything stays connected
• Approve your first pairing request if needed
• Pick whether you want a dedicated number or your personal number

If reading all of this got you excited, but the idea of managing your own server, gateway uptime, and background processes feels like a bit much, you don’t have to do it all alone. Truehost offers OpenClaw hosting built specifically for this kind of setup, with reliable uptime and everything you need already taken care of for you. OpenClaw hosting plans start as low as $14.08. It’s a simple way to enjoy the benefits without worrying about the technical upkeep yourself.