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

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.

​

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

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

​

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

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

• Маршрутизація через 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 оператора.

​

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

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

​

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

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

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

​

Режим local loopback Gateway

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.

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

​

Вимоги до 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 конфігурацію.

​

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

​

Перевірка

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

{
  "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 -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/

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-клієнтів, але не є мережевою пісочницею рівня ОС.
• Трафік 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 щодо застереження про віддалений проксі.
• 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 не перевіряє, не тестує й не сертифікує вашу політику проксі.
• Розглядайте зміни політики проксі як операційні зміни, чутливі до безпеки.