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

Gateway

Protocolo de ponte

Por que existia

  • Limite de segurança: a ponte expõe uma pequena lista de permissões em vez de toda a superfície da API do Gateway.
  • Pareamento + identidade do Node: a admissão de Node é controlada pelo Gateway e vinculada a um token por Node.
  • UX de descoberta: os nós podem descobrir gateways via Bonjour na LAN ou se conectar diretamente por uma tailnet.
  • WS de local 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 histórica padrão do listener era 18790 (as builds atuais não iniciam uma ponte TCP).

Quando TLS está habilitado, os registros TXT de descoberta incluem bridgeTls=1 mais bridgeTlsSha256 como uma dica não secreta. Observe que os registros TXT Bonjour/mDNS não sã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 Node + 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 então envia pair-ok e hello-ok.

Historicamente, hello-ok retornava serverName; as superfícies de Plugin hospedadas agora são anunciadas por meio de pluginSurfaceUrls. Canvas/A2UI usa pluginSurfaceUrls.canvas; o alias obsoleto canvasHostUrl não faz parte do protocolo refatorado.

Quadros

Cliente → Gateway:

  • req / res: RPC do Gateway com escopo (chat, sessões, configuração, integridade, voicewake, skills.bins)
  • event: sinais do Node (transcrição de voz, solicitação de agente, assinatura de chat, ciclo de vida de exec)

Gateway → Cliente:

  • invoke / invoke-res: comandos de Node (canvas.*, camera.*, screen.record, location.get, sms.send)
  • event: atualizações de chat para sessões assinadas
  • ping / pong: keepalive

A aplicação legada da lista de permissões ficava em src/gateway/server-bridge.ts (removido).

Eventos do ciclo de vida de exec

Os Nodes podem emitir eventos exec.finished ou exec.denied para expor a atividade de system.run. Eles são mapeados para eventos do sistema no Gateway. (Nodes legados ainda podem emitir exec.started.)

Campos do payload (todos opcionais, salvo indicação em contrário):

  • sessionKey (obrigatório): sessão do agente que deve receber o evento do sistema.
  • runId: id de exec único para agrupamento.
  • command: string de comando bruta ou formatada.
  • exitCode, timedOut, success, output: detalhes de conclusão (somente finished).
  • reason: motivo da negação (somente denied).

Uso histórico de tailnet

  • Vincule a ponte a um IP de tailnet: bridge.bind: "tailnet" em ~/.openclaw/openclaw.json (apenas histórico; bridge.* não é mais válido).
  • Os clientes se conectam via nome MagicDNS ou IP da tailnet.
  • Bonjour não atravessa redes; use host/porta manual ou DNS-SD de área ampla quando necessário.

Versionamento

A ponte era v1 implícita (sem negociação de mínimo/máximo). Esta seção é apenas referência histórica; os clientes atuais de Node/operador usam o WebSocket Protocolo Gateway.

Relacionado