How to Connect OpenClaw to WhatsApp: Complete Setup Guide

Channels & Integrations · 10 min read

How to Set Up OpenClaw on WhatsApp (Complete Guide)

Last updated: February 2026 · Reading time: 8 minutes · Difficulty: Beginner-friendly

WhatsApp is the most popular way to use OpenClaw. It makes sense — you already check WhatsApp dozens of times a day. Having an AI assistant sitting right there in your chat list, alongside your friends and family, means you'll actually use it.

But WhatsApp is also the trickiest channel to set up. Unlike Telegram (which uses a simple bot token), WhatsApp requires linking a device — the same process you'd use for WhatsApp Web. And there are some quirks around session management, group chats, and keeping the connection alive that are worth knowing upfront.

This guide covers the full setup from scratch, plus the things nobody tells you until something breaks.

Before You Start

You'll need three things ready:

OpenClaw installed and running. If you haven't done this yet, follow our setup guide first. This guide picks up where that one leaves off.

A WhatsApp account. Your personal one is fine — OpenClaw links as an additional device, just like WhatsApp Web. It doesn't take over your account or interfere with your normal conversations.

Your phone nearby. You'll need it to scan a QR code during the linking process. After that, your phone can go back in your pocket.

Step 1: Link WhatsApp to OpenClaw

Open your terminal (or SSH into your server if you're running OpenClaw remotely) and run:

openclaw channels login

A QR code appears in your terminal. It looks like a messy grid of characters — that's normal, it's a text-based QR code.

On your phone:

  1. Open WhatsApp
  2. Tap Settings (or the three dots on Android)
  3. Tap Linked Devices
  4. Tap Link a Device
  5. Point your camera at the QR code in your terminal

Within a few seconds, the terminal should confirm the connection. You'll also see your OpenClaw instance appear in WhatsApp's "Linked Devices" list on your phone.

Step 2: Set Up Your Allowlist

This step is critical. Without an allowlist, anyone who has your phone number could message your WhatsApp and get responses from your AI assistant — burning through your API credits and potentially accessing your tools.

Open your OpenClaw config file:

nano ~/.openclaw/openclaw.json

Add or update the WhatsApp section:

{
    "channels": {
        "whatsapp": {
            "allowFrom": ["+1234567890"]
        }
    }
}

Replace +1234567890 with your own phone number, in international format. You can add multiple numbers:

{
    "channels": {
        "whatsapp": {
            "allowFrom": ["+1234567890", "+0987654321"]
        }
    }
}

Only numbers on this list can talk to your assistant. Everyone else gets ignored.

Restart the gateway after changing the config:

openclaw restart

Step 3: Send Your First Message

Open WhatsApp on your phone. You won't see a new contact — your assistant responds through your own number, like a conversation with yourself.

Send a message:

Hey, are you there?

You should get a response within a few seconds. If you do, everything is working.

Try something more useful:

Remind me to take the laundry out in 45 minutes

Summarize the last 3 emails I received

What's the weather like tomorrow?

Setting Up Group Chats

OpenClaw can participate in WhatsApp group chats too. This is great for shared assistants — a family group where anyone can ask questions, or a work group where the assistant handles meeting notes.

By default, group access is disabled. To enable it, add a groups section to your config:

{
    "channels": {
        "whatsapp": {
            "allowFrom": ["+1234567890"],
            "groups": {
                "*": {
                    "requireMention": true
                }
            }
        }
    }
}

The "*" means all groups. The requireMention setting means the assistant only responds when someone @mentions it — it won't jump into every conversation unprompted.

If you want to restrict to specific groups instead of allowing all:

{
    "channels": {
        "whatsapp": {
            "groups": {
                "Group Name Here": {
                    "requireMention": true
                }
            }
        }
    }
}

A word of caution: be careful with group access. Every message from every member in the group gets processed (even if the assistant doesn't respond), which uses tokens and costs money. Keep groups small and purposeful.

Chat Commands

You can control your assistant directly from WhatsApp using slash commands. These work in any conversation:

Command What it does
/new or /reset Start a fresh conversation (clears context)
/compact Summarize and trim the conversation history (saves tokens)
/status Show current model, token usage, and session info
/think high Enable deep thinking mode for complex questions
/think off Disable thinking mode (faster, cheaper responses)
/verbose on Show detailed responses
/verbose off Keep responses concise
/usage full Show per-response cost breakdown

The most useful ones for daily use are /new (when switching topics) and /compact (when conversations get long and responses slow down).

Handling Media

OpenClaw can process images and audio files sent through WhatsApp.

Images: Send a photo and ask "what's in this image?" or "read the text in this picture." The assistant processes it through the AI model's vision capabilities. Useful for things like scanning receipts, reading signs, or getting information about products.

Voice messages: Send a voice note and the assistant transcribes it, then responds to the content. You can have entire conversations by voice note if you prefer talking over typing.

Documents: Send a PDF or other document and ask the assistant to summarize it, extract specific information, or answer questions about its content.

Videos: Short video clips can be processed, though this uses more tokens than images.

The main limitation is file size. WhatsApp compresses media aggressively, which is usually fine. Very large files may fail to process — if that happens, try a smaller or lower-resolution version.

Keeping the Connection Alive

This is the part that catches most people. WhatsApp's linked device connection can drop for several reasons, and when it does, your assistant goes silent until you re-link.

Why it disconnects:

  • Your phone was offline for more than 14 days (WhatsApp's limit for linked devices)
  • WhatsApp pushed an update that reset device links
  • Your server was offline for an extended period
  • Your phone's WhatsApp was reinstalled

How to tell if you're disconnected:

If your assistant stops responding, check the gateway logs:

openclaw doctor

The doctor command flags channel connection issues. If WhatsApp is disconnected, you'll see it clearly in the output.

How to reconnect:

Same process as the first time:

openclaw channels login

Scan the QR code again. Your config stays intact — you don't need to redo anything else.

How to prevent disconnections:

Keep your phone connected to the internet. WhatsApp requires the linked phone to come online periodically to maintain the device link. If you travel somewhere without connectivity for two weeks, expect to need to re-link when you get back.

If you're running on a cloud server, make sure the server stays up. A stable VPS from DigitalOcean or Hetzner essentially never goes down on its own, so the main risk is the phone-side timeout.

→ Best hosting for OpenClaw (always-on servers)

Privacy and Security Considerations

A few important things to understand about how OpenClaw handles WhatsApp.

OpenClaw uses the Baileys library to connect to WhatsApp. Baileys is an unofficial, open-source implementation of the WhatsApp Web protocol. It's widely used and well-maintained, but it's not endorsed by WhatsApp/Meta. In practice, this has worked fine for the vast OpenClaw community, but it's worth knowing.

Your messages pass through WhatsApp's servers (encrypted end-to-end) and then through your AI model provider (Anthropic or OpenAI). The message content is decrypted on your server, sent to the AI API, and the response comes back the same way. WhatsApp can't read the content, but your AI provider can — that's how the AI works.

Your WhatsApp session credentials are stored locally on your server in ~/.openclaw/credentials. Protect this directory. Anyone with access to these credentials could read your WhatsApp messages.

Don't run OpenClaw on a shared computer without understanding the implications. Your WhatsApp session, API keys, and conversation history are all accessible to anyone who can log into the machine.

Troubleshooting

QR code won't scan

Make sure your terminal window is large enough to display the full QR code. If characters are wrapping to the next line, the QR code becomes unreadable. Expand your terminal window and try again.

If you're SSH'd into a remote server and the QR code looks garbled, try using a terminal with better Unicode support, or copy the QR code text and paste it into a local terminal.

Assistant responds to wrong people

Your allowlist isn't configured correctly. Double-check that allowFrom in your config contains the right phone numbers in international format (with the + prefix and country code). Restart the gateway after any config changes.

Messages are delayed

If responses take longer than 5–10 seconds, the bottleneck is usually the AI model, not WhatsApp. Try these in order:

  1. Send /compact to trim conversation context
  2. Send /new to start a fresh session
  3. Switch to a faster model (Sonnet instead of Opus)
  4. Check your server resources with docker stats or htop

"Logged out" errors in the logs

WhatsApp unlinked your device. Run openclaw channels login and scan the QR code again. If this keeps happening frequently, make sure your phone stays connected to the internet.

Media files aren't processing

Check that your server has enough disk space for temporary file storage. Also verify that your AI model supports vision (Claude Opus and Sonnet do, Haiku does too but with less detail).

Advanced: Sending Messages Programmatically

Once WhatsApp is connected, you can use the CLI to send messages from scripts or cron jobs:

openclaw message send --to +1234567890 --message "Your daily report is ready"

This opens up automation possibilities. A few examples:

Morning briefing: A cron job at 7am that asks the assistant to summarize your emails and send the result to your WhatsApp.

Server monitoring: A script that checks your server health and messages you on WhatsApp if something looks wrong.

Webhook relay: Connect an external service (Stripe, GitHub, your CRM) to fire webhooks that get forwarded to you as WhatsApp messages.

# Example cron job: daily email summary at 7am
0 7 * * * openclaw agent --message "Summarize my unread emails and send me the summary" --channel whatsapp

Frequently Asked Questions

Will this get my WhatsApp account banned?

The OpenClaw community hasn't reported bans for personal assistant use. Baileys mimics normal WhatsApp Web behavior. That said, sending mass messages or spamming would likely trigger WhatsApp's automated systems, so don't do that.

Can I use a separate phone number for the assistant?

Yes. Get a cheap SIM card, register a new WhatsApp account on it, and link that to OpenClaw. This keeps your personal WhatsApp completely separate. Some people prefer this for peace of mind.

Does this work with WhatsApp Business?

OpenClaw connects through the standard WhatsApp protocol, not the Business API. A regular WhatsApp account is what you need.

Can multiple people in my family use it?

Yes — add all their phone numbers to the allowFrom list. Or set up a family group chat with the assistant in it. Each person's DMs with the assistant are separate sessions with their own context.

How much data does it use?

Very little. Text messages are tiny. Even with regular image and voice processing, you'd struggle to use more than a few hundred megabytes per month. It's negligible on any modern data plan.

Don't have OpenClaw running yet? Start with our complete setup guide. Looking for the cheapest way to keep it running 24/7? Check our hosting comparison or cost breakdown.