Devices

text

Copy

openclaw devices

Manage device pairing requests and device-scoped tokens.

Commands

text

Copy

openclaw devices list

List pending pairing requests and paired devices.

text
Copy
openclaw devices list
openclaw devices list --json

Pending request output shows the requested access next to the device's current approved access when the device is already paired. This makes scope/role upgrades explicit instead of looking like the pairing was lost.

text

Copy

openclaw devices remove <deviceId>

Remove one paired device entry.

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

.

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

text

Copy

openclaw devices clear --yes [--pending]

Clear paired devices in bulk.

text
Copy
openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json

text

Copy

openclaw devices approve [requestId] [--latest]

Approve a pending device pairing request by exact

. If is omitted or is passed, OpenClaw only prints the selected pending request and exits; rerun approval with the exact request ID after verifying the details.

If the device is already paired and asks for broader scopes or a broader role, OpenClaw keeps the existing approval in place and creates a new pending upgrade request. Review the

vs columns in or use to preview the exact upgrade before approving it.

If the Gateway is explicitly configured with

, first-time requests from matching client IPs can be approved before they appear in this list. That policy is disabled by default and never applies to operator/browser clients or upgrade requests.

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

text

Copy

openclaw devices reject <requestId>

Reject a pending device pairing request.

text
Copy
openclaw devices reject <requestId>

text

Copy

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

Rotate a device token for a specific role (optionally updating scopes). The target role must already exist in that device's approved pairing contract; rotation cannot mint a new unapproved role. If you omit

, later reconnects with the stored rotated token reuse that token's cached approved scopes. If you pass explicit values, those become the stored scope set for future cached-token reconnects. Non-admin paired-device callers can rotate only their own device token. The target token scope set must stay within the caller session's own operator scopes; rotation cannot mint or preserve a broader operator token than the caller already has.

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

Returns rotation metadata as JSON. If the caller is rotating its own token while authenticated with that device token, the response also includes the replacement token so the client can persist it before reconnecting. Shared/admin rotations do not echo the bearer token.

text

Copy

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

Revoke a device token for a specific role.

Non-admin paired-device callers can revoke only their own device token. Revoking some other device's token requires

. The target token scope set must also fit within the caller session's own operator scopes; pairing-only callers cannot revoke admin/write operator tokens.

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

Returns the revoke result as JSON.

Common options

• text

  Copy

  --url <url>
  : Gateway WebSocket URL (defaults to
  text

  Copy

  gateway.remote.url
  when configured).
• text

  Copy

  --token <token>
  : Gateway token (if required).
• text

  Copy

  --password <password>
  : Gateway password (password auth).
• text

  Copy

  --timeout <ms>
  : RPC timeout.
• text

  Copy

  --json
  : JSON output (recommended for scripting).

Notes

• Token rotation returns a new token (sensitive). Treat it like a secret.
• These commands require
  text

  Copy

  operator.pairing
  (or
  text

  Copy

  operator.admin
  ) scope.
• text

  Copy

  gateway.nodes.pairing.autoApproveCidrs
  is an opt-in Gateway policy for fresh node device pairing only; it does not change CLI approval authority.
• Token rotation and revocation stay inside the approved pairing role set and approved scope baseline for that device. A stray cached token entry does not grant a token-management target.
• For paired-device token sessions, cross-device management is admin-only:
  text

  Copy

  remove
  ,
  text

  Copy

  rotate
  , and
  text

  Copy

  revoke
  are self-only unless the caller has
  text

  Copy

  operator.admin
  .
• Token mutation is also caller-scope contained: a pairing-only session cannot rotate or revoke a token that currently carries
  text

  Copy

  operator.admin
  or
  text

  Copy

  operator.write
  .
• text

  Copy

  devices clear
  is intentionally gated by
  text

  Copy

  --yes
  .
• If pairing scope is unavailable on local loopback (and no explicit
  text

  Copy

  --url
  is passed), list/approve can use a local pairing fallback.
• text

  Copy

  devices approve
  requires an explicit request ID before minting tokens; omitting
  text

  Copy

  requestId
  or passing
  text

  Copy

  --latest
  only previews the newest pending request.

Token drift recovery checklist

Use this when Control UI or other clients keep failing with

or .

1. Confirm current gateway token source:

bash
Copy
openclaw config get gateway.auth.token

2. List paired devices and identify the affected device id:

bash
Copy
openclaw devices list

3. Rotate operator token for the affected device:

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

4. If rotation is not enough, remove stale pairing and approve again:

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

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

Notes:

• Normal reconnect auth precedence is explicit shared token/password first, then explicit
  text

  Copy

  deviceToken
  , then stored device token, then bootstrap token.
• Trusted
  text

  Copy

  AUTH_TOKEN_MISMATCH
  recovery can temporarily send both the shared token and the stored device token together for the one bounded retry.

Related:

• Dashboard auth troubleshooting
• Gateway troubleshooting

Related

• CLI reference
• Nodes