Настройка Codex CLI: разбор config.toml и типовые ошибки подключения
Habr AI · оригинал
Материал подготовлен автоматизированной редакционной системой. Факты можно сверить по указанному первоисточнику.
Статья детально разбирает структуру конфигурационного файла Codex CLI и описывает девять распространенных ошибок, препятствующих корректной работе с кастомными эндпоинтами. Автор также анализирует механизм потребления токенов и выявляет несоответствия в кэшировании контекста между различными режимами запуска инструмента.
Ценность: Понимание специфики конфигурации Codex CLI критически важно для разработчиков, использующих альтернативные прокси-серверы или локальные модели, так как стандартные переменные окружения OpenAI здесь не работают. Кроме того, выявленные проблемы с кэшированием токенов напрямую влияют на стоимость использования API и эффективность работы с инструментом.
Codex CLI отличается от Claude Code подходом к настройке: вместо универсальной переменной окружения для URL здесь используется файл config.toml. В материале представлен минимальный рабочий конфиг, где ключевыми являются поля model_provider, base_url и wire_api. Важно отметить, что без явного указания имени провайдера инструмент по умолчанию обращается к api.openai.com, игнорируя любые другие настройки. Протокол взаимодействия жестко задан: в версии 0.154 поддерживается только режим responses, а устаревший chat больше не функционирует.
Автор статьи систематизировал девять способов «сломать» конфигурацию, каждый из которых был воспроизведен на практике. Самая частая ошибка — попытка использовать переменную OPENAI_BASE_URL, которая полностью игнорируется Codex. Другой типичный сценарий — отсутствие суффикса /v1 в base_url, что приводит к запросам на корневой домен и получению HTML-страниц вместо JSON-ответов. Также выявлено, что неизвестные идентификаторы моделей не блокируют запуск, но приводят к использованию запасных метаданных, что может деградировать производительность.
Отдельного внимания заслуживает вопрос безопасности и совместимости. Использование параметра experimental_bearer_token для хранения ключа прямо в конфиге создает риск утечки данных при копировании файлов настроек. Рекомендуется использовать env_key, ссылающийся на переменную окружения. Параметры supports_websockets и requires_openai_auth описаны как потенциально вредные или бесполезные: первый вызывает лишние попытки подключения к WebSocket-шлюзам, а второй не влияет на авторизацию при наличии корректного ключа.
Значительная часть материала посвящена экономике использования токенов. Тестирование показало, что даже короткий запрос потребляет около 15 000 входных токенов из-за системного промпта и описаний инструментов. При этом выявлена аномалия: при использовании режима resume кэш входных токенов не читается (cached_input_tokens: 0), тогда как прямые запросы через curl демонстрируют нормальное кэширование. Это несоответствие может значительно увеличить расходы пользователей, так как каждый ход сессии будет оплачиваться как новый.
Для диагностики рекомендуется использовать команду codex exec --json и анализировать поле usage в событии turn.completed. Это позволяет точно отслеживать количество использованных токенов и эффективность кэширования. В заключение автор предлагает чек-лист для проверки конфигурации: соответствие имени провайдера, корректность URL, наличие /v1 в адресе и экспорт переменной с ключом в текущей оболочке.
Материал актуален для разработчиков, мигрирующих на Codex CLI или использующих его в связке с самописными прокси-серверами. Понимание этих нюансов позволяет избежать длительной отладки и оптимизировать затраты на API-вызовы.