Gateway
Protocollo del bridge
Perché esisteva
- Confine di sicurezza: esponeva un piccolo elenco di elementi consentiti anziché l'intera superficie API del Gateway.
- Associazione + identità del Node: l'ammissione dei Node era gestita dal Gateway e vincolata a un token specifico per ciascun Node.
- Esperienza di rilevamento: i Node potevano rilevare i Gateway tramite Bonjour sulla LAN oppure connettersi direttamente tramite una tailnet.
- WS su local loopback: l'intero piano di controllo WS rimaneva locale, a meno che non venisse incanalato tramite SSH.
Trasporto
- TCP, un oggetto JSON per riga (JSONL).
- TLS facoltativo (
bridge.tls.enabled: true). - La porta predefinita del listener era
18790.
Quando TLS era abilitato, i record TXT di rilevamento includevano bridgeTls=1 e bridgeTlsSha256 come indicazione non segreta. I record TXT Bonjour/mDNS non sono autenticati; i client non potevano considerare l'impronta digitale pubblicizzata come un pin autorevole senza un'ulteriore verifica fuori banda.
Handshake e associazione
- Il client invia
hellocon i metadati del Node e il token (se già associato). - Se non è associato, il Gateway risponde con
error(NOT_PAIRED/UNAUTHORIZED). - Il client invia
pair-request. - Il Gateway attende l'approvazione, quindi invia
pair-okehello-ok.
In precedenza, hello-ok restituiva serverName; le superfici dei Plugin ospitati vengono ora annunciate tramite pluginSurfaceUrls nel protocollo attuale del Gateway (Canvas/A2UI utilizza pluginSurfaceUrls.canvas).
Frame
Dal client al Gateway:
req/res: RPC del Gateway con ambito limitato (chat, sessioni, configurazione, stato, attivazione vocale, skills.bins).event: segnali del Node (trascrizione vocale, richiesta dell'agente, sottoscrizione alla chat, ciclo di vita dell'esecuzione).
Dal Gateway al client:
invoke/invoke-res: comandi del Node (canvas.*,camera.*,screen.record,location.get,sms.send).event: aggiornamenti della chat per le sessioni sottoscritte.ping/pong: mantenimento della connessione.
L'applicazione dell'elenco di elementi consentiti si trovava in src/gateway/server-bridge.ts (rimosso).
Eventi del ciclo di vita dell'esecuzione
I Node emettevano exec.finished per rendere visibile l'attività system.run completata, mappata dal Gateway agli eventi di sistema (i Node precedenti potevano anche emettere exec.started). exec.denied contrassegnava un tentativo system.run negato come rifiuto terminale, senza accodare un evento di sistema né attivare il lavoro dell'agente.
Campi del payload (tutti facoltativi, salvo diversa indicazione):
| Campo | Note |
|---|---|
sessionKey |
Obbligatorio. Sessione dell'agente per la correlazione degli eventi e, per exec.finished, la consegna dell'evento di sistema. |
runId |
ID di esecuzione univoco per il raggruppamento. |
command |
Stringa del comando grezza o formattata. |
exitCode, timedOut, output |
Dettagli sul completamento (solo per il completamento). |
reason |
Motivo del rifiuto (solo per il rifiuto). |
Utilizzo storico della tailnet
- Associa il bridge a un indirizzo IP della tailnet:
bridge.bind: "tailnet"in~/.openclaw/openclaw.json(solo a fini storici;bridge.*non è più una configurazione valida). - I client si connettevano tramite il nome MagicDNS o l'indirizzo IP della tailnet.
- Bonjour non attraversa le reti; in alternativa erano necessari DNS-SD su rete geografica oppure host e porta configurati manualmente.
Controllo delle versioni
Il bridge utilizzava implicitamente la versione 1, senza negoziazione dei valori minimi e massimi. I client attuali dei Node e degli operatori utilizzano il protocollo WebSocket del Gateway, che negozia un intervallo di versioni del protocollo.
