How to Approve OpenClaw Node Pairing Safely

Node pairing is how OpenClaw decides which iOS, Android, macOS, or headless nodes are allowed to join the Gateway network. A node can expose useful capabilities, but it also represents a remote action surface. Approving it should be a deliberate identity and trust decision, not a reflexive click-through.

30-second answer

Pair nodes through the Gateway device pairing flow, review requests with openclaw devices list, and approve or reject by requestId. Already paired devices do not silently receive broader roles or scopes; upgrades create new pending requests. Optional trusted-CIDR auto-approval is narrow, disabled by default, and only applies to fresh role node requests with no requested scopes.

When this pays off

This matters when you connect phones, tablets, Macs, browser hosts, or remote command nodes to an always-on Gateway. For business automation, nodes can provide camera, audio, location, media, browser, or host-local capabilities. That value is exactly why pairing needs a clean approval habit.

Operator runbook

1. Use the device pairing flow for WebSocket nodes. The docs distinguish WS device pairing with role node from legacy node.pair.* APIs. The durable device record is the source of approved roles and scopes for modern nodes.
2. Generate setup details through a trusted operator path. With the device-pair plugin, Telegram can provide /pair setup instructions and a separate setup code. That code contains the Gateway WebSocket URL and a short-lived bootstrap token. Treat it like a password while it is valid.
3. Review pending requests before approving. Run openclaw devices list and compare request role, scopes, metadata, and identity. If the same device retries with different auth details, the prior pending request can be superseded. Approve the current request only when it matches the device you expect.
4. Understand scope upgrades. Already paired devices do not get broader access silently. If a device reconnects asking for more scopes or a broader role, OpenClaw creates a fresh pending upgrade request. Compare existing approved access against requested access before you approve.
5. Use autoApproveCidrs sparingly. The docs describe gateway.nodes.pairing.autoApproveCidrs for private node networks, but it applies only to fresh role node device pairing with no requested scopes. Operator, browser, Control UI, WebChat, role upgrades, scope upgrades, metadata changes, and public-key changes remain manual.
6. Remember live command policy. Pairing establishes node identity and trust, but it does not permanently pin the node command surface. Live node commands come from what the node declares after global command allow/deny policy is applied, and system.run approvals live on the node side.

Verification

After approval, run openclaw devices list or node status commands as appropriate and confirm the device is paired, connected, and exposing only expected capabilities. Then test one low-risk node tool. Revoke or remove stale nodes and confirm pending requests disappear when a device is deleted.

Common mistakes

Do not approve a node because it is on the same Wi-Fi without checking identity. Do not enable CIDR auto-approval for broad networks. Do not treat setup codes as harmless QR content. And do not assume node command safety is solved by pairing alone; command policy and exec approvals still matter.

Turn it into a repeatable operating system

The Playbook puts node pairing into a device lifecycle: request, identify, approve, verify, monitor, rotate, revoke. That is how you safely turn phones and machines into useful OpenClaw peripherals instead of mystery endpoints.

Before rollout

Before rollout, name every node by location and purpose after approval. A list of device IDs is hard to audit later. A list like support-mac-mini, warehouse-ipad, or home-office-browser-host makes stale devices and unexpected capability changes much easier to catch. Schedule a periodic review so old phones and test nodes do not stay trusted forever.