Перед настройкой Codex в VS Code ответьте на три вопроса: какое расширение открывает панель, кто выдал credential и куда реально отправляется запрос модели. Эти ответы могут принадлежать трём разным организациям. Поэтому поле «API key» само по себе ничего не объясняет.
Надёжный результат выглядит так: вы установили официальное расширение OpenAI, осознанно выбрали вход ChatGPT или API key, задали provider в пользовательском config.toml, а затем подтвердили маршрут небольшой правкой, diff и существующей проверкой проекта.
Составьте паспорт маршрута
До любых изменений запишите предполагаемую схему без секретов:
| Вопрос | Пример ответа | Кто отвечает за сбой |
|---|---|---|
| Какая поверхность используется? | Официальное расширение Codex для VS Code | расширение, VS Code, текущий local/remote host |
| Как выполнен вход? | ChatGPT или OpenAI Platform API key | соответствующий аккаунт, workspace или API project |
| Какой provider активен? | встроенный OpenAI, company gateway, local runtime | владелец endpoint и его политики |
| Какая модель выбрана? | точный API model ID | каталог и права provider |
| Чем подтверждается результат? | ограниченный diff и прошедший тест | ваш репозиторий и процесс review |
Если один пункт неизвестен, сначала выясните его. Случайная замена ключа одновременно с Base URL и моделью создаёт три новые причины ошибки.
Установите именно официальное расширение
Откройте официальную страницу Codex IDE и перейдите по ссылке Visual Studio Code. Сверьте расширение и publisher с официальным маршрутом. Не выбирайте продукт только по слову Codex или похожей иконке: настройки других AI-расширений не являются настройками Codex.
После установки откройте знакомый Git-проект. Нажмите значок Codex в Activity Bar. Если значка нет, вызовите Command Palette и выполните Codex: Open Codex Sidebar.
Успешно открытая панель доказывает лишь загрузку расширения. Она не подтверждает авторизацию, доступ к модели, контекст проекта или правильность будущей правки.
Выберите владельца авторизации и биллинга
Для локального расширения доступны два способа входа, описанные в документации OpenAI по авторизации:
- Sign in with ChatGPT связывает Codex с выбранным аккаунтом и workspace ChatGPT.
- Use API Key принимает ключ из OpenAI Platform; использование оплачивается через API project по стандартным API-тарифам.
API key не переносит включённый объём подписки ChatGPT в Platform. И наоборот, подписка ChatGPT не оплачивает запросы внешнего gateway. На API-key маршруте функции, зависящие от ChatGPT workspace или cloud services, могут быть ограничены.
Если расширение уже авторизовано, откройте profile menu, проверьте текущий метод и выполните Log out, прежде чем выбрать другой. Не начинайте переключение с удаления ~/.codex/auth.json: CLI и IDE используют общий кэш входа, а ручное удаление скрывает исходное состояние и создаёт дополнительную проблему хранения credential.
Ключ нельзя вставлять в prompt, исходный код, issue, screenshot или общий конфигурационный файл. Для выбора между подпиской и Platform отдельно разберите Codex API key и subscription.
Откройте конфигурацию, которую читает Codex
Настройки IDE делятся на два типа. Параметры интерфейса расширения находятся в VS Code и используют ключи chatgpt.*. Выбор модели, provider, permissions и другие параметры агента читаются из config.toml.
OpenAI подтверждает в основах конфигурации, что CLI и IDE extension разделяют слои конфигурации. В панели Codex нажмите шестерёнку, затем Codex Settings > Open config.toml. Для персонального provider нужен файл:
text~/.codex/config.toml
Не помещайте машинный endpoint и provider credential в repository-level .codex/config.toml. Репозиторий не должен незаметно перенаправлять личный трафик разработчика.
Опишите сторонний provider минимально
Ниже показана связь полей, а не готовый сервис. Замените hostname, переменную и model ID значениями из документации выбранного provider:
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 и названии table. Не переопределяйте зарезервированные built-in ID openai, ollama и lmstudio. base_url берётся из API-документации provider, а не из адреса его личного кабинета. env_key — имя переменной окружения, не секрет. model — точный API ID, а не маркетинговое название.
Для текущего shell macOS/Linux:
bashexport PRIVATE_GATEWAY_API_KEY="<provider-key>" code .
Для текущего PowerShell:
powershell$env:PRIVATE_GATEWAY_API_KEY = "<provider-key>" code .
Запускайте VS Code из того окружения, где установлена переменная. Dock, Start menu, WSL, Remote SSH и dev container могут передать другой environment. Проверяйте наличие переменной, но не печатайте её значение в лог.
В официальном разделе custom providers также есть OpenAI auth, command-backed token и no-auth вариант для локальных сервисов. Используйте один метод, соответствующий реальному контракту provider.
Совместимый JSON ещё не означает совместимый агент
Надпись OpenAI-compatible может означать только сходный request body. Codex дополнительно зависит от поведения Responses API, streaming events, tool calls, ошибок, model IDs и возможностей конкретной модели. Provider может поддерживать простой текст и не поддерживать инструменты, которые понадобятся агенту.
Перед большим заданием подтвердите по отдельности:
- Документирован ли точный Base URL и wire API?
- Авторизует ли ключ выбранную модель?
- Возвращает ли endpoint нормальный stream?
- Работают ли требуемые tool calls?
- Кто владеет quota, billing, retention и поддержкой?
Корректно разобранный TOML доказывает только форму конфигурации. Один текстовый ответ доказывает только один путь запроса.
Проведите первую проверку на маленькой правке
Выберите функцию, поведение которой вам известно. До запроса сохраните состояние:
bashgit status --short
Откройте файл, выделите одну функцию и задайте узкие границы:
textПроверь только выделенную функцию parseConfig. Пустая строка должна возвращать существующий тип ошибки. Не меняй публичный API, другие файлы и зависимости. Покажи предполагаемый diff и назови существующий тест для проверки.
После ответа проверьте не описание, а артефакты:
bashgit diff -- path/to/file git status --short
Успех состоит из четырёх независимых сигналов: нет ошибки авторизации, нет endpoint/model error, ответ использует реальные детали выделенного кода, diff ограничен задачей и существующая проверка проходит. Если сработал только чат, нельзя считать доказанными tools или корректность кода.
Ищите первую сломанную границу
Нет значка или команды Codex
Проверьте расширение, enabled state в текущем окне и место установки для local/Remote/WSL. API key не исправляет незагруженное расширение.
Панель открывается, но вход не завершается
Определите, должен ли владельцем быть ChatGPT workspace или OpenAI Platform project. Проверьте состояние соответствующего аккаунта без передачи ключа. Модель и Base URL пока не меняйте.
Codex игнорирует custom provider
Убедитесь, что изменён пользовательский файл, ID совпадают и более приоритетный слой не выбирает другое значение. Подробный разбор есть в статье почему Codex config.toml не работает.
Возникают 401/403, 404 или model not found
Для 401/403 сначала проверяются environment, владелец credential и entitlement provider. Для 404/model-not-found — Base URL, путь и точный ID. Сохраняйте исходный error и время, но удаляйте token, headers, account IDs и приватный код.
Текст работает, а tools или stream — нет
Это сигнал о capability provider. Уменьшите задачу до одной неработающей функции и сверяйте её с документацией сервиса. Расширение filesystem permissions не устраняет несовместимость модельного endpoint.
Зафиксируйте без секретов версии VS Code и расширения, auth method, provider ID, hostname, model ID, исходную ошибку, границы diff и команду теста. Такой паспорт позволяет увидеть, какой владелец изменился после обновления, и не превращает каждую ошибку в повторную установку всего стека.
