Netwerkproxy

OpenClaw kan HTTP- en WebSocket-verkeer tijdens runtime routeren via een door de operator beheerde forward proxy. Dit is optionele gelaagde beveiliging: centrale controle over uitgaand verkeer, sterkere SSRF-bescherming en controleerbaarheid van bestemmingen aan de netwerkgrens. Omdat de proxy de bestemming evalueert op het moment dat de verbinding wordt gemaakt, na DNS-resolutie en onmiddellijk voordat de upstreamverbinding wordt geopend, verkleint deze ook het tijdsvenster waarvan een DNS-rebindingaanval afhankelijk is tussen een eerdere DNS-controle op applicatieniveau en de daadwerkelijke uitgaande verbinding. Eén proxybeleid biedt operators bovendien één plek om bestemmingsregels, netwerksegmentatie, snelheidslimieten of allowlists voor uitgaand verkeer af te dwingen zonder OpenClaw opnieuw te bouwen.

OpenClaw levert, downloadt, start, configureert of certificeert geen proxy. U gebruikt de proxytechnologie die bij uw omgeving past; OpenClaw routeert zijn eigen HTTP- en WebSocket-clients erdoorheen.

Configuratie

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

U kunt de URL ook via de omgeving instellen terwijl proxy.enabled: true in de configuratie blijft staan:

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

proxy.proxyUrl heeft voorrang op OPENCLAW_PROXY_URL. Als proxy.enabled true is maar er geen geldige URL kan worden bepaald, mislukken beveiligde opdrachten bij het opstarten in plaats van terug te vallen op directe netwerktoegang.

Sla voor beheerde Gateway-services de URL op in de configuratie, zodat deze een herinstallatie overleeft, in plaats van te vertrouwen op omgevingsvariabelen van het voorgrondproces:

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

De terugvaloptie via de omgevingsvariabele OPENCLAW_PROXY_URL is het meest geschikt voor uitvoeringen op de voorgrond. Als u deze met een geïnstalleerde service wilt gebruiken, plaatst u de variabele in de permanente omgeving van de service ($OPENCLAW_STATE_DIR/.env, standaard ~/.openclaw/.env) en installeert u de service vervolgens opnieuw, zodat launchd/systemd/Geplande taken de instelling overneemt.

HTTPS-proxyeindpunt met een privé-CA

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

proxy.tls.caFile verifieert het eigen TLS-certificaat van het proxyeindpunt. Het is geen vertrouwensinstelling voor MITM bij de bestemming, geen clientcertificaat en geen vervanging voor het bestemmingsbeleid van de proxy. Gebruik NODE_EXTRA_CA_CERTS alleen wanneer het volledige Node-proces vanaf het opstarten een aanvullende CA moet vertrouwen (bijvoorbeeld een bedrijfsbreed TLS-inspectiesysteem dat elk HTTPS-bestemmingscertificaat opnieuw ondertekent) — deze variabele geldt voor het hele proces en moet worden ingesteld voordat Node start. OpenClaw kan deze daarom niet tijdens de uitvoering toepassen zoals bij proxy.tls.caFile. Geef voor het vertrouwen van HTTPS-proxyeindpunten de voorkeur aan proxy.tls.caFile: dit is beperkt tot beheerde proxyrouting in plaats van het hele proces.

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

Hoe routering werkt

Met proxy.enabled: true en een geldige URL routeren beveiligde runtimeprocessen (openclaw gateway run, openclaw node run, openclaw agent --local) normaal uitgaand HTTP- en WebSocket-verkeer via de proxy:

OpenClaw-proces  fetch, node:http, node:https, WebSocket-clients  -> operatorproxy -> bestemming

Intern installeert OpenClaw Proxyline als routeringsruntime op procesniveau. Dit omvat fetch, clients op basis van undici, node:http/node:https, gangbare WebSocket-clients en door helpers aangemaakte CONNECT-tunnels. Ook vervangt het door aanroepers verstrekte Node-HTTP-agents, zodat expliciete agents (waaronder axios, got, node-fetch en vergelijkbare clients op basis van Node-agents) de proxy niet ongemerkt kunnen omzeilen.

Het schema van de proxy-URL beschrijft de verbinding van OpenClaw naar de proxy, niet naar de uiteindelijke bestemming:

• http://proxy.example:3128 — gewone TCP naar de proxy; OpenClaw verzendt HTTP-proxyverzoeken, waaronder CONNECT voor HTTPS-bestemmingen.
• https://proxy.example:8443 — OpenClaw opent TLS naar de proxy zelf (waarbij het certificaat van de proxy wordt geverifieerd) en verzendt vervolgens HTTP-proxyverzoeken binnen die sessie.

TLS voor de bestemming staat los van TLS voor het proxyeindpunt: voor een HTTPS-bestemming vraagt OpenClaw de proxy altijd om een CONNECT-tunnel en start het TLS voor de bestemming via die tunnel.

Terwijl de proxy actief is, wist OpenClaw no_proxy/NO_PROXY. Deze omzeilingslijsten zijn gebaseerd op bestemmingen; als localhost of 127.0.0.1 daarin blijft staan, kunnen SSRF-doelen de proxy volledig omzeilen. Bij het afsluiten herstelt OpenClaw de eerdere proxyomgeving en stelt het de gecachete routeringsstatus opnieuw in.

Sommige plugins beheren een aangepast transport dat eigen proxyconfiguratie nodig heeft, zelfs wanneer routering op procesniveau actief is. De Bot API-client van Telegram gebruikt een eigen HTTP/1-undici-dispatcher en respecteert afzonderlijk de proxyomgevingsvariabelen van het proces plus de terugvaloptie OPENCLAW_PROXY_URL.

Gateway-local-loopbackmodus

Lokale clients voor het Gateway-besturingsvlak maken normaal verbinding met een WebSocket via local loopback, zoals ws://127.0.0.1:18789. proxy.loopbackMode bepaalt of dit verkeer de beheerde proxy omzeilt:

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

Het omzeilen van het Gateway-besturingsvlak is beperkt tot localhost en letterlijke IP-URL's voor local loopback — gebruik ws://127.0.0.1:18789, ws://[::1]:18789 of ws://localhost:18789. Andere hostnamen worden als normaal verkeer gerouteerd.

Containers

Voor opdrachten met openclaw --container ... stuurt OpenClaw OPENCLAW_PROXY_URL door naar de op de container gerichte onderliggende CLI wanneer deze variabele is ingesteld. De URL moet vanuit de container bereikbaar zijn — 127.0.0.1 verwijst daar naar de container zelf, niet naar de host. OpenClaw weigert proxy-URL's voor local loopback bij op containers gerichte opdrachten, tenzij u OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 instelt om deze controle expliciet te omzeilen.

Verwante proxytermen

• proxy.enabled / proxy.proxyUrl — uitgaande routering via een forward proxy voor runtimeverkeer. Deze pagina.
• gateway.auth.mode: "trusted-proxy" — inkomende, identiteitsbewuste authenticatie via een reverse proxy voor toegang tot de Gateway. Zie Authenticatie via een vertrouwde proxy.
• openclaw proxy — lokale debugproxy en inspectieprogramma voor vastgelegd verkeer voor ontwikkeling en ondersteuning. Zie openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy — opt-in voor web_fetch waarmee een door de operator beheerde HTTP(S)-proxy uit de omgeving DNS kan omzetten, terwijl standaard strikte DNS-vastzetting en hostnaambeleid behouden blijven. Zie Web ophalen.
• Proxy-instellingen die specifiek zijn voor een kanaal of provider — eigenaarspecifieke overschrijvingen voor één transport. Geef de voorkeur aan de beheerde netwerkproxy voor centrale controle over uitgaand verkeer in de hele runtime.

De proxy valideren

Het bestemmingsbeleid van de proxy vormt de daadwerkelijke beveiligingsgrens; OpenClaw kan niet controleren of uw proxy de juiste doelen blokkeert. Configureer de proxy om:

• Alleen te binden aan local loopback of een vertrouwde privé-interface die uitsluitend bereikbaar is voor het OpenClaw-proces, de host, container of het serviceaccount.
• Bestemmingen zelf om te zetten en na DNS-resolutie, op het moment dat de verbinding wordt gemaakt, te blokkeren op IP-adres, zowel voor gewone HTTP-verbindingen als voor HTTPS-CONNECT-tunnels.
• Omzeiling op basis van bestemmingen te weigeren voor local loopback, privé-, link-local-, metadata-, multicast-, gereserveerde en documentatiereeksen.
• Allowlists met hostnamen te vermijden, tenzij u het DNS-resolutiepad volledig vertrouwt.
• Bestemming, beslissing, status en reden te registreren — nooit aanvraaginhoud, autorisatieheaders, cookies of andere geheimen.
• Het beleid onder versiebeheer te houden en wijzigingen als beveiligingsgevoelig te beoordelen.

Valideer vanaf dezelfde host, container of hetzelfde serviceaccount waarop OpenClaw wordt uitgevoerd:

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

Met een HTTPS-proxyeindpunt met een privé-CA:

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

Als proxy.enabled niet true is en er geen --proxy-url is opgegeven, meldt de opdracht een configuratieprobleem in plaats van te valideren; geef --proxy-url door voor een eenmalige voorafgaande controle voordat u de configuratie wijzigt.

Zonder --allowed-url/--denied-url zijn dit de standaardcontroles: https://example.com/ moet bereikbaar zijn en een tijdelijke local loopback-kanarieserver die de proxy niet mag bereiken, moet worden geblokkeerd. De local loopback-controle slaagt bij een transportfout, of bij een niet-2xx-antwoord zonder het token dat de kanarie per uitvoering gebruikt; de controle mislukt bij een 2xx-antwoord zonder het token (een onverwacht succesvol antwoord van iets anders dan de kanarie) en in het bijzonder bij elk antwoord met het overeenkomende token, omdat dit bewijst dat de proxy daadwerkelijk een local loopback-bestemming heeft doorgestuurd die deze had moeten weigeren. Aangepaste --denied-url-doelen hebben geen dergelijk kanarietoken en werken daarom volgens het fail-closed-principe: elk HTTP-antwoord telt als bereikbaar (mislukt) en een transportfout wordt als onbeslist gerapporteerd in plaats van als bewezen geblokkeerd, omdat OpenClaw niet kan bevestigen of uw proxy een bereikbare oorsprong heeft geweigerd of dat er iets anders is misgegaan. --apns-reachable verzendt opzettelijk een ongeldig providertoken, zodat een antwoord 403 InvalidProviderToken geldt als bewijs dat de tunnel Apple heeft bereikt. De opdracht eindigt met 1 bij elke validatiefout; inloggegevens in de proxy-URL worden zowel in tekst- als JSON-uitvoer geredigeerd.

{  "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 }  ]}

Handmatige controle met curl (de openbare aanvraag moet slagen; de local loopback- en metadata-aanvragen moeten door de proxy zelf worden geblokkeerd — alleen curl kan geen onderscheid maken tussen een weigering door de proxy en een onbereikbare oorsprong, zoals de ingebouwde kanarie van openclaw proxy validate dat wel kan):

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/

Aanbevolen geblokkeerde bestemmingen

Basisblokkeerlijst voor elke forward proxy, firewall of elk uitgaand-verkeersbeleid. OpenClaws eigen SSRF-classificatie bevindt zich in src/infra/net/ssrf.ts en packages/net-policy/src/ip.ts (BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, het benchmarkprefix uit RFC 2544 en de verwerking van ingesloten IPv4 voor NAT64/6to4/Teredo/ISATAP/IPv4-mapped-vormen) — nuttige referenties, maar OpenClaw exporteert of handhaaft deze regels niet in uw externe proxy.

Voeg eventuele aanvullende metadatahosts of gereserveerde bereiken toe die uw cloudprovider of netwerkplatform documenteert.

Beperkingen

• Dit biedt dekking op procesniveau voor JavaScript HTTP/WebSocket-clients en is geen netwerksandbox op besturingssysteemniveau.
• Onbewerkte net-, tls- en http2-sockets, native add-ons en niet-OpenClaw-subprocessen kunnen routering op Node-niveau omzeilen, tenzij ze proxyomgevingsvariabelen overnemen en respecteren. Afgesplitste OpenClaw-subproces-CLI's nemen de beheerde proxy-URL en de status van proxy.loopbackMode over.
• Lokale WebUI's van gebruikers en lokale modelservers vallen niet onder een algemene omzeiling voor het lokale netwerk — voeg ze indien nodig toe aan de toelatingslijst van het proxybeleid van de beheerder. De uitzondering is het beveiligde rechtstreekse pad van de meegeleverde Ollama-provider voor geheugenembeddings, beperkt tot de exacte lokale local loopback-oorsprong van de host uit de geconfigureerde baseUrl; Ollama-hosts op LAN, tailnet, privénetwerken en openbare netwerken gebruiken nog steeds de beheerde proxy.
• Rechtstreeks doorsturen naar upstream door de lokale debugproxy (voor proxyaanvragen en CONNECT-tunnels) is standaard uitgeschakeld wanneer de beheerde proxymodus actief is; schakel dit alleen in voor goedgekeurde lokale diagnostiek.
• OpenClaw inspecteert, test of certificeert uw proxybeleid niet. Behandel wijzigingen in het proxybeleid als beveiligingsgevoelige operationele wijzigingen.