> ## 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. # Мережевий проксі 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: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} 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](/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 для окремого каналу або провайдера: owner-specific перевизначення для конкретного транспорту. Надавайте перевагу керованому мережевому proxy, коли мета — централізований контроль вихідного трафіку в усьому runtime. ## Конфігурація ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} proxy: enabled: true proxyUrl: http://127.0.0.1:3128 ``` Для HTTPS endpoint proxy з приватним proxy CA: ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} proxy: enabled: true proxyUrl: https://proxy.corp.example:8443 tls: caFile: /etc/openclaw/proxy-ca.pem ``` Ви також можете надати URL через середовище, залишивши `proxy.enabled=true` у конфігурації: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 активний: ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 у конфігурації: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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.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 адреси та поширені шляхи хмарних метаданих | | `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::/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-сумісні та IPv4-відображені IPv6 | Якщо ваш хмарний провайдер або мережева платформа документує додаткові хости метаданих чи зарезервовані діапазони, додайте також їх. ## Валідація Перевіряйте проксі з того самого хоста, контейнера або сервісного облікового запису, який запускає OpenClaw: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` Для кінцевої точки HTTPS-проксі, підписаної приватним CA: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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-виводі: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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 theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ``` або встановіть: ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} 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](#gateway-loopback-mode) щодо застереження для віддаленого проксі. * 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 | Вимкнене, поки активний режим керованого проксі, якщо явно не ввімкнено для локальної діагностики. | | IRC | Raw TCP/TLS; не проксіюється режимом керованого HTTP-проксі. Вимкніть, якщо прямий IRC egress не схвалено. | | Інші raw-клієнтські виклики `net`, `tls` або `http2` | Мають бути класифіковані захистом raw-сокетів перед landing. |