Understanding OpenClaw's Pairing System

OpenClaw's pairing system is a critical security and access control mechanism that ensures only authorized users and devices can interact with your AI agent. It operates on two distinct levels: direct message (DM) pairing for chat access and node pairing for device enrollment. This dual-layer approach provides robust protection while maintaining usability.

Direct Message Pairing (Chat Access Control)

When configured with DM policy pairing, OpenClaw requires explicit approval before processing messages from unknown senders. This system acts as your first line of defense against unauthorized access. When a new user attempts to message your bot, they receive an 8-character uppercase pairing code (excluding ambiguous characters like 0/O and 1/I) that expires after one hour.

The pairing process is straightforward:

1. The sender receives a pairing code via their messaging platform
2. You review the pairing request using openclaw pairing list [channel]
3. You approve the sender with openclaw pairing approve [channel] [CODE]

This system prevents unauthorized access while allowing you to grant permission to trusted contacts. By default, OpenClaw limits pending pairing requests to three per channel, preventing spam and ensuring manageable oversight. Once approved, users are added to your allowlist and can interact with your agent without further authentication.

Node Device Pairing (Device Enrollment)

The second layer of pairing controls which devices can connect to your OpenClaw gateway. This is essential when you want to access your agent from multiple devices like iPhones, Android phones, or other computers. When a new device attempts to connect, it generates a device pairing request that requires your explicit approval.

You can manage node pairing through several methods:

• Telegram pairing: Message your bot /pair to receive a setup code, then approve with /pair approve
• Command line: Use openclaw devices list to view pending requests and openclaw devices approve [requestId] to approve specific devices

The setup code is a base64-encoded JSON payload containing the gateway's WebSocket URL and a short-lived pairing token. This secure handshake ensures that only devices with the correct credentials can join your network.

Security Implementation

OpenClaw stores pairing information in sensitive files under ~/.openclaw/credentials/:

• Pending requests: Stored in -pairing.json files
• Approved allowlists: Stored in -allowFrom.json files

These files should be treated as highly sensitive, as they control access to your AI assistant. The system's design prevents unauthorized access even if someone gains partial system access, as they would still need to bypass the pairing approval process.

Best Practices for Pairing

To maintain optimal security while ensuring usability:

1. Regularly review your allowlist - Periodically check who has access to your agent and remove contacts who no longer need it

2. Use specific channel policies - Configure different pairing policies for different channels based on their security requirements

3. Monitor pairing attempts - Keep an eye on pairing requests to detect any suspicious activity

4. Combine with other security measures - Pairing works best when combined with other security practices like Tailscale authentication and proper channel configuration

The pairing system exemplifies OpenClaw's philosophy of security through explicit consent. Rather than relying on passwords or shared secrets that can be compromised, it requires your manual approval for every new connection. This approach ensures that you maintain complete control over who and what can interact with your AI assistant.