Netwerkproxy

​

Waarom een proxy gebruiken

• Centraal beleid: onderhoud één egress-beleid in plaats van erop te vertrouwen dat elke HTTP-aanroeplocatie in de toepassing de netwerkregels goed toepast.
• Controles bij verbinding: 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 toepassingsniveau 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.
• Controleerbaarheid: log toegestane en geweigerde bestemmingen aan de egress-grens.
• 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

• http://proxy.example:3128: OpenClaw opent een gewone TCP-verbinding naar de forward proxy en verzendt HTTP-proxyverzoeken, inclusief CONNECT voor HTTPS-bestemmingen.
• https://proxy.example:8443: OpenClaw opent TLS naar het proxy-eindpunt, verifieert het proxycertificaat en verzendt vervolgens HTTP-proxyverzoeken binnen die TLS-sessie.

​

Gerelateerde proxytermen

• proxy.enabled / proxy.proxyUrl: uitgaande forward-proxyroutering voor OpenClaw-runtime-egress. Deze pagina documenteert die functie.
• gateway.auth.mode: "trusted-proxy": inkomende identity-aware reverse-proxy-authenticatie voor Gateway-toegang. Zie Trusted 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 beheerder gecontroleerde HTTP(S)-env-proxy DNS te laten oplossen, terwijl standaard strikte DNS-pinning en hostnamebeleid behouden blijven. Zie Web fetch.
• Kanaal- of providerspecifieke proxyinstellingen: eigenaarsspecifieke overrides voor een bepaald transport. Geef de voorkeur aan de beheerde netwerkproxy wanneer het doel centrale egress-controle over de runtime is.

​

Configuratie

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

​

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 het beheerde bypassbeleid van Proxyline, zodat lokaal Gateway-WebSocket-verkeer direct verbinding kan maken. Aangepaste loopback-Gateway-poorten werken omdat de host en poort van de actieve Gateway-URL worden geregistreerd. De gebundelde browser-Plugin kan ook de exacte lokale CDP-readiness- en DevTools-WebSocket-eindpunten registreren voor door OpenClaw gestarte beheerde browsers, en de gebundelde Ollama memory embedding provider kan zijn eigen smallere bewaakte directe pad gebruiken voor de exact geconfigureerde hostlokale loopback-embedding-origin.
• proxy: OpenClaw registreert geen Gateway- of Ollama-loopbackbypasses, dus dat loopbackverkeer wordt via de beheerde proxy verzonden. Als de proxy extern is, moet deze speciale routering bieden voor de loopbackservice van de OpenClaw-host, zoals mapping naar een door de proxy bereikbare hostnaam, IP of tunnel. Standaard externe proxies lossen 127.0.0.1 en localhost op vanaf de proxyhost, niet vanaf de OpenClaw-host.
• block: OpenClaw weigert Gateway-loopback-control-plane-verbindingen en bewaakte Ollama-hostlokale embedding-loopbackverbindingen voordat 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 te binden aan loopback of een private vertrouwde interface.
• 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 bij verbindingstijd voor zowel gewone HTTP-verzoeken als HTTPS CONNECT-tunnels.
• Bestemmingsgebaseerde omzeilingen te weigeren voor loopback-, private, link-local-, metadata-, multicast-, reserved- of documentatiereeksen.
• Hostname-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

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/

​

Proxy-CA-vertrouwen

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

​

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 het beheerde bypassbeleid van Proxyline. Operators kunnen proxy.loopbackMode: "proxy" instellen om Gateway-loopbackverkeer via de beheerde proxy te sturen, of proxy.loopbackMode: "block" om loopback-Gateway-verbindingen te weigeren. Zie Gateway-loopbackmodus voor de kanttekening bij externe proxy’s.
• Raw net-, tls- en http2-sockets, native addons en niet-OpenClaw-kindprocessen kunnen proxyrouting op Node-niveau omzeilen, tenzij ze proxyomgevingsvariabelen erven en respecteren. Geforkte OpenClaw-kind-CLI’s erven de beheerde proxy-URL en de status van proxy.loopbackMode.
• IRC is een raw TCP/TLS-kanaal buiten door operators beheerde forward-proxyrouting. Stel in implementaties die vereisen dat alle egress via die forward-proxy loopt channels.irc.enabled=false in, tenzij directe IRC-egress 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 worden geallowlist in het operatorproxybeleid; OpenClaw stelt daarvoor geen algemene bypass voor lokale netwerken beschikbaar. De gebundelde Ollama-provider voor geheugen-embeddings is beperkter: deze kan alleen een bewaakt direct pad gebruiken voor de exacte host-lokale loopback-embedding-origin die is afgeleid van de geconfigureerde baseUrl, zodat host-lokale embeddings blijven werken wanneer de beheerde proxy de host-loopback niet kan bereiken. LAN-, tailnet-, private-network- en openbare Ollama-embeddinghosts gebruiken nog steeds het beheerde proxypad. proxy.loopbackMode: "proxy" stuurt dit Ollama-loopbackverkeer via de beheerde proxy, en proxy.loopbackMode: "block" weigert het voordat een verbinding wordt geopend.
• Proxy-bypass voor het Gateway-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 worden gerouteerd als gewoon hostnaamgebaseerd verkeer.
• OpenClaw inspecteert, test of certificeert je proxybeleid niet.
• Behandel wijzigingen in proxybeleid als beveiligingsgevoelige operationele wijzigingen.