Gateway - Neotask by Neotask Documentation | Neotask

Gateway

Cos'è il Gateway?

Il Gateway è il cuore di Open Claw — un singolo servizio a lunga esecuzione che gestisce tutte le sessioni degli agenti, i canali di messaggistica, l'esecuzione degli strumenti e le connessioni dei dispositivi. Tutto passa attraverso il Gateway.

È un server WebSocket che ascolta le connessioni dai client (app desktop, app mobili, dashboard web) e gestisce l'intero ciclo di vita dell'assistente AI.

Architettura

Componenti

  • WebSocket Server — Accetta le connessioni dei client (porta predefinita 18789)
  • HTTP Server — Serve la Control UI, il canvas host e gli endpoint di health
  • Channel Adapters — Mantengono le connessioni alle piattaforme di messaggistica (WhatsApp, Telegram, Discord, ecc.)
  • Session Manager — Persiste e gestisce lo stato delle conversazioni degli agenti
  • Cron Scheduler — Esegue i job pianificati e i risveglio tramite heartbeat
  • Plugin Runtime — Carica e gestisce il ciclo di vita dei plugin
  • Browser Service — Controlla le istanze Chromium per l'automazione web

    • Modalità di Binding

    | Modalità | Descrizione | |------|-------------| | Loopback | Predefinita. Accessibile solo da localhost (127.0.0.1) | | LAN | Accessibile sulla rete locale. Auto-scopribile tramite Bonjour/mDNS | | Tailnet | Accessibile tramite Tailscale VPN con MagicDNS | | Custom | Lega a un indirizzo specifico |

    Autenticazione

    | Metodo | Descrizione | |--------|-------------| | Token | Bearer token WebSocket (UUID o stringa personalizzata) | | Password | Autenticazione basata su password (hash bcrypt) | | Trusted Proxy | Per proxy inversi con header pre-autenticati | | Local Trust | Connessioni loopback approvate automaticamente |

    Configurazione

    Il Gateway è configurato tramite openclaw.json (formato JSON5). Sezioni principali:

    | Sezione | Controlla | |---------|----------| | agents | Elenco agenti, valori predefiniti, workspace | | gateway | Porta, modalità di binding, autenticazione, comportamento di ricarica | | channels | Configurazione e credenziali per canale | | tools | Permessi degli strumenti, profili, sicurezza | | plugins | Caricamento plugin, abilitazione, configurazione per plugin | | models | Autenticazione provider, fallback, impostazioni provider | | skills | Directory delle skill, configurazione per skill | | browser | Profili browser, porte, modalità headless | | cron | Configurazione dello scheduler | | session | Regole di reset, soglie di compattazione | | messages | Impostazioni TTS, policy media | | memory | Configurazione dell'indicizzazione della memoria | | security | Sandboxing, modalità elevata, approvazioni |

    Hot Reload

    Le modifiche alla configurazione possono essere applicate senza riavvio:

    | Modalità | Comportamento | |------|----------| | Hybrid (predefinita) | Applica immediatamente le modifiche sicure, riavvia per le altre | | Hot | Applica solo le modifiche hot-safe, ignora le altre | | Restart | Riavvia per qualsiasi modifica che richiede ricarica | | Off | Nessun ricaricamento automatico |

    Accesso Remoto

    Tailscale (Consigliato)

    Tailscale fornisce accesso remoto sicuro e zero-config:

  • Lega il Gateway al tuo Tailnet
  • Accedi da qualsiasi dispositivo sulla stessa rete Tailscale
  • DNS automatico tramite MagicDNS
  • Tailscale Serve può esporre la dashboard con HTTPS

    • SSH Tunnel

    Inoltra la porta del Gateway tramite SSH:

  • Semplice, sicuro, nessuna modifica alla configurazione necessaria
  • Funziona con qualsiasi macchina con supporto SSH
  • Supporta il protocollo WebSocket completo e la Control UI

    • Regole di Sicurezza

  • Loopback + SSH/Tailscale è la combinazione più sicura
  • Il binding non-loopback richiede la configurazione del token di autenticazione
  • TLS fingerprint pinning disponibile per sicurezza extra
  • Il controllo del browser è disabilitato per le connessioni remote per default

    • Monitoraggio della Salute

    Endpoint di Health

    L'endpoint HTTP /health restituisce:

  • Stato del Gateway
  • Liveness RPC
  • Salute per canale (connesso, stato auth, numero di account)
  • Disponibilità del browser
  • Agenti attivi e nodi connessi
  • Uptime

    • Probe

  • RPC liveness — Connessione WebSocket + test echo
  • Channel health — Controllo auth + ping API per canale
  • Browser readiness — Controllo porta, controllo processo
  • Node connectivity — Timestamp dell'ultimo heartbeat

    • Scoperta

    Bonjour/mDNS

    Quando legato alla LAN, il Gateway si annuncia tramite DNS multicast:

  • Tipo di servizio: _openclaw-gw._tcp
  • Include porta, trasporto, stato TLS e informazioni DNS Tailscale
  • Le app companion scoprono automaticamente il Gateway

    • Scoperta Wide-Area

    Scopri i gateway sulla tua rete con timeout configurabili. Supporta sia Bonjour locale che scoperta DNS Tailscale.

    Gateway Multipli

    Puoi eseguire più istanze del Gateway sulla stessa macchina usando i profili:

  • Ogni profilo ha configurazione, workspace, sessioni e stato separati
  • Porte diverse per ogni Gateway
  • Utile per l'isolamento (personale vs lavoro) o il testing

    • Diagnostica

    Doctor

    Lo strumento di diagnostica integrato controlla:

  • Validità della configurazione
  • Permessi dei file
  • Connettività dei canali
  • Stato dell'autenticazione dei modelli
  • Compatibilità della versione Node.js
  • Configurazioni errate comuni

    • Può correggere automaticamente molti problemi quando glielo viene permesso.

    Logging

    I log del Gateway vengono scritti in file JSONL giornalieri:

  • Tracciamento dell'utilizzo dei token per completamento
  • Log degli eventi dei canali
  • Log degli errori con contesto strutturato
  • Livelli di log configurabili

    • View full documentation