Skip to main content

API 服务器

API 服务器会把 hermes-agent 暴露为兼容 OpenAI 的 HTTP 端点。任何支持 OpenAI 格式的前端，比如 Open WebUI、LobeChat、LibreChat、NextChat、ChatBox 等，都可以把 hermes-agent 作为后端接入。

代理会带着完整的工具能力来处理请求，包括终端、文件操作、网页搜索、记忆、技能等，并返回最终响应。开启流式输出时，工具执行进度还会以内联形式显示，让前端实时知道代理正在做什么。

快速入门​

1. 启用 API 服务器​

在 ~/.hermes/.env 中添加：

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# Optional: only if a browser must call Hermes directly
# API_SERVER_CORS_ORIGINS=http://localhost:3000

2. 启动网关​

运行以下命令：

hermes gateway

你会看到类似下面的输出：

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

3. 连接前端​

将任意兼容 OpenAI 的客户端指向 http://localhost:8642/v1：

# Test with 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!"}]}'

你也可以直接接入 Open WebUI、LobeChat 或其他前端。分步说明可参阅 Open WebUI 集成指南。

端点​

POST /v1/chat/completions​

这是标准的 OpenAI Chat Completions 格式。它是无状态的，因此每次请求都需要通过 messages 数组携带完整对话历史。

请求示例：

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

响应示例：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "hermes-agent",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Here's a fibonacci function..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 50, "completion_tokens": 200, "total_tokens": 250}
}

流式传输：启用后，接口会返回 Server-Sent Events（SSE），按 token 逐步发送响应片段；如果未启用流式输出，则会一次性返回完整结果。

流式过程中的工具进度：当代理在流式请求中调用工具时，内容流里会插入简短的进度提示，例如 `💻 pwd`、`🔍 Python docs`。这些提示会以内联 Markdown 的形式出现在最终回答之前，让 Open WebUI 这类前端可以实时显示工具执行状态。

POST /v1/responses​

这是 OpenAI Responses API 格式。它支持通过 previous_response_id 在服务端延续对话状态，服务器会保存完整的对话历史，包括工具调用和工具结果，因此多轮上下文不需要客户端自己维护。

请求示例：

{
  "model": "hermes-agent",
  "input": "What files are in my project?",
  "instructions": "You are a helpful coding assistant.",
  "store": true
}

响应示例：

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "hermes-agent",
  "output": [
    {"type": "function_call", "name": "terminal", "arguments": "{\"command\": \"ls\"}", "call_id": "call_1"},
    {"type": "function_call_output", "call_id": "call_1", "output": "README.md src/ tests/"},
    {"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "Your project has..."}]}
  ],
  "usage": {"input_tokens": 50, "output_tokens": 200, "total_tokens": 250}
}

多轮对话与 previous_response_id​

通过链式调用可以保留完整上下文，包括之前的工具调用：

{
  "input": "Now show me the README",
  "previous_response_id": "resp_abc123"
}

服务器会从已存储的响应链中重建完整对话——所有之前的工具调用和结果均被保留。

命名对话​

你也可以用 conversation 参数代替手动追踪 response_id：

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

服务器会自动把请求关联到该会话的最新响应。这有点类似网关会话里的 /title 命名方式。

GET /v1/responses/{response_id}​

根据 ID 检索之前存储的响应。

DELETE /v1/responses/{response_id}​

删除已存储的响应。

GET /v1/models​

列出可用模型。对外暴露的模型名默认使用 配置文件 名称；如果是默认配置文件，则为 hermes-agent。多数前端都需要这个接口来发现模型。

GET /health​

健康检查。返回 {"status": "ok"}。也可通过 GET /v1/health 访问，以兼容期望 /v1/ 前缀的 OpenAI 客户端。

系统提示处理​

当前端发送 system 消息（Chat Completions）或 instructions 字段（Responses API）时，hermes-agent 会把这些内容叠加到核心系统提示之上。也就是说，代理依然保留全部工具、记忆和技能，前端给出的系统提示只是额外补充说明。

这意味着你可以在前端自定义代理行为，而不必担心丢掉 Hermes 原有能力：

  • Open WebUI 的系统提示：“你是一位 Python 专家。始终包含类型注解。”
  • 代理依然具备终端、文件工具、网络搜索、记忆等功能。

认证​

通过 Authorization 头使用 Bearer Token 认证：

Authorization: Bearer YOUR_TOKEN_HERE

密钥通过 API_SERVER_KEY 环境变量配置。如果需要让浏览器直接调用 Hermes，还要额外设置 API_SERVER_CORS_ORIGINS，显式放行对应来源。

安全性警告

API 服务器提供对 hermes-agent 工具集的完全访问权限，包括终端命令。当绑定到非本地回环地址（如 0.0.0.0）时，必须启用认证。同时应将 API_SERVER_CORS_ORIGINS 设置得尽可能窄，以控制浏览器访问范围。

默认绑定地址（127.0.0.1）仅限本地使用。默认情况下禁用浏览器访问；仅在明确信任的来源下才启用。

配置​

环境变量​

变量默认值说明
API_SERVER_ENABLEDfalse启用 API 服务器
API_SERVER_PORT8642HTTP 服务器端口
API_SERVER_HOST127.0.0.1绑定地址（默认仅限 localhost）
API_SERVER_KEY(无)认证用的 Bearer Token
API_SERVER_CORS_ORIGINS(无)允许的浏览器来源列表（逗号分隔）
API_SERVER_MODEL_NAME(配置文件名)在 /v1/models 上显示的模型名称。默认为配置文件名，或默认配置文件的 hermes-agent

config.yaml​

# Not yet supported — use environment variables.
# config.yaml support coming in a future release.

安全头信息​

所有响应均包含安全头信息：

  • X-Content-Type-Options: nosniff — 防止 MIME 类型嗅探
  • Referrer-Policy: no-referrer — 防止引用来源泄露

CORS​

API 服务器默认不启用浏览器 CORS。

如需直接从浏览器访问，请显式设置允许来源列表：

API_SERVER_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

启用 CORS 时：

  • 预检请求（Preflight）包含 Access-Control-Max-Age: 600（缓存 10 分钟）
  • SSE 流式响应 包含 CORS 头，确保浏览器 EventSource 客户端正常工作
  • Idempotency-Key 是允许的请求头——客户端可发送它用于去重（响应按键缓存 5 分钟）

大多数文档化的前端（如 Open WebUI）采用服务端到服务端连接，无需 CORS。

兼容前端​

任何支持 OpenAI API 格式的前端均可使用。已测试/文档化集成：

前端星标数连接方式
Open WebUI126k提供完整指南
LobeChat73k自定义提供商端点
LibreChat34klibrechat.yaml 中设置自定义端点
AnythingLLM56k通用 OpenAI 提供商
NextChat87k使用 BASE_URL 环境变量
ChatBox39k设置 API 主机
Jan26k远程模型配置
HF Chat-UI8kOPENAI_BASE_URL
big-AGI7k自定义端点
OpenAI Python SDK—OpenAI(base_url="http://localhost:8642/v1")
curl—直接 HTTP 请求

多用户设置与配置文件​

要为多个用户提供各自独立的 Hermes 实例（包括独立配置、记忆和技能），请使用 配置文件：

# Create a profile per user
hermes profile create alice
hermes profile create bob

# Configure each profile's API server on a different port
hermes -p alice config set API_SERVER_ENABLED true
hermes -p alice config set API_SERVER_PORT 8643
hermes -p alice config set API_SERVER_KEY alice-secret

hermes -p bob config set API_SERVER_ENABLED true
hermes -p bob config set API_SERVER_PORT 8644
hermes -p bob config set API_SERVER_KEY bob-secret

# Start each profile's gateway
hermes -p alice gateway &
hermes -p bob gateway &

每个配置文件的 API 服务器会自动将其配置文件名作为模型 ID 广播：

在 Open WebUI 中，为每个用户分别添加连接即可。模型下拉菜单里会显示 alice 和 bob 两个独立模型，它们分别由彼此隔离的 Hermes 实例提供。详情见 Open WebUI 指南。

限制​

  • 响应存储 — 存储的响应（用于 previous_response_id）持久化于 SQLite，重启网关后仍存在。最多保存 100 条响应（LRU 淘汰策略）。
  • 不支持文件上传 — 通过上传文件实现视觉/文档分析的功能尚未通过 API 支持。
  • 模型字段仅为装饰性 — 请求中的 model 字段虽被接受，但实际使用的 LLM 模型由 config.yaml 中的服务器端配置决定。