Guides/For developers

I run OpenClaw and want WhatsApp done properly, not a QR session that keeps dropping

Two routes: OpenClaw built-in QR scan (quick, fragile) or an official number through WACO (stable, blast allowed). 3 min read

OpenClaw can reach WhatsApp two ways, and the consequences differ sharply. Most people pick the first because it takes five minutes, then are surprised when the number drops or gets blocked.

Route 1: the built-in plugin, QR scan

The @openclaw/whatsapp plugin goes through WhatsApp Web: you scan a QR with your phone and that session is what the agent uses.

Install the plugin first. Without it the login command does not appear.
Start the login and the QR appears. Scan it from WhatsApp on your phone → Linked devices → Link a device.
Keep the phone online while scanning and for a few minutes afterwards. A new session only counts once the first sync finishes.
A QR lives about half a minute. If it expires, request a new one rather than scanning an old screenshot.

What you accept: a personal or ordinary WhatsApp Business number, sessions that drop when the phone is off too long or too many devices are linked, no blast, no templates, and the blocking risk is yours because this route is not official.

Do not put your main business number on the QR route. One block takes the whole customer history on that number with it, and Meta does not handle appeals for unofficial use.

Route 2: an official number through WACO

Here the OpenClaw WhatsApp plugin is not used at all. No QR, no session to drop. OpenClaw simply talks to WACO over HTTP: incoming messages arrive at your bridge as message.received, the bridge calls OpenClaw and posts the answer to POST /api/v1/balas. The pattern and sample code are in Bring your own AI.

One OpenClaw specific warning

A single OpenClaw call is heavy, hundreds of megabytes per invocation. Calling it once per incoming message will take a small VM down at busy hours, and a busy customer can send thousands of messages a day.

Queue, do not fan out. One queue per customer number, with a global cap on concurrent calls.
Single flight. While a call is running for that number, the next message waits for the result instead of starting a second call.
No fast polling. Use the webhook rather than asking for status every few seconds.

Which to choose

For experiments, a personal assistant or an internal group, the QR route is fine. For a number that serves customers, appears in ads, or needs blast and templates, use the official route through WACO. The difference is not about AI features; it is about whether that number can be trusted with the business.

← PreviousI already have my own AI, I just need the WhatsApp side

Still stuck after following this guide? Contact us from the dashboard — attach a screenshot if you have one, it speeds everything up.