Codex CLI за корпоративным прокси: PAC/WPAD, CA-сертификаты и HTTPS_PROXY (2026)

Если ваш ноутбук открывает ChatGPT в браузере, но codex просто застывает на первом запросе, — сеть не сломана, и Codex тоже. Codex CLI не читает ваш PAC-файл и не обнаруживает WPAD так, как это делает браузер, поэтому машина, которая нормально ходит в веб, всё равно оставит codex висеть на первом запросе. Это руководство проведёт вас от мёртвого терминала к работающему агенту и объяснит, почему решение — это ручной HTTPS_PROXY даже в 2026 году.

Ответ за 30 секунд

Вся работа сводится к четырём ходам: найти реальный прокси, на который указывает PAC, экспортировать HTTPS_PROXY/HTTP_PROXY/NO_PROXY, передать Codex корпоративный CA через CODEX_CA_CERTIFICATE, а затем проверить с RUST_LOG=debug. Остальная часть страницы — это детали по каждому ходу и ошибки, с которыми вы столкнётесь по пути.

Что вы сможете после этой настройки (и чего не сможете)

После завершения Codex будет отправлять свои API-вызовы через тот же прокси, что и браузер, переживёт промежуточный узел с инспекцией TLS и пропустит прокси для внутренних Git-серверов и реестров пакетов. Это покрывает подавляющее большинство закрытых корпоративных сетей.

Это не превратит Codex в браузер. Codex по-прежнему не разбирает PAC-скрипт, по-прежнему не отвечает на WPAD-широковещание и по-прежнему не умеет надёжно стримить через SOCKS5. Если ваша служба безопасности раздаёт настройки прокси только через групповые политики и PAC-URL, именно вам придётся перевести это в переменную окружения. Этот перевод и есть настоящая работа — та часть, которую пропускает любой ответ в духе «просто задай HTTPS_PROXY».

Рамка решения: когда применять эту настройку (а когда НЕ применять)

Когда применять

• Ваша организация раздаёт конфиг прокси через PAC/WPAD или групповые политики, а CLI-инструменты предоставлены сами себе.
• Прокси делает инспекцию TLS, поэтому вы видите ошибки сертификата от любого инструмента, которого нет в системном хранилище доверия.
• У вас пять и более разработчиков ходят через один прокси, и вам нужен один общий задокументированный конфиг вместо того, чтобы каждый гадал сам.

Когда НЕ применять

• Вы в домашней сети или в кафе, где прокси вообще нет. Установка HTTPS_PROXY на мёртвый адрес только сломает Codex. Уберите её.
• Ваш прокси прозрачный (перехватывает на сетевом уровне без клиентской настройки). Тогда настраивать нечего, а ручная переменная прокси может привести к двойному проксированию запроса.
• Вам нужно лишь сменить API-ключ или эндпоинт. Это правка config.toml в одну строку, а не проект по настройке прокси. Переходите к продвинутому разделу.

Для самого значения прокси есть чёткое правило остановки. Если curl -x http://your-proxy:port https://api.openai.com/v1/models возвращает HTTP-статус вместо зависания, значит адрес прокси верный и настройку можно прекратить. Всё, что после этого, — это доверие к CA и аутентификация, а это отдельные проблемы с отдельными решениями.

Почему Codex игнорирует ваш прокси PAC/WPAD

Codex игнорирует PAC и WPAD, потому что это CLI, построенный на HTTP-клиенте, который понимает только переменные окружения для прокси, а не браузерный стек прокси. Именно этот факт архитектуры и вызывает большую часть путаницы, поэтому стоит быть точным.

PAC-файл (Proxy Auto-Config) — это небольшая JavaScript-программа с функцией FindProxyForURL(url, host). Браузер выполняет эту функцию для каждого запроса и получает ответ вроде PROXY proxy.corp.example.com:8080 или DIRECT. WPAD (Web Proxy Auto-Discovery) — это протокол, который сообщает браузеру, где лежит этот PAC-файл, обычно через опцию DHCP или DNS-запись wpad.<yourdomain>. Браузеры, приложения Office и сетевой стек Windows — все они говорят на этом языке. Согласно обзору PAC-файлов от проекта PyPAC, почти ни один инструмент командной строки этого не умеет.

HTTP-клиент Codex учитывает HTTPS_PROXY, HTTP_PROXY, ALL_PROXY и NO_PROXY — это стандартная Unix-конвенция, общая для curl, git и большинства языковых рантаймов. Есть открытый запрос сделать так, чтобы каждый HTTP-клиент Codex единообразно учитывал переменные окружения прокси, но на момент Codex 0.142.x поддерживаемый путь — задать эти переменные самому. Так что цепочка, которая работает для браузера (WPAD находит PAC, PAC возвращает прокси, браузер его использует), не имеет эквивалента внутри Codex. Без заданного HTTPS_PROXY Codex пытается установить прямое соединение, файрвол его отбрасывает, и вы получаете зависание вместо внятной ошибки. Именно из-за этого молчаливого отброса всё выглядит как баг Codex, хотя на деле это пропущенный шаг перевода.

Полезно увидеть два пути обнаружения бок о бок. Браузер при старте либо читает PAC-URL, который админ раздал через групповую политику, либо рассылает WPAD-запрос по DHCP и DNS, чтобы найти его. Затем он выполняет FindProxyForURL для каждого отдельного URL, поэтому разные хосты могут получать разные ответы: интранет возвращает DIRECT, публичный интернет возвращает PROXY. Codex не делает ничего из этого. Он читает четыре строки из окружения один раз, при запуске, и применяет их на всю сессию. Ни скрипта на каждый хост, ни широковещания для автообнаружения, ни повторной оценки. Вот почему «мои другие инструменты работают» — не доказательство того, что заработает Codex: ваши другие инструменты почти наверняка читают те же переменные окружения, которые вы сейчас зададите, а не PAC-файл.

Системные требования

Прежде чем трогать настройки прокси, подтвердите базовые вещи, потому что прокси охотно скроет несвязанную проблему установки.

• Codex CLI установлен из правильного пакета. npm install -g @openai/codex. Пакет codex без области видимости на npm — это другой проект, и его установка — самая частая причина, по которой позже всплывает command not found или странное поведение.
• Node.js 16 или новее для пути установки через npm (@openai/codex объявляет engines: node >=16). Более старый Node провалит установку раньше, чем вы вообще дойдёте до сети.
• Эндпоинт вашего прокси в виде host:port. Если у вас есть только PAC-URL, следующий шаг его разберёт.
• Корпоративный корневой CA в формате PEM, если ваш прокси инспектирует TLS. Попросите у команды платформы «бандл корневого CA» или экспортируйте его из системного хранилища ключей.

Пошагово: направляем Codex на корпоративный прокси

Проходите по порядку. У каждого шага есть проверка, чтобы вы понимали, что он сработал, прежде чем двигаться дальше.

Шаг 1: Убедитесь, что браузер работает, а Codex — нет

Откройте ваш API-хост в браузере и посмотрите, как он загружается, затем выполните голый запрос из терминала.

# In a browser: https://api.openai.com/v1/models loads (401 JSON is fine)
# In the terminal, this should hang or fail fast if there's a proxy:
curl -sS --max-time 10 https://api.openai.com/v1/models ; echo "exit=$?"

Если браузер достаёт до хоста, а curl уходит в таймаут, у вас классическая настройка «только PAC». Этот разрыв и есть вся ваша проблема, а следующий шаг его закрывает.

Шаг 2: Разберите PAC-файл, чтобы найти реальный прокси

Вам нужен настоящий host:port, который PAC вернул бы для API-хоста. На macOS прочитайте URL автонастройки, затем протестируйте его. pactester поставляется с пакетом pacparser.

# macOS: find the PAC URL your system is configured with
scutil --proxy | grep -i ProxyAutoConfig
# Download it and ask which proxy serves the API host
curl -s "$PAC_URL" -o wpad.dat
pactester -p wpad.dat -u https://api.openai.com
# → PROXY proxy.corp.example.com:8080; DIRECT

На Windows PowerShell читает тот же URL автонастройки и действующий прокси WinHTTP:

Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings' AutoConfigURL
netsh winhttp show proxy

Возьмите первый PROXY host:port, который выведет резолвер. Это то значение, которое вы жёстко пропишете дальше. Мануал по pactester описывает флаги, если в вашем PAC несколько правил.

Шаг 3: Задайте HTTPS_PROXY, HTTP_PROXY и NO_PROXY

Экспортируйте прокси для HTTPS и HTTP и перечислите в NO_PROXY каждый внутренний хост, который должен идти в обход прокси.

export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export HTTP_PROXY="http://proxy.corp.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com,.internal"

Обратите внимание: схема URL прокси — это http://, хотя он несёт HTTPS-трафик. Это правильно: схема описывает, как вы общаетесь с прокси, а не то, что он пересылает. Если прокси требует учётные данные, впишите их прямо в строку:

export HTTPS_PROXY="http://alice:[email protected]:8080"

Поместите эти строки в ~/.zshrc или ~/.bashrc, чтобы новые оболочки их унаследовали. Отсутствующий NO_PROXY — частая причина того, что после установки прокси ломаются внутренние вызовы Git или реестра, поэтому не пропускайте его.

Шаг 4: Доверьтесь CA прокси с инспекцией TLS

Если ваш прокси инспектирует TLS, он переподписывает каждый сертификат частным корневым CA. Codex будет отвергать это, пока вы не скажете ему доверять этому CA. Укажите в CODEX_CA_CERTIFICATE путь к PEM-бандлу перед входом.

export CODEX_CA_CERTIFICATE="/etc/pki/tls/certs/corporate-root-ca.pem"
# Fallback that also covers curl, git, and other tools:
export SSL_CERT_FILE="/etc/pki/tls/certs/corporate-root-ca.pem"
codex login

CODEX_CA_CERTIFICATE имеет приоритет и влияет только на Codex; когда она не задана, Codex откатывается на SSL_CERT_FILE, которую большинство корпоративных образов уже устанавливают. Документация по продвинутой конфигурации Codex описывает параметры провайдера модели и эндпоинта, которые вы будете использовать в продвинутом разделе ниже.

Шаг 5: Проверьте с RUST_LOG=debug

Убедитесь, что переменные видны Codex, и понаблюдайте за согласованием прокси.

env | grep -i proxy
RUST_LOG=debug codex exec "print the current date" 2>&1 | grep -i proxy

Если отладочный вывод показывает хост вашего прокси, а команда возвращает результат, вы закончили. Если по-прежнему не работает, сообщение об ошибке подскажет, какой слой сломался, а следующий раздел сопоставляет каждое сообщение с решением.

Частые ошибки при настройке (и их решения)

Большинство сбоев прокси выдают одно из нескольких сообщений. Найдите своё здесь, прежде чем менять случайные настройки.

Две из них заслуживают отдельного замечания. Ошибка сертификата — самый частый блокер в инспектируемых сетях, и решается она доверием к CA, а не отключением проверки. Отключение проверки TLS, «чтобы заработало», отдаёт ваш трафик тому, кто есть на проводе, — так что не делайте этого. А зависание SOCKS5 реально: SOCKS5 работает для некоторых путей Codex, но нестабилен для стриминговых ответов, на которые агент опирается, так что в корпоративной сети предпочтите HTTP-прокси.

Схема диагностики одним взглядом

flowchart TD
    A[Browser reaches internet, codex hangs] --> B{Proxy env vars set?}
    B -->|No| C[Resolve PAC, set HTTPS_PROXY + NO_PROXY]
    B -->|Yes| D{SSL / certificate error?}
    C --> D
    D -->|Yes| E[Set CODEX_CA_CERTIFICATE to corporate CA]
    D -->|No| F{407 auth error?}
    E --> F
    F -->|Yes| G[Add user:pass@ or run a cntlm/px relay]
    F -->|No| H[Run RUST_LOG=debug codex exec to trace]

Когда HTTPS_PROXY всё равно нужен (даже если PAC говорит DIRECT)

HTTPS_PROXY всё равно нужен всякий раз, когда Codex должен достучаться до хоста, который ваш PAC маршрутизирует через прокси, — а в большинстве корпоративных сетей это каждый внешний API-хост. То, что PAC умён, Codex не помогает, потому что Codex никогда не выполняет PAC. На этом спотыкаются в трёх конкретных ситуациях, о которых стоит сказать отдельно.

Первая — раздельная маршрутизация. Ваш PAC возвращает DIRECT для внутренних хостов и PROXY для публичного интернета. Всё внутреннее работает из терминала без всяких переменных, поэтому вы решаете, что сеть открыта, а потом первый внешний API-вызов зависает. Решение — задать HTTPS_PROXY для внешних хостов и перечислить внутренние в NO_PROXY, чтобы они шли напрямую.

Вторая — VPN с раздельным туннелированием. На VPN PAC может отправлять корпоративный трафик через прокси, а всё остальное — напрямую, или наоборот. Когда вы подключаетесь или отключаетесь, действующий прокси меняется, а экспортированная переменная — нет. Если Codex начинает падать сразу после переключения VPN, разберите PAC заново и обновите HTTPS_PROXY.

Третья — предположение о прозрачном прокси. Некоторые сети перехватывают трафик на роутере без клиентской настройки, поэтому браузерам ничего не нужно. Если у вас так, HTTPS_PROXY может вообще не понадобиться, а установка его на несуществующий хост только сломает Codex. Тест curl из рамки решения говорит, в каком мире вы находитесь: если голый curl к API-хосту работает, у вас прозрачный прокси и переменную стоит оставить незаданной.

Коротко: задавайте HTTPS_PROXY, когда API-хост проксируется, и убирайте его, когда сеть проксирует прозрачно. Промежуточного варианта, где Codex читает PAC за вас, не существует.

Конфигурация для команды / нескольких разработчиков

Как только одна машина заработала, цель — чтобы следующий разработчик не повторял ваш потерянный день. Масштабируемый паттерн — отделить общий несекретный конфиг от персонального секрета.

Держите значения прокси и CA в версионируемом фрагменте профиля, который команда подключает из своего rc-файла оболочки:

# proxy.env — committed to the team dotfiles repo (no secrets here)
export HTTPS_PROXY="http://proxy.corp.example.com:8080"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,.corp.example.com,.internal"
export CODEX_CA_CERTIFICATE="/etc/pki/tls/certs/corporate-root-ca.pem"

Держите каждый API-ключ вне этого файла — в персональной переменной, которую разработчик задаёт один раз. Для прокси, требующих учётные данные, не коммитьте ничей пароль в HTTPS_PROXY; пусть каждый добавляет свой user:pass@ локально или запускает локальный ретранслятор аутентификации, чтобы в общем конфиге не было никаких учётных данных вообще.

На прокси NTLM или Kerberos всей команде нужен локальный ретранслятор, потому что Codex не умеет этот handshake. Запустите ретранслятор на каждой машине, например cntlm или px, и направьте HTTPS_PROXY всех на него:

# px handles enterprise NTLM auth; Codex talks plain HTTP to localhost
px --proxy=proxy.corp.example.com:8080 --port=3128 &
export HTTPS_PROXY="http://localhost:3128"

Одна деталь развёртывания подводит команды каждый раз: разработчик, запускающий Codex из терминала IDE или лаунчера, а не из логин-оболочки. GUI-приложения на macOS и Windows не наследуют переменные, заданные в ~/.zshrc, поэтому в точности та настройка, что работает в терминале, падает внутри редактора. Задокументируйте это в заметке для онбординга. На macOS задайте переменные в пользовательском агенте launchd или в собственном окружении приложения; на Windows используйте диалог системных переменных окружения, чтобы их наследовал каждый процесс, а не только новые оболочки. Проверьте, что свежая копия работает: откройте совершенно новый терминал и выполните RUST_LOG=debug codex exec "print ok", прежде чем говорить кому-либо, что конфиг готов.

Продвинутое: кастомный base_url и мультипровайдерная маршрутизация

Когда прокси и CA на месте, Codex может достучаться до любого OpenAI-совместимого эндпоинта через тот же корпоративный выход в сеть, а не только до api.openai.com. Именно здесь кастомный провайдер модели в config.toml окупает себя.

Определите блок провайдера, указывающий на OpenAI-совместимый шлюз. Справочник по конфигу документирует каждый ключ:

# ~/.codex/config.toml
model_provider = "ofox"
model = "openai/gpt-5.4"

[model_providers.ofox]
name = "ofox OpenAI-compatible gateway"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOX_API_KEY"

Если вы хотите лишь перенаправить встроенного провайдера OpenAI на другой эндпоинт, задайте openai_base_url вместо написания целого блока провайдера. В любом случае запрос по-прежнему уходит с вашей машины через настроенный HTTPS_PROXY и по-прежнему доверяет заданному вами CA, так что работа над прокси переносится без изменений.

Причина, по которой команда прибегает к этому в закрытой сети, — консолидация. Вместо того чтобы просить команду файрвола внести в allowlist несколько вендорских API-хостов и вести несколько ключей, вы направляете Codex на один OpenAI-совместимый шлюз и меняете модели сменой строки. На ofox это означает один эндпоинт и один ключ, покрывающие модели вроде openai/gpt-5.4 наряду с Claude, Gemini и другими, что держит allowlist прокси коротким. Если хотите сначала попробовать конкретную модель, страница модели openai/gpt-5.4 содержит её актуальные детали. Трафик по-прежнему идёт через ваш корпоративный прокси; ничего здесь его не обходит.

FAQ

Поддерживает ли Codex CLI автонастройку прокси через PAC или WPAD? Нет. Codex читает HTTP_PROXY, HTTPS_PROXY, ALL_PROXY и NO_PROXY, но не выполняет PAC-файлы и не обнаруживает прокси через WPAD. PAC вы разбираете сами и кладёте результат в HTTPS_PROXY.

Почему Codex зависает, хотя браузер выходит в интернет? Браузер получает прокси из PAC-файла через WPAD, а Codex — нет. Без заданной переменной прокси Codex открывает прямое соединение, которое файрвол отбрасывает, поэтому запрос висит до таймаута.

Как задать прокси для Codex CLI? Экспортируйте HTTPS_PROXY и HTTP_PROXY с адресом и портом вашего прокси, а для внутренних хостов задайте NO_PROXY. В config.toml нет ключа для прокси, поэтому путь — это переменная окружения.

Как исправить ошибку SSL-сертификата в Codex за прокси? Прокси с инспекцией TLS предъявляет сертификат, подписанный частным корневым CA, которому Codex не доверяет. Укажите в CODEX_CA_CERTIFICATE путь к PEM корпоративного корневого CA перед codex login. Если переменная не задана, Codex откатывается на SSL_CERT_FILE.

Поддерживает ли Codex CLI прокси SOCKS5? Частично. SOCKS5 работает для некоторых путей, но нестабилен для стриминга и websocket-трафика, который Codex использует активно. HTTP-прокси через HTTPS_PROXY надёжнее в корпоративной сети.

Как настроить прокси Codex для всей команды? Держите переменные прокси и CA в общем несекретном фрагменте профиля, а блок провайдера в config.toml закоммитьте в репозиторий dotfiles. API-ключи и учётные данные прокси держите персональными, никогда не коммитьте.

В чём разница между HTTP_PROXY и HTTPS_PROXY для Codex? HTTP_PROXY применяется к обычным http://-запросам, а HTTPS_PROXY — к https://-запросам. API-трафик Codex весь идёт по HTTPS, поэтому важен именно HTTPS_PROXY, но задайте обе с одним значением.

Как пройти аутентификацию через прокси NTLM или Kerberos с Codex? Codex не умеет напрямую аутентификацию по NTLM или Kerberos. Запустите локальный ретранслятор вроде cntlm или px, затем направьте HTTPS_PROXY на http://localhost:<порт-ретранслятора>.

Источники

Проблема с корпоративным прокси почти никогда не в том, что Codex сломан; дело в том, что Codex честно говорит на единственном диалекте прокси, который под него никто не настроил, — на простых переменных окружения. Всё вышеизложенное сверено с этими источниками на 2026-07-05:

• Продвинутая конфигурация OpenAI Codex и справочник по конфигу: https://developers.openai.com/codex/config-advanced
• Issue про переменные окружения прокси в OpenAI Codex: https://github.com/openai/codex/issues/4242
• PyPAC «About PAC files» о поведении PAC/WPAD: https://pypac.readthedocs.io/en/latest/about_pac.html
• Мануал pactester: https://manpages.ubuntu.com/manpages/focal/man1/pactester.1.html
• Снимок каталога моделей и документации ofox: https://ofox.ai/models