H繁中版
文件核心功能subscription proxy
<!-- Source: https://hermesbible.com/docs/user-guide/features/subscription-proxy -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/subscription-proxy

Subscription proxy 是一個本地 HTTP 伺服器，讓外部應用 — OpenViking、Karakeep、Open WebUI，任何支援 OpenAI 相容 chat completions 的程式 — 使用你透過 Hermes 管理的供應商訂閱作為它們的 LLM 端點。Proxy 會附加正確的憑證（自動重新整理），因此應用永遠不需要靜態 API 金鑰。

這與 API server 不同：

API serverSubscription proxy
服務內容你的 agent（完整工具集、記憶、技能）原始模型推論
使用場景「使用 Hermes 作為聊天後端」「從另一個應用使用我的 Portal 訂閱」
驗證方式你的 API_SERVER_KEY任何 bearer（proxy 附加真實憑證）
工具呼叫是 — agent 執行工具否 — 純透傳

當你想要agent 作為後端時，使用 API server。當你只是想透過訂閱使用模型時，使用 proxy。

快速開始

1. 登入你的供應商（一次性）

hermes portal

這會開啟你的瀏覽器進行 Nous Portal OAuth 流程。Hermes 將 refresh token 儲存在 ~/.hermes/auth.json — 與所有 Hermes 供應商登入存放的位置相同。

2. 啟動 proxy

hermes proxy start

Starting Hermes proxy for Nous Portal
  Listening on:  http://127.0.0.1:8645/v1
  Forwarding to: (resolved per-request from your subscription)
  Use any bearer token in the client — the proxy attaches your real credential.

讓它在前景運行。如果要讓它在登出後繼續運行，請使用 tmux、nohup 或 systemd 單元。

3. 將你的應用指向它

任何 OpenAI 相容的應用設定都使用相同的三項配置：

Base URL:   http://127.0.0.1:8645/v1
API key:    任意（例如 "sk-unused"）
Model:      Hermes-4-70B    # 或 Hermes-4.3-36B、Hermes-4-405B

Proxy 會忽略來自你應用的 Authorization 標頭，並在上游請求中附加你真實的 Portal 憑證。當 bearer 接近過期時會自動重新整理。

可用供應商

hermes proxy providers

目前已發佈：nous（Nous Portal）和 xai（xAI / Grok）。可以在 hermes_cli/proxy/adapters/ 中實作 UpstreamAdapter 介面來新增更多 OAuth 供應商。

檢查狀態

hermes proxy status

Hermes proxy upstream adapters

  [nous    ] Nous Portal — ready (bearer expires 2026-05-15T06:43:21Z)

如果看到 not logged in，請執行 hermes portal。如果看到 credentials need attention，表示你的 refresh token 已被撤銷（罕見 — 通常發生在你從 Portal 網頁 UI 登出時）— 只需重新執行 hermes portal。

允許的路徑

Proxy 只轉發上游實際提供的路徑。對於 Nous Portal：

路徑用途
/v1/chat/completions聊天補全（串流 + 非串流）
/v1/completions舊版文字補全
/v1/embeddings向量嵌入
/v1/models模型列表

其他路徑（/v1/images/generations、/v1/audio/speech 等）會回傳 404 並附帶清楚的錯誤訊息指向允許的路徑。這可以防止游離的用戶端向上游洩漏奇怪的請求。

設定 OpenViking 使用 Portal

OpenViking 是一個上下文資料庫，需要 LLM 供應商來提供其 VLM（視覺/語言模型，用於擷取記憶）和嵌入模型。透過 proxy，你可以將其 vlm.api_base 指向你的本地 proxy：

編輯 ~/.openviking/ov.conf：

{
  "vlm": {
    "provider": "openai",
    "model": "Hermes-4-70B",
    "api_base": "http://127.0.0.1:8645/v1",
    "api_key": "unused-proxy-attaches-real-creds"
  }
}

然後在與 openviking-server 並行的終端機中啟動你的 proxy：

# 終端機 1
hermes proxy start

# 終端機 2
openviking-server

OpenViking 的 VLM 呼叫現在會透過你的 Portal 訂閱。嵌入模型端仍需要自己的供應商 — Portal 確實提供 /v1/embeddings，但模型選擇取決於你的方案層級支援的內容；請查看 portal.nousresearch.com/models。

設定 Karakeep（或任何書籤/摘要應用）

Karakeep 接受 OpenAI 相容的 API 用於書籤摘要。在其設定中：

# Karakeep .env
OPENAI_API_BASE_URL=http://127.0.0.1:8645/v1
OPENAI_API_KEY=any-non-empty-string
INFERENCE_TEXT_MODEL=Hermes-4-70B

同樣的模式適用於 Open WebUI、LobeChat、NextChat 或任何其他 OpenAI 相容的用戶端。

在區域網路上公開

預設情況下 proxy 綁定 127.0.0.1（僅本機）。要讓網路上的其他機器使用它：

hermes proxy start --host 0.0.0.0 --port 8645

⚠ 請注意： 你網路上的任何人都可以使用你的 Portal 訂閱。Proxy 本身沒有驗證機制 — 它接受任何 bearer。如果要在信任網路之外公開，請使用防火牆、VPN 或帶有適當驗證的反向代理。

速率限制

你的 Portal 方案的 RPM/TPM 限制適用於整個 proxy。Proxy 不會分散或池化 — 它使用你的完整訂閱配額作為單一 bearer。在 portal.nousresearch.com 監控使用量。

架構

Proxy 設計上是精簡的。每個請求：

  1. 從你的應用接收 POST /v1/chat/completions
  2. 查找適配器的當前憑證（如即將過期則重新整理）
  3. 逐字轉發請求本文，附帶 Authorization: Bearer <minted-key>
  4. 原封不動地串流回應（保留 SSE）

無轉換。不記錄請求本文。無 agent 迴圈。Proxy 是一個附加憑證的透傳層。

未來：更多 OAuth 供應商

適配器系統是可插拔的。新增供應商（例如 HuggingFace、GitHub Copilot 的聊天端點、透過 OAuth 的 Anthropic）需要在 hermes_cli/proxy/adapters/<provider>.py 中實作 UpstreamAdapter 並在 adapters/__init__.py 中註冊。在協定層級不相容 OpenAI 的供應商（例如 Anthropic Messages API）需要轉換層，這不在目前的範圍內。

spotifytool gateway