2026 OpenRouter 保姆級教學：API 接入 GPT／Claude／Gemini 全模型決策指南

若您同時維護 OpenAI、Anthropic、Google、DeepSeek 多套 API 金鑰，早已熟悉五個後台、五套帳單與五種限流處理的負擔。OpenRouter 以統一 LLM API 閘道把這一切收斂為一組 Key、一個 OpenAI 相容端點，即可呼叫 GPT、Claude、Gemini 與 400+ 模型。本文以繁體中文獨立撰寫，涵蓋雙層路由、五大優勢與何時不該用、直連 API 決策表、curl／Python／Node.js 範例、定價與 FAQ，並說明 OpenClaw Agent 為何宜託管在常線上遠端 Mac 伺服器。

1. OpenRouter 是什麼：統一 LLM API 閘道、端點與雙層路由

OpenRouter 是「統一 LLM API 閘道／聚合層」：以一組 API Key + 一個 OpenAI 相容 Endpoint，即可呼叫來自 70+ 供應商、400+ 模型 的能力，而不必為每家廠商分別註冊帳號、接入 SDK、管理帳單。

• 統一端點：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-sonnet-4、google/gemini-2.5-pro

OpenRouter 在每次請求中做兩件獨立的路由決策——這也是它與簡單代理的本質差異：

主力供應商限流或報錯時，OpenRouter 可自動切換下一個可用供應商或備選模型（models 陣列），業務端不必自行實作 circuit breaker。模型清單可對照《OpenRouter 分層競爭與 OpenClaw 路由決策》與《2026 Top10 選型矩陣》。

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 的場景（誠實說明局限，才能做出正確決策）：

• 單一模型、超大体量（月消費數萬美元以上），5.5% 充值手續費已值得自建直連
• 需要供應商專屬能力：Anthropic Prompt Caching、OpenAI Batch API、Google Vertex 工具鏈
• 對延遲極度敏感——OpenRouter 閘道通常增加約 10–80ms 額外跳數
• 資料合規／資料駐留要求，不允許流量經過美國第三方中間層
• 涉密 Prompt 不應走記錄政策不明的免費 preview 模型

3. OpenRouter vs 直連 OpenAI／Anthropic／Google API 對比表

4. 多供應商接入的三類痛點（編號式拆解）

痛點一：N 家供應商 = N 套整合債務。 每接入一家就要維護認證、限流處理、錯誤碼對映與帳單對帳；Agent 框架換模型時，Prompt 與 tool schema 還要逐個驗證相容性。OpenRouter 把「換模型 = 改字串」變成現實，但您需接受閘道層延遲與合規邊界。

痛點二：單點限流拖垮整條 Agent 鏈路。 生產環境 429／5xx 若只在應用層重試，使用者側表現為「已讀不回」。OpenRouter 的 Provider Routing + models fallback 把容錯下沉到閘道——前提是閘道程序本身 7×24 在線，且伺服器記憶體與頻寬足以支撐長時工具迴圈。

痛點三：成本與合規的「黑盒感」。 多後台對帳、免費 preview 模型的 Prompt 記錄、資料經美國中間層——中小團隊容易低估隱性風險。選型時必須同時看 token 帳單、充值手續費與資料出境政策。

5. 五步 HowTo：從註冊到第一次 chat/completions 呼叫

1. 註冊 OpenRouter 帳號：前往 openrouter.ai，以電子郵件或 OAuth 註冊；建議開啟用量告警。
2. 確認免費額度或充值：原型期可先用 25+ 免費模型；生產 Agent 建議預充 ≥$10 解鎖更高免費檔與穩定付費路由。
3. 建立 API Key：Dashboard → Keys，按專案拆分 Key 並設定 spend limit；切勿把 Key 寫進前端或公開儲存庫。
4. 設定環境：本機或 CI 匯出 OPENROUTER_API_KEY；OpenClaw 使用者寫入 openclaw.json 的 SecretRef。
5. 驗收第一次呼叫：用下方 curl 或 Python 範例請求，確認 HTTP 200 與 choices[0].message.content。

export OPENROUTER_API_KEY="sk-or-v1-..."

curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Reply with exactly: OpenRouter OK"}]
  }' | jq -r '.choices[0].message.content'

6. 程式範例：curl／Python／Node.js／OpenAI SDK／串流／Fallback

cURL

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://sftpmac.com" \
  -H "X-Title: SFTPMAC OpenRouter Demo" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [
      {"role": "user", "content": "用一句話解釋什麼是量子計算"}
    ]
  }'

Python（requests）

import os
import requests

response = requests.post(
    url="https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
        "HTTP-Referer": "https://sftpmac.com",
        "X-Title": "SFTPMAC OpenRouter Demo",
    },
    json={
        "model": "google/gemini-2.5-pro",
        "messages": [
            {"role": "user", "content": "幫我寫一個快速排序的 Python 實作"}
        ],
    },
    timeout=60,
)
response.raise_for_status()
print(response.json()["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://sftpmac.com",
    "X-Title": "SFTPMAC OpenRouter Demo",
  },
});

const completion = await client.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "Explain OpenRouter in one sentence." }],
});

console.log(completion.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 from OpenRouter."}],
    extra_headers={
        "HTTP-Referer": "https://sftpmac.com",
        "X-Title": "SFTPMAC OpenRouter Demo",
    },
)
print(completion.choices[0].message.content)

串流輸出（Streaming）

const stream = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "寫一首關於秋天的短詩" }],
  stream: true,
});

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

多模型 Fallback（容災）

{
  "model": "anthropic/claude-sonnet-4",
  "models": [
    "anthropic/claude-sonnet-4",
    "openai/gpt-4o",
    "google/gemini-2.5-pro"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Summarize this incident." }]
}

主模型被限流或報錯時，OpenRouter 按順序自動嘗試列表中的下一個模型。OpenClaw 使用者應在 openclaw.json 鏡像相同的主備 slug，並以 SecretRef 管理金鑰。

查詢可用模型

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

7. 定價說明：無 token 加價、5.5% 手續費、BYOK

經驗法則：若每月 OpenRouter 充值手續費已超過維護兩套直連整合的工程成本，應評估 BYOK 或僅對最高流量 slug 改走直連。

8. 常見問題 FAQ

Q：OpenRouter 要收費嗎？ 付費模型按 token 原價計費；充值 Credits 收 5.5%（最低 $0.80）。25+ 免費模型未充值約 50 次／天，充值 ≥$10 後約 1000 次／天。

Q：會在 token 上加價嗎？ 不會；僅充值環節 5.5% 手續費，BYOK 每月前 100 萬次免服務費。

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

Q：OpenRouter 安全嗎？ 流量經閘道轉發至供應商；涉密資料需評估中間層與 BYOK；勿把 Key 暴露在前端。

Q：和直連 API 怎麼選？ 多模型／fallback／原型選 OpenRouter；超大体量、官方專屬能力、極低延遲或硬合規選直連。見上文對比表。

Q：和 OpenClaw 怎麼配合？ 在 openclaw.json 設定 OpenRouter provider 與主備模型，閘道放常線上 Mac 並跑 doctor／probe 驗收。

9. 總結：OpenRouter 的價值、局限與遠端 Mac 銜接

OpenRouter 把「多供應商 LLM 整合」壓縮成一組 Key、一個 Endpoint、改一行 model 字串——對 OpenClaw、Hermes 等多模型 Agent 與 A／B 測試，遷移成本幾乎為零。雙層路由（Model + Provider）與內建 Failover 讓應用程式不必重複寫限流切換；無 token 加價與 25+ 免費模型降低了原型門檻。

但它不是銀彈：閘道增加約 10–80ms 延遲；充值 5.5% 手續費在大体量下會逼您回歸直連；流量經美國中間層可能觸碰合規紅線。筆電合蓋休眠導致閘道離線時，OpenRouter 再穩也救不了「通道已讀不回」——瓶頸往往在宿主伺服器是否 7×24 在線，而非模型層。

若您要把 OpenRouter 接進 OpenClaw 做生產 Agent，下一步應讓閘道、工作區與 API Key 管理落在常線上的 macOS 節點：Apple Silicon 足夠的記憶體跑多 Agent、原生 launchd 守護、SFTP／rsync 同步設定與製品，並確保伺服器頻寬足以支撐 API 串流與檔案同步。SFTPMAC 遠端 Mac 租賃提供面向 OpenRouter／OpenClaw 的 Apple 生態環境——比「家用電腦兼 API 閘道」更適合把統一 LLM 路由當生產基礎設施的團隊。