English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Security

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

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

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

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

Проксі дає операторам одну точку мережевого контролю для вихідного HTTP- і WebSocket-трафіку. Це може бути корисно навіть поза посиленням захисту від SSRF:

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

Маршрутизація через проксі є процесним обмежувальним механізмом для звичайного вихідного HTTP- і WebSocket-трафіку. Вона дає операторам fail-closed шлях для спрямування підтримуваних JavaScript HTTP-клієнтів через їхній власний фільтрувальний проксі, але це не мережевий sandbox на рівні ОС і не означає, що OpenClaw сертифікує політику призначень проксі.

Як OpenClaw спрямовує трафік

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

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, використані для її реалізації. WebSocket-клієнти control plane OpenClaw Gateway використовують вузький прямий шлях для Gateway RPC-трафіку через local loopback, коли URL Gateway використовує localhost або буквальну loopback IP-адресу, таку як 127.0.0.1 чи [::1]. Цей шлях control plane має мати змогу досягати loopback Gateway, навіть коли проксі оператора блокує loopback-призначення. Звичайні runtime HTTP- і WebSocket-запити все одно використовують налаштований проксі.

Внутрішньо OpenClaw використовує два процесні хуки маршрутизації для цієї функції:

  • Маршрутизація диспетчера Undici покриває fetch, клієнти на основі undici та транспорти, які надають власний диспетчер undici.
  • Маршрутизація global-agent покриває викликачів Node core node:http і node:https, зокрема багато бібліотек, побудованих поверх http.request, https.request, http.get і https.get. Режим керованого проксі примусово вмикає цей глобальний агент, щоб явні HTTP-агенти Node випадково не обійшли проксі оператора.

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

Сам URL проксі має використовувати http://. HTTPS-призначення все одно підтримуються через проксі за допомогою HTTP CONNECT; це означає лише, що OpenClaw очікує звичайний HTTP forward-proxy listener, наприклад http://127.0.0.1:3128.

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

Під час завершення роботи OpenClaw відновлює попереднє proxy-середовище та скидає кешований стан процесної маршрутизації.

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

  • proxy.enabled / proxy.proxyUrl: маршрутизація вихідного трафіку OpenClaw runtime через forward proxy. Ця сторінка документує цю функцію.
  • gateway.auth.mode: "trusted-proxy": автентифікація вхідного доступу до Gateway через identity-aware reverse proxy. Див. Автентифікація через 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.
  • Налаштування проксі, специфічні для каналу або провайдера: owner-specific перевизначення для конкретного транспорту. Віддавайте перевагу керованому мережевому проксі, коли метою є централізований контроль вихідного трафіку в усьому runtime.

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

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.

Режим Loopback для Gateway

Локальні клієнти control plane Gateway зазвичай підключаються до loopback 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-only (типово): OpenClaw реєструє loopback-авторитет Gateway в активному контролері NO_PROXY global-agent, щоб локальний WebSocket-трафік Gateway міг підключатися напряму. Користувацькі loopback-порти Gateway працюють, тому що host і port активного URL Gateway реєструються.
  • proxy: OpenClaw не реєструє loopback-авторитет Gateway у NO_PROXY, тому локальний трафік Gateway надсилається через керований проксі. Якщо проксі віддалений, він має забезпечити спеціальну маршрутизацію до loopback-сервісу хоста OpenClaw, наприклад зіставити його з доступним для проксі hostname, IP або тунелем. Стандартні віддалені проксі резолвлять 127.0.0.1 і localhost з хоста проксі, а не з хоста OpenClaw.
  • block: OpenClaw забороняє loopback-з’єднання control plane Gateway до відкриття socket.

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

Для керованих 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 у durable environment сервісу, наприклад $OPENCLAW_STATE_DIR/.env або ~/.openclaw/.env, а потім перевстановіть сервіс, щоб launchd, systemd або Scheduled Tasks запускали gateway з цим значенням.

Для команд openclaw --container ... OpenClaw передає OPENCLAW_PROXY_URL у дочірній CLI, орієнтований на контейнер, коли його встановлено. URL має бути доступний зсередини контейнера; 127.0.0.1 посилається на сам контейнер, а не на хост. OpenClaw відхиляє loopback URL-и проксі для команд, орієнтованих на контейнер, якщо ви явно не перевизначите цю safety-перевірку.

Вимоги до проксі

Політика проксі є межею безпеки. OpenClaw не може перевірити, що проксі блокує правильні цілі.

Налаштуйте проксі так, щоб він:

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

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

Використовуйте цей denylist як відправну точку для будь-якого forward proxy, firewall або політики вихідного трафіку.

Логіка класифікатора на рівні застосунку 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 форм. Ці файли корисні як довідкові матеріали під час підтримки зовнішньої політики проксі, але OpenClaw не експортує й не застосовує ці правила автоматично у вашому проксі.

Діапазон або 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 Спільний адресний простір carrier-grade NAT
198.18.0.0/15, 2001:2::/48 Діапазони для benchmark
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 діапазони
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 або мережева платформа документує додаткові metadata hosts чи reserved ranges, також додайте їх.

Валідація

Перевірте проксі з того самого хоста, контейнера або service account, який запускає OpenClaw:

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

За замовчуванням, коли користувацькі призначення не надано, команда перевіряє, що https://example.com/ успішно відповідає, і запускає тимчасову loopback-канарку, до якої проксі не має дістатися. Стандартна перевірка забороненого призначення проходить, коли проксі повертає не-2xx відповідь із відмовою або блокує канарку транспортною помилкою; вона не проходить, якщо успішна відповідь доходить до канарки. Якщо проксі не ввімкнено й не налаштовано, перевірка повідомляє про проблему конфігурації; використовуйте --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-канарка може відрізнити відмову проксі від доступного джерела. Користувацькі перевірки --denied-url не мають такої канарки, тому розглядайте і HTTP-відповіді, і неоднозначні транспортні помилки як невдалі перевірки, якщо ваш проксі не надає специфічний для розгортання сигнал відмови, який можна перевірити окремо.

Потім увімкніть маршрутизацію OpenClaw через проксі:

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

Обмеження

  • Проксі покращує покриття для локальних у процесі JavaScript-клієнтів HTTP і WebSocket, але це не мережевий sandbox на рівні ОС.
  • Трафік loopback площини керування Gateway за замовчуванням має прямий локальний обхід через proxy.loopbackMode: "gateway-only". OpenClaw реалізує цей обхід, реєструючи активний loopback-authority Gateway у керованому контролері global-agent NO_PROXY. Оператори можуть установити proxy.loopbackMode: "proxy", щоб надсилати loopback-трафік Gateway через керований проксі, або proxy.loopbackMode: "block", щоб заборонити loopback-з’єднання Gateway. Див. Режим Loopback для Gateway щодо застереження для віддаленого проксі.
  • Сирі сокети net, tls і http2, native addons і дочірні процеси не з OpenClaw можуть обходити маршрутизацію проксі на рівні Node, якщо вони не успадковують і не дотримуються змінних середовища проксі. Розгалужені дочірні CLI OpenClaw успадковують URL керованого проксі та стан proxy.loopbackMode.
  • IRC — це сирий TCP/TLS-канал поза маршрутизацією через керований оператором forward proxy. У розгортаннях, де весь вихідний трафік має проходити через цей forward proxy, задайте channels.irc.enabled=false, якщо прямий вихідний IRC-трафік не схвалено явно.
  • Локальний debug proxy є діагностичним інструментом, і його пряме upstream-пересилання для проксі-запитів і CONNECT-тунелів за замовчуванням вимкнено, поки активний режим керованого проксі; вмикайте пряме пересилання лише для схваленої локальної діагностики.
  • Локальні WebUI користувача та локальні сервери моделей слід додавати до allowlist у політиці проксі оператора, коли це потрібно; OpenClaw не надає для них загального обходу локальної мережі.
  • Обхід проксі площини керування Gateway навмисно обмежено localhost і URL з буквальними loopback-IP. Використовуйте ws://127.0.0.1:18789, ws://[::1]:18789 або ws://localhost:18789 для локальних прямих з’єднань із площиною керування Gateway; інші імена хостів маршрутизуються як звичайний трафік на основі hostname.
  • OpenClaw не перевіряє, не тестує й не сертифікує вашу політику проксі.
  • Розглядайте зміни політики проксі як операційні зміни, чутливі до безпеки.