Codex в VS Code: API-ключ, сторонняя модель и проверка настройки

Перед настройкой Codex в VS Code ответьте на три вопроса: какое расширение открывает панель, кто выдал ключ или предоставил способ входа и куда реально отправляется запрос модели. Эти ответы могут принадлежать трём разным организациям. Поэтому поле «API key» само по себе ничего не объясняет.

Надёжный результат выглядит так: вы установили официальное расширение OpenAI, осознанно выбрали вход через ChatGPT или API-ключ, выбрали поставщика модели в пользовательском config.toml, а затем проверили подключение на небольшой правке, просмотрели изменения и запустили существующий тест проекта.

Определите, как устроено подключение

До любых изменений запишите предполагаемую схему без секретов:

Если один пункт неизвестен, сначала выясните его. Случайная замена ключа одновременно с Base URL и моделью создаёт три новые причины ошибки.

Установите именно официальное расширение

Откройте официальную страницу Codex IDE и перейдите по ссылке Visual Studio Code. Сверьте название расширения и его издателя с данными на официальной странице. Не выбирайте продукт только по слову Codex или похожей иконке: настройки других AI-расширений не являются настройками Codex.

После установки откройте знакомый Git-проект. Нажмите значок Codex в Activity Bar. Если значка нет, вызовите Command Palette и выполните Codex: Open Codex Sidebar.

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

Выберите владельца авторизации и биллинга

Для локального расширения доступны два способа входа, описанные в документации OpenAI по авторизации:

• Sign in with ChatGPT связывает Codex с выбранным аккаунтом и рабочим пространством ChatGPT.
• Use API Key принимает ключ из OpenAI Platform; использование оплачивается в проекте API по стандартным API-тарифам.

API-ключ не переносит включённый объём подписки ChatGPT в Platform. И наоборот, подписка ChatGPT не оплачивает запросы стороннего шлюза. При входе по API-ключу функции, зависящие от рабочего пространства ChatGPT или облачных сервисов, могут быть ограничены.

Если расширение уже авторизовано, откройте меню профиля, проверьте текущий метод и выполните Log out, прежде чем выбрать другой. Не начинайте переключение с удаления ~/.codex/auth.json: CLI и IDE используют общий кэш входа, а ручное удаление скрывает исходное состояние и создаёт дополнительную проблему хранения учётных данных.

Ключ нельзя вставлять в текст задания, исходный код, отчёт об ошибке, снимок экрана или общий конфигурационный файл. Для выбора между подпиской и Platform отдельно разберите API-ключ Codex и подписку.

Откройте конфигурацию, которую читает Codex

Настройки IDE делятся на два типа. Параметры интерфейса расширения находятся в VS Code и используют ключи chatgpt.*. Выбор модели, поставщика и разрешений и другие параметры агента читаются из config.toml.

OpenAI подтверждает в основах конфигурации, что CLI и расширение IDE используют общую систему конфигурации. В панели Codex нажмите шестерёнку, затем Codex Settings > Open config.toml. Для персональной настройки поставщика модели нужен файл:

~/.codex/config.toml

Не помещайте адрес персонального сервиса и его учётные данные в файл .codex/config.toml внутри репозитория. Репозиторий не должен незаметно перенаправлять личный трафик разработчика.

Добавьте минимальную конфигурацию стороннего поставщика

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

# ~/.codex/config.toml
model = "EXACT_MODEL_ID"
model_provider = "private_gateway"

[model_providers.private_gateway]
name = "Private gateway"
base_url = "https://gateway.example.com/v1"
env_key = "PRIVATE_GATEWAY_API_KEY"
wire_api = "responses"

private_gateway должен точно совпадать в model_provider и названии секции TOML. Не переопределяйте зарезервированные встроенные идентификаторы openai, ollama и lmstudio. base_url берётся из документации API поставщика, а не из адреса его личного кабинета. env_key — имя переменной окружения, не секрет. model — точный API ID, а не маркетинговое название.

Для текущего сеанса оболочки macOS/Linux:

export PRIVATE_GATEWAY_API_KEY="<provider-key>"
code .

Для текущего PowerShell:

$env:PRIVATE_GATEWAY_API_KEY = "<provider-key>"
code .

Запускайте VS Code из того окружения, где установлена переменная. При запуске через Dock, меню «Пуск», WSL, Remote SSH или контейнер разработки окружение может отличаться. Проверяйте наличие переменной, но не печатайте её значение в лог.

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

Совместимый JSON ещё не означает совместимый агент

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

Перед большим заданием подтвердите по отдельности:

1. Документирован ли точный базовый адрес и протокол API?
2. Авторизует ли ключ выбранную модель?
3. Возвращает ли API корректный потоковый ответ?
4. Работают ли нужные вызовы инструментов?
5. Кто устанавливает квоты, выставляет счёт, хранит данные и предоставляет поддержку?

Корректно разобранный TOML доказывает только форму конфигурации. Один текстовый ответ доказывает только один путь запроса.

Проведите первую проверку на маленькой правке

Выберите функцию, поведение которой вам известно. До запроса сохраните состояние:

git status --short

Откройте файл, выделите одну функцию и задайте узкие границы:

Проверь только выделенную функцию parseConfig.
Пустая строка должна возвращать существующий тип ошибки.
Не меняй публичный API, другие файлы и зависимости.
Покажи предполагаемый diff и назови существующий тест для проверки.

После ответа проверьте не описание, а артефакты:

git diff -- path/to/file
git status --short

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

Найдите этап, на котором возникла ошибка

Нет значка или команды Codex

Проверьте, включено ли расширение в текущем окне и установлено ли оно в нужной среде: локально, на удалённом компьютере или в WSL. API-ключ не исправит проблему загрузки расширения.

Панель открывается, но вход не завершается

Уточните, к чему должен относиться вход: к рабочему пространству ChatGPT или проекту OpenAI Platform. Проверьте состояние соответствующего аккаунта без передачи ключа. Модель и Base URL пока не меняйте.

Codex игнорирует стороннего поставщика

Убедитесь, что изменён пользовательский файл, ID совпадают и более приоритетный слой не выбирает другое значение. Подробный разбор есть в статье почему Codex config.toml не работает.

Возникают 401/403, 404 или model not found

При 401/403 проверьте окружение, источник ключа и права доступа у поставщика. При 404 или model-not-found — базовый адрес, путь запроса и точный идентификатор модели. Сохраните исходную ошибку и время; перед передачей журнала удалите токены, секреты в заголовках, идентификаторы аккаунта и закрытый код.

Текст работает, а инструменты или потоковая выдача — нет

Это указывает на возможное ограничение возможностей API поставщика. Уменьшите задачу до одной неработающей функции и сверяйте её с документацией сервиса. Расширение прав на файловую систему не устраняет несовместимость API модели.

Запишите версии VS Code и расширения, способ входа, идентификаторы поставщика и модели, имя сервера, исходную ошибку, изменённые файлы и команду теста. Эти сведения помогут найти изменение конфигурации после обновления без повторной установки всех компонентов.