Netzwerk-Proxy

OpenClaw kann HTTP- und WebSocket-Datenverkehr zur Laufzeit über einen vom Betreiber verwalteten Forward-Proxy leiten. Dies ist eine optionale mehrschichtige Schutzmaßnahme: zentrale Kontrolle des ausgehenden Datenverkehrs, stärkerer SSRF-Schutz und Überprüfbarkeit der Ziele an der Netzwerkgrenze. Da der Proxy das Ziel beim Verbindungsaufbau auswertet, also nach der DNS-Auflösung und unmittelbar bevor er die Upstream-Verbindung öffnet, verkleinert er außerdem das Zeitfenster, das ein DNS-Rebinding-Angriff zwischen einer früheren DNS-Prüfung auf Anwendungsebene und der tatsächlichen ausgehenden Verbindung ausnutzt. Eine einheitliche Proxy-Richtlinie bietet Betreibern zudem eine zentrale Stelle, um Zielregeln, Netzwerksegmentierung, Ratenbegrenzungen oder Positivlisten für ausgehende Verbindungen durchzusetzen, ohne OpenClaw neu erstellen zu müssen.

OpenClaw liefert keinen Proxy mit, lädt keinen herunter, startet und konfiguriert keinen und zertifiziert keinen Proxy. Sie betreiben die für Ihre Umgebung geeignete Proxy-Technologie; OpenClaw leitet seine eigenen HTTP- und WebSocket-Clients darüber.

Konfiguration

proxy:  proxyUrl: http://127.0.0.1:3128

Sie können die URL auch über die Umgebung festlegen:

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

proxy.proxyUrl hat Vorrang vor OPENCLAW_PROXY_URL. Eine konfigurierte URL aktiviert die verwaltete Proxy-Weiterleitung; wenn beide URLs entfernt werden, wird sie deaktiviert.

Speichern Sie bei verwalteten Gateway-Diensten die URL in der Konfiguration, damit sie eine Neuinstallation überdauert, anstatt sich auf die Umgebung eines Vordergrundprozesses zu verlassen:

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

Der Umgebungs-Fallback OPENCLAW_PROXY_URL eignet sich am besten für Vordergrundausführungen. Um ihn mit einem installierten Dienst zu verwenden, tragen Sie ihn in die persistente Umgebung des Dienstes ein ($OPENCLAW_STATE_DIR/.env, standardmäßig ~/.openclaw/.env) und installieren Sie den Dienst anschließend neu, damit launchd/systemd/Geplante Aufgaben ihn übernimmt.

HTTPS-Proxy-Endpunkt mit privater CA

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

proxy.tls.caFile überprüft das eigene TLS-Zertifikat des Proxy-Endpunkts. Dies ist weder eine Vertrauenseinstellung für einen MITM am Ziel noch ein Clientzertifikat oder ein Ersatz für die Zielrichtlinie des Proxys. Verwenden Sie stattdessen NODE_EXTRA_CA_CERTS nur, wenn der gesamte Node-Prozess bereits beim Start einer zusätzlichen CA vertrauen muss (zum Beispiel bei einem unternehmensweiten TLS-Inspektionssystem, das jedes HTTPS-Zielzertifikat neu signiert) — diese Variable gilt prozessweit und muss vor dem Start von Node gesetzt werden. Daher kann OpenClaw sie nicht während der Ausführung anwenden, wie dies bei proxy.tls.caFile möglich ist. Bevorzugen Sie proxy.tls.caFile für das Vertrauen in HTTPS-Proxy-Endpunkte: Es ist auf die verwaltete Proxy-Weiterleitung beschränkt, statt für den gesamten Prozess zu gelten.

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

Funktionsweise der Weiterleitung

Mit einer gültigen Proxy-URL leiten geschützte Laufzeitprozesse (openclaw gateway run, openclaw node run, openclaw agent --local) normalen ausgehenden HTTP- und WebSocket-Datenverkehr über den Proxy:

OpenClaw-Prozess  fetch, node:http, node:https, WebSocket-Clients  -> Betreiber-Proxy -> Ziel

Intern installiert OpenClaw Proxyline als prozessweite Laufzeit für die Weiterleitung. Sie deckt fetch, auf undici basierende Clients, node:http/node:https, gängige WebSocket-Clients und durch Hilfsfunktionen erstellte CONNECT-Tunnel ab und ersetzt vom Aufrufer bereitgestellte Node-HTTP-Agents, sodass explizite Agents (einschließlich axios, got, node-fetch und ähnlicher auf Node-Agents basierender Clients) den Proxy nicht unbemerkt umgehen können.

Das Schema der Proxy-URL beschreibt die Verbindung von OpenClaw zum Proxy, nicht zum endgültigen Ziel:

• http://proxy.example:3128 — unverschlüsselte TCP-Verbindung zum Proxy; OpenClaw sendet HTTP-Proxy-Anfragen, einschließlich CONNECT für HTTPS-Ziele.
• https://proxy.example:8443 — OpenClaw baut eine TLS-Verbindung zum Proxy selbst auf (einschließlich Überprüfung des Proxy-Zertifikats) und sendet anschließend innerhalb dieser Sitzung HTTP-Proxy-Anfragen.

Ziel-TLS ist unabhängig von TLS am Proxy-Endpunkt: Bei einem HTTPS-Ziel fordert OpenClaw den Proxy immer zu einem CONNECT-Tunnel auf und startet Ziel-TLS durch diesen Tunnel.

Während der Proxy aktiv ist, löscht OpenClaw no_proxy/NO_PROXY. Diese Umgehungslisten sind zielbasiert; würden localhost oder 127.0.0.1 darin verbleiben, könnten SSRF-Ziele den Proxy vollständig umgehen. Beim Herunterfahren stellt OpenClaw die vorherige Proxy-Umgebung wieder her und setzt den zwischengespeicherten Weiterleitungsstatus zurück.

Einige Plugins besitzen einen benutzerdefinierten Transport, der auch bei aktiver prozessweiter Weiterleitung eine eigene Proxy-Anbindung benötigt. Der Bot-API-Client von Telegram verwendet einen eigenen HTTP/1-undici-Dispatcher und berücksichtigt separat die Proxy-Umgebung des Prozesses sowie den Fallback OPENCLAW_PROXY_URL.

Gateway-Loopback-Modus

Lokale Clients der Gateway-Steuerungsebene verbinden sich normalerweise mit einem Loopback-WebSocket wie ws://127.0.0.1:18789. proxy.loopbackMode steuert, ob dieser Datenverkehr den verwalteten Proxy umgeht:

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

Ein konfiguriertes proxyUrl oder OPENCLAW_PROXY_URL aktiviert die verwaltete Weiterleitung. Legen Sie proxy.enabled: false nur als erweiterte Abwahloption fest, bei der die URL gespeichert bleibt, ohne sie zu aktivieren.

Die Umgehung für die Gateway-Steuerungsebene ist auf localhost und URLs mit wörtlichen Loopback-IP-Adressen beschränkt — verwenden Sie ws://127.0.0.1:18789, ws://[::1]:18789 oder ws://localhost:18789. Andere Hostnamen werden wie gewöhnlicher Datenverkehr weitergeleitet.

Container

Für openclaw --container ...-Befehle leitet OpenClaw OPENCLAW_PROXY_URL an die auf den Container ausgerichtete untergeordnete CLI weiter, wenn die Variable gesetzt ist. Die URL muss aus dem Container heraus erreichbar sein — 127.0.0.1 bezeichnet dort den Container selbst, nicht den Host. OpenClaw lehnt Loopback-Proxy-URLs für auf Container ausgerichtete Befehle ab, sofern Sie nicht OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1 festlegen, um diese Prüfung ausdrücklich zu überschreiben.

Verwandte Proxy-Begriffe

• proxy.enabled / proxy.proxyUrl — ausgehende Forward-Proxy-Weiterleitung für Laufzeitdatenverkehr. Diese Seite.
• gateway.auth.mode: "trusted-proxy" — eingehende identitätsbezogene Reverse-Proxy-Authentifizierung für den Gateway-Zugriff. Siehe Authentifizierung über vertrauenswürdige Proxys.
• openclaw proxy — lokaler Debug-Proxy und Erfassungsinspektor für Entwicklung und Support. Siehe openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy — Opt-in für web_fetch, damit ein vom Betreiber kontrollierter HTTP(S)-Umgebungs-Proxy DNS auflösen kann, während standardmäßig eine strikte DNS-Bindung und Hostnamenrichtlinie beibehalten werden. Siehe Webabruf.
• Kanal- oder Provider-spezifische Proxy-Einstellungen — besitzerspezifische Überschreibungen für einen einzelnen Transport. Bevorzugen Sie den verwalteten Netzwerk-Proxy für eine zentrale Kontrolle des ausgehenden Datenverkehrs über die gesamte Laufzeit hinweg.

Proxy validieren

Die Zielrichtlinie des Proxys bildet die eigentliche Sicherheitsgrenze; OpenClaw kann nicht überprüfen, ob Ihr Proxy die richtigen Ziele blockiert. Konfigurieren Sie ihn so, dass er:

• nur an Loopback oder eine private vertrauenswürdige Schnittstelle bindet, die ausschließlich für den OpenClaw-Prozess/-Host/-Container oder das Dienstkonto erreichbar ist.
• Ziele selbst auflöst und nach der DNS-Auflösung beim Verbindungsaufbau anhand der IP blockiert, sowohl für unverschlüsseltes HTTP als auch für HTTPS-CONNECT-Tunnel.
• zielbasierte Umgehungen für Loopback-, private, Link-Local-, Metadaten-, Multicast-, reservierte und Dokumentationsadressbereiche ablehnt.
• Positivlisten für Hostnamen vermeidet, sofern Sie dem DNS-Auflösungspfad nicht vollständig vertrauen.
• Ziel, Entscheidung, Status und Begründung protokolliert — niemals Anfragetexte, Autorisierungsheader, Cookies oder andere Geheimnisse.
• die Richtlinie unter Versionskontrolle hält und Änderungen als sicherheitskritisch überprüft.

Validieren Sie von demselben Host, Container oder Dienstkonto aus, unter dem OpenClaw ausgeführt wird:

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

Mit einem HTTPS-Proxy-Endpunkt mit privater CA:

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

Wenn weder eine Konfiguration noch eine Umgebungsvariable oder ein Wert für --proxy-url verfügbar ist, meldet der Befehl ein Konfigurationsproblem; übergeben Sie --proxy-url für eine einmalige Vorabprüfung, bevor Sie die Konfiguration ändern.

Ohne --allowed-url/--denied-url gelten folgende Standardprüfungen: https://example.com/ muss erfolgreich sein, und ein temporärer Loopback-Canary-Server, den der Proxy nicht erreichen darf, muss blockiert werden. Die Loopback-Prüfung ist bei einem Transportfehler oder bei einer Nicht-2xx-Antwort ohne das ausführungsspezifische Token des Canary erfolgreich. Sie schlägt bei einer 2xx-Antwort ohne das Token fehl (ein unerwarteter Erfolg von etwas anderem als dem Canary) und insbesondere bei jeder Antwort mit dem passenden Token, da dies beweist, dass der Proxy tatsächlich ein Loopback-Ziel weitergeleitet hat, das er hätte ablehnen müssen. Benutzerdefinierte --denied-url-Ziele verfügen über kein solches Canary-Token und verwenden daher ein Fail-Closed-Verhalten: Jede HTTP-Antwort gilt als erreichbar (Fehler), und ein Transportfehler wird als nicht eindeutig statt als nachweislich blockiert gemeldet, da OpenClaw nicht bestätigen kann, ob Ihr Proxy einen erreichbaren Ursprung abgelehnt hat oder ob ein anderer Fehler aufgetreten ist. --apns-reachable sendet absichtlich ein ungültiges Provider-Token, sodass eine 403 InvalidProviderToken-Antwort als Nachweis gilt, dass der Tunnel Apple erreicht hat. Der Befehl wird bei jedem Validierungsfehler mit 1 beendet; Anmeldedaten in der Proxy-URL werden sowohl in der Text- als auch in der JSON-Ausgabe unkenntlich gemacht.

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

Manuelle curl-Prüfung (die öffentliche Anfrage sollte erfolgreich sein; die Loopback- und Metadatenanfragen sollten vom Proxy selbst blockiert werden — curl allein kann eine Ablehnung durch den Proxy nicht von einem nicht erreichbaren Ursprung unterscheiden, wie dies der integrierte Canary von openclaw proxy validate kann):

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/

Empfohlene blockierte Ziele

Ausgangssperrliste für jeden Forward-Proxy, jede Firewall oder jede Egress-Richtlinie. Der OpenClaw-eigene SSRF-Klassifizierer befindet sich in src/infra/net/ssrf.ts und packages/net-policy/src/ip.ts (BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, das RFC-2544-Benchmark-Präfix und die Behandlung eingebetteter IPv4-Adressen für NAT64-/6to4-/Teredo-/ISATAP-/IPv4-gemappte Formen) — nützliche Referenzen, OpenClaw exportiert oder erzwingt diese Regeln jedoch nicht in Ihrem externen Proxy.

Fügen Sie alle zusätzlichen Metadatenhosts oder reservierten Bereiche hinzu, die Ihr Cloud-Provider oder Ihre Netzwerkplattform dokumentiert.

Einschränkungen

• Dies bietet Abdeckung auf Prozessebene für JavaScript-HTTP-/WebSocket-Clients, keine Netzwerk-Sandbox auf Betriebssystemebene.
• Rohe net-, tls- und http2-Sockets, native Add-ons sowie untergeordnete Prozesse außerhalb von OpenClaw können das Routing auf Node-Ebene umgehen, sofern sie Proxy-Umgebungsvariablen nicht erben und berücksichtigen. Abgespaltene untergeordnete OpenClaw-CLIs erben die verwaltete Proxy-URL und den Zustand von proxy.loopbackMode.
• Lokale WebUIs der Benutzer und lokale Modellserver werden nicht durch eine allgemeine Umgehung für lokale Netzwerke abgedeckt — nehmen Sie sie bei Bedarf in die Zulassungsliste der Proxy-Richtlinie des Betreibers auf. Eine Ausnahme bildet der geschützte direkte Pfad des gebündelten Ollama-Providers für Memory-Embeddings, der auf den exakten hostlokalen Loopback-Ursprung aus dessen konfiguriertem baseUrl beschränkt ist; Ollama-Hosts im LAN, Tailnet, privaten Netzwerk und öffentlichen Netzwerk verwenden weiterhin den verwalteten Proxy.
• Die direkte Upstream-Weiterleitung des lokalen Debug-Proxys (für Proxy-Anfragen und CONNECT-Tunnel) ist standardmäßig deaktiviert, solange der verwaltete Proxy-Modus aktiv ist; aktivieren Sie sie nur für genehmigte lokale Diagnosen.
• OpenClaw überprüft, testet oder zertifiziert Ihre Proxy-Richtlinie nicht. Behandeln Sie Änderungen an der Proxy-Richtlinie als sicherheitskritische betriebliche Änderungen.