devices
openclaw devices
Section titled “openclaw devices”Manage device pairing requests and device-scoped tokens.
Commands
Section titled “Commands”openclaw devices list
Section titled “openclaw devices list”List pending pairing requests and paired devices.
openclaw devices listopenclaw devices list --jsonPending request output includes the requested role and scopes so approvals can be reviewed before you approve.
openclaw devices remove <deviceId>
Section titled “openclaw devices remove <deviceId>”Remove one paired device entry.
openclaw devices remove <deviceId>openclaw devices remove <deviceId> --jsonopenclaw devices clear --yes [--pending]
Section titled “openclaw devices clear --yes [--pending]”Clear paired devices in bulk.
openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --jsonopenclaw devices approve [requestId] [--latest]
Section titled “openclaw devices approve [requestId] [--latest]”Approve a pending device pairing request. If requestId is omitted, OpenClaw
automatically approves the most recent pending request.
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 approveopenclaw devices approve <requestId>openclaw devices approve --latestopenclaw devices reject <requestId>
Section titled “openclaw devices reject <requestId>”Reject a pending device pairing request.
openclaw devices reject <requestId>openclaw devices rotate --device <id> --role <role> [--scope <scope...>]
Section titled “openclaw devices rotate --device <id> --role <role> [--scope <scope...>]”Rotate a device token for a specific role (optionally updating scopes).
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.writeopenclaw devices revoke --device <id> --role <role>
Section titled “openclaw devices revoke --device <id> --role <role>”Revoke a device token for a specific role.
openclaw devices revoke --device <deviceId> --role nodeCommon options
Section titled “Common options”--url <url>: Gateway WebSocket URL (defaults togateway.remote.urlwhen configured).--token <token>: Gateway token (if required).--password <password>: Gateway password (password auth).--timeout <ms>: RPC timeout.--json: JSON output (recommended for scripting).
Note: when you set --url, the CLI does not fall back to config or environment credentials.
Pass --token or --password explicitly. Missing explicit credentials is an error.
- Token rotation returns a new token (sensitive). Treat it like a secret.
- These commands require
operator.pairing(oroperator.admin) scope. devices clearis intentionally gated by--yes.- If pairing scope is unavailable on local loopback (and no explicit
--urlis passed), list/approve can use a local pairing fallback.
Token drift recovery checklist
Section titled “Token drift recovery checklist”Use this when Control UI or other clients keep failing with AUTH_TOKEN_MISMATCH or AUTH_DEVICE_TOKEN_MISMATCH.
- Confirm current gateway token source:
openclaw config get gateway.auth.token- List paired devices and identify the affected device id:
openclaw devices list- Rotate operator token for the affected device:
openclaw devices rotate --device <deviceId> --role operator- If rotation is not enough, remove stale pairing and approve again:
openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>- Retry client connection with the current shared token/password.
Related: