Connecting OpenClaw to WhatsApp: how it works and what to expect

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 a 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

A separate number for the agent is the clean way, and almost nobody has one lying around: a prepaid SIM or an eSIM for a few pounds a month is what it takes. Linking your personal account works too, and it is worth knowing exactly what that means before you scan, because three things follow that the setup never mentions.

• The agent speaks as you. The Gateway is a linked device on your account, so everything it sends is sent by you: in your self-chat its replies appear as your own outgoing messages, on every device where you read that chat, and nothing marks them apart from things you wrote (seen 2026-09-11 on 2026.9.2).
• Everyone who messages you gets a pairing code, by default. The default DM policy on every channel is pairing: a message from a number the agent does not know earns the sender a short code, sent from your account, and their message is not read until you approve it — about once an hour per sender while the request is open, three pending at most. On a bot number that is the right gate. On your personal number the unknown senders are your contacts. Tell the agent to reply only to you (or set channels.whatsapp.dmPolicy to allowlist with your own number in allowFrom) before anyone else finds out.
• Everything on your number passes through the linked session, whether or not the agent acts on it — the same as WhatsApp Web on a laptop.

If the agent will ever message anyone besides you, or you would rather not think about any of this, the separate number stops being optional.

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.
• Linking can fail on current releases, and it comes and goes (seen 2026-09-10 on 2026.9.2): the phone reports “Connection failed. Try again.” seconds after the scan, the Gateway logs a connection timeout before login, and no credentials are written; a few more scans and WhatsApp answers “Can’t link new devices right now. Try again later.” — an account cooldown that cleared overnight. The next day the same account linked first time on the same Gateway, from a terminal with openclaw channels login --channel whatsapp, where the failed scans had gone through the Control UI’s QR and the agent’s own login tool. The WhatsApp Web library OpenClaw bundles is missing a handler for a registration-refresh message WhatsApp began sending after a scan in late July 2026 (the library’s issue #2737; a fix is proposed and unmerged), which fits a failure that comes and goes. If it hits yours, do not keep scanning — that only earns the cooldown. Try again the next day, from the CLI.

Bottom line: choose Telegram for the frictionless first channel; choose WhatsApp when that’s 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 an Everpod pod it’s the same official channel and the same QR scan: you bring the number; the staying-up part is our job.)