Hermes 多家 AI 的 OAuth、原生 Provider 與 Proxy/Bridge 接法

查詢與驗證日期：2026-08-22
適用範圍：本機 Hermes 以多個模型 provider 運作的架構說明。本文不包含帳號、token、API key、私人網址或可直接連入的端點。

一句話結論

「能在 Hermes 裡選到模型」不代表它們都用同一種登入方式。實務上有三條完全不同的路徑：

原生 provider：Hermes → 官方服務
Proxy/bridge：  Hermes → 本機轉接程式 → 官方 CLI 或官方服務
正式雲端 OAuth：Hermes → 雲端平台（ADC／service account）→ 模型服務

差別會影響：誰保存憑證、使用哪一種配額或帳單、是否可看見正確 token 用量，以及故障時應查哪一層。

1. 先理解四個名詞

原生 provider

Hermes 直接支援該模型服務的協定與驗證。Hermes 自己負責選模型、保存或讀取認證、向官方服務送請求。

Hermes → 官方 API / 官方 provider

優點是結構短、狀態和用量較容易查；缺點是 Hermes 必須真的支援那一種驗證方式。

OAuth

OAuth 是「授權登入」機制，不等於 API key，也不等於所有服務都能拿來當 API。通常會得到短期 access token 與可續期的 refresh token。

OAuth 可出現在不同層：

• Hermes 自己持有 OAuth：例如原生 Codex provider。
• 官方 CLI 持有 OAuth：例如 Gemini CLI 或 Claude Code 登入後，CLI 自己管理 token。
• 雲端平台持有 OAuth：例如 Google Cloud ADC 或 service account 對 Vertex AI 取得短期權杖。

API key

API key 是給正式 API 呼叫的長期憑證。它通常綁定專案、帳單和 API 配額，並不會自動使用個人訂閱方案的額度。

Proxy / bridge

Proxy 或 bridge 是本機常駐的中介程式。它把 Hermes 的請求轉成另一種協定，或轉交給已登入的 CLI。

Hermes → OpenAI 相容介面 → proxy/bridge → CLI 或官方服務

它的價值是兼容性；代價是多一層服務、更多故障點與較不透明的用量統計。

2. 本機各 provider 的實際路由

A. OpenAI Codex：原生 Hermes provider

Hermes → openai-codex provider → OpenAI

這條是 Hermes 原生 provider 路徑。Hermes 管理其登入狀態並直接向 OpenAI 請求，不需要額外本機 bridge。

適合：想要較少元件、較直接的 provider 狀態與穩定性時。

注意：不要把「Codex/ChatGPT 登入」和「OpenAI Platform API key」混為同一種帳務或授權。正式 OpenAI API 的公開文件以 API key 作為一般 API 驗證方式；實際帳戶可用的登入與產品權益仍以官方帳戶設定為準。

B. Anthropic Claude 原生 provider：直接由 Hermes 呼叫

Hermes → anthropic provider → Anthropic

以 claude-opus-4-6 這類指定為 anthropic provider 的模型為例，走的是 Hermes 原生 Anthropic 路徑，概念上最接近 Codex 的「Hermes 直接管理 provider」模式。

適合：需要短路徑、清楚區分 Hermes 原生登入與本機 CLI 的情況。

C. Claude Code bridge：由本機 Claude Code OAuth 執行

Hermes
  → custom:claude-code-proxy
  → 本機 Claude Code bridge
  → claude -p
  → Claude Code 的 Claude.ai OAuth
  → Anthropic

claude-opus、claude-sonnet、claude-haiku 這類 custom alias 屬於這條路。bridge 對 Hermes 提供 OpenAI 相容 chat 介面，收到請求後再啟動已登入的 Claude Code CLI。

這不是 Hermes 原生 Anthropic provider。它適合把「已登入的 Claude Code 工作流程」接進 Hermes，但請注意：

• Claude Code 可能把內容視為 agent 任務，會帶入其系統指令、工具設定或額外處理回合。
• bridge 若回傳簡化的 usage 欄位，Hermes 端數字不一定能代表真實 Claude Code 消耗。
• Claude 的訂閱與第三方工具使用必須依 Anthropic 當時的方案與條款；技術可通不等於永久保證可用。

D. Gemini proxy：由本機 Gemini/Google OAuth 轉接

Hermes
  → custom:gemini-proxy
  → 本機 cli-proxy
  → Gemini CLI / Google OAuth
  → Google Gemini

本機 Gemini alias 都指定 custom:gemini-proxy。因此 hermes auth status gemini 即使顯示未登入，也不等於 Gemini 不能用：那個指令檢查的是 Hermes 原生 gemini provider；實際模型走的是 proxy 裡保存的 Google OAuth。

適合：希望使用 Gemini CLI／Google AI Pro 這類 Google 帳號登入後的 CLI 額度，而 Hermes 本身沒有對應的個人 Gemini CLI OAuth 原生 provider。

注意：proxy 是相容性轉接層，不是官方 Gemini API key 的直連路徑。它應只在本機使用，不應公開成他人可共用的服務。

E. Gemini 原生 API provider：正式 Gemini API key

Hermes → gemini provider → Gemini API

這條不需要本機 cli-proxy，但使用的是 GEMINI_API_KEY（或 Google AI Studio 專案的正式 API 憑證）。它走 Gemini API 的專案配額與帳單，不會使用個人 Google AI Pro／Gemini CLI 訂閱額度。

適合：正式應用、可預測的 API 帳單、高用量或需要較完整的 API 功能時。

F. Vertex AI：原生雲端 OAuth2 路徑

Hermes → vertex provider → Google Cloud / Vertex AI → Gemini

Vertex 路徑使用 Google Cloud 的 Application Default Credentials（ADC）或 service account，取得短期 OAuth2 access token。它不使用個人 Gemini CLI/Google AI Pro 訂閱額度，而是使用 GCP 專案的 Vertex AI 帳單與配額。

適合：企業、可稽核部署、服務帳號、明確 GCP 專案與生產環境。

3. 一張比較表

4. Token、配額與費用到底有何差異？

同一模型、同一完整輸入，proxy 不會憑空大量增加 token

HTTP 轉送本身不會產生模型 token。真正決定消耗的是模型收到的：

• 完整對話歷史與 system prompt
• 輸入與輸出長度
• reasoning / thinking token
• 工具呼叫與回傳結果
• 是否有 prompt cache 或 server-side cache

但不同路徑仍可能有顯著差異

因此不能只看 Hermes 的 token 數字來比較所有路徑；對 bridge 尤其要以底層 CLI 或官方帳戶的配額／用量頁為準。

5. Google AI Pro / Gemini CLI 訂閱與 Gemini API 的差別

這是最常被混淆的地方：

Google AI Pro / Gemini CLI OAuth
→ Google 帳號、Gemini CLI 使用量或方案配額

Gemini API key
→ Google AI Studio / Cloud 專案、API 配額與帳單

Vertex AI
→ GCP 專案、Vertex AI 配額與帳單

三者不是同一個錢包，也不是同一套上限。若目標是使用個人 Google AI Pro 的 Gemini CLI 額度，現有的 Gemini proxy 是實際路徑；若目標是正式、可量化、可長期自動化的 API，則應使用 Gemini API 或 Vertex。

以 Jio 等合作促銷取得的 Google AI Pro 權益亦屬 Google 帳號／訂閱路徑，而非 Gemini API key。它的持續性取決於促銷提供者、資格與條款，不應當作正式 API 成本替代品。

6. 合規與帳號風險

可以合理使用的範圍

• 在本人本機，以自己的帳號與正常使用頻率執行已登入的官方 CLI。
• 將只監聽 localhost 的 proxy 作為個人工具整合。
• 遵守服務的使用條款、模型配額、內容政策與帳號資格條件。

應避免的行為

• 將個人訂閱 OAuth 包裝成對外販售或公開 API。
• 多帳號輪替、偽裝 client 身分、繞過 429、繞過方案或促銷資格限制。
• 公開 proxy port、API key、OAuth refresh token 或把憑證交給第三方。
• 將促銷／個人訂閱帳號作為高頻、商業化或唯一生產依賴。

風險不是「只要使用 proxy 就一定封號」。OAuth 本身是官方支援的驗證機制；但非官方相容 proxy、跨區促銷、過度自動化或規避配額都會提高 token 被撤銷、服務受限或帳號被檢視的風險。正式生產工作建議使用官方 API key、Vertex 或服務帳號。

7. 故障時先辨識路由，再查對的地方

原生 provider

模型是否指定原生 provider？
→ Hermes provider auth status
→ Hermes Gateway 狀態
→ 在使用者授權下再做一次真實模型請求

Claude Code bridge

Claude Code 是否登入？
→ bridge 是否存活並只監聽 localhost？
→ 已認證的 /v1/models 是否能列出模型？
→ 在使用者授權下做一次 completion

Gemini proxy

cli-proxy 是否存活並只監聽 localhost？
→ Google OAuth 憑證是否存在、可更新？
→ 已認證的 /v1/models 是否回 HTTP 200？
→ 在使用者授權下做一次 completion

不要只看「Model switched」或「模型名稱出現在清單」就宣稱可用；那只證明設定或 discovery 成功，未必證明底層帳號真的可生成內容。

8. 選擇建議

最好的架構通常不是只押一條路：將個人 OAuth proxy 視為方便的低頻來源，同時保留至少一個正式原生 provider 或 API provider 作 fallback。

9. 官方參考資料

• OpenAI API Quickstart
• Anthropic：登入 Claude 帳號與第三方工具說明
• Anthropic：Claude Code 訂閱方案
• Gemini CLI：Authentication
• Gemini CLI：Token caching
• Gemini API：Billing
• Gemini API：OAuth quickstart
• Google Gemini API：Abuse monitoring

免責聲明

本文是技術架構與公開條款的整理，不是法律、稅務、帳務或平台政策保證。模型可用性、方案內容、帳單、促銷資格、token 限制與第三方整合規則會變動；要做生產或商業決策時，請以各官方帳戶後台與最新官方條款為準。