Introduction

WhatsApp is where your actual conversations live, which is exactly why connecting OpenClaw to it feels different from every other integration: your agent stops being "an AI tool in a browser tab" and becomes a contact in your phone that you message like a person. WhatsApp is a first-class channel in OpenClaw — and with the 2.0 release smoothing onboarding, connecting it takes about ten minutes.

This guide covers account linking and sender access as separate steps. It follows the official WhatsApp documentation reviewed on October 2, 2026. If you haven't installed OpenClaw yet, start with the installation guide.

Before You Start

  • A supported OpenClaw installation, with its CLI available in your terminal
  • The phone with your WhatsApp account, unlocked — you'll scan a QR code
  • Five minutes of privacy thinking (Step 2 will explain why: the agent connects to your WhatsApp account as a linked device)

Choose which account to link. The official guide recommends a dedicated WhatsApp number; personal-number self-chat is also supported. A dedicated account helps you keep automated replies separate from personal conversations.

Step 1 — Add the WhatsApp Channel to Your Config

Merge the channel settings into ~/.openclaw/openclaw.json, preserving your other configuration. See the official configuration guide for editing options.

For personal-number self-chat, replace the example with your own international E.164 number, including + and the country code:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"],
      "selfChatMode": true,
      "groupPolicy": "disabled"
    }
  }
}

For a dedicated agent number, allowFrom should instead contain the trusted human's number. Omit selfChatMode and keep an explicit allowlist. If you want to approve additional senders individually, use dmPolicy: "pairing" and the separate approval flow in Step 3. Keep groups disabled until you deliberately configure group access.

OpenClaw connects as a linked device. Generate the login QR explicitly:

openclaw channels login --channel whatsapp

If the WhatsApp plugin is missing, this command offers to install it. To link:

  1. On your phone, open WhatsApp → Settings → Linked Devices → Link a Device
  2. Scan the live QR shown by the login command
  3. Wait for login confirmation

Then start the Gateway with your normal service manager, or run it in the foreground:

openclaw gateway

Use one Gateway process for the linked account. Check the connection:

openclaw channels status --probe

After linking, your phone's Linked Devices screen will show the session. Two practical notes:

  • Linked-device slots are limited. WhatsApp allows a handful of linked devices per account; if yours is full, log out an old WhatsApp Web session first
  • The QR is time-limited. Re-run openclaw channels login --channel whatsapp if it expires; restarting the Gateway is not the QR login procedure

Step 3 — Check Sender Access

With the personal-number configuration above, open your WhatsApp self-chat and send a message. Do not expect a pairing code for your own number. selfChatMode: true admits self-chat; setting it to false ignores self-originated DMs even if your number is allowlisted.

For a dedicated number using dmPolicy: "pairing", send a DM from the trusted person's account, then review and approve its request:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Check the sender identity before approval. DM pairing grants chat access; it is separate from the QR that links the WhatsApp account, and it does not grant group access. With dmPolicy: "allowlist", add intended senders to allowFrom instead of expecting unknown senders to receive pairing codes.

Step 4 — Test the Connection

Run through this checklist before you call it done:

  • Basic reply — a "hello" gets a model-generated answer
  • Context survives restart — restart the Gateway and confirm the conversation remembers earlier messages (since 2.0, sessions persist in SQLite, so history should survive cleanly)
  • Access check — use a second, unapproved number to confirm it cannot reach the agent; allowlist mode blocks it, while pairing mode requires approval
  • Task sanity — give it one real job you'd actually delegate (a summary, a lookup, a reminder) and confirm tools fire from the WhatsApp path

What Linking Actually Means for Your Account

This is the part most setup guides gloss over, and on WhatsApp it matters:

  • Replies come from your number. The agent isn't a separate WhatsApp bot account — it sends and receives through your linked session. People you message see your own contact card. That's powerful (your agent can message people as you) and consequential (mistakes are attributed to you), so be deliberate about what the agent is allowed to send.
  • Treat the linked account as sensitive access. Review which conversations and tools you expose. A dedicated account can reduce overlap with personal chats; it does not replace sender policies, tool restrictions, or careful handling of private data.
  • Logout is one tap. WhatsApp Settings → Linked Devices → select the session → Log out disconnects OpenClaw instantly. Worth knowing before you need it.

Securing a WhatsApp-Connected Agent

A WhatsApp-connected agent takes instructions from the app on your phone — which means anyone who can reach it can steer it. The standard hardening set, in priority order:

  1. Gateway stays local. Nothing about WhatsApp requires exposing your Gateway to the internet. If yours is exposed, close it first — see is OpenClaw safe?
  2. Sandbox tool execution. A prompt-injected message reaching unsandboxed shell is the nightmare scenario on any chat channel. Configure sandboxing per our Docker isolation guide
  3. Cap model spend. Unpaired strangers can't trigger your agent, but your own usage and any approved contacts' can — spending caps and alerts per the cost guide
  4. Think before allowing outbound sends. If your agent can message contacts on your behalf, require confirmation steps in how you prompt it, and review any skill that can send messages

Troubleshooting

QR code expires before I can scan. Re-run openclaw channels login --channel whatsapp, with WhatsApp's Linked Devices screen ready.

Linked, but the agent never replies. Check openclaw channels status --probe, openclaw doctor, and logs. Then inspect your DM policy, allowFrom, and selfChatMode; only pairing mode uses sender access requests. See the official WhatsApp troubleshooting steps.

The linked session was disconnected. Diagnose connectivity first. If the account is no longer linked, run the QR login command again. Re-linking the account and approving a human sender are separate operations; do not delete stored state as a first troubleshooting step.

Replies stopped after upgrading OpenClaw. Channel credentials normally carry over across 2.0, but messaging internals changed — check the Gateway logs for channel errors before re-linking from scratch.

Duplicate or echoed replies. Check for duplicate Gateway processes using the same linked account. Stop the unintended duplicate through its service manager, keeping one process for that account, then check logs again.

FAQ

Does connecting OpenClaw to WhatsApp cost anything? No — WhatsApp doesn't charge for linked-device usage, and OpenClaw's channel is part of the free software. Your only costs are model usage and optional hosting (see the cost breakdown).

Will my contacts know I'm using an AI? They'll see messages from your number as usual. OpenClaw doesn't label messages as automated — which is exactly why the outbound-send considerations above matter.

Can I use a second, dedicated WhatsApp number instead of my personal one? Yes. Link that account, then put your personal sender number in allowFrom, or approve its DM request in pairing mode. You will message the agent's dedicated number rather than use personal self-chat.

How is this different from the Telegram setup? Mechanically similar (channel config → pairing approval), but WhatsApp links through your existing account via QR while Telegram uses a purpose-created bot token. Telegram is the faster, more disposable option; WhatsApp is the one where your conversations already are. Full comparison in our Telegram guide.

Can the agent send voice notes or read images I send? OpenClaw's WhatsApp channel handles media messages, and model support for images/voice varies by provider and model choice. If media handling matters to you, test it explicitly after setup — capabilities here change with both OpenClaw releases and model updates.