An OpenRouter coding agent uses one OpenRouter API key to reach models from many providers. OpenCode has OpenRouter built in, Codex CLI connects through a provider block in ~/.codex/config.toml, and Claude Code connects by pointing ANTHROPIC_BASE_URL at https://openrouter.ai/api, for Claude models. The catch: not every model on OpenRouter is good at tool calls, and a coding agent depends on them.
Use OpenRouter with your agent
| Agent | Supported? | How | Note |
|---|---|---|---|
| Claude Code | Claude models only | ANTHROPIC_BASE_URL=https://openrouter.ai/api plus your key in ANTHROPIC_AUTH_TOKEN |
Anthropic doesn’t support routing Claude Code to non-Claude models through any gateway. OpenRouter only guarantees it with Anthropic as the provider |
| Codex CLI | Yes | [model_providers.openrouter] in ~/.codex/config.toml |
Only in the user-level config; Codex ignores provider keys in a project’s .codex/config.toml |
| OpenCode | Yes, built in | /connect, choose OpenRouter, paste the key |
Pick a model with /models |
| Contenox | Yes | Backends → Providers → More providers → OpenRouter | Lists every text model OpenRouter returns |
Before you start: a capped key
Create a key on the keys page, give it a name, and set a credit limit. OpenRouter recommends a limit on every key, because a leaked key or a runaway agent could otherwise spend your whole balance. Agent work also needs credit on the account; see Why do free models fail?
Claude Code
Set the base URL and put the key in ANTHROPIC_AUTH_TOKEN. ANTHROPIC_API_KEY must be explicitly empty.
In PowerShell on Windows:
$env:ANTHROPIC_BASE_URL = "https://openrouter.ai/api"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_OPENROUTER_KEY"
$env:ANTHROPIC_API_KEY = ""
claude
On macOS or Linux:
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="YOUR_OPENROUTER_KEY"
export ANTHROPIC_API_KEY=""
claude
To keep the setting across terminals, put the same three values in the env block of ~/.claude/settings.json (%USERPROFILE%\.claude\settings.json on Windows). Never put the key in a project’s .claude/settings.json; that file gets committed.
Run /status in Claude Code. It should show Auth token: ANTHROPIC_AUTH_TOKEN and Anthropic base URL: https://openrouter.ai/api.
The cached-login trap: if you were signed in to Claude before, the old login can still win. Run /logout, quit, and start claude again from the shell where you set the variables.
Codex CLI
Add OpenRouter to ~/.codex/config.toml. OpenRouter’s guide uses a command that prints the key, which also lets Codex load OpenRouter’s model catalog.
On Windows:
model_provider = "openrouter"
model = "~openai/gpt-sol-latest"
[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
[model_providers.openrouter.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:OPENROUTER_API_KEY"]
Set the key with setx OPENROUTER_API_KEY "YOUR_OPENROUTER_KEY" in PowerShell, then fully restart Codex so it sees the variable.
On macOS or Linux, the auth block is:
[model_providers.openrouter.auth]
command = "sh"
args = ["-c", "echo $OPENROUTER_API_KEY"]
and the key goes in your shell profile: export OPENROUTER_API_KEY="YOUR_OPENROUTER_KEY". Then run codex in your project.
A plain env_key = "OPENROUTER_API_KEY" also authenticates, but then Codex doesn’t fetch the model catalog and warns about unknown models. A 401 with “Missing Authentication header” usually means the auth command didn’t run. Change models by editing model to another OpenRouter slug.
OpenCode
- Run
opencode, then/connect. - Choose OpenRouter and paste the key. OpenCode stores it in
~/.local/share/opencode/auth.json. - Run
/modelsand pick one. Many OpenRouter models are preloaded.
To add a model that isn’t in the list, put it under provider.openrouter.models in opencode.json.
Contenox
- Open Backends → Providers, then More providers, and choose OpenRouter.
- Paste the key into API Key, or select Create key to open OpenRouter’s keys page first.
- Select Connect and wait for Connected.
To keep the key out of the app, open Advanced and enter an Environment variable name such as OPENROUTER_API_KEY, set the variable and restart Contenox. Leave Base URL at https://openrouter.ai/api/v1. The Model chip then lists every text model OpenRouter returns, with a search box, and you can switch per session. Download Contenox.
Which OpenRouter models work for a coding agent?
A coding agent reads files, edits them and runs commands through tool calls. A model that chats well can still fail here by inventing tools or sending broken arguments.
- Start from models with tool support: OpenRouter’s list filtered to tools. Model IDs start with the provider, such as
anthropic/...ordeepseek/.... - Prefer a large context window. Agents send file contents and command output every turn.
- Test on a real task, such as fixing one failing test, and watch whether the tool calls succeed before you trust it with a multi-file change.
OpenRouter’s rankings show what people use, not how well a model performs. See How to choose a model for coding.
Why do free models fail with an agent?
Models with :free in their ID have low daily request limits, and an agent sends many requests per task. Some free endpoints don’t support tool calls at all. Use them to try OpenRouter, not for agent work. Current limits are in the OpenRouter FAQ.
Common errors
| Error | What it means | Fix |
|---|---|---|
| 401 | The key is wrong, disabled or deleted, or the agent didn’t send it | Check the variable reached the agent; create a new key if needed |
| 402 | No credit left on the account or key | Add credit |
| 403 “Key limit exceeded” | The key hit the credit limit you set on it | Raise the key’s limit on the keys page |
| 429 | Too many requests, common on free models | Wait, or switch to a paid model |
| 502 or 503 | The model is down, or no provider can serve the request | Try again later or pick another model |
If a key ever ends up in a repository or a chat log, delete it on the keys page and create a new one.
What does OpenRouter cost?
You pay per token at each model’s rate, from prepaid credit. OpenRouter adds a fee when you buy credit, and a separate rule applies if you bring your own provider key. See the pricing page and limits.
Does OpenRouter store my code?
By default, OpenRouter does not store prompts or responses unless you turn on logging. The provider it routes to has its own data policy. To route only to providers with zero data retention, choose ZDR only in your privacy settings. Details: data collection docs.
Related
- How to choose a model for coding: what matters beyond leaderboards
- AI coding costs: why agents use so many tokens
- Keep secrets away from AI agents: store keys safely
- Quickstart: connect a provider in Contenox and run a first session