OpenClaw Pairing: Secure Device Access

Pairing: Secure Access Control

OpenClaw uses pairing codes to control who can talk to your AI. It’s simple: unknown contacts get a code, you approve or ignore them.

No random strangers are going to accidentally (or intentionally) use your AI.

---

How Pairing Works

When someone new sends a message to your OpenClaw bot:

1. They receive a pairing code (8 uppercase characters)
2. The code expires after 1 hour
3. You approve it with a CLI command
4. They’re added to your allowlist — future messages go through automatically

Codes are designed to be human-readable: no confusing characters like 0/O or 1/I.

---

Two Types of Pairing

1. DM Pairing (Chat Contacts)

Controls who can message your bot on each channel.

List pending requests:

openclaw pairing list whatsapp
openclaw pairing list telegram
openclaw pairing list discord

Approve a contact:

openclaw pairing approve whatsapp <CODE>
openclaw pairing approve telegram <CODE>
openclaw pairing approve discord <CODE>

Works for: whatsapp, telegram, discord, signal, imessage, slack

2. Node Pairing (Devices)

Controls which devices (iOS, Android, macOS, headless) can connect to your gateway.

List pending device requests:

openclaw pairing list nodes

Approve a device:

openclaw pairing approve nodes <CODE>

---

Where State is Stored

Pairing data lives in ~/.openclaw/credentials/:

File	Purpose
<channel>-pairing.json	Pending pairing requests
<channel>-allowFrom.json	Approved allowlist

For example:

• whatsapp-pairing.json — pending WhatsApp requests
• telegram-allowFrom.json — approved Telegram contacts

---

Limits

To prevent spam:

• Max 3 pending requests per channel — additional requests are ignored until one expires or is approved
• Codes expire after 1 hour — the bot only sends a new code when creating a fresh request
• One code per sender per hour — no code spam

---

Self-Chat Exception

Your own phone number (the one linked to WhatsApp, etc.) is implicitly trusted. You don’t need to approve yourself.

This means:

• Messages from your linked device skip pairing
• selfChatMode in WhatsApp works without approval

---

Config Options

Disable pairing entirely (not recommended):

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["*"]
    }
  }
}

The "*" wildcard allows everyone. Use with caution!

Security deep dive: Official security docs →

---

Common Workflows

Approve your own phone

First time setup? You’ll need to approve yourself from another device:

1. Text the bot from your phone
2. Get the pairing code
3. On your computer: openclaw pairing approve whatsapp <CODE>

Add a family member

Share the bot with someone:

1. They text your bot number
2. They receive a code (tell them to share it with you)
3. You run: openclaw pairing approve whatsapp <CODE>

Revoke access

Edit the allowlist file directly:

# View current allowlist
cat ~/.openclaw/credentials/whatsapp-allowFrom.json

# Remove a number and save

---

Troubleshooting

”No pending pairing requests”

The code might have expired. Ask them to text the bot again to generate a new code.

Bot not sending pairing codes

Check if the gateway is running:

openclaw gateway status

Still stuck? Our AI Setup Assistant is trained on all OpenClaw documentation.

---

What’s Next?

• Connect WhatsApp → — Full setup guide
• Connect Discord → — Bot setup
• Getting Started → — Complete onboarding

---

Need help? Join the OpenClaw Discord or check the official docs.