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

約 18 分鐘閱讀 · MACCOME · 2026 年 7 月 24 日

適合誰讀？需要同時呼叫 GPT、Claude、Gemini 的 AI 開發者、獨立開發者，以及經營雙語技術部落格的 SEO 從業者。結論先行：OpenRouter 用一組 API Key 與 OpenAI 相容 Endpoint 即可存取 70+ 供應商、400+ 模型，換模型只需改 model 字串。本文包含：六大痛點、路由原理表、OpenRouter vs 直連對比、五優勢與不該用場景、curl/Python/Node 程式碼、定價、英文流量診斷、雙語 SEO、P0–P2 清單與 FAQ。

OpenRouter API 接入：開發者常見的六大痛點

多模型 Agent 時代，「每換一個模型就重寫一套 SDK」是隱性成本。以下六點是團隊在評估 OpenRouter API 前最常卡關的地方：

  1. 多帳號、多 Key、多帳單。OpenAI、Anthropic、Google 各需註冊、各管額度，FinOps 對帳成本高。
  2. 供應商限流即業務中斷。單一廠商 429/5xx 時，應用程式若未自建 circuit breaker，使用者直接看到錯誤。
  3. 模型切換=重構。不同 SDK 訊息格式、工具呼叫、串流處理不一致，A/B 測試成本被低估。
  4. 延遲與合規取捨不清。聚合閘道約增加 10–80ms 跳數；資料不可經美國中間層時，OpenRouter 並非正解。
  5. 定價誤解。「5.5% 手續費」常被誤以為加在 token 單價上；實際只在充值 Credits 時收取。
  6. 雙語站英文流量低。中文直譯英文、hreflang 缺失、CDN 攔截 Googlebot 等技術 SEO 問題疊加，英文頁幾乎零收錄（見下文診斷清單）。

OpenRouter 是什麼？路由機制一次講清

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。也可用 openrouter/auto 自動選模。

決策層決定什麼控制欄位
模型路由（Model Routing）由哪個模型回答model 或 openrouter/auto
供應商路由（Provider Routing）同一模型由哪家機房處理provider 物件；預設按價格倒平方加權
自動容災（Fallback）主力限流時切換備援models 陣列 + route: "fallback"

OpenRouter 和直接呼叫 OpenAI / Anthropic API 有什麼區別？

維度OpenRouter直連官方 API
接入成本一組 Key、一個 Endpoint每廠商各註冊、各 Key、各 SDK
模型切換改 model 字串即可常需改 SDK 與適配層
容災內建跨供應商 Failover需自建重試與 circuit breaker
延遲閘道約 +10–80ms通常更低
定價token 原價透傳；充值 5.5% 手續費無中間層手續費；大用量可談企業價
專屬能力通用 Chat CompletionsBatch API、Assistants、Prompt Caching、Vertex 工具鏈等
合規流量經第三方閘道可選資料駐留與企業合約

更完整的選型框架見 OpenRouter 多模型路由決策矩陣。

OpenRouter 的五個核心優勢與「什麼時候不該用」

五個核心優勢

  1. 一組 Key 打通所有模型——遷移成本接近零，換模型不改業務邏輯。
  2. 跨供應商自動 Failover——限流/宕機由閘道層處理，無需自建熔斷器。
  3. 統一帳單與 Dashboard——一次查看所有模型的 token、成本、TTFT。
  4. 無 token 加價——按供應商原價；BYOK 每月前 100 萬次請求免服務費。
  5. 25+ 免費模型——快速原型與 A/B 測試成本低（見定價表）。

更適合直連官方 API 的場景

  • 單一模型、月消費數萬美元以上——5.5% 充值手續費已值得自建直連。
  • 需要 Anthropic Prompt Caching、OpenAI Batch/Assistants、Google Vertex 專屬工具。
  • 延遲極度敏感（即時語音、高頻交易輔助）。
  • 資料合規／資料駐留不允許經美國第三方中間層。

OpenRouter 定價說明：免費額度、Credits 與 BYOK

項目規則
免費模型25+ 模型；未充值約 50 次/天；充值 ≥$10 後 1000 次/天、20 次/分鐘
付費模型按供應商原價計 token；無 token markup
充值手續費5.5%（最低 $0.80）；加密貨幣另收 5%
BYOK自帶供應商 Key；每月前 100 萬次請求免服務費，超出後對等值收 5%

OpenRouter API 程式碼範例：curl / Python / Node / 串流 / Fallback

cURL 基礎請求

bash
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（OpenAI SDK 零成本遷移——重點）

python
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://maccome.com",
        "X-Title": "MACCOME Blog Demo",
    },
)
print(completion.choices[0].message.content)

Node.js（OpenAI SDK）

javascript
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）

javascript
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" }]
}

查詢可用模型清單

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

提示：在 Agent 閘道（如 OpenClaw 多供應商路由）中，OpenRouter 可作為統一 upstream；Failover 鏈應與 Gateway 設定對齊，避免雙重重試。

六步 Runbook：從註冊到第一次 API 呼叫

  1. 註冊 OpenRouter 帳號——前往 openrouter.ai，完成 Email 驗證。
  2. 建立 API Key——在 Keys 頁面產生 Key，存入密鑰管理器（勿寫入版本庫）。
  3. （可選）充值 Credits——需付費模型或提升免費額度時充值 ≥$10；記住 5.5% 僅在充值環節。
  4. 設定環境變數——export OPENROUTER_API_KEY=sk-or-... 於本機或 CI 密鑰庫。
  5. 用 curl 驗證連通——先跑通 claude-3.5-sonnet 或免費模型，確認 HTTP 200。
  6. 接入 OpenAI SDK——改 base_url 與 api_key，加上 HTTP-Referer 標頭；部署至 7×24 執行環境（見收束段落）。
  7. 配置 Fallback 鏈——生產環境設定 models 陣列，覆蓋主力限流場景。

為什麼英文頁流量低？診斷清單（抓取 / 內容 / 外鏈）

抓取與索引層（優先排查）

  • CDN/WAF 攔截 Googlebot——用 Search Console「網址檢查」模擬抓取，比瀏覽器開啟更可靠。
  • 缺少正確 hreflang——Google 可能只收錄中文版，英文被視為重複內容。
  • robots.txt 誤封 /en/ 或 sitemap 未分語言列出。
  • 純 CSR 空殼 HTML——爬蟲拿不到正文，長期不索引。

內容層

  • 英文是「中文直譯」——應對齊 "OpenRouter vs OpenAI API" 等原生搜尋詞，而非 "OpenRouter Advantages"。
  • E-E-A-T 不足——缺作者、缺真實測試數據，易被降權。

修復順序（性價比由高到低）

  1. Search Console 確認英文頁是否被抓取。
  2. 排查 CDN/WAF 日誌。
  3. 補齊 hreflang、canonical、sitemap 分語言標註。
  4. 本地化重寫 3–5 篇重點英文文（非機翻）。
  5. 在 dev.to / Reddit / Hacker News 做首批分發。

中文 SEO 策略：關鍵詞矩陣與結構化資料

核心詞（標題/H1）：OpenRouter、OpenRouter API、OpenRouter 教學。中腰部（H2）：OpenRouter 怎麼用、和 OpenAI 的區別、免費模型、收費嗎。長尾（FAQ）：API Key 怎麼取得、國內能用嗎、Python 怎麼呼叫、安全嗎。

百度需標題、首段、H2 原樣出現核心詞；同時覆蓋 AI 搜尋的語義集群。文末 FAQ 必配 FAQPage JSON-LD（本文已植入）。

雙語站技術架構：hreflang / canonical / sitemap

MACCOME 採 /zh/、/en/、/zh-Hant/ 等子目錄結構。每語言版本 canonical 指向自身；hreflang 互相宣告 8 語（本文 head 已含）。sitemap 中各語言 URL 獨立列出並帶 alternate 標註。

發布與分發渠道

渠道語言用途
掘金 / V2EX / 知乎 / CSDN中文教程分發、技術外鏈
dev.to英文教程類自然流量，可帶 canonical 回主站
Hacker News / Reddit英文深度內容、垂直社群
X（Twitter）中英短摘要曝光、初始點擊信號

P0–P2 行動清單與效果追蹤

P0（本週：止血）

  • Search Console 檢查英文頁抓取/索引。
  • 排查 CDN/WAF 是否攔截 Googlebot。
  • 補全 hreflang、canonical、獨立 sitemap 條目。

P1（寫作發布）

  • 中英文分別獨立成稿（共享程式碼、本地化論述）。
  • 關鍵詞嵌入標題、首段、H2、FAQ。
  • 植入 BlogPosting + FAQPage Schema。

P2（分發追蹤）

  • 中文分發掘金/知乎；英文分發 dev.to。
  • 分別提交 sitemap 至 Google 與百度資源平台。

追蹤指標

  • GSC：按 /en/ 與 /zh/ 看 Impressions——0 展現=收錄問題；高展現低 CTR=標題/描述問題。
  • 站內統計：分語言自然搜尋、跳出率、閱讀時長。
  • 每月無痕搜尋 3–5 個核心詞，確認排名。

三組可引用硬數據

  • 70+ 供應商、400+ 模型——一 Endpoint /v1/chat/completions 統一接入（OpenRouter 官方文件）。
  • 25+ 免費模型——未充值 50 次/天，充值 ≥$10 後 1000 次/天（官方 FAQ）。
  • 充值 5.5% 手續費、無 token markup——BYOK 每月前 100 萬次免服務費（定價頁）。

總結：OpenRouter 適合多模型原型，生產 Agent 需要穩定執行環境

OpenRouter 解決了「多 Key、多 SDK、無 Failover」的接入痛點，是 2026 年多模型 Agent 的高性價比起點。但筆電合蓋會中斷 MCP 長連線、本地 sleep 策略無法保證 7×24 Cron Agent、CI 與本機混跑難以重現生產路由——這些是 OpenRouter 本身解決不了的執行環境問題。

若你已在 OpenRouter 上跑 Claude Code、OpenClaw Gateway 或自研 Agent，將 runtime 釘在 MACCOME 雲端 Mac mini（M4/M4 Pro）專用節點，通常比在本機筆電上折騰 sleep 與網路更穩。詳見 雲端 Mac 租用價格 與 OpenRouter CLI 工具排行選型。

最後更新：2026 年 7 月 24 日 | 參考：OpenRouter 官方文件

常見問題

OpenRouter 要收費嗎？

有 25+ 免費模型（未充值約 50 次/天）。付費模型按供應商原價計 token，OpenRouter 不在 token 上加價；充值 Credits 時收 5.5% 手續費（最低 $0.80）。

OpenRouter 和直接呼叫 OpenAI API 有什麼區別？

OpenRouter 提供統一 Endpoint 與跨供應商 Failover；直連延遲更低且可存取 Batch/Assistants 等專屬 API。月消費數萬美元以上或合規要求高時，直連通常更划算。

OpenRouter Python 怎麼呼叫？

用 OpenAI SDK，設定 base_url="https://openrouter.ai/api/v1" 與 OPENROUTER_API_KEY 即可；完整程式碼見上文第 6 節。

OpenRouter 國內能用嗎？

OpenRouter 為海外服務，需自行評估網路與合規。若資料不可經美國第三方閘道，應選直連或私有部署。

OpenRouter 安全嗎？資料會外洩嗎？

請求會經 OpenRouter 閘道路由至底層供應商。敏感資料應查閱各供應商 DPA；高合規場景考慮 BYOK 或直連。

如何在 Mac 上穩定跑 OpenRouter Agent？

避免筆電合蓋中斷 Agent。MACCOME 提供 M4/M4 Pro 雲端 Mac 節點，適合 7×24 執行；詳見 雲端 Mac 租用價格。

雙語部落格英文流量為什麼低？

常見原因：hreflang 缺失、CDN 攔截 Googlebot、英文內容為中文直譯。按本文 P0 清單先確認索引，再本地化重寫英文標題與 FAQ。