订阅代理

订阅代理是一个本地 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 提供商​