Netwerkproxy

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.

​

Waarom een proxy gebruiken

• Centraal beleid: beheer één egressbeleid in plaats van erop te vertrouwen dat elke HTTP-aanroepplaats in de applicatie de netwerkregels correct toepast.
• Controles tijdens verbinden: evalueer de bestemming na DNS-resolutie en direct voordat de proxy de upstreamverbinding opent.
• Verdediging tegen DNS-rebinding: verklein de kloof tussen een DNS-controle op applicatieniveau en de daadwerkelijke uitgaande verbinding.
• Bredere JavaScript-dekking: routeer gewone fetch, node:http, node:https, WebSocket, axios, got, node-fetch en vergelijkbare clients via hetzelfde pad.
• Auditbaarheid: log toegestane en geweigerde bestemmingen aan de egressgrens.
• Operationele controle: dwing bestemmingsregels, netwerksegmentatie, snelheidslimieten of uitgaande allowlists af zonder OpenClaw opnieuw te bouwen.

​

Hoe OpenClaw verkeer routeert

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

• Undici-dispatcherrouting dekt fetch, undici-gebaseerde clients en transports die hun eigen undici-dispatcher leveren.
• global-agent-routing dekt Node core node:http- en node:https-aanroepers, waaronder veel bibliotheken die zijn gebouwd bovenop http.request, https.request, http.get en https.get. Beheerde proxymodus forceert die globale agent zodat expliciete Node HTTP-agents de operatorproxy niet per ongeluk omzeilen.

​

Gerelateerde proxytermen

• proxy.enabled / proxy.proxyUrl: uitgaande forward-proxy-routing voor OpenClaw runtime-egress. Deze pagina documenteert die functie.
• gateway.auth.mode: "trusted-proxy": inkomende identiteitsbewuste reverse-proxy-authenticatie voor Gateway-toegang. Zie Vertrouwde proxy-authenticatie.
• openclaw proxy: lokale debugproxy en capture-inspector voor ontwikkeling en ondersteuning. Zie openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: opt-in voor web_fetch om een door de operator beheerde HTTP(S)-env-proxy DNS te laten oplossen, terwijl standaard strikte DNS-pinning en hostnaambeleiid behouden blijven. Zie Web fetch.
• Kanaal- of providerspecifieke proxyinstellingen: eigenaarsspecifieke overrides voor een specifieke transportlaag. Geef de voorkeur aan de beheerde netwerkproxy wanneer het doel centrale egresscontrole over de runtime is.

​

Configuratie

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

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

​

Gateway Loopback-modus

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

• gateway-only (standaard): OpenClaw registreert de Gateway-loopbackautoriteit in de actieve global-agent NO_PROXY-controller zodat lokaal Gateway WebSocket-verkeer direct kan verbinden. Aangepaste loopback-Gatewaypoorten werken omdat de host en poort van de actieve Gateway-URL worden geregistreerd.
• proxy: OpenClaw registreert geen Gateway-loopback-NO_PROXY-autoriteit, dus lokaal Gateway-verkeer wordt via de beheerde proxy verzonden. Als de proxy extern is, moet deze speciale routering bieden voor de loopbackservice van de OpenClaw-host, zoals het mappen daarvan naar een door de proxy bereikbare hostnaam, IP of tunnel. Standaard externe proxy’s lossen 127.0.0.1 en localhost op vanaf de proxyhost, niet vanaf de OpenClaw-host.
• block: OpenClaw weigert loopback Gateway control-plane-verbindingen voordat er een socket wordt geopend.

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

​

Proxyvereisten

• Alleen aan loopback of een privé vertrouwde interface te binden.
• Toegang te beperken zodat alleen het OpenClaw-proces, de host, container of serviceaccount deze kan gebruiken.
• Bestemmingen zelf op te lossen en bestemmings-IP’s na DNS-resolutie te blokkeren.
• Beleid toe te passen tijdens verbinden voor zowel gewone HTTP-aanvragen als HTTPS CONNECT-tunnels.
• Bestemmingsgebaseerde bypasses te weigeren voor loopback-, privé-, link-local-, metadata-, multicast-, gereserveerde of documentatiebereiken.
• Hostnaam-allowlists te vermijden, tenzij je het DNS-resolutiepad volledig vertrouwt.
• Bestemming, beslissing, status en reden te loggen zonder request bodies, authorization-headers, cookies of andere geheimen te loggen.
• Proxybeleid onder versiebeheer te houden en wijzigingen te beoordelen als beveiligingsgevoelige configuratie.

​

Aanbevolen geblokkeerde bestemmingen

​

Validatie

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

​

Limieten

• De proxy verbetert de dekking voor proceslokale JavaScript-HTTP- en WebSocket-clients, maar is geen netwerk-sandbox op OS-niveau.
• Gateway-loopbackverkeer voor het control-plane gebruikt standaard een directe lokale bypass via proxy.loopbackMode: "gateway-only". OpenClaw implementeert die bypass door de actieve Gateway-loopbackautoriteit te registreren in de beheerde global-agent-NO_PROXY-controller. Operators kunnen proxy.loopbackMode: "proxy" instellen om Gateway-loopbackverkeer via de beheerde proxy te verzenden, of proxy.loopbackMode: "block" om loopback-Gateway-verbindingen te weigeren. Zie Gateway-loopbackmodus voor de kanttekening bij externe proxy’s.
• Ruwe net-, tls- en http2-sockets, native add-ons en niet-OpenClaw-kindprocessen kunnen Node-proxyrouting omzeilen, tenzij ze proxy-omgevingsvariabelen erven en respecteren. Geforkte OpenClaw-kind-CLI’s erven de beheerde proxy-URL en de status van proxy.loopbackMode.
• IRC is een ruw TCP/TLS-kanaal buiten door operators beheerde forward-proxyrouting. Stel in implementaties die alle uitgaande verbindingen via die forward-proxy vereisen channels.irc.enabled=false in, tenzij directe IRC-uitgang expliciet is goedgekeurd.
• De lokale debugproxy is diagnostische tooling en de directe upstream-forwarding voor proxyverzoeken en CONNECT-tunnels is standaard uitgeschakeld terwijl de beheerde proxymodus actief is; schakel directe forwarding alleen in voor goedgekeurde lokale diagnostiek.
• Lokale WebUI’s van gebruikers en lokale modelservers moeten waar nodig op de allowlist in het proxybeleid van de operator worden geplaatst; OpenClaw stelt geen algemene bypass voor lokale netwerken voor hen beschikbaar.
• De Gateway-proxybypass voor het control-plane is bewust beperkt tot localhost en letterlijke loopback-IP-URL’s. Gebruik ws://127.0.0.1:18789, ws://[::1]:18789 of ws://localhost:18789 voor lokale directe Gateway-control-plane-verbindingen; andere hostnamen routeren zoals gewoon hostnaamgebaseerd verkeer.
• OpenClaw inspecteert, test of certificeert je proxybeleid niet.
• Behandel wijzigingen in het proxybeleid als beveiligingsgevoelige operationele wijzigingen.