OpenClaw Devices Guide: openclaw devices, the Two-Stage Approval Trap, and Node Scopes

Approving a device with openclaw devices approve leaves the node connected and completely powerless. It opens the transport socket, but hands the agent zero commands.

Search results for openclaw devices lean heavily on reference tables. The official CLI documentation, the node pairing guide, and the command index list every flag from join-code to rotate. They describe how to accept a WebSocket connection from a secondary MacBook or a Linux box on your mesh. What they gloss over is the two-stage handshake that follows. You approve the device, check openclaw nodes status, and wonder why your primary agent still cannot execute a script on the remote machine. That silence happens because device transport and capability surfaces live in two separate permission queues. This guide walks through both approvals, the preview trap in --latest, and how to register remote workers without opening a backdoor into your network.

Device Pairing vs DM Pairing

Do not confuse device pairing with chat pairing. In the OpenClaw pairing guide, we looked at openclaw pairing, which handles human identities reaching your bot over Telegram, Slack, or Discord. That command maps inbound sender IDs to conversation sessions.

openclaw devices operates on physical hardware. It admits companion machines, mobile nodes, and auxiliary worker processes into your gateway mesh. A device connects as a WebSocket client declaring a role such as node or operator. Until you approve that hardware record, the gateway drops its packets at the perimeter.

The Two-Stage Approval Trap

Pairing is two handshakes.

When an external machine initiates a connection with role node, your Gateway generates an ephemeral transport record that validates the client certificate, records the remote IP, and assigns a temporary request identifier that expires five minutes after the last retry. You inspect it with the device command:

openclaw devices list
openclaw devices list --json

The output reveals a pending request with a requestId like devreq_9f82a1c4. You run approval:

openclaw devices approve devreq_9f82a1c4

The CLI prints success. The remote daemon reconnects. Yet when your agent tries to invoke a tool on that node, the task stalls. The daemon logs state PAIRING_REQUIRED.

Device transport and command execution are completely decoupled. Approving the device only maintains the raw WebSocket connection. The node's declared command surface remains unapproved, and an unapproved surface exposes zero tools.

To complete enrollment, you must inspect the node surface queue:

openclaw nodes pending
openclaw nodes approve nodereq_4b71d9e2

Notice the identifiers. devreq_9f82a1c4 and nodereq_4b71d9e2 are entirely distinct tokens. The first admits the box to the socket mesh. The second authorizes the specific capabilities (such as file reads or shell commands) declared in the node manifest. Skipping the second step is the single most common reason new companion nodes stay deaf.

The --latest Flag Exits Code 1 by Design

Automation scripts often break on openclaw devices approve because of an intentional safety guard in the CLI parser.

If you run openclaw devices approve without an argument, or pass --latest, the command does not approve anything. Instead, it prints a formatted preview of the newest pending request and exits with code 1.

# This will NOT approve the request!
openclaw devices approve --latest
echo "Exit code: $?" # Prints 1

The developers designed this behavior so bash scripts would not blindly approve whatever device knocked on the port first. If you want an automated deployment pipeline, query the JSON stream, extract the exact identifier, verify the public key fingerprint, and pass the explicit ID:

REQ_ID=$(openclaw devices list --json | jq -r '.pending[0].requestId // empty')
if [ -n "$REQ_ID" ]; then
  openclaw devices approve "$REQ_ID"
fi

The Five-Minute Expiry and the Superseded ID Flap

Pending device requests expire 5 minutes after the device's last retry.

A companion node that keeps running reconnects with an exponential backoff capped at 30 seconds. As long as that retry loop continues, the Gateway keeps the existing requestId alive. You do not need to rush before the clock runs out.

Problems arise when the device restarts with altered parameters. If the remote node changes its requested role, alters its declared tool scopes, or regenerates its local public key, OpenClaw marks the previous request as superseded. It issues a device.pair.resolved event on the event bus and assigns a brand new requestId.

If you paste an ID from a terminal tab you opened two minutes ago, you will receive an error stating the request was not found. When an approval fails unexpectedly, re-run openclaw devices list to capture the refreshed ID.

Node Scopes and the system.run Boundary

A node with an unapproved command surface is just an idle WebSocket connection burning electricity.

When you approve a node surface via openclaw nodes approve, you bind capabilities to the gateway. Those capabilities fall into strict security tiers:

Surface approval does not bypass local Gateway execution policy. Even after you grant system.run on a secondary node, any command matching your local security rules still triggers normal approval prompts, as detailed in our exec approvals guide.

Auto-Approving Nodes on Private Subnets

If you operate a fleet across a private WireGuard or mesh network, manually approving every Mac Mini or VPS quickly becomes tedious. You can configure subnet auto-approval in your gateway config:

{
  "gateway": {
    "nodes": {
      "pairing": {
        "autoApproveCidrs": ["100.64.0.0/10", "192.168.1.0/24"]
      }
    }
  }
}

When coupled with private mesh overlays like the ones covered in our Tailscale networking guide, incoming connections from trusted IPs skip the manual openclaw devices approve prompt.

There is an important restriction: autoApproveCidrs only admits fresh node requests with no elevated scopes. A node requesting system.run or administrative operator roles will never auto-approve from a subnet rule. You must confirm those elevated privileges by hand on the primary host.

Renaming and Revoking Devices

Device records persist in the gateway database. A machine named node-mac-m2 will retain that identity through gateway reboots and network disconnections.

# Assign a stable, human-readable label
openclaw devices rename --device dev_3a91bf --name "studio-mac-mini"

# Rotate token credentials for an existing node
openclaw devices rotate --device dev_3a91bf --role node --scope canvas

# Revoke a node and sever its connection
openclaw devices remove dev_3a91bf

Labels assigned with rename are owner-side metadata. They survive device pairing repairs and role modifications without changing the stable deviceId.

If you decommission a machine, use openclaw devices remove <deviceId>. If a device holds both operator and node roles, removing the node via openclaw nodes remove --node <id> strips only the worker execution capability, leaving the operator account intact.

Common Failure Modes

Final Verdict

Treat openclaw devices as your physical admission gate and openclaw nodes as your capability lock. Keep autoApproveCidrs restricted to point-to-point tailnets, label your hardware early with rename, and check openclaw security audit after registering any worker that holds shell permissions. Run the gateway doctor as explained in the gateway doctor guide if your node sockets refuse to bind.