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

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 определить не удаётся, защищённые команды завершаются ошибкой при запуске, а не переключаются на прямой доступ к сети.

Ключ	Тип	По умолчанию	Примечания
`proxy.enabled`	логический	не задано	Для активации маршрутизации должно иметь значение `true`.
`proxy.proxyUrl`	строка	не задано	URL прямого прокси-сервера `http://` или `https://`. Учётные данные, встроенные в URL, считаются конфиденциальными и скрываются в снимках и журналах.
`proxy.tls.caFile`	строка	не задано	Набор сертификатов ЦС для проверки конечной точки прокси-сервера `https://`, подписанной частным ЦС.
`proxy.loopbackMode`	`gateway-only` \| `proxy` \| `block`	`gateway-only`	Управляет обходом прокси для обратной петли; см. ниже.

Для управляемых служб Gateway сохраняйте 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

Резервный вариант с переменной окружения 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 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 и допустимого 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-only` (по умолчанию)	OpenClaw регистрирует активный адрес обратной петли Gateway как исключение для прямого подключения, поэтому локальный WebSocket-трафик Gateway подключается без прокси-сервера. Пользовательские порты обратной петли поддерживаются, поскольку исключение применяется к точно настроенным хосту и порту. Встроенный браузерный плагин регистрирует исключение того же типа для точных локальных URL проверки готовности CDP и WebSocket DevTools управляемых браузеров, запущенных OpenClaw; встроенный поставщик векторных представлений памяти Ollama использует более узкий защищённый прямой путь для точно настроенного локального источника векторных представлений на хосте.
`proxy`	Исключения для обратной петли не регистрируются; трафик обратной петли Gateway и Ollama проходит через прокси-сервер. Удалённый прокси-сервер должен уметь маршрутизировать трафик обратно к службе обратной петли на хосте OpenClaw (например, через доступное имя хоста, IP-адрес или туннель) — стандартный удалённый прокси-сервер разрешает `127.0.0.1`/`localhost` относительно самого себя, а не хоста OpenClaw.
`block`	OpenClaw запрещает подключения плоскости управления Gateway по обратной петле и защищённые подключения Ollama по обратной петле для получения векторных представлений до открытия сокета.

Обход прокси-сервера для плоскости управления 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-url <url>`	Проверить этот URL вместо определения конфигурации или переменных среды.
`--proxy-ca-file <path>`	Пакет сертификатов центра сертификации для конечной точки HTTPS-прокси.
`--allowed-url <url>`	Адрес назначения, обращение к которому должно завершиться успешно (можно указывать несколько раз).
`--denied-url <url>`	Адрес назначения, который должен быть заблокирован (можно указывать несколько раз).
`--apns-reachable`	Также проверить, что прокси может туннелировать прямой HTTP/2-запрос к APNs в песочнице.
`--apns-authority <url>`	Переопределить адрес APNs, проверяемый с помощью `--apns-reachable`.
`--timeout-ms <ms>`	Время ожидания каждого запроса.
`--json`	Машиночитаемый вывод.

Если 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/

Диапазон или хост	Причина блокировки
`127.0.0.0/8`, `localhost`, `localhost.localdomain`	Loopback IPv4
`::1/128`	Loopback IPv6
`0.0.0.0/8`, `::/128`	Неопределенные адреса и адреса текущей сети
`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`	Частные сети RFC 1918
`169.254.0.0/16`, `fe80::/10`	Link-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 и ORCHIDv2
`64:ff9b::/96`, `64:ff9b:1::/48`	Префиксы NAT64 со встроенным IPv4
`2002::/16`, `2001::/32`	6to4 и Teredo со встроенным IPv4
`::/96`, `::ffff:0:0/96`	IPv4-совместимые и IPv4-mapped IPv6

Ограничения

Поверхность	Состояние управляемого прокси
`fetch`, `node:http`, `node:https`, распространенные клиенты WebSocket	При наличии конфигурации направляются через обработчики управляемого прокси.
Прямой HTTP/2 для APNs	Направляется через управляемый вспомогательный компонент APNs `CONNECT`.
Loopback плоскости управления Gateway	Прямой доступ разрешен только для точно настроенного локального URL loopback Gateway.
Перенаправление вышестоящего трафика отладочного прокси	Отключено при активном режиме управляемого прокси, если не включено явно для локальной диагностики.
IRC	Необработанный TCP/TLS; режим управляемого HTTP-прокси не применяется. Установите `channels.irc.enabled: false`, если в вашей среде весь исходящий трафик должен проходить через прямой прокси.
Другие прямые вызовы клиентов `net`, `tls` или `http2`	Перед включением должны быть классифицированы средством защиты необработанных сокетов.

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

Gateway

Remote access

Security

Nodes and media

Web interfaces

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

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

Конечная точка прокси-сервера HTTPS с частным ЦС

Как работает маршрутизация

Режим обратной петли Gateway

Контейнеры

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

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

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

Ограничения

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

​Конечная точка прокси-сервера HTTPS с частным ЦС

​Как работает маршрутизация

​Режим обратной петли Gateway

​Контейнеры

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

​Проверка прокси-сервера

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

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

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

Конечная точка прокси-сервера HTTPS с частным ЦС

Как работает маршрутизация

Режим обратной петли Gateway

Контейнеры

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

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

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

Ограничения