openclaw devices

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

Opções comuns

• --url <url>: URL do WebSocket do Gateway (usa gateway.remote.url por 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 da RPC
• --json: saída JSON (recomendado para scripts)

Comandos

openclaw devices list

Liste as solicitações de pareamento pendentes e os dispositivos pareados.

openclaw devices listopenclaw devices list --json

Para uma solicitação pendente em um dispositivo já pareado, a saída mostra o acesso solicitado ao lado do acesso atualmente aprovado para o dispositivo, para que ampliações de escopo ou função fiquem visíveis em vez de parecerem um pareamento perdido.

Os nomes de exibição dos dispositivos pareados usam esta ordem de precedência: rótulo do operador (operatorLabel de devices rename), depois displayName do cliente, depois clientId e, por fim, deviceId.

openclaw devices approve [requestId] [--latest]

Aprove uma solicitação de pareamento pendente pelo requestId exato. Omitir requestId ou passar --latest apenas exibe uma prévia da solicitação pendente mais recente e encerra (código 1); execute novamente com o ID exato da solicitação para aprová-la.

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

Comportamento da aprovação:

• Se o dispositivo já estiver pareado e solicitar escopos mais amplos ou outra função, o OpenClaw manterá a aprovação existente e criará uma nova solicitação de ampliação pendente. Compare Requested com Approved em openclaw devices list ou visualize uma prévia com --latest antes de aprovar.
• Aprovar uma função node ou outra função que não seja de operador exige operator.admin. operator.pairing é suficiente para aprovações de dispositivos de operador, mas somente quando os escopos de operador solicitados permanecem dentro dos escopos do próprio chamador. Consulte Escopos do operador.
• Se gateway.nodes.pairing.autoApproveCidrs estiver configurado, solicitações iniciais com role: node provenientes de IPs de cliente correspondentes poderão ser aprovadas automaticamente antes de aparecerem nesta lista. Esse recurso é desativado por padrão e nunca se aplica a clientes operadores/navegadores nem a solicitações de ampliação.
• gateway.nodes.pairing.sshVerify (ativado por padrão) aprova automaticamente solicitações iniciais com role: node quando o Gateway verifica a chave do dispositivo por SSH no host do Node. Portanto, as solicitações podem aparecer como aprovadas logo após serem exibidas. Defina sshVerify: false para desativar a verificação por SSH; isso é independente de autoApproveCidrs, portanto desative essa opção também para exigir pareamento exclusivamente manual.

openclaw devices reject <requestId>

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

openclaw devices reject <requestId>

openclaw devices remove <deviceId>

Remova uma entrada de dispositivo pareado.

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

Um chamador autenticado com um token de dispositivo pareado pode remover apenas a entrada de seu próprio dispositivo. A remoção de outro dispositivo exige operator.admin.

openclaw devices rename --device <id> --name <label>

Atribua um rótulo de operador a um dispositivo pareado. Os rótulos são um estado mantido pelo proprietário: eles persistem após reparos de pareamento e novas aprovações de função e não alteram o deviceId estável.

openclaw devices rename --device <deviceId> --name "Kitchen Mac"openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json

• --name é obrigatório, tem espaços nas extremidades removidos, não pode estar vazio e é limitado a 64 caracteres.
• As superfícies de exibição (lista da CLI e inventário da interface de controle) priorizam o rótulo do operador em relação ao nome de exibição informado pelo cliente.
• Um chamador de dispositivo pareado sem privilégios administrativos pode renomear apenas seu próprio dispositivo. Renomear outro dispositivo exige operator.admin.

openclaw devices clear --yes [--pending]

Remova dispositivos pareados em massa. Exige --yes.

openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --json

--pending também rejeita todas as solicitações de pareamento pendentes.

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

Alterne o token de um dispositivo para uma função, atualizando opcionalmente seus escopos.

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

• A função de destino já deve existir no contrato de pareamento aprovado desse dispositivo; a alternância não pode emitir uma nova função não aprovada.
• Omitir --scope reutiliza os escopos aprovados armazenados em cache para o token nas reconexões posteriores. Passar valores --scope explícitos substitui o conjunto de escopos armazenado para futuras reconexões com token em cache.
• Um chamador de dispositivo pareado sem privilégios administrativos pode alternar apenas o token de seu próprio dispositivo, e o conjunto de escopos de destino deve permanecer dentro dos escopos de operador do próprio chamador; a alternância não pode emitir nem preservar um token mais amplo do que aquele que o chamador já possui.

Retorna os metadados da alternância como JSON. Se o chamador alternar seu próprio token enquanto estiver autenticado com esse token de dispositivo, a resposta incluirá o token substituto para que o cliente possa armazená-lo antes da reconexão. Alternâncias compartilhadas/administrativas nunca retornam o token de portador.

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

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

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

Um chamador de dispositivo pareado sem privilégios administrativos pode revogar apenas o token de seu próprio dispositivo. Revogar o token de outro dispositivo exige operator.admin. O conjunto de escopos de destino também deve estar contido nos escopos de operador do próprio chamador; chamadores com apenas permissão de pareamento não podem revogar tokens de operador com privilégios administrativos/de gravação.

Observações

• Estes comandos exigem o escopo operator.pairing (ou operator.admin). Funções de dispositivo que não sejam de operador sempre exigem operator.admin; consulte Escopos do operador.
• A alternância e a revogação de tokens permanecem dentro do conjunto de funções de pareamento aprovado do dispositivo e de sua linha de base de escopos. Uma entrada isolada de token em cache não concede um destino para gerenciamento de tokens.
• Em sessões com token de dispositivo pareado, o gerenciamento entre dispositivos (remove, rename, rotate, revoke) é restrito ao próprio dispositivo, a menos que o chamador tenha operator.admin.
• A alternância de token retorna um novo token (sensível) — trate-o como um segredo.
• Se o escopo de pareamento não estiver disponível no local loopback e nenhum --url explícito for passado, list/approve poderão recorrer ao estado de pareamento local.

Lista de verificação para recuperação de divergência de tokens

Use esta lista quando a interface de controle ou outros clientes continuarem falhando com AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH ou AUTH_SCOPE_MISMATCH.

1. Confirme a origem atual do token do Gateway:

   openclaw config get gateway.auth.token

2. Liste os dispositivos pareados e identifique o ID do dispositivo afetado:

   openclaw devices list

3. Alterne o token de operador do dispositivo afetado:

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

4. Se a alternância não for suficiente, remova o pareamento obsoleto e aprove novamente:

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

5. Tente novamente a conexão do cliente com o token/senha compartilhado atual.

Observações:

• Precedência normal de autenticação na reconexão: primeiro token/senha compartilhado explícito, depois deviceToken explícito, depois token de dispositivo armazenado e, por fim, token de inicialização.
• A recuperação confiável de AUTH_TOKEN_MISMATCH pode enviar temporariamente o token compartilhado e o token de dispositivo armazenado juntos em uma única nova tentativa limitada.
• AUTH_SCOPE_MISMATCH significa que o token do dispositivo foi reconhecido, mas não contém o conjunto de escopos solicitado; corrija o contrato de aprovação de pareamento/escopos antes de alterar a autenticação compartilhada do Gateway.

Relacionado:

• Solução de problemas de autenticação do painel
• Solução de problemas do Gateway

Aprovação na primeira execução do Paperclip / openclaw_gateway

Os agentes do Paperclip que se conectam pelo adaptador openclaw_gateway passam pela mesma aprovação de pareamento de dispositivo na primeira execução que qualquer outro cliente novo. Se o Paperclip informar openclaw_gateway_pairing_required, aprove o dispositivo pendente e tente novamente.

openclaw devices approve --latest

A prévia mostra o comando openclaw devices approve <requestId> exato; verifique os detalhes e execute novamente esse comando com o ID da solicitação para aprová-la. Para um Gateway remoto ou credenciais explícitas, passe as mesmas opções ao visualizar a prévia e aprovar:

openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>

Para evitar novas aprovações após cada reinicialização, configure um adapterConfig.devicePrivateKeyPem persistente no Paperclip em vez de permitir que ele gere uma nova identidade efêmera de dispositivo a cada execução:

{  "adapterConfig": {    "devicePrivateKeyPem": "<ed25519-private-key-pkcs8-pem>"  }}

Se a aprovação continuar falhando, execute primeiro openclaw devices list para confirmar que existe uma solicitação pendente.

Relacionado

• Referência da CLI
• Nodes