Codex CLI

Configure Codex with a OneRouter custom provider that uses the Responses API.

Managing multiple providers?

Use the CC-Switch guide to manage Codex provider entries visually while keeping the OneRouter base URL at /v1.

Install Codex CLI

Use the official installer or npm package, then reopen the terminal if the command is not immediately available.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Verify the installation

codex --version

Set the API key

Keep API keys in environment variables or the client's protected credential store. Never commit keys to a project, paste them into chat, or include them in screenshots.

export ONEROUTER_API_KEY="YOUR_ONEROUTER_API_KEY"

Configure the custom provider

Edit the user-level ~/.codex/config.toml. The base URL stops at /v1; Codex appends the Responses API path. env_key is the environment-variable name, not the secret itself.

Keep provider and authentication settings at user level. Project configuration should not be responsible for supplying a personal API key.

model = "<MODEL_SLUG>"
model_provider = "onerouter"
model_reasoning_effort = "medium"

[model_providers.onerouter]
name = "OneRouter"
base_url = "https://onerouter.com/v1"
env_key = "ONEROUTER_API_KEY"
wire_api = "responses"

Choose model and reasoning effort

model must match a complete OneRouter slug. Codex supports minimal, low, medium, high, and xhigh as configuration values, but the selected model may support only a subset. Start with medium; remove the setting or lower it if the provider rejects the value.

SettingGuidance
modelUse the exact ID from OneRouter model discovery
model_providerMust match [model_providers.onerouter] exactly
model_reasoning_effortUse only a level supported by the selected model
wire_apiKeep responses for this provider

Launch and verify

Open a familiar small repository and start with a read-only task. Confirm the selected model and provider before allowing file edits or commands.

cd <PROJECT_PATH>
codex

Troubleshooting

SymptomHow to fix it
401Confirm ONEROUTER_API_KEY exists in the Codex process and contains the full key.
404Use /v1 and keep wire_api = "responses"; do not append /responses.
Requests go to OpenAIMake model_provider match the provider table name exactly.
Model not foundUse the complete model slug returned by OneRouter and verify key access.
Project config has no effectMove machine-level provider configuration to the user config file.