OpenRouter 保姆级教程
从 0 到 1 接入 GPT/Claude/Gemini 全模型

多厂商 API 碎片化：接入统一网关前的五类痛点

OpenRouter 本质是统一 LLM API 网关（Unified LLM Gateway）：你只需维护一把 API Key，即可通过 OpenAI 兼容协议访问 OpenAI、Anthropic、Google、DeepSeek 等厂商模型，无需为每家单独写鉴权与 SDK 适配层。但在决定迁移前，应先认清「直连多厂商」在生产里常见的五类隐性成本 🔧

1. 01

   多 Key 轮换税：GPT、Claude、Gemini 各需独立账号与账单，Key 泄露轮换、配额监控与告警分散在三套控制台，运维面指数膨胀。

2. 02

   SDK 方言税：虽多数支持 OpenAI 格式，但 base_url、Header（如 Anthropic 版本号）、流式字段与 tool call schema 仍有差异，Agent 框架切换模型时要改多处。

3. 03

   Failover 手写税：主模型 429 或宕机时需自写重试链、指数退避与备模型映射；缺统一路由层时，每次加新模型都要改业务代码。

4. 04

   定价对账税：各厂商计价单位、缓存折扣与 batch 规则不同，FinOps 难以在一张表里对比「同一 prompt 换模型贵多少」。

5. 05

   免费额度分散税：各平台免费 tier 规则不一；OpenRouter 聚合 25+ 免费模型并统一配额（未充值 50 次/日，充值 $10 后 1000 次/日，20 次/分钟），但需理解平台费与 BYOK 边界。

认清以上痛点后，再对照下一节的路由机制与对比表，判断 OpenRouter 是否匹配你的延迟、合规与调用量级假设。

六步 Runbook：从注册到 fallback 链验证

以下六步可在 30 分钟内完成首次调用；每步产出可写入团队 README，便于 onboarding 新成员。

1. 01

   注册账号：访问 openrouter.ai，用 GitHub 或邮箱创建账户。

2. 02

   创建 API Key：进入 Keys 页面生成 Key，立即复制；生产环境勿提交到 Git，用密钥管理服务托管。

3. 03

   设置环境变量：export OPENROUTER_API_KEY="sk-or-..."，CI/CD 与本地 .env 保持一致命名。

4. 04

   首次 curl 验证：对 /v1/chat/completions 发 POST，确认 200 与 choices[0].message 结构。

5. 05

   配置 OpenAI SDK：Python/Node 中将 base_url 指向 OpenRouter，可选加 HTTP-Referer 与 X-Title 参与排行榜统计。

6. 06

   测试 fallback 链：用 models 数组或故意指定不可用模型，验证 auto failover 到备模型并记录日志。

curl 首次请求

curl 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": "user", "content": "Hello from OpenRouter"}]
  }'

Python requests

import os, requests

resp = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "anthropic/claude-sonnet-4",
        "messages": [{"role": "user", "content": "Explain Model Routing vs Provider Routing"}],
    },
)
print(resp.json()["choices"][0]["message"]["content"])

Python OpenAI SDK（含 HTTP-Referer / X-Title）

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
    default_headers={
        "HTTP-Referer": "https://your-app.example.com",
        "X-Title": "My Agent App",
    },
)

completion = client.chat.completions.create(
    model="google/gemini-2.5-pro-preview",
    messages=[{"role": "user", "content": "Summarize OpenRouter pricing"}],
)
print(completion.choices[0].message.content)

Node.js OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultHeaders: {
    "HTTP-Referer": "https://your-app.example.com",
    "X-Title": "My Agent App",
  },
});

const res = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(res.choices[0].message.content);

JavaScript 流式输出

const stream = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Stream this response" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Fallback 模型链（JSON）

{
  "model": "openai/gpt-4o",
  "models": [
    "openai/gpt-4o",
    "anthropic/claude-sonnet-4",
    "google/gemini-2.5-flash-preview"
  ],
  "messages": [{"role": "user", "content": "If primary fails, try fallbacks"}]
}

curl 拉取模型列表

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | jq '.data[] | {id, pricing}'

可引用硬数据、开发者 SEO 与生产部署收束

下列参数可直接引用进技术方案或 README；来源为 OpenRouter 官方文档与平台公开数据（2026 年 7 月）。

• 提供商规模：70+ inference 提供商聚合在同一网关后。
• 模型数量：400+ 模型，命名规范 vendor/model。
• 免费模型：25+ 模型；未充值 50 次/日，充值 $10 后 1000 次/日，20 次/分钟。
• 平台费：充值 5.5%（最低 $0.80）；BYOK 100 万 req/月免费档，超出 5%。
• 延迟 overhead：相较直连，通常增加 10–80ms（视区域与 provider 而定）。

面向开发者的双语 SEO / 英文流量诊断

若你的 Agent 产品或技术博客需要同时触达中英文开发者，OpenRouter 类 API 文档的 SEO 需注意以下工程实践（而非简单机翻）：

• hreflang 矩阵：中英页面应互指 canonical 与 hreflang；避免同一 URL 混两种语言导致 Google 判 duplicate。
• CDN / WAF 与 Googlebot：部分国内 CDN 默认规则会误拦海外爬虫；用 Search Console「URL 检查」确认英文页可被 Googlebot 抓取，而非仅 200 给人看。
• 禁止机翻英文：英文页应用母语技术写作重写（术语、代码注释风格、搜索词），不要用中文正文一键翻译——EEAT 与 bounce rate 会同时受损。
• 关键词矩阵：中文偏「OpenRouter 教程 / 接入 / 免费模型」；英文偏 “OpenRouter API guide”, “unified LLM gateway”, “OpenAI compatible multi-model”；代码示例中的 model ID 保持全球一致。

OpenRouter 解决了「多模型 API 统一接入」，但本地开发机在休眠、系统更新与进程被杀时会让 7×24 Agent、cron 与 webhook 回调中断——API Key 再稳定，宿主不稳定仍会导致 failover 链空转。笔记本合盖后 OpenClaw、LangGraph 或自研 daemon 无法保证 SLA；纯 Linux VPS 又缺 Apple Silicon 与 macOS 工具链。对需要长期在线的 AI Agent 与自动化流水线，VpsMesh 的 Mac Mini 云端租赁通常是更优解：专用节点、弹性租期、可审计环境，让 OpenRouter 路由策略跑在真正 7×24 在线的宿主上，而不是赌本地机器今晚不合盖。