How to Set Up OpenClaw with WhatsApp

OpenClaw can connect to WhatsApp so your AI agent replies to messages, summarizes group chats, and handles tasks directly from the app you already use. WhatsApp doesn’t have an official bot API for personal accounts, so OpenClaw uses a linked web session instead — the same mechanism that powers WhatsApp Web on your laptop. You scan a QR code, the session links, and your agent starts listening. No third-party service sits between you and your messages. Everything runs on your machine.

This guide covers the full setup: pairing, config, group handling, media, and what to do when the session drops.

:::note[TL;DR]

OpenClaw connects to WhatsApp via a linked web session (QR code scan)
Messages stay local — nothing passes through external servers
Group chats can be filtered so the agent only responds where you want it
Media messages (images, voice notes, documents) are downloaded to your local workspace
Sessions drop occasionally; OpenClaw auto-reconnects, but you may need to re-scan if the phone is offline too long :::

Prerequisites

OpenClaw installed and running — if you haven’t set it up yet, start with the install guide
WhatsApp account on your phone (personal or business)
Phone and laptop on the same network during initial QR code pairing (after that, the session persists independently)

How does WhatsApp integration actually work?

WhatsApp doesn’t offer a public bot API the way Telegram or Discord does. You can’t just register a bot and get a token. Instead, OpenClaw uses the WhatsApp Web multi-device protocol. It registers itself as a linked device on your account — the same way you’d link a second laptop or tablet.

When someone sends you a message, your phone syncs it to all linked devices. OpenClaw picks it up, processes it through your agent, and sends a reply back through the same channel. From the other person’s perspective, it looks like you’re replying from your phone. They don’t see a bot or a different number.

The scenario: You’re on vacation and your family group chat is blowing up with logistics — who’s bringing what, what time is dinner, can someone pick up grandma. You’ve set OpenClaw to monitor that group. It summarizes every 20 messages into three bullet points and sends the summary to your “Saved Messages” chat. You check once an hour instead of scrolling through 150 messages.

The main downside: WhatsApp limits linked devices to four. If you already have a laptop, a tablet, and a desktop linked, adding OpenClaw means unlinking one of them.

Step 1: Enable WhatsApp in your config

Open your agent’s config.yaml (usually at ~/.openclaw/agents/<agent-name>/config.yaml) and add a WhatsApp entry to the messaging section:

messaging:
  - platform: whatsapp
    sessionName: "openclaw-main"
    allowedUsers: ["+1234567890"]
    allowedGroups: []
    mediaDownload: true
    mediaPath: "~/.openclaw/workspace/media"

Here’s what each field does:

sessionName — An identifier for this linked session. If you need to re-pair later, OpenClaw uses this to find the right session store.
allowedUsers — Phone numbers (with country code) that the agent will respond to. Leave this empty and it responds to everyone — don’t do that unless you want strangers burning through your API credits.
allowedGroups — Group chat names the agent monitors. An empty array means no groups. We’ll configure this in a later step.
mediaDownload — When true, images, voice notes, and documents sent to the agent are saved to disk.
mediaPath — Where downloaded media files land.

:::warning The allowedUsers field is not optional in practice. Without it, anyone who has your number — or anyone in a monitored group — can trigger the agent. Set it on day one. :::

Step 2: Pair with QR code

Start your agent:

openclaw tui

On first launch with WhatsApp enabled, a QR code appears in the terminal. Open WhatsApp on your phone, go to Settings → Linked Devices → Link a Device, and scan the code.

The pairing takes 5–15 seconds. Once connected, you’ll see a confirmation in the terminal:

[whatsapp] Session "openclaw-main" linked successfully
[whatsapp] Listening for messages...

From this point, the session persists across OpenClaw restarts. You don’t need to re-scan every time you reboot. The session data is stored locally in ~/.openclaw/sessions/whatsapp/.

The scenario: You’re setting this up on a headless server that doesn’t have a GUI. The QR code prints as ASCII art directly in the terminal. You scan it from your phone while SSHed in. It works fine — no desktop environment needed.

Step 3: Test with a direct message

Send a message to yourself (your own number) or to the agent’s “Saved Messages” chat. You should see it arrive in the OpenClaw terminal and get a reply within a few seconds.

If the agent doesn’t respond:

Check the terminal for errors — an auth failure means the session didn’t link properly
Verify the phone number in allowedUsers matches your actual number, including country code
Make sure your phone has an internet connection — WhatsApp Web sessions require the phone to be online (or at least have been online recently for multi-device mode)

How do I set up group chat monitoring?

Group chats are where WhatsApp integration gets genuinely useful. Instead of reading 200 messages in a family or team group, you let the agent summarize, track action items, or answer questions.

Add group names to the allowedGroups array in your config:

messaging:
  - platform: whatsapp
    sessionName: "openclaw-main"
    allowedUsers: ["+1234567890"]
    allowedGroups: ["Family Logistics", "Work Team Alpha"]
    groupBehavior: "mention-only"

The groupBehavior field controls when the agent responds:

Value	Behavior
`mention-only`	Only responds when someone mentions the agent by name in the group
`all`	Responds to every message (careful with this — it gets noisy fast)
`summary`	Silently watches and posts a summary at configurable intervals

For most setups, mention-only is the right default. It keeps the agent quiet unless someone specifically asks for help.

The scenario: Your work group chat is 40 people. Half of them post memes. You set groupBehavior to mention-only and tell your team to tag the agent when they need something looked up. The agent ignores the memes, answers the questions, and everyone’s happy.

:::tip Group names in WhatsApp are case-sensitive and can contain emoji. Copy the exact name from your phone — "Work Team 🚀" won’t match "Work Team". :::

How does media handling work?

When mediaDownload is true, the agent downloads images, voice notes, PDFs, and other files to the path you set in mediaPath. The agent can then reference them in context — describing an image, transcribing a voice note (if you have a transcription skill configured), or reading a PDF.

Files are saved with timestamps:

~/.openclaw/workspace/media/
  ├── 2026-04-07_14-23_image.jpg
  ├── 2026-04-07_14-25_voice.ogg
  └── 2026-04-07_15-01_document.pdf

Voice notes arrive as .ogg files. If your agent has a transcription tool (like Whisper via MCP), it can transcribe them automatically. Without a transcription tool, the agent acknowledges the voice note but can’t read its content.

:::warning Media files accumulate. If you’re in active groups, this folder grows fast. Set up a cleanup cron job or add a scheduled task to your agent to purge files older than 7 days. :::

What happens when the session drops?

Sessions disconnect for a few reasons: your phone goes offline for more than 14 days, you manually unlink the device from WhatsApp settings, or WhatsApp’s servers rotate keys (rare, but it happens).

OpenClaw handles reconnection automatically in most cases. If the session data is still valid, it re-establishes the connection without a QR scan. If the session is truly expired, you’ll see this in the logs:

[whatsapp] Session expired. QR code required for re-pairing.

At that point, restart the TUI and scan again.

To minimize disconnects:

Keep your phone connected to the internet at least once every few days
Don’t clear WhatsApp’s app data or cache while a session is active
If you’re running OpenClaw on a server, set up a health check that alerts you when the WhatsApp connection drops

Can I run multiple WhatsApp accounts?

Yes. Add multiple entries to the messaging array, each with a different sessionName:

messaging:
  - platform: whatsapp
    sessionName: "personal"
    allowedUsers: ["+1234567890"]
    allowedGroups: ["Family"]
  - platform: whatsapp
    sessionName: "work"
    allowedUsers: ["+0987654321"]
    allowedGroups: ["Team Alpha"]

Each session links to a different phone number and gets its own QR code during pairing. The agent routes messages based on which session received them.

Frequently asked questions

Does the other person know they’re talking to an AI?

No. Replies come from your number, using your profile picture and name. From their side, it looks like you’re typing. WhatsApp doesn’t expose linked device activity to the other party. Whether you should tell people is an ethics question, not a technical one.

Can I use WhatsApp Business instead of a personal account?

Yes. The linking process is identical — WhatsApp Business supports linked devices the same way. The main advantage is that Business accounts can have auto-greeting messages and labels, which play well with OpenClaw’s routing if you’re using it for customer-facing work.

Will this get my account banned?

WhatsApp’s terms of service don’t explicitly permit third-party automation on personal accounts. The risk is low for personal use at normal message volumes — OpenClaw mimics a standard linked device, not a mass-messaging bot. Don’t use it to send hundreds of unsolicited messages. If you need high-volume automation, use the official WhatsApp Business API (which requires a Meta-approved business account).

Can the agent send messages proactively, not just reply?

Yes. If you set up scheduled tasks in your agent config, it can send messages at specific times — a morning briefing, a reminder, a daily summary. The message goes through the linked session like any other reply. Configure this in the agent’s schedules section, not the WhatsApp config.

How much does WhatsApp integration add to API costs?

It depends entirely on message volume and response length. Each incoming message that triggers the agent counts as one API call to your configured LLM. A quiet personal chat might add $1–2/month. A busy group with groupBehavior: "all" can add significantly more. Use mention-only or summary mode to keep costs predictable.