Aviera
2024
How to Use Claude Code with OpenRouter
Use Claude Code with OpenRouter: point ANTHROPIC_BASE_URL at the gateway, blank ANTHROPIC_API_KEY, pick free model IDs, and run /logout to clear cached login.
You still need the agent that edits files and runs the shell. The bill is what you cannot keep. Native tokens run out mid-refactor. Yesterday’s cheap session is expensive again. Something in the login is still pointing at the old slot, even after you thought you moved.
To use Claude Code with OpenRouter, set ANTHROPIC_BASE_URL to https://openrouter.ai/api, put the OpenRouter key in ANTHROPIC_AUTH_TOKEN, and set ANTHROPIC_API_KEY to an empty string so the CLI does not fall back to Anthropic OAuth. Run /logout once if you were logged in before. Confirm with /status that the base URL and auth token source are OpenRouter.
You know the before picture.
You are paying native rates for file edits that a free Llama could have done. Or you are waiting on a rate-limit wall that has nothing to do with how hard the prompt is. You still want Claude Code: the terminal agent that can read the repo, patch files, and run shell. You do not want a second product. You want a different mailbox.
The after picture is quieter, and slightly more annoying to set up.
/status names OpenRouter as the base URL. The OpenRouter key sits in ANTHROPIC_AUTH_TOKEN. The Anthropic key field is blank on purpose. A leftover login is gone. Free IDs still 429. You planned for that.
Commands and config in this guide come from NotebookLM research dated 15 August 2026 (MindStudio dated April 2026; oEmbed check 16 August 2026) plus the OpenRouter Claude Code cookbook, Claude Code settings, model configuration, the Help Center model article, and models, usage, and limits. No live CLI verify on this draft. When a blog disagrees with the cookbook on AUTH_TOKEN versus API_KEY, use the cookbook.
This will not work if you leave a real Anthropic key in ANTHROPIC_API_KEY, skip /logout after an old OAuth session, or pin one :free ID that is already 429ing. It will also not work if a third-party model cannot speak Claude Code’s tool-use JSON and fails quietly while you keep prompting.
This page will not cover curl install as a product, the native /model catalog, session save, Pro versus API billing, or a slash-command directory. Installing the CLI lives on Install Claude Code. Native aliases and Anthropic defaults live on How to change the model in Claude Code. Sessions and /compact live on Claude Code sessions. Seat cost lives on Claude Code Pro pricing. Slash names as a catalog live on Claude Code slash commands.
Claude Desktop is a different product. It uses a Third-Party Inference panel, not these CLI exports. Cursor and VS Code pick models in their own UI; that comparison is Claude Code vs Cursor and Claude Code VS Code, not a second gateway how-to.
Claude Code still edits files and runs shell. OpenRouter is the API address, not a new CLI.
Why route Claude Code through OpenRouter
Keep the Claude Code toolset (file edit, shell). Send the HTTP calls somewhere else.
OpenRouter is a gateway: one API address that forwards requests to many providers. You still type in the same CLI. You still let the agent touch the repo. The invoice and the model catalog change.
Why bother? Native Anthropic tokens and rate limits are the expensive part of an agent that reads the tree on every turn. The cookbook and the threads around it say you can point the client at another API without that being a terms-of-service violation. You give up Anthropic’s native quality guarantees. That trade is the whole point, and it is also the catch.
Ignore OpenRouter’s apps and statistics hub as a how-to. Charts of “what Claude Code users ran this month” do not set your env vars.
If you have ever hit this wall, you already know the motive. You wanted the agent. You did not want to ration Opus for a rename.
Connect Claude Code to OpenRouter (environment config)
You still live in the same house. You still cook in the same kitchen. You still answer the same doorbell. What changed is the mailbox on the street: you filed a forwarding card so letters go to a sorting office that can send them on to whoever is cheapest this week. The kitchen did not move. The address did.
That house is Claude Code. The forwarding card is ANTHROPIC_BASE_URL. The sorting office is OpenRouter. The leftover mail in the old slot is cached Anthropic login, and we will clear it in a later section.
Two blogs will argue about where the key lives. Use Variant A from the cookbook.
Variant A (high confidence, official integration guide):
ANTHROPIC_BASE_URL is the hostname the CLI calls instead of Anthropic. ANTHROPIC_AUTH_TOKEN is the bearer token for that gateway: the OpenRouter key. ANTHROPIC_API_KEY set to an empty string is not optional decoration. It stops the CLI from falling back to Anthropic OAuth.
Variant B (medium confidence, MindStudio, April 2026) puts the OpenRouter key in ANTHROPIC_API_KEY and appends /v1 to the base URL. That is the conflict. Do not average the two recipes. The cookbook columns win.
Use the cookbook columns. The blog variant is the conflict that causes login fallback.
Code With Yousaf walks setup and a first prompt on free models. Watch it for the shape of a working session, then come back and confirm with /status. The video is not a substitute for the three exports.
[EMBED: YouTube - https://www.youtube.com/watch?v=p6tTpW8_buk ]
Obtain an OpenRouter key
Sign up at openrouter.ai. In the dashboard, open Keys and create an API key. Paste that value into ANTHROPIC_AUTH_TOKEN. There is no screenshot of the Keys page in this article on purpose. If a tutorial shows you a dashboard crop, treat it as someone else’s UI, not ours.
Install check only
If the binary is missing, the cookbook install lines are:
Windows PowerShell:
That is a mention, not an install guide. Full install, PATH, and doctor live on Install Claude Code.
Verify
Inside a session, run /status. A slash command is a / instruction in the Claude Code prompt, not a shell binary.
You want Auth token sourced from ANTHROPIC_AUTH_TOKEN and Anthropic base URL https://openrouter.ai/api. If /status still looks like a native Anthropic login, the forwarding card never stuck. Skip ahead to logout and Keychain before you debug model IDs.
What you now have: three exports and a status check. Time invested: about eight minutes if the binary was already there.
Local vs global scoping
A Claude Code default model on this URL is not the Anthropic alias catalog. It is “which gateway and which OpenRouter ID does this folder use.” Native defaults stay on How to change the model in Claude Code.
Project scope: .claude/settings.local.json in the repo. Use it when only this project should talk to OpenRouter.
User or global scope: your shell profile (~/.zshrc and friends) or ~/.claude/settings.json. On Windows the user file is C:\Users\<YourName>\.claude\settings.json.
Anthropic’s settings docs rank precedence as Managed, then Local, then Project, then User. Managed is org policy. Local .claude/settings.local.json is the usual project pin. A user file or a zshrc export applies everywhere you open a terminal.
Confirm the winner with /status. If you exported in one tab and launched claude from another that never sourced the profile, you will swear the docs are wrong.
Project file wins for one repo. Shell profile or user settings apply everywhere. Confirm the winner with /status.
Local .claude/settings.local.json is the usual project pin. User files and zshrc are global.
The three exports take a minute. The leftover Anthropic login is the entire afternoon.
Clear cached Anthropic login
Here is the honest version.
You set the gateway. You still get “model not found.” You assume the ID is wrong. Often the ID is fine. The CLI is still holding an Anthropic OAuth session from last month.
Run /logout once to drop the cached session. The cookbook treats this as required if you were previously logged in with an Anthropic account.
Blank ANTHROPIC_API_KEY is still required after logout. Logout does not invent the empty string for you.
On macOS, native installs may not keep a simple JSON login file. Sources point at Keychain. Delete the generic password named Claude Code-credentials:
That is a leftover mailbox, not a settings.json you can grep.
/logout drops the cached session. The blank API key is still required. Keychain is the macOS leftover.
I tried this the sloppy way first: exports only, no logout. /status still looked native. The model picker lied. That is the failure tutorials skip because it is not a pretty env block.
Pick OpenRouter model IDs (and a gateway default)
OpenRouter IDs use provider/model-name:free. Example from sources:
--model sets the first turn. /model <alias|name> switches later. Pass OpenRouter IDs here, not a rewrite of Anthropic’s native picker. Alt+P and the Anthropic alias list stay on How to change the model in Claude Code.
Optional: turn on the gateway picker with CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1. The picker is a curated set of high-ranked models, not the full OpenRouter catalog. If the ID you want is missing, type it.
If sources apply to your org check, CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1 is the fast-mode override in the ledger.
Deprecated name to stop copying: ANTHROPIC_SMALL_FAST_MODEL was replaced by ANTHROPIC_DEFAULT_HAIKU_MODEL. Do not paste the old key from a 2025 gist.
Version floors matter when you chase newer Anthropic families through any path, gateway included. Opus 5 needs Claude Code v2.1.219 or later. Sonnet 5 needs v2.1.197 or later. Fable 5 needs v2.1.170 or later. Blogs still saying 3.5 or Opus 4.8 are stale on names. Run claude update before you blame OpenRouter.
Opus 5 needs v2.1.219 or later. Sonnet 5 needs v2.1.197. Fable 5 needs v2.1.170.
Pin a :free ID when you need one model. Use openrouter/free when 429s start rotating you off a single ID.
openrouter/free is the failover ID. It auto-selects from available free models instead of pinning one name that is already hot. We will put numbers on the ceiling in the next section.
Free-tier limits and the Free Models Router
Free is not unlimited. Typical free-tier ceilings in sources are 20 requests per minute and 200 requests per day per model. Hit them and you get a 429: HTTP speak for “too many requests, wait or switch.”
Your moves: wait, switch to another :free ID, use openrouter/free so the gateway rotates, or add credit. Daniel Barczak’s walkthrough (medium freshness) says about 10 dollars of credit can lift you into a higher rate-limit tier while you still call free models. We do not have sourced paid rpm numbers to print. Do not invent them.
Bart Slodyczka’s video is titled like a guarantee. Watch it for the Free Models Router. Treat “unlimited” as the title, not our promise.
Free IDs still 429. Wait, switch IDs, use openrouter/free, or add about 10 dollars of credit for a higher rpm tier.
[EMBED: YouTube - https://www.youtube.com/watch?v=p4KD56w2kpc ]
But here is the thing.
The forwarding card can be perfect and the sorting office can still be slammed. You wanted the kitchen to keep cooking. The 429 is not a misconfigured BASE_URL. It is shared free capacity. Pinning one celebrity free ID is how you learn that the hard way.
Model tier strategy: which free model for which job
MindStudio splits the free bench this way: Llama 3.3 70B for writing new code; DeepSeek R1 for reasoning-heavy debug. Those models can cover a lot of day-to-day coding and still lag Opus on huge codebases and security-sensitive work. Do not copy “free is more than enough” as a fact. Pair it with the silent tool-use warning later.
Native “which Claude model is best for coding” stays on How to change the model in Claude Code. Flagship Anthropic numbers live on Claude Opus 5 Benchmarks. Here the split is which free OpenRouter ID for which job, knowing quality is not Opus.
Greg’s video is about default-model waste: expensive planning versus cheaper execution. He shows a cost gap in-session (sources describe a 25-cent Opus 4 run versus a 5-cent Sonnet 4 run). Watch it for the hybrid instinct. Do not treat those two figures as OpenRouter prices.
[EMBED: YouTube - https://www.youtube.com/watch?v=eP9fA5MHG20 ]
That is one sourced startup. DeepSeek R1 stays a prose pick for debug, not a fake scoreboard.
Switch models mid-session on the gateway
People searching claude code change model on this page want OpenRouter IDs, not a second Anthropic tutorial.
/model <alias|name> and claude --model … both work with gateway IDs. The next response re-reads history without cached context. That is the Reddit/NLM note: you keep the transcript, you pay to read it again.
If you need memory that survives a model hop, keep it in files. Some developers use a docs-md folder of .md notes and feed those into a fresh session. Session save, /clear, and /compact as a product live on Claude Code sessions.
/clear wipes the conversation. /compact summarizes when you are mid-task and need to keep going. Anthropic’s help center calls those the strongest levers for quality and cost. They still help when the tokens are OpenRouter’s.
Keep the hop on this page. Keep the session machinery on that one.
Hybrid orchestration: main thread vs subagents
A subagent is a worker instance you send a job to so the main thread does not drown. Isolation docs live on Sequential thinking in Claude Code.
On the gateway, CLAUDE_CODE_SUBAGENT_MODEL lets workers sit on a cheaper or free OpenRouter ID while the parent stays on a stronger one. The ledger’s example shape is an export:
Point that variable at an OpenRouter ID when you want workers off the parent’s bill. Do not treat the example string as the only legal value.
opusplan is the alias that plans on Opus and executes on Sonnet. Name it, then leave it. Plan Mode as a product lives on Claude Code Plan Mode.
Advisor-executor (expensive plan, cheaper build) is a full pattern of its own. Do not run the whole session on the flagship. Details live on Advisor-Executor Orchestration.
Do agentic features work through OpenRouter? Shell and file tools work when the model speaks a compatible API. Extended thinking may not. Quality follows the model, not the gateway brand.
Workers can sit on a cheaper OpenRouter ID. Isolation lives with sequential thinking. Plan Mode depth lives on the Plan Mode guide.
Thinking blocks and Anthropic Skin
OpenRouter’s Anthropic Skin is a gateway feature: it can pass Thinking blocks and native tool use so the CLI still sees reasoning the way Anthropic-shaped traffic expects. Compatibility is not guaranteed for every third-party ID.
Sources name DeepSeek R1 and meituan/longcat-flash as models that can render reasoning chains. That is not a matrix. If a model is not in the sources, do not invent a pass/fail cell for it.
ultrathink is a body trigger for one-off deep reasoning without changing the session’s effort settings. Use it when you want a single hard look, not a new default.
The honest limit: non-Anthropic models may fail Claude Code’s tool-use JSON schemas silently. The agent looks busy. The file never changes. You will blame the prompt. Check Skin and schema mismatch before you add another paragraph of instructions.
Skin is a gateway feature, not a promise for every third-party ID. Do not treat this graphic as a compatibility matrix.
Confused? Fair enough. Skin is the stamp that says “this still looks like Anthropic on the wire.” Silence is the mute bell when the worker cannot fill the tool form. The diagram is two stamps. The CLI is not in the picture on purpose.
Cost observability
/cost shows session spend in Anthropic’s help-center sense: tokens and dollars for the current conversation when you are on pay-as-you-go. OpenRouter credit burn is a different meter. The cookbook’s job for that is a statusLine.
A status line is a small command the CLI runs to print extra status in the terminal chrome. The cookbook shape is:
Confidence on the script path is medium. The cookbook expects an external script. Do not invent the script body here. Point at the cookbook statusline section and fill in a real path on your machine.
/clear and /compact remain cost and quality levers even on a gateway. Depth of when to save a session is Claude Code sessions. Pay-as-you-go versus a subscription seat is Claude Code Pro pricing. Do not rerun that billing FAQ on this page.
If you sign in with an API key (Console, OpenRouter, or Bedrock), sources meter you pay-as-you-go per token with no hard stop of the subscription kind. That is why a statusline matters once you leave pure free IDs.
When a local Claude Code Router is worth it
musistudio/claude-code-router is a local control plane. It sits on port :3456 between agents and providers. People use it for key rotation, credential pools, and request logging. It is extra. It is not required for the three-export OpenRouter path.
If you only needed a cheaper mailbox, stop at env vars. If you are running multiple agents and you want one box that sees every hop, CCR is the optional crate in the middle.
Full setup is its own guide: Claude Code Router Setup. Do not paste a second install stack here.
Claude Desktop still uses a Third-Party Inference panel. Different product. Different clicks.
CCR is extra local control, not required for the env-var OpenRouter path. Full setup is a separate guide.
Troubleshooting
Start with the symptom, not a new blog.
Model not found after you connected: /logout, blank ANTHROPIC_API_KEY, then Keychain on macOS. Recheck /status for ANTHROPIC_AUTH_TOKEN and https://openrouter.ai/api.
429: wait, switch :free ID, use openrouter/free, or add about 10 dollars of credit for a higher rpm tier (Barczak / NLM, medium freshness). This is not Anthropic’s subscription reset. Native rate-limit errors live on Claude Code rate limits.
Silent tool-use: Skin / schema mismatch. Try a model sources already associate with tool calls. Stop adding adjectives to the prompt.
Whitespace in URLs: Zack Reed documents local LM Studio models injecting spaces into long fetch strings. Adjacent failure. Not this OpenRouter install path. If you are on cloud OpenRouter IDs, look at 429 and logout first.
permissions.deny replaces the deprecated ignorePatterns config. If an old gist still says ignorePatterns, update the key.
Model-not-found is usually leftover OAuth. 429 is free-tier. Whitespace-in-URL is the local LM Studio adjacent bug, not this install path.
Slash command names you already met (/status, /logout, /model, /cost, /clear, /compact) are enough for this job. A full catalog lives on Claude Code slash commands.
FAQ
Why use OpenRouter with Claude Code?
You keep Claude Code’s file and shell tools while HTTP goes through a gateway that can serve free and third-party models. The motive in sources is native token cost and rate limits, not a second CLI. You lose Anthropic’s native quality guarantees when you leave first-party models.
Is it against Anthropic's terms of service to route Claude Code through OpenRouter?
Sources say pointing the client at another API is not a terms violation. You are changing the endpoint, not cracking the binary. You still give up Claude-specific capabilities that only native models guarantee.
Does OpenRouter work with Claude Code's agentic features?
Autonomous multi-step work (shell, file read and edit) can function because the API shape is compatible. Quality depends on the model. Extended thinking may not work. Silent tool-use failures are the failure mode, not a loud error every time.
Can I use free models on OpenRouter with Claude Code?
Yes. Set the cookbook env vars, then pass a :free ID such as meta-llama/llama-3.3-70b-instruct:free, or use openrouter/free to auto-select from available free models. Free still 429s. See the limits section.
Why am I getting "model not found" errors after connecting to OpenRouter?
Usually a cached Anthropic OAuth session fighting the gateway credentials. Run /logout once, keep ANTHROPIC_API_KEY as an empty string, and on macOS delete the Claude Code-credentials Keychain item if the native install stored one.
What happens when I exceed OpenRouter's free tier limits?
Requests fail with 429 once you hit the typical ceiling of 20 requests per minute (and 200 per day per model in sources). Wait, switch free IDs, use openrouter/free, or add a small credit balance for paid rate limits that are still cheaper than direct Anthropic in the blogs. We do not print invented paid rpm figures.
Which free model on OpenRouter is closest to Claude in coding quality?
Llama 3.3 70B is the strongest free option in sources for writing new code. DeepSeek R1 is the pick for reasoning-heavy debug. They can cover a large share of day-to-day work and still fall short of Opus on massive codebases and security-sensitive tasks. Native “best Claude for coding” stays on the change-model guide.
How do I get higher rate limits for free models on OpenRouter?
Putting about 10 dollars of credit into the OpenRouter account can lift you into a higher rate-limit tier even if you keep calling free models (Daniel Barczak / NLM, medium freshness). The balance can sit unspent while free IDs stop choking mid-task. It is not a forever-unlimited plan.
How do I change OpenRouter models while keeping project context?
/model mid-session keeps the conversation history; the next response re-reads it without cached context. For memory that survives a hop, keep notes in .md files (a docs-md folder shows up in Reddit/NLM). Native Anthropic switching depth is How to change the model in Claude Code. Session save is Claude Code sessions.
Whether this stays the cheap default for agentic work is still moving. Gateways add models. Free IDs rot under traffic. Skin coverage will not be even. Watch /status more than you watch a YouTube title that says unlimited.
If you try one thing this week, do the three cookbook exports, run /logout once, then /status. If Auth token is not ANTHROPIC_AUTH_TOKEN and the base URL is not OpenRouter, stop adding model IDs. Fix the mailbox first. For the native picker after that, the next guide is How to change the model in Claude Code. If you want Plan Mode instead of a cheaper ID, start at Claude Code Plan Mode. Subscribe if you want the next guide in this series before it hits search.
Until then...
Sage
PS. The credentials that wreck a setup are often not in the repo. They sit in a system password drawer next to Wi-Fi secrets, invisible to a project search. If the in-session logout did nothing, that is the drawer to open.
Medium SEO settings (paste into Medium Story settings)
Do not publish this block in the article body. Use for Medium SEO Settings + Story preview only. No em-dashes in these fields.
Story title
Story subtitle (preview dek, under 140)
SEO Title (keep primary; Medium suffix under 60 if possible)
SEO Description (158 chars)
Topics (up to 5; only if Medium autocompletes)
Artificial Intelligence
Programming
Software Development
Claude AI (or Claude)
Productivity
Keyword intent covered: primary claude code with openrouter; soft-overlap secondaries claude code change model and claude code default model (C12 owns native depth); editorial OpenRouter env/ID/limit phrases; 9 filler FAQs.
