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 | shVerify the installation
codex --versionSet 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.
| Setting | Guidance |
|---|---|
model | Use the exact ID from OneRouter model discovery |
model_provider | Must match [model_providers.onerouter] exactly |
model_reasoning_effort | Use only a level supported by the selected model |
wire_api | Keep 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>
codexTroubleshooting
| Symptom | How to fix it |
|---|---|
| 401 | Confirm ONEROUTER_API_KEY exists in the Codex process and contains the full key. |
| 404 | Use /v1 and keep wire_api = "responses"; do not append /responses. |
| Requests go to OpenAI | Make model_provider match the provider table name exactly. |
| Model not found | Use the complete model slug returned by OneRouter and verify key access. |
| Project config has no effect | Move machine-level provider configuration to the user config file. |