Codex API: свой ключ, Base URL и модель (2026)

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

Разберём на примере распространённых версий октября 2026 года три вещи: как установить Codex CLI, как написать config.toml и как проверить и отладить работу с собственным шлюзом.

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

1. Три формы Codex

Форма	Вход	Можно ли использовать свой ключ
Codex CLI	Команда `codex` в терминале	Да, через config.toml
Расширение IDE	Боковая панель редактора	Зависит от версии, обычно через аккаунт
Облачные задачи	Веб-интерфейс	Обычно используется аккаунт ChatGPT

Для большинства разработчиков основная площадка для своего API — Codex CLI. Он читает код, изменяет файлы и запускает команды, а модель отвечает только за рассуждения. При замене конечной точки модели инструменты по-прежнему выполняются локально.

2. API-ключ и Base URL для Codex

Собственному провайдеру в Codex CLI нужны три параметра: Base URL, API-ключ и имя модели. Официальный адрес по умолчанию — https://api.openai.com/v1; при использовании ZSQH AI Gateway адрес — https://ai.zhongshangqihang.com/v1.

Параметр	Официальное значение	Шлюз ZSQH
Base URL	`https://api.openai.com/v1`	`https://ai.zhongshangqihang.com/v1`
Авторизация	API-ключ OpenAI	Ключ, созданный в консоли шлюза
Протокол	Responses API	Предоставляется вход `/v1/responses`, поддержка моделей — по документации
Имя модели	Официальный ID	По странице тарифов

Здесь есть важное изменение 2026 года: собственный провайдер Codex CLI принимает только wire_api = "responses", старый wire_api = "chat" удалён. Значит, шлюз должен уметь пересылать протокол Responses; если доступен только Chat Completions, нужен промежуточный слой преобразования протокола или другой клиент. ZSQH AI Gateway предоставляет вход /v1/responses; какие именно модели поддерживают Responses, уточняйте в документации и на странице тарифов.

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

Выберите способ для своей системы:

# npm
npm install -g @openai/codex

# macOS Homebrew
brew install --cask codex

# Проверка версии после установки
codex --version

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

Выполните codex в терминале.
Выберите способ входа по подсказке.
Создайте тестовый каталог и попросите прочитать один файл.
Убедившись в нормальном ответе, переключайтесь на своего провайдера.

4. Написание config.toml

Пользовательская конфигурация Codex CLI находится в ~/.codex/config.toml. Файл .codex/config.toml в каталоге проекта не переопределяет определение провайдера, из-за чего легко решить, что настройка не применилась.

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

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

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

model — ID модели для вызова; должен полностью совпадать с идентификатором на странице тарифов.
model_provider — имя провайдера, определённого ниже; значения должны совпадать.
base_url — корневой OpenAI-совместимый адрес, обычно заканчивается на /v1.
env_key — имя переменной окружения с ключом; не вписывайте ключ прямо в файл.
wire_api — для текущей версии указывается responses.

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

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

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

5. Проверка первого запроса

В интерактивном режиме просто выполните codex и задайте в каталоге проекта вопрос только на чтение, например «объясни входной файл этого каталога». Если нужна одноразовая неинтерактивная проверка, используйте codex exec (если подкоманда есть в вашей версии — сначала проверьте codex exec --help):

cd /path/to/your-project
codex exec "Опиши структуру каталогов проекта тремя пунктами, не изменяй файлы"

Чтобы посмотреть, куда уходит запрос, включите отладочный лог:

codex --log-level debug

Смотрите, направлен ли запрос на ваш Base URL, содержит ли путь /responses и передаётся ли имя модели без изменений. Частая причина «конфигурация не работает» — терминал не перечитал переменные окружения или файл изменён не в том месте.

6. Как выбрать модель

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

Сценарий	Рекомендация	На что обратить внимание
Повседневная правка кода	Универсальная или кодовая модель	Поддержка потокового вывода
Чтение больших репозиториев	Модель с длинным контекстом	Чем длиннее контекст, тем выше стоимость запроса
Многошаговые задачи	Модель со стабильным вызовом инструментов	Сначала проверьте на небольшой задаче
Пакетные скрипты	Модель подешевле	Ограничьте повторы при сбоях

ID модели смотрите на странице тарифов. Одна из самых частых ошибок — вписать в model отображаемое название со страницы: оно часто не совпадает с API-идентификатором.

7. Типовые ошибки и решения

Симптом	Частая причина	Что делать
`401 Unauthorized`	Ключ не экспортирован или указан неверно	Откройте новый терминал, проверьте значение переменной из `env_key`
`404 Not Found`	В Base URL лишний или недостающий `/v1`, шлюз не поддерживает `/responses`	Сверьте адрес и набор интерфейсов
Ошибка `wire_api = "chat"`	Используется старая конфигурация	Укажите `responses` или обновите Codex
`model not found`	ID не совпадает со страницей тарифов	Скопируйте точный идентификатор
Запрос обрывается	Сеть или тайм-аут потокового ответа	Проверьте прокси, тайм-ауты и повторы
`429`	Лимит запросов или исчерпана квота	Посмотрите расход в шлюзе, снизьте параллельность

Если шлюз поддерживает только Chat Completions, а текущая версия Codex — только Responses, надёжнее добавить слой преобразования протокола (например, шлюз вроде LiteLLM), чем искать старые версии. Старые версии рано или поздно перестают поддерживаться.

8. Безопасность и расходы

Храните ключ только в переменных окружения или менеджере секретов, не в Git.
Выпустите для Codex отдельный ключ, чтобы удобно задавать лимиты и отзывать его.
Настройте на шлюзе бюджет и лимит параллельных запросов, чтобы циклы агента не выжигали квоту.
В больших репозиториях заранее исключите артефакты сборки, каталоги зависимостей и файлы с секретами.
Регулярно смотрите отчёты о расходе и разделяйте затраты по проектам.
Не вставляйте в промпты рабочие ключи, клиентские данные и необезличенные логи.

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

Codex API и подписка ChatGPT — это одно и то же?

Нет. Подписка ChatGPT относится к веб-продуктам и клиентам; Codex CLI может работать через вход в аккаунт или через API-ключ с оплатой по факту. Модели тарификации разные, при закупке для команды их нужно считать отдельно.

Поддерживает ли Codex CLI интерфейс Chat Completions?

Собственный провайдер текущей версии поддерживает только протокол Responses, wire_api = "chat" удалён. Для конечных точек только с Chat Completions нужен слой преобразования протокола.

Почему изменения в config.toml не действуют?

Убедитесь, что изменён ~/.codex/config.toml, а не файл внутри проекта; проверьте, что model_provider совпадает с именем в [model_providers.xxx]; затем откройте новый терминал, чтобы подхватились переменные окружения.

В поле model указывать отображаемое имя или API-идентификатор?

API-идентификатор. Отображаемое имя предназначено для интерфейса; при ошибке обычно возвращается model not found. Точное значение смотрите в разделе тарифов.

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

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

Что дальше

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