Proxy di rete

​

Perché usare un proxy

• Policy centrale: mantieni una sola policy di egress invece di affidarti a ogni punto di chiamata HTTP dell’applicazione affinché applichi correttamente le regole di rete.
• Controlli al momento della connessione: valuta la destinazione dopo la risoluzione DNS e subito prima che il proxy apra la connessione upstream.
• Difesa contro DNS rebinding: riduce lo scarto tra un controllo DNS a livello applicativo e la connessione in uscita effettiva.
• Copertura JavaScript più ampia: instrada fetch, node:http, node:https, WebSocket, axios, got, node-fetch e client simili attraverso lo stesso percorso.
• Verificabilità: registra le destinazioni consentite e negate al confine di egress.
• Controllo operativo: applica regole di destinazione, segmentazione di rete, limiti di frequenza o allowlist in uscita senza ricompilare OpenClaw.

​

Come OpenClaw instrada il traffico

OpenClaw process
  fetch                  -> operator-managed filtering proxy -> public internet
  node:http and https    -> operator-managed filtering proxy -> public internet
  WebSocket clients      -> operator-managed filtering proxy -> public internet

• http://proxy.example:3128: OpenClaw apre una connessione TCP in chiaro al forward proxy e invia richieste proxy HTTP, incluso CONNECT per le destinazioni HTTPS.
• https://proxy.example:8443: OpenClaw apre TLS verso l’endpoint proxy, verifica il certificato del proxy e poi invia richieste proxy HTTP all’interno di quella sessione TLS.

​

Termini proxy correlati

• proxy.enabled / proxy.proxyUrl: instradamento tramite forward proxy in uscita per l’egress di runtime di OpenClaw. Questa pagina documenta tale funzionalità.
• gateway.auth.mode: "trusted-proxy": autenticazione reverse proxy in ingresso con identità per l’accesso al Gateway. Vedi Autenticazione tramite proxy attendibile.
• openclaw proxy: proxy di debug locale e ispettore di acquisizione per sviluppo e supporto. Vedi openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: consenso esplicito per web_fetch affinché un proxy env HTTP(S) controllato dall’operatore risolva il DNS mantenendo il pinning DNS rigoroso e la policy hostname predefiniti. Vedi Web fetch.
• Impostazioni proxy specifiche di canale o provider: override specifici del proprietario per un particolare trasporto. Preferisci il proxy di rete gestito quando l’obiettivo è il controllo centralizzato dell’egress in tutto il runtime.

​

Configurazione

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128

proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem

OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run

​

Modalità loopback del Gateway

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128
  loopbackMode: gateway-only # gateway-only, proxy, or block

• gateway-only (predefinito): OpenClaw registra l’autorità loopback del Gateway nella policy di bypass gestita di Proxyline, così il traffico WebSocket locale del Gateway può connettersi direttamente. Le porte Gateway loopback personalizzate funzionano perché l’host e la porta dell’URL del Gateway attivo sono registrati. Il Plugin browser in bundle può anche registrare gli endpoint WebSocket locali esatti di prontezza CDP e DevTools per i browser gestiti avviati da OpenClaw, e il provider di embedding di memoria Ollama in bundle può usare il proprio percorso diretto sorvegliato più ristretto per l’origine embedding loopback locale all’host esattamente configurata.
• proxy: OpenClaw non registra bypass loopback per Gateway o Ollama, quindi quel traffico loopback viene inviato attraverso il proxy gestito. Se il proxy è remoto, deve fornire un instradamento speciale per il servizio loopback dell’host OpenClaw, per esempio mappandolo a un hostname, IP o tunnel raggiungibile dal proxy. I proxy remoti standard risolvono 127.0.0.1 e localhost dall’host del proxy, non dall’host OpenClaw.
• block: OpenClaw nega le connessioni loopback del piano di controllo del Gateway e le connessioni loopback di embedding locali all’host sorvegliate di Ollama prima di aprire un socket.

openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway install --force
openclaw gateway start

​

Requisiti del proxy

• Effettuare il bind solo su loopback o su un’interfaccia privata attendibile.
• Limitare l’accesso in modo che solo il processo, l’host, il container o l’account di servizio OpenClaw possa usarlo.
• Risolvere autonomamente le destinazioni e bloccare gli IP di destinazione dopo la risoluzione DNS.
• Applicare la policy al momento della connessione sia per le richieste HTTP in chiaro sia per i tunnel HTTPS CONNECT.
• Rifiutare bypass basati sulla destinazione per intervalli loopback, privati, link-local, metadata, multicast, riservati o di documentazione.
• Evitare allowlist di hostname a meno che tu non consideri pienamente attendibile il percorso di risoluzione DNS.
• Registrare destinazione, decisione, stato e motivo senza registrare corpi delle richieste, header di autorizzazione, cookie o altri segreti.
• Tenere la policy del proxy sotto controllo versione e rivedere le modifiche come configurazione sensibile per la sicurezza.

​

Destinazioni bloccate consigliate

​

Convalida

openclaw proxy validate --proxy-url http://127.0.0.1:3128

openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem

{
  "ok": true,
  "config": {
    "enabled": true,
    "proxyUrl": "http://127.0.0.1:3128/",
    "source": "override",
    "errors": []
  },
  "checks": [
    {
      "kind": "allowed",
      "url": "https://example.com/",
      "ok": true,
      "status": 200
    },
    {
      "kind": "apns",
      "url": "https://api.sandbox.push.apple.com",
      "ok": true,
      "status": 403
    }
  ]
}

curl -x http://127.0.0.1:3128 https://example.com/
curl -x http://127.0.0.1:3128 http://127.0.0.1/
curl -x http://127.0.0.1:3128 http://169.254.169.254/

​

Attendibilità della CA del proxy

proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem

openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl https://proxy.corp.example:8443
openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pem
openclaw gateway run

proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem

​

Limiti

• Il proxy migliora la copertura per i client JavaScript HTTP e WebSocket locali al processo, ma non è una sandbox di rete a livello di sistema operativo.
• Il traffico del piano di controllo loopback del Gateway usa per impostazione predefinita un bypass locale diretto tramite proxy.loopbackMode: "gateway-only". OpenClaw implementa quel bypass registrando l’autorità di loopback Gateway attiva nella policy di bypass gestita di Proxyline. Gli operatori possono impostare proxy.loopbackMode: "proxy" per inviare il traffico di loopback Gateway tramite il proxy gestito, oppure proxy.loopbackMode: "block" per negare le connessioni Gateway di loopback. Vedi Modalità loopback Gateway per l’avvertenza sul proxy remoto.
• I socket raw net, tls e http2, gli addon nativi e i processi figlio non OpenClaw possono aggirare il routing proxy a livello Node, a meno che ereditino e rispettino le variabili d’ambiente del proxy. Le CLI figlio OpenClaw biforcate ereditano l’URL proxy gestito e lo stato proxy.loopbackMode.
• IRC è un canale TCP/TLS raw al di fuori del routing tramite proxy forward gestito dall’operatore. Nelle distribuzioni che richiedono che tutto il traffico in uscita passi tramite quel proxy forward, imposta channels.irc.enabled=false, a meno che l’egress IRC diretto sia approvato esplicitamente.
• Il proxy di debug locale è uno strumento diagnostico e il suo inoltro upstream diretto per richieste proxy e tunnel CONNECT è disabilitato per impostazione predefinita mentre la modalità proxy gestita è attiva; abilita l’inoltro diretto solo per diagnostica locale approvata.
• Le WebUI locali dell’utente e i server di modelli locali dovrebbero essere inseriti nell’allowlist nella policy proxy dell’operatore quando necessario; OpenClaw non espone un bypass generale della rete locale per essi. Il provider di embedding di memoria Ollama in bundle è più ristretto: può usare un percorso diretto protetto solo per l’esatta origine di embedding loopback locale all’host derivata dal baseUrl configurato, così gli embedding locali all’host continuano a funzionare quando il proxy gestito non può raggiungere il loopback dell’host. Gli host di embedding Ollama su LAN, tailnet, rete privata e pubblici usano comunque il percorso del proxy gestito. proxy.loopbackMode: "proxy" invia questo traffico di loopback Ollama tramite il proxy gestito, e proxy.loopbackMode: "block" lo nega prima di aprire una connessione.
• Il bypass proxy del piano di controllo Gateway è intenzionalmente limitato a localhost e URL con IP di loopback letterali. Usa ws://127.0.0.1:18789, ws://[::1]:18789 o ws://localhost:18789 per connessioni locali dirette al piano di controllo Gateway; gli altri nomi host vengono instradati come normale traffico basato su nome host.
• OpenClaw non ispeziona, testa né certifica la tua policy proxy.
• Tratta le modifiche alla policy proxy come modifiche operative sensibili per la sicurezza.