Codex CLI with OpenRouter
VerifiedUse model slugs from OpenRouter's fast-changing catalog inside Codex CLI through a single API key. OpenRouter documents this integration for its coding agents.
Last verified 2026-07-30 against official provider documentation.
About Codex CLI
Codex CLI is OpenAI's open-source coding agent for the terminal. It reads custom model providers from ~/.codex/config.toml and authenticates through an environment variable.
About OpenRouter
OpenRouter is a unified API gateway to hundreds of models from many providers. One key unlocks every model slug, with provider failover and a single billing dashboard.
Key points
- The model slug must match the OpenRouter catalog exactly, including the provider prefix (for example openai/gpt-5.3-codex).
- wire_api = "responses" is required: Codex removed the chat completions protocol in February 2026.
- openai, ollama, and lmstudio are reserved provider IDs; define a new block named openrouter as shown.
- The key is read from the OPENROUTER_API_KEY environment variable via env_key.
Set up Codex CLI with OpenRouter
Choose your operating system, shell and model. The steps below update instantly and are generated locally in your browser.
Many OpenRouter slugs work. Compatibility depends on the model supporting the Responses API and Codex tool/request semantics; the ~ aliases resolve to the newest matching model.
Browse the full OpenRouter model catalogGet an API key
Create a OpenRouter API key. Codex CLI authenticates with it — it never leaves your machine.
Get a OpenRouter API key- Install Codex CLI: npm install -g @openai/codex
- Sign in, open Keys, and create a key that starts with sk-or-. Free-tier requests are available; adding $10 in credits raises your daily free limit.
Configure the connection
Add the provider block to your Codex config, then export your API key.
model = "openai/gpt-5.3-codex"
model_provider = "openrouter"
model_reasoning_effort = "high"
[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
wire_api = "responses"
env_key = "OPENROUTER_API_KEY"Create the file if it does not exist. Provider settings only take effect in the user-level config.
- 1Add to ~/.zshrc
export OPENROUTER_API_KEY="sk-or-"Verify the configuration
Run this command in a new terminal. A successful response confirms that Codex CLI is talking to the configured endpoint.
codex exec "Say hello in one sentence."The exact reply varies. You can also verify the request appears in the provider dashboard (billing / activity page).
Start using it
Launch Codex CLI and send your first message.
- Type: Explain the files in this project.
codexTroubleshooting
Most issues fall into one of these categories. Each entry lists the cause, the fix, and how to verify it.
401 Unauthorized
Troubleshooting guideThe API key is wrong, expired, or the provider account has no balance.
Create a fresh key on the provider dashboard, then regenerate the config with the new key. If the key is stored in a shell profile, open a new terminal so the export takes effect.
Verify: Run `echo $ANTHROPIC_AUTH_TOKEN` (or `echo $DEEPSEEK_API_KEY` / `$OPENROUTER_API_KEY` for Codex) and confirm the value looks like a valid key.
404 Not Found
Troubleshooting guideThe base URL is wrong (typo, extra path segment) or, on Codex, the wire protocol does not match what the provider serves.
Copy the exact base URL from this page. For Codex, keep `wire_api = "responses"` with OpenRouter; if DeepSeek returns 404 on /responses, try removing the wire_api line to match the endpoint your provider serves.
Verify: Re-run the verify command from step 3 and check the error path: it should end in /anthropic (Claude Code) or /responses (Codex).
Model Not Found
Troubleshooting guideThe model name does not exist on the provider, or the agent cached an old login that overrides the environment.
Pick a model from the provider list on this page. For Claude Code with OpenRouter, run `/logout` inside Claude Code, then relaunch — a cached Anthropic login overrides your environment variables.
Verify: Confirm ANTHROPIC_API_KEY is set to an empty string (OpenRouter) or unset (DeepSeek), then run `claude /status` again.
Rate Limit / Insufficient Quota
Troubleshooting guideThe provider limits requests per minute, or the account balance ran out.
Wait for the limit window, top up the account balance, or switch to a cheaper model. OpenRouter users can raise free-tier limits by adding credits.
Verify: Check the provider dashboard (balance and usage page) for the rejected request.
Network Error / Connection Failed
Troubleshooting guideThe machine cannot reach the provider endpoint, or an intercepting proxy rewrites the request.
Check DNS and connectivity to the base URL, review proxy and firewall settings, and retry. Use the exact endpoint from this page; third-party mirrors are not supported.
Verify: Run `curl -I <base url>` (e.g. `curl -I https://api.deepseek.com/anthropic`) and confirm a reachable response.
Timeout / Request Timed Out
Troubleshooting guideA slow model, a long prompt, or a restricted network to the provider region.
Retry the request, shorten the prompt, or switch to a faster model. Region-based connectivity issues may require a different network or a provider with closer servers.
Verify: Run the verify command again when the network is idle and confirm it completes.
Fails with "wire_api chat" error
Codex removed the chat completions wire protocol in February 2026.
Set wire_api = "responses" in the openrouter provider block (the generated config already does this).
Verify: `codex exec "hi"` starts without a protocol error.
Frequently asked questions
Why does Codex report "Unknown model" for non-OpenAI models?
Codex cannot fetch the OpenRouter model catalog when using env_key-based auth, so fallback metadata is shown. The requests still work; command-based auth restores the catalog.
Why is the reserved ID openrouter not available?
openai, ollama, and lmstudio are built in. Any other name, including openrouter, is fine — just use the block exactly as generated.
Does model_reasoning_effort apply to every model?
It is ignored by models that do not expose a reasoning effort control. It is safe to leave in the config.