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).

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.

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.