Codex setup guide
config.toml setup, env_key vs experimental_bearer_token, and model IDs per plan.
You configure a third-party gateway in config.toml and the Codex CLI runs your custom model right away, yet Codex Desktop displays only Custom and leaves your models out of the dropdown. Digging past the config file reveals the filter is in the Desktop UI.
After wiring ~/.codex/config.toml to a third-party gateway, you run codex -m claude-sonnet-5-5 in the terminal and everything works. Then you open Codex Desktop, look at the model bar, and see only Custom (or Custom High)—with none of your custom models anywhere in the dropdown.
The natural first guess is that Desktop did not read config.toml, or that something in the file is invalid. Checking it step by step shows two separate layers: a pair of local config traps that genuinely break loading, and a client-side UI filter that still hides the dropdown entries even when your config is spotless.
Seeing Custom in the Codex Desktop bar does not mean your config failed. As long as model sits at the top of config.toml, Desktop still routes requests to that exact model ID even when the dropdown hides it.
Before blaming the Desktop app, two easy mistakes can make it look like config.toml is being ignored:
model and model_provider below a [table] headerIn TOML, keys belong to the top-level root only if they appear before the first [model_providers.xxx] header. If you paste model = "claude-sonnet-5-5" at the bottom of the file, it falls inside [model_providers.codingpass] instead of setting the global default, and Desktop will not pick it up.
Codex Desktop reads config.toml once at launch. Closing the window on macOS leaves the background process running, so reopening the window keeps the old settings. You need a full quit (Cmd + Q on macOS, or exiting from the system tray on Windows) after every edit.
Custom?After moving the top-level keys above [model_providers.codingpass] and doing a full Cmd + Q restart, sending a test prompt reveals something telling: the request actually succeeds and reaches claude-sonnet-5-5, even though the badge in the UI still reads Custom.
Meanwhile, the codex CLI reading the exact same config.toml shows and switches models without trouble. Looking at how Desktop is built explains the split: the underlying app-server does load your config.toml and model_catalog_json via model/list, but the Electron renderer wrapping it applies its own UI gate:
use_hidden_models, available_models, default_model) and strips any model outside the allowed list (tracked in openai/codex#19694).In short, routing works—the Desktop UI is just hiding non-catalog models behind a Custom or Custom High label.
Once you know the backend is routing correctly, stop fighting config.toml formatting and pick the workaround that matches how often you switch models:
| Approach | When to use | Trade-off |
|---|---|---|
Hardcode model in config.toml | You mostly stick to one custom model in Desktop | UI shows Custom; switching requires editing the file + Cmd + Q |
| Keep a ChatGPT session logged in | You want to lift the API-key-only UI gate | Requires signing in with an OpenAI account (Free/Go tier is enough) |
Use codex CLI (-m / --profile) | You switch models or providers frequently | Terminal TUI instead of Desktop GUI |
Community app.asar patchers | You want custom entries inside the Desktop dropdown | Unofficial; overwritten on every Codex Desktop update |
model at the top and ignore CustomIf you mostly stay on one model in Desktop—such as claude-sonnet-5-5 or gpt-6-2-sol via CodingPass—keep model_provider and model at the very top of ~/.codex/config.toml above any [table]:
model_provider = "codingpass"model = "claude-sonnet-5-5" [model_providers.codingpass]name = "CodingPass"base_url = "https://codingpass.ai/v1"env_key = "CODINGPASS_API_KEY"wire_api = "responses"Quit completely (Cmd + Q) and reopen. Ignore the Custom badge and send prompts as usual.
To lift the API-key-only restriction, keep a standard ChatGPT account signed in inside the app alongside your custom config.toml provider. The active session satisfies the UI check while your requests still route through the provider in config.toml.
-m or --profileThe codex CLI has no Desktop renderer filter. Since Codex 0.134.0, profiles live in separate files, so you can keep your main config on official OpenAI and put CodingPass in ~/.codex/cp.config.toml:
codex --profile cp -m claude-sonnet-5-5app.asar patches (last resort)Because the filter lives inside the local Electron app.asar bundle, community tools such as CodexUse toggle use_hidden_models so custom models appear in the dropdown. Every Codex Desktop update overwrites app.asar, making this fragile for daily use.
For full config.toml examples, environment variables, and available models per tier, see the Codex setup guide and how allowances and caps work.
Use CodingPass inside Codex CLI and Desktop with one config.toml. Point base_url to codingpass.ai/v1 for pay-as-you-go access to Claude, GPT, and open models.