OpenRouter 是一个面向大模型推理的聚合网关它把多家模型服务商也就是“推理服务商”的模型统一成一套 OpenAI 兼容的 API。开发者只需要一个账号、一把 API Key、一份账单就能调用来自不同厂商的大模型。最近 OpenRouter 上线了 Makora 推理服务商这之后同一套接入流程里又多了一个可选的算力来源。下面直接按“理解概念、准备账号、跑通调用、排查问题、接入工具链、生产落地”这条主线展开适合刚接触 OpenRouter 的开发者也适合已经接好 OpenAI 接口、想扩展模型来源的团队。读完以后你可以独立完成从注册到把 OpenRouter 接进 Claude Code 的全过程并且能根据报错信息判断问题出在鉴权、额度、模型 ID 还是网络。1. 先理清 OpenRouter、推理服务商和模型路由的关系1.1 OpenRouter 是一层“推理 API 聚合网关”先理解一个容易混淆的点OpenRouter 本身不训练模型它是一个网关。它负责把多个模型供应商的推理服务统一接到一个入口上对外提供一套标准 HTTP API。这样带来的直接好处有三个不用为每个模型厂商单独注册账号、单独维护鉴权。不用分别学习 OpenAPI、Anthropic API、其他厂商私有接口的差异。账单统一在同一个后台就能看到所有模型的花费。实际项目里OpenRouter 最常见的用法是作为一个“模型路由层”存在。业务代码只依赖 OpenRouter 的接口格式模型 ID 可以在配置里随时切换后面某个模型质量不行、价格变高或者服务不稳定改配置即可核心代码不用动。1.2 推理服务商在 OpenRouter 里扮演什么角色在 OpenRouter 的术语里“推理服务商”provider是真正运行模型的算力方。模型是一个逻辑概念服务商是物理实现。同一个模型可能被多个服务商同时提供但不同服务商给出的价格、响应速度、上下文长度和限流策略可能完全不同。OpenRouter 在收到请求后会根据路由规则选择一个服务商来处理这次推理。默认情况下它会考虑价格、可用性和响应时间你也可以在请求参数里指定用哪个服务商或者排除某些服务商。这也是理解“新服务商上线”这件事的关键新服务商意味着可用算力增加、价格可能被拉低、路由选择变多但只要你用 OpenRouter 的标准接口就几乎感知不到底层变化。把概念整理成一张表概念通俗理解在请求中如何体现模型逻辑上的大模型 ID请求体里的model字段推理服务商真正跑模型的算力方请求体里的provider参数聚合网关转发和路由层OpenRouter 的 API 地址本身路由网关选择哪个服务商route参数和默认策略1.3 新服务商上线后开发者应该关注三件事标题里提到的 Makora 就是这类新上线的推理服务商。它具体提供了哪些模型、价格是多少、限流有多紧要以 OpenRouter 官方模型列表页和接口文档为准。作为使用方重点检查三件事模型列表里有没有新增可用的模型 ID。新服务商的定价、上下文长度、每分钟请求数限制是否满足你的场景。请求参数里能不能指定或排除这个服务商。注意新上线的服务商不代表所有模型都能立刻稳定使用。上线初期模型列表、价格、可用地区都可能调整落地前一定要用真实请求验证而不是只看宣传信息。2. 从注册到拿到 API Key先做对这几步2.1 注册账号并确认基本访问状态注册流程本身不复杂打开 OpenRouter 官网使用邮箱或第三方账号登录进入后台后就能看到 Dashboard。这里要提醒一点OpenRouter 部署在海外不同网络环境下页面的可达性和 API 的稳定性会不一样。如果页面或接口长时间不可达先检查 DNS 解析、出口网络和超时配置不要在代码层面盲目排查。注册成功后的第一步不是急着充值而是先把“能否正常访问官网和 API 端点”确认清楚。2.2 创建 API Key并让环境变量成为唯一入口进入 Settings 里的 Keys 页面创建一把 Key。创建完成后页面只会完整显示一次离开页面后就看不到了。推荐的做法是立刻写入环境变量而不是粘贴到代码里export OPENROUTER_API_KEYsk-or-xxxxx在项目里也可以使用.env文件来管理但.env文件必须加入.gitignore。不要把这把 Key 提交到 Git 仓库也不要写进前端代码OpenRouter 的 Key 承担鉴权计费双重职责泄露后可能造成额度被刷。2.3 先看懂预付费额度和账单入口OpenRouter 采用预付费点数Credits模式请求按 token 用量扣费。新账号是否赠送体验额度、赠送多少要以当前官方规则为准不同时期可能不一样。充值的入口在账户后台支付方式会根据账号所在区域和官方支持情况变化以实际页面显示为准。理解额度模型对于排查问题很有用当余额不足时OpenRouter 会返回402 Payment Required而不是429。很多新手把这两个状态码混在一起导致排查方向完全错误。建议新账号先小额充值或者先从免费的:free后缀模型开始测试确认整条链路正常后再切换到付费模型。2.4 用 curl 先确认鉴权和网络都正常拿到 Key 之后第一条命令建议请求模型列表接口而不是直接发对话请求。因为模型列表接口不产生推理费用适合用来验证 Key、网络和接口路径curl -s https://openrouter.ai/api/v1/models \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -H Content-Type: application/json如果返回一段包含data数组的 JSON说明 Key 有效、网络可达。如果返回401说明 Key 不对如果超时说明网络或 DNS 有问题。这个检查点能帮你把“环境问题”和“代码问题”分开。3. 用三次调用跑通一个大模型推理任务验证完鉴权和网络后下一步就是跑通一次真正的推理请求。这里分三步走查模型 ID、用 curl 发最小请求、再用 Python 封装成可复用调用。3.1 从模型列表接口拿到准确的模型 ID不要凭记忆敲模型 ID这是最容易翻车的地方。OpenRouter 的模型 ID 通常是“组织/模型名”的格式区分大小写。使用jq从模型列表接口提取所有 IDcurl -s -H Authorization: Bearer $OPENROUTER_API_KEY \ https://openrouter.ai/api/v1/models | jq -r .data[].id | sort如果列表里已经包含 Makora 提供的模型也可以直接过滤curl -s -H Authorization: Bearer $OPENROUTER_API_KEY \ https://openrouter.ai/api/v1/models | jq -r .data[].id | grep -i makoragrep过滤不到不代表模型不存在可能只是命名里没有包含服务商名称。更稳妥的方式是在模型列表页搜索或者查看该模型的详情接口。列表接口返回的数据里除了id还有context_length和pricing字段前者决定对话窗口大小后者决定每百万 token 的成本都要在选型时核对。3.2 最小请求curl 调用 chat/completionsOpenRouter 的核心推理接口是POST https://openrouter.ai/api/v1/chat/completions示例请求如下这里的model只是示例实际要换成第 3.1 节查到的真实 IDcurl https://openrouter.ai/api/v1/chat/completions \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -H Content-Type: application/json \ -d { model: openai/gpt-4o-mini, messages: [ {role: system, content: 你是技术助手。}, {role: user, content: 用一句话解释什么是推理服务商。} ] }正常返回的 JSON 结构里choices[0].message.content是模型输出usage里包含prompt_tokens、completion_tokens和total_tokens。这一步能跑通说明接口路径、鉴权、模型 ID 和请求体格式都正确。如果模型 ID 写错OpenRouter 会返回404或类似的模型不存在错误这时候应该回到模型列表核对 ID。3.3 用 Python 封装成可复用调用不引入 OpenAI SDK 也能调用使用标准库requests就能完成最小闭环import os import requests url https://openrouter.ai/api/v1/chat/completions headers { Authorization: fBearer {os.environ[OPENROUTER_API_KEY]}, Content-Type: application/json, } payload { model: openai/gpt-4o-mini, messages: [ {role: user, content: 用一句话解释 OpenRouter 的路由机制。} ], temperature: 0.7, max_tokens: 512, } resp requests.post(url, headersheaders, jsonpayload, timeout60) resp.raise_for_status() data resp.json() print(data[choices][0][message][content]) print(data[usage])这里有两个细节timeout必须设置推理模型的响应时间可能很长不设超时会导致调用挂死resp.raise_for_status()会在 HTTP 状态码异常时直接抛出异常避免把错误响应当成正常结果继续处理。3.4 关键参数速查表请求体里的参数分为两类一类是 OpenAI 兼容参数一类是 OpenRouter 特有的路由和计费参数。常用参数整理如下参数含义常见值注意事项model模型 ID来自/models接口区分大小写不要手敲messages对话消息列表至少包含一条 user 消息空列表会报错temperature采样温度0 到 2越高越随机代码任务常用 0 到 0.3max_tokens最大输出 token 数按任务需求太小会导致输出截断top_p核采样概率默认 1通常与 temperature 二选一调整stream是否流式返回true 或 false长输出建议开启provider指定或排除服务商对象格式新服务商上线后可在此指定route路由策略默认自动控制 fallback 行为除了请求体OpenRouter 还支持两个有意义的请求头HTTP-Referer和X-Title。这两个头用于标识调用方应用方便在后台查看某个应用的用量统计。生产环境建议带上否则所有请求在后台都堆在一起很难区分是哪个服务在调用。4. 模型找不到、429、余额不足常见问题排查链路接入 OpenRouter 的大多数线上问题最后都集中在几个固定现象上。下面按“现象 - 原因 - 检查方式 - 处理建议”的链路整理。4.1 现象一模型 ID 对不上或列表里搜不到常见报错是模型不存在或者在模型列表里搜索不到某个服务商的新模型。造成这个现象的原因很多按优先级排查模型 ID 大小写或路径写错。先和/models接口返回的id字段逐字对比。模型已从 OpenRouter 下架或暂时不可用。官网模型页会标记当前状态下架模型即使 ID 正确也会报错。模型存在地区或账号限制。部分模型只对特定区域或特定账号开放换个网络环境测不一定管用要查看模型详情页的状态。客户端缓存了旧列表。比如某些 IDE 插件、cc-switch 配置或网关工具会缓存模型列表刷新缓存后再试。模型根本不是 OpenRouter 官方收录的模型。例如社区或个人创建的模型路径比如某种stealth/ox-alpha类型的命名需要确认该模型是否真正存在于 OpenRouter 平台而不是某个第三方工具里的自定义名字。正确的排查顺序是先用接口实时确认模型是否存在再看模型状态最后检查自己代码里是否写死了旧 ID。4.2 现象二429、402、403、404 混在一起这几个状态码经常被混为一谈但处理方式完全不同状态码含义检查方式处理建议401API Key 无效或缺失检查环境变量是否注入重建 Key确认在请求头里正确传入402余额不足打开账单页面看 Credits充值或临时切换免费模型403账号或地区权限不足查看账号状态和模型限制换合规账号或换可用模型404模型或路由不存在核对模型 ID从/models接口重新获取 ID429触发限流查看限流规则和用量页降低 QPS增加指数退避重试429尤其值得细说。OpenRouter 对模型和服务商都有速率限制超过之后会返回429。处理方式不是盲目加重试而是先看后台的用量页面确认是“每分钟请求数超了”还是“单次请求太重”。重试时要带指数退避例如第一次等 1 秒、第二次等 2 秒、第三次等 4 秒避免限流被加重。注意402和429的修复方向完全不同。遇到402先去充值或换模型遇到429先去降速或重试不要用同一个重试逻辑处理所有错误。4.3 现象三超时、空回复、输出被截断调用推理接口时还可能遇到三类间接问题请求超时。推理模型尤其是带思考能力的模型首 token 延迟可能很长。建议把客户端超时调到 60 秒以上或者改走stream: true流式输出避免连接被网关提前掐断。输出被截断。如果返回结果明显不完整检查usage.completion_tokens是否接近max_tokens并确认finish_reason是否为length。如果确实是截断调大max_tokens同时评估成本。空回复或拒绝回答。先检查messages是否为空再看服务商是否对某些提示词做了内容过滤最后查看返回里有没有refusal或类似字段。不要只盯着choices是否为空要看完整响应体。排查这类问题时保留完整响应 JSON 比只看打印结果有用得多。生产环境建议把请求 ID、状态码、finish_reason和usage记到日志里后续定位会快很多。5. 把 OpenRouter 接入 Claude Codecc-switch 只是换环境变量很多开发者关注 OpenRouter是想把它接入 Claude Code 这类命令行 AI 工具通过 OpenRouter 使用不同模型。理解这一节的关键在于cc-switch 这类工具并不是什么魔法它本质上是帮你修改 Claude Code 的环境变量。5.1 Claude Code 的接入原理环境变量决定请求去向Claude Code 官方计划默认请求 Anthropic 的接口但它支持通过环境变量修改请求地址和鉴权信息。核心变量包括ANTHROPIC_BASE_URLAPI 地址。ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY鉴权令牌。ANTHROPIC_MODEL主模型 ID。ANTHROPIC_SMALL_FAST_MODEL后台小任务模型 ID。OpenRouter 提供了 Anthropic 兼容的接入端点具体路径以官方文档为准。只要把ANTHROPIC_BASE_URL指向 OpenRouter 的兼容端点把鉴权令牌换成 OpenRouter 的 KeyClaude Code 的请求就会走到 OpenRouter再通过模型 ID 路由到对应模型。5.2 手动配置先把一条链路跑通不依赖任何工具直接在终端里导出环境变量就能测试export ANTHROPIC_BASE_URLhttps://openrouter.ai/api/v1/anthropic export ANTHROPIC_AUTH_TOKENsk-or-xxxxx export ANTHROPIC_MODELanthropic/claude-3.5-sonnet export ANTHROPIC_SMALL_FAST_MODELanthropic/claude-3.5-haiku claude这里的模型 ID 只是示例必须以/models接口实际返回为准。手动配置能跑通说明链路没问题如果这一步就报错后面用任何切换工具都会报错因为工具改的也是这些变量。5.3 用 cc-switch 做多套配置切换cc-switch 是社区常用的配置切换工具适合需要经常在官方配置和 OpenRouter 配置之间切换的场景。它的本质是把上一节的环境变量保存成多套方案切换时自动替换当前终端的配置。配置存储的字段大致如下{ name: openrouter-profile, provider: openrouter, baseURL: https://openrouter.ai/api/v1/anthropic, apiKey: sk-or-xxxxx, model: anthropic/claude-3.5-sonnet, smallFastModel: anthropic/claude-3.5-haiku }具体字段名和存储位置会随 cc-switch 版本变化以你使用的版本为准。使用这类工具时要记住一个原则切换后必须确认环境变量真的变了。很多“切换不生效”的问题其实是新开的终端进程没有加载新配置或者两个变量互相覆盖。5.4 验证接入成功的关键信号接入是否成功不能只看 Claude Code 能不能启动。建议按顺序做三个验证发送一个简单问题确认模型能正常回复。打开 OpenRouter 后台的活动记录页确认请求确实到达了 OpenRouter并查看了对应的模型 ID。故意把模型 ID 写错确认报错信息指向 OpenRouter而不是 Claude Code 本身。第三步看起来多余但它能确认请求真的被路由到了 OpenRouter。如果错误信息仍然指向 Anthropic 官方说明ANTHROPIC_BASE_URL没有生效问题出在环境变量而不是模型 ID。6. 生产环境接入前要补的几个工程习惯学习环境里调通接口很简单但生产环境接入时必须补上密钥管理、错误重试、成本控制这三块。6.1 密钥不外泄是第一优先生产环境不要依赖手动export要使用密钥管理服务或部署平台的环境变量功能。同时要做到代码仓库不出现任何 Key 明文。日志打印请求时对Authorization头做脱敏。前端页面不直接携带 Key所有推理请求走后端中转。为开发环境和生产环境分别创建 Key发现问题时可以单独吊销。密钥泄露后唯一的止损手段是立即吊销并重新生成。所以还要定期检查后台的 Key 列表删除不再使用的 Key。6.2 重试、超时和流式输出要同时配置只设置超时而不设置重试遇到429时接口还是会失败只设置重试而不设置超时耗时请求会一直挂着。推荐组合是客户端超时设置在 60 秒以上流式请求可以更长。对429、5xx做指数退避重试最多尝试 3 次。5xx重试之间要增加随机抖动避免多个请求同时重试造成雪崩。对402、401、404不要重试这类错误重试没有意义。调用失败后还要保留一条完整日志包含请求 ID、模型 ID、状态码和错误正文方便后续回溯。6.3 成本控制要落实到 token 和余额两个层面OpenRouter 按 token 计费成本控制必须在两个层面同时做请求层面设置max_tokens避免模型无限输出在代码里记录每次请求的usage按天聚合。账户层面定期查看余额和消费记录设置合理的充值额度把“余额不足”从事故变成可预期事件。对于测试环境直接用:free后缀的免费模型跑通流程确认逻辑正确后再切换付费模型是控制成本最直接的办法。但免费模型通常限流更严、响应更慢不能直接照搬生产配置。6.4 上线前检查清单把上面所有要点汇成一份可勾选的清单每次接入新服务商或新项目时至少过一遍API Key 由环境变量或密钥管理服务注入不在代码中出现。模型 ID 来自/models接口不手写固定字符串。客户端设置了超时时间。429和5xx有指数退避重试逻辑。402、401、404有独立的分支处理。日志不记录 Key但记录模型 ID、状态码、finish_reason和usage。开发环境使用免费或低成本模型生产环境才切付费模型。后台监控余额和请求量余额低于阈值时有告警。切换服务商后验证模型 ID、价格和限流规则与文档一致。如果是接入 Claude Code确认ANTHROPIC_BASE_URL和鉴权令牌都已生效。按照这条链路走完从 OpenRouter 注册、创建 Key、跑通推理请求到接入 Claude Code 和生产排查基本不会遇到无从下手的卡点。新服务商上线带来的选择变多但只要接口层稳定、排查链路清晰底层换谁提供服务都不影响上层业务。下一步可以重点研究 OpenRouter 的路由参数和限流规则把“能调用”升级成“能用得稳、花得省”。