165 lines
4.3 KiB
Markdown
165 lines
4.3 KiB
Markdown
---
|
|
summary: "CLI reference for `openclaw devices` (device pairing + token rotation/revocation)"
|
|
read_when:
|
|
- You are approving device pairing requests
|
|
- You need to rotate or revoke device tokens
|
|
title: "devices"
|
|
---
|
|
|
|
# `openclaw devices`
|
|
|
|
Manage device pairing requests and device-scoped tokens.
|
|
|
|
## Commands
|
|
|
|
### `openclaw devices list`
|
|
|
|
List pending pairing requests and paired devices.
|
|
|
|
```
|
|
openclaw devices list
|
|
openclaw devices list --json
|
|
```
|
|
|
|
### `openclaw devices remove <deviceId>`
|
|
|
|
Remove one paired device entry.
|
|
|
|
```
|
|
openclaw devices remove <deviceId>
|
|
openclaw devices remove <deviceId> --json
|
|
```
|
|
|
|
### `openclaw devices clear --yes [--pending]`
|
|
|
|
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]`
|
|
|
|
Approve a pending device pairing request. If `requestId` is omitted, OpenClaw
|
|
automatically approves the most recent pending request.
|
|
|
|
```
|
|
openclaw devices approve
|
|
openclaw devices approve <requestId>
|
|
openclaw devices approve --latest
|
|
```
|
|
|
|
### `openclaw devices reject <requestId>`
|
|
|
|
Reject a pending device pairing request.
|
|
|
|
```
|
|
openclaw devices reject <requestId>
|
|
```
|
|
|
|
### `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.write
|
|
```
|
|
|
|
### `openclaw devices revoke --device <id> --role <role>`
|
|
|
|
Revoke a device token for a specific role.
|
|
|
|
```
|
|
openclaw devices revoke --device <deviceId> --role node
|
|
```
|
|
|
|
## Common options
|
|
|
|
- `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when 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.
|
|
|
|
## Notes
|
|
|
|
- Token rotation returns a new token (sensitive). Treat it like a secret.
|
|
- These commands require `operator.pairing` (or `operator.admin`) scope.
|
|
- `devices clear` is intentionally gated by `--yes`.
|
|
- If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback.
|
|
|
|
## Paperclip / `openclaw_gateway` first-run approval
|
|
|
|
When a new Paperclip agent connects through the `openclaw_gateway` adapter for the
|
|
first time, the Gateway may require a one-time **device pairing approval** before
|
|
runs can succeed. If Paperclip shows an error like
|
|
`openclaw_gateway_pairing_required`, approve the pending device and retry.
|
|
|
|
Typical local setup:
|
|
|
|
```bash
|
|
openclaw devices approve --latest
|
|
```
|
|
|
|
If the gateway is remote or requires explicit credentials, pass them directly:
|
|
|
|
```bash
|
|
openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>
|
|
```
|
|
|
|
To avoid re-approving after restarts, keep a persistent device key in the
|
|
Paperclip adapter config instead of generating a new ephemeral identity each run:
|
|
|
|
```json
|
|
{
|
|
"adapterConfig": {
|
|
"devicePrivateKeyPem": "<your-ed25519-private-key-in-pkcs8-pem>"
|
|
}
|
|
}
|
|
```
|
|
|
|
If approval keeps failing, run `openclaw devices list` first to confirm a pending
|
|
request exists.
|
|
|
|
## Token drift recovery checklist
|
|
|
|
Use this when Control UI or other clients keep failing with `AUTH_TOKEN_MISMATCH` or `AUTH_DEVICE_TOKEN_MISMATCH`.
|
|
|
|
1. Confirm current gateway token source:
|
|
|
|
```bash
|
|
openclaw config get gateway.auth.token
|
|
```
|
|
|
|
2. List paired devices and identify the affected device id:
|
|
|
|
```bash
|
|
openclaw devices list
|
|
```
|
|
|
|
3. Rotate operator token for the affected device:
|
|
|
|
```bash
|
|
openclaw devices rotate --device <deviceId> --role operator
|
|
```
|
|
|
|
4. If rotation is not enough, remove stale pairing and approve again:
|
|
|
|
```bash
|
|
openclaw devices remove <deviceId>
|
|
openclaw devices list
|
|
openclaw devices approve <requestId>
|
|
```
|
|
|
|
5. Retry client connection with the current shared token/password.
|
|
|
|
Related:
|
|
|
|
- [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)
|
|
- [Gateway troubleshooting](/gateway/troubleshooting#dashboard-control-ui-connectivity)
|