Install Codex Router on macOS (Codex App & CLI)

This page walks through installing Codex Router on macOS for either the Codex App or the Codex CLI, including the optional menu-bar control panel, and explains how to verify that everything is healthy 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.

Guided install

Open Terminal and run:

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

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.

Desktop companion (optional)

On macOS, guided setup can build and launch the native menu-bar control panel, which shows Codex health, per-provider usage, quota cards and provider controls in a native glass interface. Run it any time with:

./bin/model-router-tray

The app bundle is placed in ~/Applications and needs the Swift toolchain. If the toolchain is missing, guided setup skips the step with guidance instead of failing the install. On first launch the tray registers itself as a login item so it reopens after a reboot; you can disable that from its Settings tab or System Settings › Login Items.

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:

1. Run ./bin/model-router codex doctor and resolve any FAIL line.
2. Confirm ./bin/model-router codex providers says SHOW and ready for the provider you chose.
3. Fully quit Codex with Command-Q, reopen it, and create a new task.
4. 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.