如何把 Hermes Agent 作为 OpenAI 兼容后端接入 Open WebUI 等前端【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agentHermes Agent 内置了一个 OpenAI 兼容的 API Server开启后任何会说 OpenAI 协议的 Web 前端——Open WebUI、LobeChat、LibreChat、NextChat、ChatBox 等——都可以把它当作后端模型来连接。每个请求到达后Hermes 会用完整的工具集终端、文件操作、web 搜索、记忆、skills处理请求并返回最终响应流式输出时还会内联推送工具执行进度。本文以 Open WebUI 为主路径走通从启用 API Server、启动网关、验证接口到接入前端的完整流程最后说明排查方法和接入其他前端的差异。前提已安装 hermes 命令行工具并且 Hermes 本身已配置好模型 provider——API Server 是 agent 运行时而不是纯 LLM 代理Hermes 需要可用的 provider 配置才能正常响应请求文档建议可先运行hermes setup --portal配置 Nous Portal一次覆盖模型与工具后端。如果之后用 Docker 跑 Open WebUI宿主机上还需要 Docker。在 Hermes 侧启用 API ServerOpen WebUI 官方集成指南使用的写法是hermes config set它会自动把开关路由到config.yaml、把密钥路由到~/.hermes/.envhermes config set API_SERVER_ENABLED true hermes config set API_SERVER_KEY your-secret-key把your-secret-key替换成你自己生成的密钥后面 Open WebUI 侧的OPENAI_API_KEY必须与它完全一致。等价的写法是把环境变量直接写进~/.hermes/.env见 API Server 文档API_SERVER_ENABLEDtrue API_SERVER_KEYchange-me-local-dev如果网关已经在运行需要重启让改动生效这会先停掉再启动hermes gateway进程hermes gateway stop hermes gateway除开关和密钥外相关环境变量及默认值来自 API Server 文档变量默认值说明API_SERVER_ENABLEDfalse启用 API serverAPI_SERVER_PORT8642HTTP 端口API_SERVER_HOST127.0.0.1绑定地址默认仅本机API_SERVER_KEY(必填)Bearer 鉴权令牌API_SERVER_CORS_ORIGINS(无)浏览器直连时的 CORS 白名单同一组设置也可以写在~/.hermes/config.yaml的gateway.api_server:段port、key、host、cors_origins、model_name等环境变量优先于config.yaml。启动网关并验证 API Serverhermes gateway启动成功的标志是终端出现这行文档示例输出[API Server] API server listening on http://127.0.0.1:8642接着在宿主机上跑两条验证命令curl -s http://127.0.0.1:8642/health # 文档示例输出{status: ok, ...} curl -s -H Authorization: Bearer your-secret-key http://127.0.0.1:8642/v1/models # 文档示例输出{object:list,data:[{id:hermes-agent, ...}]}判断方法均来自 Open WebUI 指南/health不通 → 网关没有读到API_SERVER_ENABLEDtrue重启网关/v1/models返回401→Authorization头里的密钥与API_SERVER_KEY不一致/v1/models列表里的模型名默认是 profile 名默认 profile 则是hermes-agent前端模型下拉框里显示的就是这个名字。如果之后要用 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!}]}用 Docker 启动并接入 Open WebUI在宿主机上启动 Open WebUI 容器通过环境变量指向本机 Hermesdocker run -d -p 3000:8080 \ -e OPENAI_API_BASE_URLhttp://host.docker.internal:8642/v1 \ -e OPENAI_API_KEYyour-secret-key \ -e ENABLE_OLLAMA_APIfalse \ --add-hosthost.docker.internal:host-gateway \ -v open-webui:/app/backend/data \ --name open-webui \ --restart always \ ghcr.io/open-webui/open-webui:main命令要点OPENAI_API_BASE_URL必须带/v1后缀指向 Hermes API ServerOPENAI_API_KEY必须非空且等于 Hermes 的API_SERVER_KEYENABLE_OLLAMA_APIfalse关掉默认的 Ollama 后端否则模型选择器上方会出现一个空的 Ollama 区块如果你确实同时运行了 Ollama 可以省略--add-hosthost.docker.internal:host-gateway让容器内的host.docker.internal解析到宿主机Linux 没有 Docker Desktop 时必须见下文排查一节。首次启动需要 15–30 秒Open WebUI 第一次运行会下载约 150MB 的 sentence-transformer 嵌入模型等docker logs open-webui输出稳定后再打开界面。不想用环境变量时也可以走 Admin UI 配置登录http://localhost:3000第一个注册的用户成为管理员→ 点profile avatar→Admin Settings→Connections→ 在OpenAI API下点 wrench 图标Manage→ Add New Connection填入URLhttp://host.docker.internal:8642/v1和与API_SERVER_KEY完全相同的API Key点对勾验证连接后Save。需要注意环境变量只在 Open WebUI首次启动时生效之后连接设置会存在它自己的数据库里。后续改配置要走 Admin UI或者删掉 Docker volume 重来。验证接入结果打开http://localhost:3000完成初始管理员账号创建后模型下拉框中应出现你的 agent显示为 profile 名默认 profile 即hermes-agent发消息即可开始对话。发送一条会触发工具的消息时Open WebUI 会在 agent 最终回答之前流式显示工具进度指示工具 emoji 加关键参数例如ls -la、web 搜索关键词这是 agent 正在调工具而不是卡死的信号。复杂问题会先执行多轮工具调用再产出最终回答响应一次性出现属于文档说明的正常现象不是超时。关于 API 模式Open WebUI 默认使用Chat Completions/v1/chat/completions推荐且开箱即用每次请求携带完整对话历史。也可以在 Admin Settings → Connections → OpenAI → Manage 中把 API Type 改为Responses (Experimental)改走/v1/responses不过文档说明目前 Open WebUI 即使在 Responses 模式下也是客户端管理历史、每次发送完整消息列表该模式的主要收益是结构化的function_call/function_call_outputSSE 事件流而非服务端previous_response_id会话状态。接入其他 OpenAI 兼容前端同一套 API Server 不需要任何 Hermes 侧改动即可给其他前端使用API Server 文档 列出的已测试/已记录集成前端接入方式LobeChatCustom provider endpointLibreChatlibrechat.yaml 中配置 custom endpointAnythingLLM通用 OpenAI providerNextChatBASE_URL环境变量ChatBoxAPI Host 设置JanRemote model configHF Chat-UIOPENAI_BASE_URLbig-AGICustom endpointOpenAI Python SDKOpenAI(base_urlhttp://localhost:8642/v1)原则把基址指向http://hermes主机:8642/v1API Key 填API_SERVER_KEY即可。服务端到服务端连接如 Open WebUI不需要 CORS只有浏览器页面要直连 Hermes 时才需设置API_SERVER_CORS_ORIGINS白名单。常见问题排查以下判断项来自 Open WebUI 指南 的 Troubleshooting 章节模型下拉框为空。依次检查URL 是否带/v1后缀http://host.docker.internal:8642/v1不能只写:8642curl http://localhost:8642/health是否返回{status: ok}带 Bearer 头请求/v1/models是否返回含hermes-agent的列表Docker 网络——容器内localhost指向容器自身而不是宿主机须用host.docker.internal或--networkhost如果漏掉了ENABLE_OLLAMA_APIfalse空的 Ollama 区块会出现在 Hermes 模型上方重启容器加上该变量或在 Admin Settings → Connections 里禁用 Ollama。连接测试通过但模型加载不出来。文档指出这几乎总是漏了/v1后缀Open WebUI 的连接测试只是基础连通性检查不验证模型列表接口。Invalid API key 报错。核对 Open WebUI 的OPENAI_API_KEY与 Hermes 的API_SERVER_KEY是否一致。特别注意Open WebUI 在首次启动后会把 OpenAI 兼容连接设置持久化到自己的数据库如果在 Admin UI 里存过错误的 key只改环境变量不够——要在Admin Settings → Connections里更新或删除已保存的连接或重置 Open WebUI 数据目录/数据库。Linux 上host.docker.internal不解析无 Docker Desktop。文档给出三个选项--add-hosthost.docker.internal:host-gateway--networkhost并把OPENAI_API_BASE_URL改为http://localhost:8642/v1或直接用 Docker 网桥 IP文档示例为http://172.17.0.1:8642/v1。可选用 Profiles 做多用户隔离要给多个用户各自隔离的 Hermes 实例独立配置、记忆、skills用 profiles。API_SERVER_*是环境变量而非 YAML 配置键要写进每个 profile 自己的.env端口避开默认平台占用8644webhook、8645wecom-callback、8646msgraph-webhook例如用8650hermes profile create alice cat ~/.hermes/profiles/alice/.env EOF API_SERVER_ENABLEDtrue API_SERVER_PORT8650 API_SERVER_KEYalice-secret EOF hermes -p alice gateway 每个 profile 的 API Server 自动以 profile 名作为模型 ID 上报如http://localhost:8650/v1/models→ 模型alice。在 Open WebUI 的Admin Settings → Connections中为每个 profile 各加一条连接URL、Key 对应填写模型下拉框就会显示多个彼此隔离的模型再通过管理面板把模型分配给不同 Open WebUI 用户。要改模型显示名在对应 profile 里设置API_SERVER_MODEL_NAME例如hermes -p alice config set API_SERVER_MODEL_NAME Alices Agent限制与边界工具在 API Server 所在主机执行。这是 agent 运行时而非纯 LLM 代理若笔记本上的 Open WebUI 指向远程机器上的 API Serverpwd、文件工具、浏览器工具都跑在远程主机上。需要工具作用于本地工作区时应在本机运行 Hermes。安全。API Server 授予完整工具集访问权包括终端命令API_SERVER_KEY在所有部署中包括默认回环绑定127.0.0.1都是必填的且所有响应带X-Content-Type-Options: nosniff、Referrer-Policy: no-referrer安全头。并发上限。跨 OpenAI 兼容端点与 Runs 端点同时执行的 agent 运行数受max_concurrent_runs限制默认 100关闭达到上限时新的运行请求返回 HTTP 429Too many concurrent runs (max N)客户端应退避重试。模型覆盖行为。在 OpenAI 兼容端点上只带model而不带provider的请求model值默认被忽略通用客户端常硬编码gpt-4o之类名字设计上是回退到网关默认模型需要按请求覆盖时在config.yaml打开gateway.platforms.api_server.direct_model_requests: true或发送显式provider字段。/v1/models上报的始终是稳定的 Hermes 别名hermes-agent或 profile 名不是全部可路由的 provider/模型组合。Responses API 存储。previous_response_id依赖的服务端存储持久化在 SQLite、可跨网关重启最多保留 100 条LRU 淘汰。输入限制。两个 OpenAI 兼容端点都支持内联图片http(s)或data:image/...但上传文件类输入file/input_file/file_id和非图片data:URL 会返回400 unsupported_content_type。完成以上步骤后成功状态可以对照三条输出确认hermes gateway打印 listening 行、/health返回{status: ok}、Open WebUI 模型下拉框出现hermes-agent或你的 profile 名且对话能收到含工具进度的流式响应。需要进一步扩展端点细节时参考 API Server 完整端点文档 与 Programmatic Integration。【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
