Codex Desktop Hides Your Custom Models

Most people are one config line away from a fix. Match what you see to the table, then act.

The single fastest check: open a terminal in the same folder, run codex (the CLI), then type /model. If the CLI lists your model but Desktop does not, you have the client-side filter bug — and no amount of config editing on the Desktop side will surface it. Skip to Fix 1.

This is the decision that saves you an afternoon of editing the wrong layer.

They need different fixes. Picking the wrong one is why people spend an afternoon re-typing a working config.

The first one surprises people. Per the open codex issue #19694, the app-server loads the catalog correctly and returns your models through its model/list endpoint — but the Desktop UI applies an extra filter and drops locally configured models before rendering the picker. The backend knows about your model. The frontend refuses to show it. That is a client bug, not a config error, and it was filed on 2026-04-26 and is still open at time of writing.

The second cause is the most common and the least alarming. If you only wrote model = "some-id" with no catalog, Codex has the string but no display name, no context window, no capability flags. The picker shows the label "Custom" and moves on. Your requests still go to the right model. This trips people up because "Custom" looks broken when it is actually working.

Codex builds its model list in layers, and the order tells you which fix will actually land.

Three sources feed the list: a catalog bundled with the binary, a remote catalog fetched from OpenAI, and your local model_catalog_json. The local file wins — it overrides both the bundled and the remote catalog on startup, which is why a correct model_catalog_json is the real lever for third-party models rather than a nice-to-have.

Here is the part that trips everyone. When Codex starts, the app-server reads all three layers, resolves them, and exposes the result through an internal model/list endpoint. The CLI renders that list directly, so custom models show up. The Desktop app renders the same list through an extra client step that, per issue #19694, applies its own allowlist and drops locally configured entries before they reach the dropdown. Same backend, same catalog, two different pickers. That single divergence is why the CLI is a dependable escape hatch and Desktop is not.

There is also a cache to watch. Codex keeps ~/.codex/models_cache.json, and after you switch providers or edit a catalog it does not always resync. A stale cache can keep showing an old list — or an empty one — even after your config is correct. Deleting that file forces a clean rebuild on the next launch, which is worth trying before you assume the catalog itself is wrong.

Work top to bottom. Fix 1 always works. The later fixes make the picker pretty and the list switchable.

THE RELIABLE WORKAROUND

# ~/.codex/config.toml   (user-level, not a project folder)
model = "your-provider/your-model-id"
model_provider = "my-gateway"

[model_providers.my-gateway]
name = "my-gateway"
base_url = "https://your-gateway.example/v1"
env_key = "MY_GATEWAY_API_KEY"
wire_api = "responses"

MAKE THE PICKER LIST IT

# top of ~/.codex/config.toml
model_catalog_json = "/Users/you/.codex/my-models.json"
model = "your-provider/your-model-id"
model_provider = "my-gateway"

{
  "models": [
    {
      "slug": "your-provider/your-model-id",
      "display_name": "Your Model (gateway)",
      "description": "Coding model via the gateway",
      "context_window": 262000,
      "max_context_window": 262000,
      "supported_in_api": true,
      "visibility": "list",
      "priority": 1
    }
  ]
}

FIX THE CONFIG LAYER

# check where your provider actually lives
grep -rn "model_providers" ~/.codex/config.toml ./.codex/config.toml 2>/dev/null
# if it is in ./.codex/config.toml, move the [model_providers.*] block
# and model_provider = "..." into ~/.codex/config.toml, then restart

FIX THE TOOLING LAYER

# confirm the catalog exists and lists your models after re-saving
cat ~/.codex/cc-switch-model-catalog.json | grep -o '"slug":[^,]*'
# if this is empty, re-save the provider in cc-switch and check again

Half the "custom models not showing" reports are a broken route wearing a display costume. Each one produces a symptom that looks like the picker hiding your model, when the request never had a chance to land.

The tell that separates these from the real #19694 filter is one command: run the same request from the CLI. If the CLI also fails, it is one of the errors above, not the Desktop picker, and no catalog edit will fix it. If the CLI succeeds and only Desktop stays blind, then it is the filter — and you are back to Fix 1 and Fix 4.

This is not one bug. It is a cluster of related issues in the Codex app and in the tools that write its config. Knowing which one you have saves you from applying the wrong fix.

The pattern across all of these: the routing works, the display does not. The CLI has been the reliable escape hatch every time, because it reads the catalog without the Desktop renderer's extra filtering. If you are blocked in Desktop, the CLI (codex in your terminal) will almost always show and use the model.

If you are done fighting the Desktop UI, here are ways to keep using custom models without waiting on a client fix.

The point of a gateway here is one endpoint and one key across many models, so switching a model is a one-string edit rather than a new provider block each time. Whichever path you take, the Desktop picker quirk is a display layer on top, not a routing constraint.

Do not trust the picker as your source of truth — that is the thing that is broken. Verify at the layer below it.

codex --version                 # confirm you are on a recent build
codex                           # start the CLI, then type /model
# the CLI enumerates the catalog without the Desktop filter

If /model in the CLI shows your model, the catalog and provider are correct and any remaining gap is the Desktop renderer. If the CLI also comes up empty, the problem is upstream: wrong file (Fix 3), malformed catalog (Fix 2 / Fix 4), or a bad slug. For a raw sanity check that the route itself resolves, one curl against the gateway with your key tells you whether the model exists before you blame the client at all. Routing first, display second.

The fixes above get your picker back. The rest is the part worth acting on before the next bug.

You can read this bug two ways. The narrow way: a Desktop client filters out your models, set them inline, move on. The useful way: a tool you treated as part of your workflow silently dropped functionality at the rendering layer, and the only signal was that the dropdown looked empty.

We see this in nearly every AI system we audit. A team builds on one client, one UI, one default model, and a bug, a deprecation, or a quiet filter turns a working setup into a half-day of guessing. The Codex picker bug is just the most recent, most specific version of it.

Three things make a setup survive these changes:

If your workflow collapses when one client hides a model, the workflow failed the design test — not the client.

About FACTA

FACTA helps startups and growth-stage teams turn AI into production systems that keep running — not demos that impress once.

We design the architecture around the parts that actually break under real usage: model abstraction, credentials you own, failover, cost controls, observability. The boring infrastructure that keeps a system alive after launch.

Led by Matías Baglieri and Carolina Fogliato, we focus on one thing:

AI leadership that builds. Not just advises.