Codex Router Models Missing? Fix the Model Picker

The most common “it does not work” report is external models not appearing in the Codex model picker. In almost every case the cause is one of three things: the provider is not enabled, its credential is missing, or Codex has not been fully restarted. This page walks through the exact sequence to fix it.

Why the catalog is credential-aware

Codex Router only includes models from enabled external providers that have a stored API key or valid OAuth session. Native GPT models are included only when codex login status confirms an OpenAI login. So a model can be “installed” in the registry and still absent from your picker until its provider is enabled and authenticated.

Step 1: check provider status

./bin/model-router codex providers

The intended provider must report both SHOW and ready:

• SHOW means the provider is visible in the catalog.
• ready means the credential or OAuth session exists.

If the provider is not SHOW, enable it:

./bin/model-router codex providers enable deepseek

If it is SHOW but not ready, set the key or sign in. See the model guides for the right command per provider.

Step 2: refresh the catalog

./bin/model-router codex refresh-catalog
./bin/model-router codex doctor

refresh-catalog regenerates the merged catalog from the current registry, enabled providers and stored credentials.

Step 3: fully restart Codex

Codex loads model_catalog_json only at app startup. Closing a window does not reload it.

1. Fully quit Codex — on macOS use Command-Q; on Windows use the app’s Quit command or end it from the tray if present.
2. Reopen Codex.
3. Create a new task.
4. Open the normal model picker.

If the models are still missing, run refresh-catalog again, fully quit, and reopen.

Step 4: inspect the startup catalog

codex debug models

This shows the catalog Codex actually loaded at startup. If the routed models are present here but absent from the picker, the app may have been suspended rather than quit — fully quit and reopen. If they are absent here, the catalog capture or provider selection is at fault; re-check steps 1–2.

Routed model agents are missing

Pulling main updates only the source checkout. Apply that revision to the per-user installation and verify the generated custom agents:

./bin/model-router codex update
./bin/model-router codex doctor

The doctor should report OK for Routed model agents. If not:

./bin/model-router codex doctor --fix

Then fully quit Codex, reopen it, and create a new task. Generated personal agent definitions live under $CODEX_HOME/agents/ (normally ~/.codex/agents/).

Still missing? Verify the managed config

The config root should contain exactly one codex-router-managed block with the loopback base URL on port 4102, a generated /_codex-router/.../v1 path, and a catalog under $CODEX_HOME/codex-router/merged-models.json. Use ./bin/status — which redacts the generated path — when sharing diagnostics, and never paste the complete managed URL into an issue.

When all else fails

Run doctor --fix, create a support bundle, and open an issue on the repository with the redacted output. See the troubleshooting overview and the doctor guide for the full diagnostic flow.