Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Proxy di rete

​

Perché usare un proxy?

• Criterio centralizzato: mantieni un unico criterio di uscita invece di affidarti al fatto che ogni punto di chiamata HTTP dell’applicazione 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 il 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 client simili attraverso lo stesso percorso.
• Verificabilità tramite audit: registra le destinazioni consentite e negate al confine di uscita.
• Controllo operativo: applica regole sulle destinazioni, 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

• L’instradamento del dispatcher Undici copre fetch, i client basati su undici e i trasporti che forniscono il proprio dispatcher undici.
• L’instradamento global-agent copre i chiamanti Node core node:http e node:https, incluse molte librerie stratificate su http.request, https.request, http.get e https.get. La modalità proxy gestita forza quell’agente globale, così gli agent HTTP Node espliciti non possono aggirare accidentalmente il proxy dell’operatore.

​

Termini proxy correlati

• proxy.enabled / proxy.proxyUrl: instradamento forward-proxy in uscita per l’uscita di runtime di OpenClaw. Questa pagina documenta tale funzionalità.
• gateway.auth.mode: "trusted-proxy": autenticazione tramite reverse proxy in ingresso con consapevolezza dell’identità per l’accesso al Gateway. Vedi Autenticazione trusted proxy.
• openclaw proxy: proxy di debug locale e ispettore di acquisizione per sviluppo e supporto. Vedi openclaw proxy.
• Impostazioni proxy specifiche del canale o del provider: override specifici del proprietario per un particolare trasporto. Preferisci il proxy di rete gestito quando l’obiettivo è il controllo centralizzato dell’uscita 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

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

• Ascoltare 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 di OpenClaw possano usarlo.
• Risolvere autonomamente le destinazioni e bloccare gli IP di destinazione dopo la risoluzione DNS.
• Applicare il criterio al momento della connessione sia per le richieste HTTP in chiaro 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 nomi host 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 il criterio del proxy sotto controllo versione e revisionare 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
    }
  ]
}

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.
• I socket raw net, tls e http2, gli addon nativi e i processi figlio possono aggirare l’instradamento del proxy a livello di Node, a meno che non ereditino e rispettino le variabili d’ambiente del proxy.
• Le WebUI locali dell’utente e i server di modelli locali dovrebbero essere inseriti nella allowlist nella policy del proxy dell’operatore quando necessario; OpenClaw non espone per loro un bypass generale della rete locale.
• Il bypass del proxy per il piano di controllo del Gateway è intenzionalmente limitato a localhost e agli URL con 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 del proxy.
• Tratta le modifiche alla policy del proxy come modifiche operative sensibili per la sicurezza.