OpenRouter in Claude Code, Codex and OpenCode: the settings
The OpenRouter settings for Claude Code, Codex and OpenCode side by side: where the key goes, how to pick a model, and what each maker says will not work.
All three take an OpenRouter key, each in its own way. Claude Code: set ANTHROPIC_BASE_URL=https://openrouter.ai/api, put the key in ANTHROPIC_AUTH_TOKEN and set ANTHROPIC_API_KEY to an empty string; Anthropic does not support it with non-Claude models. Codex: define [model_providers.openrouter] in ~/.codex/config.toml with base_url = "https://openrouter.ai/api/v1", env_key = "OPENROUTER_API_KEY" and wire_api = "responses", the only wire API Codex accepts, then set model_provider = "openrouter". OpenCode: run /connect and choose OpenRouter, or give the OpenCode server OPENROUTER_API_KEY, and name models as openrouter/<OpenRouter model ID>. Every request is then billed to your OpenRouter credits, not to a Claude or ChatGPT plan.
| Where it goes | The key | The model | |
|---|---|---|---|
Claude Code | Environment, or the env block of ~/.claude/settings.json | ANTHROPIC_AUTH_TOKEN | --model, /model, ANTHROPIC_DEFAULT_*_MODEL |
Codex | ~/.codex/config.toml only, never a project’s | The variable named in env_key | model in the config, or -m |
OpenCode 2 | /connect, or opencode.json for the model | Saved by /connect, or OPENROUTER_API_KEY on the server | openrouter/<id> |
Claude Code
Claude Code talks Anthropic’s Messages API, and OpenRouter serves that API under https://openrouter.ai/api, so Claude Code treats OpenRouter as an LLM gateway. OpenRouter’s Claude Code page gives these lines for a shell profile:
export OPENROUTER_API_KEY="<your-openrouter-api-key>"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1CopiedThe key goes in ANTHROPIC_AUTH_TOKEN because Claude Code sends that variable as an Authorization: Bearer header, while ANTHROPIC_API_KEY goes out as x-api-key. The empty ANTHROPIC_API_KEY, in OpenRouter’s words, “keeps Claude Code from falling back to authenticating against Anthropic directly.” The last line is optional: it adds OpenRouter’s models to the /model picker.
On a server, a shell profile is the weak spot: cron, a systemd unit and ssh host 'claude -p …' do not read it. Claude Code’s gateway page puts the same variables in the env block of ~/.claude/settings.json, which applies to all your projects, wins over a shell export, and reaches background agents that a shell export may not:
{
"env": {
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_AUTH_TOKEN": "sk-or-...",
"ANTHROPIC_API_KEY": ""
}
}CopiedThat file now holds a live key, so keep it readable by you alone (chmod 600 ~/.claude/settings.json), and never put the key in a project’s .claude/settings.json, which is committed. Before starting Claude Code, the gateway page’s test request checks the URL and key on their own:
curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
-H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'CopiedAn error naming an unknown model still proves the key works, since OpenRouter checked it before rejecting the name; a 401 is the key. Inside Claude Code, /status should show an Anthropic base URL line with OpenRouter’s address and an Auth token line naming ANTHROPIC_AUTH_TOKEN. A startup warning that names two credential sources and ends in “auth may not work as expected” means a saved claude.ai login is still there; /logout removes it, but does not clear shell variables.
Choosing the model
The base URL changes where requests go, not which model answers. Claude Code picks the model by its usual order: /model in a session, claude --model at start, ANTHROPIC_MODEL, then the model setting. With OpenRouter, the names are OpenRouter’s IDs, and the cleanest place for them is the alias variables, which control what sonnet, opus, haiku and fable resolve to, so anything that asks for one of those aliases gets the OpenRouter model you named. Setting the Haiku one also moves background tasks such as session titles to that model:
export ANTHROPIC_DEFAULT_SONNET_MODEL="~anthropic/claude-sonnet-latest"
export ANTHROPIC_DEFAULT_OPUS_MODEL="~anthropic/claude-opus-latest"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="~anthropic/claude-haiku-latest"CopiedThe ~ IDs are OpenRouter’s aliases for each family’s latest model; a model’s own ID, as OpenRouter’s model page lists it, pins one.
What Anthropic and OpenRouter say does not work
- Models other than Claude. Anthropic’s gateway page says it “doesn’t support routing Claude Code to non-Claude models through any gateway.” OpenRouter’s own page goes further: “Claude Code with OpenRouter is only guaranteed to work with the Anthropic first-party provider.” Another lab’s OpenRouter ID can be put in these variables, but neither maker supports the result.
- Your Claude plan. With a gateway credential active, requests carry it “in place of a developer’s claude.ai subscription login”, the plan’s limits do not apply, and the traffic is “billed per token to whoever owns the credential”: here, your OpenRouter balance. A Pro or Max plan cannot be spent through OpenRouter.
- Remote Control and voice dictation. Both “are unavailable while
ANTHROPIC_API_KEY,ANTHROPIC_AUTH_TOKEN, or anapiKeyHelperis active.” If you drive a server’s sessions from your phone with Remote Control, an OpenRouter session is not one you can reach that way. - 400 errors naming fields the upstream does not know, such as “Extra inputs are not permitted”. Claude Code’s fix for a gateway whose upstream rejects its newer request fields is
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1.
Codex
Codex reaches any provider through a custom entry in its config, and the entry must speak OpenAI’s Responses API: Codex’s config reference says of wire_api that “responses is the only supported value, and it is the default when omitted.” OpenRouter serves that API at https://openrouter.ai/api/v1/responses. In ~/.codex/config.toml:
model_provider = "openrouter"
model = "~openai/gpt-sol-latest"
[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
wire_api = "responses"CopiedThen export OPENROUTER_API_KEY and run codex. Three things trip people up:
- Older tutorials say
wire_api = "chat". Current Codex refuses it: “wire_api = "chat"is no longer supported. How to fix: setwire_api = "responses"in your provider config.” - The block in a project’s
.codex/config.tomlis ignored.model_providerandmodel_providersare among the keys Codex ignores in a project-local config, with a warning at startup. They belong in~/.codex/config.toml. - An unset variable stops Codex before any request: “Missing environment variable:
OPENROUTER_API_KEY.” Under cron or a service, that is the usual cause.
Codex reads -m for one run, so codex exec -m '~anthropic/claude-sonnet-latest' "…" switches model without editing the file; any OpenRouter ID goes in model. OpenRouter’s Codex page adds that with env_key, Codex does not fetch OpenRouter’s model catalogue, so a model that is not OpenAI’s shows an “Unknown model” fallback warning. Its preferred form replaces env_key with a command that prints the key, which Codex calls when it needs a token:
[model_providers.openrouter]
name = "openrouter"
base_url = "https://openrouter.ai/api/v1"
[model_providers.openrouter.auth]
command = "sh"
args = ["-c", "echo $OPENROUTER_API_KEY"]CopiedCodex’s reference forbids combining an auth block with env_key, so use one or the other. That command still needs the variable in Codex’s environment. On a server, where a scheduled codex exec has no login shell, the command can just as well read a file only you can read, command = "cat" with the file’s path in args: anything that prints the key on standard output will do. If it prints nothing, OpenRouter answers 401 “No API key in the Authorization header”.
Keeping your ChatGPT sign-in as the default
Setting model_provider at the top of the config moves every session to OpenRouter. To keep Codex signed in with ChatGPT and use OpenRouter only when you ask, leave the [model_providers.openrouter] block in ~/.codex/config.toml and move the two top lines to a profile. Codex loads ~/.codex/config.toml, then overlays ~/.codex/<name>.config.toml with top-level keys, so ~/.codex/openrouter.config.toml holds:
model_provider = "openrouter"
model = "~openai/gpt-sol-latest"Copiedand codex --profile openrouter or codex exec --profile openrouter "…" uses it. A custom provider does not use the ChatGPT sign-in, so the run is billed to OpenRouter and does not touch your plan’s usage limit.
OpenCode
OpenRouter is one of OpenCode’s built-in providers, so there is nothing to define. In the terminal interface, run /connect, choose OpenRouter, paste the key, then pick a model with /models. Outside the interface:
opencode auth login # choose OpenRouter, paste the key
opencode auth list # confirm it was savedCopiedOpenCode’s providers page gives the other route: “Provide OPENROUTER_API_KEY to the OpenCode server or connect an OpenRouter account.” In OpenCode 2 the server is a background service, so the variable has to be set on it, not only in your shell; the background service guide covers opencode service set env.
Models are named with the openrouter/ prefix and then the full OpenRouter ID, tilde included. As the default in opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"model": "openrouter/~anthropic/claude-sonnet-latest"
}Copiedor for one unattended run, opencode run --model openrouter/~anthropic/claude-sonnet-latest "…". Where that file lives and which copy wins is in the OpenCode config guide. OpenRouter’s OpenCode page writes its examples in version 1’s shape, under provider; OpenCode 2 still reads that, and calls the key providers. If OpenRouter’s models do not appear after connecting, OpenRouter’s advice is to quit OpenCode fully and start it again, since the catalogue loads at startup.
When OpenRouter refuses the request
Once the agent reaches OpenRouter, its errors are OpenRouter’s, whichever agent shows them:
- A 401 is the key: missing, empty, deleted, or another provider’s key sent by mistake. The wording says which; OpenRouter’s 401 errors decodes each.
- A 402, “requires more credits, or fewer max_tokens”, can arrive with money still in the account, because OpenRouter reserves the request’s largest possible output first. The credits guide covers why. In Claude Code the output cap is
CLAUDE_CODE_MAX_OUTPUT_TOKENS. - “No endpoints found that support tool use” means no provider of that model accepts tools, and all three agents send tools on every request. Pick a model with tool support; the no-endpoints guide shows how to check one before an agent uses it.
- A 429 is a rate limit: a free model’s cap or the upstream provider’s. The 429 guide tells them apart. An agent session sends many requests in a few minutes, so the free models’ per-minute cap is reached quickly.