Emparelhamento pertencente ao Gateway

No pareamento de propriedade do Gateway, o Gateway é a fonte da verdade para quais nós têm permissão para entrar. As UIs (app macOS, clientes futuros) são apenas frontends que aprovam ou rejeitam solicitações pendentes.

Importante: nós WS usam pareamento de dispositivo (função node) durante connect. node.pair.* é um armazenamento de pareamento separado e não bloqueia o handshake WS. Somente clientes que chamam explicitamente node.pair.* usam este fluxo.

Conceitos

• Solicitação pendente: um nó pediu para entrar; requer aprovação.
• Nó pareado: nó aprovado com um token de autenticação emitido.
• Transporte: o endpoint WS do Gateway encaminha solicitações, mas não decide associação. (O suporte ao bridge TCP legado foi removido.)

Como o pareamento funciona

1. Um nó se conecta ao WS do Gateway e solicita pareamento.
2. O Gateway armazena uma solicitação pendente e emite node.pair.requested.
3. Você aprova ou rejeita a solicitação (CLI ou UI).
4. Na aprovação, o Gateway emite um novo token (tokens são rotacionados ao parear novamente).
5. O nó se reconecta usando o token e agora está "pareado".

Solicitações pendentes expiram automaticamente após 5 minutos.

Fluxo de trabalho da CLI (compatível com headless)

openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw nodes remove --node <id|name|ip>openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status mostra nós pareados/conectados e suas capacidades.

Superfície de API (protocolo do Gateway)

Eventos:

• node.pair.requested - emitido quando uma nova solicitação pendente é criada.
• node.pair.resolved - emitido quando uma solicitação é aprovada/rejeitada/expirada.

Métodos:

• node.pair.request - cria ou reutiliza uma solicitação pendente.
• node.pair.list - lista nós pendentes + pareados (operator.pairing).
• node.pair.approve - aprova uma solicitação pendente (emite token).
• node.pair.reject - rejeita uma solicitação pendente.
• node.pair.remove - remove um nó pareado. Para pareamentos baseados em dispositivo, isso revoga a função node do dispositivo: modifica devices/paired.json e invalida/desconecta as sessões com função de nó desse dispositivo. Um dispositivo com funções mistas (por exemplo, ele também tem operator) mantém sua linha e perde apenas a função node; uma linha de dispositivo somente de nó é excluída. Também remove qualquer entrada legada correspondente de pareamento de nó pertencente ao gateway. Authz: operator.pairing pode remover linhas de nó não operador; um chamador com token de dispositivo revogando sua própria função de nó em um dispositivo com funções mistas também precisa de operator.admin.
• node.pair.verify - verifica { nodeId, token }.

Observações:

• node.pair.request é idempotente por nó: chamadas repetidas retornam a mesma solicitação pendente.
• Solicitações repetidas para o mesmo nó pendente também atualizam os metadados armazenados do nó e o snapshot mais recente de comandos declarados allowlisted para visibilidade do operador.
• A aprovação sempre gera um token novo; nenhum token jamais é retornado por node.pair.request.
• Os níveis de escopo de operador e as verificações no momento da aprovação estão resumidos em Escopos de operador.
• Solicitações podem incluir silent: true como dica para fluxos de aprovação automática.
• node.pair.approve usa os comandos declarados da solicitação pendente para impor escopos extras de aprovação:
  • solicitação sem comandos: operator.pairing
  • solicitação de comando não exec: operator.pairing + operator.write
  • solicitação system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Controle de comandos de nó (2026.3.31+)

Quando um nó se conecta pela primeira vez, o pareamento é solicitado automaticamente. Até que a solicitação de pareamento seja aprovada, todos os comandos de nó pendentes desse nó são filtrados e não serão executados. Depois que a confiança é estabelecida pela aprovação do pareamento, os comandos declarados do nó ficam disponíveis sujeitos à política normal de comandos.

Isso significa:

• Nós que antes dependiam apenas do pareamento de dispositivo para expor comandos agora precisam concluir o pareamento de nó.
• Comandos enfileirados antes da aprovação do pareamento são descartados, não adiados.

Limites de confiança de eventos de nó (2026.3.31+)

Resumos originados por nó e eventos de sessão relacionados são restritos à superfície confiável pretendida. Fluxos acionados por notificação ou por nó que antes dependiam de acesso mais amplo a ferramentas do host ou da sessão podem precisar de ajustes. Esse endurecimento garante que eventos de nó não possam escalar para acesso a ferramentas em nível de host além do permitido pelo limite de confiança do nó.

Atualizações duráveis de presença de nó seguem o mesmo limite de identidade. O evento node.presence.alive é aceito apenas de sessões autenticadas de dispositivo de nó e atualiza metadados de pareamento apenas quando a identidade do dispositivo/nó já está pareada. Valores client.id autodeclarados não bastam para gravar estado de visto por último.

Aprovação automática (app macOS)

O app macOS pode opcionalmente tentar uma aprovação silenciosa quando:

• a solicitação está marcada como silent, e
• o app consegue verificar uma conexão SSH com o host do gateway usando o mesmo usuário.

Se a aprovação silenciosa falhar, ele volta para o prompt normal "Aprovar/Rejeitar".

Aprovação automática de dispositivos por CIDR confiável

O pareamento de dispositivo WS para role: node permanece manual por padrão. Para redes privadas de nós em que o Gateway já confia no caminho de rede, operadores podem optar por CIDRs explícitos ou IPs exatos:

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

Limite de segurança:

• Desabilitado quando gateway.nodes.pairing.autoApproveCidrs não está definido.
• Não existe modo de aprovação automática geral para LAN ou rede privada.
• Apenas pareamento novo de dispositivo role: node sem escopos solicitados é elegível.
• Clientes de operador, navegador, Control UI e WebChat permanecem manuais.
• Atualizações de função, escopo, metadados e chave pública permanecem manuais.
• Caminhos de cabeçalho de proxy confiável por loopback no mesmo host não são elegíveis porque esse caminho pode ser falsificado por chamadores locais.

Aprovação automática de atualização de metadados

Quando um dispositivo já pareado se reconecta com apenas alterações de metadados não sensíveis (por exemplo, nome de exibição ou dicas de plataforma do cliente), o OpenClaw trata isso como um metadata-upgrade. A aprovação automática silenciosa é restrita: ela se aplica apenas a reconexões locais confiáveis não navegador que já provaram posse de credenciais locais ou compartilhadas, incluindo reconexões de app nativo no mesmo host após alterações de metadados de versão do SO. Clientes de navegador/Control UI e clientes remotos ainda usam o fluxo explícito de reaprovação. Atualizações de escopo (leitura para escrita/admin) e alterações de chave pública não são elegíveis para aprovação automática de metadata-upgrade - elas permanecem como solicitações explícitas de reaprovação.

Auxiliares de pareamento por QR

/pair qr renderiza o payload de pareamento como mídia estruturada para que clientes móveis e de navegador possam escaneá-lo diretamente.

Excluir um dispositivo também varre quaisquer solicitações pendentes obsoletas de pareamento para esse ID de dispositivo, então nodes pending não mostra linhas órfãs após uma revogação.

Localidade e cabeçalhos encaminhados

O pareamento do Gateway trata uma conexão como loopback apenas quando tanto o soquete bruto quanto qualquer evidência de proxy upstream concordam. Se uma solicitação chega por loopback, mas carrega evidência de cabeçalho Forwarded, qualquer X-Forwarded-* ou X-Real-IP, essa evidência de cabeçalho encaminhado desqualifica a alegação de localidade por loopback. O caminho de pareamento então exige aprovação explícita em vez de tratar silenciosamente a solicitação como uma conexão do mesmo host. Consulte Autenticação de proxy confiável para a regra equivalente em autenticação de operador.

Armazenamento (local, privado)

O estado de pareamento é armazenado no diretório de estado do Gateway (padrão ~/.openclaw):

• ~/.openclaw/nodes/paired.json
• ~/.openclaw/nodes/pending.json

Se você sobrescrever OPENCLAW_STATE_DIR, a pasta nodes/ se move com ele.

Observações de segurança:

• Tokens são segredos; trate paired.json como sensível.
• Rotacionar um token exige reaprovação (ou excluir a entrada do nó).

Comportamento de transporte

• O transporte é sem estado; ele não armazena associação.
• Se o Gateway estiver offline ou o pareamento estiver desabilitado, os nós não conseguem parear.
• Se o Gateway estiver em modo remoto, o pareamento ainda acontece contra o armazenamento do Gateway remoto.

Relacionado

• Pareamento de canal
• Nós
• CLI de dispositivos