Pairing

Pairing

“Pairing” is OpenClaw’s explicit owner approval step. It is used in two places:

1. DM pairing (who is allowed to talk to the bot)
2. 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, 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 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).

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. If you use the device-pair plugin, you can do first-time device pairing entirely from Telegram:

1. In Telegram, message your bot: /pair
2. The bot replies with two messages: an instruction message and a separate setup code message (easy to copy/paste in Telegram).
3. On your phone, open the OpenClaw iOS app → Settings → Gateway.
4. Paste the setup code and connect.
5. 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://... or wss://...)
• 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) is a separate gateway-owned pairing store. WS nodes still require device pairing.
• Security model + prompt injection: Security
• Updating safely (run doctor): Updating
• Channel configs: