Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Il bridge TCP è stato rimosso. Le build attuali di OpenClaw non distribuiscono il listener del bridge e le chiavi di configurazione bridge.* non sono più nello schema. Questa pagina è conservata solo come riferimento storico. Usa il Protocollo Gateway per tutti i client nodo/operatore.

​
Perché esisteva

  • Confine di sicurezza: il bridge espone una piccola lista consentita invece dell’intera superficie API del Gateway.
  • Abbinamento + identità del nodo: l’ammissione dei nodi è gestita dal Gateway ed è legata a un token per nodo.
  • UX di discovery: i nodi possono individuare i Gateway tramite Bonjour su LAN, oppure connettersi direttamente su una tailnet.
  • WS in loopback: il piano di controllo WS completo resta locale a meno che non venga instradato tramite tunnel SSH.

​
Trasporto

  • TCP, un oggetto JSON per riga (JSONL).
  • TLS opzionale (quando bridge.tls.enabled è true).
  • La porta listener predefinita storica era 18790 (le build attuali non avviano un bridge TCP).
Quando TLS è abilitato, i record TXT di discovery includono bridgeTls=1 più bridgeTlsSha256 come suggerimento non segreto. Nota che i record TXT Bonjour/mDNS non sono autenticati; i client non devono trattare l’impronta pubblicizzata come un pin autorevole senza un’intenzione esplicita dell’utente o un’altra verifica fuori banda.

​
Handshake + abbinamento

  1. Il client invia hello con metadati del nodo + token (se già abbinato).
  2. Se non è abbinato, il Gateway risponde error (NOT_PAIRED/UNAUTHORIZED).
  3. Il client invia pair-request.
  4. Il Gateway attende l’approvazione, poi invia pair-ok e hello-ok.
Storicamente, hello-ok restituiva serverName; le superfici dei Plugin ospitati sono ora pubblicizzate tramite pluginSurfaceUrls. Canvas/A2UI usa pluginSurfaceUrls.canvas; l’alias deprecato canvasHostUrl non fa parte del protocollo rifattorizzato.

​
Frame

Client → Gateway:
  • req / res: RPC del Gateway con ambito (chat, sessions, config, health, voicewake, skills.bins)
  • event: segnali del nodo (trascrizione vocale, richiesta agente, iscrizione alla chat, ciclo di vita exec)
Gateway → Client:
  • invoke / invoke-res: comandi del nodo (canvas.*, camera.*, screen.record, location.get, sms.send)
  • event: aggiornamenti chat per le sessioni sottoscritte
  • ping / pong: keepalive
L’applicazione legacy della lista consentita si trovava in src/gateway/server-bridge.ts (rimosso).

​
Eventi del ciclo di vita exec

I nodi possono emettere eventi exec.finished o exec.denied per esporre l’attività system.run. Questi vengono mappati a eventi di sistema nel Gateway. (I nodi legacy possono ancora emettere exec.started.) Campi del payload (tutti opzionali salvo diversa indicazione):
  • sessionKey (obbligatorio): sessione agente che deve ricevere l’evento di sistema.
  • runId: ID exec univoco per il raggruppamento.
  • command: stringa del comando grezza o formattata.
  • exitCode, timedOut, success, output: dettagli di completamento (solo finished).
  • reason: motivo del rifiuto (solo denied).

​
Uso storico della tailnet

  • Associa il bridge a un IP della tailnet: bridge.bind: "tailnet" in ~/.openclaw/openclaw.json (solo storico; bridge.* non è più valido).
  • I client si connettono tramite nome MagicDNS o IP della tailnet.
  • Bonjour non attraversa le reti; usa host/porta manuali o DNS-SD wide-area quando necessario.

​
Versionamento

Il bridge era v1 implicito (nessuna negoziazione min/max). Questa sezione è solo un riferimento storico; i client nodo/operatore attuali usano il Protocollo Gateway WebSocket.

​
Correlati