OpenClawWiki
tutorials

OpenClaw WhatsApp Guide: Connect Your Agent to WhatsApp

Connect OpenClaw to WhatsApp step by step: link your phone via QR code, approve device pairing, and protect your personal number. Full 2026 setup guide.

OpenClaw Team•
whatsappchannelsmessagingsetuptutorial

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 walks through the full setup: adding the channel, linking your phone, approving pairing so only you can talk to your agent, and the WhatsApp-specific considerations most guides skip — what linking means for your personal number, and how to keep a WhatsApp-connected agent safe. If you haven't installed OpenClaw yet, start with the installation guide and come back.

Before You Start

  • OpenClaw installed and running (any 2.x version; the Gateway reachable from 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)

One decision worth making up front: WhatsApp connects OpenClaw to your personal number. Most operators start that way and it works fine; a subset later moves the agent to a dedicated number (a spare SIM or a second WhatsApp account) to keep automated replies off their personal identity. Nothing in this guide requires that — but knowing the option exists makes Step 1's choices easier.

Step 1 — Add the WhatsApp Channel to Your Config

OpenClaw's channel integrations live in your main configuration file — the same file that holds your model settings and Gateway options (see the configuration guide for the full layout and where the file lives on each platform).

Add a WhatsApp section to the channels block. The exact keys are documented in the official docs' channel pages (docs.openclaw.ai) and change rarely, but the shape is:

{
  "channels": {
    "whatsapp": {
      "enabled": true
    }
  }
}

Note what's absent: unlike Telegram, there's no bot token to paste. WhatsApp connects through account linking (next step), which is why the config entry is minimal. Restart the gateway so the new channel is picked up, then watch the logs — the linking step in 2.x prints what you need at startup.

Step 2 — Link Your Phone (the QR Code)

OpenClaw connects to WhatsApp the same way WhatsApp Web and WhatsApp Desktop do: as a linked device. When the Gateway starts with the WhatsApp channel enabled, it generates a QR code (current versions show it in the terminal, and the 2.0 browser app renders it on screen). To link:

  1. On your phone, open WhatsApp → Settings → Linked Devices → Link a Device
  2. Scan the QR code shown by your Gateway
  3. Wait for the Gateway logs to confirm the session is connected

After linking, your phone's Linked Devices screen will show OpenClaw's session alongside any WhatsApp Web logins you already have. Two practical notes from community experience:

  • 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. If it expires before you scan, restart the Gateway to generate a fresh one — this is the single most common "linking failed" cause

Step 3 — Approve Pairing for Yourself

Here's the step that separates a useful agent from an open front door. OpenClaw treats every inbound message as untrusted input and pairs unknown senders by default — anyone who messages your number doesn't get an AI with tool access; they get a silent pairing request.

Message your own number from WhatsApp (the account you linked), then check the Gateway logs for a pairing code and approve it:

openclaw pairing approve whatsapp <code>

Your next message gets a real reply from the model. Everyone else stays unpaired until you explicitly approve them — including contacts who message you, which is exactly the behavior you want on a channel tied to your personal number. If your agent should serve family members or a small team, approve each of them deliberately rather than loosening the default.

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)
  • Unpaired stranger test — have someone else (or a second number) message the account; confirm they hit the pairing wall, not your agent
  • 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.
  • The agent can see your chats. A linked-device session gives OpenClaw access to your WhatsApp history and incoming messages — that's how it answers in context. If that's more access than you're comfortable with, the dedicated number route isolates it, and the wacli companion CLI (an official OpenClaw Labs tool for searching and sending WhatsApp messages from the terminal) is a lighter-weight alternative when you want control without a full agent.
  • 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. Regenerate by restarting the Gateway, and have WhatsApp's Linked Devices screen open before you start.

Linked, but the agent never replies. Almost always the pairing wall — check the logs for a pending pairing request and approve it (Step 3).

It worked, then stopped after a phone or WhatsApp update. Linked sessions occasionally get dropped by WhatsApp updates. Re-link from the Linked Devices screen and re-approve pairing; your session history lives on the Gateway side and is unaffected.

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. Two Gateway processes fighting over one WhatsApp session. Kill all instances, start one.

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, and it's a common upgrade path once an agent handles real volume: register WhatsApp on a spare SIM or secondary account and link that to OpenClaw. The setup steps are identical.

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.

Related Articles

OpenClaw Security & Deployment Brief

Get the weekly OpenClaw Security & Deployment Brief — malicious skill alerts, CVE breakdowns, cost optimization tips.

Related Articles