Codex CLI

iBefore you start, make sure you have:

Codex CLI installed and available as codex。
A working Yolo Router endpoint, for example https://api.yolorouter.com。
A Yolo Router API Key generated from the console
The model ID you want to use, for example deepseek-v4-pro，It must exactly match the model ID in the Yolo Router console

Codex CLI custom providers currently use the Responses protocol. Confirm that your Yolo Router endpoint supports /v1/responses; otherwise the CLI may return 404, compatibility, or streaming errors.

Setup

Check Codex CLI

Run:

codex --version

If PowerShell blocks the script on Windows, use cmd, Git Bash, WSL, or launch PowerShell with a process-level execution policy override:

powershell -ExecutionPolicy Bypass -Command "codex --version"

Set the Yolo Router API Key

Store your API Key in an environment variable. This example uses YOLOROUTER_API_KEY, which is referenced by config.toml in the next step.

export YOLOROUTER_API_KEY="sk-yolo-..."

$env:YOLOROUTER_API_KEY = "sk-yolo-..."

set YOLOROUTER_API_KEY=sk-yolo-...

For permanent use, add it to your shell profile or system environment variables. Do not write real API keys into config.toml or commit them to your repository.

Edit Codex config

Open the user-level config file:

~/.codex/config.toml

On Windows, this is usually:

%USERPROFILE%\.codex\config.toml

Add or merge this configuration:

model = "deepseek-v4-pro"
model_provider = "yolorouter"

[model_providers.yolorouter]
name = "Yolo Router"
base_url = "https://api.yolorouter.com/v1"
wire_api = "responses"
env_key = "YOLOROUTER_API_KEY"
env_key_instructions = "Set YOLOROUTER_API_KEY to your Yolo Router API Key"

Replace:

base_url with your Yolo Router endpoint, keeping /v1
env_key only if you used a different environment variable name
model with the model ID you want to use, for example deepseek-v4-pro

Use a separate profile (optional)

If you do not want to change the default Codex CLI OpenAI configuration, put Yolo Router in a separate profile:

[model_providers.yolorouter]
name = "Yolo Router"
base_url = "https://api.yolorouter.com/v1"
wire_api = "responses"
env_key = "YOLOROUTER_API_KEY"
env_key_instructions = "Set YOLOROUTER_API_KEY to your Yolo Router API Key"

[profiles.yolorouter]
model = "deepseek-v4-pro"
model_provider = "yolorouter"

Start Codex with:

codex --profile yolorouter

Test the connection

Open any test directory and run:

codex --profile yolorouter "Introduce the model you are using in one sentence"

If Yolo Router is configured as the default provider, run:

codex "Introduce the model you are using in one sentence"

If Codex CLI returns a normal response, the integration is working.

Troubleshooting

API Key not found

Check that the current terminal can read the environment variable:

echo $YOLOROUTER_API_KEY

echo $env:YOLOROUTER_API_KEY

echo %YOLOROUTER_API_KEY%

If the output is empty, set the environment variable again before starting Codex CLI.

Model not found

Check that model exactly matches the model ID in the Yolo Router console. Use the model ID, not a display name, alias, or value with extra spaces.

Incompatible endpoint or 404

Check that base_url includes /v1, and confirm that Yolo Router supports the Responses API used by Codex CLI. You can first verify that the endpoint and key work:

curl https://api.yolorouter.com/v1/models \
  -H "Authorization: Bearer $YOLOROUTER_API_KEY"

On Windows PowerShell:

curl.exe https://api.yolorouter.com/v1/models `
  -H "Authorization: Bearer $env:YOLOROUTER_API_KEY"

Temporarily switch models

Use --model to override the configured model for a single run:

codex --profile yolorouter --model deepseek-v4-pro "Inspect the current project structure"

On this page