Мережевий проксі

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

OpenClaw не постачає, не завантажує, не запускає, не налаштовує й не сертифікує проксі-сервер. Ви запускаєте технологію проксі-сервера, що відповідає вашому середовищу; OpenClaw спрямовує через неї власні клієнти HTTP і WebSocket.

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

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

Також можна задати URL через середовище, залишивши proxy.enabled: true у конфігурації:

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

proxy.proxyUrl має пріоритет над OPENCLAW_PROXY_URL. Якщо proxy.enabled має значення true, але не вдається визначити жодного дійсного URL, захищені команди завершуються помилкою під час запуску замість переходу до прямого доступу до мережі.

Для керованих служб Gateway зберігайте URL у конфігурації, щоб він не втрачався після повторного встановлення, замість того щоб покладатися на змінну середовища процесу переднього плану:

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

Резервне використання змінної середовища OPENCLAW_PROXY_URL найкраще підходить для запусків на передньому плані. Щоб використовувати її зі встановленою службою, додайте її до постійного середовища служби ($OPENCLAW_STATE_DIR/.env, типово ~/.openclaw/.env), а потім повторно встановіть службу, щоб launchd/systemd/Заплановані завдання підхопили її.

Кінцева точка проксі-сервера HTTPS із приватним ЦС

proxy:  enabled: true  proxyUrl: https://proxy.corp.example:8443  tls:    caFile: /etc/openclaw/proxy-ca.pem

proxy.tls.caFile перевіряє власний TLS-сертифікат кінцевої точки проксі-сервера. Це не налаштування довіри до MITM для призначення, не клієнтський сертифікат і не заміна політики проксі-сервера щодо призначень. Натомість використовуйте NODE_EXTRA_CA_CERTS лише тоді, коли весь процес Node має довіряти додатковому ЦС від моменту запуску (наприклад, коли корпоративна система перевірки TLS повторно підписує сертифікат кожного призначення HTTPS) — ця змінна діє на рівні всього процесу й має бути задана до запуску Node, тому OpenClaw не може застосувати її під час роботи так само, як proxy.tls.caFile. Для довіри до кінцевої точки проксі-сервера HTTPS віддавайте перевагу proxy.tls.caFile: її дія обмежена керованою маршрутизацією через проксі-сервер, а не поширюється на весь процес.

openclaw config set proxy.enabled trueopenclaw config set proxy.proxyUrl https://proxy.corp.example:8443openclaw config set proxy.tls.caFile /etc/openclaw/proxy-ca.pemopenclaw gateway run

Як працює маршрутизація

За наявності proxy.enabled: true і дійсного URL захищені процеси середовища виконання (openclaw gateway run, openclaw node run, openclaw agent --local) спрямовують звичайний вихідний трафік HTTP і WebSocket через проксі-сервер:

OpenClaw process  fetch, node:http, node:https, WebSocket clients  -> operator proxy -> destination

Внутрішньо OpenClaw установлює Proxyline як середовище маршрутизації на рівні процесу. Воно охоплює fetch, клієнти на основі undici, node:http/node:https, поширені клієнти WebSocket і тунелі CONNECT, створені допоміжними засобами, а також замінює надані викликачем HTTP-агенти Node, щоб явно задані агенти (зокрема axios, got, node-fetch та подібні клієнти на основі агентів Node) не могли непомітно обійти проксі-сервер.

Схема URL проксі-сервера описує перехід від OpenClaw до проксі-сервера, а не до кінцевого призначення:

• http://proxy.example:3128 — звичайне TCP-з’єднання з проксі-сервером; OpenClaw надсилає проксі-запити HTTP, зокрема CONNECT для призначень HTTPS.
• https://proxy.example:8443 — OpenClaw установлює TLS-з’єднання із самим проксі-сервером (перевіряючи його сертифікат), а потім надсилає проксі-запити HTTP у межах цього сеансу.

TLS призначення не залежить від TLS кінцевої точки проксі-сервера: для призначення HTTPS OpenClaw завжди запитує в проксі-сервера тунель CONNECT і запускає TLS призначення через цей тунель.

Поки проксі-сервер активний, OpenClaw очищає no_proxy/NO_PROXY. Ці списки обходу ґрунтуються на призначеннях; наявність у них localhost або 127.0.0.1 дала б цілям SSRF змогу повністю обійти проксі-сервер. Під час завершення роботи OpenClaw відновлює попереднє середовище проксі-сервера та скидає кешований стан маршрутизації.

Деякі плагіни мають власний транспорт, для якого потрібне окреме налаштування проксі-сервера навіть за активної маршрутизації на рівні процесу. Клієнт Bot API Telegram використовує власний диспетчер HTTP/1 undici та окремо враховує змінні середовища проксі-сервера процесу разом із резервним значенням OPENCLAW_PROXY_URL.

Режим зворотного інтерфейсу Gateway

Локальні клієнти площини керування Gateway зазвичай підключаються до WebSocket на зворотному інтерфейсі, наприклад ws://127.0.0.1:18789. proxy.loopbackMode визначає, чи обходить цей трафік керований проксі-сервер:

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

Обхід площини керування Gateway обмежений localhost і URL із буквальними IP-адресами зворотного інтерфейсу — використовуйте ws://127.0.0.1:18789, ws://[::1]:18789 або ws://localhost:18789. Інші імена вузлів маршрутизуються як звичайний трафік.

Контейнери

Для команд openclaw --container ... OpenClaw передає OPENCLAW_PROXY_URL дочірньому CLI, орієнтованому на контейнер, якщо цю змінну задано. URL має бути доступним із контейнера — 127.0.0.1 там означає сам контейнер, а не вузол. OpenClaw відхиляє URL проксі-сервера зі зворотним інтерфейсом для команд, орієнтованих на контейнер, якщо ви явно не перевизначите цю перевірку, задавши OPENCLAW_CONTAINER_ALLOW_LOOPBACK_PROXY_URL=1.

Пов’язані терміни проксі-сервера

• proxy.enabled / proxy.proxyUrl — маршрутизація вихідного трафіку середовища виконання через прямий проксі-сервер. Ця сторінка.
• gateway.auth.mode: "trusted-proxy" — автентифікація через вхідний зворотний проксі-сервер з урахуванням ідентичності для доступу до Gateway. Див. Автентифікація через довірений проксі-сервер.
• openclaw proxy — локальний проксі-сервер налагодження та інспектор захоплених даних для розробки й підтримки. Див. openclaw proxy.
• tools.web.fetch.useTrustedEnvProxy — явне ввімкнення для web_fetch, яке дає змогу контрольованому оператором проксі-серверу HTTP(S), заданому через середовище, розв’язувати DNS, водночас типово зберігаючи суворе прив’язування DNS і політику імен вузлів. Див. Отримання даних із вебу.
• Налаштування проксі-сервера для окремих каналів або постачальників — специфічні для власника перевизначення одного транспорту. Для централізованого контролю вихідного трафіку в усьому середовищі виконання віддавайте перевагу керованому мережевому проксі-серверу.

Перевірка проксі-сервера

Політика проксі-сервера щодо призначень є фактичною межею безпеки; OpenClaw не може перевірити, чи блокує ваш проксі-сервер належні цілі. Налаштуйте його так, щоб він:

• Прив’язувався лише до зворотного інтерфейсу або приватного довіреного інтерфейсу, доступного тільки процесу, вузлу, контейнеру або службовому обліковому запису OpenClaw.
• Самостійно розв’язував призначення та блокував їх за IP-адресою після розв’язання DNS, під час підключення, як для звичайного HTTP, так і для тунелів HTTPS CONNECT.
• Відхиляв обхід за призначенням для зворотних, приватних, локальних для каналу, службових метаданих, багатоадресних, зарезервованих і документаційних діапазонів.
• Уникав списків дозволених імен вузлів, якщо ви не повністю довіряєте шляху розв’язання DNS.
• Записував у журнал призначення, рішення, стан і причину — але ніколи не тіла запитів, заголовки авторизації, файли cookie або інші секрети.
• Зберігав політику під керуванням версій і розглядав зміни як чутливі з погляду безпеки.

Виконайте перевірку з того самого вузла, контейнера або службового облікового запису, де працює OpenClaw:

openclaw proxy validate --proxy-url http://127.0.0.1:3128

Для кінцевої точки проксі-сервера HTTPS із приватним ЦС:

openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem

Якщо proxy.enabled не має значення true і параметр --proxy-url не вказано, команда замість перевірки повідомляє про проблему конфігурації; перед зміною конфігурації передайте --proxy-url для одноразової попередньої перевірки.

Якщо не вказано --allowed-url/--denied-url, типові перевірки такі: доступ до https://example.com/ має бути успішним, а тимчасовий контрольний сервер local loopback, якого проксі не повинен досягати, має бути заблокований. Перевірка local loopback вважається успішною в разі транспортної помилки або відповіді не з діапазону 2xx, яка не містить унікального для цього запуску токена контрольного сервера; вона завершується невдало в разі відповіді 2xx без токена (неочікуваний успішний доступ до чогось іншого, ніж контрольний сервер) і особливо в разі будь-якої відповіді з відповідним токеном, оскільки це доводить, що проксі справді переслав запит до призначення local loopback, яке мав заблокувати. Власні цілі --denied-url не мають такого контрольного токена, тому для них діє принцип безпечної відмови: будь-яка HTTP-відповідь означає, що ціль доступна (помилка), а транспортна помилка вважається непереконливим результатом, а не підтвердженим блокуванням, оскільки OpenClaw не може визначити, чи проксі заблокував доступне джерело, чи сталася інша помилка. --apns-reachable надсилає навмисно недійсний токен постачальника, тому відповідь 403 InvalidProviderToken підтверджує, що тунель досяг Apple. Команда завершується з кодом 1 у разі будь-якої помилки перевірки; облікові дані в 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 (публічний запит має бути успішним; запити до local loopback і метаданих має блокувати сам проксі — лише curl не може відрізнити блокування проксі від недоступного джерела так, як це робить вбудований контрольний сервер openclaw proxy validate):

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/

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

Початковий список заборон для будь-якого прямого проксі, брандмауера або політики вихідного трафіку. Власний класифікатор SSRF OpenClaw міститься в src/infra/net/ssrf.ts і packages/net-policy/src/ip.ts (BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, префікс RFC 2544 для еталонного тестування та обробка вбудованих IPv4-адрес у форматах NAT64/6to4/Teredo/ISATAP/IPv4-mapped) — це корисні довідкові матеріали, але OpenClaw не експортує та не застосовує ці правила у вашому зовнішньому проксі.

Додайте всі додаткові хости метаданих або зарезервовані діапазони, задокументовані вашим постачальником хмарних послуг чи мережевою платформою.

Обмеження

• Це охоплення на рівні процесу для HTTP/WebSocket-клієнтів JavaScript, а не мережева пісочниця на рівні ОС.
• Необроблені сокети net, tls, http2, нативні доповнення та дочірні процеси, що не належать OpenClaw, можуть обходити маршрутизацію на рівні Node, якщо вони не успадковують і не враховують змінні середовища проксі. Розгалужені дочірні CLI OpenClaw успадковують URL-адресу керованого проксі та стан proxy.loopbackMode.
• Локальні WebUI користувача та локальні сервери моделей не охоплюються загальним обходом локальної мережі — за потреби додайте їх до списку дозволених у політиці проксі оператора. Винятком є захищений прямий шлях вбудованого постачальника векторних представлень пам’яті Ollama, обмежений точним джерелом local loopback локального хоста з його налаштованого baseUrl; хости Ollama в LAN, tailnet, приватній і публічній мережах усе одно використовують керований проксі.
• Пряме пересилання до висхідного сервера локального налагоджувального проксі (для проксі-запитів і тунелів CONNECT) за замовчуванням вимкнено, коли активний режим керованого проксі; вмикайте його лише для схваленої локальної діагностики.
• OpenClaw не перевіряє, не тестує та не сертифікує вашу політику проксі. Розглядайте зміни політики проксі як операційні зміни, критичні для безпеки.