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. If the account uses the pairing policy, approve your sender with the final command. The guided personal-number setup instead uses an allowlist; check which policy you selected before looking for a code.

Do you need a separate WhatsApp number?

No: OpenClaw supports your personal number. A separate account gives the agent a distinct identity and keeps its conversations apart from yours. It is useful if you want to text the agent as a contact, or let it message other people without speaking from your personal account. It is a choice about identity and access, not a requirement to connect.

Linking your personal account makes OpenClaw a linked device on that account. Messages the agent sends appear as yours. On OpenClaw 2026.9.2 (September 2026), replies in self-chat appear as outgoing messages on the phone too; there is no separate bot identity.

The current official WhatsApp setup offers a personal-number route that enables self-chat mode and restricts direct messages to your own number. For an existing manually configured account, check that channels.whatsapp.dmPolicy is allowlist and that allowFrom contains only the senders you intend.

That is different from leaving the policy unset. The runtime pairing default can send a pairing code to an unknown sender; on a personal account, that sender may be one of your contacts. Restricting replies does not turn the linked device into a separate account or remove its access to the account’s linked session.

If you choose a dedicated number, use a WhatsApp account you control and can keep access to for verification and relinking. You will message that account from your usual number, then approve or allow your usual number as the sender.

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: the WhatsApp link is an outbound connection from the Gateway. Connecting WhatsApp never requires a public port.
• QR linking can fail before the account connects. As of September 2026, scans started from the control panel or by the agent’s own tool can fail while the same account links from the CLI a day later on the same host and version. Whether the route or the wait made the difference is not established, and no wait time is known to always work. If you see “Connection failed” or “Can’t link new devices right now,” stop repeated scans and follow the WhatsApp linking-error guide.