---
title: "Expose hermes-agent as an OpenAI-compatible API for any frontend"
type: source
tags:
  - "hermes-agent"
  - "api-server"
  - "openai-compatible"
  - "integration"
date: 2026-04-20
---

## Source File
- [[Agent/Expose hermes-agent as an OpenAI-compatible API for any frontend]]

## Summary（用中文描述）
- 核心主题：hermes-agent API Server 功能 —— 将 hermes-agent 暴露为 OpenAI 兼容的 HTTP API，使任何支持 OpenAI 格式的前端都能连接使用
- 问题域：AI Agent 的可访问性问题 —— 如何让任意前端（Open WebUI、LobeChat、LibreChat 等）接入 hermes-agent
- 方法/机制：
  - 通过 `API_SERVER_ENABLED=true` 启用内建 API Server
  - 默认监听 `127.0.0.1:8642`，Bearer token 认证
  - 支持 Chat Completions API（无状态）、Responses API（有状态会话）、Runs API（实时进度）、Jobs API（定时任务）
  - 系统提示词分层叠加，前端提示词不会覆盖 Agent 原有工具集
- 结论/价值：hermes-agent 可作为 OpenAI API 的直接替代品，无缝接入现有 AI 前端生态，无需修改前端代码

## Key Claims（用中文描述）
- hermes-agent API Server 将 Agent 暴露为 OpenAI 兼容 HTTP 端点，任何 OpenAI 格式的前端均可直连
- 默认绑定 `127.0.0.1:8642`，需配置 `API_SERVER_KEY` 启用 Bearer token 认证
- `/v1/chat/completions` 为无状态接口，每次请求需传递完整对话历史
- `/v1/responses` 支持服务端会话状态，通过 `previous_response_id` 链式调用保留完整上下文（含工具调用）
- `/v1/runs` API 通过 `run_id` + SSE 事件流实现长会话实时进度订阅
- Jobs API 提供 CRUD 接口，支持从远程客户端管理定时/后台 Agent 任务
- 前端传入的 system prompt 在 Agent 核心提示词之上分层叠加，保留全部工具能力
- 多用户场景通过 Profiles 隔离，每个 Profile 运行独立 API Server 实例（不同端口和认证密钥）

## Key Quotes
> "Any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, NextChat, ChatBox, and hundreds more — can connect to hermes-agent and use it as a backend." — 官方文档

> "Your agent handles requests with its full toolset (terminal, file operations, web search, memory, skills) and returns the final response." — 官方文档

> "When a frontend sends a system message (Chat Completions) or instructions field (Responses API), hermes-agent layers it on top of its core system prompt. Your agent keeps all its tools, memory, and skills." — 官方文档

> "The API server gives full access to hermes-agent's toolset, including terminal commands. When binding to a non-loopback address like 0.0.0.0, API_SERVER_KEY is required." — 官方文档安全警告

## Key Concepts
- [[OpenAI-Compatible API]]：遵循 OpenAI API 格式标准的接口层，允许非 OpenAI 后端替代原生服务
- [[Bearer Token Authentication]]：通过 `Authorization: Bearer <token>` 头部进行 API 身份验证
- [[System Prompt Layering]]：前端提示词在 Agent 核心提示词之上分层叠加，不覆盖原有工具集
- [[Conversation State Persistence]]：服务端存储完整对话历史（含工具调用），客户端无需管理上下文
- [[Server-Sent Events (SSE)]]：流式响应协议，支持 token-by-token 推送和自定义工具进度事件
- [[CORS Allowlist]]：浏览器跨域访问控制，通过白名单精确控制允许的来源
- [[Multi-Profile Isolation]]：通过 Profiles 实现多用户隔离，每个实例独立配置、内存、技能
- [[Background Job Scheduling]]：远程客户端通过 Jobs API 管理定时/后台 Agent 任务

## Key Entities
- [[hermes-agent]]：主项目， NousResearch 出品的 AI 编码 Agent，配备完整工具集（终端、文件、网络搜索、记忆、Skills）
- [[Open WebUI]]：开源 AI Web UI（126k stars），有完整集成指南
- [[LobeChat]]：开源 AI 聊天前端（73k stars），自定义 Provider 接入
- [[LibreChat]]：开源多后端聊天平台（34k stars），通过 librechat.yaml 配置
- [[NextChat]]：开源 ChatGPT Web 应用（87k stars），通过 BASE_URL 环境变量接入
- [[ChatBox]]：开源 AI 客户端（39k stars），API Host 设置接入
- [[AnythingLLM]]：开源 RAG AI 应用（56k stars），Generic OpenAI Provider 接入
- [[Jan]]：开源本地 AI 应用（26k stars），Remote Model 配置接入

## Connections
- [[hermes-agent]] ← exposes ← [[OpenAI-Compatible API]]
- [[Open WebUI]] ← connects_to ← [[hermes-agent]] API Server
- [[LobeChat]] ← connects_to ← [[hermes-agent]] API Server
- [[LibreChat]] ← connects_to ← [[hermes-agent]] API Server
- [[NextChat]] ← connects_to ← [[hermes-agent]] API Server
- [[hermes-agent]] ← supports ← [[Multi-Profile Isolation]]
- [[hermes-agent]] ← implements ← [[Background Job Scheduling]]

## Contradictions
- （暂无检测到冲突）