Use this file to discover all available pages before exploring further.
Pairing
“Pairing” is OpenClaw’s explicit access 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
, unknown senders get a short code and their message is
not processed until you approve.
Default DM policies are documented in: Security
is public only when the effective DM allowlist includes
.
Setup and validation require that wildcard for public-open configs. If existing
state contains
with concrete
entries, runtime still admits
only those senders, and pairing-store approvals do not widen
access.
Pairing codes:
- 8 characters, uppercase, no ambiguous chars ().
- 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>
If no command owner is configured yet, approving a DM pairing code also bootstraps
to the approved sender, such as
.
That gives first-time setups an explicit owner for privileged commands and exec
approval prompts. After an owner exists, later pairing approvals only grant DM
access; they do not add more owners.
Supported channels:
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
.
Where the state lives
Stored under
:
- Pending requests:
- Approved allowlist store:
- Default account:
- 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).
note
The pairing allowlist 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. First-owner bootstrap is separate config
state in `commands.ownerAllowFrom`, and group chat delivery still follows the
channel's group allowlists (for example `groupAllowFrom`, `groups`, or per-group
or per-topic overrides depending on the channel).
2) Node device pairing (iOS/Android/macOS/headless nodes)
Nodes connect to the Gateway as devices with
. The Gateway
creates a device pairing request that must be approved.
Pair via Telegram (recommended for iOS)
If you use the
plugin, you can do first-time device pairing entirely from Telegram:
- In Telegram, message your bot:
- 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: (review request IDs, role, and scopes), then approve.
The setup code is a base64-encoded JSON payload that contains:
- : the Gateway WebSocket URL ( or )
- : 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 token stays
- any handed-off token stays bounded to the bootstrap allowlist:
, , ,
- bootstrap scope checks are role-prefixed, not one flat scope pool:
operator scope entries only satisfy operator requests, and non-operator roles
must still request scopes under their own role prefix
- later token rotation/revocation remains bounded by both the device's approved
role contract and the caller session's operator scopes
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
is created.
note
An already paired device does not get broader access silently. If it reconnects asking for more scopes or a broader role, OpenClaw keeps the existing approval as-is and creates a fresh pending upgrade request. Use `openclaw devices list` to compare the currently approved access with the newly requested access before you approve.
Optional trusted-CIDR node auto-approve
Device pairing remains manual by default. For tightly controlled node networks,
you can opt in to first-time node auto-approval with explicit CIDRs or exact IPs:
{
gateway: {
nodes: {
pairing: {
autoApproveCidrs: ["192.168.1.0/24"],
},
},
},
}
This only applies to fresh
pairing requests with no requested
scopes. Operator, browser, Control UI, and WebChat clients still require manual
approval. Role, scope, metadata, and public-key changes still require manual
approval.
Node pairing state storage
Stored under
:
- (short-lived; pending requests expire)
- (paired devices + tokens)
Notes
- The legacy API (CLI:
openclaw nodes pending|approve|reject|remove|rename
- 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.
Related docs
- Security model + prompt injection: Security
- Updating safely (run doctor): Updating
- Channel configs: