English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

CLI commands

Dispositivos

openclaw devices

Gerencie solicitações de emparelhamento de dispositivos e tokens com escopo por dispositivo.

Comandos

openclaw devices list

Liste solicitações de emparelhamento pendentes e dispositivos emparelhados.

openclaw devices list
openclaw devices list --json

A saída de solicitação pendente mostra o acesso solicitado ao lado do acesso atual aprovado do dispositivo quando o dispositivo já está emparelhado. Isso torna upgrades de escopo/função explícitos, em vez de parecer que o emparelhamento foi perdido.

openclaw devices remove <deviceId>

Remova uma entrada de dispositivo emparelhado.

Quando você está autenticado com um token de dispositivo emparelhado, chamadores não administradores podem remover apenas a entrada do próprio dispositivo. Remover outro dispositivo exige operator.admin.

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

openclaw devices clear --yes [--pending]

Limpe dispositivos emparelhados em massa.

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

openclaw devices approve [requestId] [--latest]

Aprove uma solicitação pendente de emparelhamento 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 o dispositivo já estiver emparelhado e solicitar escopos mais amplos ou uma função mais ampla, o OpenClaw mantém a aprovação existente e cria uma nova solicitação pendente de upgrade. Revise as colunas Requested versus 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 explicitamente configurado com gateway.nodes.pairing.autoApproveCidrs, solicitações de primeira vez com role: node vindas de IPs de cliente correspondentes podem ser aprovadas antes de aparecerem nesta lista. Essa política é desabilitada por padrão e nunca se aplica a clientes operador/navegador nem a solicitações de upgrade.

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

openclaw devices reject <requestId>

Rejeite uma solicitação pendente de emparelhamento de dispositivo.

openclaw devices reject <requestId>

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 emparelhamento 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 de dispositivos emparelhados não administradores podem rotacionar apenas o token do próprio dispositivo. 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 rotate --device <deviceId> --role operator --scope operator.read --scope operator.write

Retorna metadados de rotação como JSON. Se o chamador estiver rotacionando o próprio token enquanto autenticado com esse token de dispositivo, a resposta também inclui o token de substituição para que o cliente possa persistí-lo antes de reconectar. Rotações compartilhadas/de administrador não ecoam o token bearer.

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

Revogue um token de dispositivo para uma função específica.

Chamadores de dispositivos emparelhados não administradores podem revogar apenas o token do próprio dispositivo. 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 com emparelhamento não podem revogar tokens de operador de administrador/gravação.

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

Retorna o resultado da revogação como JSON.

Opções comuns

  • --url <url>: URL WebSocket do Gateway (usa gateway.remote.url por padrão quando configurado).
  • --token <token>: token do Gateway (se exigido).
  • --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 (ou operator.admin). Algumas aprovações também exigem que o chamador possua os escopos de operador que o dispositivo de destino emitiria ou herdaria; consulte Escopos de operador.
  • gateway.nodes.pairing.autoApproveCidrs é uma política opt-in do Gateway apenas para emparelhamento de dispositivo Node novo; 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 emparelhamento aprovado e da linha de base de escopos aprovada para esse dispositivo. Uma entrada perdida de token em cache não concede um destino de gerenciamento de token.
  • Para sessões de token de dispositivo emparelhado, o gerenciamento entre dispositivos é exclusivo de administradores: remove, rotate e revoke são apenas para o próprio dispositivo, a menos que o chamador tenha operator.admin.
  • A mutação de token também fica contida no escopo do chamador: uma sessão apenas com emparelhamento não pode rotacionar nem revogar um token que atualmente carrega operator.admin ou operator.write.
  • devices clear é intencionalmente protegido por --yes.
  • Se o escopo de emparelhamento estiver indisponível em local loopback (e nenhum --url explícito for passado), list/approve pode usar um fallback local de emparelhamento.
  • devices approve exige um ID de solicitação explícito antes de emitir tokens; omitir requestId ou passar --latest apenas pré-visualiza a solicitação pendente mais recente.

Lista de verificação de recuperação de divergência de token

Use isto quando a Control UI ou outros clientes continuarem falhando com AUTH_TOKEN_MISMATCH ou AUTH_DEVICE_TOKEN_MISMATCH.

  1. Confirme a fonte atual do token do Gateway:
openclaw config get gateway.auth.token
  1. Liste os dispositivos emparelhados e identifique o id do dispositivo afetado:
openclaw devices list
  1. Rotacione o token de operador para o dispositivo afetado:
openclaw devices rotate --device <deviceId> --role operator
  1. Se a rotação não for suficiente, remova o emparelhamento obsoleto e aprove novamente:
openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>
  1. Tente novamente a conexão do cliente com o token/senha compartilhado atual.

Observações:

  • A precedência normal de autenticação na reconexão é token/senha compartilhado explícito primeiro, depois deviceToken explícito, depois token de dispositivo armazenado, depois token de bootstrap.
  • A recuperação confiável de AUTH_TOKEN_MISMATCH pode enviar temporariamente tanto o token compartilhado quanto o token de dispositivo armazenado juntos para a única nova tentativa delimitada.

Relacionado:

Relacionado