订阅代理

订阅代理是一个本地 HTTP 服务器，允许外部应用（如 OpenViking、Karakeep、Open WebUI，或任何支持 OpenAI 兼容聊天补全的工具）通过你由 Hermes 管理的提供商订阅来使用 LLM 服务端点。该代理会自动附加正确的凭证（并在需要时刷新），因此应用程序无需持有静态 API 密钥。

这与 API 服务器不同：

	API 服务器	订阅代理
提供内容	你的智能体（完整工具集、记忆、技能）	原生模型推理
使用场景	“将 Hermes 作为聊天后端”	“在其他应用中使用我的 Portal 订阅”
认证方式	你的 `API_SERVER_KEY`	任意 bearer token（代理会附加真实凭证）
工具调用	支持 — 智能体可执行工具	不支持 — 仅透传

当你希望将 智能体 作为后端时，请使用 API 服务器；当你只想通过订阅获取模型推理能力时，请使用代理。

快速入门

1. 登录你的提供商（仅需一次）

hermes login nous

这将在浏览器中启动 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）。更多 OAuth 提供商可通过在 hermes_cli/proxy/adapters/ 中实现 UpstreamAdapter 接口来添加。

检查状态

hermes proxy status

Hermes proxy upstream adapters

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

若看到 not logged in，请运行 hermes login nous。若看到 credentials need attention，说明你的刷新令牌已被撤销（罕见情况，通常发生在你在 Portal 网页端登出后）——只需重新运行 hermes login nous 即可恢复。

允许的路径

代理仅转发上游实际提供的路径。对于 Nous Portal：

路径	用途
`/v1/chat/completions`	聊天补全（流式 + 非流式）
`/v1/completions`	旧版文本补全
`/v1/embeddings`	嵌入向量（Embeddings）
`/v1/models`	模型列表

其他路径（如 /v1/images/generations、/v1/audio/speech 等）将返回 404 错误，并附带清晰提示，指出哪些路径是被允许的。此举可防止意外客户端向上游泄露异常请求。

配置 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（仅限本地回环）。若要让网络中的其他设备使用：

hermes proxy start --host 0.0.0.0 --port 8645

⚠ 注意：网络中的任何人 now 都可以使用你的 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/ 中实现 UpstreamAdapter 接口，并在 adapters/__init__.py 中注册即可。对于协议层面不兼容 OpenAI 的提供商（如 Anthropic Messages API），可能需要额外的转换层，但这超出了当前版本的范围。

快速入门​

1. 登录你的提供商（仅需一次）​

2. 启动代理​

3. 将你的应用指向它​

可用提供商​

检查状态​

允许的路径​

配置 OpenViking 使用 Portal​

配置 Karakeep（或其他书签/摘要类应用）​

在局域网中暴露服务​

速率限制​

架构设计​

未来：支持更多 OAuth 提供商​