第26篇：API Server——把 Hermes 变成服务

嘿，朋友们！今天咱们来玩点刺激的——把 Hermes 从“命令行小助手”升级成“7x24小时在线服务”。没错，就是那个传说中的 API Server，让 Hermes 变成一个 OpenAI 兼容的 HTTP 接口。

为啥要这么干？

想象一下：你辛辛苦苦调教好的 Hermes，带着全套工具（终端、文件操作、网页搜索、记忆、技能），现在能直接接入 Open WebUI、LobeChat、LibreChat、NextChat、ChatBox 等几百种前端。这些前端只要会说 OpenAI 的“方言”，就能把 Hermes 当后端用，而且工具调用的进度条还能实时显示，酷不酷？

💡 小贴士：Hermes 自己需要配置好模型提供商和工具后端才能干活。如果你有 Nous Portal 订阅，跑一次 hermes setup --portal 就全搞定了——300+ 模型加上网页/图片/TTS/浏览器工具，一步到位。

三步起飞

第一步：开启 API Server

打开 ~/.hermes/.env，加上这几行：

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# 可选：如果浏览器要直接访问 Hermes
# API_SERVER_CORS_ORIGINS=http://localhost:3000

第二步：启动网关

hermes gateway

看到这行就说明成功了：

[API Server] API server listening on http://127.0.0.1:8642

第三步：连接前端

把任何 OpenAI 兼容的客户端指向 http://localhost:8642/v1 就行。先用 curl 试试：

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer change-me-local-dev" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

两个核心接口

1. POST /v1/chat/completions —— 标准 OpenAI 聊天格式，无状态，每次请求都带上完整对话历史：

{
  "model": "hermes-agent",
  "messages": [
    {"role": "system", "content": "You are a Python expert."},
    {"role": "user", "content": "Write a fibonacci function"}
  ],
  "stream": false
}

2. POST /v1/responses —— 新版 Responses 格式，支持服务端记忆！用 previous_response_id 就能串联多轮对话，上下文（包括工具调用）全由服务器管理：

{
  "model": "hermes-agent",
  "input": "What files are in my project?",
  "store": true
}

下一轮直接带上 "previous_response_id": "resp_abc123" 就行，省心！

另外，如果你不想自己追踪 response ID，还可以用 conversation 参数给对话起个名字，服务器会自动接到该对话里最新的那条 response 上：

{"input": "Hello", "conversation": "my-project"}
{"input": "What's in src/?", "conversation": "my-project"}
{"input": "Run the tests", "conversation": "my-project"}

图片输入？没问题！

两种接口都支持图片。用户消息里用数组传 text 和 image_url 部分，远程 URL 和 base64 的 data:image/... 都行：

{
  "model": "hermes-agent",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.png", "detail": "high"}}
      ]
    }
  ]
}

注意：上传文件（file / file_id）和非图片的 data: URL 会返回 400 unsupported_content_type。

流式输出 & 工具进度

设置 "stream": true 就能开启 SSE 流式响应。Chat Completions 用标准的 chat.completion.chunk 事件，外加 Hermes 自定义的 hermes.tool.progress 事件——前端能实时显示“Agent 正在调用终端工具…”的进度，体验拉满！

Responses 接口则用 OpenAI 原生事件类型（response.created、response.output_text.delta 等），工具调用会以 function_call 和 function_call_output 形式出现在流里，结构化展示工具 UI 毫无压力。

顺便说一句，所有 SSE 流（Chat Completions、Responses、/api/sessions/{id}/chat/stream、/v1/runs/{id}/events）在 10 秒没事件时都会发一行 : keepalive 注释，防止长时间工具调用把客户端“晾”到超时。标准 SSE 客户端会自动忽略注释行，自己写解析器的话记得跳过以 : 开头的行。

模型思考过程也能流出来

如果模型本身会输出推理内容，而且配置允许，那思考过程也会一并返回：

Chat Completions：思考内容走 choices[0].delta.reasoning_content，正文还是 delta.content。Open WebUI、opencode、Vercel AI SDK 这些前端会把它渲染成“思考块”。
Responses：每段思考是一个原生的 reasoning output item，在下一个 message 或 function_call 之前闭合，response.completed 里也会带上。
非流式：/v1/chat/completions 在 choices[0].message.reasoning_content 返回；/v1/responses 则在 message 之前返回 reasoning item，GET /v1/responses/{id} 回放时也一样。
想关掉的话，输入端设 model_options.reasoning.enabled: false 就行。能力开关在 GET /v1/capabilities 里看 features.reasoning_streaming。

另外，Responses 流式模式下，模型在工具调用旁边写的“中途解说”（比如 openai-codex 后端的 phase="commentary" 前言）会作为独立的 message item 返回，带 "phase": "commentary"，不会混进最终答案里。不想要的话，display.interim_assistant_messages: false 可以关掉。

还有几个实用接口

除了上面两个核心接口，API Server 还提供了一些辅助端点：

GET /v1/models —— 列出可用的模型名（默认就是 profile 名，默认 profile 下是 hermes-agent），大多数前端靠它做模型发现。注意它只是 OpenAI 兼容的“轻量版”，不会枚举所有可路由的提供商/模型组合，也不带价格和能力信息。
GET /api/model/options —— Hermes 感知的客户端可以用它拿到和 Dashboard、TUI 一样的精选模型清单，包含提供商、模型能力提示和价格元数据。默认只探测当前选中的自定义端点，加 ?refresh=1 才会全量探测并刷新缓存。
GET /v1/capabilities —— 返回一份机器可读的能力描述，告诉外部 UI 当前 Hermes 版本是否支持 runs、流式、取消、会话连续性等，方便做集成时自动发现。

最后说两句

API Server 让 Hermes 从“单机工具”变成了“服务基础设施”。前端随便换，后端不用动。而且工具调用已经在服务器端执行完毕，返回的结果都是 "status": "completed"，客户端只管展示，不用操心执行逻辑。

赶紧试试吧！把 Hermes 变成你的私人 AI 后端，配上 Open WebUI 之类的漂亮前端，那感觉，真香！