Saltar para o conteúdo principal

​
Protocolo de bridge (transporte de nó legado)

O protocolo Bridge é um transporte de nó legado (TCP JSONL). Novos clientes de nó devem usar o protocolo WebSocket unificado do Gateway em vez disso. Se você está criando um operador ou cliente de nó, use o protocolo do Gateway. Nota: As builds atuais do OpenClaw não incluem mais o listener de bridge TCP; este documento é mantido para referência histórica. As chaves de configuração legadas bridge.* não fazem mais parte do esquema de configuração.

​
Por que temos ambos

  • Limite de segurança: a bridge expõe uma pequena lista de permissões em vez de toda a superfície da API do gateway.
  • Pareamento + identidade do nó: a admissão de nós é controlada pelo gateway e vinculada a um token por nó.
  • UX de descoberta: nós podem descobrir gateways via Bonjour na LAN ou conectar-se diretamente por um tailnet.
  • WS em loopback: o plano de controle WS completo permanece local, a menos que seja tunelado via SSH.

​
Transporte

  • TCP, um objeto JSON por linha (JSONL).
  • TLS opcional (quando bridge.tls.enabled é true).
  • A porta padrão legada do listener era 18790 (as builds atuais não iniciam uma bridge TCP).
Quando o TLS está habilitado, os registros TXT de descoberta incluem bridgeTls=1 além de bridgeTlsSha256 para que os nós possam fixar o certificado. Observe que os registros TXT do Bonjour/mDNS são não autenticados; os clientes não devem tratar a impressão digital anunciada como um pin autoritativo sem intenção explícita do usuário ou outra verificação fora de banda.

​
Handshake + pareamento

  1. O cliente envia hello com metadados do nó + token (se já estiver pareado).
  2. Se não estiver pareado, o gateway responde error (NOT_PAIRED/UNAUTHORIZED).
  3. O cliente envia pair-request.
  4. O gateway aguarda aprovação e, em seguida, envia pair-ok e hello-ok.
hello-ok retorna serverName e pode incluir canvasHostUrl.

​
Quadros

Cliente → Gateway:
  • req / res: RPC do gateway com escopo (chat, sessões, configuração, saúde, voicewake, skills.bins)
  • event: sinais do nó (transcrição de voz, solicitação de agente, inscrição em chat, ciclo de vida de exec)
Gateway → Cliente:
  • invoke / invoke-res: comandos do nó (canvas.*, camera.*, screen.record, location.get, sms.send)
  • event: atualizações de chat para sessões inscritas
  • ping / pong: keepalive
A aplicação da lista de permissões legada ficava em src/gateway/server-bridge.ts (removido).

​
Eventos do ciclo de vida de exec

Os nós podem emitir eventos exec.finished ou exec.denied para expor a atividade de system.run. Eles são mapeados para eventos de sistema no gateway. (Nós legados ainda podem emitir exec.started.) Campos do payload (todos opcionais, salvo indicação):
  • sessionKey (obrigatório): sessão do agente para receber o evento de sistema.
  • runId: id único de exec para agrupamento.
  • command: string de comando bruta ou formatada.
  • exitCode, timedOut, success, output: detalhes de conclusão (apenas finalizado).
  • reason: motivo da negação (apenas negado).

​
Uso de tailnet

  • Vincule a bridge a um IP de tailnet: bridge.bind: "tailnet" em ~/.openclaw/openclaw.json.
  • Os clientes se conectam via nome MagicDNS ou IP do tailnet.
  • O Bonjour não cruza redes; use host/porta manual ou DNS‑SD de área ampla quando necessário.

​
Versionamento

A bridge é atualmente v1 implícita (sem negociação de min/max). Espera-se compatibilidade retroativa; adicione um campo de versão do protocolo da bridge antes de qualquer mudança incompatível.