duolahypercho/codex-router

Codex Router

Install everything (recommended)

This is the default setup: guided provider setup + Electron Control Center + tray/menu-bar app + macOS desktop widget.

macOS or Linux

Copy and paste this into Terminal:

curl -fsSL https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.sh \
  | sh -s -- --target codex --guided --with-tray

Windows

Copy and paste this into 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

That is the complete installation. It asks which providers you want and keeps credential entry in private local prompts.

When it finishes:

1. Fully quit and reopen Codex. 2. Start a new task and choose a routed model. 3. Open Codex Router to use the Control Center.

On macOS, open Codex Router from Spotlight or ~/Applications; its icon stays in the menu bar when the Control Center is closed. The desktop widget is already included: choose Settings → Dynamic Island → Desktop from the menu-bar app to show it. It is a movable Codex Router panel rather than an item in macOS's Edit Widgets gallery.

macOS does not have a public .dmg yet; the command above builds and installs the app locally. That build requires the full Xcode app, not only the standalone Command Line Tools, because it contains SwiftUI macro and WidgetKit targets. The installer honors DEVELOPER_DIR or the Xcode selected under Xcode → Settings → Locations → Command Line Tools. If that selection still points at the standalone tools, it uses /Applications/Xcode.app or /Applications/Xcode-beta.app for this build only without changing the global selection. For an Xcode app in another location, retry the companion with:

env DEVELOPER_DIR="/path/to/Xcode.app/Contents/Developer" \
  ~/.local/share/codex-router/bin/model-router-tray

What Codex Router does

Use Anthropic, Kimi, DeepSeek, xAI, GitHub Copilot, and other external models inside the Codex App and CLI. One local installation can also serve DeepSeek Harness and Gemini CLI, plus Cursor Agent and Cursor App, Claude Code, and OpenClaw. Your provider credentials stay on your computer.

Subscription agent bridges (experimental)

The Harness page also detects three optional, client-owned agent sessions: Claude Code, Cursor Agent, and Gemini CLI. These are deliberately separate from the codex_router/... model catalog:

• Claude runs through the installed official claude process and its existing

Claude.ai login. A successful claude auth status proves login only; the account must separately be entitled to use non-interactive/SDK turns. The bridge reports Anthropic's refusal verbatim when it is not.

• Cursor Agent runs through its official ACP stdio server (agent acp).
• Gemini CLI runs through its official ACP stdio server (gemini --acp).

The router never reads or copies those clients' OAuth tokens. It stores only bounded metadata for sessions created through the bridge: client, session ID, workspace path, and timestamps. Prompts and transcripts stay out of the bridge index. File-system and terminal capabilities are not advertised yet, and permission requests are rejected by default until the Control Center has a foreground approval surface.

This is not an OpenAI-compatible subscription proxy. In particular, it does not implement CLIProxyAPI's token-to-model-endpoint behavior and does not add fake Claude, Cursor, or Gemini subscription models to another client's picker.

Inspect the optional bridges without spending a model request:

./bin/model-router codex agents status
./bin/model-router codex agents probe anthropic
./bin/model-router codex agents probe cursor
./bin/model-router codex agents probe gemini

Run a prompt only when you intend to spend the owning client's quota. Prompt text is read from stdin so it is absent from the process list:

printf '%s' 'Explain this repository.' |
  ./bin/model-router codex agents prompt anthropic --cwd "$PWD"

The ACP integrations follow the official Cursor ACP and Gemini CLI ACP contracts. Direct reuse of Gemini CLI OAuth tokens in third-party software is not implemented; Google's published Gemini CLI terms explicitly prohibit that access pattern.

Codex Router is an independent community project. It is not affiliated with or endorsed by OpenAI, GitHub, Anthropic, Moonshot AI, DeepSeek, OpenRouter, opencode, Google, or the referenced opencodex project.

Give the link to your agent

Paste this into a Codex task:

Install the router from this public repository:
https://github.com/duolahypercho/codex-router
Follow AGENTS.md. Preserve my existing Codex models, profiles, settings, and
ChatGPT login. Use only the provider authentication I choose, safely migrate
only recognized older versions, run the Codex doctor, and leave the final app
restart to me. Never ask me to paste a token or API key into chat.

If compatible authentication already exists, an agent can finish everything except the final app restart. Provider credentials are entered only through a hidden local terminal prompt.

Other installation methods

Homebrew (macOS or Linux)

Codex Router is not in homebrew/core yet, so brew install codex-router by itself does not work. For now, add this repository as a tap once:

brew tap duolahypercho/codex-router https://github.com/duolahypercho/codex-router
brew install codex-router
codex-router setup --guided

The tap URL is needed only once. Homebrew installs the formula's Node.js, Python, and build dependencies; codex-router setup --guided performs the one-time provider selection, credential-safe authentication, background service installation, and Codex integration. When setup finishes, fully quit and reopen Codex, create a new task, and choose a routed model from the picker.

Homebrew is the router/CLI-only installation. It deliberately does not build or download the Electron Control Center, tray/menu-bar app, or macOS desktop widget during setup. If you want those, use the recommended installer at the top of this README instead.

Upgrade an existing Homebrew installation with:

brew upgrade codex-router

Homebrew command equivalents

A Homebrew install puts a single codex-router command on your PATH instead of this repository's bin/ directory. Wherever the rest of this README shows ./bin/model-router codex or ./bin/, run:

codex-router 

List everything the packaged build exposes with:

codex-router help

To add a custom provider's models — the packaged equivalent of ./bin/curate-models — run:

codex-router curate-models 

codex-router install is deliberately unavailable: a Homebrew install has no writable checkout to rewrite, and brew upgrade codex-router performs that step itself.

Before removing the formula, remove the per-user service and managed Codex configuration that Homebrew does not own:

codex-router uninstall
brew uninstall codex-router

The first Homebrew install can take considerably longer than the guided installer below because the formula builds the locked Python dependencies from source. The release workflow generates Formula/codex-router.rb from requirements/python.txt and refreshes it for each release.

Maintainers preparing the eventual homebrew/core submission should follow docs/HOMEBREW_CORE.md.

npm

This project does not publish an npm-installable CLI yet. Do not use npm install codex-router for this project. Use the recommended installer or Homebrew above; a future npm package should use the scoped name @duolahypercho/codex-router so it cannot be confused with existing packages.

Guided installer

macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/duolahypercho/codex-router/main/install.sh \
  | sh -s -- --target codex --guided

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

The setup selects providers, detects existing authentication, can run the official kimi login, prompts invisibly for provider credentials, installs a per-user background service, and verifies every local layer. It never makes a paid test request unless --smoke-test is explicitly selected.

To validate the install and uninstall lifecycle before trusting the router with any credential, pass --no-provider --no-discovery: the router installs idle, reads no credential from anywhere, and answers Codex traffic with a local error. See docs/INSTALL.md.

Requirements:

• The Codex App or CLI.
• Node.js 22.19 or newer; Node.js 24 LTS is recommended.
• uv, or Python 3.10+ with venv.
• Git for the managed one-command checkout and rollback.
• On Windows, Windows PowerShell must run in FullLanguage mode and local

application-control policy must permit Add-Type. The router checks this before starting a mutation child; it does not weaken or bypass that policy.

Linux installations support the Codex CLI.

Models and authentication

| Picker label | Model ID | Authentication | | --- | --- | --- | | K2.7 Coding Highspeed (OAuth) | kimi-oauth/kimi-for-coding-highspeed | Existing Kimi Code CLI OAuth session | | K2.7 Coding (OAuth) | kimi-oauth/kimi-for-coding | Existing Kimi Code CLI OAuth session | | Kimi K3 (OAuth) | kimi-oauth/k3 | Existing Kimi Code CLI OAuth session | | Kimi K3 (API) | kimi-api/kimi-k3 | Separately billed Kimi Platform API key | | Kimi K3 (China API) | kimi-api-cn/kimi-k3 | Separately billed Moonshot China platform key | | DeepSeek V4 Flash (API) | deepseek/deepseek-v4-flash | DeepSeek API key | | DeepSeek V4 Pro (API) | deepseek/deepseek-v4-pro | DeepSeek API key | | DeepSeek V4.1 Flash (API) | deepseek/deepseek-v4.1-flash | DeepSeek API key | | Grok 4.5 (OAuth) | grok-oauth/grok-4.5 | Official Grok CLI OAuth session | | Grok 4.5 (API) | grok-api/grok-4.5 | Separately billed xAI API key | | Claude Opus 4.8 (API) | anthropic-api/claude-opus-4.8 | Separately billed Anthropic API key | | GLM-5.2 (Ollama Cloud) | ollama-cloud/glm-5.2 | Ollama Cloud API key | | GLM-5.3 (Ollama Cloud) | ollama-cloud/glm-5.3 | Ollama Cloud API key | | GLM-5.3-Flash (Ollama Cloud) | ollama-cloud/glm-5.3-flash | Ollama Cloud API key | | Kimi K2.7 Code (Ollama Cloud) | ollama-cloud/kimi-k2.7-code | Ollama Cloud API key | | Kimi K3 (Ollama Cloud) | ollama-cloud/kimi-k3 | Ollama Cloud API key | | MiniMax M3 (Ollama Cloud) | ollama-cloud/minimax-m3 | Ollama Cloud API key | | DeepSeek V4 Pro (Ollama Cloud) | ollama-cloud/deepseek-v4-pro | Ollama Cloud API key | | DeepSeek V4 Flash (Ollama Cloud) | ollama-cloud/deepseek-v4-flash | Ollama Cloud API key | | MiniMax M3 | minimax-token-plan/minimax-m3 | MiniMax Token Plan API key | | MiMo-V2.5 (Xiaomi API) | xiaomi-mimo/mimo-v2.5 | Xiaomi MiMo API key | | MiMo-V2.5-Pro (Xiaomi API) | xiaomi-mimo/mimo-v2.5-pro | Xiaomi MiMo API key | | Qwen3.8 Max (Plan) | qwen-plan/qwen3.8-max | Alibaba Model Studio plan API key | | Qwen3.8 Max Preview (Plan) | qwen-plan/qwen3.8-max-preview | Alibaba Model Studio plan API key | | Qwen3.7 Max (Plan) | qwen-plan/qwen3.7-max | Alibaba Model Studio plan API key | | Qwen3.7 Plus (Plan) | qwen-plan/qwen3.7-plus | Alibaba Model Studio plan API key | | Qwen3.6 Flash (Plan) | qwen-plan/qwen3.6-flash | Alibaba Model Studio plan API key | | DeepSeek V4 Pro (Qwen Plan) | qwen-plan/deepseek-v4-pro | Alibaba Model Studio plan API key | | DeepSeek V4 Flash (Qwen Plan) | qwen-plan/deepseek-v4-flash-0731 | Alibaba Model Studio plan API key | | GLM-5.2 (Qwen Plan) | qwen-plan/glm-5.2 | Alibaba Model Studio plan API key | | GLM-5.3-Flash (Coding Plan) | zai-coding/glm-5.3-flash | Z.ai GLM Coding Plan API key | | GLM-5.3 (Coding Plan) | zai-coding/glm-5.3 | Z.ai GLM Coding Plan API key | | GLM-5.2 (Coding Plan) | zai-coding/glm-5.2 | Z.ai GLM Coding Plan API key | | GLM-5-Turbo (Coding Plan) | zai-coding/glm-5-turbo | Z.ai GLM Coding Plan API key | | GLM-5.3-Flash (Z.ai API) | zai-api/glm-5.3-flash | Separately billed Z.ai platform API key | | GLM-5.3 (Z.ai API) | zai-api/glm-5.3 | Separately billed Z.ai platform API key | | GLM-5.2 (Z.ai API) | zai-api/glm-5.2 | Separately billed Z.ai platform API key | | GLM-4.7 (Z.ai API) | zai-api/glm-4.7 | Separately billed Z.ai platform API key | | Muse Spark 1.2 (Meta) | meta/muse-spark-1.2 | Meta Model API key | | Muse Spark 1.2 Contributor (Meta) | meta/muse-spark-1.2-contributor | Meta Model API key | | Muse Spark 1.1 (Meta) | meta/muse-spark-1.1 | Meta Model API key | | Hy4 Preview (ClinePass) | clinepass/tencent/hy4-preview | ClinePass API key | | Hy4 Preview (Command Code) | commandcode/hy4-preview | Command Code API key | | Hy4 Preview (NanoGPT) | nano-gpt/tencent/hy4-preview | NanoGPT API key | | Hy4 Preview (Nous Research) | nousresearch/tencent/hy4-preview | Nous Portal API key | | Hy4 Preview (opencode Go) | opencode-go/hy4-preview | opencode Go/Zen API key | | Union Alpha (opencode Go) | opencode-go-messages/union-alpha | opencode Go/Zen API key | | Union Alpha (OpenRouter) | openrouter/union-alpha | OpenRouter API key | | Hy4 Preview (OpenRouter) | openrouter/tencent/hy4-preview | OpenRouter API key | | GLM-5.2 (ClinePass) | clinepass/glm-5.2 | ClinePass API key | | Kimi K3 (ClinePass) | clinepass/kimi-k3 | ClinePass API key | | Kimi K3 (ainetcafe) | ainetcafe/kimi-k3 | ainetcafe API key (AINETCAFE_API_KEY) | | Kimi K2.7 Code (ClinePass) | clinepass/kimi-k2.7-code | ClinePass API key | | Kimi K2.6 (ClinePass) | clinepass/kimi-k2.6 | ClinePass API key | | DeepSeek V4 Pro (ClinePass) | clinepass/deepseek-v4-pro | ClinePass API key | | DeepSeek V4 Flash (ClinePass) | clinepass/deepseek-v4-flash | ClinePass API key | | MiMo-V2.5 (ClinePass) | clinepass/mimo-v2.5 | ClinePass API key | | MiMo-V2.5-Pro (ClinePass) | clinepass/mimo-v2.5-pro | ClinePass API key | | MiniMax M3 (ClinePass) | clinepass/minimax-m3 | ClinePass API key | | Qwen3.7 Max (ClinePass) | clinepass/qwen3.7-max | ClinePass API key | | Qwen3.7 Plus (ClinePass) | clinepass/qwen3.7-plus | ClinePass API key | | Qwen3.8 Max (ClinePass) | clinepass/qwen3.8-max | ClinePass API key |

Kimi has two API platforms and they are not interchangeable. kimi-api is the global console at platform.moonshot.ai; kimi-api-cn is the mainland console at platform.moonshot.cn. Accounts, billing, and keys are separate — a key minted on one platform is rejected by the other — so each is enabled and credentialed on its own, and both can be active at once. Pick the one matching where your key was created. (kimi-oauth is a third, distinct thing: the Kimi Code subscription reused through the official CLI's session.)

The Codex catalog is credential-aware. It includes models only from enabled external providers with a stored credential or valid OAuth session. Native GPT models are included only when codex login status confirms an OpenAI login.

Qwen is key-only. Alibaba discontinued the Qwen Code OAuth free tier on 2026-04-15, so the Model Studio plan key is the sole Qwen surface; qwen-plan points at the token-plan endpoint. Set QWEN_PLAN_BASE_URL to https://dashscope-intl.aliyuncs.com/compatible-mode/v1 to bill a pay-as-you-go DashScope key through the same provider. Alibaba publishes no quota or balance API on either endpoint, so the tray shows router-observed traffic and links to the console for actual spend.

ClinePass uses Cline's OpenAI-compatible API at https://api.cline.bot/api/v1. An API key alone does not grant access to the cline-pass/* models: the account also needs an active ClinePass subscription. Create the key under Cline Settings > API Keys, then store it with ./bin/model-router codex provider-key clinepass set.

Grok OAuth reuses the official CLI credential at ~/.grok/auth.json and sends it only to xAI's documented Grok CLI inference proxy. On that path the router also attaches bare hosted web_search and x_search tools, the same agentic surface Grok Build uses. xAI's backend chooses when to search and how to filter results; the router does not take search env knobs or request-side filter config. Install the official CLI and authenticate before enabling the route:

Other routed providers can use Codex's client-side (standalone) web search when the selected model has been verified for it. DeepSeek V4 Flash is enabled on its direct API and opencode Go routes. A compatible model declares "searchTool": { "mode": "standalone" } in its registry or user-model metadata. This capability is resolved from the selected model/provider pair; the managed Codex provider block enables the provider half of standalone search so verified models can use it, while the merged catalog remains the per-model gate. The router never infers compatibility from an OpenAI-compatible endpoint. A model is advertised only after its exact provider path has been verified to preserve Codex search-result items and tool-call history. If Codex attaches hosted-search fields to an unsupported runtime-generic route anyway, the managed Responses boundary removes only those search extensions before the strict upstream sees them.

For a routed model that has no verified standalone or provider-hosted search, Codex can instead use an explicit Perplexity Search sidecar. This is not a global fallback: the binding names one exact routed model, uses a separately stored Perplexity API key, and is refused for a model that already owns a search capability. The adapter implements Perplexity's raw POST /search API and accepts only Codex search_query commands; unsupported filters or other web commands fail by name.

Create the trusted provider descriptor, enter the key at the hidden terminal prompt, and bind the model:

./bin/model-router codex providers generic add perplexity-search \
  --name "Perplexity Search" \
  --base-url https://api.perplexity.ai \
  --adapter openai-chat
./bin/model-router codex providers generic credential perplexity-search set
./bin/model-router codex search-sidecar set PROVIDER/MODEL perplexity-search
./bin/model-router codex search-sidecar status PROVIDER/MODEL

The credential command never accepts the key as an argument. The descriptor, credential reference, and per-model binding are private, atomic state; the key remains in the generic-provider protected credential file. Search requests use the generic-provider DNS-pinned, redirect-refusing transport. Result URLs must resolve publicly, credential-bearing citations are rejected, the whole operation shares one timeout across retry and backoff, and cache entries are scoped by caller account, model, provider, and credential reference. Removing the generic provider also removes its credential and every dependent sidecar binding. Fully quit and reopen Codex after changing a binding so its model catalog refreshes.

On Windows, the same commands are available through codex-router.ps1:

.\codex-router.ps1 providers generic add perplexity-search --name "Perplexity Search" --base-url https://api.perplexity.ai --adapter openai-chat
.\codex-router.ps1 providers generic credential perplexity-search set
.\codex-router.ps1 search-sidecar set PROVIDER/MODEL perplexity-search

npm install -g @xai-official/grok
grok login --oauth

[!WARNING]

Antigravity OAuth has no bundled or shared OAuth client. Create and use a

Google OAuth Desktop-app client pair that you own, as described below. A

Google AI Pro/Ultra subscription, Gemini API key, Google account, or existing

agy CLI login does not supply that pair, and the router never copies the

official agy identity or credential store. Do not use the old

your-integration-client-secret placeholder: it cannot work.

[!IMPORTANT]

The Cloud project behind your OAuth client must be allowlisted for

cloudcode-pa.googleapis.com, and most projects are not. The bootstrap call

is billed to the project that owns the calling OAuth client, so an

operator-owned client bills your project rather than Google's. That service is

a private API: binding it needs the producer-side

servicemanagement.services.bind permission, so gcloud services enable

fails even for the project owner, and it has no API Library entry to enable

through the console.

> Sign-in still succeeds; the live probe is what fails, with

PERMISSION_DENIED / SERVICE_DISABLED. If your project is not allowlisted,

this provider cannot currently be used — there is no operator-side

workaround, and no configuration in this repository changes it. See

#566.

Create a Google OAuth Desktop app client in a Google Cloud project you own:

1. In Google Cloud Console, open APIs & Services > OAuth consent screen and configure the app for your account with a truthful name such as Codex Router—not Antigravity (add the account as a test user when the consent screen is in testing mode). 2. Open APIs & Services > Credentials, choose Create credentials > OAuth client ID, and select Desktop app. Keep the resulting client ID and matching secret in that private browser tab. 3. Run the login command below and enter that one pair only in the local setup page it opens.

Do not copy the official Antigravity/agy client or credential store. The login command binds 127.0.0.1 on an OS-assigned ephemeral port before it constructs the redirect. It opens only a loopback URL through the operating system; the local listener redirects the browser to Google, so neither client value is put in process arguments or terminal output. The pair and tokens are persisted together in the router's owner-only state and are never copied to a background-service environment.

If an older incompatible router credential is already present, the new flow preserves it and asks you to run providers disconnect antigravity-oauth before sign-in; it never silently upgrades, reuses, or overwrites that record.

./bin/model-router codex providers login antigravity-oauth
./bin/model-router codex providers probe antigravity-oauth --live --yes
./bin/model-router codex providers enable antigravity-oauth

On Windows PowerShell, use the matching wrapper:

.\model-router.ps1 codex providers login antigravity-oauth
.\model-router.ps1 codex providers probe antigravity-oauth --live --yes
.\model-router.ps1 codex providers enable antigravity-oauth

The probe sends a small real prompt and consumes provider quota. It uses the truthful codex-router identity and must succeed before the route can be enabled. If the account has no companion project, rerun the probe with --provision-project only after authorizing that side effect. Provisioning still requires a successful, schema-valid bootstrap response that explicitly advertises the tier it will use; auth errors, server errors, malformed responses, and missing tiers all fa