Codex CLI — терминальный агент программирования от OpenAI, который умеет читать код, изменять файлы и выполнять команды. Многие команды хотят подключить его к собственному шлюзу или стороннему OpenAI-совместимому входу, чтобы использовать единые ключи, счёт и управление лимитами. «Подключение своего API» на уровне конфигурации сводится к трём вещам: куда отправляется запрос (Base URL), чем подтверждается личность (ключ) и какая модель вызывается (имя модели); ошибки чаще всего возникают в способе авторизации, соответствии протокола и границах прав.

Статья основана на распространённых версиях по состоянию на октябрь 2026 года и последовательно проходит установку, авторизацию, настройку, проверку, песочницу и внедрение в команде. Codex развивается быстро — команды и параметры конфигурации сверяйте с codex --help и официальной документацией.

Примечание: OpenAI, Codex и ChatGPT — товарные знаки или зарегистрированные товарные знаки OpenAI. Статья носит технический характер и не подразумевает аффилированности с OpenAI. Требования к интерфейсам, идентификаторы моделей и тарификация могут меняться от версии к версии; сверяйтесь с официальной документацией и страницей «Модели и цены».

1. Сначала определите протокол и способ авторизации

Пользовательский provider в Codex CLI работает по протоколу Responses; wire_api сейчас принимает только responses, а старый вариант chat устарел и во многих версиях приводит к ошибке. Шлюз должен как минимум предоставлять совместимый вход /v1/responses и поддерживать потоковый вывод с завершающим событием response.completed. Если доступен только Chat Completions, нужен промежуточный слой преобразования протокола — просто вписать адрес нельзя.

Есть три пути авторизации, достаточно выбрать один:

Способ Типичная команда или настройка Когда подходит Замечания
Вход через аккаунт ChatGPT codex login Личное тестирование, временное использование Расходует квоту аккаунта, не подходит для CI
Вход по API Key codex login --with-api-key (ключ читается из stdin) Индивидуальное использование по факту Учётные данные сохраняются в auth.json или системном хранилище
Пользовательский provider env_key указывает на переменную окружения Командный шлюз, единый биллинг Ключ не попадает в TOML, проще задавать лимиты и отзывать

Текущий статус входа показывает codex login status, локальные учётные данные удаляет codex logout. Если одновременно существуют несколько типов учётных данных, сначала определите, какой из них реально действует, и только потом проверяйте конфигурацию.

2. Установка Codex CLI

Выберите способ для своей системы и после установки проверьте версию:

# Официальный установочный скрипт для macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Можно использовать пакетный менеджер; актуальные инструкции — в официальной документации
npm install -g @openai/codex
brew install --cask codex

codex --version

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

3. Настройка Base URL, ключа и модели

Пользовательская конфигурация находится в ~/.codex/config.toml, в Windows — в %USERPROFILE%\.codex\config.toml. Частая ловушка: ключи верхнего уровня должны идти до первого заголовка таблицы. Если записать model и model_provider после [model_providers.xxx], они станут полями этой таблицы, и это выглядит как «настройки не применились».

# ~/.codex/config.toml
model = "your-model-id"
model_provider = "zsqh"
web_search = "disabled"

[model_providers.zsqh]
name = "ZSQH AI Gateway"
base_url = "https://ai.zhongshangqihang.com/v1"
wire_api = "responses"
env_key = "ZSQH_API_KEY"

Значение полей:

  • model: идентификатор API, а не отображаемое имя на сайте; должен полностью совпадать со страницей цен.
  • model_provider: совпадает с ID provider ниже; не используйте зарезервированные имена openai, ollama, lmstudio.
  • base_url: включает путь API, обычно заканчивается на /v1; не дублируйте путь.
  • wire_api: укажите responses.
  • env_key: имя переменной окружения, а не сам ключ.
  • web_search: если шлюз не поддерживает поиск в интернете, сначала установите disabled, чтобы запросы не уходили в неподключённую возможность.

Затем экспортируйте ключ в той же оболочке, из которой запускаете Codex:

export ZSQH_API_KEY="sk-ваш-ключ"

В Windows PowerShell используйте $env:ZSQH_API_KEY="sk-ваш-ключ". Для постоянного действия добавьте переменную в конфигурацию оболочки или системные переменные и убедитесь, что редактор, запущенный из графического интерфейса, тоже её видит.

Если шлюз требует пользовательский заголовок, можно использовать env_http_headers = { "X-API-Key" = "ZSQH_API_KEY" }; этот способ не использует удалённое обнаружение каталога, поэтому нужно также предоставить локальный каталог моделей model_catalog_json. Если ключ динамически выдаётся инструментом управления секретами, можно получать токен через command в [model_providers.zsqh.auth], но его нельзя сочетать с env_key. При большом числе алиасов моделей можно рассмотреть model_catalog_url или локальный model_catalog_json; без такой необходимости усложнять конфигурацию не стоит.

Запомните ещё одно: доверенный проект загружает .codex/config.toml, но model_provider, model_providers и определения профилей из него игнорируются. Provider обязательно должен быть в пользовательской конфигурации.

4. Проверка, что подключение действительно работает

Выполняйте по порядку — так проще отличить «инструмент не настроен» от «шлюз недоступен»:

  1. Выполните codex login status, определите текущий способ авторизации; убедитесь, что переменная из env_key не пуста в среде запуска. Не печатайте ключ целиком в общем терминале.
  2. Выполните codex doctor, проверьте расположение файлов конфигурации, переменные окружения и типичные конфликты настроек.
  3. В тестовом репозитории выполните codex exec "Ответь ровно: gateway-ok". Ответ gateway-ok означает, что базовая цепочка работает. codex exec по умолчанию использует песочницу только для чтения — это удобно для дымового теста.
  4. Войдите в интерактивный режим и выполните /status, сверьте текущую модель и provider с настроенными значениями.
  5. Откройте журнал запросов в консоли шлюза, проверьте пользователя, алиас модели и маршрут upstream. Ответ в клиенте сам по себе недостаточен: он может прийти из кэша или старой конфигурации.
  6. Если ошибка осталась, сверьте /v1 и /responses в Base URL, затем проверьте, не переписывает ли прокси заголовок Authorization и не удаляет ли его.

5. Песочница и подтверждения: два независимых переключателя

Многие путают «автоматическое выполнение» и «какие файлы можно менять». Codex разделяет это на два механизма: политика подтверждений решает, когда процесс остановится и спросит вас, а песочница определяет, к каким файлам и сети имеет доступ процесс.

В текущих версиях распространённое значение approval_policy — on-request, оно подходит для большинства повседневных задач; never рекомендуется только в изолированной автоматизированной среде. Старый untrusted больше не поддерживается, on-failure также устарел; копирование старых руководств часто приводит к ошибке конфигурации.

У sandbox_mode три значения: read-only, workspace-write и danger-full-access. Начинайте с режима только для чтения; для изменения кода используйте workspace-write и ограничьте доступные для записи каталоги через sandbox_workspace_write.writable_roots; danger-full-access допустим только в контейнере или одноразовом runner. Если нужен сетевой доступ, отдельно включите sandbox_workspace_write.network_access, а не расширяйте все права сразу.

В неинтерактивном режиме песочницу можно задать через codex exec --sandbox workspace-write; если организация допускает автоматическую проверку, добавьте --approve-for-me. Учтите, что --full-auto больше не поддерживается — старые скрипты с этим параметром нужно исправить. В интерактивном режиме текущие права показывает и меняет /permissions.

6. Внедрение в команде: сначала малый круг, затем единая конфигурация

Начните с двух-трёх человек и одного некритичного репозитория, а после успешного пилота расширяйте. Главное при внедрении — не «сколько людей установили», а воспроизводимость конфигурации и возможность локализовать сбой.

  • Один ключ на человека, при необходимости дополнительно по проектам или средам; не используйте один ключ на всю команду.
  • На стороне шлюза задайте бюджет, параллельность и белый список моделей, чтобы цикл агента не выжигал лимит.
  • Используйте корпоративную управляемую конфигурацию для approval_policy, sandbox_mode и cli_auth_credentials_store; requirements.toml может запретить опасные комбинации вроде never и danger-full-access.
  • Если нужно принудительно задать способ входа, используйте forced_login_method = "chatgpt" или "api", чтобы сотрудники не смешивали учётные данные.
  • Ведите шаблон конфигурации без ключей: Base URL, идентификатор модели и команды диагностики.
  • Раз в месяц сверяйте расход шлюза по людям, проектам и моделям.

7. Чек-лист безопасности

  • Ключ хранится только в переменных окружения, системном хранилище или сервисе управления секретами; не пишите его в config.toml и Git. Поле experimental_bearer_token существует, но официально не рекомендуется.
  • Для Codex используйте отдельный ключ, чтобы задавать лимит, срок действия и отдельно отзывать его.
  • По умолчанию — песочница только для чтения; при необходимости записи ограничьте её конкретным каталогом репозитория и отзывайте права после задачи.
  • Не помещайте в контекст .env, auth.json, производственные конфигурации и данные клиентов; в больших репозиториях сначала исключайте артефакты сборки и каталоги зависимостей.
  • Проверяйте команды и патчи, сгенерированные Codex, особенно удаление, сетевые запросы и повышение прав.
  • Зафиксируйте версию Codex в командном образе и проверяйте совместимость конфигурации в тестовой среде перед обновлением.
  • Включите оповещения о расходе на шлюзе: при аномальных вызовах сначала остановите ключ, затем изучайте журналы.

Частые вопросы

Обязательно ли Codex CLI использует протокол Responses?

Текущий пользовательский provider принимает wire_api только со значением responses; старый chat устарел. Если шлюз предоставляет только Chat Completions, нужен слой преобразования протокола или вход с поддержкой Responses.

Конфигурация написана, почему запросы всё равно идут на адрес по умолчанию?

Проверьте, что изменён именно ~/.codex/config.toml, что ключи верхнего уровня стоят до заголовков таблиц, а model_provider точно совпадает с ID provider. Определения provider в конфигурации проекта игнорируются — это частая причина.

Можно ли писать ключ прямо в config.toml?

Не рекомендуется. Используйте env_key со ссылкой на переменную окружения или [model_providers.xxx.auth] с внешней командой получения токена. Открытый ключ легко утекает вместе с резервной копией конфигурации, скриншотом или репозиторием.

Вход через ChatGPT и API Key тарифицируются одинаково?

Нет. Вход через ChatGPT использует квоту аккаунта, API Key оплачивается по факту вызовов; лимиты, счета и объём прав различаются, поэтому команде нужно учитывать их раздельно.

Можно ли команде использовать один общий ключ?

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

Что дальше

Сложность подключения Codex не в установке, а в соответствии протокола и границах прав: сначала убедитесь, что шлюз поддерживает Responses и потоковое завершающее событие, затем настройте Base URL, ключ и модель, а в конце проведите дымовой тест в песочнице только для чтения. Если нужен единый вход и управление расходом, можно зарегистрироваться в ZSQH AI Gateway; модели и доступные интерфейсы смотрите на странице «Модели и цены».

Читайте также: