--- read_when: - Вам потрібен багаторівневий захист від атак SSRF і повторної прив’язки DNS - Налаштування зовнішнього прямого проксі для трафіку середовища виконання OpenClaw summary: Як спрямовувати HTTP- і WebSocket-трафік середовища виконання OpenClaw через фільтрувальний проксі, керований оператором title: Мережевий проксі x-i18n: generated_at: "2026-05-07T16:23:22Z" model: gpt-5.5 provider: openai source_hash: 22895b7c5521927b7145f55dff9b777e701691f01a6421db0f5b1ff489734775 source_path: security/network-proxy.md workflow: 16 --- 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, але не є мережевою пісочницею на рівні OS і не змушує OpenClaw сертифікувати політику призначень proxy. ## Як OpenClaw маршрутизує трафік Коли `proxy.enabled=true` і налаштовано URL proxy, захищені runtime-процеси, як-от `openclaw gateway run`, `openclaw node run` і `openclaw agent --local`, спрямовують звичайний вихідний HTTP- і WebSocket-трафік через налаштований proxy: ```text 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 ``` Публічний контракт — це поведінка маршрутизації, а не внутрішні hooks Node, які використовуються для її реалізації. WebSocket-клієнти control-plane OpenClaw Gateway використовують вузький прямий шлях для local loopback Gateway RPC-трафіку, коли URL Gateway використовує `localhost` або буквальну loopback IP-адресу, як-от `127.0.0.1` чи `[::1]`. Цей шлях control-plane має мати змогу досягати loopback Gateway навіть тоді, коли proxy оператора блокує loopback-призначення. Звичайні runtime HTTP- і WebSocket-запити все одно використовують налаштований proxy. Внутрішньо OpenClaw використовує два процесні hooks маршрутизації для цієї функції: - Маршрутизація через dispatcher Undici покриває `fetch`, клієнтів на базі undici і транспорти, які надають власний dispatcher undici. - Маршрутизація `global-agent` покриває викликачів core Node `node:http` і `node:https`, зокрема багато бібліотек, побудованих поверх `http.request`, `https.request`, `http.get` і `https.get`. Керований режим proxy примусово використовує цей global agent, щоб явні HTTP-агенти Node випадково не обходили proxy оператора. Деякі plugins володіють власними транспортами, яким потрібне явне підключення proxy навіть за наявності процесної маршрутизації. Наприклад, транспорт Bot API Telegram використовує власний HTTP/1 dispatcher undici і тому враховує process proxy env, а також керований fallback `OPENCLAW_PROXY_URL` у цьому специфічному для власника транспортному шляху. Сам URL proxy має використовувати `http://`. HTTPS-призначення все одно підтримуються через proxy за допомогою HTTP `CONNECT`; це лише означає, що OpenClaw очікує звичайний HTTP forward-proxy listener, як-от `http://127.0.0.1:3128`. Поки proxy активний, OpenClaw очищає `no_proxy`, `NO_PROXY` і `GLOBAL_AGENT_NO_PROXY`. Ці списки обходу залежать від призначення, тому залишення там `localhost` або `127.0.0.1` дозволило б високоризиковим SSRF-цілям пропускати фільтрувальний proxy. Під час завершення роботи OpenClaw відновлює попереднє proxy-середовище і скидає кешований стан процесної маршрутизації. ## Пов’язані терміни proxy - `proxy.enabled` / `proxy.proxyUrl`: маршрутизація вихідного runtime-трафіку OpenClaw через forward-proxy. Ця сторінка документує цю функцію. - `gateway.auth.mode: "trusted-proxy"`: вхідна автентифікація через identity-aware reverse-proxy для доступу до Gateway. Див. [Автентифікація trusted proxy](/uk/gateway/trusted-proxy-auth). - `openclaw proxy`: локальний debug proxy та інспектор захоплення для розробки й підтримки. Див. [openclaw proxy](/uk/cli/proxy). - `tools.web.fetch.useTrustedEnvProxy`: opt-in для `web_fetch`, щоб дозволити керованому оператором HTTP(S) env proxy виконувати DNS-резолюцію, зберігаючи стандартне суворе DNS pinning і політику hostname. Див. [Web fetch](/uk/tools/web-fetch#trusted-env-proxy). - Налаштування proxy, специфічні для каналу або провайдера: перевизначення для конкретного транспорту, що належать власнику. Надавайте перевагу керованому мережевому proxy, коли мета — централізований контроль вихідного трафіку в усьому runtime. ## Конфігурація ```yaml proxy: enabled: true proxyUrl: http://127.0.0.1:3128 ``` Ви також можете передати URL через середовище, залишивши `proxy.enabled=true` у config: ```bash OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run ``` `proxy.proxyUrl` має пріоритет над `OPENCLAW_PROXY_URL`. ### Режим local loopback Gateway Локальні клієнти control-plane Gateway зазвичай підключаються до loopback WebSocket, як-от `ws://127.0.0.1:18789`. Використовуйте `proxy.loopbackMode`, щоб вибрати, як поводиться цей трафік, поки керований proxy активний: ```yaml proxy: enabled: true proxyUrl: http://127.0.0.1:3128 loopbackMode: gateway-only # gateway-only, proxy, or block ``` - `gateway-only` (стандартно): OpenClaw реєструє loopback authority Gateway в активному controller `NO_PROXY` `global-agent`, щоб локальний WebSocket-трафік Gateway міг підключатися напряму. Користувацькі loopback-порти Gateway працюють, тому що host і port активного URL Gateway зареєстровані. - `proxy`: OpenClaw не реєструє loopback authority Gateway `NO_PROXY`, тому локальний трафік Gateway надсилається через керований proxy. Якщо proxy віддалений, він має надавати спеціальну маршрутизацію для loopback-служби хоста OpenClaw, наприклад зіставляти її з доступним для proxy hostname, IP або tunnel. Стандартні віддалені proxy резолвлять `127.0.0.1` і `localhost` з хоста proxy, а не з хоста OpenClaw. - `block`: OpenClaw забороняє loopback-з’єднання control-plane Gateway до відкриття socket. Якщо `enabled=true`, але не налаштовано коректний URL proxy, захищені команди завершують запуск з помилкою замість повернення до прямого доступу до мережі. Для керованих служб gateway, запущених через `openclaw gateway start`, надавайте перевагу збереженню URL у config: ```bash 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` у дочірній CLI, націлений на контейнер, коли це значення задано. URL має бути доступним зсередини контейнера; `127.0.0.1` вказує на сам контейнер, а не на host. OpenClaw відхиляє loopback URL proxy для команд, націлених на контейнер, якщо ви явно не перевизначите цю перевірку безпеки. ## Вимоги до proxy Політика proxy є межею безпеки. OpenClaw не може перевірити, що proxy блокує правильні цілі. Налаштуйте proxy так, щоб він: - Прив’язувався лише до loopback або приватного довіреного interface. - Обмежував доступ так, щоб ним міг користуватися лише процес, host, container або service account OpenClaw. - Самостійно резолвив призначення й блокував IP призначення після DNS-резолюції. - Застосовував політику під час підключення як для звичайних HTTP-запитів, так і для HTTPS-тунелів `CONNECT`. - Відхиляв обходи на основі призначення для loopback, private, link-local, metadata, multicast, reserved або documentation ranges. - Уникав allowlist hostname, якщо ви повністю не довіряєте шляху DNS-резолюції. - Журналював призначення, рішення, статус і причину без журналювання тіл запитів, заголовків authorization, cookies або інших secrets. - Тримав політику proxy під version control і перевіряв зміни як security-sensitive конфігурацію. ## Рекомендовані заблоковані призначення Використовуйте цей denylist як відправну точку для будь-якого forward proxy, firewall або політики вихідного трафіку. Логіка classifier OpenClaw на рівні застосунку міститься в `src/infra/net/ssrf.ts` і `src/shared/net/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 форм. Ці файли є корисними довідковими матеріалами під час підтримки зовнішньої політики proxy, але OpenClaw не експортує і не застосовує ці правила у вашому proxy автоматично. | Діапазон або host | Навіщо блокувати | | ------------------------------------------------------------------------------------ | -------------------------------------------------- | | `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback | | `::1/128` | IPv6 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::/10` | Link-local адреси та поширені шляхи cloud metadata | | `169.254.169.254`, `metadata.google.internal` | Служби cloud metadata | | `100.64.0.0/10` | Shared address space carrier-grade NAT | | `198.18.0.0/15`, `2001:2::/48` | Діапазони benchmarking | | `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Special-use і documentation ranges | | `224.0.0.0/4`, `ff00::/8` | Multicast | | `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::/32` | 6to4 і Teredo із вбудованим IPv4 | | `::/96`, `::ffff:0:0/96` | IPv4-compatible і IPv4-mapped IPv6 | Якщо ваш cloud provider або network platform документує додаткові metadata hosts чи reserved ranges, додайте їх також. ## Перевірка Перевірте proxy з того самого host, container або service account, який запускає OpenClaw: ```bash openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` За замовчуванням, коли не задано власних призначень, команда перевіряє, що `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-виводі: ```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`: ```bash 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 і metadata мають бути заблоковані проксі. Для `openclaw proxy validate` вбудований loopback canary може відрізнити відмову проксі від досяжного джерела. Власні перевірки `--denied-url` не мають такого canary, тому розглядайте як невдалу перевірку і HTTP-відповіді, і неоднозначні транспортні збої, якщо ваш проксі не надає специфічний для розгортання сигнал відмови, який можна перевірити окремо. Потім увімкніть проксі-маршрутизацію OpenClaw: ```bash openclaw config set proxy.enabled true openclaw config set proxy.proxyUrl http://127.0.0.1:3128 openclaw gateway run ``` або задайте: ```yaml proxy: enabled: true proxyUrl: http://127.0.0.1:3128 ``` ## Обмеження - Проксі покращує покриття для локальних у процесі JavaScript HTTP- і WebSocket-клієнтів, але не є мережевою пісочницею рівня ОС. - Трафік loopback контрольної площини Gateway за замовчуванням обходить проксі напряму локально через `proxy.loopbackMode: "gateway-only"`. OpenClaw реалізує цей обхід, реєструючи активну loopback-авторизацію Gateway у керованому контролері `global-agent` `NO_PROXY`. Оператори можуть задати `proxy.loopbackMode: "proxy"`, щоб надсилати loopback-трафік Gateway через керований проксі, або `proxy.loopbackMode: "block"`, щоб заборонити loopback-з’єднання Gateway. Див. [Режим Gateway Loopback](#gateway-loopback-mode) щодо застереження про віддалений проксі. - Raw-сокети `net`, `tls` і `http2`, нативні addons і дочірні процеси не від OpenClaw можуть обходити проксі-маршрутизацію рівня Node, якщо вони не успадковують і не дотримуються змінних середовища проксі. Відгалужені дочірні CLI OpenClaw успадковують керований URL проксі та стан `proxy.loopbackMode`. - IRC — це raw TCP/TLS-канал поза операторською керованою маршрутизацією через forward proxy. У розгортаннях, які вимагають, щоб весь вихідний трафік проходив через цей forward proxy, задайте `channels.irc.enabled=false`, якщо прямий вихід IRC явно не схвалено. - Локальний debug proxy є діагностичним інструментом, а його пряме upstream-перенаправлення для proxy-запитів і CONNECT-тунелів вимкнене за замовчуванням, доки активний режим керованого проксі; вмикайте пряме перенаправлення лише для схваленої локальної діагностики. - Локальні WebUI користувача та локальні сервери моделей слід додавати до allowlist у політиці проксі оператора за потреби; OpenClaw не надає загального обходу локальної мережі для них. - Обхід проксі для контрольної площини Gateway навмисно обмежений `localhost` і буквальними URL loopback IP. Використовуйте `ws://127.0.0.1:18789`, `ws://[::1]:18789` або `ws://localhost:18789` для локальних прямих з’єднань контрольної площини Gateway; інші імена хостів маршрутизуються як звичайний трафік на основі імені хоста. - OpenClaw не перевіряє, не тестує й не сертифікує вашу політику проксі. - Розглядайте зміни політики проксі як операційні зміни, чутливі до безпеки. | Поверхня | Стан керованого проксі | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | `fetch`, `node:http`, `node:https`, поширені WebSocket-клієнти | Маршрутизуються через хуки керованого проксі, коли налаштовано. | | Прямий APNs HTTP/2 | Маршрутизується через керований APNs CONNECT helper. | | Loopback контрольної площини Gateway | Напряму лише для налаштованого локального loopback URL Gateway. | | Upstream-перенаправлення debug proxy | Вимкнене, доки активний режим керованого проксі, якщо явно не ввімкнене для локальної діагностики. | | IRC | Raw TCP/TLS; не проксіюється режимом керованого HTTP-проксі. Вимкніть, якщо прямий вихід IRC не схвалено. | | Інші raw-виклики клієнтів `net`, `tls` або `http2` | Мають бути класифіковані raw socket guard перед landing. |