Channels
How to Connect OpenClaw to WhatsApp
Browse more in Channels.
All channels guides →This guide shows you how to connect OpenClaw to WhatsApp using the production-ready WhatsApp Web channel. You configure access policies, link a WhatsApp account via QR, and run the OpenClaw gateway so your agents can send and receive WhatsApp messages.
By the end, you have a live WhatsApp integration with pairing and group behavior under your control.
Prerequisites
- ✓An existing OpenClaw installation with the CLI available so you can run `openclaw` commands.
- ✓A WhatsApp account you can link via WhatsApp Web (a dedicated number is recommended, but a personal number also works).
- ✓Access to edit your OpenClaw gateway configuration file where the `channels.whatsapp` block is defined.
- ✓A runtime using Node for the WhatsApp gateway (Bun is flagged as incompatible for stable WhatsApp gateway operation).
Steps
- 1
Install the WhatsApp channel plugin
Install the WhatsApp plugin so the gateway can speak the WhatsApp Web protocol via Baileys. Onboarding and channel commands can install it on demand, but running the explicit plugin install keeps the setup predictable, especially in scripted environments.
bashopenclaw plugins install @openclaw/whatsapp - 2
Configure WhatsApp access policy
Define who can DM and which groups your WhatsApp agent responds to before you expose the number. Start with a tight allowlist so you do not accidentally open the bot to every contact or group on that account.
json{ channels: { whatsapp: { dmPolicy: "pairing", allowFrom: ["+15551234567"], groupPolicy: "allowlist", groupAllowFrom: ["+15551234567"], }, }, } - 3
Link your WhatsApp account with QR
Link the WhatsApp account that OpenClaw will control using the WhatsApp Web QR flow. You can link the default account or specify a named account id if you plan to run multiple WhatsApp identities.
bashopenclaw channels login --channel whatsapp - 4
Link a specific WhatsApp account id
When you run multiple WhatsApp accounts, log in with an explicit account id so credentials land in the right directory and routing stays predictable. This also makes it easier to manage separate work and personal numbers.
bashopenclaw channels login --channel whatsapp --account work - 5
Start the OpenClaw gateway with WhatsApp listener
Run the gateway so it owns the WhatsApp socket and reconnect loop for your linked account. Outbound sends require this listener to be active, so keep this process running in your normal service manager.
bashopenclaw gateway - 6
Approve initial pairing requests from new contacts
With `dmPolicy: "pairing"`, unknown senders must be approved before the agent responds. List pending pairings and approve the codes you recognize so you keep tight control over who can talk to your WhatsApp agent.
bashopenclaw pairing list whatsapp openclaw pairing approve whatsapp <CODE>
Configuration
| Option | Description | Example |
|---|---|---|
| channels.whatsapp.dmPolicy | Controls direct chat access for WhatsApp DMs, including pairing, allowlist, open, or disabled modes. | pairing |
| allowFrom | Defines the E.164-style numbers allowed to DM the WhatsApp agent or used as a fallback for group sender allowlists. | +15551234567 |
| channels.whatsapp.groupPolicy | Controls how group messages are accepted, using open, allowlist, or disabled behavior for group senders. | allowlist |
| groupAllowFrom | Sender allowlist for group messages; when unset, runtime falls back to the `allowFrom` list. | +15551234567 |
| channels.whatsapp.historyLimit | Sets how many pending group messages can be injected as context when the bot is triggered. | 50 |
| channels.whatsapp.sendReadReceipts | Enables or disables read receipts for accepted inbound WhatsApp messages. | false |
| channels.whatsapp.textChunkLimit | Defines the maximum size of each outbound WhatsApp text chunk. | 4000 |
| channels.whatsapp.chunkMode | Controls whether outbound text is chunked by length or by newline-aware splitting. | newline |
| channels.whatsapp.mediaMaxMb | Sets the maximum size in megabytes for inbound media saves and outbound media sends. | 50 |
| channels.whatsapp.reactionLevel | Controls how broadly the agent uses emoji reactions on WhatsApp, including ack-only or more extensive reactions. | ack |
| channels.whatsapp.ackReaction | Configures the emoji and scope for immediate acknowledgment reactions on inbound messages. | { channels: { whatsapp: { ackReaction: { emoji: "👀", direct: true, group: "mentions", }, }, }, } |
| channels.whatsapp.accounts.<id>.mediaMaxMb | Overrides the media size limit for a specific WhatsApp account. | 100 |
| channels.whatsapp.accounts.<id>.reactionLevel | Overrides the reaction behavior for a specific WhatsApp account. | minimal |
| channels.whatsapp.accounts.<id>.enabled | Controls whether a specific WhatsApp account is active in the gateway. | true |
| channels.whatsapp.accounts.<id>.authDir | Sets a custom directory for WhatsApp account credentials instead of the default path. | ~/.openclaw/credentials/whatsapp/work |
| channels.whatsapp.configWrites | Enables or disables channel-initiated config writes from WhatsApp interactions. | false |
| channels.whatsapp.web.enabled | Controls whether the WhatsApp Web transport is enabled for the gateway. | true |
| channels.whatsapp.web.heartbeatSeconds | Sets the heartbeat interval for the WhatsApp Web connection. | 30 |
| channels.whatsapp.web.reconnect.* | Controls reconnect behavior for the WhatsApp Web transport. | channels.whatsapp.web.reconnect.maxDelayMs |
| session.dmScope | Defines how direct chat sessions are scoped; the default `main` collapses DMs to the agent main session. | main |
| channels.whatsapp.historyLimit | Sets the limit for pending group history injection for WhatsApp groups. | 50 |
| messages.groupChat.historyLimit | Fallback configuration for group chat history injection when the WhatsApp-specific limit is not set. | 50 |
| channels.whatsapp.actions.reactions | Gates whether agent tools can send WhatsApp reaction actions. | true |
| channels.whatsapp.actions.polls | Gates whether agent tools can send WhatsApp polls. | true |
Troubleshooting
Symptom: channel status reports not linked.
The WhatsApp account is not linked yet, so the gateway cannot open a Web socket or send messages. Log in again with the WhatsApp channel login flow, then confirm the link status.
openclaw channels login --channel whatsapp
openclaw channels statusSymptom: linked account with repeated disconnects or reconnect attempts.
The WhatsApp Web connection is unstable or the runtime environment is misconfigured. Run the doctor command and follow logs to see why Baileys keeps reconnecting, then re-link the account if needed.
openclaw doctor
openclaw logs --followOutbound sends fail fast when no active gateway listener exists for the target account.
The gateway process that owns the WhatsApp socket is not running, so OpenClaw cannot deliver messages. Start or restart `openclaw gateway` and make sure the account is linked before sending again.
Group messages unexpectedly ignored.
Group access is gated by multiple layers, so a mismatch in policy or allowlists can silently drop messages. json` where later entries override earlier ones.
Bun runtime warning for WhatsApp gateway.
The WhatsApp gateway runtime should use Node, and Bun is flagged as incompatible for stable WhatsApp/Telegram gateway operation. Switch the gateway process to run under Node instead of Bun to avoid subtle disconnects and runtime issues.
Frequently asked questions
Powered by Mem0
Add persistent memory to OpenClaw
Official Mem0 plugin for OpenClaw keeps context across chats and tools. Smaller prompts, lower cost, better continuity for your agents.