Docs · Provider

OpenRouter in Claude Code, Codex, Gemini CLI and OpenCode

OpenRouter sells many vendors’ models behind one key and serves them on OpenAI Chat Completions and Anthropic Messages. Add the key to magpie once, and Claude Code, Codex, Gemini CLI, OpenCode and every other agent you connect can use any OpenRouter model through magpie’s gateway at 127.0.0.1:3425, each agent on a model of its own.

Add OpenRouter

1. Get a keyMake one on openrouter.ai/keys.
2. Add the providerIn magpie’s Providers tab, press ＋ Add provider, pick OpenRouter, paste the key and save. magpie asks OpenRouter which models it serves.
3. Pick it for an agentIn the Agents tab, click the model on the agent’s row and choose an OpenRouter model such as anthropic/claude-opus-5.5.

magpie provider add openrouter sk-…
magpie provider test openrouter

Model ids in magpie are provider/model, so OpenRouter’s read openrouter/anthropic/claude-opus-5.5: the provider, then OpenRouter’s own id. The key is kept in magpie’s settings; magpie doesn’t take it from your shell.

OpenRouter documents two optional headers that credit an app in its rankings, HTTP-Referer and X-OpenRouter-Title. magpie doesn’t send them. The provider editor’s Headers field offers them if you want your requests credited.

Endpoints

magpie doesn’t use OpenRouter’s Responses API. An agent that speaks Responses, such as Codex, is translated to one of the two above.

Model list

• Where it comes from. magpie fetches the list from https://openrouter.ai/api/v1/models, which gives each model’s context length. Names, reasoning levels and prices come from the openrouter catalog on models.dev.
• Which models agents see. OpenRouter lists hundreds. Unless you pick some, magpie shows agents the first 24 OpenRouter lists, newest first. Pick the rest in the provider’s model list, or turn on Best in family to keep only the newest of each family.
• New models. auto-include rules expose matching models now and each one a later fetch lists for the first time, and refresh-every has magpie fetch the list again by itself.
• Image models. OpenRouter’s /models lists text models only, so magpie reads image models such as FLUX, Seedream, Riverflow, Recraft and GPT Image from /api/v1/images/models. Choose one in Settings → Models → Images.
• Decision models. OpenRouter’s decision models (liquid/d1, cloudflare/clef, ~typesafe/jev-latest…) are listed too, so a routing group can classify turns with the same key.

magpie provider models openrouter +anthropic/claude-opus-5.5   # expose one more
magpie provider models openrouter best                          # newest of each family
magpie provider auto-include openrouter '*:free'               # every free model, now and later
magpie provider refresh-every openrouter 1d

In each agent

Pick the model on an agent’s row in the Agents tab, or from a terminal. Each guide says what magpie writes in that agent’s config and how to switch back.

magpie claude openrouter/anthropic/claude-opus-5.5
magpie codex openrouter/anthropic/claude-opus-5.5
magpie gemini model openrouter/google/gemini-3-pro
magpie opencode openrouter/anthropic/claude-opus-5.5

• Claude Code speaks Anthropic Messages, and so does OpenRouter at https://openrouter.ai/api, so its requests are passed on as they are. Models in Claude Code.
• Codex speaks only OpenAI Responses. magpie translates each request and the reply, streaming and tool calls included: a Claude model goes to OpenRouter’s Anthropic endpoint, every other model to Chat Completions. Models in Codex.
• Gemini CLI speaks Gemini’s API. magpie translates it the same way as Codex’s requests. Models in Gemini CLI.
• OpenCode speaks Chat Completions, so its requests go to OpenRouter as they are, except for Claude models, which magpie sends to the Anthropic endpoint for their prompt cache (see below). Models in OpenCode.

If OpenRouter says a model isn’t served on the endpoint magpie chose, magpie builds the request again for the other one and remembers that for the model.

Reasoning

• Models that always reason. Some OpenRouter models refuse to have reasoning turned off (“reasoning is mandatory for this endpoint and cannot be disabled”). When an agent asks for it off, magpie asks again with the level left to the model, on Chat Completions and on Messages alike.
• Effort mid-conversation. Claude Code sends a turn’s effort inside the conversation. OpenRouter’s Anthropic endpoint refuses that on some models, such as DeepSeek and GLM. magpie asks again at once without it, and doesn’t send it to OpenRouter again until magpie restarts.
• Earlier thinking. OpenRouter’s Anthropic endpoint turns away a thinking block without a signature, so magpie always sends one. On Chat Completions, earlier reasoning that an agent sends back in OpenRouter’s reasoning or reasoning_details fields is read as the model’s thinking.

Cache, cost and credits

• Claude’s prompt cache. On Chat Completions, a relay that serves both APIs drops cache_control, and every turn is billed uncached. So magpie asks Claude models on OpenRouter’s Messages endpoint, from any agent, with the cache breakpoints the translation adds.
• Cache tokens. magpie reads cache reads and OpenRouter’s cache_write_tokens from each reply, so the Usage tab counts cache hits and writes apart from the rest.
• Cost. The Usage tab prices each call with OpenRouter’s prices from models.dev, or the model maker’s list price when the catalog has none. A model listed at $0, such as one ending in :free, shows free beside it in magpie’s pickers.
• Which provider answered. OpenRouter names the provider that served each reply. magpie keeps it, and the call’s details in the Usage tab show it as Upstream provider.
• Credits. The OpenRouter row shows what is left on the account, in dollars: total credits less total usage, read from /api/v1/credits. It’s the whole account’s figure, so each key of one account shows the same.

Several keys and free models

One OpenRouter provider can hold several keys: press Add another key under it, or paste several at once. Requests go to the first key that’s on, and when it runs out or is rate limited the next one takes over. The provider’s routing can also rotate, weight or drain them instead. Adding the preset again makes a second OpenRouter provider; to spread requests over several keys, add them all to the one provider.

• Spend caps. spend-cap stops a key at a dollar amount a day, a month or in all, as the Usage tab prices its calls; routing then goes on to the other keys and the fallbacks.
• Fallbacks. fallback names where requests go when OpenRouter is out of quota or down: another provider’s model or a routing group.
• Free models. OpenRouter’s free models take 20 requests a minute. rpm holds each key to a rate: one request more waits for room, up to 2 minutes, then gets a 429 with a Retry-After.
• Free-model 429s. When a free model is refused by the shared pool of the provider serving it, magpie rests that model only and keeps the other free models in use. Any other 429 on a free model is OpenRouter’s account-wide free limit, and the key rests.
• A pool of free models. A routing group can take every free model OpenRouter lists with the pattern openrouter/*:free, today’s and those it lists later.

magpie provider rpm openrouter 20
magpie provider spend-cap openrouter <key> 20 month
magpie provider fallback openrouter deepseek/deepseek-v4-pro
magpie group add my-free-pool models='openrouter/*:free' routing=order
magpie group set opus-anywhere stays=session models+=openrouter/anthropic/claude-opus-5.5

Troubleshooting

• The model list has only anthropic/ ids, or fails to load. A provider given only https://openrouter.ai/api gets OpenRouter’s catalog under anthropic/ names it doesn’t serve. Give it the Chat Completions base, https://openrouter.ai/api/v1, or use the OpenRouter preset, which has both.
• “Mid-conversation reasoning effort (configuration_update) is not supported”. OpenRouter says this about Claude Code’s per-turn effort on models such as DeepSeek and GLM. magpie asks again at once without the effort, so the agent gets its answer, and stops sending it to OpenRouter until magpie restarts.
• 402 with “can only afford” or “fewer max_tokens”. OpenRouter refused the request’s size or its in-flight budget, not because the balance is spent. magpie rests the key for half an hour and tries it again then; unlike a key out of credit, its rest doesn’t grow with each refusal.
• Web search asks a model you didn’t pick. It doesn’t: when OpenRouter answers magpie’s web search, magpie asks one of the OpenRouter models you have picked, since OpenRouter can refuse others for your region. For that search magpie turns on OpenRouter’s own web plugin, which works with any of its models.
• Checking a key. magpie provider test openrouter sends a tiny request through each endpoint, or to each model you name. Add --as codex or --as claude-code to send it the way that agent would.

FAQ

How do I use OpenRouter in Claude Code?

Add your OpenRouter key in magpie (Providers, Add provider, OpenRouter), then pick a model such as anthropic/claude-opus-5.5 on Claude Code’s row, or run magpie claude openrouter/anthropic/claude-opus-5.5. magpie writes Claude Code’s settings.json and passes its requests on to OpenRouter’s Anthropic endpoint as they are.

Can Codex use OpenRouter models?

Yes. Codex speaks only the Responses API, which magpie doesn’t use at OpenRouter. magpie translates each Codex request: a Claude model goes to OpenRouter’s Anthropic endpoint and every other model to Chat Completions, and the reply comes back to Codex as Responses.

Can Gemini CLI and OpenCode use OpenRouter?

Yes. Gemini CLI’s requests are translated the same way as Codex’s. OpenCode speaks Chat Completions, so its requests go to OpenRouter as they are, except for Claude models, which magpie sends to the Anthropic endpoint so the prompt cache works.

How do I use only OpenRouter’s free models?

Make a routing group from the pattern openrouter/*:free, for example magpie group add my-free-pool models='openrouter/*:free' routing=order. It takes every free model OpenRouter lists, including ones it lists later. Models priced at $0 show free in magpie’s pickers.

Why do OpenRouter’s free models answer 429?

OpenRouter’s free models take 20 requests a minute. Set magpie provider rpm openrouter 20 and magpie holds requests back to that rate. When the 429 comes from the shared pool of the provider serving one free model, magpie rests only that model and keeps the other free models in use.

Does magpie show my OpenRouter credits?

Yes. magpie reads OpenRouter’s credits endpoint and shows what is left in dollars: total credits less total usage. The figure is for the whole account, so every key of one account shows the same.

Why does magpie fetch OpenRouter’s model list from /api/v1?

Asked at the Anthropic base, OpenRouter answers with its catalog under anthropic/ names it doesn’t serve. magpie fetches the list from the Chat Completions base, https://openrouter.ai/api/v1, and a provider given only OpenRouter’s Anthropic base is told to add that Chat base.

By provider: DeepSeek · Kimi and Kimi Code · GLM Coding Plan · Qwen · MiniMax · Gemini · Grok · Mistral · GitHub Copilot · Ollama

Every agent: Models in Claude Code, Models in Codex, Models in Gemini CLI, Models in OpenCode. Ask on Discord if you get stuck.