How to Manage OpenClaw Devices

Device management in OpenClaw is not just a convenience layer. It is the operational control plane for device pairing requests and device-scoped tokens. The docs group this under openclaw devices, and the command set covers the full lifecycle: list, approve, reject, remove, clear, rotate, and revoke. If you are running remote nodes, Control UI devices, or anything else that pairs into the gateway, this is the command family that keeps access clean instead of drifting forever.

Step 1: inspect the current state before you approve anything

Start with openclaw devices list. The docs say it shows pending pairing requests and paired devices, and if a device is already paired it will show the newly requested access alongside the currently approved access. That is important because a retried pairing can actually be an upgrade request rather than a lost device. OpenClaw wants you to see requested versus approved access before you mint more authority.

openclaw devices list
openclaw devices list --json

Step 2: approve or reject with the exact request id

Approval is intentionally strict. If you run openclaw devices approve without a request id, or with --latest, OpenClaw only previews the selected pending request and exits. You then rerun the command with the exact request id after reviewing it. That extra step is not ceremony. The docs explain that a retried device pairing can supersede an earlier pending entry and generate a new requestId, so you should list right before approval instead of trusting an older id you copied earlier.

openclaw devices approve 
openclaw devices reject 

Step 3: use remove, rotate, and revoke deliberately

If a device is stale, remove it with openclaw devices remove. If the pairing is still valid but the token drifted or needs renewal, use openclaw devices rotate. Rotation returns sensitive new token material as JSON, so treat it like a secret. If you want to kill one role token without deleting the whole device record, use revoke. The docs also note that rotation cannot mint a broader role than the approved pairing contract already allows.

openclaw devices rotate --device  --role operator --scope operator.read --scope operator.write
openclaw devices revoke --device  --role node

Step 4: understand the permission boundaries

OpenClaw is careful about who can manage what. Non-admin paired-device callers can remove, rotate, or revoke only their own device entries. Cross-device management requires operator.admin. devices clear is gated behind --yes. And if you pass --url to any of these commands, the CLI will not fall back to config or environment credentials. You must pass explicit auth with --token or --password. That safety rule shows up in several command families and it is worth respecting.

Step 5: use the token drift recovery checklist when auth goes weird

The docs include a practical recovery loop for AUTH_TOKEN_MISMATCH or AUTH_DEVICE_TOKEN_MISMATCH errors. Confirm the current shared gateway token source, list devices, rotate the operator token for the affected device, and if that is not enough remove the stale pairing and approve it again. That is a nice example of OpenClaw docs being operational instead of theoretical. They tell you exactly how to recover rather than just explaining the data model.

In practice, managing devices well means doing fewer approvals, but doing them more deliberately. Check requested versus approved access, use exact request ids, rotate before you panic, and only clear or remove when you are sure the pairing should be gone. OpenClaw gives you the right primitives. The quality comes from using them like access-control tools, not like casual cleanup commands.

If you want the operator version of these docs turned into a practical working system, read The OpenClaw Playbook. It connects official OpenClaw features to real workflows, guardrails, and deployment decisions.