.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Claude Code's harness (the agent loop, the tool use, the permission system, the session handling) is the part people don't want to give up. The models behind it are swappable, though. Point the CLI at OpenRouter and the same harness drives whatever OpenRouter serves, from other providers' frontier models to cheap open-weight ones, all on one bill with fallbacks when a provider has a bad day. This guide covers the direct env-var method first, then claude-code-router for setups that need real routing logic. I tested everything on an Ubuntu 24.04 VPS with the native Claude Code install.
The trade-offs before you start
Being upfront about the costs of this arrangement, since the blog posts hyping it rarely are. You lose subscription pricing: everything becomes per-token through OpenRouter credits, and for daily interactive use a Claude plan is hard to beat on price, as I've laid out in the article on what Claude Code costs. Some Claude Code features assume Anthropic models and degrade or disappear behind a gateway. Output quality swings hard by model, because the harness was tuned around Claude's tool-calling behavior and other models drive it with varying grace. And Anthropic doesn't support this configuration, so when something breaks you're debugging it yourself.
None of that makes it a bad idea. It makes it a tinkerer's setup, or a deliberate choice for teams that already bill through OpenRouter. Go in knowing which one you are.
Point Claude Code at OpenRouter directly
The OpenRouter cookbook documents the supported method: two officially documented Claude Code variables plus a blanked key. Claude Code needs to be installed already; if it isn't, my Claude Code install guide for Ubuntu gets you there in five minutes.
Step 1: Set the environment variables
Add this block to ~/.bashrc, with your real key from the OpenRouter dashboard:
export OPENROUTER_API_KEY="sk-or-v1-YOUR_KEY"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""Then apply it with source ~/.bashrc. Order matters inside that block: OPENROUTER_API_KEY has to be defined before the line that references it, or the auth token expands to an empty string and you get authentication errors that look like a bad key. The cookbook calls this out because it catches people constantly. Blanking ANTHROPIC_API_KEY matters too; the cookbook includes it so a leftover Console key can't muddy the picture once you start debugging auth.
Two more gotchas from the docs. The native installer doesn't read .env files, so this belongs in your shell profile (or in the env block of .claude/settings.local.json for a per-project setup). And on macOS, a previous Anthropic login sits cached in the Keychain under "Claude Code-credentials", which is worth knowing when logout doesn't seem to stick.
Step 2: Log out and verify
If you've ever signed in with an Anthropic account on this machine, clear it first. Start claude, run /logout, then quit and start it again so the new environment takes effect. Now run /status: the auth line should show ANTHROPIC_AUTH_TOKEN as the method. If it still shows your Anthropic account, the variables aren't loaded in the shell that launched the CLI, which on a fresh terminal usually means a typo in ~/.bashrc.
Step 3: Pick models through the gateway
By default the model picker won't know what OpenRouter offers. Setting CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 lets /model discover models through the gateway, and the cookbook lists per-slot overrides like ANTHROPIC_DEFAULT_OPUS_MODEL for pinning specific models to Claude Code's model classes. Start with a strong tool-calling model; the harness leans on structured tool use heavily and weaker models fumble it in ways that read as "Claude Code is broken" when it's really the model.
Claude Code Router for heavier setups
The env-var method is one provider, one key, no logic. claude-code-router (CCR) is the open-source project you graduate to when that stops being enough. It runs a local gateway on 127.0.0.1:3456, your coding agents point at that one stable endpoint and CCR decides what happens behind it: routing rules with conditions, ordered fallback chains when a provider errors, key rotation across credential pools, retries and request logs showing the resolved provider, latency, token usage and estimated cost per request. It speaks to OpenRouter, DeepSeek, Gemini, Moonshot and a long list of other providers, plus custom endpoints.
Install and start CCR
The project now ships a desktop app as the recommended path, but on a server the npm CLI does the same job without Electron. It needs Node.js 22 or newer:
npm install -g @musistudio/claude-code-router
ccr uiThat starts the gateway and a browser-based management UI on http://127.0.0.1:3458 (the gateway itself stays on port 3456). From the UI the flow is: add a provider with its API key under Providers, start the gateway under Server, then open Agent Config, pick Claude Code, select a model and apply the profile. A Docker route exists as well via docker compose up -d --build from the repo. On a remote box I keep the UI bound to localhost and reach it through an SSH tunnel, the same habit I use for any admin panel on a VPS running Claude Code.
One warning about old tutorials: the 3.x line moved configuration into the management UI, so if a guide tells you to hand-edit a JSON config file and run other subcommands, it predates the current design. The CCR documentation site is the reference worth trusting, and it covers the routing rules, client keys with quotas, per-agent profiles and multi-instance setups that don't fit in this article. CCR can also front other agents (Codex, Grok CLI, Kimi CLI, OpenCode among others), which is the quiet killer feature if you run several of them against the same provider accounts.
Switch back to stock Anthropic auth
When you want your subscription back, remove the four export lines from ~/.bashrc, then clear them from the running shell:
unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY OPENROUTER_API_KEYOpen a fresh terminal (this matters, half-cleaned shells cause the weirdest bugs), start claude, run /login and complete the browser OAuth flow. Then /status should show your Anthropic account and plan again. If the CLI keeps hitting the gateway after all that, some other file is still exporting the variables; my Claude Code troubleshooting guide has the checklist for hunting down stray environment config.
My position after months of poking at this: stock Anthropic auth is the right call for most people, most of the time. The subscription pricing is better for interactive work and everything just fits. Routers earn their place in two situations, the polyglot tinkerer who wants five providers' models inside one good harness and the team whose billing already flows through OpenRouter. If that's you, start with the two env vars and only reach for CCR once you catch yourself wanting fallback logic.
