Pairing & Access Control

Overview

Pairing is the explicit owner approval step used for security in two contexts:

1. DM Pairing - Controls who can communicate with the bot
2. Device Pairing - Controls which devices/nodes can join the Gateway network

DM Pairing (Inbound Chat Access)

When a channel uses the pairing DM policy, unknown senders receive a short code and their messages are held until you approve them.

How It Works

1. Unknown user sends a message to your bot
2. Bot responds with an 8-character pairing code
3. Messages are held in a pending queue
4. You approve or reject the pairing request
5. Approved users can communicate freely

Pairing Code Characteristics

• 8 uppercase characters
• Ambiguous characters excluded (0, O, 1, I)
• Expires after 1 hour
• Maximum 3 pending requests per channel (default)

Approval Commands

# List pending pairing requests
clawdbot pairing list telegram
clawdbot pairing list whatsapp

# Approve a pairing request
clawdbot pairing approve telegram ABC12DEF
clawdbot pairing approve whatsapp XYZ98GHI

# Reject a pairing request
clawdbot pairing reject telegram ABC12DEF

Supported Channels

Storage Locations

Device Pairing

Nodes connecting to the Gateway as devices with role: node require approval through device pairing requests.

Device Approval Commands

# List all devices (pending and paired)
clawdbot devices list

# Approve a device
clawdbot devices approve <requestId>

# Reject a device
clawdbot devices reject <requestId>

# Remove a paired device
clawdbot devices remove <deviceId>

Storage Locations

DM Policies

Configure DM policy in ~/.clawdbot/clawdbot.json:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": []
    }
  }
}

Available Policies

Security Best Practices

1. Use pairing mode for channels exposed to unknown users
2. Review pending requests regularly
3. Use allowlist mode for sensitive channels
4. Limit pending requests to prevent spam
5. Audit approved users periodically

Related Documentation

• Setup Guide - Initial configuration
• Security - Security best practices
• Channels - Channel configuration