4.4 KiB
summary, read_when, title
| summary | read_when | title | |||
|---|---|---|---|---|---|
| Pairing overview: approve who can DM you + which nodes can join |
|
Pairing |
Pairing
“Pairing” is OpenClaw’s explicit owner approval step. It is used in two places:
- DM pairing (who is allowed to talk to the bot)
- Node pairing (which devices/nodes are allowed to join the gateway network)
Security context: Security
1) DM pairing (inbound chat access)
When a channel is configured with DM policy pairing, unknown senders get a short code and their message is not processed until you approve.
Default DM policies are documented in: Security
Pairing codes:
- 8 characters, uppercase, no ambiguous chars (
0O1I). - Expire after 1 hour. The bot only sends the pairing message when a new request is created (roughly once per hour per sender).
- Pending DM pairing requests are capped at 3 per channel by default; additional requests are ignored until one expires or is approved.
Approve a sender
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
Supported channels: bluebubbles, discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, openclaw-weixin, signal, slack, synology-chat, telegram, twitch, whatsapp, zalo, zalouser.
Where the state lives
Stored under ~/.openclaw/credentials/:
- Pending requests:
<channel>-pairing.json - Approved allowlist store:
- Default account:
<channel>-allowFrom.json - Non-default account:
<channel>-<accountId>-allowFrom.json
- Default account:
Account scoping behavior:
- Non-default accounts read/write only their scoped allowlist file.
- Default account uses the channel-scoped unscoped allowlist file.
Treat these as sensitive (they gate access to your assistant).
Important: this store is for DM access. Group authorization is separate.
Approving a DM pairing code does not automatically allow that sender to run group commands or control the bot in groups. For group access, configure the channel's explicit group allowlists (for example groupAllowFrom, groups, or per-group/per-topic overrides depending on the channel).
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.
Pair via Telegram (recommended for iOS)
If you use the device-pair plugin, you can do first-time device pairing entirely from Telegram:
- In Telegram, message your bot:
/pair - The bot replies with two messages: an instruction message and a separate setup code message (easy to copy/paste in Telegram).
- On your phone, open the OpenClaw iOS app → Settings → Gateway.
- Paste the setup code and connect.
- Back in Telegram:
/pair pending(review request IDs, role, and scopes), then approve.
The setup code is a base64-encoded JSON payload that contains:
url: the Gateway WebSocket URL (ws://...orwss://...)bootstrapToken: a short-lived single-device bootstrap token used for the initial pairing handshake
Treat the setup code like a password while it is valid.
Approve a node device
openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
If the same device retries with different auth details (for example different
role/scopes/public key), the previous pending request is superseded and a new
requestId is created.
Node pairing state storage
Stored under ~/.openclaw/devices/:
pending.json(short-lived; pending requests expire)paired.json(paired devices + tokens)
Notes
- The legacy
node.pair.*API (CLI:openclaw nodes pending|approve|reject|rename) is a separate gateway-owned pairing store. WS nodes still require device pairing.