I wanted more models to choose from inside Codex. I didn't want another AI agent interface, or a config file stuffed with provider keys. Codex Router turned out to be a local bridge that avoids both.
I set this up on macOS with Codex Router 0.5.1. It also works with the Codex CLI on Linux. It's a community project, not something made or endorsed by OpenAI.
What the router does
Codex can already talk to custom model providers through the user-level ~/.codex/config.toml. The official Codex configuration reference covers model_provider, custom base_url values and model_catalog_json. Those settings go in your user config, not in a project's .codex/config.toml.
Codex Router does that wiring for you. A local background service builds a catalog from the providers you turn on and sends each Codex Responses request to whichever model you picked. If Codex is still signed in to OpenAI, the native GPT models stay in the same picker.
The clever part is tools. External models have to understand the Codex app's tools, so the router passes along the native tool definitions with flattened names like codex_app__ and mcp__. When the model calls one, the router puts the original namespace back. Codex still runs the tool itself. The router only translates and routes.
Install with Homebrew
You'll need the Codex App or CLI and a working Homebrew. The formula installs the router and its CLI. The Electron Control Center, the menu bar app and the desktop widget aren't included.
Add the tap and install:
brew tap duolahypercho/codex-router https://github.com/duolahypercho/codex-router
brew install codex-router
Then run the guided setup:
codex-router setup --guided
It asks which providers you want, looks for existing logins it can reuse, and privately prompts for any credentials that are still missing. Then it installs a background service for your user and hooks it up to Codex. Input is hidden while you type credentials. Provider keys shouldn't end up in command arguments, tracked files or chat messages.
I'd start with a single provider. It's much easier to confirm one route works before the picker fills up with models. Providers differ: some use API keys, some OAuth, some a subscription or a local endpoint, and each bills separately.
The guided setup won't send a paid test request unless you opt into the smoke test.
Check the install
I look at the service first:
codex-router status
Then run the full diagnostic:
codex-router doctor
doctor looks at the Codex config, the background service, provider credentials, the generated catalog, the routed model definitions and the managed skill pack. Warnings about providers you never set up are usually just informational. Failures that involve the provider you actually plan to use, the service or the catalog are the ones to fix.
Listing providers is safe too, since it never prints credentials:
codex-router providers
Once those pass, quit Codex completely and reopen it. Start a new task and the routed models should be in the picker. Codex only reads the external catalog at startup, so closing and reopening a single window might not be enough.
In the CLI you can pick a routed model directly:
codex -m PROVIDER/MODEL
Use the exact ID the router shows. The provider prefix matters, because the same model family might be available through several subscriptions or APIs.
Add or refresh models
Some providers publish a live catalog. To see what one offers right now:
codex-router discover-models PROVIDER
Then choose which ones show up in Codex:
codex-router curate-models PROVIDER
Restart Codex after changing the catalog. I don't add model IDs by guessing, even when the upstream API would accept them. Codex also needs correct metadata for context length, reasoning controls, input types, search and tool use.
For a live check, Codex Router has an explicit test:
codex-router test-model PROVIDER/MODEL --live --yes --quick
That sends a real request and may cost money. It needs both --live and --yes, so you can't kick off a billed test by accident.
Common problems
If no routed models show up, run codex-router providers and make sure the provider is enabled and signed in. Then run codex-router doctor and fully restart Codex so it picks up the regenerated catalog.
If the model answers but can't use app tools, check the managed skill pack in the doctor output. Installing a separate browser or computer-use driver won't fix this. Routed models are supposed to call the tool names Codex gives them, and the router handles the namespace conversion.
If the model shows up but its requests fail, double-check the exact provider and model pair. What's available can vary by API, subscription or region. I run discover-models first, and only send a small live test once I know how that provider bills.
Don't edit the router's signed local URL, and don't copy its internal credentials into some other config. If the managed Codex integration breaks, rerun the guided setup or use codex-router enable.
Update or remove it
To upgrade:
brew upgrade codex-router
To remove it, stop the per-user service and restore the managed Codex config first, then uninstall the formula:
codex-router uninstall
brew uninstall codex-router
Order matters. Homebrew owns the package, but Codex Router owns the per-user service and the Codex config it set up.