Codex model_catalog_json: руководство по настройке
По состоянию на 2026-10-08 model_catalog_json — необязательный ключ в config.toml Codex, значение которого — путь к JSON-каталогу моделей; Codex читает его только при запуске. В комментариях открытого исходного кода Codex сказано, что заданный каталог заменяет встроенный каталог моделей для текущего процесса, а варианты в выборе /model строятся из действующего каталога. Файл профиля может его переопределить, и если ключ задан в обоих файлах, побеждает профиль. На этой странице по официальному справочнику, журналу изменений и открытому исходному коду Codex разобраны формат, правила переопределения, изменение в 0.160.0 и типичные причины, по которым модели нет в /model.
Обновлено 2026-10-08
Четыре главных пункта
Когда применяется
Официальный справочник: путь к JSON-каталогу моделей, который загружается при запуске. Схема конфигурации в открытом коде Codex добавляет, что переопределения config внутри сессии принимаются, но повторно его не применяют, поэтому после правки файла перезапустите Codex.
Связь со встроенным каталогом
Комментарий в открытом коде Codex: заданный каталог заменяет встроенный для текущего процесса; варианты /model строятся из действующего каталога, сортируются по priority и фильтруются по способу аутентификации и visibility.
Если задан в обоих файлах
Официальная расширенная конфигурация: файлы профилей тоже могут переопределять model_catalog_json, и при значении в обоих файлах Codex берёт значение профиля.
Явные каталоги провайдеров
Codex CLI 0.160.0 от 2026-10-01: явные каталоги моделей провайдеров больше не подмешивают неподдерживаемые встроенные модели и не используют устаревшие записи после неудачного обновления.
Зачем нужен model_catalog_json
По состоянию на 2026-10-08 model_catalog_json позволяет передать Codex собственный каталог моделей: официальный справочник описывает его как «Optional path to a JSON model catalog loaded on startup», тип string (path), а в официальном примере конфигурации он записан как model_catalog_json = "/absolute/path/to/models.json" с пометкой, что это переопределение каталога только при запуске. Комментарии в открытом коде Codex идут дальше: заданный каталог заменяет встроенный для текущего процесса, и выбор /model строит варианты из действующего каталога. Значит, если нужно, чтобы /model показывал только выбранные вами модели, или нужно поменять отображаемые имена и порядок, правят именно этот файл. Есть два ограничения: в таблице совместимости локального доступа с Work Cloud справочник отмечает, что ключ не поддерживается как управляемое облачное переопределение и локальный каталог туда не переносится; администраторы могут также жёстко задать JSON-каталог, который Codex использует при запуске, через requirements.toml.
Изменения по версиям (от 0.156.0 до 0.161.0)
В полном списке изменений Codex CLI 0.156.0 (2026-09-22) есть #46561 «Support explicit provider model catalog URLs»; в PR сказано, что в конфигурацию провайдера добавлен model_catalog_url и что для получения каталога по API-ключу при собственном base_url нужен явный URL каталога. Заметки к 0.160.0 (2026-10-01): «Explicit provider model catalogs no longer include unsupported bundled models or reuse stale entries after refresh failures». PR #49135 поясняет: раньше провайдеры с model_catalog_url могли показывать встроенные модели, которых нет в их каталоге; теперь slug в каталоге должны быть уникальными и непустыми, метаданные сопоставляются по точному ID модели, а запуск без доступных моделей даёт ошибку конфигурации, хотя явно заданная model по-прежнему допускается. В 0.161.0 (2026-10-07) GPT-6.1 Sol стала моделью по умолчанию во встроенном каталоге и каталогах Amazon Bedrock.
Хронология каталога моделей
Вышел Codex CLI 0.156.0; в полном списке изменений есть #46561, который добавляет model_catalog_url в конфигурацию провайдера.
Вышел Codex CLI 0.160.0: явные каталоги провайдеров больше не подмешивают неподдерживаемые встроенные модели и не используют устаревшие записи после неудачного обновления.
Вышел Codex CLI 0.161.0: GPT-6.1 Sol стала моделью по умолчанию во встроенном каталоге и каталогах Amazon Bedrock; страница сверена с официальными источниками 2026-10-08.
Подтверждено vs официально не описано
Подтверждено (дословно по документации и открытому коду)
Всё перечисленное можно дословно проверить в официальной документации Codex, журнале изменений или открытом коде Codex (схема конфигурации, исходники, описания PR): model_catalog_json — путь к JSON-каталогу моделей, загружаемому при запуске; переопределения config внутри сессии его повторно не применяют; заданный каталог заменяет встроенный для текущего процесса; варианты /model сортируются по priority и фильтруются по способу аутентификации и visibility; файл профиля может его переопределить, и при значении в обоих файлах берётся значение профиля; начиная с 0.134.0 --profile не читает таблицу [profiles.profile-name] в config.toml; в Work Cloud ключ не поддерживается как управляемое облачное переопределение; ошибка разбора JSON и пустой каталог дают каждый свою ошибку при запуске; начиная с 0.160.0 явные каталоги провайдеров не подмешивают неподдерживаемые встроенные модели; начиная с 0.161.0 GPT-6.1 Sol — модель по умолчанию во встроенном каталоге.
Официально не описано, поэтому без выводов
Три вещи не документированы, и эта страница их не додумывает: во-первых, какие поля записи обязательны и какие значения они принимают — таблицы полей в документации нет, ориентиром служит встроенный models.json из открытого кода Codex; во-вторых, как разрешаются относительные пути — справочник пишет лишь string (path), основной пример использует абсолютный путь, а в примере профиля встречается ./models.json, так что надёжнее абсолютный путь; в-третьих, изменение 0.160.0 для явных каталогов провайдеров в PR называет model_catalog_url, и распространяются ли те же правила на локальный model_catalog_json, официально не сказано. Кроме того, на 2026-10-08 model_catalog_url можно найти в схеме конфигурации и описаниях PR открытого кода Codex; в справочнике на developers.openai.com этого ключа нет.
model_catalog_json или model_catalog_url
model_catalog_json (локальный файл)
Задаётся на верхнем уровне config.toml или файла профиля; значение — путь к локальному JSON-файлу, который читается только при запуске и заменяет встроенный каталог. Подходит тем, кто хочет зафиксировать список /model или держать разные каталоги для разных профилей. В Work Cloud как управляемое облачное переопределение не работает.
model_catalog_url (на уровне провайдера)
Задаётся в конфигурации конкретного провайдера; схема конфигурации в открытом коде Codex описывает его как «Optional full URL for a Codex-native model catalog», а по описанию PR Codex запрашивает каталог с аутентификацией этого провайдера. Подходит, когда каталог ведёт сам шлюз; начиная с 0.160.0 такие явные каталоги считаются авторитетными и не подмешивают встроенные модели вне каталога.
Шаги настройки
Шаг 1 — подключите провайдера. На примере документации QCode (имя провайдера выбираете сами, в документации это crs; имя переменной окружения тоже произвольное, в документации CRS_OAI_KEY): в ~/.codex/config.toml пропишите model_provider = "crs", model = "gpt-6-sol", model_reasoning_effort = "high", preferred_auth_method = "apikey", затем добавьте таблицу [model_providers.crs] с name = "crs", base_url = "https://api.qcode.cc/openai", wire_api = "responses", requires_openai_auth = true, env_key = "CRS_OAI_KEY". Шаг 2 — подготовьте файл каталога: возьмите за образец codex-rs/models-manager/models.json из открытого кода Codex; верхний уровень — массив "models", у каждой записи есть поля slug, display_name, priority, visibility, context_window и другие. Оставьте только нужные записи, в slug укажите точный ID модели, например gpt-6.1-sol, gpt-6-sol или gpt-5.6-sol, и не придумывайте полей, которых нет в образце. Шаг 3 — добавьте model_catalog_json = "/absolute/path/to/models.json" на верхний уровень config.toml. Шаг 4 — чтобы менять каталог под задачу, запишите model_catalog_json на верхний уровень ~/.codex/profile-name.config.toml и запускайте codex --profile profile-name; в таблицу [profiles.profile-name] его не кладите. Шаг 5 — перезапустите Codex и введите /model в сессии, чтобы проверить список.
На QCode
Подключение Codex к QCode делается по странице Codex на docs.qcode.cc: base_url — https://api.qcode.cc/openai, wire_api — responses, ключ — API-ключ QCode, начинающийся с cr_; этот способ обслуживает только модели GPT, Claude и китайские модели через него не идут. В конфигурации Codex из документации QCode пункта model_catalog_json нет, и документированная конфигурация работает как есть. gpt-6.1-sol, gpt-6-sol и gpt-5.6-sol на QCode доступны для вызова, и все три ID есть и во встроенном каталоге (models.json) открытого кода Codex; чтобы сменить модель на один запуск, используйте codex -m gpt-6-sol. Оплата по токенам, цены каждой модели — на /models.
Частые вопросы
Что делает model_catalog_json?
Он указывает Codex на JSON-каталог моделей. Официальный справочник называет его путём к файлу каталога, загружаемому при запуске; комментарий в открытом коде Codex говорит, что заданный каталог заменяет встроенный для текущего процесса, поэтому варианты /model берутся из этого файла. Это необязательный ключ со строкой-путём в качестве значения.
Почему моя модель не видна в /model?
Чаще всего записи нет в каталоге или она оформлена не как видимая: по комментарию в открытом коде Codex варианты /model сортируются по priority и фильтруются по способу аутентификации и visibility, а во встроенном каталоге открытого кода Codex есть записи с visibility "hide". Вторая частая причина — файл изменили, но Codex не перезапустили, а ключ действует только при запуске. Если вы используете провайдера с model_catalog_url, начиная с 0.160.0 встроенные модели вне его каталога тоже больше не подмешиваются.
Какой формат у файла каталога?
Верхний уровень — массив "models": открытый код Codex при чтении файла проверяет именно список models, и встроенный models.json устроен так же. В массиве должна быть хотя бы одна запись, иначе при запуске будет ошибка model_catalog_json path ... must contain at least one model; при неверном JSON — failed to parse model_catalog_json path ... as JSON. Таблицы полей в документации нет, поэтому надёжнее скопировать запись из встроенного файла и поменять slug, display_name и priority.
Если ключ задан и в профиле, и в config.toml, что важнее?
Профиль. В официальной расширенной конфигурации сказано, что файлы профилей тоже могут переопределять model_catalog_json и при значении в обоих файлах Codex берёт значение профиля. Пишите его на верхний уровень ~/.codex/profile-name.config.toml; начиная с 0.134.0 --profile не читает таблицу [profiles.profile-name] в config.toml.
Что изменилось в каталогах моделей в 0.160.0?
Явные каталоги моделей провайдеров стали авторитетными: по заметкам от 2026-10-01 они больше не подмешивают неподдерживаемые встроенные модели и не используют устаревшие записи после неудачного обновления. PR #49135 добавляет: slug в каталоге должны быть уникальными и непустыми, метаданные сопоставляются по точному ID модели; запуск без единой доступной модели даёт ошибку конфигурации, но явно заданная model по-прежнему допускается.
Нужен ли model_catalog_json для работы Codex с QCode?
Нет, он не обязателен. В конфигурации Codex из документации QCode такого пункта нет; с base_url https://api.qcode.cc/openai и wire_api = "responses", как в документации, можно вызывать gpt-6.1-sol, gpt-6-sol и gpt-5.6-sol, и все три ID есть во встроенном каталоге открытого кода Codex. Собственный каталог нужен, только если вы хотите, чтобы /model показывал лишь выбранные модели, или хотите поменять отображаемые имена и порядок.
Источники
Определение ключа, правила переопределения профилями и ограничения управляемых сред: справочник по конфигурации Codex, расширенная конфигурация, пример конфигурации и страница моделей OpenAI (developers.openai.com, загружено 2026-10-08). Изменения по версиям: официальный журнал изменений Codex и заметки GitHub Releases к 0.156.0, 0.160.0 и 0.161.0, загружено в тот же день. Формат каталога, правило замены, тексты ошибок и фильтрация /model: схема конфигурации, встроенный models.json и комментарии в коде ветки main открытого кода openai/codex, а также описания PR #46561 и #49135, загружено в тот же день. Подключение к QCode: страница Codex в документации QCode (обновлена 2026-09-30), загружено в тот же день.
Настройте Codex по документации и сразу работайте с GPT
Один ключ cr_ и base_url https://api.qcode.cc/openai — и в Codex можно переключаться между gpt-6.1-sol, gpt-6-sol и gpt-5.6-sol; оплата по токенам, цены каждой модели на /models.
Читайте также
Codex CLI со сторонним API: config.toml, base_url и ошибки
Как прописать config.toml, base_url и wire_api, и какие ошибки чаще всего возникают при подключении.
GPT-5.5 в Codex: уходит 14.10, в API остаётся
Когда GPT-5.5 уходит из Codex и как он остаётся доступным в API.
Codex 401 Unauthorized: вход, API-ключ и env_key
Разбор ошибки 401 Unauthorized: способ входа, API-ключ и env_key.
Синтаксис конфигурации и цитаты на этой странице сверены 2026-10-08 с официальной документацией OpenAI Codex, журналом изменений и открытым кодом Codex; изменения на стороне upstream возможны без предупреждения. Комментарии в коде и встроенный каталог меняются от версии к версии, ориентируйтесь на версию Codex на своей машине; доступность моделей — по /models.