💬 WhatsApp Setup

Link OpenClaw to WhatsApp Web with QR pairing — and understand the trade-offs before you do.

WhatsApp is one of the more powerful OpenClaw channels — chat with your agent from the app you already have open all day — but it is also the channel with the most caveats. There is no official WhatsApp bot API here. OpenClaw connects through WhatsApp Web using the Baileys library, the same unofficial protocol your browser uses when you link a device. That makes setup a QR scan rather than a token paste, and it changes the risk profile. This page walks through linking, locking it down, group behaviour, and the honest limitations. New to OpenClaw? Start with the Quick Start first, then come back.

🔌

Install on demand

WhatsApp ships as a separate plugin (@openclaw/whatsapp), not in the core package. OpenClaw offers to install it the first time you add the channel.

📷

QR pairing

You link the same way as WhatsApp Web on a desktop: scan a QR code from your phone. There is no bot token.

⚠️

Unofficial protocol

Baileys is reverse-engineered WhatsApp Web. It works well, but it is rate-limited and not a sanctioned API — use a number you can afford to risk.

⚠️ Use a separate number

OpenClaw recommends running WhatsApp on a dedicated number where possible. The setup flow is optimised for it, allowlists stay clean, and you avoid self-chat confusion. Personal-number setups are supported, but a spare SIM or eSIM keeps your main account out of the blast radius. Read the security guide before going live.

Link WhatsApp step by step

Install the plugin, configure who can reach the agent, scan the QR, and approve the first pairing.

1

Add the channel (installs the plugin)

The WhatsApp runtime lives outside the core npm package. Onboarding and the channels add command prompt to install it the first time you pick WhatsApp.

openclaw channels add --channel whatsapp

Prefer to install it yourself? Run openclaw plugins install clawhub:@openclaw/whatsapp from ClawHub, with npm as the fallback.

2

Set the access policy first

Decide who can talk to the agent before you link. Edit ~/.openclaw/openclaw.json (JSON5). The default DM policy is pairing; an allowlist of E.164 numbers is the tightest sensible default.

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

DM policy options: pairing (default), allowlist, open (requires allowFrom: ["*"]), or disabled.

3

Scan the QR code

This is the actual linking step. Run the login command, then open WhatsApp on your phone → Linked devices → Link a device and scan the QR that appears.

openclaw channels login --channel whatsapp

For a named account use --account work. On a remote or headless host, make sure you have a reliable way to deliver the live QR to the scanning phone — terminal QRs can expire mid-relay.

4

Start the gateway

The gateway owns the WhatsApp socket and the reconnect loop. Outbound sends fail fast if no listener is running for the account.

openclaw gateway

Run WhatsApp on Node, not Bun — Bun is flagged as incompatible for stable WhatsApp gateway operation.

5

Approve the first pairing (pairing mode)

If you left dmPolicy on the default pairing, an unknown sender's first message creates a pairing request you approve from the CLI.

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Pairing requests expire after 1 hour, and pending requests are capped at 3 per channel.

Allowlists, groups, and media

How access control, group activation, and attachments actually behave on WhatsApp.

🔐

Two-layer group safety

Group access has two gates. The groups map is a membership allowlist (omit it and all groups are eligible; add "*" to admit all). Then groupPolicy plus groupAllowFrom decides which senders are authorised. A reply to an allowlisted user does not authorise an unlisted sender.

📢

Mention to activate

In groups the agent only replies when mentioned by default — it will not answer every message. Owners can switch a session with /activation always or back to /activation mention. That updates session state, not global config.

🖼️

Real media support

Inbound and outbound image, video, audio, and document payloads all work. Voice notes are sent as true push-to-talk audio. Default size cap is 50 MB via mediaMaxMb; oversized images are auto-optimised to fit.

💡
Inbound media shows up as placeholders

Media-only messages are normalised to tokens like <media:image>, <media:audio>, or <media:document>, and the file is saved to the inbound media store so the agent can actually inspect it. Authorised group voice notes are transcribed before mention gating, so saying the bot's name in a voice note can trigger a reply.

The honest caveats

WhatsApp works, but it carries trade-offs the official channels do not. Know these before you rely on it.

!

It is an unofficial protocol

Baileys speaks WhatsApp Web, not a sanctioned bot API. WhatsApp can change behaviour or rate-limit linked-device traffic at any time. Sending fast or to many recipients is the surest way to draw attention — keep volume human-paced.

!

It stores more state on disk

Unlike a stateless bot token, the linked session keeps Baileys auth material on the gateway host at ~/.openclaw/credentials/whatsapp/<accountId>/creds.json (plus a .bak). Anyone with that directory can impersonate your linked device — protect the host accordingly and back the directory up before re-linking.

!

Reconnect loops happen

Linked sessions can drop and the watchdog reconnects automatically. If you see repeated status=408 timeouts, check connectivity and tune the Baileys socket timings under web.whatsapp. Diagnose with the commands below, and re-link as a last resort.

openclaw channels status --probe
openclaw doctor
openclaw logs --follow

Logging out is clean: openclaw channels logout --channel whatsapp stops the live listener and clears auth state for that account.

🧭
Prefer a sanctioned channel for production?

If you need official APIs and predictable rate limits, Telegram, Discord, and Slack are first-class OpenClaw channels with token-based auth and no reverse-engineered protocol. See the full Channels guide to compare them. WhatsApp is great for personal use; weigh the risk for anything mission-critical.