API Server

API Server 將 hermes-agent 暴露為一個與 OpenAI 兼容的 HTTP 端點。任何支持 OpenAI 格式的前端——Open WebUI、LobeChat、LibreChat、NextChat、ChatBox 以及數百個其他應用——都可以連接到 hermes-agent 並將其作為後端使用。

你的 Agent 會使用其完整的工具集（終端、文件操作、網絡搜索、記憶、技能）處理請求，並返回最終響應。在流式傳輸時，工具執行進度指示器會內聯顯示，使前端能夠實時瞭解 Agent 正在執行的操作。

快速開始

1. 啟用 API Server

將以下內容添加到 ~/.hermes/.env：

API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev
# 可選：僅當瀏覽器必須直接調用 Hermes 時
# 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：

# 用捲曲測試
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 塊發送。

流式傳輸中的工具進度：在流式請求期間，當 Agent 調用工具時，簡短的進度指示器會作為工具開始執行時的內聯內容注入到內容流中（例如 `💻 pwd`, `🔍 Python docs`）。這些內容以內聯 Markdown 形式出現在 Agent 響應文本之前，使 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

列出 Agent 作為可用模型。廣告的模型名稱默認為 配置文件 名稱（默認配置文件為 hermes-agent）。大多數前端需要此接口進行模型發現。

GET /health

健康檢查。返回 {"status": "ok"}。也支持 GET /v1/health，以滿足期望 /v1/ 前綴的 OpenAI 兼容客戶端。

系統提示處理

當前端發送 system 消息（Chat Completions）或 instructions 字段（Responses API）時，hermes-agent 會將其疊加在核心繫統提示之上。你的 Agent 將保留所有工具、記憶和技能——前端的系統提示僅添加額外指令。

這意味著你可以為不同前端自定義行為，而不會丟失任何功能：

• Open WebUI 系統提示：“你是一位 Python 專家。始終包含類型註解。”
• Agent 仍然具備終端、文件工具、網絡搜索、記憶等功能。

認證

通過 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

# 尚不支持——使用環境變量。
# config.yaml 支持將在未來版本中提供。

安全頭信息

所有響應均包含安全頭信息：

• 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 實例（獨立配置、內存、技能），請使用 配置文件：

# 為每個用戶創建一個 profile
hermes profile create alice
hermes profile create bob

# 在不同端口上配置每個 profile 的 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

# 啟動每個profile的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 中的服務器端配置決定。