OpenRouter 接入 Claude Code 怎么配：配置项、常见坑与验证方法

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

把 Claude Code 接到 OpenRouter，真正决定成败的只有三件事：ANTHROPIC_BASE_URL 填带协议头的完整地址 https://openrouter.ai/api，把 OpenRouter 的 key 放进 ANTHROPIC_AUTH_TOKEN，以及把 ANTHROPIC_API_KEY 显式置成空字符串。 剩下的问题绝大多数不是「配错了」，而是「配的东西没送到会话里」——shell profile 里的变量展开顺序不对、旧的 Anthropic 登录态还缓存着、或者把变量写进了项目根目录的 .env。官方给出的第一道验证是：在会话里敲 /status，看它报的 Auth token 是不是 ANTHROPIC_AUTH_TOKEN、base URL 是不是那个地址。动手之前还有一条前置警告要先读：官方文档明确写着，Claude Code 配 OpenRouter 只保证与 Anthropic 一方（first-party）供应商配合工作，为获得最大兼容性，建议把 Anthropic 1P 设为最高优先级的供应商。

先装，再连：安装方式不影响后面的配置

官方给了两条安装路径：一条是原生安装脚本（macOS / Linux / WSL 用 curl -fsSL https://claude.ai/install.sh | bash，Windows PowerShell 用 irm https://claude.ai/install.ps1 | iex），另一条是走 npm 装 @anthropic-ai/claude-code，后者需要 Node.js 18 或更新版本。文档把原生安装标为推荐。

这一步选哪条都行，但要记住你选的是哪条——后面有一个坑（配置文件读不读 .env）和原生安装器直接相关。

三个环境变量，一个都不能少

官方把连接要求写成了三条，措辞很紧：

1. 用完整的 OpenRouter API 地址，包含协议头：https://openrouter.ai/api
2. 把你的 OpenRouter API key 作为 ANTHROPIC_AUTH_TOKEN 提供
3. 重要：显式把 ANTHROPIC_API_KEY 置空，以免冲突

第三条最容易被当成多余动作跳过，而官方专门用一整段解释了为什么它是必需的：OpenRouter 是一个用 bearer token 鉴权的 LLM 网关，Claude Code 把 ANTHROPIC_AUTH_TOKEN 作为 Authorization: Bearer <token> 发出去，这正是 Anthropic 为「bearer 鉴权的网关」所记载的凭据变量；而 ANTHROPIC_API_KEY 走的是 x-api-key 头，会被当成直连 Anthropic 的凭据，在交互模式下还会弹一次提示、问你要不要用它盖过已保存的登录。把它设成空字符串，是为了阻止 Claude Code 退回去直接向 Anthropic 鉴权。

换句话说，这两个变量不是「二选一的同义词」，它们走的是不同的 HTTP 头、不同的凭据语义。理解了这一点，后面那些看起来莫名其妙的报错就都有解释了。key 本身的保管与轮换规则，可以顺带看一眼API 密钥安全管理。

变量写在哪：三个位置，一个雷区

写进 shell profile。 官方示例是在 ~/.zshrc（Bash 用户是 ~/.bashrc）里依次导出 OPENROUTER_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"、ANTHROPIC_API_KEY=""，另外还有一个可选的 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1。写完必须重新加载 shell（source 一下或者新开一个终端），否则你测的还是旧环境，然后得出「这套配置不管用」的错误结论——这句提醒是官方自己写在文档里的。

这里藏着本文最值得单独拎出来的一个坑，官方用 Warning 框标了出来：顺序有讲究。ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY" 是在 profile 被 source 的那一刻完成展开的。如果 OPENROUTER_API_KEY 定义在文件更靠后的位置、定义在另一个文件里、或者由密钥管理工具在你的 profile 跑完之后才注入，那么 auth token 就会展开成空串，之后每一个请求都会以鉴权错误失败。解决办法要么保证 key 在被引用之前就已定义，要么把它放进加载更早的文件（zsh 可以用 ~/.zshenv）。

顺带一提，官方也提醒了这种写法的副作用：明文 key 落在 shell profile 里，是很容易被误提交进 dotfiles 仓库或者贴进 gist 的。文档建议改从操作系统钥匙串里读取，macOS 的示例写法是 export OPENROUTER_API_KEY="$(security find-generic-password -s openrouter -w)"；万一泄漏，去 key 设置页吊销并轮换。

写进项目级设置文件。 另一种方式是在项目根目录建 .claude/settings.local.json，在 env 对象里放同样这几个键。好处是配置只作用于这个项目，方便通过版本控制分享给团队——但官方紧跟着补了一句，别把 API key 一起提交上去。

唯一的雷区：不要写进项目级 .env。 官方原话是原生 Claude Code 安装器不读取标准 .env 文件。这个坑很隐蔽，因为很多人的直觉就是「项目级配置当然放 .env」，结果配了半天没有任何生效迹象，还会误以为是网关的问题。

「模型不存在」往往不是模型问题，是旧登录态没清

如果你以前用 Anthropic 账号登录过 Claude Code，切到网关之后必须跑一次 /logout 清掉缓存的会话，然后退出并重新启动 claude，让它重新读取环境变量。官方说明这个冲突的表现形式相当有迷惑性：当缓存登录和网关凭据同时存在时，Claude Code 会在启动时告警，冲突可能导致启动行为异常，典型表现是令人困惑的「模型不存在」类错误（比如报 openrouter/auto、openrouter/pareto-code 这类只有 OpenRouter 才有的模型找不到）。

官方在排障章节把这类报错拆成了两个不同场景，处理方式并不一样：

• 场景一，你有从前遗留的 Anthropic OAuth 缓存登录——跑 /logout，然后退出重启 claude。
• 场景二，你的 shell profile 里还留着一个真实的 ANTHROPIC_API_KEY（比如旧的 Anthropic 控制台 key）——这时候 /logout 帮不上忙，因为它只清 OAuth 缓存会话，清不掉 shell 环境变量。得按前面说的把 ANTHROPIC_API_KEY="" 写进 profile 再重载。

如果缓存会话怎么都清不掉，官方还给了 macOS 上的定位方法：原生安装的缓存会话存在钥匙串里，是一条名为 Claude Code-credentials 的通用密码条目（原生安装不会写 ~/.claude/.credentials.json），可以用 security find-generic-password -s "Claude Code-credentials" 确认它是否还在，用对应的 security delete-generic-password 删掉后重启 claude。

验证：/status 该出现什么，不该出现什么

配完之后 cd 到项目目录敲 claude 就能用了，但别跳过验证这一步。官方的验证方式是在会话里执行 /status，期望看到两行：Auth token 一行显示的是 ANTHROPIC_AUTH_TOKEN，Anthropic base URL 一行显示的是 https://openrouter.ai/api。

反过来说，两种情况说明配置没生效：Auth token 那行显示的是 ANTHROPIC_API_KEY，或者出现了一行 Login method 指向某个 Claude 账号。官方对这两种情况给的判断是一致的——环境没有送达会话，重新加载 shell 并重启 claude。

第二道验证在服务端：去 OpenRouter 的 Activity 面板看请求是不是实时出现了。这一步的价值在于它证明的是「请求真的走到了 OpenRouter」，而不只是「本地变量看起来对」。日常的用量与花费跟踪可以配合API 成本监控怎么做一起搭。

底层是怎么接上的：Anthropic 皮肤

官方对连接机制的说明只有三点，但每一点都能解释一类现象：

1. 直连。把 ANTHROPIC_BASE_URL 指向 https://openrouter.ai/api 之后，Claude Code 用它的原生协议直接和 OpenRouter 对话，不需要本地代理服务。所以如果你看到有人让你先起一个本地转换服务，那不是官方这条路径。
2. Anthropic 皮肤。OpenRouter 暴露的是一个兼容 Anthropic Messages API 的输入。官方说这层「皮肤」的行为与 Anthropic API 一致，负责模型映射，并且会透传 Thinking 块与原生工具调用这类高级特性。
3. 计费。用的是你的 OpenRouter 额度，用量（包含推理 token）会出现在 OpenRouter 的面板里。

第 2 点有个实际后果：Claude Code 报错的时候，你看到的是 Anthropic 原生形态的错误类型，不是 OpenRouter 那套。官方给了这层皮肤的映射表，比如内部的 authentication 映射成 authentication_error、permission_denied 映射成 permission_error、payment_required 映射成 billing_error、rate_limit_exceeded 映射成 rate_limit_error、provider_overloaded 映射成 overloaded_error（完整映射以官方文档为准）。

关键在于官方自己承认这个映射是有损的：很多内部类型会一起塌缩成 api_error。所以 OpenRouter 在 error 对象里额外附上了规范的 error_type 字段，非流式的错误信封和流式中途的 SSE error 事件都是如此。排查的时候优先看 error_type 那个字段，别只盯着 Anthropic 那层的 type。还有一个定位细节很好用：路由前发生的错误（比如鉴权失败）request_id 是 null，路由后的错误才带 gen- 开头的生成 ID——凭这一条就能判断请求到底有没有被派发到供应商。鉴权类报错的逐层排查顺序，可以对照OpenRouter 报错 401 的排查顺序。

模型怎么指定：五个变量，外加 Fable 的例外

Claude Code 用一组环境变量决定不同任务用哪个模型，官方列出的可覆盖项是：ANTHROPIC_DEFAULT_FABLE_MODEL（Fable 类任务，对应要求最高的推理与长周期工作）、ANTHROPIC_DEFAULT_OPUS_MODEL（Opus 类，如复杂推理）、ANTHROPIC_DEFAULT_SONNET_MODEL（Sonnet 类，如常规编码）、ANTHROPIC_DEFAULT_HAIKU_MODEL（Haiku 类，如快速补全）、以及 CLAUDE_CODE_SUBAGENT_MODEL（Claude Code 派生的子代理任务）。这些要加到你设置 base URL 和 auth token 的同一个位置（shell profile 或项目设置文件）。

这里有个官方特意标注的例外：Claude Code 2.1.x 增加了 Fable 作为第四类模型，当 Claude Code 指向 OpenRouter 时，/model 默认不提供 Fable，设置 ANTHROPIC_DEFAULT_FABLE_MODEL 是让它可选的唯一办法。设完之后官方建议做两件事确认：在会话里打开 /model 看你期望的每一类是否都列出来了，再去 Activity 面板看模型那一列，确认请求确实路由到了你配的模型上。

至于前面提到的那个可选变量 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1：网关模型发现是默认关闭、需要主动开启的，开启后会出现模型选择器。有三点要知道——选择器展示的是一批精选的高排名模型，不是 OpenRouter 的完整目录；其中一些条目会路由到非 Anthropic 供应商，可能受前面那条兼容性限制影响（官方另有一句：Claude Code 是为 Anthropic 模型优化的，配其他供应商可能无法正常工作）；发现到的清单会存在本地、在启动时刷新，所以刚开启或者想让它重新拉取时，都要重启 Claude Code。另外，用上面那些变量把模型钉死，会直接选中该模型并绕过选择器。

/fast 的反直觉之处：显示开了，其实没带上

Claude Code 有个内置的 /fast 命令用来切换 fast 模式，开启后它会在请求里带上 speed: "fast" 参数，OpenRouter 完整支持这个参数——但你需要先设置环境变量 CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1，且该能力要求 Claude Code v2.1.96 或更新版本。

真正的坑在官方的 Warning 里：Claude Code 只有在解析出来的模型 ID 匹配到受支持的 Opus 版本时才会附上 speed: "fast"。如果你的 ANTHROPIC_DEFAULT_OPUS_MODEL 用的是 ~anthropic/claude-opus-latest 这类别名（也就是官方「配置模型」一节里给的那个示例本身），/fast 会显示 “Fast mode ON”，但请求发出去根本不带 speed 参数——按标准速度、标准价位走。要真正用上，必须把变量钉到某个具体的 Opus 模型 ID 上。

怎么确认它真的生效了？官方给的信号是：fast 模式激活时，响应的 usage 对象里会包含 "speed": "fast"。这比看界面提示可靠得多。还有两条边界值得记：fast 模式只由 Anthropic 一方供应商提供（其他供应商不支持）；Claude Fable 没有 fast 档，在 Fable 模型上切 /fast 不会让 Fable 变快，而是让 Claude Code 把会话切到你配置的 Opus 模型上，后续请求会按 Opus 来跑和计费。计费上只需知道 fast 模式相对该 Opus 模型的标准 token 价位属于溢价档，具体费率以官方定价页为准。

放进 CI 与看清花在哪

如果要在 GitHub Action 里用，官方给的改法是在 action 步骤上做两处改动：把 OpenRouter key 通过 anthropic_api_key 输入传入（存成名为 OPENROUTER_API_KEY 的 GitHub secret），同时在该步骤的 env 块里把 ANTHROPIC_BASE_URL 设为 https://openrouter.ai/api、ANTHROPIC_AUTH_TOKEN 设为同一个 secret。官方解释了为什么这里和本地配置反着来：action 必须先拿到 anthropic_api_key 输入才肯启动 Claude Code，而它自己并不读 ANTHROPIC_AUTH_TOKEN，所以那个输入是用来满足启动检查的，真正把 key 放进 Authorization 头的是环境变量。也正因如此，这里的 ANTHROPIC_API_KEY 不是空值（由输入填充），官方说这没问题，因为这次运行是非交互的，而且 base URL 仍然把每个请求送去 OpenRouter。

想在终端里实时看到花销，官方还提供了一个状态栏脚本（从其示例仓库下载后配到 ~/.claude/settings.json 的 statusLine 里），会显示供应商、模型、会话累计花费，以及缓存带来的抵扣。用之前有几个前提要清楚：statusline.sh 只是个薄封装，实际跑的是 npx tsx statusline.ts，因此需要 Node.js，首次渲染还需要联网下载依赖；两个文件都要下载并放在同一个目录；settings.json 只支持一个 statusLine 条目，你要是已经在用别的状态栏，加了这个就是替换掉原来的，不写合并脚本没法共存；每次刷新会对会话中每个新生成调一次生成查询接口，显示的花费是当前会话的累计值；每个会话的状态文件落在 /tmp/claude-openrouter-cost-<session-id>.json，多数系统重启后会清掉，也可以随时手动删。

最后：两个容易踩空的地方

一是供应商优先级。开头那条警告不是客套话——官方只保证 Anthropic 一方供应商能配合工作，并推荐把它设为最高优先级。OpenRouter 的供应商偏好里，order 字段是排序（官方原文是「路由器会按这个列表和顺序优先考虑这些供应商」），它不会把候选池筛空；真正做限定的是 only 字段，而且账户级的允许列表是天花板、请求级的 only 在其中收窄，两者都不满足时请求会以 404 失败。配之前想清楚你要的是「优先」还是「只准」。

二是沙箱环境下的网络问题。如果你是在 Claude Desktop 里跑 Claude Code，官方排障里提到 Claude Code 运行在一个沙箱中，其网络隔离可能破坏到网关的 TLS 连接，缓解办法是在 Claude 设置文件里加上 {"sandbox": {"enableWeakerNetworkIsolation": true}} 再重启；~/.claude/settings.json 会作用于所有项目，项目内的 .claude/settings.json 或 .claude/settings.local.json 只作用于该项目。官方特别提醒：这个开关放宽的是所有代理发起的网络流量的隔离，不只是网关 TLS，所以尽量选能解决问题的最小范围，问题解决后就删掉。同一节还提到 WebFetch 被网络出口设置拦截时，要去第三方推理配置面板的工作区限制页把需要的主机加进允许出口主机列表——这条对 Claude Code 同样适用。

最后一条让人安心的：官方声明除非你在账户设置里主动开启 prompt 日志，OpenRouter 不会记录你的源码提示词，细节以其隐私政策为准。