openclaw devices CLI Reference

`openclaw devices`

Handle device pairing requests and tokens scoped to individual devices.

Common options

--url <url>: Gateway WebSocket URL (defaults to gateway.remote.url when set up)
--token <token>: Gateway token (if one is needed)
--password <password>: Gateway password (password-based authentication)
--timeout <ms>: RPC timeout
--json: JSON output (recommended when scripting)

Warning

After you set --url, the CLI will not fall back to credentials from the config or environment. You must explicitly provide --token or --password, or the command will fail.

Commands

`openclaw devices list`

Show all devices that are paired and any pending pairing requests.

openclaw devices list
openclaw devices list --json

For a pending request on a device that is already paired, the output displays the requested access alongside the device's current approved access. This makes scope or role upgrades visible rather than appearing as a lost pairing.

The display name for a paired device follows this priority order: the operator label (operatorLabel from devices rename), then the client's displayName, then clientId, then deviceId.

`openclaw devices approve [requestId] [--latest]`

Approve a specific pending pairing request using its exact requestId. If you omit requestId or supply --latest, the command only previews the most recent pending request and exits with code 1. Rerun the command with the exact request ID to approve it.

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

Note

When a device retries pairing with different authentication details (role, scopes, or public key), OpenClaw replaces the previous pending entry with a new requestId. Run openclaw devices list just before approving to get the current id.

Approval behavior:

If the device is already paired and requests broader scopes or a different role, OpenClaw keeps the existing approval and creates a new pending upgrade request. Compare Requested against Approved in openclaw devices list, or preview with --latest, before you approve.
Approving a node role or any other non-operator role requires operator.admin. For operator-to-device approvals, operator.pairing is sufficient, but only when the requested operator scopes are within the caller's own scopes. Refer to Operator scopes.
When gateway.nodes.pairing.autoApproveCidrs is configured, first-time role: node requests from matching client IPs can be auto-approved before they appear in this list. This feature is disabled by default and never applies to operator or browser clients, nor to upgrade requests.
gateway.nodes.pairing.sshVerify (enabled by default) auto-approves first-time role: node requests when the gateway verifies the device key over SSH against the node host. As a result, requests may become approved shortly after they appear. Set sshVerify: false to disable SSH verification. This setting is independent of autoApproveCidrs, so also unset that for fully manual pairing.

`openclaw devices reject <requestId>`

Deny a pending device pairing request.

openclaw devices reject <requestId>

`openclaw devices remove <deviceId>`

Delete one paired device entry.

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

A caller authenticated with a paired device token can only remove its own device entry. To remove another device, operator.admin is required.

`openclaw devices rename --device <id> --name <label>`

Attach an operator label to a paired device. Labels are state owned by the operator side: they persist through pairing repairs and role re-approvals, and they do not alter the stable deviceId.

openclaw devices rename --device <deviceId> --name "Kitchen Mac"
openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json

--name is required, trimmed, non-empty, and limited to 64 characters.
Display surfaces (such as the CLI list and Control UI inventory) show the operator label in preference to the client-reported display name.
A non-admin paired-device caller can only rename its own device. Renaming another device requires operator.admin.

`openclaw devices clear --yes [--pending]`

Remove all paired devices at once. This action is protected by --yes.

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

--pending also cancels every pending pairing request.

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

Replace a device token for a role, optionally updating its scopes at the same time.

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

The target role must already exist in that device's approved pairing contract. Rotation cannot create a new role that was not previously approved.
Omitting --scope means the stored token's cached approved scopes will be reused on later reconnects. Providing explicit --scope values replaces the stored scope set for future reconnects that use the cached token.
A non-admin paired-device caller can only rotate its own device token, and the target scope set must be within the caller's own operator scopes. Rotation cannot create or keep a token broader than what the caller already has.

Returns rotation metadata as JSON. If the caller rotates its own token while authenticated with that device token, the response includes the replacement token so the client can save it before reconnecting. Shared or admin rotations never echo the bearer token.

`openclaw devices revoke --device <id> --role <role>`

Remove a device token for a role.

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

A paired device caller without admin rights can revoke only its own device token. To revoke a token belonging to another device, operator.admin is required. Additionally, the target scope set must be within the caller's own operator scopes; callers limited to pairing cannot revoke admin or write operator tokens.

Notes

These commands demand operator.pairing (or operator.admin) scope. Non-operator device roles always need operator.admin; refer to Operator scopes.
Token rotation and revocation remain confined to the device's approved pairing role set and scope baseline. A stale cached token entry does not create a valid token-management target.
For token sessions on paired devices, cross-device operations (remove, rename, rotate, revoke) are restricted to self-only unless the caller holds operator.admin.
A token rotation produces a new sensitive token, so handle it as a secret.
When pairing scope is absent on local loopback and no explicit --url is provided, list/approve may fall back to local pairing state.

Token drift recovery checklist

Apply this when Control UI or other clients repeatedly encounter AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH, or AUTH_SCOPE_MISMATCH.

Verify the current gateway token source:
```
openclaw config get gateway.auth.token
```
List paired devices and locate the affected device id:
```
openclaw devices list
```

Rotate the operator token for the affected device:

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

If rotation is insufficient, remove the stale pairing and reapprove:

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

Retry the client connection using the current shared token or password.

Notes:

Normal reconnect authentication precedence: explicit shared token or password first, then explicit deviceToken, then the stored device token, and finally the bootstrap token.
Trusted AUTH_TOKEN_MISMATCH recovery can temporarily send both the shared token and the stored device token together for a single bounded retry.
AUTH_SCOPE_MISMATCH indicates the device token was recognized but does not include the requested scope set; correct the pairing or scope approval contract before altering the shared gateway authentication.

Paperclip / `openclaw_gateway` first-run approval

Paperclip agents connecting via the openclaw_gateway adapter undergo the same first-run device pairing approval as any other new client. When Paperclip reports openclaw_gateway_pairing_required, approve the pending device and retry.

openclaw devices approve --latest

The preview displays the exact openclaw devices approve <requestId> command; check the details, then rerun that command with the request ID to approve it. For a remote gateway or explicit credentials, pass the same options during both preview and approval:

openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>

To avoid needing reapproval after every restart, set up a persistent adapterConfig.devicePrivateKeyPem in Paperclip rather than letting it create a new ephemeral device identity each time:

{
  "adapterConfig": {
    "devicePrivateKeyPem": "<ed25519-private-key-pkcs8-pem>"
  }
}

If approval continues to fail, run openclaw devices list first to confirm that a pending request exists.