最近不少同学在群里讨论 OpenRouter 上线了 Makora 推理服务商这件事。大家关心的点其实很集中OpenRouter 到底是什么新上线的 Makora 和之前用的模型服务商有什么区别拿到了 OpenRouter 的 API Key 之后怎么在代码里调用又怎么接到 Claude Code、cc-switch 这类工具里注册之后有没有免费额度访问不稳定怎么办报 429 或被提示“模型找不到”又该怎么排查这些问题如果只看零散的热搜和帖子很容易越看越乱。这篇文章会把 OpenRouter 从注册、创建 API Key、绑定支付方式到统一 API 调用、模型路由原理、接入 Claude Code再到高频报错排查完整地串一遍。重点会围绕“OpenRouter 上线 Makora 推理服务商”这个变化展开适合刚接触 OpenRouter 的入门读者也适合已经在用但想系统梳理接入流程的开发者。全程以实操为主代码和配置都可以直接复制参考。1. OpenRouter 与 Makora背景与核心概念1.1 OpenRouter 是什么OpenRouter 是一个大模型 API 聚合平台。通俗地说它像一个“模型路由器”把多家模型厂商和服务商提供的模型集中到同一个入口里。开发者不需要分别去 OpenAI、Anthropic、Google、Meta 等多家平台注册账号、申请 Key、学习不同的 API 格式只需要在 OpenRouter 上注册一个账号、创建一组 API Key然后通过统一的 HTTP 接口调用不同模型。从专业角度看OpenRouter 提供的是标准的/api/v1/chat/completions接口兼容 OpenAI 的消息格式。请求体里通过model参数指定要调用的模型 IDOpenRouter 会在后台完成路由、计费和结果返回。也就是说OpenRouter 更像一层“网关”真正执行推理的可能是某个模型原厂也可能是第三方推理服务商。这种模式解决了几个常见问题多模型切换成本高。换模型只需要改model参数不需要重写代码。账号和计费分散。一个账号、一个 API Key、一个余额就能访问多个模型。部分模型的官方接口有地区限制或申请门槛通过聚合平台可以获得更灵活的访问方式。1.2 Makora 作为推理服务商意味着什么这次标题里的“Makora”出现在 OpenRouter 生态中定位是“推理服务商”。可以把它理解为 OpenRouter 背后众多模型提供方之一。在 OpenRouter 的模型列表页面里每个模型通常会标注 Source 或 Provider 信息例如该模型由哪个服务商提供推理资源。Makora 被列为推理服务商意味着用户通过 OpenRouter 调用某些模型时实际的计算资源和推理服务可能由 Makora 承担。对开发者来说最重要的变化不是去单独注册 Makora而是理解下面三点你依然只需要一个 OpenRouter API Key不需要额外申请 Makora 的 Key。调用方式不变仍然是 POST 到 OpenRouter 的统一接口。计费、限流、模型可用性会根据 OpenRouter 平台规则和 Makora 的服务状态变化。所以“OpenRouter 上线 Makora 推理服务商”本质上是一次平台生态扩充。它让 OpenRouter 的模型供给更丰富也让部分模型有了新的推理后端选择。1.3 为什么开发者关注这个变化开发者关注这个变化通常不是因为 Makora 本身而是因为“多一个推理服务商”意味着多一层可用性和成本选择。在实际工程中模型推理服务可能不稳定也可能因为高并发被限流。OpenRouter 聚合多家服务商之后如果某个模型的官方渠道负载过高OpenRouter 可以尝试把请求路由到其他服务商反过来如果某个服务商整体不可用模型的调用成功率也会受影响。因此了解 OpenRouter 的服务商体系能帮你更准确地判断报错根因。另外OpenRouter 的模型市场更新很快新增服务商往往伴随着新模型的接入。关注这类变化可以让你在模型选型时多一个参考维度。2. 前置准备账号、密钥与支付2.1 注册 OpenRouter 账号使用 OpenRouter 的第一步是注册账号。打开 OpenRouter 官网openrouter.ai首页会提供邮箱注册和第三方账号登录方式。建议优先使用常用邮箱注册方便后续接收账单和异常通知。注册时需要注意密码尽量使用独立密码不要和重要邮箱、支付账号共用。如果使用第三方登录务必确认绑定的邮箱是你能长期访问的邮箱。注册后第一时间去邮箱确认验证邮件部分功能在未验证邮箱时可能不可用。需要说明的是OpenRouter 是海外服务从部分网络环境访问时响应速度和稳定性可能受国际网络环境影响。如果页面加载缓慢可以先检查本地网络、DNS 设置或防火墙策略确保使用的是合规且稳定的网络环境。2.2 创建 API Key登录 OpenRouter 后进入个人后台的 API Keys 页面就可以创建新的 API Key。创建时会要求填写名称例如dev-test或prod-app建议按用途命名方便后续管理。创建完成后页面会完整显示一次 Key 值。务必立即复制并保存到安全的位置例如密码管理器或本机环境变量文件。这个 Key 不会在平台上再次完整显示一旦关闭页面就找不回来了只能删除重建。后面代码里调用 OpenRouter 时HTTP 请求头中需要携带这个 KeyAuthorization: Bearer YOUR_OPENROUTER_API_KEY例如export OPENROUTER_API_KEYsk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx这里需要特别强调API Key 等同于你的资金访问凭证。只要 Key 泄露别人就可以用它调用付费模型产生费用由你的账号承担。千万不要把 Key 提交到 GitHub、粘贴到公开论坛或写进前端代码里。2.3 绑定支付方式与额度说明OpenRouter 的计费方式是“预付费 按量扣费”。也就是说通常需要先往账号里充值然后根据实际 token 消耗量扣费。关于支付方式OpenRouter 官方主要以国际信用卡为主具体是否支持其他支付渠道要以你账号后台实际显示的支付页面为准。国内开发者如果遇到支付困难可以先查看官方帮助文档了解支持的支付方式再决定是否绑定或充值。还有一类是免费模型。OpenRouter 上有部分模型带有:free后缀使用这些模型通常不需要余额但会有较严格的速率限制且服务可用性不做保证。免费模型适合测试接口连通性不适合生产环境。需要提醒的是OpenRouter 新注册用户是否有赠送额度、赠送多少属于平台运营规则会随活动变化。不要轻信第三方文章里的固定数字以 OpenRouter 官方当前页面显示为准。最稳妥的做法是先创建 Key。用免费模型验证接口连通性。确定需要付费模型时再绑定支付方式并小额充值。在后台设置消费提醒或预算上限防止费用异常增长。3. 理解 OpenRouter 的模型路由与统一 API3.1 统一 API 格式OpenRouter 提供的接口兼容 OpenAI Chat Completions 格式。一个最小请求如下curl https://openrouter.ai/api/v1/chat/completions \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -H Content-Type: application/json \ -d { model: model-id, messages: [ { role: user, content: 你好请介绍一下你自己 } ] }把model-id替换成 OpenRouter 模型列表中的实际模型标识即可。响应体也兼容 OpenAI 格式包含id、object、choices、usage等字段。这种统一格式带来的好处很明显如果你之前写过 OpenAI SDK 的调用代码切换到 OpenRouter 时只需要修改base_url和api_key业务代码几乎不用动。以 Python 的openai库为例from openai import OpenAI client OpenAI( base_urlhttps://openrouter.ai/api/v1, api_keyYOUR_OPENROUTER_API_KEY, ) completion client.chat.completions.create( modelmodel-id, messages[ {role: user, content: Hello!} ], ) print(completion.choices[0].message.content)这段代码就是“OpenRouter 的 api key 如何免费在代码里使用”这个问题的核心答案。只要你把model换成免费模型 ID再把 Key 换成自己的就可以在本地代码中直接调用。3.2 model 参数与 provider 路由OpenRouter 的model参数指定的是“模型 ID”而不是某个固定厂商的部署实例。同一个模型 ID 背后可能有多个服务商同时提供推理资源。OpenRouter 会根据可用性、价格、延迟等因素决定把请求路由到哪个服务商。这种路由机制对调用方是透明的。也就是说大多数情况下你不需要关心请求最终由谁执行。但对于 Makora 这类“推理服务商”概念理解路由机制会帮助你更好地排查问题如果 OpenRouter 显示某个模型由 Makora 提供说明路由目的地可能是 Makora。如果 Makora 侧服务异常调用该模型时可能出现超时、5xx 错误或较长的排队时间。OpenRouter 部分场景支持指定provider参数但这类参数属于进阶用法普通调用不建议主动设置以免降低可用性。此外OpenRouter 返回的响应头中可能包含路由相关信息。实际排查时可以关注响应中的X-Trace-Id或X-Request-Id之类的字段这些信息在反馈问题给平台时很有用。3.3 如何找到 Makora 提供的模型如果你想知道 Makora 具体提供哪些模型最直接的方法是打开 OpenRouter 的模型页面openrouter.ai/models在页面中按服务商筛选或者在模型详情页查看 Provider / Source 信息。也可以通过 OpenRouter 提供的模型列表接口来查询curl https://openrouter.ai/api/v1/models \ -H Authorization: Bearer $OPENROUTER_API_KEY返回结果是 JSON 数组每个模型会包含id、name、pricing、context_length等字段。部分模型条目中会标注服务商信息。你可以把返回结果保存下来用文本搜索方式查找包含makora关键字的模型条目。需要特别提醒的是不要在代码里硬编码一个“从热搜里看到的模型名”。OpenRouter 的模型列表更新频率较高模型 ID 可能因为服务商调整而变化。正确做法是先通过模型列表接口或官网页面确认模型 ID。再用确认后的 ID 发起调用。如果调用返回模型不存在回到模型列表重新核对。这也是“为什么在 OpenRouter 的 api 配置后找不到 stealth/ox-alpha 这个模型”这类问题最常见的答案你使用的 model id 不存在、已下线或者不在当前账号可访问的范围内。4. 实战用 OpenRouter 调用 Makora 模型4.1 创建项目结构为了演示完整流程我们先创建一个简单的 Python 项目目录openrouter-demo/ ├── .env ├── requirements.txt └── chat.py目录说明.env存放环境变量包括 OpenRouter API Key。requirements.txtPython 依赖。chat.py核心调用脚本。4.2 配置环境变量在项目根目录下创建.env文件OPENROUTER_API_KEYsk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx注意.env文件不要提交到 Git 仓库。建议在.gitignore中加上.env.env __pycache__/ .venv/接着在requirements.txt中写入依赖openai1.0.0 python-dotenv1.0.0 requests2.31.0安装依赖pip install -r requirements.txt这里使用openai库是因为 OpenRouter 的接口兼容 OpenAI 格式不需要额外引入特殊的 SDK。4.3 编写核心代码下面编写chat.py实现一个最基本的对话请求。为了通用性代码中的模型 ID 使用model-id占位符你运行前需要替换成 OpenRouter 模型列表中的真实模型 ID。# 文件路径openrouter-demo/chat.py import os from dotenv import load_dotenv from openai import OpenAI # 加载 .env 文件中的环境变量 load_dotenv() # 从环境变量读取 Key api_key os.getenv(OPENROUTER_API_KEY) if not api_key: raise ValueError(请先在 .env 文件中配置 OPENROUTER_API_KEY) # 创建客户端指向 OpenRouter client OpenAI( base_urlhttps://openrouter.ai/api/v1, api_keyapi_key, ) # 在这里替换成你需要的模型 ID model_id model-id response client.chat.completions.create( modelmodel_id, messages[ {role: system, content: 你是一个严谨、简洁的助手。}, {role: user, content: 用一句话介绍模型路由的概念。}, ], ) print(模型返回内容) print(response.choices[0].message.content) print(\nToken 消耗) print(response.usage)代码说明load_dotenv()负责读取.env文件避免把 Key 硬编码在代码里。OpenAI(base_url...)将请求地址指向 OpenRouter。messages里可以包含系统提示词和用户消息。response.usage会返回prompt_tokens、completion_tokens、total_tokens方便核对计费。4.4 使用 curl 快速验证如果不想写 Python也可以用 curl 快速验证接口是否连通curl https://openrouter.ai/api/v1/chat/completions \ -H Authorization: Bearer $OPENROUTER_API_KEY \ -H Content-Type: application/json \ -d { model: model-id, messages: [ {role: user, content: 你好} ] }如果你还没有配置环境变量可以直接把$OPENROUTER_API_KEY替换成真实的 Key 字符串但注意不要泄露。4.5 运行与验证运行脚本python chat.py预期会输出一段模型生成的文本和 token 消耗信息。如果网络环境稳定、模型 ID 正确、余额充足整个请求通常在几秒到几十秒内完成。如果这一步出现错误先不要急着改代码按照下面顺序检查API Key 是否正确设置。网络到openrouter.ai是否连通。模型 ID 是否存在于模型列表。账号余额是否足够。请求频率是否超过限制。5. 实战将 OpenRouter 接入 Claude Code5.1 Claude Code 环境变量方式Claude Code 是 Anthropic 推出的命令行 AI 编程工具。默认情况下它连接 Anthropic 官方 API但通过环境变量可以让它使用兼容 Anthropic 接口的其他服务OpenRouter 就支持这种方式。在接入之前先配置环境变量export ANTHROPIC_BASE_URLhttps://openrouter.ai/api/v1 export ANTHROPIC_AUTH_TOKEN$OPENROUTER_API_KEY说明ANTHROPIC_BASE_URL告诉 Claude Code 向哪个地址发送请求。ANTHROPIC_AUTH_TOKEN设置认证 Token这里使用 OpenRouter 的 API Key。设置完成后再启动 Claude Codeclaude如果配置正确Claude Code 会通过 OpenRouter 调用模型。你可以在交互界面中提问观察是否得到正常回复。需要注意的是OpenRouter 的模型列表中Anthropic 系列模型例如 Claude 系列的模型 ID 可能与官方不完全一致。你需要在 OpenRouter 模型页面中确认当前使用的模型 ID并通过配置或命令行参数指定。很多情况下Claude Code 会依赖ANTHROPIC_MODEL或默认模型配置因此建议查阅你所用 Claude Code 版本对模型参数的支持情况。5.2 使用 cc-switch 管理多 Providercc-switch 是一个社区工具用于快速切换 Claude Code 的 API Provider 配置。它的价值在于当你在 Anthropic 官方、OpenRouter、其他兼容平台之间切换时不用每次手动修改环境变量。使用 cc-switch 的一般思路是这样的下载并安装 cc-switch确认工具来源可信。在界面中新增一个 Provider 配置。填写 Provider 名称例如OpenRouter-Makora。填写 API Base URLhttps://openrouter.ai/api/v1。填写 API Key你的 OpenRouter Key。选择要通过 OpenRouter 使用的模型 ID。保存并切换。切换之后cc-switch 会帮你更新 Claude Code 启动时使用的环境变量或配置文件。这样你可以在多个 Provider 之间一键切换不需要每次都打开终端手动 export。这里要提醒一点cc-switch 属于第三方工具它的界面和配置项会随版本更新。如果你的版本界面和网上教程不一致以实际界面为准原理都是修改 Claude Code 的 Base URL、Token 和 Model 配置。5.3 验证接入是否成功接入完成后可以这样验证在 Claude Code 中输入一个简单问题例如“你好请回复 OK”。观察是否正常回复。如果回复正常再测试一个涉及代码生成的任务检查模型是否具备工具调用能力。打开 OpenRouter 后台的请求记录页面确认产生了对应模型的调用记录。如果 Claude Code 没有任何输出或者直接退出可以尝试在前台运行并查看日志。很多情况下问题不是配置本身而是模型 ID 不支持工具调用或 API Key 权限不足。6. 常见问题与排查思路下面整理几个从注册到调用过程中最高频的问题。问题现象常见原因解决思路页面打不开或请求超时网络环境不稳定域名解析受影响检查本地网络、DNS、防火墙换合规网络环境后重试返回 401 UnauthorizedAPI Key 错误或未设置检查环境变量重新确认 Key返回 404 / model not found模型 ID 不存在或已下线到 OpenRouter 模型列表核对 model id返回 429 或 Rate Limit请求频率超限或免费模型限流降低并发增加退避重试付费模型通常更稳定返回 402 / Insufficient Credits余额不足充值或改用免费模型Claude Code 接入后无响应Base URL、Token、模型 ID 不匹配检查环境变量和模型配置看日志调用成功但响应很慢推理服务商负载高或模型本身较大观察路由情况尝试更换模型6.1 网络访问问题OpenRouter 是海外服务。从中国大陆访问时响应速度、稳定性可能不如访问国内服务。遇到超时优先检查网络连通性ping openrouter.ai curl -I https://openrouter.ai如果curl长时间无响应说明当前网络环境访问该域名受限。此时应当使用合规、稳定的网络环境进行开发而不是在本地反复调整超时参数。ping不通不一定代表服务不可用因为部分服务器禁 ping但curl能通。如果curl也失败再结合你的网络环境判断。6.2 429 限流429 表示请求过于频繁。OpenRouter 对不同模型、不同账号等级可能设置不同的速率限制。尤其是:free免费模型限流通常很严格。解决思路降低单线程请求频率。增加重试机制对 429 响应等待一段时间后重试。生产环境改用付费模型。在 OpenRouter 后台查看当前用量和限制。示例Python 中实现简单的退避重试。import time import random def call_with_retry(chat_fn, max_retries3): for attempt in range(max_retries): try: return chat_fn() except Exception as e: if 429 in str(e) and attempt max_retries - 1: wait (2 ** attempt) random.uniform(0, 1) time.sleep(wait) continue raise这里只是重试思路具体异常类型要根据你使用的 SDK 版本进行调整。6.3 模型找不到 / model id 错误“找不到模型”是高频问题。可能原因有模型 ID 写错例如大小写不一致。模型已经下架或改名。该模型不允许当前账号访问。请求接口版本和模型 ID 不匹配。排查方法curl https://openrouter.ai/api/v1/models \ -H Authorization: Bearer $OPENROUTER_API_KEY把返回结果保存到本地搜索你需要的模型名。如果搜索结果为空说明这个模型在当前平台不可用或不存在如果存在仔细复制接口返回的id字段再发起调用。6.4 余额不足与扣费异常如果你在调用付费模型时看到类似Insufficient Credits的报错说明账号余额不够支付本次请求。处理方式到 Billing 页面查看当前余额。小额充值后再试。检查代码中是否存在循环调用避免意外消耗。为不同环境准备独立 Key便于成本追踪。扣费异常通常是因为模型上下文超出预期。建议在每次响应中记录usage字段分析 token 消耗是否符合预期。6.5 Claude Code 接入失败Claude Code 接入 OpenRouter 失败最常见的问题是环境变量没有正确传递。例如在终端里 export 后又启动了新的 Shell环境变量未继承。使用 cc-switch 时配置的模型 ID 不适用于 Claude Code。某些 Claude 模型要求工具调用能力而选中的模型不支持。建议启动 Claude Code 前先检查环境变量echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN确认输出符合预期再启动工具。如果仍然失败查看 Claude Code 的日志文件定位是网络请求失败、认证失败还是模型返回格式问题。7. 最佳实践与工程建议7.1 API Key 安全管理API Key 管理的核心原则是“最小权限、分环境隔离、定期轮换”。开发环境和生产环境使用不同的 Key。不要把 Key 写入前端代码或公开仓库。在服务器上可以使用环境变量或密钥管理服务保存 Key。定期到 OpenRouter 后台清理不再使用的 Key。如果怀疑 Key 泄露立即删除并重建。一个常见的错误是把 Key 直接写在 Python 文件里例如# 错误示范 api_key sk-or-v1-xxxx虽然本地跑起来方便但一旦文件被提交到 GitKey 就永久留在提交历史里了。正确做法是从环境变量读取。7.2 成本控制与用量监控OpenRouter 的按量计费模式下成本控制非常重要。建议在代码中记录每次调用的 token 消耗并按项目维度汇总。例如把响应中的usage写入日志print(json.dumps({ model: model_id, prompt_tokens: response.usage.prompt_tokens, completion_tokens: response.usage.completion_tokens, total_tokens: response.usage.total_tokens, }))在团队协作中可以在 OpenRouter 后台为不同项目分配不同 Key通过后台的请求日志和账单页面查看每个 Key 的消费情况。如果成本波动明显优先检查是否存在循环调用、重试逻辑过重、上下文无限增长等问题。7.3 错误重试与降级生产环境调用大模型接口时网络抖动和限流几乎是不可避免的。一个健壮的调用层应该具备超时控制给请求设置合理的超时时间避免线程长时间挂起。指数退避重试对 429、503、超时等临时错误进行有限次重试。降级策略当某个模型不可用时切换到备选模型。熔断机制连续失败时停止调用并告警。例如在 Python 的openai库中设置超时client OpenAI( base_urlhttps://openrouter.ai/api/v1, api_keyapi_key, timeout60.0, max_retries2, )这里的max_retries是 SDK 自带的重试次数timeout控制单次请求最长等待时间。具体数值需要根据业务场景调整。7.4 模型选择与稳定性OpenRouter 的模型选择很丰富但“丰富”也意味着“变化快”。建议优先选择有多个服务商支持的热门模型避免单个服务商故障导致整体不可用。对生产环境使用的模型 ID 做配置化管理不要散落在业务代码中。关注 OpenRouter 模型列表中的created、updated字段了解模型更新情况。如果需要低延迟优先选择响应速度较快的模型如果需要高质量代码生成优先选择综合能力更强的模型。关于 Makora 这类新增推理服务商建议先在非生产环境中验证稳定性和响应质量再逐步放量。8. 总结与进一步学习本文围绕“OpenRouter 上线 Makora 推理服务商”展开梳理了 OpenRouter 的基本概念、账号注册、API Key 创建、支付与额度、统一 API 调用、模型路由原理以及如何通过代码和 Claude Code 实际接入。实践部分给出了 curl 和 Python 两种调用方式也说明了 Claude Code 接入 OpenRouter 时的环境变量配置和 cc-switch 使用思路。针对网络访问、429 限流、模型找不到、余额不足、Claude Code 接入失败等高频问题给出了排查方向和解决建议。如果你想继续深入建议按下面顺序学习阅读 OpenRouter 官方 API 文档了解请求头、响应字段和错误码。在 OpenRouter 后台查看模型列表和价格页面掌握成本估算方法。研究provider路由参数理解如何控制请求路由到指定服务商。为团队搭建一个统一的大模型接入层把 Key 管理、重试、降级、日志都收口到一个模块中。最后说一句实际的在尝试“OpenRouter Makora”之前建议先用免费模型把整条链路跑通确认账号、Key、网络、代码都没有问题再切换到付费模型。这样既能控制成本又能减少配置问题带来的干扰。如果这篇文章对你有帮助可以收藏备用遇到问题随时回来对照排查。