> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/it/gateway/protocol)

### 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)

```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}}
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<br>snapshot: presence + health

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

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(streaming)
    Gateway-->>Client: res:agent<br>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](/it/gateway/protocol), [Abbinamento](/it/channels/pairing),
[Sicurezza](/it/gateway/security).

## 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

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  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](/it/concepts/agent-loop) — ciclo dettagliato di esecuzione dell'agente
* [Protocollo Gateway](/it/gateway/protocol) — contratto del protocollo WebSocket
* [Coda](/it/concepts/queue) — coda dei comandi e concorrenza
* [Sicurezza](/it/gateway/security) — modello di trust e hardening