Pairing
Overview of pairing mechanisms: approving who can message you privately, and which nodes can join.
"Pairing" is the explicit **owner approval** step in OpenClaw. It is mainly used in two types of scenarios:
1. **DM Pairing**: Who is allowed to talk to your bot/assistant
2. **Node Pairing**: Which devices/nodes are allowed to join the gateway network
For security background, see Security
1) DM Pairing (Inbound Chat Access)
When a channel's private chat policy (DM policy) is configured as `pairing`, unknown senders will receive a short code. Until you approve it, their messages **will not be processed**.
Default DM policy explanation: Security
Pairing Code Rules:
- 8-character string, all uppercase, excluding ambiguous characters (`0O1I`).
- **Expiries in 1 hour**. The bot only sends pairing messages when creating new requests (typically max once per hour per sender).
- The default limit is **3 pending requests** per channel; subsequent requests are ignored until requests expire or are approved.
Approving a Sender
openclaw pairing list telegram openclaw pairing approve telegram '<CODE>'
Supported channels: `telegram`, `whatsapp`, `signal`, `imessage`, `discord`, `slack`.
Where is the Status Saved?
Saved under `~/.openclaw/credentials/`:
- Pending requests: `<code1>'<channel>-pairing.json</code1>`
- Approved allowlist: `<code2>'<channel>-allowFrom.json</code2>`
These files determine who can access your assistant and should be protected as sensitive information.
2) Node Device Pairing (iOS/Android/macOS/Headless nodes)
Nodes connect to the Gateway as **devices** with `role: node`. The Gateway creates a device pairing request that must be approved by you.
Approving a Node Device
openclaw devices list openclaw devices approve '<requestId>' openclaw devices reject '<requestId>'
Where is the Status Saved?
Saved under `~/.openclaw/devices/`:
- `pending.json` (transient file; pending requests expire)
- `paired.json` (paired devices and their tokens)
Notes
The legacy `node.pair.*` API (CLI: `openclaw nodes pending/approve`) uses a different set of pairing storage managed by the gateway. WS nodes still require device pairing.
Related Documentation
- Security Model & Prompt Injection
- Security Updates (Running Doctor)
Channel Configuration:
- Telegram
- Signal
- iMessage
- Discord
- Slack