Codex model_catalog_json Configuration Guide
As of 2026-10-08, model_catalog_json is an optional key in Codex's config.toml whose value is the path to a JSON model catalog, and Codex loads it only at startup; the Codex open-source code says in its source comments that, once set, it replaces the bundled model catalog for the current process, and the /model picker builds its choices from the active catalog. A profile file can override it, and when both files set it the profile wins. This page walks through the format, the override rules, the 0.160.0 change and the usual reasons a model is missing from /model, based on the official config reference, changelog and the Codex open-source code.
Updated 2026-10-08
Four key points
When it applies
Official config reference: a path to a JSON model catalog loaded on startup. The config schema in the Codex open-source code adds that per-thread config overrides are accepted but do not reapply it, so restart Codex after editing the file.
Relation to the bundled catalog
A source comment in the Codex open-source code says it replaces the bundled catalog for the current process; /model choices are built from the active catalog, sorted by priority and filtered by auth mode and visibility.
When both files set it
Official advanced config: profile files can also override model_catalog_json, and Codex uses the profile value when both files set it.
Explicit provider catalogs
Codex CLI 0.160.0, released 2026-10-01: explicit provider model catalogs no longer include unsupported bundled models or reuse stale entries after refresh failures.
What model_catalog_json does
As of 2026-10-08, model_catalog_json lets you hand Codex a model catalog of your own: the official config reference describes it as an "Optional path to a JSON model catalog loaded on startup," typed string (path), and the official sample config writes it as model_catalog_json = "/absolute/path/to/models.json", commented as a startup-only model catalog override. Source comments in the Codex open-source code go further: once set, this catalog replaces the bundled catalog for the current process, and the /model picker builds its choices from the active catalog. So if you want /model to list only the models you pick, or to change display names or order, this file is what you edit. Two limits apply: the config reference's compatibility table for local computer access with Work Cloud lists it as not supported as a managed cloud override, noting that a local model catalog does not carry over; and administrators can enforce the JSON model catalog Codex uses at startup through requirements.toml.
Version changes (0.156.0 to 0.161.0)
The full change list for Codex CLI 0.156.0 (2026-09-22) includes #46561, "Support explicit provider model catalog URLs"; the PR says it adds model_catalog_url to provider configuration and that API-key catalog discovery with a custom base_url requires an explicit catalog URL. The 0.160.0 release notes (2026-10-01) read: "Explicit provider model catalogs no longer include unsupported bundled models or reuse stale entries after refresh failures." PR #49135 explains that providers with model_catalog_url could previously advertise bundled models absent from their catalog; now catalog slugs must be unique and non-empty, metadata matches by exact model ID, and a startup with no available model reports a configuration error while an explicitly configured model is still allowed. In 0.161.0 (2026-10-07), GPT-6.1 Sol became the default model in the bundled and Amazon Bedrock catalogs.
Model catalog timeline
Codex CLI 0.156.0 ships; its full change list includes #46561, which adds model_catalog_url to provider configuration.
Codex CLI 0.160.0 ships: explicit provider model catalogs stop including unsupported bundled models and stop reusing stale entries after refresh failures.
Codex CLI 0.161.0 ships: GPT-6.1 Sol becomes the default model in the bundled and Amazon Bedrock catalogs; this page was checked against the official pages on 2026-10-08.
Confirmed vs not stated officially
Confirmed (verbatim in official docs or open-source code)
All of the following can be checked word for word in the official Codex docs, changelog or the Codex open-source code (config schema, source and PR notes): model_catalog_json is the path to a JSON model catalog loaded on startup; per-thread config overrides do not reapply it; once set, it replaces the bundled catalog for the current process; /model choices are sorted by priority and filtered by auth mode and visibility; a profile file can override it, and the profile value is used when both files set it; since 0.134.0, --profile no longer reads a [profiles.profile-name] table in config.toml; with Work Cloud it is not supported as a managed cloud override; a JSON parse failure and an empty catalog each produce their own startup error; since 0.160.0, explicit provider catalogs no longer include unsupported bundled models; since 0.161.0, GPT-6.1 Sol is the bundled catalog's default model.
Not stated officially, so no conclusion here
Three things are not documented, and this page does not fill them in: first, which entry fields are required and what values they accept, since the docs have no field table and the reference to follow is the models.json bundled in the Codex open-source code; second, how relative paths are resolved, since the config reference only says string (path), the sample config body uses an absolute path and a profile example shows ./models.json, so an absolute path is the safe choice; third, the 0.160.0 change to explicit provider catalogs names model_catalog_url in its PR, and whether a local model_catalog_json follows the same rules is not stated. Also, as of 2026-10-08, model_catalog_url can be found in the config schema and PR notes of the Codex open-source code; the config reference on developers.openai.com does not list it.
model_catalog_json vs model_catalog_url
model_catalog_json (local file)
Set at the top level of config.toml or a profile file; the value is a local JSON file path, read only at startup, and it replaces the bundled catalog once set. A fit for individuals and teams who want a fixed /model list, or different catalogs per profile. With Work Cloud it cannot be used as a managed cloud override.
model_catalog_url (per provider)
Set inside a provider's configuration; the config schema in the Codex open-source code describes it as an "Optional full URL for a Codex-native model catalog," and the PR notes say Codex fetches it with that provider's authentication. A fit when a gateway maintains its own catalog; since 0.160.0 such explicit catalogs are treated as authoritative and no longer mix in bundled models outside the catalog.
Setup steps
Step 1, connect the provider. Using the QCode docs as the example (the provider name is up to you, the docs use crs; the environment variable name is also up to you, the docs use CRS_OAI_KEY): in ~/.codex/config.toml write model_provider = "crs", model = "gpt-6-sol", model_reasoning_effort = "high", preferred_auth_method = "apikey", then add a [model_providers.crs] table with name = "crs", base_url = "https://api.qcode.cc/openai", wire_api = "responses", requires_openai_auth = true, env_key = "CRS_OAI_KEY". Step 2, prepare the catalog file: use codex-rs/models-manager/models.json from the Codex open-source code as the template; the top level is a "models" array and each entry has fields such as slug, display_name, priority, visibility and context_window. Keep only the entries you want, set slug to the exact model ID, for example gpt-6.1-sol, gpt-6-sol or gpt-5.6-sol, and do not invent fields the template does not have. Step 3, add model_catalog_json = "/absolute/path/to/models.json" at the top level of config.toml. Step 4, to switch catalogs per task, put model_catalog_json at the top level of ~/.codex/profile-name.config.toml and launch with codex --profile profile-name; do not put it in a [profiles.profile-name] table. Step 5, restart Codex and type /model in a session to check the list.
On QCode
Connecting Codex to QCode follows the Codex page on docs.qcode.cc: set base_url to https://api.qcode.cc/openai, wire_api to responses, and use your QCode API key, which starts with cr_; this setup serves GPT models only, and Claude and Chinese models do not go through it. The Codex config in the QCode docs has no model_catalog_json entry, and the documented config works as is. gpt-6.1-sol, gpt-6-sol and gpt-5.6-sol are callable on QCode, and all three IDs are also in the bundled catalog (models.json) in the Codex open-source code; to switch models for a single run, use codex -m gpt-6-sol. Billing is per token; see /models for each model's price.
Frequently asked questions
What does model_catalog_json do?
It points Codex at a JSON model catalog. The official config reference says it is the path to a catalog file loaded on startup; a source comment in the Codex open-source code says that, once set, it replaces the bundled catalog for the current process, so /model choices come from that file. It is an optional key whose value is a path string.
Why doesn't my custom model show up in /model?
Most often the entry is missing from the catalog or is not written as visible: a source comment in the Codex open-source code says /model choices are sorted by priority and filtered by auth mode and visibility, and the bundled catalog in the Codex open-source code itself has entries with visibility set to "hide". The next most common cause is not restarting after editing the file, since it applies only at startup. If you use a provider with model_catalog_url, since 0.160.0 bundled models outside its catalog are no longer mixed in either.
What format does the catalog file use?
The top level is a "models" array: when the Codex open-source code reads the file it checks that models list, and the bundled models.json uses the same structure. The array needs at least one entry, otherwise startup fails with model_catalog_json path ... must contain at least one model; invalid JSON fails with failed to parse model_catalog_json path ... as JSON. The docs have no field table, so the safe approach is to copy an entry from the bundled file and then change slug, display_name and priority.
If both a profile and config.toml set it, which one wins?
The profile. The official advanced config says profile files can also override model_catalog_json and that Codex uses the profile value when both files set it. Put it at the top level of ~/.codex/profile-name.config.toml; since 0.134.0, --profile no longer reads a [profiles.profile-name] table in config.toml.
What did 0.160.0 change about model catalogs?
Explicit provider model catalogs became authoritative: the 2026-10-01 release notes say they no longer include unsupported bundled models or reuse stale entries after refresh failures. PR #49135 adds that catalog slugs must be unique and non-empty and metadata matches by exact model ID; a startup with no available model reports a configuration error, while an explicitly configured model is still allowed.
Do I need model_catalog_json to use Codex with QCode?
No, it is not required. The Codex config in the QCode docs has no such entry; with base_url https://api.qcode.cc/openai and wire_api = "responses" as documented, you can call gpt-6.1-sol, gpt-6-sol and gpt-5.6-sol, and all three IDs are also in the bundled catalog in the Codex open-source code. You only need your own catalog if you want /model to list just the models you pick, or to change display names and order.
Sources
Key definition, profile override rules and managed limits: OpenAI's Codex config reference, advanced config, sample config and models page (developers.openai.com, crawled 2026-10-08). Version changes: the official Codex changelog and the GitHub Releases notes for 0.156.0, 0.160.0 and 0.161.0, crawled the same day. Catalog format, replacement rule, error messages and /model filtering: the config schema, the bundled models.json and source comments on the main branch of the openai/codex open-source code, plus the notes on PRs #46561 and #49135, crawled the same day. QCode setup: the Codex page in the QCode docs (updated 2026-09-30), crawled the same day.
Set up Codex as documented and use GPT models right away
One cr_ key and base_url https://api.qcode.cc/openai let you switch between gpt-6.1-sol, gpt-6-sol and gpt-5.6-sol in Codex; billed per token, with each model's price on /models.
Related reading
Codex CLI third-party API setup: config.toml, base_url, errors
How to write config.toml, base_url and wire_api, and the errors you commonly hit while connecting.
Enable GPT-5.5 in Codex: retires Oct 14, API stays
When GPT-5.5 retires in Codex, and how it remains available on the API side.
Codex 401 Unauthorized: fix login, API key and env_key
Troubleshooting 401 Unauthorized across sign-in method, API key and env_key.
The config syntax and quotes on this page were checked on 2026-10-08 against the official OpenAI Codex docs, changelog and the Codex open-source code; upstream changes may happen without notice. Source comments and the bundled catalog change between versions, so go by the Codex version on your machine; model availability is whatever /models shows.