Managing Device Pairing with OpenClaw CLI

Managing device access and tokens often feels like a chore, especially when you’re dealing with pending requests or stale tokens that break your workflow. If you’ve ever been stuck trying to figure out why a device won’t connect or how to kick off an old session, you know the struggle.

The openclaw devices command is your go-to tool for managing device pairing requests and device-scoped tokens. Here is how you can use it to keep your connections clean and secure.

Commands

openclaw devices list

You can use this to list pending pairing requests and paired devices.

openclaw devices list
openclaw devices list --json

The output for pending requests includes the requested role and scopes. This helps you review approvals before you commit.

openclaw devices remove <deviceId>

If you need to remove a single paired device entry, use this command.

When you are authenticated with a paired device token, non-admin callers can remove only their own device entry. Removing some other device requires operator.admin.

openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json

openclaw devices clear --yes [--pending]

Use this to clear paired devices in bulk.

openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json

openclaw devices approve [requestId] [--latest]

This command lets you approve a pending device pairing request by its exact requestId. If you omit the requestId or pass --latest, OpenClaw only prints the selected pending request and exits. You will need to rerun the approval with the exact request ID after you verify the details.

Note: if a device retries pairing with changed auth details (role/scopes/public key), OpenClaw supersedes the previous pending entry and issues a new requestId. Run openclaw devices list right before approval to use the current ID.

openclaw devices approve
openclaw devices approve <requestId>
openclaw devices approve --latest

openclaw devices reject <requestId>

If a request looks wrong, you can reject the pending device pairing request.

openclaw devices reject <requestId>

openclaw devices rotate --device <id> --role <role> [--scope <scope...>]

You can rotate a device token for a specific role and optionally update scopes. The target role must already exist in that device’s approved pairing contract; rotation cannot mint a new unapproved role.

If you omit --scope, later reconnects with the stored rotated token reuse that token’s cached approved scopes. If you pass explicit --scope values, those become the stored scope set for future cached-token reconnects.

Non-admin paired-device callers can rotate only their own device token. Also, any explicit --scope values must stay within the caller session’s own operator scopes; rotation cannot mint a broader operator token than the caller already

openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write

openclaw devices revoke --device <deviceId> --role node

openclaw config get gateway.auth.token

openclaw devices list

openclaw devices rotate --device <deviceId> --role operator

openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>