企业官网建设流程全解析

最近不少同学在群里讨论 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参数指定要调用的模型 ID，OpenRouter 会在后台完成路由、计费和结果返回。也就是说，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 请求头中需要携带这个 Key：

Authorization: Bearer YOUR_OPENROUTER_API_KEY

例如：

export OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx

这里需要特别强调：API Key 等同于你的资金访问凭证。只要 Key 泄露，别人就可以用它调用付费模型，产生费用由你的账号承担。千万不要把 Key 提交到 GitHub、粘贴到公开论坛或写进前端代码里。

2.3 绑定支付方式与额度说明

OpenRouter 的计费方式是“预付费 + 按量扣费”。也就是说，通常需要先往账号里充值，然后根据实际 token 消耗量扣费。

关于支付方式，OpenRouter 官方主要以国际信用卡为主，具体是否支持其他支付渠道，要以你账号后台实际显示的支付页面为准。国内开发者如果遇到支付困难，可以先查看官方帮助文档，了解支持的支付方式，再决定是否绑定或充值。

还有一类是免费模型。OpenRouter 上有部分模型带有:free后缀，使用这些模型通常不需要余额，但会有较严格的速率限制，且服务可用性不做保证。免费模型适合测试接口连通性，不适合生产环境。

需要提醒的是，OpenRouter 新注册用户是否有赠送额度、赠送多少，属于平台运营规则，会随活动变化。不要轻信第三方文章里的固定数字，以 OpenRouter 官方当前页面显示为准。最稳妥的做法是：

1. 先创建 Key。
2. 用免费模型验证接口连通性。
3. 确定需要付费模型时，再绑定支付方式并小额充值。
4. 在后台设置消费提醒或预算上限，防止费用异常增长。

3. 理解 OpenRouter 的模型路由与统一 API

3.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_url="https://openrouter.ai/api/v1", api_key="YOUR_OPENROUTER_API_KEY", ) completion = client.chat.completions.create( model="<model-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 可能因为服务商调整而变化。正确做法是：

1. 先通过模型列表接口或官网页面确认模型 ID。
2. 再用确认后的 ID 发起调用。
3. 如果调用返回模型不存在，回到模型列表重新核对。

这也是“为什么在 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.txt：Python 依赖。
• chat.py：核心调用脚本。

4.2 配置环境变量

在项目根目录下创建.env文件：

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx

注意：.env文件不要提交到 Git 仓库。建议在.gitignore中加上.env：

.env __pycache__/ .venv/

接着在requirements.txt中写入依赖：

openai>=1.0.0 python-dotenv>=1.0.0 requests>=2.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_url="https://openrouter.ai/api/v1", api_key=api_key, ) # 在这里替换成你需要的模型 ID model_id = "<model-id>" response = client.chat.completions.create( model=model_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 正确、余额充足，整个请求通常在几秒到几十秒内完成。

如果这一步出现错误，先不要急着改代码，按照下面顺序检查：

1. API Key 是否正确设置。
2. 网络到openrouter.ai是否连通。
3. 模型 ID 是否存在于模型列表。
4. 账号余额是否足够。
5. 请求频率是否超过限制。

5. 实战：将 OpenRouter 接入 Claude Code

5.1 Claude Code 环境变量方式

Claude Code 是 Anthropic 推出的命令行 AI 编程工具。默认情况下它连接 Anthropic 官方 API，但通过环境变量，可以让它使用兼容 Anthropic 接口的其他服务，OpenRouter 就支持这种方式。

在接入之前，先配置环境变量：

export ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1 export ANTHROPIC_AUTH_TOKEN=$OPENROUTER_API_KEY

说明：

• ANTHROPIC_BASE_URL告诉 Claude Code 向哪个地址发送请求。
• ANTHROPIC_AUTH_TOKEN设置认证 Token，这里使用 OpenRouter 的 API Key。

设置完成后，再启动 Claude Code：

claude

如果配置正确，Claude Code 会通过 OpenRouter 调用模型。你可以在交互界面中提问，观察是否得到正常回复。

需要注意的是，OpenRouter 的模型列表中，Anthropic 系列模型（例如 Claude 系列）的模型 ID 可能与官方不完全一致。你需要在 OpenRouter 模型页面中确认当前使用的模型 ID，并通过配置或命令行参数指定。很多情况下，Claude Code 会依赖ANTHROPIC_MODEL或默认模型配置，因此建议查阅你所用 Claude Code 版本对模型参数的支持情况。

5.2 使用 cc-switch 管理多 Provider

cc-switch 是一个社区工具，用于快速切换 Claude Code 的 API Provider 配置。它的价值在于：当你在 Anthropic 官方、OpenRouter、其他兼容平台之间切换时，不用每次手动修改环境变量。

使用 cc-switch 的一般思路是这样的：

1. 下载并安装 cc-switch，确认工具来源可信。
2. 在界面中新增一个 Provider 配置。
3. 填写 Provider 名称，例如OpenRouter-Makora。
4. 填写 API Base URL：https://openrouter.ai/api/v1。
5. 填写 API Key：你的 OpenRouter Key。
6. 选择要通过 OpenRouter 使用的模型 ID。
7. 保存并切换。

切换之后，cc-switch 会帮你更新 Claude Code 启动时使用的环境变量或配置文件。这样你可以在多个 Provider 之间一键切换，不需要每次都打开终端手动 export。

这里要提醒一点：cc-switch 属于第三方工具，它的界面和配置项会随版本更新。如果你的版本界面和网上教程不一致，以实际界面为准，原理都是修改 Claude Code 的 Base URL、Token 和 Model 配置。

5.3 验证接入是否成功

接入完成后，可以这样验证：

1. 在 Claude Code 中输入一个简单问题，例如“你好，请回复 OK”。
2. 观察是否正常回复。
3. 如果回复正常，再测试一个涉及代码生成的任务，检查模型是否具备工具调用能力。
4. 打开 OpenRouter 后台的请求记录页面，确认产生了对应模型的调用记录。

如果 Claude Code 没有任何输出，或者直接退出，可以尝试在前台运行并查看日志。很多情况下，问题不是配置本身，而是模型 ID 不支持工具调用，或 API Key 权限不足。

6. 常见问题与排查思路

下面整理几个从注册到调用过程中最高频的问题。

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_retries=3): 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的报错，说明账号余额不够支付本次请求。

处理方式：

1. 到 Billing 页面查看当前余额。
2. 小额充值后再试。
3. 检查代码中是否存在循环调用，避免意外消耗。
4. 为不同环境准备独立 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"

虽然本地跑起来方便，但一旦文件被提交到 Git，Key 就永久留在提交历史里了。正确做法是从环境变量读取。

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_url="https://openrouter.ai/api/v1", api_key=api_key, timeout=60.0, max_retries=2, )

这里的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 接入失败等高频问题，给出了排查方向和解决建议。

如果你想继续深入，建议按下面顺序学习：

1. 阅读 OpenRouter 官方 API 文档，了解请求头、响应字段和错误码。
2. 在 OpenRouter 后台查看模型列表和价格页面，掌握成本估算方法。
3. 研究provider路由参数，理解如何控制请求路由到指定服务商。
4. 为团队搭建一个统一的大模型接入层，把 Key 管理、重试、降级、日志都收口到一个模块中。

最后说一句实际的：在尝试“OpenRouter + Makora”之前，建议先用免费模型把整条链路跑通，确认账号、Key、网络、代码都没有问题，再切换到付费模型。这样既能控制成本，又能减少配置问题带来的干扰。如果这篇文章对你有帮助，可以收藏备用，遇到问题随时回来对照排查。