文档 · 供应商

OpenRouter 接入 Claude Code、Codex、Gemini CLI 和 OpenCode

OpenRouter 用一个 Key 卖许多厂商的模型，提供 OpenAI Chat Completions 和 Anthropic Messages 两种接口。把 Key 添加到 magpie 一次，Claude Code、Codex、Gemini CLI、OpenCode 以及你接入的其他工具，都能通过 magpie 的本地网关 127.0.0.1:3425 使用任意 OpenRouter 模型，每个工具各用各的模型。

添加 OpenRouter

1. 拿到 Key在 openrouter.ai/keys 创建。
2. 添加供应商在 magpie 的 供应商 页点 ＋ 添加供应商，选 OpenRouter，粘贴 Key 并保存。magpie 会向 OpenRouter 查询它提供哪些模型。
3. 给工具选上在 Agent 页点工具那一行的模型，选一个 OpenRouter 模型，比如 anthropic/claude-opus-5.5。

magpie provider add openrouter sk-…
magpie provider test openrouter

magpie 里的模型 id 是 供应商/模型，所以 OpenRouter 的模型写作 openrouter/anthropic/claude-opus-5.5：前面是供应商，后面是 OpenRouter 自己的 id。Key 保存在 magpie 的设置里，magpie 不会从 shell 里读取它。

OpenRouter 文档里有两个可选请求头，HTTP-Referer 和 X-OpenRouter-Title，用来在它的排行榜里署上应用的名字。magpie 默认不发送；想让请求计入某个应用，可以在供应商编辑页的 请求头 里加上。

接口地址

magpie 不使用 OpenRouter 的 Responses 接口。Codex 这类说 Responses 的工具，会被转换成上面两种之一。

模型列表

• 列表从哪来。magpie 从 https://openrouter.ai/api/v1/models 拉取列表，里面有每个模型的上下文长度。模型名、推理档位和价格来自 models.dev 上的 openrouter 目录。
• 工具能看到哪些模型。OpenRouter 列出的模型有几百个。你没挑选时，magpie 给工具展示 OpenRouter 列表里的前 24 个（它按从新到旧排）。其余的可以在供应商的模型列表里勾选，也可以打开 每系最新，每个系列只留最新的一个。
• 新模型。auto-include 规则会立刻加入匹配的模型，以后拉取列表时新出现的匹配模型也会自动加入；refresh-every 让 magpie 定期自己重新拉取列表。
• 图像模型。OpenRouter 的 /models 只列文本模型，所以 magpie 从 /api/v1/images/models 读取 FLUX、Seedream、Riverflow、Recraft、GPT Image 等图像模型。在 设置 → 模型 → 图像 里选用。
• 决策模型。OpenRouter 的决策模型（liquid/d1、cloudflare/clef、~typesafe/jev-latest……）也会列出来，路由分组可以用同一个 Key 给每一轮做分类。

magpie provider models openrouter +anthropic/claude-opus-5.5   # 多展示一个
magpie provider models openrouter best                          # 每个系列只留最新
magpie provider auto-include openrouter '*:free'               # 所有免费模型，包括以后新上的
magpie provider refresh-every openrouter 1d

在各个工具里用

在 Agent 页点工具那一行选模型，或者在终端里切换。每篇指南都写了 magpie 会改工具配置里的哪些内容，以及怎么切回去。

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 说的是 Anthropic Messages，OpenRouter 在 https://openrouter.ai/api 也说这种协议，所以请求原样转过去。Claude Code 接入其他模型。
• Codex 只说 OpenAI Responses。magpie 会转换请求和回复，流式输出和工具调用都保留：Claude 模型发到 OpenRouter 的 Anthropic 接口，其他模型发到 Chat Completions。Codex 接入其他模型。
• Gemini CLI 说 Gemini 的 API，magpie 按和 Codex 一样的方式转换。Gemini CLI 接入其他模型。
• OpenCode 说 Chat Completions，请求原样发给 OpenRouter；Claude 模型例外，magpie 会改发到 Anthropic 接口，为的是提示缓存（见下文）。OpenCode 接入其他模型。

如果 OpenRouter 说某个模型在 magpie 选的接口上不提供，magpie 会按另一个接口重新构造请求，并记住这个模型该走哪边。

推理

• 必须推理的模型。OpenRouter 上有些模型不允许关闭推理（“reasoning is mandatory for this endpoint and cannot be disabled”）。工具要求关闭时，magpie 会去掉这个设置再问一次，推理档位交给模型自己决定。Chat Completions 和 Messages 都是这样处理。
• 对话中途的推理强度。Claude Code 会在对话里带上每一轮的推理强度。OpenRouter 的 Anthropic 接口在 DeepSeek、GLM 等模型上会拒绝它。magpie 会立刻去掉它再问一次，并且在 magpie 重启前不再把它发给 OpenRouter。
• 之前的思考内容。OpenRouter 的 Anthropic 接口会拒绝没有签名的思考块，所以 magpie 总会带上签名。在 Chat Completions 上，工具传回的 OpenRouter reasoning 或 reasoning_details 字段会被当作模型之前的思考来读。

缓存、费用与余额

• Claude 的提示缓存。同时提供两种接口的中转，在 Chat Completions 上会丢掉 cache_control，每一轮都按未缓存计费。所以不管哪个工具，magpie 都把 Claude 模型的请求发到 OpenRouter 的 Messages 接口，带上转换时加的缓存断点。
• 缓存 token。magpie 从每个回复里读取缓存读取量和 OpenRouter 的 cache_write_tokens，用量 页会把缓存命中和缓存写入单独统计。
• 费用。用量页按 models.dev 上 OpenRouter 的价格给每次调用计价；目录里没有的，按模型厂商的官方价格算。标价为 0 美元的模型，比如以 :free 结尾的，在 magpie 的模型选择器里会标上 免费。
• 是哪家回答的。OpenRouter 会说明每个回复由哪家服务商提供。magpie 会记下来，用量页里调用详情的 上游 就是它。
• 余额。OpenRouter 那一行会以美元显示账号的剩余额度，即总充值减去总用量，读自 /api/v1/credits。这是整个账号的数字，同一账号下的每个 Key 显示的都一样。

多个 Key 与免费模型

一个 OpenRouter 供应商可以放多个 Key：在它下面点 添加另一个密钥，也可以一次粘贴好几个。请求先走第一个开着的 Key，它用完或被限流时由下一个接替。也可以把供应商的路由方式改成轮流、按权重或用完一个再换下一个。再次添加这个预设会多出一个 OpenRouter 供应商；想把请求分摊到多个 Key，就把它们都放进同一个供应商里。

• 花费上限。spend-cap 给某个 Key 设一个每天、每月或总计的美元上限，按用量页的计价算；到了上限，路由就转去其他 Key 和备用模型。
• 备用模型。fallback 指定 OpenRouter 额度用完或挂掉时请求去哪：另一个供应商的模型，或一个路由分组。
• 免费模型。OpenRouter 的免费模型每分钟只接受 20 个请求。rpm 给每个 Key 限速：超出的请求排队等空位，最多等 2 分钟，再等不到就返回带 Retry-After 的 429。
• 免费模型的 429。如果免费模型是被背后服务商的共享池拒绝的，magpie 只让这一个模型暂停，其他免费模型照常使用。免费模型的其他 429 是 OpenRouter 整个账号的免费额度到了，这时 Key 会暂停。
• 免费模型池。路由分组可以用 openrouter/*:free 这个模式包含 OpenRouter 列出的所有免费模型，现在的和以后新上的都算。

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

常见报错

• 模型列表里全是 anthropic/ 开头的 id，或者拉不下来。只填了 https://openrouter.ai/api 的供应商，拿到的是 OpenRouter 挂在 anthropic/ 下的目录，那些 id 它并不提供。给它加上 Chat Completions 地址 https://openrouter.ai/api/v1，或者直接用 OpenRouter 预设，两个地址都有。
• “Mid-conversation reasoning effort (configuration_update) is not supported”。这是 OpenRouter 在 DeepSeek、GLM 等模型上拒绝 Claude Code 每轮推理强度时的报错。magpie 会立刻去掉推理强度再问一次，工具照样拿到回复，并且在 magpie 重启前不再把它发给 OpenRouter。
• 402，提示 “can only afford” 或 “fewer max_tokens”。OpenRouter 拒绝的是这次请求的大小或进行中请求的预算，不是余额用完了。magpie 让这个 Key 暂停半小时后再试；和真正没余额的 Key 不同，它的暂停时间不会越拒越长。
• 联网搜索会不会用到没选的模型？不会。由 OpenRouter 回答 magpie 的联网搜索时，magpie 只用你选过的 OpenRouter 模型，因为 OpenRouter 可能因为地区拒绝别的模型。搜索时 magpie 会打开 OpenRouter 自己的 web 插件，它的任何模型都能用。
• 检查 Key。magpie provider test openrouter 会向每个接口发一个很小的请求，或者发给你指定的每个模型。加上 --as codex 或 --as claude-code，就按那个工具的方式发送。

常见问题

Claude Code 怎么用 OpenRouter？

在 magpie 里添加 OpenRouter 的 Key（供应商页，添加供应商，选 OpenRouter），然后在 Claude Code 那一行选一个模型，比如 anthropic/claude-opus-5.5，或者运行 magpie claude openrouter/anthropic/claude-opus-5.5。magpie 会写好 Claude Code 的 settings.json，请求原样转给 OpenRouter 的 Anthropic 接口。

Codex 能用 OpenRouter 的模型吗？

能。Codex 只说 Responses API，而 magpie 不走 OpenRouter 的 Responses 接口，所以会转换每个请求：Claude 模型发到 OpenRouter 的 Anthropic 接口，其他模型发到 Chat Completions，回复再转回 Responses 交给 Codex。

Gemini CLI 和 OpenCode 能用 OpenRouter 吗？

能。Gemini CLI 的请求和 Codex 一样做转换。OpenCode 说 Chat Completions，请求原样发给 OpenRouter；只有 Claude 模型例外，magpie 会改发到 Anthropic 接口，好让提示缓存生效。

怎么只用 OpenRouter 的免费模型？

用 openrouter/*:free 这个模式建一个路由分组，比如 magpie group add my-free-pool models='openrouter/*:free' routing=order。它会包含 OpenRouter 列出的所有免费模型，以后新上的也算。标价为 0 美元的模型在 magpie 的模型选择器里会标上 免费。

OpenRouter 的免费模型为什么返回 429？

OpenRouter 的免费模型每分钟只接受 20 个请求。运行 magpie provider rpm openrouter 20，magpie 就会把请求压在这个速度以内。如果 429 来自某个免费模型背后服务商的共享池，magpie 只让这个模型暂停，其他免费模型照常使用。

magpie 能显示 OpenRouter 的余额吗？

能。magpie 读取 OpenRouter 的 credits 接口，以美元显示剩余额度，也就是总充值减去总用量。这是整个账号的数字，同一账号下的每个 Key 显示的都一样。

为什么 magpie 从 /api/v1 拉取 OpenRouter 的模型列表？

在 Anthropic 地址上拉列表，OpenRouter 返回的是挂在 anthropic/ 前缀下的目录，里面的 id 它并不提供服务。magpie 从 Chat Completions 地址 https://openrouter.ai/api/v1 拉列表；只填了 OpenRouter Anthropic 地址的供应商，会提示你补上这个 Chat 地址。

按供应商：DeepSeek · Kimi 与 Kimi Code · GLM 编程套餐 · 通义千问 · MiniMax · Gemini · Grok · Mistral · GitHub Copilot · Ollama

各个工具的指南：Claude Code 接入其他模型、Codex 接入其他模型、Gemini CLI 接入其他模型、OpenCode 接入其他模型。遇到问题可以在 Discord 提问。