API Server

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

你的代理会使用其完整的工具集（终端、文件操作、网络搜索、记忆、技能）处理请求，并返回最终响应。在流式传输时，工具执行进度指示器会内联显示，使前端能够实时了解代理正在执行的操作。

快速开始

1. 启用 API Server

将以下内容添加到 ~/.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 聊天补全格式。无状态——完整的对话历史通过 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}
}

流式传输（"stream": true）：返回 Server-Sent Events (SSE) 格式的 token-by-token 响应块。当配置中启用流式传输时，LLM 生成的 token 会实时发出；当禁用时，完整响应作为单个 SSE 块发送。

流式传输中的工具进度：在流式请求期间，当代理调用工具时，简短的进度指示器会作为工具开始执行时的内联内容注入到内容流中（例如 `💻 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 参数代替追踪响应 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/{id}`

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

`DELETE /v1/responses/{id}`

删除一个已存储的响应。

GET /v1/models

列出代理作为可用模型。广告的模型名称默认为配置文件名称（默认配置文件为 hermes-agent）。大多数前端需要此接口进行模型发现。

GET /health

健康检查。返回 {"status": "ok"}。也支持 GET /v1/health，以满足期望 /v1/ 前缀的 OpenAI 兼容客户端。

系统提示处理

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

这意味着你可以为不同前端自定义行为，而不会丢失任何功能：

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

认证

通过 Authorization 头使用 Bearer Token 认证：

Authorization: Bearer ***

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

安全性

API Server 提供对 hermes-agent 工具集的完全访问权限，包括终端命令。当绑定到非回环地址（如 0.0.0.0）时，API_SERVER_KEY 是 必需的。同时应将 API_SERVER_CORS_ORIGINS 保持狭窄，以控制浏览器访问。

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

配置

环境变量

变量	默认值	描述
`API_SERVER_ENABLED`	`false`	启用 API Server
`API_SERVER_PORT`	`8642`	HTTP 服务器端口
`API_SERVER_HOST`	`127.0.0.1`	绑定地址（默认仅限本地）
`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 后：

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

大多数已文档化的前端（如 Open WebUI）均采用服务端到服务端连接，完全不需要 CORS。

兼容前端

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

前端	星标数	连接方式
Open WebUI	126k	提供完整指南
LobeChat	73k	自定义提供者端点
LibreChat	34k	librechat.yaml 中的自定义端点
AnythingLLM	56k	通用 OpenAI 提供者
NextChat	87k	BASE_URL 环境变量
ChatBox	39k	API 主机设置
Jan	26k	远程模型配置
HF Chat-UI	8k	OPENAI_BASE_URL
big-AGI	7k	自定义端点
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 广播：

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 中的服务器端配置决定。

快速开始​

1. 启用 API Server​

2. 启动网关​

3. 连接前端​

端点​

POST /v1/chat/completions​

POST /v1/responses​

多轮对话与 previous_response_id​

命名对话​

GET /v1/responses/{id}​

DELETE /v1/responses/{id}​

GET /v1/models​

GET /health​

系统提示处理​

认证​

配置​

环境变量​

config.yaml​

安全头信息​

CORS​

兼容前端​

多用户设置与配置文件​

限制​