Proxy sieciowy

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Dlaczego warto używać proxy

• Centralna polityka: utrzymuj jedną politykę ruchu wychodzącego zamiast polegać na tym, że każde miejsce wywołań HTTP w aplikacji poprawnie zastosuje reguły sieciowe.
• Kontrole w momencie łączenia: oceniaj miejsce docelowe po rozpoznaniu DNS i bezpośrednio przed otwarciem przez proxy połączenia upstream.
• Obrona przed DNS rebinding: zmniejsz lukę między sprawdzeniem DNS na poziomie aplikacji a faktycznym połączeniem wychodzącym.
• Szersze pokrycie JavaScript: kieruj zwykłe klienty fetch, node:http, node:https, WebSocket, axios, got, node-fetch i podobne przez tę samą ścieżkę.
• Audytowalność: rejestruj dozwolone i odrzucone miejsca docelowe na granicy ruchu wychodzącego.
• Kontrola operacyjna: wymuszaj reguły miejsc docelowych, segmentację sieci, limity szybkości lub allowlisty ruchu wychodzącego bez przebudowy OpenClaw.

​

Jak OpenClaw kieruje ruch

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

• Kierowanie dyspozytorem Undici obejmuje fetch, klienty oparte na undici oraz transporty, które udostępniają własny dyspozytor undici.
• Kierowanie global-agent obejmuje wywołujących z rdzenia Node node:http i node:https, w tym wiele bibliotek zbudowanych na http.request, https.request, http.get i https.get. Tryb zarządzanego proxy wymusza tego globalnego agenta, aby jawne agenty HTTP Node nie mogły przypadkowo ominąć proxy operatora.

​

Powiązane terminy proxy

• proxy.enabled / proxy.proxyUrl: kierowanie wychodzące przez forward-proxy dla ruchu OpenClaw w czasie wykonywania. Ta strona dokumentuje tę funkcję.
• gateway.auth.mode: "trusted-proxy": przychodzące uwierzytelnianie reverse proxy świadome tożsamości dla dostępu do Gateway. Zobacz Uwierzytelnianie zaufanego proxy.
• openclaw proxy: lokalne proxy debugowania i inspektor przechwytywania do programowania i wsparcia. Zobacz openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy: opcjonalne włączenie dla web_fetch, aby pozwolić kontrolowanemu przez operatora proxy HTTP(S) ze środowiska rozwiązywać DNS przy zachowaniu domyślnego ścisłego przypinania DNS i polityki nazw hostów. Zobacz Pobieranie z sieci.
• Ustawienia proxy specyficzne dla kanału lub dostawcy: nadpisania właściciela dla konkretnego transportu. Preferuj zarządzane proxy sieciowe, gdy celem jest centralna kontrola ruchu wychodzącego w całym środowisku uruchomieniowym.

​

Konfiguracja

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

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

​

Tryb loopback Gateway

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

• gateway-only (domyślne): OpenClaw rejestruje autorytet loopback Gateway w aktywnym kontrolerze NO_PROXY global-agent, aby lokalny ruch WebSocket Gateway mógł łączyć się bezpośrednio. Niestandardowe porty Gateway loopback działają, ponieważ host i port aktywnego URL Gateway są rejestrowane.
• proxy: OpenClaw nie rejestruje autorytetu NO_PROXY dla loopback Gateway, więc lokalny ruch Gateway jest wysyłany przez zarządzane proxy. Jeśli proxy jest zdalne, musi zapewniać specjalne kierowanie do usługi loopback hosta OpenClaw, na przykład mapowanie jej na nazwę hosta, adres IP lub tunel osiągalny przez proxy. Standardowe zdalne proxy rozwiązują 127.0.0.1 i localhost z hosta proxy, a nie z hosta OpenClaw.
• block: OpenClaw odmawia połączeń płaszczyzny sterowania Gateway przez loopback przed otwarciem gniazda.

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

​

Wymagania dotyczące proxy

• Wiązało się tylko z loopback lub prywatnym zaufanym interfejsem.
• Ograniczało dostęp tak, aby mogły z niego korzystać tylko proces, host, kontener lub konto usługi OpenClaw.
• Samodzielnie rozwiązywało miejsca docelowe i blokowało docelowe adresy IP po rozpoznaniu DNS.
• Stosowało politykę w momencie łączenia zarówno dla zwykłych żądań HTTP, jak i tuneli HTTPS CONNECT.
• Odrzucało obejścia oparte na miejscu docelowym dla loopback, prywatnych, link-local, metadanych, multicast, zarezerwowanych lub dokumentacyjnych zakresów.
• Unikało allowlist nazw hostów, chyba że w pełni ufasz ścieżce rozpoznawania DNS.
• Rejestrowało miejsce docelowe, decyzję, status i przyczynę bez rejestrowania treści żądań, nagłówków autoryzacji, cookies ani innych sekretów.
• Utrzymywało politykę proxy pod kontrolą wersji i przeglądało zmiany jak konfigurację wrażliwą na bezpieczeństwo.

​

Zalecane blokowane miejsca docelowe

​

Walidacja

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

​

Ograniczenia

• Proxy poprawia pokrycie dla lokalnych w procesie klientów JavaScript HTTP i WebSocket, ale nie jest sieciowym sandboxem na poziomie systemu operacyjnego.
• Ruch płaszczyzny sterowania Gateway przez loopback domyślnie korzysta z bezpośredniego lokalnego obejścia przez proxy.loopbackMode: "gateway-only". OpenClaw implementuje to obejście przez zarejestrowanie aktywnego urzędu loopback Gateway w zarządzanym kontrolerze global-agent NO_PROXY. Operatorzy mogą ustawić proxy.loopbackMode: "proxy", aby wysyłać ruch loopback Gateway przez zarządzane proxy, albo proxy.loopbackMode: "block", aby odmawiać połączeń loopback Gateway. Zobacz tryb loopback Gateway, aby poznać zastrzeżenie dotyczące zdalnego proxy.
• Surowe gniazda net, tls i http2, natywne dodatki oraz procesy potomne spoza OpenClaw mogą omijać trasowanie proxy na poziomie Node, chyba że dziedziczą i respektują zmienne środowiskowe proxy. Rozwidlonie potomne CLI OpenClaw dziedziczą zarządzany adres URL proxy oraz stan proxy.loopbackMode.
• IRC to surowy kanał TCP/TLS poza trasowaniem przez zarządzane przez operatora proxy pośredniczące. We wdrożeniach wymagających, aby cały ruch wychodzący przechodził przez to proxy pośredniczące, ustaw channels.irc.enabled=false, chyba że bezpośredni ruch wychodzący IRC jest jawnie zatwierdzony.
• Lokalne proxy debugowania jest narzędziem diagnostycznym, a jego bezpośrednie przekazywanie upstream dla żądań proxy i tuneli CONNECT jest domyślnie wyłączone, gdy aktywny jest zarządzany tryb proxy; włączaj bezpośrednie przekazywanie tylko dla zatwierdzonej lokalnej diagnostyki.
• Lokalne WebUI użytkownika i lokalne serwery modeli powinny zostać umieszczone na liście dozwolonych w polityce proxy operatora, gdy jest to potrzebne; OpenClaw nie udostępnia dla nich ogólnego obejścia sieci lokalnej.
• Obejście proxy płaszczyzny sterowania Gateway jest celowo ograniczone do localhost i dosłownych adresów URL IP loopback. Użyj ws://127.0.0.1:18789, ws://[::1]:18789 albo ws://localhost:18789 dla lokalnych bezpośrednich połączeń płaszczyzny sterowania Gateway; inne nazwy hostów są trasowane jak zwykły ruch oparty na nazwie hosta.
• OpenClaw nie sprawdza, nie testuje ani nie certyfikuje Twojej polityki proxy.
• Traktuj zmiany polityki proxy jako operacyjne zmiany wrażliwe pod względem bezpieczeństwa.