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

OpenRouter 是统一 LLM API 网关：一个 Key、一个 OpenAI 兼容端点即可调用 70+ 供应商、400+ 模型。本文覆盖双层路由、定价与免费额度、curl/Python/Node.js 全套代码、多模型 fallback，以及中英双语 SEO 与 OpenClaw Agent 远程 Mac 7×24 部署建议。

1. OpenRouter 是什么：统一 LLM 网关、端点与双层路由机制

OpenRouter 是一个「统一 LLM API 网关 / 聚合层」：用一个 API Key + 一个 OpenAI 兼容 Endpoint，即可调用 GPT、Claude、Gemini、Llama、DeepSeek、Qwen、Mistral 等来自 70+ 家供应商、400+ 个模型 的能力，而不必为每个厂商单独注册账号、接入 SDK、管理账单。

• 统一 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

OpenRouter 内部做两件独立的路由决策——写文章时务必讲清，这也是它与简单代理的本质区别：

自动故障转移（Auto Failover）：主力供应商限流或报错时，OpenRouter 自动切换下一个可用供应商或备选模型（models 数组），业务侧不必自己写 circuit breaker。

免费模型：平台提供 25+ 免费模型（如部分 Llama、Gemma、DeepSeek 免费档）。未充值账户约 50 次/天（不计费）；账户充值 ≥$10 后免费模型额度提升至约 1000 次/天，并受约 20 次/分钟频率限制。

定价机制：OpenRouter 不在 token 单价上加价，按供应商原价透传；仅在充值购买 Credits 时收取 5.5%（最低 $0.80）手续费，加密货币支付另收 5%。BYOK（自带供应商 Key）模式下，每月前 100 万次请求免服务费，超出后对超出部分收 5% 服务费。

2. OpenRouter 五大核心优势与什么时候不该用

1. 一个 Key 打通所有模型：不必为 OpenAI、Anthropic、Google、Meta、DeepSeek 各注册一套账号与 SDK；换模型只需改 model 字符串。
2. 跨供应商自动 Failover：限流/宕机由网关层重试与切换，可显式配置 models fallback 链。
3. 统一账单与用量分析：一个 Dashboard 查看所有模型的消耗、成本、TTFT 与吞吐量。
4. 无 token 加价：中大体量可用 BYOK 进一步压低成本。
5. 场景明确：适合多模型 A/B、Agent 框架、中小体量应用与快速原型。

更适合直连官方 API 的场景（看似「劝退」，却是建立 E-E-A-T 的关键）：

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

3. OpenRouter vs 直连 OpenAI / Anthropic / Google API 对比表

若你已在 OpenClaw 上做多模型路由，可对照《OpenRouter 分层竞争与 OpenClaw 路由决策》与《2026 Top10 选型矩阵》做模型分层。

4. 多厂商接入的三类痛点（编号式拆解）

痛点一：N 个厂商 = N 套集成债务。 每接入一家就要维护认证、限流处理、错误码映射与账单对账；Agent 框架换模型时，Prompt 与 tool schema 还要逐个验证兼容性。OpenRouter 把「换模型 = 改字符串」变成现实，但你要接受网关层延迟与合规边界。

痛点二：单点限流拖垮整条 Agent 链路。 生产里 429/5xx 若只在应用层重试，用户侧表现为「已读不回」。OpenRouter 的 Provider Routing + models fallback 把容错下沉到网关，适合 OpenClaw、Hermes 等长时 Agent——前提是网关进程本身 7×24 在线。

痛点三：成本与合规的「黑盒感」。 多后台对账、免费档 stealth 模型记录 Prompt、数据经美国中间层——中小团队容易低估隐性风险。选型时必须同时看 token 账单、充值手续费与数据出境政策，不能只看「一个 Key 真香」。

5. 三步快速接入 + 五步 HowTo 实操

三步快速接入（TL;DR）

1. 注册并创建 Key：openrouter.ai → Keys → 生成 API Key，写入 .env。
2. 改两行配置：OPENROUTER_API_KEY + OpenAI SDK base_url="https://openrouter.ai/api/v1"。
3. 发第一次请求：POST /v1/chat/completions，model 设为 anthropic/claude-3.5-sonnet 或任意目标模型。

五步详细 HowTo（与 JSON-LD 对齐）

1. 注册 OpenRouter 账号：GitHub 或邮箱注册，完成验证；建议开启用量告警。
2. 充值或确认免费额度：原型期可先用 25+ 免费模型；生产 Agent 建议预充 ≥$10 解锁更高免费档与稳定付费路由。
3. 创建 API Key：Dashboard → Keys，按项目拆分 Key，设置 spend limit；切勿把 Key 写进前端或公开仓库。
4. 配置环境：本地或 CI 设置 OPENROUTER_API_KEY；OpenClaw 用户写入 openclaw.json 的 SecretRef，参考《credentials 分层排障》。
5. 验收第一次调用：用下方 curl 或 Python 示例请求，确认 HTTP 200 与 choices[0].message.content；Agent 场景再跑 openclaw doctor 与 channels probe。

6. 代码示例：curl / Python / Node.js / OpenAI SDK / 流式 / Fallback / models 列表

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 零成本迁移——重点）

import os
from openai import OpenAI

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://sftpmac.com",
        "X-Title": "SFTPMAC OpenRouter 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（容灾）JSON 配置

{
  "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"

7. 英文页面流量低：抓取 / 内容 / 外链三层诊断清单

自建博客英文页流量低，通常是多层问题叠加。建议按下列顺序自查（同样适用于 SFTPMAC 双语站运营者）：

7.1 抓取与索引层（优先级最高）

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

7.2 内容层

• 英文内容是中文直译，关键词与句式不匹配英文开发者搜索习惯（应搜 "OpenRouter vs OpenAI API" 而非直译「优势」）。
• 缺少独立英文关键词研究；E-E-A-T 不足——无作者信息、无真实测试数据，像内容农场。

7.3 权重与外链层

• 中文站在掘金/知乎/V2EX 有分发，英文几乎未在 dev.to、Hacker News、Reddit 分发，英文页零外链。
• 新域名信任度低，需持续更新 + 外链 + 正确技术 SEO 才能提高抓取频率。

修复顺序（性价比从高到低）：GSC 索引报告 → CDN/WAF 模拟 Googlebot → 补齐 hreflang/canonical/sitemap → 本地化重写 3–5 篇英文重点文 → dev.to / HN / Reddit 首批分发。

8. 中文 SEO 策略：关键词矩阵、标题信号词与 Meta 模板

标题信号词（本页 H1 已组合「保姆级教程」「从0到1」「2026最新完整指南」）：完整度型（完整指南、全攻略）+ 门槛型（保姆级、手把手）+ 时效型（2026最新）可显著提升 CTR；社交平台分发可换「避坑型」标题做 A/B。

Meta Description 模板（已应用于本页 head）：150–160 字符，含核心词 + 行动号召 +「保姆级/真实踩坑」等信任词。百度需标题/首段/H2 字面出现核心词；豆包/DeepSeek AI 搜索则要求主题集群语义完整——两者都要兼顾。

9. 英文 SEO 策略摘要（双语站运营者必读）

英文读者搜索更偏完整问句与对比意图：OpenRouter vs OpenAI API、is OpenRouter worth it、OpenRouter OpenAI SDK drop-in replacement。标题信号词对应关系：Complete Guide / Beginner's Guide（完整度/门槛）、Step-by-Step（从0到1）、Honest Review（避坑）——不要直译中文「保姆级」，且避免 Ultimate+Complete+Beginner 堆砌被判 clickbait。

英文正文结构建议：首段 TL;DR 定义块 → 对比表格 → When NOT to use → 可运行代码 + 真实价格数字 → FAQ 用口语问句（"Is OpenRouter free?"）。技术 SEO 专项：GSC 按 /en/ 过滤 impressions；Rich Results Test 模拟 Googlebot；英文 canonical 指向自身；sitemap 分语言 + hreflang alternate。

SFTPMAC 英文版姊妹文路径：/en/blog/20260724-openrouter-api-tutorial-gpt-claude-gemini-integration-guide-2026.html，应与中文版独立撰写、仅共享代码与数据。

10. 双语站点技术架构：hreflang、URL、canonical 与 sitemap

推荐 URL 结构（子目录共享域名权重）：

https://sftpmac.com/zh/blog/20260724-openrouter-baomuji-jiaocheng-api-jieru-gpt-claude-gemini-juece-zhinan.html
https://sftpmac.com/en/blog/20260724-openrouter-api-tutorial-gpt-claude-gemini-integration-guide-2026.html

hreflang 标注示例（两语言页面 <head> 中互相声明）：

<link rel="alternate" hreflang="zh-Hans" href="https://sftpmac.com/zh/blog/20260724-openrouter-baomuji-jiaocheng-api-jieru-gpt-claude-gemini-juece-zhinan.html" />
<link rel="alternate" hreflang="en" href="https://sftpmac.com/en/blog/20260724-openrouter-api-tutorial-gpt-claude-gemini-integration-guide-2026.html" />
<link rel="alternate" hreflang="x-default" href="https://sftpmac.com/en/blog/20260724-openrouter-api-tutorial-gpt-claude-gemini-integration-guide-2026.html" />

canonical：每个语言版本指向自身，不要中文 canonical 指英文或反之。本页 canonical 已设为 zh 完整 URL。

sitemap：中英文各自独立 <url>，并用 <xhtml:link rel="alternate" hreflang="..." /> 声明对应版本，便于爬虫一次性发现双语页面。

11. 发布与分发渠道清单

12. P0 / P1 / P2 可执行行动清单

P0（本周内，止血 / 排查）

• Google Search Console 检查英文页真实抓取与索引状态
• 排查 CDN/WAF 是否拦截 Googlebot / 海外流量
• 补全 hreflang、canonical、独立 sitemap 条目

P1（写作与发布）

• 按大纲分别撰写中文版与英文版（英文本地化重写，非直译）
• 关键词自然嵌入标题、首段、H2、FAQ
• 加入 BlogPosting + HowTo + FAQPage 结构化数据

P2（分发与追踪）

• 中文版分发掘金 / 知乎 / V2EX
• 英文版分发 dev.to，视质量考虑 HN / Reddit
• 两语言 sitemap 提交 GSC 与百度搜索资源平台

13. 效果追踪指标

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

14. 常见问题 FAQ

Q：OpenRouter 收费吗？ 付费模型按 token 原价计费；充值 Credits 收 5.5%（最低 $0.80）。25+ 免费模型未充值约 50 次/天，充值 ≥$10 后约 1000 次/天。

Q：OpenRouter 国内能用吗？ 通常可访问 API，但延迟与稳定性因网络而异；生产需监控重试并评估数据出境合规。

Q：OpenRouter 支持哪些模型？ 70+ 供应商、400+ 模型；用 GET /v1/models 或 Dashboard 查询。命名格式 vendor/model。

Q：OpenRouter 安全吗？ 流量经网关转发至供应商；涉密数据需评估中间层与 BYOK；勿把 Key 暴露在前端。

Q：OpenRouter 和直连 API 怎么选？ 多模型/fallback/原型选 OpenRouter；超大体量、官方专属能力、极低延迟或硬合规选直连。见上文对比表。

Q：会在 token 上加价吗？ 不会；仅充值环节 5.5% 手续费，BYOK 每月前 100 万次免服务费。

Q：Python 怎么调用？ requests 直 POST 或 OpenAI SDK 改 base_url，见第 6 节代码。

Q：和 OpenClaw 怎么配合？ 在 openclaw.json 配置 OpenRouter provider 与主备模型，网关放常在线 Mac 并跑 doctor/probe 验收。

15. 总结：OpenRouter 的价值、局限与远程 Mac 7×24 Agent 部署

OpenRouter 把「多厂商 LLM 集成」压缩成一个 Key、一个 Endpoint、改一行 model 字符串——对 OpenClaw/Hermes 等多模型 Agent、A/B 测试与中小体量应用，迁移成本几乎为零。双层路由（Model + Provider）与内置 Failover 让业务代码不必重复写限流切换；无 token 加价与 25+ 免费模型降低了原型门槛。

但它不是银弹：网关增加约 10–80ms 延迟；充值 5.5% 手续费在大体量下会逼你回归直连；流量经美国中间层可能触碰合规红线；免费 stealth 模型不适合敏感 Prompt。本地笔记本跑 Agent 还会因休眠导致通道超时——OpenRouter 再稳也救不了间歇离线的网关。

若你要把 OpenRouter 接进 OpenClaw 做 7×24 生产 Agent，下一步应让网关、工作区与 API Key 管理落在常在线的 macOS 节点，用 SFTP/rsync 同步配置与制品，并配合 launchd 守护与 channels probe 验收。SFTPMAC 远程 Mac 租赁提供面向 OpenRouter / OpenClaw 的 Apple Silicon 环境：低延迟回调、原生守护进程、以及与站内 OpenRouter 选型、gateway restart、生产安全专文衔接的运维基线——比「家用电脑兼 API 网关」更适合把统一 LLM 路由当生产基础设施的团队。