OpenClaw Devices CLI Reference

`openclaw devices`

Pairing requests for devices and tokens scoped to devices are managed here.

Common options

--url <url>: Gateway WebSocket URL, which defaults to gateway.remote.url when configured
--token <token>: Gateway token, used when required
--password <password>: Gateway password, for password-based authentication
--timeout <ms>: RPC timeout setting
--json: JSON output, recommended for scripting

Warning

Once --url is set, the CLI skips falling back to credentials from config or environment variables. You must provide --token or --password explicitly, otherwise the command fails.

Commands

`openclaw devices list`

Show devices that are paired and pairing requests still awaiting action.

openclaw devices list
openclaw devices list --json

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

Display names for paired devices follow this priority: operator label (operatorLabel from devices rename), then client displayName, then clientId, then deviceId.

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

Approve a pending pairing request by providing the exact requestId. If requestId is left out, or --latest is passed, only the newest pending request is previewed and the command exits with code 1. Rerun with the precise request ID to perform the approval.

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

Note

When a device retries pairing with altered auth details (role, scopes, or public key), OpenClaw replaces the earlier pending entry with a fresh requestId. Execute openclaw devices list right before approving to obtain the current id.

What happens on approval:

For a device already paired that asks for wider scopes or a different role, OpenClaw preserves the existing approval and adds a new pending upgrade request. Check Requested against Approved in openclaw devices list, or use --latest to preview, before you approve.
Approving a node role or any other non-operator role calls for operator.admin. Operator-device approvals only need operator.pairing, and only when the requested operator scopes fall within the caller's own scopes. Refer to Operator scopes.
With gateway.nodes.pairing.autoApproveCidrs configured, first-time role: node requests from matching client IPs can be auto-approved before showing up in this list. This is off 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 to the node host. As a result, requests can become approved shortly after they appear. Set sshVerify: false to turn off SSH verification. This is separate from autoApproveCidrs, so that must also be unset for pairing to be manual only.

`openclaw devices reject <requestId>`

Turn down a pending device pairing request.

openclaw devices reject <requestId>

`openclaw devices remove <deviceId>`

Delete a single paired device entry.

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

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

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

Give a paired device an operator label. Labels are owner-side state: they persist through pairing repairs and role re-approvals, and they leave the stable deviceId untouched.

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

--name is mandatory, gets trimmed, must be non-empty, and is limited to 64 characters.
Display surfaces (CLI list, Control UI inventory) show the operator label instead of the client-reported display name.
A non-admin paired-device caller can rename only its own device. Renaming another device requires operator.admin.

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

Clear devices in bulk. This is gated by --yes.

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

--pending also rejects every pending pairing request.

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

Rotate a device token for a role, with optional scope updates.

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

The target role must already be part of that device's approved pairing contract; rotation cannot create a new unapproved role.
Leaving out --scope means the stored token's cached approved scopes are reused on later reconnects. Supplying explicit --scope values replaces the stored scope set for future cached-token reconnects.
A non-admin paired-device caller can rotate only its own device token, and the target scope set must fit within the caller's own operator scopes. Rotation cannot mint or preserve a token broader than what the caller already holds.

Rotation metadata comes back 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 persist it before reconnecting. Shared or admin rotations never echo the bearer token.

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

Revoke a device token for a role.

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

A non-admin paired-device caller can revoke only its own device token. Revoking another device's token requires operator.admin. The target scope set must also fit within the caller's own operator scopes; pairing-only callers cannot revoke admin/write operator tokens.

Notes

These commands require operator.pairing (or operator.admin) scope. Non-operator device roles always require operator.admin; see Operator scopes.
Token rotation and revocation stay inside the device's approved pairing role set and scope baseline. A stray cached token entry does not grant a token-management target.
For paired-device token sessions, cross-device management (remove, rename, rotate, revoke) is self-only unless the caller has operator.admin.
Token rotation returns a new token (sensitive), treat it like a secret.
If pairing scope is unavailable on local loopback and no explicit --url is passed, list/approve can fall back to local pairing state.

Token drift recovery checklist

Use this when Control UI or other clients keep failing with AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH, or AUTH_SCOPE_MISMATCH.

Confirm current gateway token source:
```
openclaw gateway auth-token --show
```
Run the command in an interactive terminal on the Gateway host and treat its output as a secret.
List paired devices and identify 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 not enough, remove the stale pairing and approve again:

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

Retry the client connection with the current shared token/password.

Notes:

Normal reconnect auth precedence: explicit shared token/password first, then explicit deviceToken, then stored device token, then bootstrap token.
Trusted AUTH_TOKEN_MISMATCH recovery can temporarily send both the shared token and the stored device token together for one bounded retry.
AUTH_SCOPE_MISMATCH means the device token was recognized but does not carry the requested scope set; fix the pairing/scope approval contract before changing shared gateway auth.

Paperclip / `openclaw_gateway` first-run approval

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

openclaw devices approve --latest

The preview prints the exact openclaw devices approve <requestId> command; verify the details, then rerun that command with the request ID to approve it. For a remote gateway or explicit credentials, pass the same options while previewing and approving:

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

To avoid re-approving after every restart, configure a persistent adapterConfig.devicePrivateKeyPem in Paperclip instead of letting it generate a new ephemeral device identity each run:

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

If approval keeps failing, run openclaw devices list first to confirm a pending request exists.