Skip to main content

​
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, 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
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. 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
That bootstrap token carries the built-in pairing bootstrap profile:
  • primary handed-off node token stays scopes: []
  • any handed-off operator token stays bounded to the bootstrap allowlist: operator.approvals, operator.read, operator.talk.secrets, operator.write
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.
  • The pairing record is the durable source of truth for approved roles. Active device tokens stay bounded to that approved role set; a stray token entry outside the approved roles does not create new access.