codex - 💡(How to fix) Fix OpenRouter model catalog parsing fails on startup

Summary

@openai/codex / codex-cli v0.133.0 fails during startup when using an OpenRouter model provider profile. The failure happens before the prompt is handled, while codex_models_manager refreshes the available model catalog.

Environment

• OS: Linux 6.6.87.2-microsoft-standard-WSL2
• Node: v22.18.0 via nvm
• Package: @openai/codex 0.133.0
• CLI: codex-cli 0.133.0
• Repo: https://github.com/openai/codex
• Binary path: /home/alexa/.nvm/versions/node/v22.18.0/lib/node_modules/@openai/codex/node_modules/@openai/codex-linux-x64/vendor/x86_64-unknown-linux-musl/bin/codex
• OpenRouter configured as a custom model_provider in ~/.codex/config.toml

Reproduction

1. Configure OpenRouter in ~/.codex/config.toml:

   [model_providers.openrouter]
   name = "OpenRouter"
   base_url = "https://openrouter.ai/api/v1"
   env_key = "OPENROUTER_API_KEY"
   wire_api = "responses"
   
   [profiles.or-opus]
   model_provider = "openrouter"
   model = "anthropic/claude-opus-4.7"
   
   [profiles.or-sonnet]
   model_provider = "openrouter"
   model = "anthropic/claude-sonnet-4.6"
   
   [profiles.or-cheap]
   model_provider = "openrouter"
   model = "deepseek/deepseek-v4-pro"

2. Export a valid OpenRouter API key:

   export OPENROUTER_API_KEY=...

3. Run Codex with the OpenRouter profile:

   codex exec --profile or-cheap "Responda apenas: ok"

Expected

Codex should start normally, use the configured OpenRouter profile, send the prompt to deepseek/deepseek-v4-pro, and return the model response.

Actual

Codex fails during startup while refreshing the model catalog:

2026-05-23T23:59:02.585758Z ERROR codex_models_manager::manager:
  failed to refresh available models: stream disconnected before completion:
  failed to decode models response: missing field `models` at line 1 column 426380;
  body: {"data":[{"id":"qwen/qwen3.7-max","canonical_slug":"qwen/qwen3.7-max-20260520",...

The command does not reach the actual prompt execution path. OpenRouter via Codex is therefore unusable with this configuration.

Root cause hypothesis

This looks like a model catalog response shape mismatch.

The OpenRouter models endpoint returns a JSON payload shaped like:

{"data":[...]}

The error suggests codex_models_manager is trying to deserialize the response as a payload containing a top-level models field:

missing field `models` at line 1 column 426380

Because the OpenRouter catalog response is large, the failure is reported after reading more than 426 KB of JSON. The startup path appears to either require the wrong schema for OpenRouter's /models response, or to route the OpenRouter model refresh through a parser intended for another provider's catalog format.

Validation that OpenRouter API is OK

Calling OpenRouter directly with the same API key and target model works:

curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek/deepseek-v4-pro","messages":[{"role":"user","content":"Responda apenas: ok"}],"max_tokens":10}'

Observed response:

{
  "id": "gen-1779581673-4UydX3iYJz0VXDnxLTFv",
  "model": "deepseek/deepseek-v4-pro-20260423",
  "provider": "Novita"
}

This confirms the OpenRouter API key, account, model name, and provider routing are working outside Codex.

Workaround

• Call OpenRouter directly via curl or another OpenAI-compatible client.
• Use Codex with the default subscription/auth profile instead of the OpenRouter profile.
• If there is or will be a flag/config option to disable online model catalog refresh for custom providers, that would likely avoid this startup blocker.

Related

Searches attempted:

• gh issue list -R openai/codex --search "openrouter" --state all
• gh issue list -R openai/codex --search "models manager refresh" --state all
• gh issue list -R openai/codex --search "missing field models" --state all

The local gh calls failed with error connecting to api.github.com, so related issue discovery was completed via web search instead.

Possibly related OpenRouter/custom-provider issues:

• https://github.com/openai/codex/issues/18228 - OpenRouter fails with Codex CLI 0.121.0, but the reported failure is an invalid Responses API request/tool schema issue rather than model catalog parsing.
• https://github.com/openai/codex/issues/1471 - OpenRouter exec retries on provider/model errors; related to OpenRouter usage with codex exec, but not the same catalog parsing failure.
• https://github.com/openai/codex/issues/1963 - OpenRouter model messages not displayed; related to OpenRouter response handling, but not startup model refresh.
• https://github.com/openai/codex/issues/7275 - Tool call protocol validation errors with strict third-party OpenAI-compatible providers such as OpenRouter; related custom-provider compatibility issue.
• https://github.com/openai/codex/issues/21884 - Contains a codex_models_manager::manager refresh failure log, but for Windows child-process timeout rather than OpenRouter JSON schema parsing.

No exact duplicate for missing field models on the OpenRouter catalog response was found in the available search results.