Hermes Agent API 集成：一个端点，任意前端

任何 OpenAI 兼容的聊天前端本来就已经会说 /v1/chat/completions。Hermes Agent 把这一事实用到了极致：把它们中的任何一个指向 http://localhost:8642/v1，传入一个 API 密钥，你就得到了完整的 Hermes 运行时——工具、记忆、技能、cron——都藏在一个熟悉的 HTTP 表面之下，客户端一行代码都不用改。

这就是 Hermes API 服务器的全部理念。它不是一个 Hermes 专属的 SDK 需要你去学。它是 OpenAI 的形状，在本地起服务，把智能体包起来。如果你已经在用 Open WebUI、LobeChat、LibreChat、NextChat、ChatBox，或者一个跟 openai-python 说话的脚本，那么你已经知道怎么集成。

本文会带你走一遍：API 服务器暴露了什么、怎么打开它，以及在真实前端接入之后，哪些做法能站得住脚。

API 服务器到底暴露了什么

API 服务器是 Hermes gateway 内部的一个组件。启用之后，它默认监听 127.0.0.1:8642，并用 OpenAI 的 HTTP 契约支持四类端点：

/v1/chat/completions —— 经典的 Chat Completions 端点。无状态，支持或不支持流式。90% 的 OpenAI 兼容前端用的就是这个。
/v1/responses —— 较新的 Responses API，有状态，支持通过 previous_response_id 进行会话链接，可以通过 ID 恢复会话，而不必每次都重发全部消息历史。
/v1/runs —— 一套长任务 API，用于超出单次 request/response 周期的作业。客户端提交一个 run，轮询状态，就绪后再取结果。
/api/jobs —— 一层围绕内建 cron 调度器的 REST API，让外部应用可以像管理任何其他资源一样地创建、列出、取消智能体的定时任务。

你发出的每个请求都会走完整个 Hermes 栈。模型不是独自作答。它可以访问终端、文件系统、网页搜索、记忆文件，以及你配置的任何 MCP 服务器。想更全面地看看这些工具如何最终触达模型，可以看 Hermes Agent 与 MCP。

打开 API 服务器

API 服务器默认是关的。你在 ~/.hermes/.env 里加两条配置来打开它：

API_SERVER_ENABLED=true
API_SERVER_KEY=$(openssl rand -hex 32)

然后重启 gateway（hermes gateway）。相同的值也可以放在 ~/.hermes/config.yaml 的 gateway.api_server: 段落里，如果你更喜欢 YAML；但两者同时设置时环境变量优先。

打开之前有几点值得知道：

默认绑定地址是 127.0.0.1，也就是端点只能从同一台主机访问。如果你在 Docker 容器里跑 Hermes，希望另一个容器或宿主机能访问到，还需要额外设置 API_SERVER_HOST=0.0.0.0，并确认端口已经映射出来。
API_SERVER_KEY 至少 8 个字符。把它当成任何其他 API 密钥来对待：不要提交到仓库，不要贴到共享频道。一旦泄露，网络上任何人都可以用你的账号、你的工具和你的凭证去跑智能体任务。
端口 8642 是 Hermes 的约定，不是什么标准。如果和你机器上的东西冲突，改 API_SERVER_PORT 即可。下游一切只需要拿到一个基础 URL。

服务器起来之后，用任意 OpenAI SDK 快速验一下：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="你设置的密钥",
)

resp = client.chat.completions.create(
    model="hermes",
    messages=[{"role": "user", "content": "今天几号？顺便读一下 README.md。"}],
)
print(resp.choices[0].message.content)

除了基础 URL，这段代码里没有任何东西是 Hermes 特有的。这正是它的意义所在。

那些拿来就用的前端

因为表面就是 OpenAI 的，绝大多数现有聊天前端只需改一处设置就能连上。下面是被问得最多的几个：

Open WebUI。 Admin Settings → Connections → OpenAI → Add Connection。把 Base URL 设为 http://localhost:8642/v1，API 密钥填你的 API_SERVER_KEY。最常见的错误是漏掉 /v1 后缀，别漏。Open WebUI 会把它持久化在自己的数据库里，之后要改密钥，请从 admin UI 里改，不要靠再次编辑环境变量。

LobeChat。 在 Settings → Language Model → OpenAI 里，把 API proxy URL 覆盖成 http://localhost:8642/v1，粘贴密钥即可。模型列表可以只有一条 hermes；服务器会把所有请求映射到同一个智能体。

LibreChat。 在 librechat.yaml 里加一条自定义端点：apiKey: 你的密钥、baseURL: http://localhost:8642/v1，模型名可以随便写，会显示在选择器里。剩下的 LibreChat 会按自托管 OpenAI 来处理。

NextChat、ChatBox 等等。 同样的套路：基础 URL 加密钥。只要一个前端号称兼容 OpenAI，几乎肯定能用。

把 Hermes 藏在这些前端后面的好处是：你能白拿它们打磨过的 UI —— 聊天记录、置顶会话、模型切换、并排对比 —— 而背后那个「模型」实际上是你自己的智能体加上你自己的工具。

流式、工具进度与 Responses API

第一次接触 API 服务器时，有两件事会让人惊讶。

第一是流式响应会带上工具进度。当智能体决定跑 shell、访问网页或读取文件时，流会把这一步告诉客户端。遵守流式格式的前端会内联显示「running tool: web_search」之类的字样，然后再继续输出模型的实际回复。你不用再另外接一条日志通道，就能真实地观察到智能体在做什么。

第二是 Responses API。/v1/responses 在 /v1/chat/completions 所不具备的意义上是有状态的。客户端不必每轮都把整个消息历史再传一遍，而是可以传一个 previous_response_id，服务器就从上一次响应停下的地方继续。这在需要多轮、长会话的场景下很重要，因为每次上传历史成本不菲；这也天然契合 OpenAI 自身较新 SDK 的方向。如果你的前端两个都支持，长会话优先用 Responses，一次性调用则用 Chat Completions。

Runs 与 Jobs 覆盖了 request/response 模型里那些别扭的场景：跑十分钟的 run，或每天早上 8 点触发、把摘要丢到某个频道的定时任务。参见 Hermes Agent scheduled tasks and automation，那是 cron 侧的做法。

值得遵循的做法

一些在 API 服务器真正承担工作后依然站得住的习惯：

没有充分理由之前，先把端点留在 localhost。 默认绑定是安全的。如果确实需要远程访问，前面加一层带 TLS 和鉴权的真正反向代理，而不是把 host 直接翻成 0.0.0.0 暴露在公网上。

能做到的话，一个客户端一把密钥。 目前的服务器只接受一个 API_SERVER_KEY。如果你要接多个前端，希望撤销其中一个而不影响其他，那就用多把不同的 API_SERVER_KEY 跑多个独立的 Hermes 实例，或者在前面终止一层代理，由代理来发放按客户端隔离的密钥，再统一转发一个共享密钥给智能体。

模型名只是标签，不是路由。 每个请求都走同一个智能体。除非你就是想让不同前端在自己的 UI 里显示不同的名字，否则让所有前端指向同一条 model: "hermes" 就好。

接入新前端时盯一下日志。 gateway 会记录每次入站请求和每次工具调用。前几段对话时扫一眼，就能很快看出前端发的消息是不是你以为的那样，或者是不是塞了一段 system prompt 在和你现有的记忆文件对着干。

长对话优先 Responses，脚本调用优先 Chat Completions。 客户端复杂度是一样的，服务端成本不是。

Hermify 在其中的位置

自己跑 API 服务器并不复杂，但仍意味着要维持 gateway 进程活着、容器持续升级、端口保持可达。如果你想跳过这些，Hermify 会在 Telegram 上为你运行一个托管的 Hermes Agent，工具、记忆和技能一致，大约一分钟即可上线。今天托管产品的 API 表面以 Telegram 优先；如果你想让自定义客户端直接连上你自己的智能体，那还是走自托管 API 服务器。不管走哪条路，底层的运行时是一样的，本文的思路都能迁移过去。