Перейти к основному содержанию
OpenClaw может маршрутизировать runtime-трафик HTTP и WebSocket через управляемый оператором прямой прокси. Это необязательная эшелонированная защита для развертываний, которым нужны централизованный контроль исходящего трафика, более сильная защита от 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-клиентов через собственный фильтрующий прокси, но не является сетевой песочницей на уровне ОС и не заставляет 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 плоскости управления OpenClaw Gateway используют узкий прямой путь для local loopback Gateway RPC-трафика, когда URL Gateway использует localhost или буквальный loopback IP, например 127.0.0.1 или [::1]. Этот путь плоскости управления должен иметь возможность достигать loopback Gateway даже тогда, когда операторский прокси блокирует loopback-назначения. Обычные runtime-запросы HTTP и WebSocket по-прежнему используют настроенный прокси. Внутренне OpenClaw устанавливает Proxyline как runtime маршрутизации на уровне процесса для этой функции. Proxyline покрывает fetch, клиенты на базе undici, вызывающих Node core node:http / node:https, распространенные WebSocket-клиенты и созданные вспомогательными средствами CONNECT-туннели. Режим управляемого прокси заменяет предоставленные вызывающей стороной HTTP-агенты Node, чтобы явные агенты случайно не обходили операторский прокси. Некоторые Plugins владеют собственными транспортами, которым нужна явная привязка прокси даже при наличии маршрутизации на уровне процесса. Например, транспорт Bot API в Telegram использует собственный HTTP/1-диспетчер undici и поэтому учитывает env прокси процесса плюс управляемый fallback OPENCLAW_PROXY_URL в этом owner-specific транспортном пути. Сам URL прокси может использовать либо http://, либо https://. Эти схемы описывают соединение от OpenClaw к endpoint прокси:
  • http://proxy.example:3128: OpenClaw открывает обычное TCP-соединение к прямому прокси и отправляет HTTP proxy-запросы, включая CONNECT для HTTPS-назначений.
  • https://proxy.example:8443: OpenClaw открывает TLS к endpoint прокси, проверяет сертификат прокси, а затем отправляет HTTP proxy-запросы внутри этой TLS-сессии.
HTTPS назначения отделен от TLS endpoint прокси. Для HTTPS-назначения OpenClaw по-прежнему запрашивает у прокси HTTP-туннель CONNECT, а затем запускает TLS назначения через этот туннель. Пока прокси активен, OpenClaw очищает no_proxy и NO_PROXY. Эти списки обхода основаны на назначениях, поэтому оставленные там localhost или 127.0.0.1 позволили бы высокорисковым SSRF-целям обходить фильтрующий прокси. При завершении работы OpenClaw восстанавливает предыдущую proxy-среду и сбрасывает кэшированное состояние маршрутизации процесса.

​
Связанные термины прокси

  • proxy.enabled / proxy.proxyUrl: маршрутизация исходящего трафика OpenClaw runtime через прямой прокси. Эта страница документирует эту функцию.
  • gateway.auth.mode: "trusted-proxy": входящая identity-aware аутентификация через обратный прокси для доступа к Gateway. См. Аутентификация через доверенный прокси.
  • openclaw proxy: локальный отладочный прокси и инспектор захвата для разработки и поддержки. См. openclaw proxy.
  • tools.web.fetch.useTrustedEnvProxy: opt-in для web_fetch, позволяющий контролируемому оператором HTTP(S) env proxy разрешать DNS, сохраняя при этом строгую привязку DNS и политику имен хостов по умолчанию. См. Web fetch.
  • Настройки прокси, специфичные для канала или провайдера: owner-specific переопределения для конкретного транспорта. Предпочитайте управляемый сетевой прокси, когда цель — централизованный контроль исходящего трафика во всем runtime.

​
Конфигурация

proxy:
  enabled: true
  proxyUrl: http://127.0.0.1:3128
Для HTTPS endpoint прокси с частным CA прокси: 
proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem
Вы также можете передать URL через окружение, сохранив proxy.enabled=true в конфигурации: 
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 управляемого прокси, пока управляемый прокси активен: 
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 работают, потому что регистрируются хост и порт активного URL Gateway. Встроенный browser Plugin также может зарегистрировать точные локальные CDP readiness- и DevTools WebSocket endpoints для управляемых браузеров, запущенных OpenClaw, а встроенный провайдер Ollama для memory embeddings может использовать собственный более узкий защищенный прямой путь для точно настроенного host-local loopback origin embeddings.
  • proxy: OpenClaw не регистрирует loopback-обходы Gateway или Ollama, поэтому этот loopback-трафик отправляется через управляемый прокси. Если прокси удаленный, он должен предоставить специальную маршрутизацию для loopback-сервиса хоста OpenClaw, например сопоставление с доступным прокси hostname, IP или туннелем. Стандартные удаленные прокси разрешают 127.0.0.1 и localhost с хоста прокси, а не с хоста OpenClaw.
  • block: OpenClaw запрещает loopback-соединения плоскости управления Gateway и защищенные host-local embedding loopback-соединения Ollama до открытия сокета.
Если enabled=true, но корректный URL прокси не настроен, защищенные команды завершают запуск с ошибкой вместо fallback к прямому сетевому доступу. Для управляемых сервисов 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 в долговечное окружение сервиса, например $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 прокси для команд, нацеленных на контейнер, если вы явно не переопределите эту проверку безопасности.

​
Требования к прокси

Политика прокси является границей безопасности. OpenClaw не может проверить, что прокси блокирует правильные цели. Настройте прокси так, чтобы он:
  • Привязывался только к loopback или частному доверенному интерфейсу.
  • Ограничивал доступ так, чтобы использовать его могли только процесс, хост, контейнер или сервисная учетная запись OpenClaw.
  • Самостоятельно разрешал назначения и блокировал IP назначений после разрешения DNS.
  • Применял политику при подключении как для обычных HTTP-запросов, так и для HTTPS-туннелей CONNECT.
  • Отклонял обходы на основе назначений для loopback, private, link-local, metadata, multicast, reserved или documentation диапазонов.
  • Избегал allowlist имен хостов, если вы не полностью доверяете пути разрешения DNS.
  • Логировал назначение, решение, статус и причину, не логируя тела запросов, заголовки авторизации, cookies или другие секреты.
  • Хранил политику прокси под контролем версий и проверял изменения как конфигурацию, чувствительную к безопасности.

​
Рекомендуемые заблокированные назначения

Используйте этот denylist как отправную точку для любого прямого прокси, firewall или политики исходящего трафика. Логика классификатора OpenClaw на уровне приложения находится в src/infra/net/ssrf.ts и packages/net-policy/src/ip.ts. Соответствующие хуки паритета — BLOCKED_HOSTNAMES, BLOCKED_IPV4_SPECIAL_USE_RANGES, BLOCKED_IPV6_SPECIAL_USE_RANGES, RFC2544_BENCHMARK_PREFIX и встроенная обработка IPv4 sentinel для NAT64, 6to4, Teredo, ISATAP и IPv4-mapped форм. Эти файлы полезны как справочные материалы при поддержке внешней политики прокси, но OpenClaw не экспортирует и не применяет эти правила в вашем прокси автоматически.
Диапазон или хостПочему нужно блокировать
127.0.0.0/8, localhost, localhost.localdomainIPv4 loopback
::1/128IPv6 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::/10Link-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Многоадресная рассылка
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::/326to4 и Teredo со встроенным IPv4
::/96, ::ffff:0:0/96IPv6, совместимый с IPv4, и IPv6 с отображением IPv4
Если ваш облачный провайдер или сетевая платформа документирует дополнительные хосты метаданных или зарезервированные диапазоны, добавьте и их.

​
Проверка

Проверяйте прокси с того же хоста, контейнера или сервисного аккаунта, где работает OpenClaw: 
openclaw proxy validate --proxy-url http://127.0.0.1:3128
Для HTTPS-эндпоинта прокси, подписанного частным CA: 
openclaw proxy validate --proxy-url https://proxy.corp.example:8443 --proxy-ca-file /etc/openclaw/proxy-ca.pem
По умолчанию, когда пользовательские назначения не указаны, команда проверяет, что https://example.com/ успешно открывается, и запускает временную loopback-канарейку, до которой прокси не должен доходить. Стандартная проверка запрета проходит, когда прокси возвращает ответ отказа не 2xx или блокирует канарейку транспортной ошибкой; она завершается ошибкой, если до канарейки доходит успешный ответ. Если прокси не включен и не настроен, проверка сообщает о проблеме конфигурации; используйте --proxy-url для разовой предварительной проверки перед изменением конфигурации. Используйте --allowed-url и --denied-url, чтобы проверить ожидания, специфичные для развертывания. Добавьте --apns-reachable, чтобы также проверить, что прямая доставка APNs HTTP/2 может открыть CONNECT-туннель через прокси и получить ответ APNs sandbox; проба использует намеренно недействительный токен провайдера, поэтому 403 InvalidProviderToken ожидается и считается признаком доступности. Пользовательские запрещенные назначения работают по принципу fail-closed: любой HTTP-ответ означает, что назначение было доступно через прокси, а любая транспортная ошибка сообщается как неопределенный результат, потому что OpenClaw не может доказать, что прокси заблокировал доступный origin. При ошибке проверки команда завершается с кодом 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-канарейка может отличить отказ прокси от доступного origin. Пользовательские проверки --denied-url не имеют такой канарейки, поэтому считайте и HTTP-ответы, и неоднозначные транспортные ошибки ошибками проверки, если только ваш прокси не предоставляет специфичный для развертывания сигнал отказа, который можно проверить отдельно.

​
Доверие к CA прокси

Используйте управляемый proxy.tls.caFile, когда сам эндпоинт прокси использует сертификат, подписанный частным CA: 
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: 
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
или задайте: 
proxy:
  enabled: true
  proxyUrl: https://proxy.corp.example:8443
  tls:
    caFile: /etc/openclaw/proxy-ca.pem

​
Ограничения

  • Прокси улучшает покрытие для локальных в процессе HTTP- и WebSocket-клиентов JavaScript, но не является сетевой песочницей уровня ОС.
  • Трафик плоскости управления Gateway через loopback по умолчанию использует прямой локальный обход через proxy.loopbackMode: "gateway-only". OpenClaw реализует этот обход, регистрируя активный loopback authority Gateway в управляемой политике обхода Proxyline. Операторы могут задать proxy.loopbackMode: "proxy", чтобы отправлять loopback-трафик Gateway через управляемый прокси, или proxy.loopbackMode: "block", чтобы запрещать loopback-подключения Gateway. См. Режим loopback для Gateway для предостережения о удаленном прокси.
  • Сырые сокеты net, tls и http2, нативные аддоны и дочерние процессы не OpenClaw могут обходить прокси-маршрутизацию уровня Node, если они не наследуют и не соблюдают переменные окружения прокси. Разветвленные дочерние CLI OpenClaw наследуют управляемый URL прокси и состояние proxy.loopbackMode.
  • IRC — это сырой TCP/TLS-канал вне маршрутизации управляемого оператором forward proxy. В развертываниях, где весь исходящий трафик должен проходить через этот forward proxy, задайте channels.irc.enabled=false, если прямой исходящий IRC-трафик явно не одобрен.
  • Локальный отладочный прокси — диагностический инструмент; его прямая пересылка вверх по цепочке для прокси-запросов и CONNECT-туннелей по умолчанию отключена, пока активен управляемый режим прокси. Включайте прямую пересылку только для одобренной локальной диагностики.
  • Локальные WebUI пользователя и локальные серверы моделей при необходимости должны быть добавлены в allowlist в политике прокси оператора; OpenClaw не предоставляет для них общего обхода локальной сети. Встроенный провайдер эмбеддингов памяти Ollama уже: он может использовать защищенный прямой путь только для точного host-local loopback origin эмбеддингов, полученного из настроенного baseUrl, чтобы host-local эмбеддинги продолжали работать, когда управляемый прокси не может достичь host loopback. LAN, tailnet, частные сетевые и публичные хосты эмбеддингов Ollama по-прежнему используют путь через управляемый прокси. proxy.loopbackMode: "proxy" отправляет этот loopback-трафик Ollama через управляемый прокси, а proxy.loopbackMode: "block" запрещает его до открытия соединения.
  • Обход прокси для плоскости управления Gateway намеренно ограничен localhost и буквальными loopback IP URL. Используйте 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.
Восходящая пересылка отладочного проксиОтключена, пока активен управляемый режим прокси, если явно не включена для локальной диагностики.
IRCСырой TCP/TLS; не проксируется управляемым режимом HTTP-прокси. Отключайте, если прямой исходящий IRC-трафик не одобрен.
Другие сырые клиентские вызовы net, tls или http2Должны быть классифицированы защитой сырых сокетов до попадания в код.