Proxy di rete

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.

​

Perché usare un proxy

• Policy centralizzata: mantieni una sola policy di egress invece di affidarti a ogni punto di chiamata HTTP dell’applicazione per applicare correttamente le regole di rete.
• Controlli al momento della connessione: valuta la destinazione dopo la risoluzione DNS e immediatamente prima che il proxy apra la connessione upstream.
• Difesa dal DNS rebinding: riduci lo scarto tra un controllo DNS a livello applicativo e la connessione in uscita effettiva.
• Copertura JavaScript più ampia: instrada i normali client fetch, node:http, node:https, WebSocket, axios, got, node-fetch e 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

Processo OpenClaw
  fetch                  -> proxy filtrante gestito dall'operatore -> internet pubblica
  node:http and https    -> proxy filtrante gestito dall'operatore -> internet pubblica
  Client WebSocket       -> proxy filtrante gestito dall'operatore -> internet pubblica

• L’instradamento tramite dispatcher Undici copre fetch, i client basati su undici e i trasporti che forniscono un proprio dispatcher undici.
• L’instradamento global-agent copre i chiamanti Node core node:http e node:https, incluse molte librerie basate su http.request, https.request, http.get e https.get. La modalità proxy gestita forza quell’agente globale, in modo che agent HTTP Node espliciti non aggirino accidentalmente il proxy dell’operatore.

​

Termini correlati al proxy

• proxy.enabled / proxy.proxyUrl: instradamento tramite proxy forward in uscita per l’egress di runtime di OpenClaw. Questa pagina documenta questa funzionalità.
• gateway.auth.mode: "trusted-proxy": autenticazione tramite proxy inverso in ingresso con identità per l’accesso al Gateway. Vedi Autenticazione trusted proxy.
• openclaw proxy: proxy locale di debug e ispettore di acquisizione per sviluppo e supporto. Vedi openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: opt-in per web_fetch per permettere a un proxy env HTTP(S) controllato dall’operatore di risolvere il DNS mantenendo il pinning DNS rigoroso predefinito e la policy sugli hostname. Vedi Web fetch.
• Impostazioni proxy specifiche per 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

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à di loopback del Gateway nel controller NO_PROXY global-agent attivo, così il traffico WebSocket del Gateway locale può connettersi direttamente. Le porte Gateway di loopback personalizzate funzionano perché l’host e la porta dell’URL Gateway attivo vengono registrati.
• proxy: OpenClaw non registra un’autorità NO_PROXY di loopback del Gateway, quindi il traffico Gateway locale viene inviato attraverso il proxy gestito. Se il proxy è remoto, deve fornire un instradamento speciale per il servizio di loopback dell’host OpenClaw, ad 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 del piano di controllo del Gateway di loopback 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 al loopback o a 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 semplici sia per i tunnel HTTPS CONNECT.
• Rifiutare i bypass basati sulla destinazione per intervalli di loopback, privati, link-local, metadata, multicast, riservati o di documentazione.
• Evitare allowlist di hostname a meno che non ti fidi completamente del 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

​

Validazione

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

{
  "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/

openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway run

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

​

Limiti

• Il proxy migliora la copertura per i client HTTP e WebSocket JavaScript locali al processo, ma non è una sandbox di rete a livello di sistema operativo.
• Il traffico del piano di controllo loopback del Gateway passa per impostazione predefinita tramite bypass locale diretto con proxy.loopbackMode: "gateway-only". OpenClaw implementa quel bypass registrando l’autorità loopback attiva del Gateway nel controller NO_PROXY gestito di global-agent. Gli operatori possono impostare proxy.loopbackMode: "proxy" per inviare il traffico loopback del Gateway attraverso il proxy gestito, oppure proxy.loopbackMode: "block" per negare le connessioni loopback del Gateway. Vedi Modalità Loopback del Gateway per l’avvertenza sul proxy remoto.
• I socket raw net, tls e http2, gli addon nativi e i processi figli non OpenClaw possono bypassare il routing proxy a livello Node, a meno che ereditino e rispettino le variabili d’ambiente del proxy. Le CLI figlie OpenClaw forkate ereditano l’URL del proxy gestito e lo stato proxy.loopbackMode.
• IRC è un canale TCP/TLS raw al di fuori del routing proxy forward gestito dall’operatore. Nei deployment che richiedono tutto l’egress attraverso quel proxy forward, imposta channels.irc.enabled=false a meno che l’egress IRC diretto non sia esplicitamente approvato.
• 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 gestito è attiva; abilita l’inoltro diretto solo per diagnostica locale approvata.
• Le WebUI locali dell’utente e i server modello locali dovrebbero essere inseriti nella allowlist nella policy proxy dell’operatore quando necessario; OpenClaw non espone un bypass generale della rete locale per essi.
• Il bypass proxy del piano di controllo del Gateway è intenzionalmente limitato a localhost e agli URL IP loopback letterali. Usa ws://127.0.0.1:18789, ws://[::1]:18789 o ws://localhost:18789 per connessioni locali dirette al piano di controllo del 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.