Getting Started8 minBeginnerSecurity

Pairing

OpenClaw's explicit owner approval step for DM pairing and node device pairing

What is 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

Pairing is a security feature to ensure only approved senders and devices can access your OpenClaw gateway and AI assistant.

1DM 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.

NoteDefault 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: telegram, whatsapp, signal, imessage, discord, slack

Where the state lives

Stored under ~/.openclaw/credentials/:

  • <channel>-pairing.jsonPending requests
  • <channel>-allowFrom.jsonApproved allowlist store

Security Note:Treat these as sensitive (they gate access to your assistant)

2Node 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.

Approve a node device

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

Where the state lives

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.

Next Steps

Learn about OpenClaw security best practices and more configuration options.

Security GuideGetting Started