codex - 💡(How to fix) Fix OSS mode: Custom models not loaded from models_cache.json at turn setup

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/lenny/.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_command
• web_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