How to Use OpenRouter in Claude Code

Using OpenRouter in Claude Code takes three environment variables and one logout. Set ANTHROPIC_BASE_URL to https://openrouter.ai/api, put your OpenRouter key in ANTHROPIC_AUTH_TOKEN, set ANTHROPIC_API_KEY to an empty string, then run /logout once if you were signed in with an Anthropic account. No local proxy is needed.

Here's the short version:

• Where the variables go: your shell profile (~/.zshrc, ~/.bashrc) or the env block of a Claude Code settings file
• How to pick models: ANTHROPIC_MODEL for the session, ANTHROPIC_DEFAULT_OPUS_MODEL / SONNET / HAIKU / FABLE to remap the aliases
• The big caveat: Claude Code is built for Claude models. Other models on OpenRouter may run, but tool use is where they break, and Anthropic doesn't support that setup

This guide follows OpenRouter's Claude Code integration guide and Anthropic's gateway docs as of October 2026.

Why route Claude Code through OpenRouter

OpenRouter exposes an endpoint that speaks the Anthropic Messages API. When Claude Code points at it, Claude Code talks its native protocol straight to OpenRouter, and OpenRouter forwards the request to a provider.

OpenRouter lists three reasons to do it:

The fourth reason, the one most searches are really about, is running Claude Code with other models. That works in a narrower way than people hope, and we'll get to it below.

One billing point before you start. OpenRouter bills these requests to your OpenRouter credits. Anthropic's LLM gateway docs add that while a gateway credential is active, your claude.ai subscription's usage limits don't apply to those requests. In other words, a Pro or Max plan doesn't pay for Claude Code traffic sent through OpenRouter. If you're weighing that tradeoff, our comparison of OpenRouter alternatives covers the other gateways.

How to use OpenRouter in Claude Code: the setup

If Claude Code isn't installed yet, start with our Claude Code install guide. Then get an API key from your OpenRouter account settings.

Step 1: Set the three variables

OpenRouter's requirements are specific:

1. ANTHROPIC_BASE_URL is https://openrouter.ai/api, scheme included
2. ANTHROPIC_AUTH_TOKEN holds your OpenRouter API key
3. ANTHROPIC_API_KEY is explicitly empty

Why the token variable and not the key variable? Claude Code sends ANTHROPIC_AUTH_TOKEN as an Authorization: Bearer header, which is what OpenRouter reads. ANTHROPIC_API_KEY goes out as an x-api-key header and is treated as a direct Anthropic credential. Blanking it keeps Claude Code from falling back to Anthropic.

The shell profile version, from OpenRouter's guide:

# ~/.zshrc or ~/.bashrc
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=""

Reload with source ~/.zshrc or open a new terminal. Skip that and you'll test the old environment and decide the setup is broken.

OpenRouter flags an ordering trap here. ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY" expands when the profile loads. If the key is defined later in the file, or injected by a secrets manager after your profile runs, the token expands to an empty string and every request fails with an auth error.

Step 2: Clear a cached Anthropic login

If you ever signed in to Claude Code with an Anthropic account, run this once inside Claude Code:

/logout

Then quit and relaunch claude. OpenRouter says a cached login alongside a gateway credential produces auth-conflict warnings and confusing model-not-found errors, especially for OpenRouter-only model names.

Anthropic's gateway connection guide describes the same conflict from its side. ANTHROPIC_AUTH_TOKEN takes precedence over a saved claude.ai login immediately, and the login stays saved but unused. A real ANTHROPIC_API_KEY, by contrast, prompts you once to approve it before it takes over. /logout only clears the saved login. It does nothing about an old Anthropic key still exported in your shell, which is why Step 1 blanks it.

Step 3: Verify with /status

Start claude in your project and run /status. You want two lines:

Auth token: ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://openrouter.ai/api

If the auth line names ANTHROPIC_API_KEY, or a Login method line names a Claude account, the environment didn't reach the session. Reload the shell and relaunch. Then send a prompt and check that it appears in your OpenRouter activity.

Shell profile vs settings.json: where to put the variables

You have two homes for the configuration, and they behave differently.

The settings-file form:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "<your-openrouter-api-key>",
    "ANTHROPIC_API_KEY": ""
  }
}

Three rules from the docs decide which one wins and what gets read:

• Settings beat the shell. If both set the same variable, the settings-file value applies.
• .env files don't count. OpenRouter warns that the native installer doesn't read a project .env file.
• Background agents need settings. Anthropic notes that a gateway exported only in your shell doesn't reliably reach background agents. Use a settings file if those must route through OpenRouter.

The VS Code extension is its own case. Anthropic's docs put gateway variables for it in claudeCode.environmentVariables in VS Code's user settings, because the extension checks credentials there before it launches.

On key hygiene, OpenRouter suggests loading the key from your OS keychain instead of pasting it into a profile. On a Mac, that looks like export OPENROUTER_API_KEY="$(security find-generic-password -s openrouter -w)".

Choosing models: ANTHROPIC_MODEL and ANTHROPIC_DEFAULT_*_MODEL

Claude Code doesn't ask OpenRouter for "a model". It asks for whatever its aliases resolve to, so model choice comes down to a handful of variables. Anthropic's model configuration docs define them:

Each value has to be a model name the provider understands. On OpenRouter, that's the OpenRouter slug. OpenRouter's own example maps every class to an Anthropic model through its latest aliases:

export ANTHROPIC_DEFAULT_FABLE_MODEL="~anthropic/claude-fable-latest[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="~anthropic/claude-opus-latest[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="~anthropic/claude-sonnet-latest[1m]"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="~anthropic/claude-haiku-latest"
export CLAUDE_CODE_SUBAGENT_MODEL="~anthropic/claude-opus-latest[1m]"

A few details that save debugging time:

• The [1m] suffix matters. Claude Code assumes a 200k context window unless the model name ends in [1m]. OpenRouter strips the marker before routing, so it only changes what Claude Code assumes. Our post on the 1M context window explains why that changes when compaction kicks in.
• Fable isn't offered by default. OpenRouter says that through its endpoint, Fable only shows up in /model if you set ANTHROPIC_DEFAULT_FABLE_MODEL.
• Order of priority. /model mid-session beats --model at launch, which beats ANTHROPIC_MODEL, which beats the model field in settings.
• Subagents follow their own variable. Set CLAUDE_CODE_SUBAGENT_MODEL if you want Claude Code subagents on a cheaper or stronger model than the main session.

Want to browse rather than pin? Set CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 and restart. Claude Code then asks OpenRouter for a model list at startup and adds it to the /model picker. OpenRouter says the picker shows a curated set of top-ranked models, not its whole catalog, and that some entries route to non-Anthropic providers.

Claude Code with other models: what actually works

This is where expectations need resetting.

Anthropic doesn't support it. The LLM gateway docs say Anthropic doesn't support routing Claude Code to non-Claude models through any gateway. If it breaks, you're on your own.

OpenRouter hedges too. Its guide says Claude Code with OpenRouter is only guaranteed to work with the Anthropic first-party provider, and recommends setting Anthropic as the top-priority provider through provider selection. It also says plainly that Claude Code is optimized for Anthropic models and may not work correctly with other providers.

Tool use is the failure point. Claude Code is an agent. Every file read, edit and shell command is a tool call. A model that chats well but handles tool calls poorly will stall, loop, or return malformed calls. Before you map an alias to a non-Anthropic model, check that it supports tools. OpenRouter's model list can be filtered to tool-capable models. Even then, treat it as an experiment rather than a production setup.

Some features need Claude. Auto mode, Claude Code's classifier-reviewed permission mode, requires a supported Claude model. When it isn't available, Claude Code starts the session in Manual mode instead. Our guide to Claude Code auto mode covers the requirements.

A practical pattern if you want to experiment: keep opus and sonnet on Claude, and remap only haiku, which handles lighter background work. If something misbehaves, you'll know which alias to blame.

Troubleshooting OpenRouter in Claude Code

Remote Control and voice dictation are also unavailable while a gateway credential is active, per Anthropic's connection guide, because both rely on a claude.ai identity.

When the setup is the problem

All of this is a lot of environment plumbing for the person who just wanted Claude Code to work with a different model. If you spend more time on /status than on the task, Taku is a different shape: an AI-native desktop workspace where you mirror an AI setup someone already got working and run it, without reproducing their environment first. Taku is in Beta, and the Mac app is available now.

FAQ

Can Claude Code use OpenRouter?

Yes. Set ANTHROPIC_BASE_URL to https://openrouter.ai/api, put your OpenRouter key in ANTHROPIC_AUTH_TOKEN, set ANTHROPIC_API_KEY to an empty string, and run /logout once if you were signed in to Anthropic.

Should I use ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY for OpenRouter?

ANTHROPIC_AUTH_TOKEN. It's sent as a bearer token, which OpenRouter expects. Leave ANTHROPIC_API_KEY explicitly empty so Claude Code doesn't fall back to authenticating with Anthropic.

Can I use non-Claude models in Claude Code through OpenRouter?

You can map an alias to one, but neither company guarantees it works. Anthropic doesn't support non-Claude models through gateways, and OpenRouter only guarantees the Anthropic first-party provider. Tool calling is where other models usually fail.

How do I change the model Claude Code uses on OpenRouter?

Set ANTHROPIC_MODEL for the session, or remap the aliases with ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL and ANTHROPIC_DEFAULT_FABLE_MODEL, using OpenRouter model slugs.

Does my Claude Pro or Max subscription cover OpenRouter usage?

No. While a gateway credential is active, Anthropic says your subscription's usage limits don't apply to those requests. OpenRouter bills them to your OpenRouter credits.

Why does Claude Code still use my Anthropic account?

Usually a cached login or a real key in ANTHROPIC_API_KEY. Run /logout, blank the key, reload your shell, and confirm with /status that the auth line names ANTHROPIC_AUTH_TOKEN.