openrouter 接入 claude code

很多人按教程把 Claude Code 的地址改成 OpenRouter 之后，能跑起来但一上量就出问题：长任务半路断、并发一开就限流、报错看不出是通道还是模型的问题。这篇不重讲协议和客户端装法，只给落地做法——从哪里改配置、超时和并发怎么设、失败怎么降级、日志记哪几个字段、换通道后按什么顺序自查。

很多人第一次把 Claude Code 接到 OpenRouter，流程走通了、也能出结果，但一到真实项目上量就出问题：长任务跑到一半停住、并发一开就撞限流、报错分不清是通道还是模型本身。这类问题的根子通常不在客户端装没装对，而在超时、并发、降级、日志这几件事没提前定规则。这篇只讲落地做法，协议和客户端安装不重复。

先把结论摆在这：Claude Code 走 Anthropic 那一侧的协议，改法和 OpenAI 系客户端不一样，所以配置要分三项确认——base URL、鉴权变量、默认模型，别一次全改完再一起排错。下面按「值不值得接→改哪里→怎么设超时重试→并发怎么控→怎么降级→日志记什么→怎么验收→上线清单」的顺序走一遍。

先想清楚：为什么要让 Claude Code 走 OpenRouter

走一层通道是有代价的：多一跳网络、多一层配额和计费口径、多一处要排查的日志。所以在动手之前先判断自己的场景属不属于「值得」。下面这张表可以直接对照。

• 适合的场景：手上有多个模型想按任务切、单一供应商偶尔不稳、想用一套 Key 管多个模型。
• 不适合的场景：团队对数据出境有硬要求、任务极度依赖某一家的独有能力。
• 先明确你能接受的代价：多一跳网络延迟、多一层配额与计费口径、多一处可能需要排查的日志。
• 动手前到 /openrouter 看当前的模型清单与调用口径，到 /official-api 对照官方直连的差别，判断这层通道值不值。
• 如果只是想省钱或想用免费额度，先读站内 openrouter-free-model-calling 与 openrouter-usage-ranking，别把省钱当成唯一理由。

改哪几个地方：配置入口与环境变量

Claude Code 走的是 Anthropic 协议那一侧，改法和 OpenAI 系客户端不一样。最稳的做法是把 base URL、鉴权变量、默认模型三项拆开，一项一项改、一项一项验，而不是一口气改完再去看哪里报错。

base URL

指向通道侧的入口地址，别把两种协议的地址混用。

鉴权变量

通道侧发的 Key，注意变量名和客户端认的变量名是否一致。

默认模型

要写成通道侧认识的写法，大小写和分隔符对不上通常直接报模型不存在。

环境变量改完要新开一个终端会话才生效。很多人卡在「改了没用」，其实是旧 shell 里还留着老值，这种问题排查半小时都找不出原因，其实重开一个窗口就好。

• 先把三项分开确认，别一次改完再一起排错。
• 环境变量改完新开一个终端会话，避免旧 shell 残留旧值。
• 模型名按通道侧写法来，大小写和分隔符对不上会报模型不存在，而不是鉴权错。
• 具体字段名和写法到 client-setup 看客户端侧说明，到 base-url 看两套协议的差异，这篇不重复。

超时与重试：把「偶发断流」变成可预期的行为

长任务卡住，多数不是连接超时，而是读取超时。所以连接超时、读取超时、整体超时这三项要分开设，不要只写一个总超时了事。分档建议到 api-timeout-tuning 对照。

1. 分三档设超时连接超时给短、读取超时给长、整体超时兜底。设完跑一个长上下文请求验证不会提前断。
2. 限定重试范围只对幂等且明确是网络层的错误重试。模型侧返回的内容级错误重试只会重复烧额度。
3. 用指数退避并设上限重试间隔按指数退避递增，加一个最大重试次数，避免一次任务卡死一整晚。
4. 流式单独处理流式场景下断流和超时要分开判断，先看 streaming-sse-production 里那几条前置检查。

判断标准很简单：如果一次任务失败后，你没法从日志里说清是超时、限流还是内容错误，那重试策略就还没定清楚。重试不是越多越好，是「知道什么时候该放弃」才算定完。

并发与批量：别让 Claude Code 自己把配额打满

很多人并发一开就限流，是因为并发上限是拍脑袋定的。先量出你能承受的上限，再开任务。基线可以去 /tools/speed-test 跑一遍，别凭感觉设数字。

• 批量任务要分批排队，加一个失败重投队列，不要让所有子任务同时起。
• 触发限流后的处理顺序：先降并发、再拉长间隔、最后才考虑换通道。
• 直接换通道会把问题带到新通道上，等于把一个没定位的问题复制了一遍。
• 退避与排队的具体档位参考 429-concurrency-backoff 与 batch-concurrency-throttle-guide。

降级与换源：主通道抖了怎么接着干活

降级能救急，但前提是先把「什么算失败到需要换源」定义清楚。规则要写死在配置里，不能靠人临时判断，否则同一批任务两个人跑出两种结果。

• 定义失败条件：连续多次同类错误、超过时长阈值、还是特定错误码，三选一或组合。
• 降级目标要提前验证过可用，临时抓一个没用过的模型接上去，结果往往是把任务写坏而不是写不完。
• 换源后模型能力可能变弱，涉及重构、跨文件改动的任务要限制在降级通道上跑，宁可排队等主通道恢复。
• 多通道编排思路见 multi-model-routing-fallback，这里只强调判断条件要可量化。

日志记哪几个字段：出问题能复盘

日志不是记得越多越好，是记对字段。下面这几项能覆盖大多数「慢」和「贵」的归因，缺一项排查时就得多猜一轮。

请求体只记摘要和长度，不要把完整代码上下文落盘，团队协作场景下这是数据风险。拿这些字段做一个小看板，按天看失败率和平均耗时，趋势比单次报错更能说明问题。字段清单可以对着 api-log-fields-replay 里的口径抄，保持一致后面好横向比。

换通道后的验收顺序：五步走一遍再上量

换通道或者改配置之后，别直接上量。按下面五步走一遍，每一步都留一条可复现的命令或脚本，之后每次改配置重跑一遍，比人肉点一遍靠谱得多。

1. 单请求连通性发一个最短请求，确认能拿到返回，验证鉴权和 base URL。
2. 带工具调用的请求Claude Code 常用工具调用，这一步通不过后面都白搭。
3. 长上下文请求故意给一个较大的上下文，验证读取超时设得够不够。
4. 流式输出跑一次流式，确认断流和超时能区分开。
5. 并发压一小批开一小批并发，看限流和退避有没有按预期触发。

验收不过时按「鉴权→模型名→网络→配额」的顺序查，别一上来就怀疑模型能力。排错顺序的细节可以看 relay-connectivity-verification 和 401/403 那两篇，这里不展开。判断标准是：每一步都能重跑，且失败时能定位到具体一项配置，而不是「整体不行」。

上线前对照清单

把下面四组逐条过一遍，四条都打勾再上量。这份清单的价值不在全面，在于让你每次改完配置都有个固定动作，不用凭记忆。

• 配置：base URL、鉴权、默认模型三项在干净终端里验证通过。
• 稳定性：超时分档、重试上限、退避策略、降级条件都已写进配置而非文档。
• 成本：知道这批任务大概的量级，到 /tools/model-cost-calculator 与 /usage 核一遍口径。
• 可观测：日志字段齐全，能回答「上一次失败是什么原因」。