SeaHi

主题

00:00:00
SeaHi2026-04-142026-05-31Hermes Agent 中文教程
1999
8.3m

API 服务器 ​

API 服务器将 hermes-agent 暴露为兼容 OpenAI 的 HTTP 端点。任何支持 OpenAI 格式的前端 —— Open WebUI、LobeChat、LibreChat、NextChat、ChatBox 等数百个 —— 都可以连接到 hermes-agent 并将其用作后端。

您的 Agent 使用其完整的工具集（终端、文件操作、网络搜索、记忆、技能）处理请求并返回最终响应。流式传输时，工具进度指示器会内联显示，因此前端可以显示 Agent 正在做什么。

快速开始 ​

1. 启用 API 服务器 ​

添加到 ~/.hermes/.env：

bash
API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# 可选：仅当浏览器需要直接调用 Hermes 时
# API_SERVER_CORS_ORIGINS=http://localhost:3000

2. 启动网关 ​

bash
hermes gateway

您将看到：

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

3. 连接前端 ​

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

bash
# 使用 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 聊天补全格式。无状态 —— 完整的对话通过每个请求中的 messages 数组包含。

请求：

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

响应：

json
{
  "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}
}

流式传输 ("stream": true)：返回带有逐令牌响应块的服务器发送事件 (SSE)。当在配置中启用流式传输时，令牌会在 LLM 生成时实时发出。禁用时，完整响应作为单个 SSE 块发送。

流中的工具进度：当 Agent 在流式请求期间调用工具时，会在内容流中注入简短的进度指示器，显示工具开始执行（例如 `💻 pwd`、`🔍 Python docs`）。这些以内联 markdown 形式出现在 Agent 的响应文本之前，让 Open WebUI 等前端实时了解工具执行情况。

POST /v1/responses ​

OpenAI Responses API 格式。通过 previous_response_id 支持服务器端对话状态 —— 服务器存储完整的对话历史（包括工具调用和结果），因此无需客户端管理即可保留多轮上下文。

请求：

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

响应：

json
{
  "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 进行多轮对话 ​

链式响应以在轮次之间保持完整上下文（包括工具调用）：

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

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

命名对话 ​

使用 conversation 参数替代跟踪响应 ID：

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

服务器自动链接到该对话中的最新响应。类似于网关会话的 /title 命令。

GET /v1/responses/{id} ​

通过 ID 检索先前存储的响应。

DELETE /v1/responses/{id} ​

删除存储的响应。

GET /v1/models ​

将 Agent 列为可用模型。通告的模型名称默认为配置文件名称（或默认配置文件的 hermes-agent）。大多数前端需要此端点进行模型发现。

GET /health ​

健康检查。返回 {"status": "ok"}。也可在 GET /v1/health 获取，适用于期望 /v1/ 前缀的兼容 OpenAI 客户端。

系统提示处理 ​

当前端发送 system 消息（聊天补全）或 instructions 字段（Responses API）时，hermes-agent 会将其叠加在其核心系统提示之上。您的 Agent 保留所有工具、记忆和技能 —— 前端的系统提示添加额外指令。

这意味着您可以按前端自定义行为而不会丢失功能：

  • Open WebUI 系统提示："You are a Python expert. Always include type hints."
  • Agent 仍然拥有终端、文件工具、网络搜索、记忆等。

认证 ​

通过 Authorization 头进行 Bearer 令牌认证：

Authorization: Bearer ***

通过 API_SERVER_KEY 环境变量配置密钥。如果您需要浏览器直接调用 Hermes，还要将 API_SERVER_CORS_ORIGINS 设置为显式允许列表。

安全

API 服务器可完全访问 hermes-agent 的工具集，包括终端命令。当绑定到非环回地址如 0.0.0.0 时，API_SERVER_KEY 是必需的。同时保持 API_SERVER_CORS_ORIGINS 范围狭窄以控制浏览器访问。

默认绑定地址 (127.0.0.1) 仅用于本地使用。默认禁用浏览器访问；仅对显式受信任的来源启用。

配置 ​

环境变量 ​

变量默认值描述
API_SERVER_ENABLEDfalse启用 API 服务器
API_SERVER_PORT8642HTTP 服务器端口
API_SERVER_HOST127.0.0.1绑定地址（默认为仅本地主机）
API_SERVER_KEY(无)Bearer 令牌用于认证
API_SERVER_CORS_ORIGINS(无)逗号分隔的允许浏览器来源
API_SERVER_MODEL_NAME(配置文件名称)/v1/models 上的模型名称。默认为配置文件名称，或默认配置文件的 hermes-agent。

config.yaml ​

yaml
# 尚不支持 —— 使用环境变量。
# config.yaml 支持将在未来版本中推出。

安全头 ​

所有响应都包含安全头：

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

CORS ​

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

对于直接浏览器访问，设置显式允许列表：

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

启用 CORS 时：

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

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

兼容的前端 ​

任何支持 OpenAI API 格式的前端都可以工作。已测试/记录的集成：

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

使用配置文件的多用户设置 ​

要为多个用户提供其自己的隔离 Hermes 实例（单独的配置、记忆、技能），请使用配置文件：

bash
# 为每个用户创建配置文件
hermes profile create alice
hermes profile create bob

# 在每个配置文件上配置 API 服务器使用不同端口
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

# 启动每个配置文件的网关
hermes -p alice gateway &
hermes -p bob gateway &

每个配置文件的 API 服务器自动将配置文件名称通告为模型 ID：

  • http://localhost:8643/v1/models → 模型 alice
  • http://localhost:8644/v1/models → 模型 bob

在 Open WebUI 中，将每个添加为单独连接。模型下拉菜单将 alice 和 bob 显示为不同的模型，每个都由完全隔离的 Hermes 实例支持。有关详细信息，请参阅 Open WebUI 指南。

限制 ​

  • 响应存储 —— 存储的响应（用于 previous_response_id）保存在 SQLite 中，并在网关重启后保留。最多 100 个存储的响应（LRU 驱逐）。
  • 无文件上传 —— 尚不支持通过 API 上传文件进行视觉/文档分析。
  • 模型字段是装饰性的 —— 请求中的 model 字段被接受，但实际使用的 LLM 模型在服务器端的 config.yaml 中配置。