AI RouterAI Router
User GuideAPI ReferenceAI ApplicationsHelp & SupportBusiness Cooperation

OpenAI Codex CLI

Configure OpenAI Codex CLI on Windows, macOS, and Linux to use AI Router as an OpenAI-compatible endpoint with a single API key and base URL.

About this page

This guide shows how to point the OpenAI Codex CLI at AI Router so your Codex sessions route through your AI Router key and base URL.

AI Router is a unified, OpenAI-compatible AI gateway: one API key plus one base URL lets you reach many model providers, with model groups, token groups, quotas, and usage tracking.

Codex CLI is a terminal-based coding agent that runs locally and edits code, applies patches, and runs commands. Because it speaks the OpenAI-compatible protocol, you can redirect it from the default OpenAI endpoint to AI Router by changing two settings: the base URL and the API key.

What you need

A AI Router API key

Create a key in the AI Router console. It looks like sk-... (key management TBD in your deployment).

The AI Router base URL

The OpenAI-compatible endpoint, e.g. https://ai.sammier.com/v1

Node.js 18+ (or Homebrew on macOS)

Required to install the Codex CLI via npm.

Use your own base URL

https://ai.sammier.com is a placeholder. Replace it everywhere below with the address of the AI Router instance you actually use — either your own self-hosted deployment or one provided to you. Do not connect API addresses or keys from unknown sources to a production environment.

Configure Codex CLI for AI Router

Codex CLI reads its configuration from ~/.codex/config.toml and takes the API key from an environment variable. The pattern is the same on every platform:

  1. Define a custom model provider that points base_url at your AI Router OpenAI-compatible endpoint.
  2. Make that provider the default.
  3. Export your AI Router key as an environment variable.

Create or edit ~/.codex/config.toml

Add a provider block for AI Router and select it as the default. Replace the base URL and model with the ones available on your AI Router instance.

model = "gpt-4o"            # any model your AI Router instance exposes
model_provider = "code-router"

[model_providers.code-router]
name = "AI Router"
base_url = "https://ai.sammier.com/v1"
env_key = "CODE_ROUTER_API_KEY"

The env_key value names the environment variable Codex will read the key from.

Export your API key

Set the environment variable named in env_key to your AI Router key.

export CODE_ROUTER_API_KEY="sk-..."

Add the line to ~/.zshrc or ~/.bashrc to persist it across sessions.

setx CODE_ROUTER_API_KEY "sk-..."

Open a new terminal afterward so the variable is picked up.

Run Codex

Start Codex in any project directory:

cd /path/to/your/project
codex

Use /model inside the session to switch between models your AI Router instance exposes.

Which models can I use?

The available model names depend on the model groups configured on your AI Router instance. Check the AI Router console for the list, and use those exact names in config.toml or via the /model command. (Specific model catalog and pricing: TBD.)

Installing Codex CLI

If you do not yet have Codex CLI installed, follow the steps for your platform, then return to the configuration section above.

Install Node.js with Homebrew (see https://brew.sh), then install the CLI:

brew update
brew install node
npm install -g @openai/codex
codex --version

Permission errors

If npm install -g fails on permissions, either prefix with sudo, or point npm at a user directory:

npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Install Node.js (LTS) and then the CLI:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @openai/codex
codex --version

Build dependencies

Some distributions need build tooling:

# Ubuntu / Debian
sudo apt install build-essential
# Fedora / RHEL
sudo dnf groupinstall "Development Tools"

For the best experience on Windows, use the Windows Subsystem for Linux (WSL2), then follow the Linux steps inside WSL.

wsl --install

Restart Windows after installation, open a WSL shell, install Node.js (an LTS release such as 22), then install the CLI:

wsl
nvm install 22        # if using nvm
npm install -g @openai/codex
codex --version

Windows notes

  • Prefer PowerShell over CMD when not using WSL.
  • If you hit permission issues, try running the terminal as administrator.
  • Some antivirus tools may flag the install; add an exception if needed.

How routing works after configuration

Once the base URL points at AI Router, every model request from Codex — including names that look like vendor-preset models — is sent to your configured AI Router endpoint and authenticated with your AI Router key. AI Router then resolves the model to a provider channel and tracks usage against your quota.

Feedback

Found an issue with these docs or with AI Router? Open an issue on the source repository: https://github.com/ssgzy/Router-new-api.

How is this guide?

Last updated on

Claude Code

Configure Claude Code, Anthropic's terminal coding agent, to route requests through AI Router using an Anthropic-compatible base URL and your AI Router API key.

Factory Droid CLI

Factory Droid CLI setup guide — install and configure this AI software engineering agent with AI Router. Supports end-to-end development from planning to testing.

On this page

What you need
Configure Codex CLI for AI Router
Create or edit ~/.codex/config.toml
Export your API key
Run Codex
Installing Codex CLI
How routing works after configuration