> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pareamento Gateway-Owned

# Pareamento de propriedade do Gateway (Opção B)

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

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

## Conceitos

* **Solicitação pendente**: um nó solicitou entrada; 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
  a associação. (O suporte legado à ponte TCP está obsoleto/removido.) (Suporte à ponte TCP legada está obsoleto/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. Voce aprova ou rejeita a solicitação (CLI ou UI).
4. Na aprovação, o Gateway emite um **novo token** (tokens são rotacionados em novo pareamento).
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 (amigável para headless)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
```

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

## Superfície da 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.
* `node.pair.approve` — aprova uma solicitação pendente (emite token).
* `node.pair.reject` — rejeita uma solicitação pendente.
* `node.pair.verify` — verifica `{ nodeId, token }`.

Notas:

* `node.pair.request` é idempotente por nó: chamadas repetidas retornam a mesma
  solicitação pendente.
* A aprovação **sempre** gera um token novo; nenhum token é retornado de
  `node.pair.request`.
* As solicitações podem incluir `silent: true` como uma dica para fluxos de aprovação automática.

## Aprovação automática (app do macOS)

O app do 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 ao prompt normal de “Aprovar/Rejeitar”.

## 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 voce substituir `OPENCLAW_STATE_DIR`, a pasta `nodes/` é movida junto com ele.

Notas de segurança:

* Tokens são segredos; trate `paired.json` como sensível.
* Rotacionar um token exige nova aprovação (ou a exclusão da entrada do nó).

## Comportamento do transporte

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