Pairing & Device Verification

Secure device pairing with QR codes, approval flows, and pairing tokens

OpenClaw uses pairing to securely connect new users and devices. When someone first messages your bot, they receive a unique pairing code. You approve or deny the pairing request, giving you control over who can access your AI agent.

How Pairing Works

1. Unknown user messages bot

   A user who is not in your allowFrom list sends a message to your bot.

2. Bot sends pairing code

   The bot automatically responds with a pairing code like:

   Pairing required. Your code: ABC-123-DEF
   Ask the operator to approve with:
   openclaw pairing approve whatsapp ABC-123-DEF
   
3. You approve or deny

   Review the request and approve it:

   openclaw pairing approve whatsapp ABC-123-DEF
   

   Or deny it:

   openclaw pairing deny whatsapp ABC-123-DEF
   
4. User is added to allowlist

   Upon approval, the user’s identifier is automatically added to allowFrom in your config. They can now message the bot freely.

Enabling Pairing

Pairing is enabled with the pairing DM policy:

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",
      "allowFrom": []
    },
    "discord": {
      "dmPolicy": "pairing",
      "allowFrom": []
    }
  }
}

Supported Channels

Pairing is supported on these channels:

• WhatsApp - Identifies by phone number (E.164)
• Telegram - Identifies by user ID (numeric)
• Discord - Identifies by user ID (snowflake)
• Slack - Identifies by user ID (e.g., U123ABC456)
• Signal - Identifies by phone number or UUID
• iMessage - Identifies by phone number, email, or chat ID

Viewing Pending Requests

List all pending pairing requests:

openclaw pairing list

Output:

Pending pairing requests:

whatsapp:
  [phone] - Code: ABC-123-DEF - Requested: 2 minutes ago

telegram:
  123456789 (@username) - Code: XYZ-789-GHI - Requested: 5 minutes ago

Approving Requests

By Code

Approve using the pairing code:

openclaw pairing approve whatsapp ABC-123-DEF

By Identifier

Approve using the user’s identifier directly:

openclaw pairing approve telegram 123456789

By Interactive Selection

Let the CLI prompt you:

openclaw pairing approve

This shows a list of pending requests and lets you select which to approve.

Denying Requests

Deny a pairing request:

openclaw pairing deny whatsapp ABC-123-DEF

Or by identifier:

openclaw pairing deny telegram 123456789

Denied users will receive a message notifying them their request was denied.

Pairing Token Lifecycle

Generation

• Tokens are generated automatically when an unknown user messages
• Format: ABC-123-DEF (3 groups of alphanumeric characters)
• Tokens are unique per user per channel

Expiration

Pairing tokens expire after 24 hours by default. Configure this:

{
  "channels": {
    "pairing": {
      "tokenExpiry": "24h"
    }
  }
}

Supported formats:

• "1h" - 1 hour
• "24h" - 24 hours (default)
• "7d" - 7 days

Storage

Pairing tokens are stored in:

~/.openclaw/pairing/
  ├── whatsapp.json
  ├── telegram.json
  ├── discord.json
  └── ...

Automatic Allowlist Updates

When you approve a pairing request, OpenClaw automatically:

1. Adds the user’s identifier to allowFrom in your config
2. Writes the updated config to disk
3. Sends a confirmation message to the user

Example: approving [phone] on WhatsApp updates your config:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["[phone]"]
    }
  }
}

QR Code Pairing (WhatsApp & Signal)

WhatsApp and Signal use QR codes for initial device pairing:

WhatsApp

openclaw channels login whatsapp

1. A QR code appears in your terminal
2. Open WhatsApp on your phone → Settings → Linked Devices
3. Tap “Link a Device” and scan the QR code
4. Your device is now paired

Signal

signal-cli link -n "OpenClaw"

1. A QR code appears
2. Open Signal on your phone → Settings → Linked Devices
3. Tap ”+” and scan the QR code
4. Your device is now linked

Security Considerations

Pairing Codes

• Short-lived - Expire after 24 hours by default
• Single-use - Invalidated after approval or denial
• Channel-specific - A code for WhatsApp won’t work on Telegram
• Operator-controlled - Only you can approve requests

Best Practices

1. Review requests promptly - Don’t leave pairing requests pending for days
2. Verify the sender - Before approving, confirm you know who’s requesting access
3. Use allowlist mode for production bots with a fixed set of users
4. Monitor approvals - Check openclaw pairing list regularly
5. Revoke access if needed by removing from allowFrom

Revoking Access

If you need to revoke a user’s access:

openclaw pairing revoke whatsapp [phone]

Or manually edit your config to remove them from allowFrom:

{
  "channels": {
    "whatsapp": {
      "allowFrom": [
        // Remove the user's identifier from this array
      ]
    }
  }
}

Troubleshooting

Pairing code not sent

Check that:

• dmPolicy is set to "pairing" for the channel
• The channel is enabled and gateway is running
• The user is not already in allowFrom

Verify:

openclaw channels status --probe

Approval not working

Common issues:

• Wrong channel name (use openclaw pairing list to see valid channels)
• Code typo (codes are case-sensitive: ABC-123-DEF)
• Code expired (default: 24 hours)

Check pending requests:

openclaw pairing list

User still cannot message after approval

After approval, the user should be in allowFrom. Verify:

openclaw config get channels.whatsapp.allowFrom

If missing, manually add them:

openclaw config set channels.whatsapp.allowFrom '["[phone]"]'

Then restart the gateway:

openclaw gateway restart

Pairing storage full or corrupted

If you encounter issues with pairing storage, you can reset it:

rm -rf ~/.openclaw/pairing/
openclaw gateway restart

This will clear all pending pairing requests.

QR code not appearing (WhatsApp/Signal)

For WhatsApp:

• Ensure web.enabled: true in config
• Check logs: openclaw logs --follow
• Try again: openclaw channels login whatsapp --force

For Signal:

• Ensure signal-cli is installed
• Try: signal-cli link -n "OpenClaw"

Advanced Configuration

Custom Pairing Messages

Customize the pairing request message:

{
  "channels": {
    "pairing": {
      "message": "Hello! To use this bot, please share your pairing code with the administrator.\n\nYour code: {code}"
    }
  }
}

Available placeholders:

• {code} - The pairing code
• {channel} - Channel name (e.g., “whatsapp”)
• {identifier} - User’s identifier

Notification on New Requests

Get notified of new pairing requests:

{
  "channels": {
    "pairing": {
      "notifyOn": ["telegram:123456789"],
      "notifyMessage": "New pairing request on {channel} from {identifier}. Code: {code}"
    }
  }
}

You’ll receive a message on your configured notification channel whenever someone requests pairing.

CLI Reference

List Pending Requests

openclaw pairing list [channel]

Options:

• [channel] - Optional: filter by channel (e.g., whatsapp, telegram)

Approve Request

openclaw pairing approve <channel> <code-or-identifier>

Examples:

openclaw pairing approve whatsapp ABC-123-DEF
openclaw pairing approve telegram 123456789
openclaw pairing approve discord @username

Deny Request

openclaw pairing deny <channel> <code-or-identifier>

Revoke Access

openclaw pairing revoke <channel> <identifier>

Removes the user from allowFrom in your config.

Next Steps

Configuration Reference

Full configuration options

WhatsApp Setup

Set up WhatsApp with QR pairing

Security Best Practices

Secure your OpenClaw deployment

CLI Commands

Full pairing command reference