How to Pair OpenClaw Device Nodes

Device pairing is OpenClaw’s approval layer for nodes, browser devices, and companion apps. A node connects to the Gateway WebSocket with a device identity and role, and the Gateway creates a pairing request that the owner must approve. That gives you a durable contract for what the device is allowed to be, instead of trusting any client that can reach the port.

When this is the right move

Pair devices when adding iOS, Android, macOS node mode, a headless node host, or a non-loopback browser Control UI connection. Local loopback browser connections can be auto-approved, but Tailnet and LAN browser devices still require explicit approval. That is a feature, not friction.

The practical workflow

1. Start the device, app, browser, or node host so it attempts to connect to the Gateway.
2. On the Gateway host, list pending devices and inspect the request ID, role, scopes, and metadata.
3. Approve only the current request ID. If the device retried with changed auth details, the prior pending request may have been superseded.
4. Reject requests you do not recognize. Do not leave mystery pending devices sitting around as future confusion.
5. After approval, check node status or reconnect the browser/app to confirm it uses the approved role and scope set.

Grounded command or config pattern

The docs show the same core approve/reject flow for WS nodes and device pairing.

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

The pairing docs also describe Telegram-based first-time device pairing through /pair when the device-pair plugin is used. The setup code is a base64 JSON payload with a Gateway WebSocket URL and a short-lived bootstrap token. Treat it like a password while valid.

Operator notes

The strongest detail in the docs is upgrade behavior. An already paired device does not silently gain broader access. 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. That is the right security posture for devices that can execute commands or show admin UI.

Rollout approach

For pair openclaw device nodes, I would make the first pass deliberately small: one owner, one machine or channel, one visible test, and one rollback path. OpenClaw features become powerful when they connect to real tools and real messages, so the safest rollout is not a giant configuration day. It is a short rehearsal that proves the docs-grounded path works in your exact workspace before you depend on it while busy.

Common mistake

The common mistake is treating the command as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and a tiny verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A small note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or machine changes.

Safety checks

Auto-approval is manual by default for a reason. The docs allow optional trusted-CIDR node auto-approval only for tightly controlled node networks and only for fresh role: node requests with no requested scopes. Operator, browser, Control UI, and WebChat clients still require manual approval.

How to verify it worked

Run openclaw nodes status for node devices or reconnect the browser/app for Control UI devices. The approved device should connect without another pairing prompt, and any later scope upgrade should produce a new pending request instead of silently broadening access.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.