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

这篇讲的是：如何把 Hermes Agent 变成一个“标准插座”，让任何支持 OpenAI 格式的聊天前端（比如 Open WebUI、LobeChat）都能插上来用。

---

想象一下：你家里装了一个超强力的“全能管家”（Hermes），它能帮你操作电脑、查资料、写代码。但问题是，管家只在你家客厅等你下指令。API Server 就是给这个管家装了一个“对外服务窗口”——任何会说“OpenAI 语言”的访客（前端应用），都能通过这个窗口向管家下指令，拿到结果。

第1步：打开服务开关

用文本编辑器打开配置文件 ~/.hermes/.env，加入三行配置：

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# 可选：如果浏览器要直接访问，取消下一行注释
# API_SERVER_CORS_ORIGINS=http://localhost:3000

第一行是“开门营业”，第二行是“门禁密码”（自己改成复杂点的），第三行是“允许哪些访客直接进来”。

第2步：启动服务

在终端里运行：

hermes gateway

看到这行输出就说明服务开好了：

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

第3步：连接你的前端

方法A：用命令行测试（先确认通了）

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": "你好！"}]}'

方法B：连接图形界面（推荐日常用）

打开 Open WebUI 或 LobeChat，在设置里把 API 地址填成 http://localhost:8642/v1，密钥填你设的密码，模型选 hermes-agent，就能像用 ChatGPT 一样用 Hermes 了。

两个核心接口，一个管聊天，一个管记忆

/v1/chat/completions：标准聊天接口。每次请求都要带上完整对话历史（无状态）。支持传图片（网络图片或 base64 编码的本地图片），也支持流式输出——打字机效果，而且 Hermes 会额外发一个 hermes.tool.progress 事件，前端就能显示“正在使用工具”的提示。

/v1/responses：更聪明的接口。服务端帮你记住上下文——你只需要传一个 previous_response_id，Hermes 会自动把之前的对话（包括工具调用过程）接上。更省事的是用 conversation 参数：

{"input": "看看我项目里有什么文件", "conversation": "my-project"}
{"input": "帮我读一下 README", "conversation": "my-project"}

同一个名字就自动串成多轮对话，在仪表盘里也显示为一条记录。

两个实用小接口

• GET /v1/models：让前端知道“我这里有 Hermes 这个模型可用”。
• GET /api/model/options：给 Hermes 自家的界面用的，返回更详细的模型列表、价格、能力标签。

---

总结一下：API Server 让 Hermes 从一个“本地工具”变成了“标准服务”——任何 OpenAI 兼容的前端都能接上来用，而且工具调用、图片输入、流式输出这些高级功能全都保留。

下篇预告：服务开好了，怎么让手机也能连上？下一篇我们聊聊 远程访问与安全配置，把 Hermes 带出家门。