--- read_when: - Вам нужна многоуровневая защита от атак SSRF и DNS rebinding - Настройка внешнего прямого прокси для трафика runtime OpenClaw summary: Как направлять HTTP- и WebSocket-трафик среды выполнения OpenClaw через фильтрующий прокси, управляемый оператором title: Сетевой прокси x-i18n: generated_at: "2026-06-28T23:47:32Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 3fc68d950037922ba3dc983c94a71bac3374750a02ef25f2c046cf782410be68 source_path: security/network-proxy.md workflow: 16 --- 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-трафик через настроенный прокси: ```text 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. См. [Аутентификация через доверенный прокси](/ru/gateway/trusted-proxy-auth). - `openclaw proxy`: локальный отладочный прокси и инспектор захвата для разработки и поддержки. См. [openclaw proxy](/ru/cli/proxy). - `tools.web.fetch.useTrustedEnvProxy`: opt-in для `web_fetch`, позволяющий контролируемому оператором HTTP(S) env proxy разрешать DNS, сохраняя при этом строгую привязку DNS и политику имен хостов по умолчанию. См. [Web fetch](/ru/tools/web-fetch#trusted-env-proxy). - Настройки прокси, специфичные для канала или провайдера: owner-specific переопределения для конкретного транспорта. Предпочитайте управляемый сетевой прокси, когда цель — централизованный контроль исходящего трафика во всем runtime. ## Конфигурация ```yaml proxy: enabled: true proxyUrl: http://127.0.0.1:3128 ``` Для HTTPS endpoint прокси с частным CA прокси: ```yaml proxy: enabled: true proxyUrl: https://proxy.corp.example:8443 tls: caFile: /etc/openclaw/proxy-ca.pem ``` Вы также можете передать URL через окружение, сохранив `proxy.enabled=true` в конфигурации: ```bash 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 управляемого прокси, пока управляемый прокси активен: ```yaml 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 в конфигурации: ```bash 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.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-адреса и распространенные пути метаданных облака | | `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::/32` | 6to4 и Teredo со встроенным IPv4 | | `::/96`, `::ffff:0:0/96` | IPv6, совместимый с IPv4, и IPv6 с отображением IPv4 | Если ваш облачный провайдер или сетевая платформа документирует дополнительные хосты метаданных или зарезервированные диапазоны, добавьте и их. ## Проверка Проверяйте прокси с того же хоста, контейнера или сервисного аккаунта, где работает OpenClaw: ```bash openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` Для HTTPS-эндпоинта прокси, подписанного частным CA: ```bash 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-выводе: ```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`: ```bash 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: ```yaml 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: ```bash 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 ``` или задайте: ```yaml 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](#gateway-loopback-mode) для предостережения о удаленном прокси. - Сырые сокеты `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` | Должны быть классифицированы защитой сырых сокетов до попадания в код. |