訂閱代理

訂閱代理是一個本地 HTTP 服務器，它允許外部應用（如 OpenViking、Karakeep、Open WebUI，或任何支持 OpenAI 兼容聊天補全的應用）使用由 Hermes 管理的提供商訂閱作為其 LLM 端點。該代理會自動附加正確的憑據（並自動刷新），因此應用無需使用靜態 API 密鑰。

這與 API 服務器不同：

	API 服務器	訂閱代理
服務內容	你的智能體（完整工具集、記憶、技能）	原始模型推理
用例	“將 Hermes 用作聊天后端”	“在另一個應用中使用我的 Portal 訂閱”
認證	你的 `API_SERVER_KEY`	任意 bearer token（代理會附加真實的憑據）
工具調用	是 — 智能體會執行工具	否 — 僅透傳

當你希望將智能體作為後端時，請使用 API 服務器。當你僅希望通過訂閱使用模型時，請使用代理。

快速開始

1. 登錄到你的提供商（一次性操作）

hermes portal

這將在瀏覽器中打開 Nous Portal OAuth 流程。Hermes 會將刷新令牌存儲在 ~/.hermes/auth.json 中——這也是所有 Hermes 提供商登錄信息的存儲位置。

2. 啟動代理

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:    anything (e.g. "sk-unused")
Model:      Hermes-4-70B    # or Hermes-4.3-36B, Hermes-4-405B

代理會忽略來自你應用的 Authorization 頭，並將你真實的 Portal 憑據附加到上游請求中。當 bearer token 接近過期時，刷新會自動進行。

可用的提供商

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，說明你的刷新令牌已被撤銷（這種情況很少見，通常是因為你在 Portal Web UI 中退出了登錄）——只需重新運行 hermes portal 即可。

允許的路徑

代理僅轉發上游實際提供的路徑。對於 Nous Portal：

路徑	用途
`/v1/chat/completions`	聊天補全（支持流式和非流式）
`/v1/completions`	傳統文本補全
`/v1/embeddings`	嵌入向量
`/v1/models`	模型列表

其他路徑（如 /v1/images/generations、/v1/audio/speech 等）將返回 404，並附帶明確的錯誤信息，指向允許的路徑。這可以防止 stray 客戶端向上遊發送奇怪的請求。

配置 OpenViking 以使用 Portal

OpenViking 是一個上下文數據庫，需要 LLM 提供商為其 VLM（用於提取記憶的視覺/語言模型）和嵌入模型提供支持。通過代理，你可以將其 vlm.api_base 指向本地代理：

編輯 ~/.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 一起啟動代理：

# Terminal 1
hermes proxy start

# Terminal 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 的客戶端。

在局域網中暴露

默認情況下，代理綁定到 127.0.0.1（僅限 localhost）。要讓網絡中的其他機器使用它：

hermes proxy start --host 0.0.0.0 --port 8645

⚠ 注意： 你網絡中的任何人都可以使用你的 Portal 訂閱。代理本身沒有認證機制——它接受任何 bearer token。如果你要在受信任網絡之外暴露此服務，請使用防火牆、VPN 或帶有適當認證的反向代理。

速率限制

你的 Portal 層級的 RPM/TPM 限制適用於整個代理。代理不會進行扇出或池化——它是一個具有你完整訂閱配額的單一 bearer token。請在 portal.nousresearch.com 監控使用情況。

架構

代理故意保持極簡。每個請求的處理流程如下：

從你的應用接收 POST /v1/chat/completions
查找適配器當前的憑據（如果即將過期則刷新）
原樣轉發請求體，並附加 Authorization: Bearer <minted-key>
將響應原樣流式返回（保留 SSE）

無轉換。無請求體日誌記錄。無智能體循環。代理只是一個附加憑據的透傳通道。

未來：更多 OAuth 提供商

適配器系統是可插拔的。添加新的提供商（例如 HuggingFace、GitHub Copilot 的聊天端點、通過 OAuth 的 Anthropic）需要在 hermes_cli/proxy/adapters/<provider>.py 中實現 UpstreamAdapter，並在 adapters/__init__.py 中註冊它。在協議層面不與 OpenAI 兼容的提供商（例如 Anthropic Messages API）需要一個轉換層，這超出了當前架構的範圍。

快速開始​

1. 登錄到你的提供商（一次性操作）​

2. 啟動代理​

3. 將你的應用指向它​

可用的提供商​

檢查狀態​

允許的路徑​

配置 OpenViking 以使用 Portal​

配置 Karakeep（或任何書籤/摘要應用）​

在局域網中暴露​

速率限制​

架構​

未來：更多 OAuth 提供商​