How OpenClaw WhatsApp Pairing Works - A Complete Guide

If you’re setting up OpenClaw to work with WhatsApp, one of the first security features you’ll encounter is pairing. This isn’t just a formality—it’s your control center for deciding who can talk to your AI assistant via WhatsApp. In this guide, we’ll walk through exactly how OpenClaw’s WhatsApp pairing system works, why it’s important, and how to manage it effectively.

What is Pairing?

At its core, pairing is OpenClaw’s way of ensuring that only trusted people can interact with your AI agent over WhatsApp. When someone messages your OpenClaw-linked number for the first time, they don’t immediately get a response. Instead, OpenClaw generates a unique 8-character pairing code and sends it to you, the owner. You must explicitly approve the requester before they gain access.

This prevents unauthorized users from flooding your assistant with requests or probing for sensitive information.

Key Features of WhatsApp Pairing

• 8-character codes: Uppercase, non-ambiguous (e.g., no 0/O or 1/I)
• 1-hour expiration: Codes expire after 60 minutes
• 3-pending request limit: Only three unapproved requests are tracked at once
• Owner-controlled approval: Only you can approve new contacts

Why Pairing Matters

Security is the main reason. Without pairing, your assistant is open to anyone who knows your number. While that might seem convenient, it opens the door to spam, misuse, and potential data leaks if your assistant has access to personal files or systems.

Pairing shifts control back to you. You decide:

• Who can message your bot
• When they gain access
• How long they stay approved

It’s a lightweight but powerful gatekeeper.

How to Approve a New Contact

When a new contact messages your WhatsApp number, OpenClaw will notify you (typically via your primary channel like iMessage or Telegram). You’ll see a message like:

New pairing request from +15551234567
Code: ABCD1234
Expires in 60 minutes

To approve them, run:

openclaw pairing approve whatsapp ABCD1234

Once approved, the user is added to your allowlist and can interact normally.

Where Pairing Data Is Stored

All pairing information is stored locally on your machine:

• ~/.openclaw/credentials/whatsapp-pairing.json – Pending requests
• ~/.openclaw/credentials/whatsapp-allowFrom.json – Approved contacts

These files are sensitive—treat them like passwords. They determine who has access to your assistant.

Configuring WhatsApp Access Policies

Pairing is just one part of WhatsApp access control. OpenClaw supports multiple policies:

• pairing (default): Requires approval via code
• allowlist: Only pre-approved numbers can message
• open: Anyone can message (requires allowFrom: ["*"])
• disabled: No inbound DMs allowed

You can set this in your OpenClaw config under channels.whatsapp.dmPolicy.

For production use, we recommend sticking with pairing or allowlist.

Best Practices

1. Review pending requests regularly – Don’t let unknown codes pile up.
2. Use specific allowlists for teams – If multiple people need access, pre-approve them.
3. Disable open policies – Avoid allowFrom: ["*"] unless in a controlled environment.
4. Monitor self-chat behavior – If your own number is in the allowlist, OpenClaw applies special safeguards (no read receipts, no self-pings).

Troubleshooting Common Issues

"I didn’t get a pairing code"

Make sure your primary channel (e.g., iMessage) is connected and working. OpenClaw sends pairing notifications there.

"The code expired"

No problem—just have the user resend their message. A new code will be generated.

"I approved but they still can’t message"

Check that channels.whatsapp.allowFrom includes the number in E.164 format (e.g., +15551234567).

Final Thoughts

WhatsApp pairing is a critical layer of security that gives you full control over who interacts with your AI assistant. It’s easy to set up, hard to bypass, and essential for maintaining trust and privacy.

By understanding how it works and using it wisely, you can enjoy the convenience of AI conversations on WhatsApp—without sacrificing security.

Ready to set it up? Scan the QR code in your terminal and start pairing with confidence.