OpenClaw WhatsApp setup

WhatsApp turns OpenClaw into an assistant you can message like any contact. Unlike Telegram there is no bot token: OpenClaw links to a WhatsApp account by QR code, the same way WhatsApp Web does. Strongly consider a dedicated number rather than your personal one; the agent will be reading and sending messages on whatever account you link. You need a working install first; see how to install OpenClaw.

1. Add the WhatsApp channel and link by QR

openclaw channels add --channel whatsapp
openclaw channels login --channel whatsapp

The login command shows a QR code; scan it from WhatsApp on the phone that owns the number (Settings, Linked Devices, Link a Device). For multiple accounts, append --account work.

QR login needs you to see the terminal. On a remote server, prefer a direct QR image handoff over screen-sharing workarounds; see our OpenClaw VPS guide.

2. Set the access policy

Pairing is the default and the right baseline: unknown senders get a time-limited code instead of direct agent access.

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

Phone numbers use full international format. dmPolicy accepts pairing, allowlist, open, and disabled; never run open on an agent that can execute commands.

3. Start the gateway and approve yourself

openclaw gateway
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Pairing requests expire after one hour, and a channel holds at most three pending requests at a time.

Groups

groupPolicy: "allowlist" plus groupAllowFrom controls who can invoke the agent inside groups. Requiring a mention keeps the bot from reacting to every message; combine both for anything with people you do not fully trust.

Where credentials live

The WhatsApp session is stored at ~/.openclaw/credentials/whatsapp/<accountId>/creds.json (with a .bak backup next to it). Treat that folder like a password: it IS your linked WhatsApp session. Our safe-setup checklist covers file permissions.

Useful behavior knobs

• textChunkLimit (default 4000) and chunkMode control how long replies split.
• mediaMaxMb (default 50) caps inbound media size.
• reactionLevel ("off", "ack", "minimal", "extensive") sets how chatty the bot is with emoji reactions.
• sendReadReceipts is on by default; turn it off if you do not want the agent marking your chats read.

Troubleshooting

| Problem | Fix | | --- | --- | | "Not linked" errors | openclaw channels login --channel whatsapp, then openclaw channels status | | Reconnect loops | Tune the socket timings under web.whatsapp.* (keepAliveIntervalMs, connectTimeoutMs) | | Group messages ignored | Check groupPolicy, groupAllowFrom, the group allowlist, and mention settings | | Linking keeps breaking | Back up the credentials folder, openclaw channels logout --channel whatsapp --account <id>, then re-link |

WhatsApp is the highest-traffic channel most people connect, which also makes it the biggest token spender: every message routes through your model. See what OpenClaw costs to run and pick a cheap default from best models for OpenClaw.

Source: OpenClaw WhatsApp channel docs, checked June 2026.