Last updated September 8, 2026

Install Codex Router on macOS (Codex App & CLI)

This page walks through the recommended full installation of Codex Router on macOS for the Codex App or CLI. It includes the Control Center, menu-bar host and desktop widget, then verifies everything before you open the model picker.

Requirements on macOS

The Codex App or the Codex 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.

Recommended full install

Open Terminal and run:

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

The wizard lets you toggle providers by number, shows a live ready/needs-key/needs-sign-in status for each one, and walks you through credential onboarding for anything you selected. It ends with a review summary before anything is installed.

Never paste a key into the command. API keys are entered through a hidden terminal prompt, and the installer refuses to touch a ChatGPT login or your existing Codex settings.

The recommended command builds and installs Codex Router.app, which combines the native menu-bar host with the Electron Control Center. Opening the app shows the Control Center; closing its window leaves the menu-bar host running. Launch it from Spotlight or ~/Applications, or rebuild it with:

./bin/model-router-tray

The app bundle is placed in ~/Applications and 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, and can use /Applications/Xcode.app without changing the global selection. The Dynamic-Island-style overlay is off by default; choose Settings → Dynamic Island → Desktop for the movable quota and activity widget.

If Xcode is installed elsewhere, rebuild the companion with:

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

Kimi OAuth on macOS

If you select Kimi OAuth, guided setup reuses the official Kimi Code CLI session. When the CLI already exists, it offers to run the login command:

kimi login

The router reads the official credential under $KIMI_CODE_HOME or ~/.kimi-code and refreshes it under a cross-process lock. Do not copy the OAuth token into Codex config, an API-key file, or an environment variable.

Verify the install

Codex loads model_catalog_json only at app startup, so after setup:

Run ./bin/model-router codex doctor and resolve any FAIL line.
Confirm ./bin/model-router codex providers says SHOW and ready for the provider you chose.
Fully quit Codex with Command-Q, reopen it, and create a new task.
Open the normal model picker and look for the routed model.

You can inspect Codex’s startup catalog directly:

codex debug models

If models are still missing, run ./bin/refresh-catalog, fully quit Codex, and reopen it.

Check the background service

The router runs as a per-user launchd service. To inspect it:

launchctl print "gui/$(id -u)/io.github.codex-router"

If the service is stopped, ./bin/model-router codex doctor --fix rebuilds the managed config and service state.

Uninstall

./bin/model-router codex uninstall

Uninstall removes the marked integration config and current service but intentionally retains the checkout, logs, backups and provider credentials. To fully remove state, inspect ~/.codex/codex-router manually before deleting anything.

For common problems on macOS, see the troubleshooting overview and the Windows install guide for the Windows-specific notes.