OpenClaw WhatsApp Setup: Complete Guide

You installed OpenClaw. You picked your model. Now you want to talk to your AI agent from WhatsApp. The same app you already use 50 times a day. No new interface. No browser tab. Just message your agent like you'd message a friend. Here's exactly how to set it up.

What You Need Before Starting

Before you touch the WhatsApp config, make sure you have these basics covered:

• OpenClaw installed (npm install -g openclaw@latest). Requires Node.js 22 or newer.
• An API key configured (Anthropic, OpenAI, or a local model via Ollama). Check our OpenClaw pricing breakdown for cost details.
• A phone with WhatsApp installed. That's the phone you'll scan the QR code from.
• Your gateway running or ready to start. The gateway is what keeps the WhatsApp connection alive.

If you haven't installed OpenClaw yet, head to installopenclawnow.com and follow the one-liner. Takes about 2 minutes.

Dedicated Number vs Personal Number

You have two options. Each works. One is cleaner.

Personal number works too. OpenClaw supports it. When your linked self number is also in the allowlist, self-chat safeguards kick in automatically. It skips read receipts for self-chat turns and avoids mention loops that would ping yourself. But it can get messy if you're not careful with your config.

For a dedicated number, your config is simple:

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"]  // your personal number
    }
  }
}

For a personal number setup, OpenClaw writes a self-chat-friendly baseline automatically during onboarding. It sets selfChatMode: true and adds your number to allowFrom.

Step-by-Step WhatsApp Setup

Four steps. Under 5 minutes if everything goes right.

Step 1: Configure your access policy

Open your openclaw.json config file and add the WhatsApp channel block. At minimum:

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"]
    }
  }
}

The dmPolicy: "pairing" is the default. It means new contacts have to go through a pairing flow. They message the agent, get a pairing code, and you approve or deny via CLI. Simple access control without touching the config every time.

Step 2: Link WhatsApp via QR code

Run this in your terminal:

openclaw channels login --channel whatsapp

A QR code appears in your terminal. On your phone, open WhatsApp. Go to Settings > Linked Devices > Link a Device. Scan the code.

That's it. WhatsApp treats OpenClaw like another linked device (same as WhatsApp Web or Desktop).

How the WhatsApp Bridge Works Under the Hood

OpenClaw uses the Baileys library to connect to WhatsApp. Baileys is an open-source, community-maintained implementation of the WhatsApp Web protocol. It does not require the WhatsApp Business API or a Meta developer account.

What this means in practice:

• No monthly fees. Unlike the official WhatsApp Cloud API (which charges per conversation after free tier limits), Baileys is completely free.
• No business verification. You do not need a Meta Business Manager account, a verified business phone number, or approval from Meta.
• Full feature support. Text messages, images, videos, voice notes, documents, stickers, reactions, read receipts. Everything works.
• Session persistence. Once linked, the session stays active until you explicitly log out or WhatsApp revokes the link. OpenClaw saves the session credentials to disk so it survives gateway restarts.

One important limitation: WhatsApp allows a maximum of 4 linked devices per account. If you are already using WhatsApp Web, WhatsApp Desktop, and another linked device, you may need to unlink one before connecting OpenClaw.

Step 3: Start the gateway

openclaw gateway

The gateway owns the WhatsApp socket and handles reconnections. Keep it running. If you're on a Mac Mini or VPS, set it up as a daemon so it survives reboots.

Step 4: Approve pairing (if using pairing mode)

When someone messages your agent for the first time, they'll get a pairing code. Approve it:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Pairing requests expire after 1 hour. You can have up to 3 pending requests per channel.

Access Control: Who Can Talk to Your Agent

This is the part most people skip and then regret. Lock it down from day one.

OpenClaw supports four DM policies for WhatsApp:

Policy	Who Can Message	Best For
pairing	Anyone, but requires approval	Default. Good for most setups.
allowlist	Only numbers in allowFrom	Production. Locked down tight.
open	Everyone (requires allowFrom: ["*"])	Testing only. Don't run this in production.
disabled	Nobody	When you only want group access.

For a solo founder running a personal agent: allowlist with your own number is the way to go. Nobody else needs to talk to your agent.

You can also set per-account overrides if you run multiple WhatsApp numbers:

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
      accounts: {
        work: {
          dmPolicy: "pairing",
          allowFrom: ["+15559876543", "+15558765432"]
        }
      }
    }
  }
}

Using OpenClaw in WhatsApp Groups

Yes, your agent can participate in group chats. No, it won't reply to every single message (unless you want it to).

Group access has two layers:

1. Group membership allowlist. Which groups can the agent see? If you set groups in your config, only those groups are eligible. Omit it and all groups are fair game.

2. Group sender policy. Who in those groups can trigger the agent?

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    }
  }
}

By default, the agent only responds when mentioned. It uses WhatsApp mentions, configured regex patterns, and reply-to-bot detection. So someone replying to the agent's message also counts as a mention.

One thing to know: sender allowlists are evaluated before mention detection. So even if someone @mentions your agent, they'll be blocked if they're not on the allowlist when groupPolicy: "allowlist" is set.

Media Handling in WhatsApp

Your agent can both receive and send media through WhatsApp. Here is how each type works:

• Images: When you send a photo, OpenClaw downloads it and passes it to your configured vision model for analysis. The agent can describe the image, extract text via OCR, or use it as context. To send images back, the agent uses the message tool with a file path or URL.
• Voice notes: Incoming voice messages get transcribed automatically using Whisper or your configured speech-to-text provider. The agent processes the transcription as regular text. You can also configure your agent to reply with voice using TTS.
• Documents: PDFs, spreadsheets, and text files get downloaded and processed. Your agent can read the contents, summarize them, or extract specific data points.
• Videos: Video files get downloaded. The agent can extract frames for visual analysis or process the audio track for transcription.
• Stickers: Similar to Telegram, OpenClaw uses vision models to describe sticker content and caches descriptions to avoid repeated API calls.

File size limits follow WhatsApp's own restrictions: 16MB for media, 100MB for documents. OpenClaw handles the download and caching automatically. Files are stored temporarily in your workspace directory under ~/.openclaw/whatsapp/media/.

Self-Chat Mode: Talk to Yourself (Productively)

This is one of the best WhatsApp features most people miss. When your personal number is in allowFrom, OpenClaw activates self-chat safeguards:

• Skips read receipts for self-chat turns (so your contacts don't see weird "read" statuses)
• Ignores mention triggers that would ping yourself
• Adds a response prefix like [Marc] so you can tell agent replies apart from your own messages

You literally message yourself on WhatsApp and your agent responds. It looks like a conversation with yourself. Except one side is an AI that can check your calendar, search the web, manage your files, and run automations.

Troubleshooting Common Issues

Things that will go wrong and how to fix them:

"Outbound sends fail fast" means your gateway isn't running or the WhatsApp listener isn't active. Start the gateway: openclaw gateway. If it was running, restart it.

Agent not responding in groups. Check your groupPolicy. If it's set to allowlist, make sure the sender is in groupAllowFrom. Also verify you're mentioning the agent properly.

WhatsApp disconnects after a few hours. This happens. The gateway handles reconnections automatically. If it keeps disconnecting, run openclaw doctor --fix to diagnose issues. You can also try openclaw channels logout --channel whatsapp and re-link.

Duplicate messages or echo loops. Usually means selfChatMode isn't set properly on a personal number. Check that your number is in allowFrom and let OpenClaw's self-chat protections do their job.

For more fixes, check our full OpenClaw troubleshooting guide.

What You Can Actually Do from WhatsApp

Once connected, your WhatsApp becomes a command center. Everything your agent can do, you can trigger from a message:

• Send it a voice note. OpenClaw transcribes and processes it.
• Share a photo. Your agent can analyze images, read documents, extract text.
• Ask it to check your email. "Any urgent emails today?"
• Run automations. "Post today's thread to X." "Draft a newsletter." "Check my calendar."
• Search the web. "What's the weather in Bali?" "Find me flights to Tokyo next week."
• Manage files. "Read the latest report." "Update the project status."

The full list of possibilities depends on your skills and config. Check 25+ OpenClaw use cases for inspiration.

I run 13 agents from my WhatsApp and Telegram setup. Content creation, email management, research, social media scheduling. All from the same messaging apps I was already using. That's the point. You don't need another dashboard. You need your tools where you already are.

Advanced Configuration Tips

Once your basic setup works, these tweaks make the experience smoother:

• Response prefix: Configure a prefix like [Agent] or your agent's name so you can instantly tell agent messages apart from your own. Especially important in self-chat mode where both sides look like "you."
• Rate limiting: WhatsApp has anti-spam detection. If your agent sends too many messages too quickly, WhatsApp may temporarily block the account. OpenClaw has built-in rate limiting, but avoid cron jobs that blast 20+ messages in rapid succession.
• Multi-device awareness: When you open the same WhatsApp chat on your phone and send a message, the agent might see it as a new incoming message and try to respond. The selfChatMode protections handle most edge cases, but be aware of this if you see unexpected responses.
• Session persistence: The WhatsApp session file lives at ~/.openclaw/whatsapp/. Back this up. If you lose it, you need to re-scan the QR code. If you are migrating to a new server, copy this directory to avoid re-authentication.
• WhatsApp vs Telegram: In my experience, Telegram is better for power users because of forum topics and unlimited file sizes. WhatsApp is better for casual use because everyone already has it installed. Run both if you want the best of each.

Frequently Asked Questions

How do I connect OpenClaw to WhatsApp?

OpenClaw connects to WhatsApp through a WhatsApp Web bridge. During setup, scan a QR code with your phone to link the session. Once connected, your agent can send and receive WhatsApp messages, images, and voice notes.

Can I use OpenClaw as a WhatsApp assistant?

Yes, OpenClaw works as a full WhatsApp assistant. Message your agent on WhatsApp and it responds with AI-powered answers, executes tasks, searches the web, and manages your tools. It works just like chatting with a human assistant.

Does the OpenClaw WhatsApp integration work 24/7?

Yes, as long as your OpenClaw instance is running and the WhatsApp Web session stays active. The session may need periodic re-authentication by scanning the QR code again. A stable internet connection ensures continuous operation.

Can OpenClaw send WhatsApp messages to my contacts?

Yes, OpenClaw can send messages to your WhatsApp contacts when configured to do so. You can set up automated messages, reminders, and notifications. Always use this responsibly and respect your contacts' preferences.

Is the OpenClaw WhatsApp setup difficult?

No, the WhatsApp setup is straightforward. Install the WhatsApp channel plugin, scan the QR code with your phone, and you are connected. The process takes about 5 minutes. OpenClaw handles the technical bridge automatically.