订阅代理

订阅代理是一个本地 HTTP 服务器，它允许外部应用程序 —— 如 OpenViking、Karakeep、Open WebUI，以及任何支持 OpenAI 兼容的聊天补全（chat completions）协议的程序 —— 将你通过 Hermes 管理的供应商订阅作为其 LLM 端点。该代理会自动附加正确的凭证（并自动刷新它们），因此外部应用程序永远不需要静态的 API 密钥。

这与 API 服务器（API server） 不同：

	API 服务器（API server）	订阅代理（Subscription proxy）
它提供什么（What it serves）	你的智能体（包含完整的工具集、记忆、技能）	原始模型推理（Raw model inference）
使用场景（Use case）	“将 Hermes 作为聊天后端”	“从另一个应用使用我的 Portal 订阅”
认证（Auth）	你的 API_SERVER_KEY	任何 Bearer 令牌（代理会自动附加真实的凭证）
工具调用（Tool calls）	是 —— 由智能体运行工具	否 —— 仅限直通（passthrough）

当你需要将 智能体 作为后端时，请使用 API 服务器。当你只想通过你的订阅来使用 模型 时，请使用代理。

快速开始（Quick Start）

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 令牌临近过期时，会自动进行刷新。

可用供应商（Available providers）

hermes proxy providers

当前已附带：nous（Nous Portal）。通过在 hermes_cli/proxy/adapters/ 中实现 UpstreamAdapter 接口，可以添加更多 OAuth 供应商。

检查状态（Check status）

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 网页端 UI 退出登录时发生） —— 只需重新运行 hermes login nous 即可。

允许的路径（Allowed paths）

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

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

其他路径（/v1/images/generations、/v1/audio/speech 等）将返回 404 错误，并附带明确的错误提示指向允许的路径。这可以防止异常客户端向游泄漏奇怪的请求。

配置 OpenViking 使用 Portal

OpenViking 是一个上下文数据库，它需要一个 LLM 供应商来为其 VLM（用于提取记忆的愿景/语言模型，vision/language model）和嵌入模型提供支持。通过该代理，您可以将其 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 一起启动您的代理：

# 终端 1
hermes proxy start

# 终端 2
openviking-server

现在，OpenViking 的 VLM 调用将流经您的 Portal 订阅。嵌入模型端仍然需要其自己的供应商 —— Portal 确实提供 /v1/embeddings 服务，但模型的选择取决于您的级别（tier）所支持的内容；请查看 portal.nousresearch.com/models。

配置 Karakeep（或任何书签/摘要应用）（Configuring Karakeep (or any bookmark/summarizer app)）

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 的客户端。

在局域网中暴露（Exposing on LAN）

默认情况下，代理绑定到 127.0.0.1（仅限本地主机）。要让网络中的其他机器使用它，请运行：

hermes proxy start --host 0.0.0.0 --port 8645

⚠ 请注意： 此时你网络中的任何人都可以使用你的 Portal 订阅。该代理本身没有身份验证机制 —— 它接受任何 Bearer 令牌。如果你将其暴露在信任网络之外，请使用防火墙、VPN 或带有正确身份验证的反向代理。

速率限制（Rate limits）

你的 Portal 级别（tier）的 RPM/TPM（每分钟请求数/每分钟 Token 数）限制适用于整个代理。该代理不会进行扇出（fan out）或合并池化（pool） —— 它是一个带有你完整订阅配额 e 的单一 Bearer 凭证。可在 portal.nousresearch.com 监控使用情况。

架构（Architecture）

该代理被特意设计得极简。对于每个请求：

1. 接收来自你应用的 POST /v1/chat/completions。
2. 查找适配器（adapter）当前的凭证（如果即将过期则进行刷新）。
3. 逐字转发请求体（request body），并附带 Authorization: Bearer <minted-key>。
4. 原封不动地将响应流式传回（保留 SSE）。

无转换、不记录请求体、没有智能体循环。该代理是一个附加凭证的直通（pass-through）通道。

未来：支持更多 OAuth 供应商

适配器系统是可插拔的。添加一个新的供应商（例如 HuggingFace、GitHub Copilot 的聊天端点、通过 OAuth 的 Anthropic）需要在 hermes_cli/proxy/adapters/<provider>.py 中实现 UpstreamAdapter 并将其注册到 adapters/__init__.py 中。对于在协议级别不兼容 OpenAI 的供应商（例如 Anthropic 消息 API），则需要一个转换层，这超出了当前架构的设计范围。