在 Claude Code 里用 OpenRouter：官方 cookbook 给的接法与它的边界

2026-08-18

想把 Claude Code 的请求转到 OpenRouter 上去，网上能搜到的说法很多，但真正有依据的只有两份东西：OpenRouter 官方文档里那篇《Claude Code》cookbook（openrouter.ai/docs/cookbook/coding-agents/claude-code-integration），以及 Claude Code 官方文档里讲通用 LLM 网关的两页（code.claude.com/docs/en/llm-gateway-connect 和 code.claude.com/docs/en/llm-gateway）。

两份文档描述的是同一件事的两端，立场不同：OpenRouter 那篇是「几分钟跑起来」的快速上手，Claude Code 那两页是「你们组织自己运维一个网关」的通用说明。放在一起看，能对上的地方对得很齐，对不上的地方也很具体。

先看两边各自把边界划在哪

这是本文最该先说的一段，因为它决定了后面所有配置值不值得做。

OpenRouter 那篇 cookbook 开头就有一条 Warning，写明 Claude Code 配合 OpenRouter 只保证与 Anthropic 一方（first-party）供应商正常工作，并建议把 Anthropic 1P 设成优先级最高的 provider。文中另一处也重复了同一个意思：Claude Code 是针对 Anthropic 模型优化的，配其它供应商可能不能正确工作。

Claude Code 侧的《Other LLM gateways》页，从另一个方向划了同一条线：Anthropic 不背书、不维护、也不审计第三方网关产品，并且不支持通过任何网关把 Claude Code 路由到非 Claude 模型。

两边措辞不同，落点是一个：两份文档承诺的范围都只到「换一个计费与管控入口」，没有到「换一个模型」。如果你接 OpenRouter 的动机是想在 Claude Code 里跑别家模型，两边文档都没有给你承诺。这个判断放在最前面，能省掉后面一堆折腾。

第一处口径差：Windows 用户会在第二步卡住

OpenRouter 的 cookbook 一共五步：装 Claude Code、设环境变量、清掉缓存登录、启动、验证。

第一步它给了 Windows 的写法（PowerShell 用 irm https://claude.ai/install.ps1 | iex，macOS/Linux/WSL 用 curl -fsSL https://claude.ai/install.sh | bash，也可以走 npm 装 @anthropic-ai/claude-code）。

但第二步开始就没有 Windows 了。设环境变量那一段给的是两个 Tab：一个是往 ~/.zshrc 或 ~/.bashrc 里写 export，另一个是项目级的 .claude/settings.local.json。持久化那条 Note 列的三个文件也是 ~/.bashrc、~/.zshrc、~/.config/fish/config.fish。Windows 上原生 PowerShell 该怎么写，这篇 cookbook 没有说明。

Claude Code 那边的《Connect Claude Code to an LLM gateway》页补上了这个缺口，它的每个代码块都带 Bash/Zsh 与 PowerShell 两个 Tab：

$env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"

该页还写明：shell 里的导出只对当前终端会话与它启动的程序有效，从 Dock 或开始菜单启动的编辑器读不到；要跨新终端持久化，就把同样几行加到 shell profile，PowerShell 对应的是你的 $PROFILE。settings 文件的 Windows 路径它也给了：%USERPROFILE%\.claude\settings.json。

所以 Windows 读者的实际路径是：变量名与取值照 OpenRouter 的 cookbook，写法去 Claude Code 的网关页拿 PowerShell 那一栏。 把两边拼起来大致是这样：

$env:ANTHROPIC_BASE_URL = "https://openrouter.ai/api"
$env:ANTHROPIC_AUTH_TOKEN = "<YOUR_API_KEY>"
$env:ANTHROPIC_API_KEY = ""

以上为按官方文档中的参数语义组合的示例，未经实测，以官方文档与 --help 的实际输出为准。

Unix 侧另有一个 OpenRouter 专门给了 Warning 的坑：cookbook 示例写的是 export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"，这个展开发生在 profile 被 source 的那一刻，key 若定义在更靠后的位置、别的文件里或由 secrets manager 事后注入，token 就展开成空字符串，请求全部鉴权失败。

第二处口径差：项目 settings 文件到底该不该进版本控制

这是两份文档措辞方向明确相反的一处，值得单独拎出来。

OpenRouter 的 cookbook 在 .claude/settings.local.json 那个 Tab 下写：这个方法把配置限定在项目范围内，便于通过版本控制把 OpenRouter 设置分享给团队（只是要小心别提交 API key）。

Claude Code 的网关页对同一个文件的说法是：.claude/settings.local.json 只作用于单个项目，而且Claude Code 在往里写设置时会把它加进你的全局 gitignore；如果这个文件是你手工建的、或者是让 Claude 写的，你得自己先把它加进 gitignore，免得误提交凭据。同一页还有一条 Warning：不要把凭据放进项目的 .claude/settings.json，因为那个文件是会被提交、会被所有 clone 仓库的人拿到的。

一个说「便于分享」，一个说「默认被 gitignore、且别提交凭据」，很容易读混。稳妥的读法是把「共享配置」和「共享密钥」拆开：base URL、CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY 这类是配置，凭据不是。至于哪个文件在你的仓库里到底被不被忽略，落地前自己用 git check-ignore 确认一遍——这一步属于通用工程做法，不是上面两份官方文档里的内容。

还有一条只在 Claude Code 排查表里出现、cookbook 没有的说明，和上面放一起才看得出关系：在交互式会话中，项目 .claude/settings.json 或 .claude/settings.local.json 里的 env 块，是在首次运行向导与文件夹信任提示之后才生效的。所以完全按 cookbook 的项目 settings 那条路走，第一次启动仍可能被要求登录——那一刻它还没读到你的凭据。该页给的处置是把 ANTHROPIC_AUTH_TOKEN 放到首次设置之前就会读的位置：shell 导出、~/.claude/settings.json 的 env 块，或管理端下发的 managed settings。

另外 OpenRouter 侧还有一条硬警告：不要把这些变量放进项目级 .env 文件，原生安装的 Claude Code 不读标准 .env。

为什么是 `ANTHROPIC_AUTH_TOKEN`，以及为什么要把另一个置空

这一点两边完全对得上，而且 OpenRouter 的 Note 直接引用了 Claude Code 那一页作为依据。

Claude Code 的凭据变量表列了三类：ANTHROPIC_AUTH_TOKEN 用于网关方说「bearer token / Authorization header」的情况，ANTHROPIC_API_KEY 用于说「API key / x-api-key」的情况，apiKeyHelper 用于凭据会轮换或来自 vault 的情况。该页还写明了变量到 HTTP 头的映射：ANTHROPIC_AUTH_TOKEN 走 Authorization: Bearer，ANTHROPIC_API_KEY 走 x-api-key，apiKeyHelper 两个头都发。凭据放错变量，就会以网关不读的那个头送过去，请求以 401 失败。OpenRouter 用 bearer token 鉴权，所以选 ANTHROPIC_AUTH_TOKEN。

「把 ANTHROPIC_API_KEY 显式置空」这条是 OpenRouter 侧强调的：它写明该变量会被当成直连 Anthropic 的凭据，在交互模式下还会提示你一次以决定是否覆盖已保存的登录，置空是为了防止 Claude Code 回落到直接对 Anthropic 鉴权。Claude Code 那页对应的说法是「网关凭据变量优先于已保存的 claude.ai 登录或 Console key，ANTHROPIC_AUTH_TOKEN 立即生效，ANTHROPIC_API_KEY 需在交互模式下批准一次」——它并没有要求你置空。这不算矛盾：OpenRouter 那条 Note 自己写明了置空的作用是防止回落到直连 Anthropic 鉴权，而它的排查小节确实把「shell profile 里还留着一把真 key」单列成了一个故障场景。两处放在一起读，置空这一步对应的是那个场景，文档没有再解释更多。

对应地，OpenRouter 的排查小节把两种残留分得很清楚：切换之前缓存的 Anthropic OAuth 登录，跑 /logout 然后退出重启 claude；shell profile 里还留着一把真的 ANTHROPIC_API_KEY，/logout 帮不上忙——它只清缓存的 OAuth 会话，不清 shell 环境变量。Claude Code 那页排查表第一行只写了「取消变量以使用已保存登录，或跑 /logout 以使用网关凭据」，没拆到这么细。

OpenRouter 还提到 macOS 上缓存会话存在 Keychain 里一个名为 Claude Code-credentials 的通用密码条目中（原生安装不写 ~/.claude/.credentials.json）——这一点我们在本文引用的 Claude Code 两页网关文档里没有找到对应说明，不比。Windows 上缓存登录存在哪，两边都没有说明。

验证：cookbook 只给了一步，另一边给了两步

OpenRouter 的第五步是进 Claude Code 跑 /status，官方文档写明期望看到的两行是：

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

如果 Auth token 那行显示的是 ANTHROPIC_API_KEY，或者出现了指向某个 Claude 账号的 Login method 行，说明环境没有送达会话。

Claude Code 那页在 /status 之前多了一步，对排障更有价值：先不开 Claude Code，直接对网关发一个请求。它给了 Bash 与 PowerShell 两种写法（Bash 侧是 curl -X POST "$ANTHROPIC_BASE_URL/v1/messages"，PowerShell 侧是对同一地址的 Invoke-RestMethod -Method Post），带上 Authorization: Bearer、anthropic-version 和一个极小的 body（body 里的模型名只是文档当时的示例值，平台上有哪些模型随时在变，别当清单用）。该页写明这样做的意义是：失败就能把问题指向网关而不是你的客户端配置。它还给了一条容易被忽略的判据——返回一个「模型名不认识」的错误同样证明 URL 与凭据是通的，因为网关是先鉴权再拒绝模型名的。返回 401 才是凭据被拒，那时候就该换另一个变量再试。

接上之后你会失去什么，cookbook 没有讲

这是我觉得最该补的一块。OpenRouter 的 cookbook 通篇讲的是接上之后多了什么（供应商故障转移、组织预算管控、用量可见性），但一旦网关凭据生效，Claude Code 有几项功能会直接不可用，这只在 Claude Code 那一页里写着：

Remote Control 与语音听写（voice dictation）依赖 claude.ai 身份，在 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 激活时不可用；Remote Control 在 ANTHROPIC_BASE_URL 指向非 Anthropic 主机时同样被禁用，所以光用 claude.ai 登录也救不回来。要恢复得取消对应变量（语音听写取消凭据变量，Remote Control 还要取消 ANTHROPIC_BASE_URL）。
Claude Code in Slack 与网页版是 Anthropic 托管产品，始终走 Anthropic 的 API，不属于网关部署范围，云端会话环境里设的网关变量不会生效。
订阅这一层：《Other LLM gateways》页写明，网关凭据变量或 apiKeyHelper 激活期间，开发者的 claude.ai 订阅不被使用，订阅的用量上限也不适用，这部分流量按 token 计费给网关转发的那份凭据的所有者。OpenRouter 侧对应的说法是「你按 OpenRouter credits 计费」。方向一致。

换句话说，接 OpenRouter 不是「在原有能力上加一层」，而是换了一套身份。你要是天天用 Remote Control，这笔账得先算清楚。

模型选择与 `/fast`：两边各说了一半

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 这个变量两边都写了，是网关模型发现的开关，默认不开。

OpenRouter 侧补充的是行为边界：picker 展示的是一组精选条目而不是完整目录，其中一些条目会路由到非 Anthropic 供应商、因而受前面那条兼容性限制影响；发现到的列表由 Claude Code 存在本地并在启动时刷新，所以开启之后要重启 Claude Code。

Claude Code 侧补充的是怎么确认它跑没跑：发现到的模型会以 From gateway 标注出现在 /model 里；用 claude --debug 启动，在 ~/.claude/debug/<session-id>.txt 的调试日志里找 [gatewayDiscovery] 开头的行，成功会记录缓存了多少个模型，404、超时、重定向也都记在那里。

/fast 这一块也是各说一半，但拼起来正好是完整的因果：Claude Code 排查表写明，可用性检查需要 claude.ai 登录或一把 Anthropic API key，只带 bearer token 时 Claude Code 直接把 fast mode 当作已禁用、连检查都不发，处置是设 CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1；OpenRouter 侧给的是同一个变量，并注明需要 Claude Code v2.1.96 或更新版本。

OpenRouter 还额外标了一个很容易踩的坑：Claude Code 只在解析出的模型 ID 匹配受支持的 Opus 版本时才会附上 speed: "fast"。如果你按它「Configuring Models」一节的示例把 ANTHROPIC_DEFAULT_OPUS_MODEL 设成了 ~anthropic/claude-opus-latest 这个别名，/fast 会报告 “Fast mode ON”，但请求里根本没带 speed 参数。要真的用上就得把变量钉到一个具体的 Opus ID 上。（这里的模型 ID 与别名都是官方文档当时的示例值，平台上的模型随时在变，不要当清单用。）

剩下三条实用边界

CI 场景：GitHub Action 那一段是两边逐字对得上的地方。OpenRouter 说要把 key 同时以 anthropic_api_key 输入传进去、并在 step 的 env 块里设 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN；Claude Code 那页解释了原因——action 在启动前要求有 anthropic_api_key 等凭据之一，而它本身并不读 ANTHROPIC_AUTH_TOKEN，所以那个输入只是为了过启动检查，真正把 key 放进 Authorization 头的是环境变量。两边都指出这里 ANTHROPIC_API_KEY 不为空没关系，因为这是非交互运行。
上下文超限：OpenRouter 的排查只写了「拆小任务或开新会话」。Claude Code 那页细得多：网关若强制一个比模型原生窗口更小的上下文、并用自己的措辞改写了错误，Claude Code 那套按 Anthropic 原文措辞匹配的「自动压缩再重试」就不会触发；恢复靠 /compact，预防靠把 CLAUDE_CODE_AUTO_COMPACT_WINDOW 设成网关的限制——但该值会被夹在一个下限与模型上下文窗口之间，网关限制低于那个下限时匹配不上。
成本状态栏：OpenRouter 提供了一套跟踪费用的 statusline 脚本，配到 ~/.claude/settings.json 的 statusLine 字段。两条边界先知道为好：该字段只支持一个条目，加了这个就会替换掉你原有的，不写包装脚本合并输出没法共存；脚本是 npx tsx 的薄封装，需要 Node.js 且首次渲染要联网。它的每会话状态文件路径文档写的是 /tmp/claude-openrouter-cost-<session-id>.json，Windows 上对应放哪没有说明。

一句话的决策路径

如果你的动机是统一计费入口、做团队预算与用量归集，两边文档支持这条路，而且要把 Anthropic 一方供应商放在最优先。如果你的动机是在 Claude Code 里换模型，两边都没给承诺，先别投入。Windows 用户按 cookbook 走到第二步就得切到 Claude Code 的网关页拿 PowerShell 写法。配完先用 curl 打一次网关再开 CLI，/status 只是最后一道确认。最后，把 Remote Control、语音听写、Slack 与网页版这几项要不要留，提前决定好——这几样和网关凭据不能共存，而这一点只写在 Claude Code 那一侧。

本文依据 OpenRouter 官方文档（openrouter.ai/docs）于 2026-08-18 的公开内容整理。该平台闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观与运行表现的任何描述。该平台的供应商、模型与路由策略随时变动，文中不列具体供应商名单与模型清单；价格、额度与限流的具体数值请以官方定价页与用量说明为准。

本文涉及的另一方内容依据其官方文档整理（Claude Code：code.claude.com/docs）。双方均为闭源商业产品，本文只对照各方公开写明的机制，不推断实现，也不对产品做优劣排名。

两款产品迭代频繁，文中涉及的命令、环境变量与配置项随版本变动，请以官方文档最新内容为准。安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。