Netzwerk-Proxy

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.

​

Warum einen Proxy verwenden

• Zentrale Policy: Pflegen Sie eine Egress-Policy, statt sich darauf zu verlassen, dass jede HTTP-Aufrufstelle der Anwendung die Netzwerkregeln korrekt umsetzt.
• Prüfungen beim Verbindungsaufbau: Bewerten Sie das Ziel nach der DNS-Auflösung und unmittelbar bevor der Proxy die Upstream-Verbindung öffnet.
• Schutz vor DNS-Rebinding: Verringern Sie die Lücke zwischen einer DNS-Prüfung auf Anwendungsebene und der tatsächlichen ausgehenden Verbindung.
• Breitere JavaScript-Abdeckung: Leiten Sie gewöhnliche fetch-, node:http-, node:https-, WebSocket-, axios-, got-, node-fetch- und ähnliche Clients über denselben Pfad.
• Prüfbarkeit: Protokollieren Sie erlaubte und abgelehnte Ziele an der Egress-Grenze.
• Betriebliche Kontrolle: Erzwingen Sie Zielregeln, Netzwerksegmentierung, Rate-Limits oder ausgehende Allowlists, ohne OpenClaw neu zu bauen.

​

Wie OpenClaw Traffic leitet

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-Dispatcher-Routing deckt fetch, Undici-basierte Clients und Transporte ab, die ihren eigenen Undici-Dispatcher bereitstellen.
• global-agent-Routing deckt Node-Core-Aufrufer von node:http und node:https ab, einschließlich vieler Bibliotheken, die auf http.request, https.request, http.get und https.get aufbauen. Der verwaltete Proxy-Modus erzwingt diesen globalen Agent, damit explizite Node-HTTP-Agents den Operator-Proxy nicht versehentlich umgehen.

​

Verwandte Proxy-Begriffe

• proxy.enabled / proxy.proxyUrl: ausgehendes Forward-Proxy-Routing für OpenClaw-Laufzeit-Egress. Diese Seite dokumentiert diese Funktion.
• gateway.auth.mode: "trusted-proxy": eingehende identitätsbewusste Reverse-Proxy-Authentifizierung für Gateway-Zugriff. Siehe Vertrauenswürdige Proxy-Authentifizierung.
• openclaw proxy: lokaler Debug-Proxy und Capture-Inspector für Entwicklung und Support. Siehe openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: Opt-in für web_fetch, damit ein operatorgesteuerter HTTP(S)-Umgebungsproxy DNS auflösen kann, während die standardmäßig strikte DNS-Pinning- und Hostname-Policy beibehalten wird. Siehe Web fetch.
• Kanal- oder Provider-spezifische Proxy-Einstellungen: eigentümerspezifische Overrides für einen bestimmten Transport. Bevorzugen Sie den verwalteten Netzwerk-Proxy, wenn das Ziel zentrale Egress-Kontrolle über die Laufzeit hinweg ist.

​

Konfiguration

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 (Standard): OpenClaw registriert die Gateway-Loopback-Autorität im aktiven global-agent-NO_PROXY-Controller, damit lokaler Gateway-WebSocket-Traffic direkt verbinden kann. Benutzerdefinierte Loopback-Gateway-Ports funktionieren, weil Host und Port der aktiven Gateway-URL registriert werden.
• proxy: OpenClaw registriert keine Gateway-Loopback-NO_PROXY-Autorität, sodass lokaler Gateway-Traffic über den verwalteten Proxy gesendet wird. Wenn der Proxy remote ist, muss er spezielles Routing für den Loopback-Dienst des OpenClaw-Hosts bereitstellen, etwa durch Zuordnung zu einem vom Proxy erreichbaren Hostnamen, einer IP oder einem Tunnel. Standardmäßige Remote-Proxys lösen 127.0.0.1 und localhost vom Proxy-Host aus auf, nicht vom OpenClaw-Host.
• block: OpenClaw verweigert Loopback-Gateway-Control-Plane-Verbindungen, bevor ein Socket geöffnet wird.

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

​

Proxy-Anforderungen

• Nur an Loopback oder eine private vertrauenswürdige Schnittstelle bindet.
• Den Zugriff so beschränkt, dass nur der OpenClaw-Prozess, Host, Container oder das Dienstkonto ihn verwenden kann.
• Ziele selbst auflöst und Ziel-IPs nach der DNS-Auflösung blockiert.
• Die Policy beim Verbindungsaufbau sowohl für einfache HTTP-Anfragen als auch für HTTPS-CONNECT-Tunnel anwendet.
• Zielbasierte Bypässe für Loopback-, private, linklokale, Metadaten-, Multicast-, reservierte oder Dokumentationsbereiche ablehnt.
• Hostname-Allowlists vermeidet, es sei denn, Sie vertrauen dem DNS-Auflösungspfad vollständig.
• Ziel, Entscheidung, Status und Grund protokolliert, ohne Anfragetexte, Autorisierungs-Header, Cookies oder andere Geheimnisse zu protokollieren.
• Proxy-Policy unter Versionskontrolle hält und Änderungen wie sicherheitssensitive Konfiguration prüft.

​

Empfohlene blockierte Ziele

​

Validierung

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

​

Grenzen

• Der Proxy verbessert die Abdeckung für prozesslokale JavaScript-HTTP- und WebSocket-Clients, ist aber keine Netzwerksandbox auf Betriebssystemebene.
• Gateway-Loopback-Traffic der Control Plane verwendet standardmäßig eine direkte lokale Umgehung über proxy.loopbackMode: "gateway-only". OpenClaw implementiert diese Umgehung, indem die aktive Gateway-Loopback-Autorität im verwalteten global-agent-NO_PROXY-Controller registriert wird. Betreiber können proxy.loopbackMode: "proxy" setzen, um Gateway-Loopback-Traffic über den verwalteten Proxy zu senden, oder proxy.loopbackMode: "block", um Loopback-Gateway-Verbindungen zu verweigern. Siehe Gateway-Loopback-Modus für den Hinweis zum Remote-Proxy.
• Roh-net-, tls- und http2-Sockets, native Addons und Nicht-OpenClaw-Kindprozesse können Proxy-Routing auf Node-Ebene umgehen, sofern sie Proxy-Umgebungsvariablen nicht erben und beachten. Geforkte OpenClaw-Child-CLIs erben die verwaltete Proxy-URL und den Zustand von proxy.loopbackMode.
• IRC ist ein Roh-TCP/TLS-Kanal außerhalb des vom Betreiber verwalteten Forward-Proxy-Routings. Setzen Sie in Bereitstellungen, die sämtlichen ausgehenden Datenverkehr über diesen Forward Proxy erzwingen, channels.irc.enabled=false, sofern direkter IRC-Egress nicht ausdrücklich genehmigt ist.
• Der lokale Debug-Proxy ist Diagnosewerkzeug, und seine direkte Upstream-Weiterleitung für Proxy-Anfragen und CONNECT-Tunnel ist standardmäßig deaktiviert, solange der verwaltete Proxy-Modus aktiv ist; aktivieren Sie direkte Weiterleitung nur für genehmigte lokale Diagnosen.
• Lokale WebUIs der Benutzer und lokale Modellserver sollten bei Bedarf in der Betreiber-Proxy-Richtlinie auf die Allowlist gesetzt werden; OpenClaw stellt dafür keine allgemeine Umgehung des lokalen Netzwerks bereit.
• Die Proxy-Umgehung für die Gateway-Control-Plane ist absichtlich auf localhost und wörtliche Loopback-IP-URLs begrenzt. Verwenden Sie ws://127.0.0.1:18789, ws://[::1]:18789 oder ws://localhost:18789 für direkte lokale Gateway-Control-Plane-Verbindungen; andere Hostnamen werden wie gewöhnlicher hostnamenbasierter Traffic geroutet.
• OpenClaw prüft, testet oder zertifiziert Ihre Proxy-Richtlinie nicht.
• Behandeln Sie Änderungen an der Proxy-Richtlinie als sicherheitssensible betriebliche Änderungen.