Connecting OpenClaw to WhatsApp: how it works and what to expect
OpenClaw joins WhatsApp the way WhatsApp Web does — a QR link, no Business API. Setup steps, the second-number question, and the gotchas.
OpenClaw connects to WhatsApp the way WhatsApp Web does: your agent links to a WhatsApp account by scanning a QR code — no Business API, no Twilio, no Meta approval process. Setup is a few CLI commands plus the scan; the real decisions are which phone number the agent uses and knowing the quirks of a linked-session channel before they surprise you.
How it works (and why that matters)
The official WhatsApp channel rides the same mechanism as WhatsApp Web (via the Baileys library, in production status): your agent becomes a linked device on a real WhatsApp account. That design has consequences in both directions. Good: it’s free, immediate, works with a normal account, and needs no business verification. Trade-off: the Gateway owns a live linked session — so the session credentials it stores are sensitive, and if WhatsApp unlinks the device (as it can), you re-scan to relink.
Setup: four commands and a scan
openclaw channels add --channel whatsapp
openclaw channels login --channel whatsapp
openclaw gateway
openclaw pairing approve whatsapp <CODE>The login step renders a QR code; you scan it from WhatsApp on the phone that owns the account (Settings → Linked Devices). Login is QR-only, and the docs carry an honest warning for remote setups: QR codes rendered in terminals or passed around as screenshots can expire in transit — have the phone ready and scan promptly. The linked-session credentials land under ~/.openclaw/credentials/whatsapp/ — part of the state directory you protect and back up. As on every channel, unknown senders hit the pairing gate (codes expire after an hour, pending requests cap at three) — approve yourself and you’re talking.
The phone-number question
The docs’ position matches operating experience: a separate number for the agent is recommended, not required. Linking your personal account works — your agent can even live in your self-chat — but a dedicated number (a cheap eSIM or prepaid SIM) keeps identities clean: the agent’s presence, contacts, and any experiments stay separate from your own account, and nothing you do with your personal WhatsApp can tangle the agent’s session. If the agent will message anyone besides you, the separate number stops being optional in spirit.
Quirks to know before they find you
- Sends need the session live — if the linked session is down, outbound messages fail fast rather than queue. An always-on, stable home for the Gateway matters more on WhatsApp than on Telegram, where the bot model is more forgiving.
- Media caps at 50 MB by default (configurable via
mediaMaxMb). - No inbound exposure here either — like the rest of OpenClaw’s channels, the WhatsApp link is an outbound connection from the Gateway. Connecting WhatsApp never requires a public port.
Bottom line: choose Telegram for the frictionless first channel; choose WhatsApp when that’s genuinely where you live — with a dedicated number, a machine that stays up, and the re-scan ritual filed under “normal maintenance,” it’s a solid daily driver. (On Everpod pods it’s the same official channel and the same QR scan — you bring the number; the staying-up part is our job.)