Architettura del Gateway

# Panoramica

• Un singolo Gateway a lunga durata gestisce tutte le superfici di messaggistica (WhatsApp tramite Baileys, Telegram tramite grammY, Slack, Discord, Signal, iMessage, WebChat).
• I client del piano di controllo (app macOS, CLI, UI web, automazioni) si connettono al Gateway tramite WebSocket sull'host di bind configurato (predefinito 127.0.0.1:18789).
• Anche i Node (macOS/iOS/Android/headless) si connettono tramite WebSocket, ma dichiarano role: node con capability/comandi espliciti.
• Un Gateway per host; è l'unico punto che apre una sessione WhatsApp.
• Il canvas host è servito dal server HTTP del Gateway sotto:
  • /__openclaw__/canvas/ (HTML/CSS/JS modificabili dall'agente)
  • /__openclaw__/a2ui/ (host A2UI) Usa la stessa porta del Gateway (predefinita 18789).

# Componenti e flussi

# Gateway (demone)

• Mantiene le connessioni dei provider.
• Espone un'API WS tipizzata (richieste, risposte, eventi push del server).
• Convalida i frame in ingresso rispetto a JSON Schema.
• Emette eventi come agent, chat, presence, health, heartbeat, cron.

# Client (app Mac / CLI / amministrazione web)

• Una connessione WS per client.
• Inviano richieste (health, status, send, agent, system-presence).
• Si sottoscrivono agli eventi (tick, agent, presence, shutdown).

# Node (macOS / iOS / Android / headless)

• Si connettono allo stesso server WS con role: node.
• Forniscono un'identità del dispositivo in connect; l'abbinamento è basato sul dispositivo (ruolo node) e l'approvazione risiede nello store di abbinamento dei dispositivi.
• Espongono comandi come canvas.*, camera.*, screen.record, location.get.

Dettagli del protocollo:

• Protocollo Gateway

# WebChat

• UI statica che usa l'API WS del Gateway per la cronologia chat e gli invii.
• Nelle configurazioni remote, si connette tramite lo stesso tunnel SSH/Tailscale degli altri client.

# Ciclo di vita della connessione (singolo client)

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: or res error + close
    Note left of Client: payload=hello-ok
snapshot: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent
ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent
(streaming)
    Gateway-->>Client: res:agent
final {runId, status, summary}

# Protocollo wire (riepilogo)

• Trasporto: WebSocket, frame di testo con payload JSON.
• Il primo frame deve essere connect.
• Dopo l'handshake:
  • Richieste: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • Eventi: {type:"event", event, payload, seq?, stateVersion?}
• hello-ok.features.methods / events sono metadati di discovery, non un dump generato di ogni route helper richiamabile.
• L'autenticazione con segreto condiviso usa connect.params.auth.token oppure connect.params.auth.password, in base alla modalità di autenticazione del gateway configurata.
• Le modalità che trasportano identità, come Tailscale Serve (gateway.auth.allowTailscale: true) o gateway.auth.mode: "trusted-proxy" non local loopback, soddisfano l'autenticazione tramite header della richiesta invece di connect.params.auth.*.
• gateway.auth.mode: "none" per ingress privato disabilita completamente l'autenticazione con segreto condiviso; mantieni questa modalità disattivata su ingress pubblico/non attendibile.
• Le chiavi di idempotenza sono obbligatorie per i metodi con effetti collaterali (send, agent) per poter riprovare in sicurezza; il server mantiene una cache di deduplica di breve durata.
• I Node devono includere role: "node" più capability/comandi/permessi in connect.

# Abbinamento + trust locale

• Tutti i client WS (operatori + node) includono un'identità del dispositivo in connect.
• I nuovi ID dispositivo richiedono l'approvazione dell'abbinamento; il Gateway emette un token dispositivo per le connessioni successive.
• Le connessioni dirette local loopback possono essere approvate automaticamente per mantenere fluida la UX sullo stesso host.
• OpenClaw dispone anche di un percorso ristretto di auto-connessione backend/container-locale per flussi helper attendibili con segreto condiviso.
• Le connessioni Tailnet e LAN, inclusi i bind tailnet sullo stesso host, richiedono comunque l'approvazione esplicita dell'abbinamento.
• Tutte le connessioni devono firmare il nonce connect.challenge.
• Il payload di firma v3 vincola anche platform + deviceFamily; il gateway fissa i metadati abbinati alla riconnessione e richiede un abbinamento di riparazione per modifiche ai metadati.
• Le connessioni non locali richiedono comunque approvazione esplicita.
• L'autenticazione del Gateway (gateway.auth.*) si applica comunque a tutte le connessioni, locali o remote.

Dettagli: Protocollo Gateway, Abbinamento, Sicurezza.

# Tipizzazione del protocollo e generazione del codice

• Gli schemi TypeBox definiscono il protocollo.
• JSON Schema viene generato da questi schemi.
• I modelli Swift vengono generati da JSON Schema.

# Accesso remoto

• Preferito: Tailscale o VPN.

• Alternativa: tunnel SSH

  ssh -N -L 18789:127.0.0.1:18789 user@host
  

• Lo stesso token di handshake + autenticazione si applica tramite il tunnel.

• TLS + pinning opzionale possono essere abilitati per WS nelle configurazioni remote.

# Snapshot operativo

• Avvio: openclaw gateway (foreground, log su stdout).
• Integrità: health tramite WS (incluso anche in hello-ok).
• Supervisione: launchd/systemd per il riavvio automatico.

# Invarianti

• Esattamente un Gateway controlla una singola sessione Baileys per host.
• L'handshake è obbligatorio; qualsiasi primo frame non JSON o non-connect comporta una chiusura forzata.
• Gli eventi non vengono riprodotti; i client devono aggiornarsi in caso di gap.

# Correlati

• Loop agente — ciclo dettagliato di esecuzione dell'agente
• Protocollo Gateway — contratto del protocollo WebSocket
• Coda — coda dei comandi e concorrenza
• Sicurezza — modello di trust e hardening