Перейти до основного вмісту
OpenClaw може маршрутизувати runtime HTTP- і WebSocket-трафік через керований оператором forward proxy. Це необов’язковий додатковий рівень захисту для розгортань, яким потрібні централізований контроль вихідного трафіку, сильніший захист від SSRF і краща аудитованість мережі. OpenClaw не постачає, не завантажує, не запускає, не налаштовує й не сертифікує proxy. Ви запускаєте технологію proxy, яка підходить для вашого середовища, а OpenClaw маршрутизує через неї звичайні локальні для процесу HTTP- і WebSocket-клієнти.

​
Навіщо використовувати proxy

Proxy дає операторам одну точку мережевого контролю для вихідного HTTP- і WebSocket-трафіку. Це може бути корисно навіть поза посиленням захисту від SSRF:
  • Централізована політика: підтримуйте одну політику вихідного трафіку замість покладання на те, що кожна точка HTTP-виклику в застосунку правильно застосує мережеві правила.
  • Перевірки під час підключення: оцінюйте призначення після DNS-резолюції та безпосередньо перед тим, як proxy відкриє upstream-з’єднання.
  • Захист від DNS rebinding: зменшуйте розрив між DNS-перевіркою на рівні застосунку та фактичним вихідним з’єднанням.
  • Ширше покриття JavaScript: маршрутизуйте звичайні fetch, node:http, node:https, WebSocket, axios, got, node-fetch і подібні клієнти через один і той самий шлях.
  • Аудитованість: журналюйте дозволені й відхилені призначення на межі вихідного трафіку.
  • Операційний контроль: застосовуйте правила призначення, сегментацію мережі, обмеження швидкості або allowlist-и вихідного трафіку без повторного збирання OpenClaw.
Маршрутизація через proxy є захисним обмеженням рівня процесу для звичайного вихідного HTTP- і WebSocket-трафіку. Вона дає операторам fail-closed шлях для маршрутизації підтримуваних JavaScript HTTP-клієнтів через власний фільтрувальний proxy, але не є мережевою пісочницею рівня ОС і не змушує OpenClaw сертифікувати політику призначень proxy.

​
Як OpenClaw маршрутизує трафік

Коли proxy.enabled=true і налаштовано URL proxy, захищені runtime-процеси, як-от openclaw gateway run, openclaw node run і openclaw agent --local, маршрутизують звичайний вихідний HTTP- і WebSocket-трафік через налаштований proxy: 
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
Публічний контракт — це поведінка маршрутизації, а не внутрішні Node hooks, використані для її реалізації. Клієнти WebSocket площини керування OpenClaw Gateway використовують вузький прямий шлях для local loopback Gateway RPC-трафіку, коли URL Gateway використовує localhost або буквальну loopback IP-адресу, як-от 127.0.0.1 чи [::1]. Цей шлях площини керування має мати змогу досягати loopback Gateway навіть тоді, коли proxy оператора блокує loopback-призначення. Звичайні runtime HTTP- і WebSocket-запити й надалі використовують налаштований proxy. Внутрішньо OpenClaw встановлює Proxyline як runtime маршрутизації рівня процесу для цієї функції. Proxyline охоплює fetch, клієнти на базі undici, викликачів Node core node:http / node:https, поширені WebSocket-клієнти та створені допоміжними засобами CONNECT-тунелі. Керований режим proxy замінює надані викликачем HTTP-агенти Node, щоб явні агенти випадково не обходили proxy оператора. Деякі plugins володіють власними транспортами, яким потрібне явне підключення proxy навіть за наявності маршрутизації рівня процесу. Наприклад, транспорт Bot API для Telegram використовує власний HTTP/1 undici dispatcher і тому враховує env proxy процесу плюс керований fallback OPENCLAW_PROXY_URL у цьому owner-specific транспортному шляху. Сам URL proxy може використовувати http:// або https://. Ці схеми описують з’єднання від OpenClaw до endpoint proxy:
  • http://proxy.example:3128: OpenClaw відкриває звичайне TCP-з’єднання до forward proxy і надсилає HTTP proxy-запити, включно з CONNECT для HTTPS-призначень.
  • https://proxy.example:8443: OpenClaw відкриває TLS до endpoint proxy, перевіряє сертифікат proxy, а потім надсилає HTTP proxy-запити всередині цієї TLS-сесії.
HTTPS призначення відокремлений від TLS endpoint proxy. Для HTTPS-призначення OpenClaw все одно просить proxy створити HTTP-тунель CONNECT, а потім запускає TLS призначення через цей тунель. Поки proxy активний, OpenClaw очищає no_proxy і NO_PROXY. Ці списки обходу базуються на призначенні, тому залишені там localhost або 127.0.0.1 дозволили б високоризиковим SSRF-цілям пропустити фільтрувальний proxy. Під час завершення роботи OpenClaw відновлює попереднє proxy-середовище та скидає кешований стан маршрутизації процесу.

​
Пов’язані терміни proxy

  • proxy.enabled / proxy.proxyUrl: маршрутизація outbound forward-proxy для runtime-вихідного трафіку OpenClaw. Ця сторінка документує цю функцію.
  • gateway.auth.mode: "trusted-proxy": вхідна reverse-proxy автентифікація з урахуванням ідентичності для доступу до Gateway. Див. Автентифікація trusted proxy.
  • openclaw proxy: локальний debug proxy та інспектор захоплення для розробки й підтримки. Див. openclaw proxy.
  • tools.web.fetch.useTrustedEnvProxy: opt-in для web_fetch, що дозволяє керованому оператором HTTP(S) env proxy виконувати DNS-резолюцію, зберігаючи стандартні суворі DNS pinning і політику hostname. Див. Web fetch.
  • Налаштування proxy для окремого каналу або провайдера: owner-specific перевизначення для конкретного транспорту. Надавайте перевагу керованому мережевому proxy, коли мета — централізований контроль вихідного трафіку в усьому runtime.

​
Конфігурація

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128
Для HTTPS endpoint proxy з приватним proxy CA: 
proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem
Ви також можете надати URL через середовище, залишивши proxy.enabled=true у конфігурації: 
OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run
proxy.proxyUrl має пріоритет над OPENCLAW_PROXY_URL.

​
Режим loopback для Gateway

Локальні клієнти площини керування Gateway зазвичай підключаються до loopback WebSocket, наприклад ws://127.0.0.1:18789. Використовуйте proxy.loopbackMode, щоб вибрати, як поводяться винятки loopback managed-proxy, поки керований proxy активний: 
proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128
  loopbackMode: gateway-only # gateway-only, proxy, or block
  • gateway-only (стандартно): OpenClaw реєструє loopback authority Gateway у керованій політиці обходу Proxyline, щоб локальний WebSocket-трафік Gateway міг підключатися напряму. Власні loopback-порти Gateway працюють, бо реєструються host і port активного URL Gateway. Вбудований browser plugin також може реєструвати точні локальні CDP readiness і DevTools WebSocket endpoints для керованих браузерів, запущених OpenClaw, а вбудований провайдер embedding пам’яті Ollama може використовувати власний вужчий захищений прямий шлях для точного налаштованого host-local loopback embedding origin.
  • proxy: OpenClaw не реєструє loopback-обходи Gateway або Ollama, тому цей loopback-трафік надсилається через керований proxy. Якщо proxy віддалений, він має забезпечити спеціальну маршрутизацію до loopback-сервісу хоста OpenClaw, наприклад зіставлення його з hostname, IP або tunnel, доступними для proxy. Стандартні віддалені proxy резолвлять 127.0.0.1 і localhost з хоста proxy, а не з хоста OpenClaw.
  • block: OpenClaw відхиляє loopback-з’єднання площини керування Gateway і захищені host-local embedding loopback-з’єднання Ollama до відкриття socket.
Якщо enabled=true, але не налаштовано жодного дійсного URL proxy, захищені команди завершують запуск помилкою замість fallback до прямого мережевого доступу. Для керованих служб gateway, запущених через openclaw gateway start, бажано зберігати URL у конфігурації: 
openclaw config set proxy.enabled true
openclaw config set proxy.proxyUrl http://127.0.0.1:3128
openclaw gateway install --force
openclaw gateway start
Fallback через середовище найкраще підходить для запусків у передньому плані. Якщо ви використовуєте його зі встановленою службою, помістіть OPENCLAW_PROXY_URL у довготривале середовище служби, наприклад $OPENCLAW_STATE_DIR/.env або ~/.openclaw/.env, а потім перевстановіть службу, щоб launchd, systemd або Scheduled Tasks запускали gateway з цим значенням. Для команд openclaw --container ... OpenClaw передає OPENCLAW_PROXY_URL у container-targeted дочірній CLI, коли його встановлено. URL має бути доступний зсередини контейнера; 127.0.0.1 посилається на сам контейнер, а не на хост. OpenClaw відхиляє loopback URL proxy для container-targeted команд, якщо ви явно не перевизначите цю safety check.

​
Вимоги до proxy

Політика proxy є межею безпеки. OpenClaw не може перевірити, що proxy блокує правильні цілі. Налаштуйте proxy так, щоб він:
  • Прив’язувався лише до loopback або приватного довіреного інтерфейсу.
  • Обмежував доступ так, щоб ним могли користуватися лише процес, хост, контейнер або service account OpenClaw.
  • Самостійно резолвив призначення та блокував IP-адреси призначень після DNS-резолюції.
  • Застосовував політику під час підключення як для звичайних HTTP-запитів, так і для HTTPS-тунелів CONNECT.
  • Відхиляв обходи на основі призначення для loopback, приватних, link-local, metadata, multicast, reserved або documentation діапазонів.
  • Уникав hostname allowlist-ів, якщо ви не повністю довіряєте шляху DNS-резолюції.
  • Журналював призначення, рішення, статус і причину без журналювання тіл запитів, authorization headers, cookies або інших secrets.
  • Тримав політику proxy під version control і переглядав зміни як security-sensitive конфігурацію.

​
Рекомендовані заблоковані призначення

Використовуйте цей denylist як відправну точку для будь-якого forward proxy, firewall або політики вихідного трафіку. Логіка класифікатора рівня застосунку OpenClaw міститься в src/infra/net/ssrf.ts і packages/net-policy/src/ip.ts. Відповідні parity hooks: BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, RFC2544_BENCHMARK_PREFIX і обробка вбудованого IPv4 sentinel для NAT64, 6to4, Teredo, ISATAP і IPv4-mapped форм. Ці файли є корисними reference під час підтримки зовнішньої політики proxy, але OpenClaw автоматично не експортує й не застосовує ці правила у вашому proxy.
Діапазон або хостЧому потрібно блокувати
127.0.0.0/8, localhost, localhost.localdomainIPv4 loopback
::1/128IPv6 loopback
0.0.0.0/8, ::/128Невизначені адреси та адреси цієї мережі
10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16Приватні мережі RFC1918
169.254.0.0/16, fe80::/10Link-local адреси та поширені шляхи хмарних метаданих
169.254.169.254, metadata.google.internalСервіси хмарних метаданих
100.64.0.0/10Спільний адресний простір NAT операторського класу
198.18.0.0/15, 2001:2::/48Діапазони для бенчмаркінгу
192.0.0.0/24, 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32Діапазони спеціального використання та документації
224.0.0.0/4, ff00::/8Multicast
240.0.0.0/4Зарезервований IPv4
fc00::/7, fec0::/10Локальні/приватні діапазони IPv6
100::/64, 2001:20::/28Діапазони IPv6 discard і ORCHIDv2
64:ff9b::/96, 64:ff9b:1::/48Префікси NAT64 із вбудованим IPv4
2002::/16, 2001::/326to4 і Teredo із вбудованим IPv4
::/96, ::ffff:0:0/96IPv4-сумісні та IPv4-відображені IPv6
Якщо ваш хмарний провайдер або мережева платформа документує додаткові хости метаданих чи зарезервовані діапазони, додайте також їх.

​
Валідація

Перевіряйте проксі з того самого хоста, контейнера або сервісного облікового запису, який запускає OpenClaw: 
openclaw proxy validate --proxy-url http://127.0.0.1:3128
Для кінцевої точки HTTPS-проксі, підписаної приватним CA: 
openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem
За замовчуванням, якщо користувацькі призначення не надано, команда перевіряє, що https://example.com/ виконується успішно, і запускає тимчасовий loopback-canary, до якого проксі не має дістатися. Стандартна перевірка заборони проходить, коли проксі повертає не-2xx відповідь відмови або блокує canary через транспортну помилку; вона завершується невдало, якщо успішна відповідь доходить до canary. Якщо проксі не ввімкнено й не налаштовано, валідація повідомляє про проблему конфігурації; використовуйте --proxy-url для одноразової попередньої перевірки перед зміною конфігурації. Використовуйте --allowed-url і --denied-url, щоб перевірити очікування, специфічні для розгортання. Додайте --apns-reachable, щоб також перевірити, що пряма доставка APNs HTTP/2 може відкрити CONNECT-тунель через проксі й отримати відповідь sandbox APNs; проба використовує навмисно недійсний токен провайдера, тому 403 InvalidProviderToken є очікуваним результатом і вважається досяжністю. Користувацькі заборонені призначення працюють за fail-closed принципом: будь-яка HTTP-відповідь означає, що призначення було досяжним через проксі, а будь-яка транспортна помилка повідомляється як непереконлива, бо OpenClaw не може довести, що проксі заблокував досяжне джерело. У разі помилки валідації команда завершується з кодом 1. Використовуйте --json для автоматизації. JSON-вивід містить загальний результат, джерело ефективної конфігурації проксі, будь-які помилки конфігурації та кожну перевірку призначення. Облікові дані URL проксі редагуються в текстовому та JSON-виводі: 
{
  "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: 
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/
Публічний запит має пройти успішно. Loopback-запити та запити метаданих мають блокуватися проксі. Для openclaw proxy validate вбудований loopback-canary може відрізнити відмову проксі від досяжного джерела. Користувацькі перевірки --denied-url не мають такого canary, тому вважайте і HTTP-відповіді, і неоднозначні транспортні помилки помилками валідації, якщо ваш проксі не надає специфічний для розгортання сигнал відмови, який можна перевірити окремо.

​
Довіра до CA проксі

Використовуйте керований proxy.tls.caFile, коли сама кінцева точка проксі використовує сертифікат, підписаний приватним CA: 
proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem
Цей CA використовується для TLS-перевірки кінцевої точки проксі. Це не налаштування довіри MITM для призначення, не клієнтський сертифікат і не заміна політики призначень проксі. Використовуйте NODE_EXTRA_CA_CERTS лише тоді, коли весь процес Node має довіряти додатковому CA від запуску процесу, наприклад коли корпоративна система TLS-інспекції перепідписує сертифікати призначень для кожного HTTPS-клієнта в процесі. NODE_EXTRA_CA_CERTS є глобальним для процесу й має бути наявним до запуску Node. Надавайте перевагу proxy.tls.caFile для довіри до кінцевої точки HTTPS-проксі, бо він обмежений керованою маршрутизацією проксі. Потім увімкніть маршрутизацію проксі OpenClaw: 
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

​
Обмеження

  • Проксі покращує покриття для локальних у процесі JavaScript HTTP- і WebSocket-клієнтів, але не є мережевою пісочницею рівня ОС.
  • Трафік control-plane Gateway через loopback за замовчуванням обходить проксі напряму локально через proxy.loopbackMode: "gateway-only". OpenClaw реалізує цей обхід, реєструючи активний loopback-authority Gateway у керованій політиці обходу Proxyline. Оператори можуть встановити proxy.loopbackMode: "proxy", щоб надсилати loopback-трафік Gateway через керований проксі, або proxy.loopbackMode: "block", щоб заборонити loopback-підключення Gateway. Див. Режим loopback Gateway щодо застереження для віддаленого проксі.
  • Raw-сокети net, tls і http2, native addons та дочірні процеси не OpenClaw можуть обходити маршрутизацію проксі рівня Node, якщо вони не успадковують і не поважають змінні середовища проксі. Відгалужені дочірні CLI OpenClaw успадковують керований URL проксі та стан proxy.loopbackMode.
  • IRC є raw TCP/TLS-каналом поза маршрутизацією через керований оператором forward proxy. У розгортаннях, які вимагають увесь вихідний трафік через цей forward proxy, встановіть channels.irc.enabled=false, якщо прямий вихідний IRC-трафік явно не схвалено.
  • Локальний debug proxy є діагностичним інструментом, і його пряме пересилання upstream для проксі-запитів та CONNECT-тунелів вимкнене за замовчуванням, поки активний режим керованого проксі; вмикайте пряме пересилання лише для схваленої локальної діагностики.
  • Локальні WebUI користувача та локальні сервери моделей мають бути внесені до allowlist у політиці проксі оператора, коли це потрібно; OpenClaw не надає для них загального обходу локальної мережі. Вбудований провайдер ембедингів пам’яті Ollama вужчий: він може використовувати захищений прямий шлях лише для точного host-local loopback джерела ембедингів, отриманого з налаштованого baseUrl, щоб host-local ембединги продовжували працювати, коли керований проксі не може дістатися host loopback. LAN, tailnet, private-network і публічні хости ембедингів Ollama і далі використовують шлях керованого проксі. proxy.loopbackMode: "proxy" надсилає цей loopback-трафік Ollama через керований проксі, а proxy.loopbackMode: "block" забороняє його до відкриття підключення.
  • Обхід проксі для control-plane Gateway навмисно обмежений localhost і буквальними URL loopback IP. Використовуйте ws://127.0.0.1:18789, ws://[::1]:18789 або ws://localhost:18789 для локальних прямих підключень control-plane Gateway; інші імена хостів маршрутизуються як звичайний трафік на основі імен хостів.
  • OpenClaw не інспектує, не тестує й не сертифікує вашу політику проксі.
  • Ставтеся до змін політики проксі як до чутливих з погляду безпеки операційних змін.
ПоверхняСтан керованого проксі
fetch, node:http, node:https, поширені WebSocket-клієнтиМаршрутизуються через керовані хуки проксі, коли налаштовано.
Прямий APNs HTTP/2Маршрутизується через керований APNs CONNECT helper.
Loopback control-plane GatewayНапряму лише для налаштованого локального loopback URL Gateway.
Upstream-пересилання debug proxyВимкнене, поки активний режим керованого проксі, якщо явно не ввімкнено для локальної діагностики.
IRCRaw TCP/TLS; не проксіюється режимом керованого HTTP-проксі. Вимкніть, якщо прямий IRC egress не схвалено.
Інші raw-клієнтські виклики net, tls або http2Мають бути класифіковані захистом raw-сокетів перед landing.