How to Connect OpenClaw to WhatsApp (Complete Setup Guide)

Why WhatsApp?

Compared to other channels, WhatsApp has unique advantages:

The tradeoff: WhatsApp's API is more restrictive than Telegram's, and setup is slightly more involved.

• **You already use it.** No context switching — your AI agent lives alongside your normal chats
• **Works everywhere.** Phone, desktop, web — WhatsApp is on every device
• **End-to-end encrypted.** Messages between you and your agent are encrypted by default
• **Voice messages supported.** Send voice notes and get transcriptions back

Prerequisites

Before starting:

• **OpenClaw installed and running** — see our setup guide if you haven't done this yet
• **A phone number for WhatsApp** — this can be your existing number or a separate one
• **Your server accessible** — OpenClaw needs to stay running for WhatsApp to work

Step 1: Configure the WhatsApp Channel

OpenClaw uses the WhatsApp Web protocol to connect. During setup, you'll scan a QR code — just like linking WhatsApp Web on a new computer.

When the gateway starts, it will display a QR code in the terminal. Scan it with WhatsApp on your phone:

1. Open WhatsApp → Settings → Linked Devices

2. Tap "Link a Device"

3. Scan the QR code shown in your terminal

Once linked, your OpenClaw agent can send and receive messages through your WhatsApp account.

# Enable the WhatsApp channel
openclaw config set channels.whatsapp.enabled true

# Start the gateway
openclaw gateway restart

Step 2: Set Up Message Routing

By default, OpenClaw responds to direct messages. You'll want to configure which conversations trigger the agent:

**Recommendation:** Start with direct messages only. Add groups later once you're comfortable with how the agent behaves.

# Respond to all direct messages
openclaw config set channels.whatsapp.routing.direct true

# Respond in specific groups (by group name or ID)
openclaw config set channels.whatsapp.routing.groups '["Family", "Work Team"]'

# Or respond only when mentioned
openclaw config set channels.whatsapp.routing.mentionOnly true

Step 3: Test the Connection

Send yourself a message (or have a friend message you):

Your agent should respond within a few seconds. If it doesn't:

• Check `openclaw gateway status` for errors
• Make sure your phone has internet (WhatsApp requires the phone to be online initially)
• Try `openclaw gateway restart` to re-establish the connection

Practical WhatsApp Workflows

**Personal Assistant**

Message your agent throughout the day:

**Email Triage**

Instead of checking your inbox, let your agent check for you. Set this up with the email assistant skill.

**Travel Helper**

When you're traveling, your agent becomes invaluable:

**Voice Notes**

Send voice messages to your agent — it transcribes them and responds. The agent processes the voice note, checks your calendar, looks up the exchange rate, and sends back a text response.

• "Remind me to pick up groceries at 6 PM"
• "What's the weather like tomorrow?"
• "Find me a restaurant near Shibuya with good reviews"
• "Translate this to Japanese: I have a reservation for 2"
• Currency conversions on the fly
• Translation of menus, signs, and conversations
• Finding nearby restaurants, ATMs, pharmacies
• Checking flight status and gate changes

Group Chat Behavior

Adding your agent to group chats requires careful configuration. You don't want it responding to every message:

**Best practices for groups:**

See our channel comparison guide for more on group chat behavior across platforms.

• Set `mentionOnly: true` for group chats
• Configure the agent's group personality in SOUL.md (less verbose, more helpful)
• Use the agent for shared tasks: "What's the plan for Saturday?" or "Find a flight for all of us"

Keeping the Connection Alive

WhatsApp Web connections can drop if:

OpenClaw handles reconnection automatically in most cases. For maximum uptime:

If the connection drops and doesn't reconnect, you'll need to re-scan the QR code. This happens rarely but it's good to know.

• Your phone loses internet for an extended period
• WhatsApp updates its protocol
• Your server restarts

# Run OpenClaw as a system service
openclaw service install
openclaw service start

# Check connection status
openclaw gateway status

Privacy Considerations

When using WhatsApp with OpenClaw:

For maximum privacy, pair WhatsApp with a local Ollama model — messages never leave your machine.

• **Your messages pass through your server.** With self-hosting, this is your own machine — no third parties involved
• **WhatsApp's E2E encryption protects messages in transit.** But once received by OpenClaw, they're processed by your AI model provider (Anthropic, OpenAI, etc.)
• **Be mindful of group chats.** Other people's messages in groups will be processed by the AI model
• **Consider who has access to your server.** Anyone with server access can read message logs

Troubleshooting

QR code not showing: Run `openclaw gateway restart` and check terminal output.

Messages not being received: Verify phone has internet; re-link device if needed.

Slow responses: Check AI model latency; consider switching to a faster model.

"Phone offline" errors: Keep your phone connected to WiFi; WhatsApp requires periodic phone connectivity.

Agent responding to wrong chats: Check routing config; set `mentionOnly` for groups.

What's Next?

With WhatsApp connected, explore:

Your AI agent now lives in your pocket. Use it.

• **Cron jobs and heartbeats** for proactive check-ins
• **Email integration** to manage your inbox from WhatsApp
• **Automation examples** for workflow ideas
• **Security hardening** to lock down your setup

Conclusion

With WhatsApp connected, your OpenClaw agent is always reachable from the app you already use every day. Start with direct messages, then expand to group chats and automation workflows as you get comfortable. For maximum privacy, pair it with a local Ollama model. For maximum productivity, combine it with email integration and cron jobs. New to OpenClaw? Start with our complete setup guide, then come back here to add WhatsApp.

Frequently asked questions