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 上用 launchd 守護 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-Hant/openrouter-api-guide/ 與 /en/openrouter-api-guide/（子目錄共享網域權重）
• 每個語言版本 canonical 指向自身，勿互相指
• 植入 BlogPosting + FAQPage JSON-LD 結構化資料

權重與外鏈層：繁體中文可在 Medium、Facebook 社團、PTT、Hacker News 繁體討論區分發；英文應在 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 分發：繁體→Medium/PTT/技術社團；英文→dev.to，視品質考慮 HN/Reddit；提交 sitemap 至 GSC 與 Google Search Console 繁體屬性

效果追蹤指標：

• GSC 按 /en/ 與 /zh-Hant/ 分別看 Impressions、CTR、平均排名——展現量為 0 是收錄問題，展現高 CTR 低是標題/描述問題
• Google Search Console 繁體屬性：收錄量、索引量、關鍵字排名
• 站內統計（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 推理後端解耦部署，模型可隨時切換而不影響執行時穩定性。