看到“OpenRouter Is Having Issues”这句话时很多开发者的第一反应是“OpenRouter 是不是又崩了”。但根据我接触到的实际案例平台自身故障其实并不常见大部分“Having Issues”的时刻是我们自己在注册、获取 API Key、调用模型、接入 Claude Code 的路上踩了坑。这篇文章就把这些 issues 拆开讲清楚OpenRouter 是什么、注册和充值怎么操作、API Key 怎么拿到、免费模型怎么调用以及最常见的 401、429、404 model not found 该如何排查。最后我会给出通过 cc-switch 接入 Claude Code 的完整步骤。无论你只是想写个脚本调模型还是想把 OpenRouter 当作 Claude Code 的后端供应商这篇教程都能直接复用。1. OpenRouter 是什么为什么大家都在讨论 “Having Issues”1.1 一个统一的模型聚合 API 平台OpenRouter 是一个 AI 模型 API 聚合平台。你可以把它理解成一个“模型网关”OpenAI、Anthropic、Meta、Mistral、DeepSeek、Qwen 等多家模型被统一接入到一个 API 接口后面。作为开发者你不需要为每一家模型单独注册账号、单独记一套接口规范只需要注册一个 OpenRouter 账号创建一个 API Key调用同一个https://openrouter.ai/api/v1/chat/completions接口在请求体里通过model字段切换不同的模型。这种设计在业务开发中非常实用。比如你同时需要对比几个模型的输出效果或者同一个系统里简单任务用便宜的小模型复杂任务用贵的大模型OpenRouter 都能帮你把复杂度收敛到一个入口上。1.2 OpenRouter 和官方模型 API 的区别很多第一次接触 OpenRouter 的同学会问我直接用 OpenAI 官方 API 不行吗为什么还要经过 OpenRouter区别主要有三点对比项官方模型 APIOpenRouter接口标准各家标准不统一统一 OpenAI Chat 兼容格式账号体系每家独立注册、独立充值一个账号、一个 Key、一个余额模型切换需要切换不同 SDK 和接口修改model字段即可免费模型官方一般没有免费额度带:free后缀的模型可免费调用附加能力较少模型路由、多供应商切换、详细用量统计OpenRouter 并不是“破解别人模型”它本身是一个正常付费的 API 网关。它帮你聚合模型从中赚取合理的通道成本。所以如果你想长期稳定使用还是需要了解它的充值和计费机制。1.3 “Having Issues”到底指什么标题里的 “OpenRouter Is Having Issues” 其实不是某个固定的官方报错文案而是开发者对一类问题的概括。在我看到的讨论里大家遇到的 issues 通常集中在官网打不开注册流程卡住不知道在哪里充值或者支付宝/银行卡渠道对不上创建了 API Key但调用时返回 401免费模型调用频率稍高就返回 429照着教程填了一个模型 ID结果返回 404 model not found用 cc-switch 把 OpenRouter 接入 Claude Code 后Claude Code 无法识别模型。这些问题大多不是 OpenRouter 平台挂了而是配置、模型 ID 或网络环境导致的。我们逐个拆开看。2. 注册账号与获取 API Key 实操2.1 注册前需要准备的东西第一步是打开 OpenRouter 官网。OpenRouter 目前主要使用英文界面没有所谓的“官方中文版”。如果你在搜索引擎里看到“OpenRouter 官网中文版”一般有两种情况浏览器自动翻译后的页面第三方教程做的中文截图。所以不用纠结语言把邮箱、Google 账号或 GitHub 账号准备好就行。注册入口通常在首页右上角的 Sign In 或 Sign Up 按钮。这里要特别说一下“国内能用吗”这个问题。OpenRouter 是海外平台访问是否顺畅取决于你当前的实际网络环境、服务器部署位置以及本地合规要求。如果你连官网都无法打开请先确认自己所在环境是否允许访问海外服务再继续后续操作。本文只讨论 OpenRouter 平台本身的使用方法不展开网络访问的具体方式。2.2 创建 API Key注册完成后进入 Dashboard找到 API Keys 相关页面点击创建 Key。创建时一般可以给 Key 设置名称和权限范围部分设置项因账号状态而异。创建完成后Key 只会完整显示一次格式通常类似sk-or-v1-xxxxxxxxxxxxxxxx建议立刻复制保存到本地密码管理工具里。你后续所有请求都会用到这个 Key。2.3 关于充值和余额机制OpenRouter 是预付费模式。调用付费模型时系统会从余额里扣费余额不足时付费模型的请求会失败。如果你想充值需要在官网的 Billing / Credits 页面操作。官方渠道主要支持国际信用卡/借记卡具体支持的支付方式以你账号页面看到的为准。至于网上经常有人问的“OpenRouter 支付宝充值”这并不是官方承诺的固定通道。OpenRouter 官方是否开放本地化支付方式会随着平台政策变化第三方代充服务存在账号安全和资金风险请自己判断。如果只是想测试功能可以先不充值用免费模型跑通链路再说。3. 用代码调用 OpenRouter API3.1 核心接口地址OpenRouter 的 Chat Completion 接口地址是https://openrouter.ai/api/v1/chat/completions鉴权方式与 OpenAI 类似Authorization: Bearer 你的_API_KEY请求体需要包含的关键参数有model模型 ID例如meta-llama/llama-3.3-70b-instruct:freemessages对话消息数组包含role和contenttemperature温度参数控制随机性max_tokens生成的最大 token 数。需要注意示例中的模型 ID 只是演示用。OpenRouter 的模型列表会经常调整免费模型更是不定期上下架所以调用前最好以官网 Models 页面为准。3.2 用 curl 快速验证先用 curl 验证链路是最快的排错方式。curl https://openrouter.ai/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -d { model: meta-llama/llama-3.3-70b-instruct:free, messages: [ {role: user, content: 请用一句话介绍 OpenRouter} ] }执行前先设置环境变量export OPENROUTER_API_KEYsk-or-v1-你复制的key如果返回一段 JSON并且里面有choices[0].message.content说明链路已经通了。3.3 Python 调用示例Python 直接使用requests库即可不需要额外安装 OpenRouter 专属 SDK。import os import requests API_KEY os.environ.get(OPENROUTER_API_KEY) URL https://openrouter.ai/api/v1/chat/completions payload { model: meta-llama/llama-3.3-70b-instruct:free, messages: [ {role: system, content: 你是一个乐于助人的助手。}, {role: user, content: 请解释一下 OpenRouter 的用途。} ], temperature: 0.7, } headers { Authorization: fBearer {API_KEY}, Content-Type: application/json, } resp requests.post(URL, jsonpayload, headersheaders, timeout60) print(resp.status_code) print(resp.json())这里有几个关键点Key 从环境变量读取而不是写死在代码里timeout60可以防止请求一直挂起返回的resp.json()中真正的内容在choices[0][message][content]里。3.4 Node.js 调用示例如果你用的是 Node.js 18 及以上版本可以直接用内置fetchconst API_KEY process.env.OPENROUTER_API_KEY; const res await fetch(https://openrouter.ai/api/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${API_KEY}, }, body: JSON.stringify({ model: meta-llama/llama-3.3-70b-instruct:free, messages: [ { role: user, content: 你好请介绍 OpenRouter } ], }), }); const data await res.json(); console.log(data);如果你在代码里写死了 Key一旦代码提交到 GitHubKey 可能被扫描工具泄漏。这个隐患后面在最佳实践里我会再次强调。3.5 免费模型怎么找OpenRouter 的免费模型通常带有:free后缀。例如某个模型 ID 可能是xxx/xxx:free。通过官网 Models 页面可以筛选免费模型。更推荐的方式是直接调用模型列表接口把它保存下来做分析curl https://openrouter.ai/api/v1/models返回的 JSON 里包含模型 ID、名称、上下文长度、定价等信息。你可以用脚本把带:free的模型过滤出来这样就不用来回翻网页了。不过要记住免费模型是 OpenRouter 为了吸引开发者测试用的它们在下线方面没有承诺。生产环境不能把稳定运行押注在一个免费模型上否则某天模型下线你的服务会立刻报 404。4. 常见 issues 排查401、429、404这一节是很多同学真正需要的内容。不管是调用 OpenRouter API还是通过 cc-switch 接入 Claude Code下面的报错都绕不开。4.1 401 Unauthorized认证失败如果你看到类似401 Unauthorized或Authentication error通常是认证信息有问题。需要按这个顺序排查请求头是否带了Authorization值是不是Bearer sk-or-v1-xxx的完整格式Key 是否复制完整有没有多空格、少字符Key 是否已过期或被删除是否不小心把代码里的环境变量名写错了。一个常见的低级错误是把Bearer写成了BearerToken或者把 Key 放在api_key字段里。OpenRouter 遵循 OpenAI 兼容格式鉴权必须放在 Header 的Authorization里。4.2 429 Too Many Requests请求被限流免费模型非常容易出现 429。因为免费资源是共享的平台需要限制单个用户的请求频率。处理思路有几种降低请求频率避免短时间高并发增加退避重试等待一段时间后再请求如果业务需要稳定换付费模型。一个简单的 Python 重试逻辑如下import time import requests def call_with_retry(payload, max_retries3): headers { Authorization: fBearer {os.environ[OPENROUTER_API_KEY]}, Content-Type: application/json, } for attempt in range(max_retries): resp requests.post( https://openrouter.ai/api/v1/chat/completions, jsonpayload, headersheaders, timeout60, ) if resp.status_code 429: wait_time int(resp.headers.get(Retry-After, 2 ** attempt)) time.sleep(wait_time) continue return resp return resp这里读取了响应头Retry-After如果服务端没有返回这个头就使用指数退避策略第一次等 1 秒第二次等 2 秒第三次等 4 秒。4.3 404 model not found为什么找不到 stealth/ox-alpha很多教程或者社区讨论里会出现stealth/ox-alpha这类模型 ID但你把它的 ID 填进请求却返回 404 或者 “model not found”。原因有很多常见的有模型 ID 已经失效。OpenRouter 的模型列表是动态的测试模型、内部模型、限时模型都可能被下架或改名。模型 ID 拼写不完整。某些模型需要带后缀比如:free或者:beta。不同模型的ID格式不一样。模型只在特定权限下可用。部分模型可能需要特定账号权限或额外的申请流程。教程中的模型 ID 本来就是临时的。这类情况在 AI 工具快速迭代期特别常见今天的 ID 不代表明天还有效。遇到这种情况正确的排查方法是打开官网 Models 页面直接搜索stealth或ox-alpha如果搜索不到说明它已经被下架或从未公开展示如果搜索得到认真比对返回的完整 model ID注意大小写和后缀暂时用openrouter/auto或其他稳定模型验证请求链路。openrouter/auto是 OpenRouter 提供的自动选择模型 ID适合用来确认“到底是我参数写错还是模型 ID 错”。等链路通了再换回你真正要用的模型。4.4 网络超时和连接失败如果你请求后没有任何返回而是出现超时、拒绝连接、SSL 错误那要先区分是平台问题还是本地网络问题。可以先手动访问 OpenRouter 的模型列表接口curl https://openrouter.ai/api/v1/models如果这个接口都不通说明你当前环境访问 OpenRouter 有网络层面的问题。如果接口通了但 Chat 接口超时再检查是不是触发了平台限流或者模型响应太慢。4.5 常见 issues 速查表问题现象常见原因解决思路401 UnauthorizedAPI Key 为空、错误或过期检查请求头和 Key 是否完整429 Too Many Requests请求频率过高尤其是免费模型退避重试、降低并发、换付费模型404 model not found模型 ID 拼写错误或已下架搜索官方模型列表用稳定模型验证400 Bad Requestmessages 为空、max_tokens 过大检查请求体格式和参数范围请求超时网络环境或模型响应慢确认网络连通性调整 timeout能访问官网但 API 不通Key 权限、余额、限流到 Dashboard 检查用量和余额5. 通过 cc-switch 接入 Claude CodeOpenRouter 的热搜词里“OpenRouter 通过 cc-switch 接入 Claude Code”出现频率很高。这部分我单独讲一下。5.1 cc-switch 是什么Claude Code 默认连接到 Anthropic 官方服务需要自己的 Anthropic 账号和 Key。如果你想用 OpenRouter 作为后端就需要把 Claude Code 的 API 地址和密钥“切换”到 OpenRouter。cc-switch 本质上是一个配置管理工具它帮你维护多套 Claude Code 供应商配置并在它们之间切换避免每次手动改环境变量或者配置文件。它的核心能力就是让 Claude Code 指向你指定的 base URL 和 API Key。5.2 Claude Code 接入 OpenRouter 的原理Claude Code 运行时会读取类似下面的环境变量来控制 API 地址和密钥ANTHROPIC_BASE_URLhttps://openrouter.ai/api/v1/anthropic ANTHROPIC_API_KEYsk-or-v1-你的openrouter_key其中ANTHROPIC_BASE_URL需要指向 OpenRouter 提供的 Anthropic 兼容端点。OpenRouter 提供了兼容 Anthropic 协议的访问地址这样 Claude Code 才能用原生协议把请求发到 OpenRouter再由 OpenRouter 路由到下游模型。5.3 实际操作步骤安装并打开 cc-switch。不同版本的 cc-switch 界面会有差异但核心逻辑相同。新增 Provider / 配置项。填写配置名称任意例如OpenRouterbase URL填写 OpenRouter 的 Anthropic 兼容端点通常为https://openrouter.ai/api/v1/anthropic以官方文档为准API Key填写 OpenRouter 的 Key也就是sk-or-v1-开头的字符串。保存并激活该配置。启动 Claude Code发送一条测试消息观察是否能正常返回。如果你之前已经使用过 Anthropic 官方配置cc-switch 切换后会修改 Claude Code 的实际配置文件。如果 Claude Code 已经在运行最好重启会话。5.4 接入失败怎么排查接入失败时先回到基础变量上排查base URL 是否正确是否多了/v1或少了anthropicAPI Key 是否是 OpenRouter 的 Key而不是 Anthropic 的 KeyOpenRouter 账户余额是否足够选择的模型是否被 Claude Code 支持是否支持工具调用function callingcc-switch 版本和 Claude Code 版本是否兼容。特别提醒不要用免费模型作为 Claude Code 的主模型。Claude Code 在正常使用过程中会产生大量上下文请求免费模型限流很厉害很容易触发 429导致会话中断。6. 充值、成本控制与免费模型边界6.1 是否需要充值如果你只是本地测试、写个脚本玩一玩使用带:free后缀的免费模型就够了不需要充值。但如果你要把 OpenRouter 接入到项目或者 Claude Code 里建议先充一小笔钱。免费模型的不稳定性会影响业务。OpenRouter 的充值入口在 Billing / Credits 页面支持的具体支付方式以页面显示为准。6.2 如何控制消费上限OpenRouter 的账户设置里通常可以设置消费限制Limits。我建议在充值后第一时间设置一个较低的上限比如 5 美元或 10 美元防止自己调试时忘记关掉循环或者 Key 泄漏后被别人刷余额。设置入口一般在账户设置或 Billing 页面。具体字段名因平台改版而变化以实际界面为准。6.3 免费模型不是“零成本”那么简单免费模型虽然没有直接的费用但使用成本体现在其他方面限流更严格可能随时下架上下文长度和速率优先级低于付费模型不适用于生产业务。所以正确的心态是免费模型用来学习、测试、做 demo付费模型用来支撑正式服务。7. 最佳实践与工程建议7.1 API Key 安全是第一优先级OpenRouter 的 Key 就是钱。一旦泄漏别人可以直接刷你的余额。务必要做到不使用硬编码写在环境变量或本地.env文件中前端代码不要直接放 Key所有请求都应经过后端服务.env文件加入.gitignore定期轮换 Key如果发现异常消费立刻在后台删除并重建 Key。7.2 模型 ID 不要写死这在前面已经反复强调过。OpenRouter 的模型列表是动态的免费模型、测试模型随时可能调整。建议把模型 ID 放到配置中心或其他配置管理机制中这样即使模型切换也不需要改代码重新发布。同时可以定期拉取https://openrouter.ai/api/v1/models对比模型变化做好提醒。7.3 超时、重试和可观测性接入第三方 API 时一定要考虑异常设置超时时间对 429 做指数退避重试对 5xx 做有限次数重试记录每次请求的状态码、延迟、模型 ID 和用量信息。如果你的请求失败了最好能记录 OpenRouter 返回的错误信息以及请求 ID。这些信息在排查问题时非常关键。7.4 日志和成本监控OpenRouter 的 Dashboard 会展示用量和费用明细。建议定期查看特别是团队共同使用时。你可以在业务日志里记录每次请求的 token 消耗估算成本。避免出现“跑了一个晚上余额没了”的情况。7.5 合规与数据安全OpenRouter 是海外平台请求会发送到其背后的第三方模型服务商。如果业务涉及敏感数据或合规要求需要先确认数据是否允许出域。不要把脱敏要求不明确的数据直接发送给第三方模型尤其是个人隐私和商业机密。7.6 区分“平台故障”和“配置问题”如果 OpenRouter 官方状态页显示所有服务正常但你的请求报错那大概率是你自己的网络环境或请求参数问题。可以先拉取模型列表接口再尝试用 curl 直接调用把问题边界缩小。这样能节省大量时间。8. 总结OpenRouter 是一个能把多家大模型 API 统一起来的网关它的价值在于减少多模型接入的重复成本。这篇教程把一个新手最容易遇到的 issues 都拆开了注册、创建 Key、充值、调用免费模型、排查 401/429/404以及用 cc-switch 接入 Claude Code。最后送你一个排错顺序先到官网 Models 搜索你用的模型 ID确认它还在再用 curl 直接调用确认 Key 和接口地址没问题最后再检查 cc-switch 的 base URL、API Key 和模型配置。很多 issues 查到后面答案往往只是模型 ID 多了一个后缀或者 Key 少复制了一个字符。希望这篇教程能帮你省下一点排查时间。