Сетевой прокси

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/Scheduled Tasks применили его.

Конечная точка прокси-сервера 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  fetch, node:http, node:https, WebSocket-клиенты  -> прокси-сервер оператора -> назначение

Внутри 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 или 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 не может проверить, блокирует ли ваш прокси-сервер нужные цели. Настройте его следующим образом:

• Привязывайте только к интерфейсу loopback или доверенному частному интерфейсу, доступному исключительно процессу, хосту, контейнеру или служебной учетной записи OpenClaw.
• Прокси должен самостоятельно разрешать адреса назначения и блокировать их по IP-адресу после разрешения DNS, во время подключения, как для обычного HTTP, так и для туннелей HTTPS CONNECT.
• Отклоняйте попытки обхода на основе адреса назначения для диапазонов loopback, частных, link-local, метаданных, многоадресной рассылки, зарезервированных и документационных диапазонов.
• Избегайте списков разрешенных имен хостов, если не доверяете полностью пути разрешения 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/ должен завершиться успешно, а временный контрольный сервер loopback, недоступный для прокси, должен быть заблокирован. Проверка loopback считается успешной при транспортной ошибке или ответе, отличном от 2xx, в котором отсутствует уникальный токен контрольного сервера для текущего запуска; она завершается неудачей при ответе 2xx без токена (неожиданный успешный ответ от чего-либо, кроме контрольного сервера) и особенно при любом ответе с совпадающим токеном, поскольку это доказывает, что прокси действительно перенаправил запрос к адресу 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 (публичный запрос должен завершиться успешно, а запросы к 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 не экспортирует и не применяет эти правила во внешнем прокси.

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

Ограничения

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