.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
WhatsApp is the fastest way to “feel” OpenClaw. You don’t need a new app. You don’t need to sit in a terminal. You just scan a QR code once then you chat with your agent from the same place you already message friends and coworkers.
This guide is the beginner path: scan QR, confirm it’s linked, start the gateway, send a first message. If you’re installing on a VPS and you want a safe baseline before you start linking channels, skim how to host OpenClaw securely on a VPS first.
What WhatsApp linking means for OpenClaw
OpenClaw uses WhatsApp’s “Linked devices” flow. It’s the same feature used by WhatsApp Web. You scan a QR code and WhatsApp links a companion device to your account. WhatsApp explains the steps in their help center. How to link a device
The difference is what the “device” is. In this case it’s your OpenClaw instance running on your laptop or VPS. Messages still go through WhatsApp like normal, but OpenClaw receives them and replies back.
Before you scan the QR code
Make one decision up front: which phone number will be the WhatsApp identity for OpenClaw.
Option A: A dedicated number
This is the calmer option. If something gets flagged or you want to reset later you don’t touch your personal WhatsApp identity. It also keeps your contact list and personal chats separate from whatever you test with OpenClaw.
Option B: Your personal number
It works and many people do it for testing. Still, WhatsApp is clear that automated or bulk messaging is not allowed under their terms and they enforce that when accounts behave like spam. WhatsApp on automated or bulk messaging
If your plan is “talk to myself and do personal automation” the risk is lower than running outreach or blasting groups. Just be honest with yourself about how you’ll use it.
Step 1: Make sure OpenClaw is running and reachable
If you installed OpenClaw over SSH on a VPS, you can keep everything local-only and use SSH port forwarding to reach the web UI. Our quickstart walks through that flow. OpenClaw quickstart onboarding over SSH
For WhatsApp linking you mainly need the server to be online and your gateway to be able to run. If you’re on a VPS, do the boring parts now:
- Firewall is on
- Gateway binds to 127.0.0.1 not 0.0.0.0
- You have gateway auth enabled
Step 2: Generate the WhatsApp QR code
On the machine where OpenClaw is installed run:
openclaw channels loginYou’ll see a QR code in the terminal. Scan it quickly. QR codes expire and if you stare at it for too long you’ll just end up rerunning the command.
Step 3: Scan the QR code in WhatsApp
On the phone that owns the WhatsApp account you chose:
- Open WhatsApp
- Go to Linked devices
- Tap Link a device
- Scan the QR code shown in your terminal
If scanning fails, it’s usually one of these:
- QR expired, rerun openclaw channels login
- Screen brightness too low
- Camera can’t focus, move closer then pull back slightly
Step 4: Confirm OpenClaw saved the session
After a successful scan OpenClaw should print something like “device linked” and “session saved”. From that point you don’t rescan every time you reboot. OpenClaw stores WhatsApp session credentials locally and reconnects when the gateway starts.
Under the hood OpenClaw uses Baileys to speak the WhatsApp Web protocol. If you’re curious or you want to verify you’re using the legit library, this is the upstream project. WhiskeySockets Baileys
Step 5: Enable the WhatsApp channel in your config
Edit your OpenClaw config and enable WhatsApp. Your file location can vary depending on how you installed. If you’re following the default setup, it’s typically under your OpenClaw workspace directory.
Here’s a minimal example. Keep the allowlist tight at first.
{
"channels": {
"whatsapp": {
"enabled": true,
"dmPolicy": "pairing",
"allowFrom": ["+15551234567"]
}
}
}dmPolicy: "pairing" means unknown numbers won’t get full access. They’ll have to pair first. That saves you from a lot of regret later.
Step 6: Start the gateway
Start the gateway in a terminal session:
openclaw gateway --port 18789 --verboseIf you run OpenClaw as a service, your command might be different. The important part is: the gateway is running and the WhatsApp channel reports as connected.
Step 7: Send your first message from WhatsApp
Open WhatsApp and message the number you linked. Send something boring like:
HelloYou want a simple “does it reply” test. If you want a slightly better test that proves tool execution works, try:
List files in my home directoryFor a deeper “first message” walkthrough across channels, there’s a separate guide here. Send your first message to OpenClaw
Troubleshooting that fixes most WhatsApp setups
QR code keeps expiring
Rerun the login command and scan immediately. If you’re doing this over SSH, consider running the command in a terminal that your phone can scan easily.
WhatsApp links but OpenClaw never replies
Confirm the gateway is running, then read logs. A dead-simple check is to restart the gateway and watch for “WhatsApp connected”. If the gateway is not running, WhatsApp can be linked and still nothing will respond.
WhatsApp says the device is linked but OpenClaw keeps asking to login
That usually means the saved credentials can’t be read due to permissions or you’re running OpenClaw under a different user than the one that did the login.
OpenClaw replies but pairing blocks me
This is expected if you left pairing on. Approve the pairing request or add your number to allowFrom. Don’t switch to “open” just to get past a small inconvenience.
A quick safety note about WhatsApp automation
WhatsApp takes action against automated or bulk messaging behavior. If you treat OpenClaw like a personal assistant and you keep usage human-looking, you’re far less likely to run into issues than someone doing mass messaging. That’s also why a dedicated number is a smart move.
