Codex Router
English · 简体中文 · 日本語
Use external models in Codex and other coding clients through one local router.
Store provider credentials locally, share one installation across
clients, and keep native GPT access when you have a valid ChatGPT login.
Install · First use · Providers ·
Commands · Documentation
What it supports
| Client | Integration |
|---|
| Codex App and CLI | Native and external models in the model picker; Linux support covers the CLI |
| DeepSeek Harness | Managed provider routes in its settings |
| Gemini CLI | Managed endpoint, key, and default-model environment block |
| Cursor Agent / Cursor App | Local Agent launcher / separately keyed public HTTPS edge for App BYOK |
| Claude Code | Separate claude-router launcher using the local Messages adapter |
| OpenClaw | Managed Responses provider |
| opencode, pi, omp, Command Code, Hermes Agent | Provider configuration published into the existing client |
The Control Center manages connections, model visibility, usage, and service
health. macOS uses a native menu-bar host with an embedded Electron window;
Windows and Linux use an Electron window and tray.
Image, search, and subagent capabilities depend on the selected model route.
Some features use additional provider requests and quota. See the Codex guide and
client guide for limitations.
Install
Requirements
- Codex App or CLI for the default Codex setup; install another supported client
when using its integration.
- Node.js 22.19+; a maintained Node.js 24 LTS release is recommended.
- Git for managed checkout installation, updates, and rollback.
uv or Python 3.10+ with venv for the default compatibility-enabled source
installation. An explicit compatibility-layer opt-out
skips Python installation and probes. Source dependency setup follows the
stored compatibility policy. Homebrew installs the formula's Python dependencies.- On Windows, PowerShell must run in
FullLanguage mode and policy must allow
Add-Type.
- To build the macOS desktop companion locally, the full Xcode app is required.
Choose one installation method. Setup asks which providers to enable and uses
private local prompts for credentials. Live inference tests run only when
explicitly requested and consume the selected provider's quota.
Guided source installation
macOS / Linux — Terminal
curl -fsSL https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.sh \
| sh -s -- --target codex --guided --with-tray
Windows — PowerShell
$installer = Join-Path $env:TEMP "codex-router-install.ps1"
Invoke-WebRequest https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.ps1 -OutFile $installer
powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer -Target codex -Guided -WithTray
These commands install the router service and desktop companion. Use --no-tray
(macOS/Linux) or -NoTray (Windows), in place of the tray flag, for the router
without the companion. On macOS, a missing full Xcode installation skips the
companion with guidance rather than failing the installed router.
To inspect the installer first, clone the repository and run the local
installer. See installation, proxy configuration, and migration.
Homebrew — router and CLI only
brew tap duolahypercho/codex-router https://github.com/duolahypercho/codex-router
brew install codex-router
codex-router setup --guided
Homebrew provides the router and CLI; use the source installer for the desktop
companion. Use codex-router <command> for the Codex maintenance commands below, and
brew upgrade codex-router for updates. See the
Homebrew instructions for command
equivalents and removal.
First use
- Finish provider setup. Some providers require you to select models from their
live catalog before any appear.
- Run the doctor from the installed checkout and resolve any
FAIL:
./bin/model-router codex doctor on macOS/Linux, or
.\model-router.ps1 codex doctor on Windows.
- Fully quit and reopen Codex, create a new task, and choose the intended model.
Codex reads the router's model catalog at startup.
- Open Codex Router for the Control Center. Closing its window normally
leaves the tray running; use its tray/menu-bar entry to reopen it.
If a model is missing, check provider selection, authentication, and model
visibility before reinstalling. See
missing models.
A native GPT model additionally requires a usable ChatGPT login.
For agent-assisted installation, give your agent the repository link and ask
it to follow AGENTS.md, preserve existing settings and login,
use only your chosen providers, run the doctor, and leave the final Codex
restart to you.
Providers and models
Built-in integrations include Anthropic, Kimi, DeepSeek, xAI, Z.ai, Qwen,
MiniMax, Meta, OpenRouter, GitHub Copilot, and others. Available models depend
on the provider, region, account entitlement, and your local selection.
For example, from a source checkout on macOS/Linux:
./bin/model-router codex provider-key deepseek set
./bin/model-router codex providers enable deepseek
./bin/model-router codex providers
On Windows, replace ./bin/model-router codex with
.\model-router.ps1 codex. For catalog-only providers, select models with
./bin/curate-models PROVIDER on macOS/Linux or
.\codex-router.ps1 curate-models PROVIDER on Windows.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
