OpenRouter 保姆级教程：
从0到1接入 GPT / Claude / Gemini 全模型（2026 最新）

OpenRouter 是统一 LLM API 网关 / 聚合层：Endpoint 为 https://openrouter.ai/api/v1/chat/completions，认证方式为 Authorization: Bearer $OPENROUTER_API_KEY，协议兼容 OpenAI Chat Completions——已有 OpenAI SDK 代码基本不用改，只需换 base_url 和 api_key。模型命名规则为 供应商/模型名，例如 openai/gpt-4o、anthropic/claude-3.5-sonnet、google/gemini-2.5-pro、deepseek/deepseek-chat。

• 多账号碎片化：直连 OpenAI、Anthropic、Google、Meta、DeepSeek 各需一套 Key、SDK 与账单后台，原型阶段切换模型成本极高。
• 单点故障无容错：某一厂商限流或宕机时，业务代码需自行实现重试、切换供应商，工程复杂度高。
• 账单对账困难：5 个后台分别看 Token 消耗、延迟与成本，月结对账易出错。

OpenRouter 内部做两层独立路由决策，这是理解其技术价值的关键：

• 自动故障转移：主力供应商限流/报错时，OpenRouter 自动切换下一可用供应商或备选模型（models 数组），业务侧通常不会收到 500。
• 免费模型：25+ 免费模型（部分 Llama、Gemma、DeepSeek 免费档），未充值约 50 次/天，账户充值 ≥$10 后提升至 1000 次/天、20 次/分钟。
• 价格机制：OpenRouter 不在 token 单价上加价，按供应商原价透传；充值 Credits 时收 5.5%（最低 $0.80） 手续费，加密货币另收 5%。BYOK 模式每月前 100 万次 请求免费，超出后对等值部分收 5% 服务费。

官方文档与 FAQ 以 OpenRouter 站内为准，发版后请再次打开链接核对。

https://openrouter.ai/docs

https://openrouter.ai/docs/faq

• 一个 Key 打通所有模型：换模型 = 改一个 model 字符串，无需重写业务逻辑或为每个厂商写适配层。
• 跨供应商自动 Failover：内置重试 + 切换供应商 + 切换模型，业务代码无需自写 circuit breaker；可显式配置 models: ["anthropic/claude-3.5-sonnet", "openai/gpt-4o", "google/gemini-2.5-pro"] 形成 fallback 链。
• 统一账单和用量分析：一个 Dashboard 看所有模型消耗、成本、TTFT、吞吐量。
• 无 token 加价：同类聚合服务常在 token 单价上加价，OpenRouter FAQ 明确无 markup，仅充值环节收 5.5% 手续费；中大体量可用 BYOK 进一步降本。
• 场景边界清晰：适合快速原型、多模型 A/B 测试、中小体量（月消费几千美元以内）、需要 fallback 提升可用性、同一套 Prompt/Agent 跑遍市面模型的团队。

更适合直连官方 API 的场景：单一模型超大体量（月消费数万美元以上，5.5% 手续费已值得自建直连）；需要供应商专属能力（Anthropic Prompt Caching、OpenAI Batch/Assistants API、Google Vertex 工具链）；对延迟极度敏感（OpenRouter 网关约增加 10–80ms）；有数据合规/数据驻留要求，不允许流量经美国第三方中间层。

写「什么时候不该用」并非劝退，而是建立 E-E-A-T 信任，也是 AI 摘要最愿意引用的平衡视角——同时覆盖「OpenRouter vs 直连 API」等高转化长尾词。

1. 注册 OpenRouter 账号：访问 openrouter.ai，使用 GitHub 或邮箱注册。国内网络环境可能需要稳定代理访问控制台。
2. 创建 API Key：在 Settings → Keys 页面生成 Key，复制后存入环境变量 OPENROUTER_API_KEY，切勿提交到 Git 仓库。
3. （可选）充值 Credits：免费模型可零成本试用；调用付费模型需充值。充值 ≥$10 可解锁更高免费模型配额（1000 次/天）。
4. 选择目标模型：在 Models 页面浏览，或调用 GET /api/v1/models 获取完整列表，记下 provider/model 格式名称。
5. 发起第一次请求：用 curl 或 OpenAI SDK 向 https://openrouter.ai/api/v1/chat/completions 发送 POST，确认返回 choices[0].message.content。
6. 生产化配置：添加 HTTP-Referer 与 X-Title 请求头（OpenRouter 建议，用于排行榜统计）；配置 models fallback 链；在 Mac/Linux 用 launchd/systemd 守护 Agent 进程，避免笔记本休眠导致调用中断。

若你在 Mac 上运行 Cursor、OpenClaw 或自研 Agent，Gateway 与脚本应部署在7×24 在线的 macOS 主机上，OpenRouter 仅作为可替换的推理后端——这与模型选型同等重要。

cURL 直接请求：

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3.5-sonnet",
    "messages": [
      { "role": "user", "content": "用一句话解释什么是量子计算" }
    ]
  }'

Python（requests 原生写法）：

import requests
import os

response = requests.post(
    url="https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "google/gemini-2.5-pro",
        "messages": [
            {"role": "user", "content": "帮我写一个快速排序的 Python 实现"}
        ],
    },
)
print(response.json()["choices"][0]["message"]["content"])

Python（OpenAI SDK 零成本迁移——重点）：

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "HTTP-Referer": "https://calmvps.com",
        "X-Title": "CALMVPS Blog Demo",
    },
)
print(completion.choices[0].message.content)

Node.js（OpenAI SDK）：

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const completion = await openai.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "Explain OpenRouter in one sentence" }],
});
console.log(completion.choices[0].message.content);

流式输出（Streaming）：

const stream = await openai.chat.completions.create({
  model: "anthropic/claude-3.5-sonnet",
  messages: [{ role: "user", content: "写一首关于秋天的短诗" }],
  stream: true,
});
for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
}

多模型 Fallback 容灾配置：

{
  "model": "anthropic/claude-3.5-sonnet",
  "models": [
    "anthropic/claude-3.5-sonnet",
    "openai/gpt-4o",
    "google/gemini-2.5-pro"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Hello" }]
}

主模型被限流或报错时，OpenRouter 按顺序自动尝试列表中的下一个模型，业务侧无需额外重试逻辑。

查询可用模型列表：

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

• Endpoint：https://openrouter.ai/api/v1/chat/completions（OpenAI 兼容）
• 模型规模：70+ 供应商、400+ 模型（GPT、Claude、Gemini、Llama、DeepSeek、Qwen、Mistral 等）
• 免费额度：25+ 免费模型；未充值约 50 次/天；充值 ≥$10 → 1000 次/天、20 次/分钟
• 充值手续费：5.5%（最低 $0.80）；加密货币支付另收 5%
• BYOK：自带供应商 Key，每月前 100 万次请求免费，超出后对等值部分收 5% 服务费
• 网关延迟：相较直连官方 API 约增加 10–80ms 额外跳数（视区域与供应商而定）

各模型 prompt/completion 单价可在 OpenRouter Models 页面实时查询，价格随供应商调整，集成前请核对最新标价。

https://openrouter.ai/models

• OpenRouter 收费吗？不在 token 单价上加价；充值 Credits 时收 5.5% 手续费。25+ 免费模型可零成本试用。
• OpenRouter 国内能用吗？取决于网络环境；数据经美国第三方网关，有合规要求的企业应评估数据驻留。
• OpenRouter 支持哪些模型？400+ 模型，命名格式 provider/model，可通过 /api/v1/models 查询。
• OpenRouter 和 Claude 直连哪个好？多模型 + fallback + 统一账单选 OpenRouter；Prompt Caching、Batch API、极低延迟选直连。
• OpenRouter 一个月多少钱？完全按实际 Token 消耗计费，无固定月费；中小团队原型阶段月消费常在数十至数百美元。
• OpenRouter 安全吗？网关可见请求内容；敏感数据考虑 BYOK 或直连，并查阅隐私政策。
• OpenRouter 和 OpenAI 的区别？OpenRouter 是聚合网关，OpenAI 是单一模型供应商；OpenRouter 可调用 OpenAI 模型及其他厂商模型。
• 如何用 OpenRouter 搭建 AI 聊天机器人？后端用 OpenAI SDK 指向 OpenRouter Endpoint，前端 WebSocket/SSE 接收流式输出即可；Agent 逻辑与模型解耦。

若你在自建博客发布本篇类教程，中文有流量而英文几乎为零，通常是多层问题叠加——按性价比从高到低自查：

P0 抓取与索引层（最常被忽视）：

• CDN/WAF 拦截 Googlebot：国内 CDN + WAF 可能把海外 IP 或非常规 UA 判为攻击流量。用 Google Search Console「网址检查」实测抓取，比浏览器打开更可靠。
• hreflang 缺失：Google 可能只收录中文版为规范版本，英文版被视为重复内容。
• robots.txt / noindex 误配置：检查是否 disallow 了 /en/ 路径。
• sitemap 未分语言：中英文应各自列出并带 alternate 标注。
• CSR 空壳 HTML：纯前端渲染页面爬虫可能拿到空内容，需 SSR/SSG。

P1 内容层：

• 禁止中文直译英文：英文用户搜 "OpenRouter vs OpenAI API"、"is OpenRouter worth it"，而非 "OpenRouter Advantages"。标题、首段、H2、FAQ 问句须用英文原生表达重写。
• query fan-out 覆盖：2026 年 Google AI Mode 会把一次搜索拆成多个子问题（是什么、怎么用、多少钱、和谁比、安全吗、局限是什么），内容须全部覆盖。
• E-E-A-T：加入真实测试经验、账单截图、踩坑记录；纯 AI 生成内容排名明显更差。

中文 SEO 关键词矩阵（标题/H2/FAQ 须字面覆盖核心词）：

• 核心词：OpenRouter、OpenRouter API、OpenRouter 教程
• 中腰部：OpenRouter 怎么用、OpenRouter API 接入、OpenRouter 和 OpenAI 的区别、OpenRouter 免费模型
• 长尾问题：OpenRouter API Key 怎么获取、OpenRouter 国内能用吗、OpenRouter Python 怎么调用

英文 SEO 关键词矩阵（本地化重写，非直译）：

• 核心：OpenRouter API, OpenRouter tutorial, OpenRouter integration
• 对比类：OpenRouter vs OpenAI API, is OpenRouter worth it, OpenRouter alternatives
• How-to：OpenRouter Python example, OpenRouter OpenAI SDK drop-in replacement, OpenRouter fallback routing

双语站点技术架构建议：

• URL 结构：/zh/openrouter-api-guide/ 与 /en/openrouter-api-guide/（子目录共享域名权重）
• 每个语言版本 canonical 指向自身，勿互相指
• 植入 BlogPosting + FAQPage JSON-LD 结构化数据

权重与外链层：中文可在掘金、知乎、V2EX、CSDN 分发；英文应在 dev.to、Reddit（r/LocalLLaMA、r/programming）、Hacker News、Indie Hackers 获取初始外链。中文站积累的外链不会自动传导给英文页面。

可执行行动清单（按优先级）：

• P0 本周：Google Search Console 检查英文页抓取/索引；排查 CDN/WAF 是否拦截 Googlebot；补全 hreflang、canonical、独立 sitemap 条目
• P1 写作：中英文分别独立成稿（非直译）；关键词嵌入标题/首段/H2/FAQ；加入 Article + FAQPage Schema
• P2 分发：中文→掘金/知乎/V2EX；英文→dev.to，视质量考虑 HN/Reddit；提交 sitemap 至 GSC 与百度搜索资源平台

效果追踪指标：

• GSC 按 /en/ 与 /zh/ 分别看 Impressions、CTR、平均排名——展现量为 0 是收录问题，展现高 CTR 低是标题/描述问题
• 百度搜索资源平台：收录量、索引量、关键词排名
• 站内统计（Umami/Plausible/GA4）：分语言自然搜索流量、跳出率、阅读时长
• 每月无痕模式在 Google.com 搜索 3–5 个核心词，确认排名位置

回到 OpenRouter 本身：它在 Mac 上跑 Agent 时，Gateway、launchd、Skill 脚本需要 7×24 在线的 macOS 主机。笔记本合盖休眠、Linux VPS 无 Xcode/Metal、共享虚拟机资源争抢，是 Agent「半路失联」的常见根因——这与选哪个云端模型同等重要。

OpenRouter 适合快速验证多模型路由，但长期生产环境若需稳定 iOS CI/CD、OpenClaw Gateway 常驻与 AI Agent 自动化，CALMVPS 裸金属 Mac Mini 租赁提供更优解：独占 Apple Silicon、root 权限、7×24 在线、120 秒交付，Gateway 与 OpenRouter 推理后端解耦部署，模型可随时切换而不影响运行时稳定性。