OSS mode: Custom models not loaded from models_cache.json at turn setup
Workaround guide: https://gist.github.com/LAP87/045cde0227512408d268c67cb49123be
Summary
When running Codex in --oss mode with custom models (e.g. via Ollama), get_model_info() fails
to find the model and displays: "Model metadata for X not found. Defaulting to fallback
metadata; this can degrade performance and cause issues."
Root cause
OpenAiModelsManager initializes remote_models from the bundled models.json (6 OpenAI models
only). The user's models_cache.json (populated by a script that syncs Ollama models into
Codex's model cache) is never read automatically — get_model_info() reads remote_models
directly without triggering a cache load.
The cache is only consulted when list_models() is called via refresh_available_models(), which
happens asynchronously in the TUI model picker, not at turn setup.
Workaround (user-side)
The only way to make custom models immediately available is setting model_catalog_json in
~/.codex/config.toml:
model_catalog_json = "/home/user/.codex/model_catalog.json"
This forces StaticModelsManager, which loads all models at startup. The catalog file should
contain a {"models": [...]} array with model entries matching the protocol schema.
Request
It would be better if --oss mode automatically loaded models_cache.json into the model
catalog at startup, so users don't need model_catalog_json + a separate file + enum-value
massaging just to use their Ollama models without warnings.
Metadata enum gotcha (bonus)
Even with model_catalog_json, the JSON must use protocol-compliant values:
visibility: list / hide / none (not custom)apply_patch_tool_type: freeform (not unified)shell_type: default / local / unified_exec / disabled / shell_commandweb_search_tool_type: text / text_and_image
Otherwise Codex rejects the catalog at parse time with "unknown variant" errors.
Environment
- Codex v0.134.0
- Ollama as local provider
OSS mode: Custom models not loaded from models_cache.json at turn setup
Workaround guide: https://gist.github.com/LAP87/045cde0227512408d268c67cb49123be
Summary
When running Codex in
--ossmode with custom models (e.g. via Ollama),get_model_info()failsto find the model and displays: "Model metadata for
Xnot found. Defaulting to fallbackmetadata; this can degrade performance and cause issues."
Root cause
OpenAiModelsManagerinitializesremote_modelsfrom the bundledmodels.json(6 OpenAI modelsonly). The user's
models_cache.json(populated by a script that syncs Ollama models intoCodex's model cache) is never read automatically —
get_model_info()readsremote_modelsdirectly without triggering a cache load.
The cache is only consulted when
list_models()is called viarefresh_available_models(), whichhappens asynchronously in the TUI model picker, not at turn setup.
Workaround (user-side)
The only way to make custom models immediately available is setting
model_catalog_jsonin~/.codex/config.toml:This forces
StaticModelsManager, which loads all models at startup. The catalog file shouldcontain a
{"models": [...]}array with model entries matching the protocol schema.Request
It would be better if
--ossmode automatically loadedmodels_cache.jsoninto the modelcatalog at startup, so users don't need
model_catalog_json+ a separate file + enum-valuemassaging just to use their Ollama models without warnings.
Metadata enum gotcha (bonus)
Even with
model_catalog_json, the JSON must use protocol-compliant values:visibility:list/hide/none(notcustom)apply_patch_tool_type:freeform(notunified)shell_type:default/local/unified_exec/disabled/shell_commandweb_search_tool_type:text/text_and_imageOtherwise Codex rejects the catalog at parse time with "unknown variant" errors.
Environment