Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw devices
Gerencie solicitações de pareamento de dispositivos e tokens com escopo de dispositivo.
Comandos
openclaw devices list
Liste solicitações de pareamento pendentes e dispositivos pareados.
openclaw devices remove <deviceId>
Remova uma entrada de dispositivo pareado.
Quando você está autenticado com um token de dispositivo pareado, chamadores que não são administradores podem
remover apenas a entrada de dispositivo deles mesmos. Remover outro dispositivo exige
operator.admin.
openclaw devices clear --yes [--pending]
Limpe dispositivos pareados em massa.
openclaw devices approve [requestId] [--latest]
Aprove uma solicitação pendente de pareamento de dispositivo pelo requestId exato. Se requestId
for omitido ou --latest for passado, o OpenClaw apenas imprime a solicitação pendente
selecionada e sai; execute a aprovação novamente com o ID exato da solicitação depois de verificar
os detalhes.
Se um dispositivo tentar parear novamente com detalhes de autenticação alterados (função, escopos ou chave pública), o OpenClaw substitui a entrada pendente anterior e emite um novo
requestId. Execute openclaw devices list logo antes da aprovação para usar o ID atual.Requested vs Approved em openclaw devices list
ou use openclaw devices approve --latest para pré-visualizar o upgrade exato antes de
aprová-lo.
Se o Gateway estiver configurado explicitamente com
gateway.nodes.pairing.autoApproveCidrs, solicitações iniciais de role: node de
IPs de cliente correspondentes podem ser aprovadas antes de aparecerem nesta lista. Essa política
fica desativada por padrão e nunca se aplica a clientes operador/navegador ou a solicitações
de upgrade.
openclaw devices reject <requestId>
Rejeite uma solicitação pendente de pareamento de dispositivo.
openclaw devices rotate --device <id> --role <role> [--scope <scope...>]
Rotacione um token de dispositivo para uma função específica (opcionalmente atualizando escopos).
A função de destino já deve existir no contrato de pareamento aprovado desse dispositivo;
a rotação não pode emitir uma nova função não aprovada.
Se você omitir --scope, reconexões posteriores com o token rotacionado armazenado reutilizam os
escopos aprovados em cache desse token. Se você passar valores explícitos de --scope, eles
se tornam o conjunto de escopos armazenado para futuras reconexões com token em cache.
Chamadores com dispositivo pareado que não são administradores podem rotacionar apenas o token de dispositivo
deles mesmos.
O conjunto de escopos do token de destino deve permanecer dentro dos escopos de operador da própria sessão
do chamador; a rotação não pode emitir nem preservar um token de operador mais amplo do que o
chamador já possui.
openclaw devices revoke --device <id> --role <role>
Revogue um token de dispositivo para uma função específica.
Chamadores com dispositivo pareado que não são administradores podem revogar apenas o token de dispositivo
deles mesmos.
Revogar o token de outro dispositivo exige operator.admin.
O conjunto de escopos do token de destino também deve caber dentro dos escopos de operador da própria sessão
do chamador; chamadores apenas de pareamento não podem revogar tokens de operador admin/write.
Opções comuns
--url <url>: URL WebSocket do Gateway (usagateway.remote.urlpor padrão quando configurado).--token <token>: Token do Gateway (se necessário).--password <password>: Senha do Gateway (autenticação por senha).--timeout <ms>: Tempo limite de RPC.--json: Saída JSON (recomendado para scripts).
Observações
- A rotação de token retorna um novo token (sensível). Trate-o como um segredo.
- Estes comandos exigem o escopo
operator.pairing(ouoperator.admin). Algumas aprovações também exigem que o chamador tenha os escopos de operador que o dispositivo de destino emitiria ou herdaria; consulte Escopos de operador. gateway.nodes.pairing.autoApproveCidrsé uma política opcional do Gateway apenas para pareamento inicial de dispositivo node; ela não altera a autoridade de aprovação da CLI.- A rotação e a revogação de tokens permanecem dentro do conjunto de funções de pareamento aprovado e da linha de base de escopos aprovada para esse dispositivo. Uma entrada de token em cache perdida não concede um alvo de gerenciamento de token.
- Para sessões de token de dispositivo pareado, o gerenciamento entre dispositivos é apenas para admin:
remove,rotateerevokesão apenas para o próprio dispositivo, a menos que o chamador tenhaoperator.admin. - A mutação de token também fica contida no escopo do chamador: uma sessão apenas de pareamento não pode
rotacionar ou revogar um token que atualmente carrega
operator.adminouoperator.write. devices clearé intencionalmente protegido por--yes.- Se o escopo de pareamento estiver indisponível em local loopback (e nenhum
--urlexplícito for passado), list/approve pode usar um fallback de pareamento local. devices approveexige um ID de solicitação explícito antes de emitir tokens; omitirrequestIdou passar--latestapenas pré-visualiza a solicitação pendente mais recente.
Lista de verificação para recuperação de desvio de token
Use isto quando a Control UI ou outros clientes continuarem falhando comAUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH ou AUTH_SCOPE_MISMATCH.
- Confirme a origem atual do token do gateway:
- Liste dispositivos pareados e identifique o id do dispositivo afetado:
- Rotacione o token de operador para o dispositivo afetado:
- Se a rotação não for suficiente, remova o pareamento obsoleto e aprove novamente:
- Tente novamente a conexão do cliente com o token/senha compartilhado atual.
- A precedência normal de autenticação na reconexão é primeiro token/senha compartilhado explícito, depois
deviceTokenexplícito, depois token de dispositivo armazenado e, por fim, token de bootstrap. - A recuperação confiável de
AUTH_TOKEN_MISMATCHpode enviar temporariamente tanto o token compartilhado quanto o token de dispositivo armazenado juntos na única nova tentativa limitada. AUTH_SCOPE_MISMATCHsignifica que o token de dispositivo foi reconhecido, mas não carrega o conjunto de escopos solicitado; corrija o contrato de aprovação de pareamento/escopo antes de alterar a autenticação compartilhada do gateway.