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

OpenRouter 本質上是模型聚合層（Model Gateway）：你在應用裡只維護一組 API Key 與一個 Base URL，後端由 OpenRouter 把請求轉發到 Anthropic、OpenAI、Google、DeepSeek、Meta 等供應商。對外介面與 OpenAI Chat Completions API 相容，因此 LangChain、OpenAI SDK、Cursor、Aider 等工具通常只需改 base_url 與 model 字串即可切換全系模型。

核心端點為 POST https://openrouter.ai/api/v1/chat/completions；列舉模型用 GET https://openrouter.ai/api/v1/models。OpenRouter 另提供用量儀表板、按模型/供應商分帳，以及可選的 HTTP-Referer / X-Title 標頭用於排行榜歸因（公開文件建議帶上站點 URL 與應用名稱）。

• 帳號碎片化：每換一家模型就要申請 Key、配額與帳單，財務與合規審批週期被拖長。
• SDK 與端點不一致：雖然多數轉向 OpenAI 格式，但 Header、工具呼叫、串流事件仍可能有細微差異，Agent 框架難以「一行配置切模型」。
• 無 fallback 的單點故障：某供應商 429 或區域故障時，若沒有路由層，整條 Agent 鏈路直接中斷。
• 主機與 API 脫節：在超賣 VPS 上跑 7×24 Hermes / Claude Code 閘道，長連線重置比模型限流更常導致任務失敗；API 再穩也救不了抖動的主機。

OpenRouter 提供兩層路由語意，評審與 Runbook 裡應寫清楚用的是哪一種：

定價方面，OpenRouter 對各模型按供應商標價計費、不對 Token 加價；儲值時收取約 5.5% 信用卡手續費。若使用 BYOK（自帶各廠 Key），每月約 100 萬次 轉發請求可免 OpenRouter 轉發費（以官方方案為準）。免費模型池含 25+ 模型：未儲值約 50 次/日，儲值 $10 後約 1000 次/日 免費額度。

• 可引用資料點 1：OpenRouter 聚合 70+ 供應商、400+ 模型，單端點 OpenAI 相容。
• 可引用資料點 2：聚合層典型額外延遲約 10–80ms（視區域與供應商而異），極低延遲場景需實測。
• 可引用資料點 3：儲值手續費 5.5%；BYOK 方案約 100 萬次/月 免轉發費（官方條款為準）。

優勢一：一 Key 全系模型。 開發與 staging 環境只需管理一組 Secret，降低泄漏面與輪換成本。

優勢二：Token 不加價。 帳單按各模型公開單價累加，方便與直連報價對照；適合中小團隊先做路由實驗再談直簽。

優勢三：內建 fallback 與路由。 主模型 429 時自動切備援，減少 Agent 夜間無人值守失敗。

優勢四：OpenAI SDK 即插即用。 改 base_url 即可接入現有 LangChain / Vercel AI SDK 專案。

優勢五：統一用量與模型發現。 儀表板按模型聚合 spend，/models 端點可程式化發現新模型（如 DeepSeek V4 Flash）。

1. 01
   註冊並建立 Key：登入 OpenRouter 控制台，建立 API Key，寫入密鑰管理器（勿提交 Git）。可選儲值 $10 解鎖更高免費模型日額度。
2. 02
   選模型 ID：在 Models 頁複製 vendor/model 字串；編碼場景可從 deepseek/deepseek-chat 或 anthropic/claude-sonnet-4 開始。
3. 03
   發送 Chat Completions：Base URL 設為 https://openrouter.ai/api/v1，Authorization 為 Bearer YOUR_KEY。成功後在儀表板確認用量與單價。

curl 基本請求

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://your-app.example" \
  -H "X-Title: My Agent" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "用三句話解釋 OpenRouter 路由"}]
  }'

Python（requests）

import os, requests
r = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/gpt-4o",
        "messages": [{"role": "user", "content": "Hello"}],
    },
    timeout=60,
)
print(r.json()["choices"][0]["message"]["content"])

Python（OpenAI SDK + base_url）

from openai import OpenAI
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)
resp = client.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    messages=[{"role": "user", "content": "Summarize routing vs fallback"}],
)
print(resp.choices[0].message.content)

Node（OpenAI SDK）

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});
const completion = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Explain model routing" }],
});
console.log(completion.choices[0].message.content);

串流（Node）

const stream = await client.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "Stream this reply" }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Fallback 模型陣列

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

列舉模型

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

在請求 body 加入 provider 欄位可限制或排序供應商（詳見 OpenRouter 文件）。BYOK 模式下把各廠 Key 填入控制台，可在大流量時降低 OpenRouter 轉發費。Cursor / Claude Code 通常只需在設定裡把 OpenAI Base URL 改為 OpenRouter，並填寫模型別名表；長時 Agent 建議在獨佔 macOS 主機上用 launchd 常駐閘道，避免筆電休眠斷連。

若 NUKCLOUD 英文版或技術文 Google 曝光低，按下列項排查（與 OpenRouter 無關但常見於多語站）：

• Search Console：確認 /en/ 網址已驗證、無「已發現未索引」大量堆積。
• CDN / WAF：是否對 Googlebot 或美國 ASN 誤判 403；對比直連源站狀態碼。
• hreflang：列表頁是否宣告語系對應；詳情頁僅 canonical、不堆 hreflang（本站規範）。
• 機翻痕跡：英文 Title/H1 若與中文逐句對應，CTR 與停留時間常偏低；應重寫而非翻譯。
• 外鏈與引用：英文 DevRel、HN、Reddit 是否指向英文 canonical URL 而非中文預設。

雙語站應本地化而非翻譯：繁中讀者關心接入教程與國內合規；英文讀者關心 SDK 片段與 latency 數字。同一 slug 跨語系對齊，但 intro 與 FAQ 須獨立撰寫。

• URL 結構：https://nukcloud.com/{lang}/blog/{slug}.html，lang 為 zh、en、ja、zh-Hant 等八語系。
• Canonical：每篇詳情頁指向自身語系 URL；禁止詳情頁堆疊 hreflang（列表頁維護矩陣）。
• Sitemap：新文上線後跑 generate-sitemap.js，確保八語系同 slug 入圖。
• Schema：BlogPosting + FAQPage 嵌於 JSON-LD mainEntity；headline 不含 | NUKCLOUD。

核心 KPI：自然點擊、FAQ 富摘要展示、OpenRouter 相關查詢排名、下單頁轉化率。在 Matomo 為 CTA 與內鏈加事件，按月對比 zh-Hant 與 en 漏斗。

1. 01
   凍結路由表：主模型 + 2 個 fallback + 每任務 token 上限；敏感 repo 禁用免費 Stealth 模型。
2. 02
   Secret 管理：Key 只放 CI / 1Password；本地 .env 进 .gitignore；BYOK 各厂 Key 分租户存放。
3. 03
   撥備獨佔 Mac：經 下單頁 與 控制台 選區域；Agent 長連線需獨佔語意，見 生產就緒六步。
4. 04
   部署閘道：在實例上 launchd 常駐 OpenRouter 代理或 Hermes；Cursor Base URL 指向內網 HTTPS 反代。
5. 05
   可觀測：記錄 model id、latency、429 次數、fallback 觸發率；OpenRouter 儀表板與實例日誌對齊。
6. 06
   月度複盤：對比 API spend 與 定價頁 上 Mac 租用成本；若 7×24 Agent 頻繁斷線，優先換獨佔節點而非繼續加模型。

共享 macOS VPS 常見頻寬抖動、超賣與長連線重置，對 Claude Code 式「數千次工具呼叫、12 小時背景 Agent」尤其致命。需要可審計生產平面時，NUKCLOUD 多區域裸機 Mac / 雲端 Mac 節點在獨佔語意、SSH 基線與區域主鏈路上更易與採購、合規文件對齊；可從 定價頁 評估規格與租期。