Cómo gestionar tus dispositivos con openclaw devices

Gestionar el acceso de nuevos dispositivos o revocar permisos antiguos puede ser un proceso tedioso si no tienes las herramientas adecuadas. Si alguna vez has tenido problemas con tokens que no coinciden o necesitas autorizar rápidamente una nueva conexión, esta guía te ayudará a resolverlo de forma directa.

openclaw devices

Administra las solicitudes de emparejamiento de dispositivos y los tokens con alcance de dispositivo.

Comandos

openclaw devices list

Lista las solicitudes de emparejamiento pendientes y los dispositivos vinculados.

openclaw devices list
openclaw devices list --json

La salida de las solicitudes pendientes incluye el rol solicitado y los scopes, para que puedas revisar las aprobaciones antes de confirmarlas.

openclaw devices remove <deviceId>

Elimina la entrada de un dispositivo vinculado.

Cuando te autenticas con un token de dispositivo vinculado, los usuarios que no son administradores solo pueden eliminar su propia entrada de dispositivo. Eliminar cualquier otro dispositivo requiere el permiso operator.admin.

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

openclaw devices clear --yes [--pending]

Limpia dispositivos vinculados de forma masiva.

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

openclaw devices approve [requestId] [--latest]

Aprueba una solicitud de emparejamiento de dispositivo pendiente mediante el requestId exacto. Si omites el requestId o pasas --latest, OpenClaw solo muestra la solicitud pendiente seleccionada y finaliza; vuelve a ejecutar la aprobación con el ID de solicitud exacto tras verificar los detalles.

Nota: si un dispositivo reintenta el emparejamiento con detalles de autenticación distintos (rol/scopes/llave pública), OpenClaw reemplaza la entrada pendiente anterior y genera un nuevo requestId. Ejecuta openclaw devices list justo antes de la aprobación para usar el ID actual.

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

openclaw devices reject <requestId>

Rechaza una solicitud de emparejamiento de dispositivo pendiente.

openclaw devices reject <requestId>

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

Rota un token de dispositivo para un rol específico (opcionalmente actualizando los scopes). El rol de destino ya debe existir en el contrato de emparejamiento aprobado de ese dispositivo; la rotación no puede crear un nuevo rol que no haya sido aprobado. Si omites --scope, las reconexiones posteriores con el token rotado almacenado reutilizan los scopes aprobados en caché de ese token. Si pasas valores --scope explícitos, estos se convierten en el conjunto de scopes almacenados para futuras reconexiones con tokens en caché. Los usuarios de dispositivos vinculados que no sean administradores solo pueden rotar su propio token de dispositivo. Además, cualquier valor de --scope explícito debe mantenerse dentro de los propios scopes de operador de la sesión del usuario; la rotación no puede generar un token de operador con más permisos de los que el usuario ya tiene.

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

Devuelve el nuevo payload del token en formato JSON.

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

Revoca un token de dispositivo para un rol específico.

Los usuarios de dispositivos vinculados que no sean administradores solo pueden revocar su propio token de dispositivo. Revocar el token de otro dispositivo requiere operator.admin.

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

Devuelve el resultado de la revocación en formato JSON.

Opciones comunes

• --url <url>: URL del WebSocket del Gateway (por defecto es gateway.remote.url cuando está configurado).
• --token <token>: Token del Gateway (si es necesario).
• --password <password>: Contraseña del Gateway (autenticación por contraseña).
• --timeout <ms>: Tiempo de espera (timeout) de RPC.
• --json: Salida en JSON (recomendado para scripts).

Nota: cuando configuras --url, la CLI no recurre a las credenciales de configuración o del entorno. Pasa --token o --password explícitamente. La falta de credenciales explícitas es un error.

Notas

• La rotación de tokens devuelve un nuevo token (información sensible). Trátalo como un secreto.
• Estos comandos requieren el scope operator.pairing (o operator.admin).
• La rotación de tokens se mantiene dentro del conjunto de roles de emparejamiento aprobados y la base de scopes aprobada para ese dispositivo. Una entrada de token en caché huérfana no otorga un nuevo objetivo de rotación.
• Para sesiones de tokens de dispositivos vinculados, la gestión entre dispositivos es solo para administradores: remove, rotate y revoke son solo para uso propio a menos que el usuario tenga operator.admin.
• devices clear está protegido intencionadamente por el flag --yes.
• Si el scope de emparejamiento no está disponible en el loopback local (y no se pasa un --url explícito), las funciones de listar/aprobar pueden usar un sistema de respaldo (fallback) de emparejamiento local.
• devices approve requiere un ID de solicitud explícito antes de generar tokens; omitir el requestId o pasar --latest solo muestra una vista previa de la solicitud pendiente más reciente.

Lista de verificación para recuperación de desfase de tokens

Usa esto cuando la Control UI u otros clientes sigan fallando con errores AUTH_TOKEN_MISMATCH o AUTH_DEVICE_TOKEN_MISMATCH.

1. Confirma la fuente actual del token del gateway:

openclaw config get gateway.auth.token

2. Lista los dispositivos vinculados e identifica el ID del dispositivo afectado:

openclaw devices list

3. Rota el token de operador para el dispositivo afectado:

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

4. Si la rotación no es suficiente, elimina el emparejamiento antiguo y aprueba de nuevo:

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

5. Reintenta la conexión del cliente con el token o contraseña compartida actual.

Notas:

• La precedencia normal de autenticación al reconectar es: primero el token/contraseña compartido explícito, luego el deviceToken explícito, después el token de dispositivo almacenado y finalmente el token de bootstrap.
• La recuperación de confianza de AUTH_TOKEN_MISMATCH puede enviar temporalmente tanto el token compartido como el token de dispositivo almacenado juntos para un único reintento limitado.

Siguientes pasos

• Solución de problemas de autenticación del Dashboard
• Solución de problemas del Gateway

AI Setup Assistant