Complete reference for openclaw devices, managing device pairing requests, removing paired devices, and rotating or revoking device tokens with scope control.
What is Openclaw Devices?
Device management controls which clients are paired and authorized to communicate with the Gateway. When a new device initiates a pairing request, it shows up as pending until an operator explicitly approves or rejects it.
Once paired, each device holds a role-specific token with defined scopes that controls what it can do. The devices command surface lets you manage the full lifecycle: inspect requests, approve or reject them, remove stale paired devices, and rotate or revoke tokens without having to touch the Gateway config directly.
Where to Start
To see what’s pending or already paired, run devices list first, it’s the read-only overview before any mutation. For approving the most recent request without knowing its ID, devices approve with no arguments (or –latest) is the fastest path.
Note: If you are Installing OpenClaw on a VPS, remember that your local CLI will need to target the remote IP using the --url flag to manage pairing requests from your mobile or desktop clients.
If you’re working in a script or CI context, always pass –json to get structured output and use explicit –url + –token flags, the Security Notes explain exactly why omitting either when using a remote URL will fail. Token rotation output contains a live secret, handle it accordingly.
Device Management Commands
Commands for viewing, approving, rejecting, and removing device pairing entries.
| openclaw devices list Lists all pending pairing requests and already paired devices. Run this first before any approve/reject/remove operation to confirm IDs and current state. Append –json for machine-readable output suitable for scripting. |
| openclaw devices approve [requestId] Approves a pending device pairing request. The requestId is optional, if you omit it, OpenClaw automatically approves the most recent pending request. The –latest flag is the explicit equivalent of omitting the ID. Three equivalent ways to approve the most recent request: openclaw devices approve openclaw devices approve –latest openclaw devices approve <requestId> |
| openclaw devices reject <requestId> Rejects a specific pending device pairing request. Unlike approve, a requestId is required, there’s no auto-latest shortcut for rejections. |
| openclaw devices remove <deviceId> Removes a single already-paired device entry from the Gateway. The device’s tokens are invalidated on removal. Use devices list to get the correct deviceId before running this. |
| openclaw devices clear –yes Clears paired devices in bulk. Intentionally gated, the –yes flag is strictly required and cannot be omitted. Append –pending to instead clear out pending pairing requests rather than confirmed paired devices. devices clear –yes is irreversible. All paired devices will need to re-pair from scratch. Confirm your intent with devices list before running. |
Token Management Commands
Commands for rotating and revoking device tokens. Token rotation returns a live secret, treat the output accordingly.
| openclaw devices rotate –device <id> –role <role> [–scope <scope>] Rotates a device token for a specific role and allows you to optionally update its scopes. The –scope flag is repeatable, pass it multiple times to assign multiple scopes in a single rotation. Token rotation returns a new token in the output. This is sensitive and must be treated like a secret. Do not log it to a shared system, commit it to version control, or leave it visible in your terminal scroll history. |
| openclaw devices revoke –device <id> –role <role> Revokes the device token for a specific role. The device remains paired but the token for that role is invalidated immediately. The device will need to re-authenticate for that role after revocation. |
token rotation with scope update
# Rotate token and update to read + write scopes openclaw devices rotate --device <id> --role <role> --scope operator.read --scope operator.write # Revoke a specific role token openclaw devices revoke --device <id> --role <role>
Common Options
All devices commands accept standard Gateway RPC flags. These are additive to every command in §1 and §2.
| Flag | Description |
|---|---|
--url <url> | Overrides the Gateway WebSocket URL. When using this flag, you must also explicitly pass –token or –password, the CLI will not fall back to config or environment variables. See §4. |
--token <token> | Provides Gateway authentication via token. Required alongside –url when targeting a remote Gateway. |
--password <password> | Alternative to –token for Gateway authentication when password-based auth is configured. |
--timeout <ms> | Sets the RPC timeout in milliseconds. Useful when targeting a high-latency remote Gateway. |
| –json | Outputs the result in JSON format. Recommended for scripting, provides structured, parseable output for all commands including list, approve, and rotate. |
Security & Auth Notes
Three behaviors that affect auth and scope resolution, understand these before scripting or targeting a remote Gateway.
Strict URL Auth
If you pass an explicit –url, the CLI will not fall back to your config or environment variables for credentials. You must explicitly pass –token or –password, or the command will fail. This is intentional, implicit credential leakage across URL targets is a common source of auth bugs.
Required Scopes
Running these commands requires your client token to have the operator.pairing (or operator.admin) scope. If your token doesn’t have this scope, commands will be rejected at the Gateway level with a permission error. Use devices rotate –scope operator.pairing to update an existing device’s scope.
Local Loopback Fallback
If the pairing scope is unavailable on a local loopback connection and you haven’t passed an explicit –url, the list and approve commands can use a local pairing fallback mechanism. This fallback is only available on local loopback, it does not apply to remote Gateway targets.
Token Rotation Output is a Live Secret
The rotate command returns the new token in its output. This token is active immediately. Do not log it to shared systems, write it to a file with world-readable permissions, or leave it in terminal scroll history on a shared machine. Treat it the same as a database password or API key.
openclaw devices clear --yes and openclaw devices clear --yes --pending are irreversible. Run openclaw devices list and confirm the current state before executing either command in a production environment.
