nexus/wiki/sources/open-webui-hermes-agent.md

title, type, tags, date

title	type	tags	date
Open WebUI | Hermes Agent	source	hermes-agent open-webui integration api-server docker	2026-04-20

Source File

• Agent/Open WebUI Hermes Agent

Summary（用中文描述）

• 核心主题：如何将 Open WebUI（最流行的自托管 AI 聊天界面）与 Hermes Agent 通过内置 API Server 进行连接
• 问题域：AI 前端与 Agent 后端的集成方案，用户希望通过更友好的 Web UI 访问 Hermes Agent
• 方法/机制：Hermes Agent 提供 OpenAI 兼容的 /v1/chat/completions API Server，Open WebUI 通过 Docker 部署并配置 API Base URL 接入；支持多用户 Profiles 场景下多实例部署
• 结论/价值：用户获得完整的对话管理、用户账户和现代化聊天界面，同时 Agent 保留全部工具集（终端、文件操作、网页搜索、记忆、Skills 等）能力

Key Claims（用中文描述）

• Open WebUI 通过 Hermes Agent 内置 API Server 以类 OpenAI 方式接入，双方无需 CORS 配置（server-to-server 直连）
• 启用 API Server 只需在 ~/.hermes/.env 中设置 API_SERVER_ENABLED=true 和 API_SERVER_KEY=your-secret-key
• Docker 部署 Open WebUI 时，必须使用 host.docker.internal 访问宿主机端口，localhost 在容器内指向容器自身
• 模型下拉菜单默认显示 Profile 名称，可通过 API_SERVER_MODEL_NAME 环境变量覆盖
• 多用户场景下，每个 Profile 运行独立 API Server（不同端口），在 Open WebUI Admin 中逐一添加连接

Key Quotes

"Open WebUI talks to Hermes server-to-server, so you do not need API_SERVER_CORS_ORIGINS for this integration." — 架构说明，server-to-server 无需 CORS

"The model name defaults to the profile name. To override it, set API_SERVER_MODEL_NAME in the profile's .env." — 自定义模型名称的方法

"Environment variables only take effect on Open WebUI's first launch. After that, connection settings are stored in its internal database." — Docker 部署重要限制

Key Concepts

• APIServer: Hermes Agent 内置的 OpenAI 兼容 HTTP Server，提供 /v1/chat/completions 等端点
• ChatCompletions: OpenAI 标准聊天补全 API 格式，默认模式，推荐使用
• ResponsesAPI: OpenAI 实验性响应 API，支持 previous_response_id 维持对话状态和结构化事件流
• ToolStreaming: 工具执行时实时流式输出工具 emoji 和关键参数到 UI，提供可见性
• DockerHostNetworking: Docker 容器访问宿主机服务的方式（host.docker.internal 或 --network=host）

Key Entities

• OpenWebUI: 最流行的自托管 AI 聊天界面（126k GitHub stars），作为 Hermes Agent 的 Web 前端
• HermesAgent: Nous Research 的 AI Agent 框架，支持多平台（CLI、Telegram、Gateway），内置 API Server
• DockerCompose: 多容器应用编排工具，用于持久化部署 Open WebUI
• Profiles: Hermes Agent 的多配置文件系统，每个 Profile 独立运行，支持多用户隔离

Connections

• OpenWebUI ← connects_to ← HermesAgent (via APIServer /v1/chat/completions)
• HermesAgent ← enables ← APIServer (env: API_SERVER_ENABLED=true)
• OpenWebUI ← served_by ← DockerCompose (持久化部署)
• HermesAgent ← scales_via ← Profiles (多用户多实例)

Contradictions

• 与 ResponsesAPI vs ChatCompletions 的选择：
  • 冲突点：两种 API 模式的适用场景描述
  • 当前观点：文档推荐 Chat Completions（开箱即用）；Responses API 提供结构化事件流但当前 Open WebUI 仍客户端管理历史
  • 对方观点：Responses API 可通过 previous_response_id 维持服务端对话状态
  • 注：两者并非真正冲突，Responses 是实验性增强，Chat Completions 是默认稳定选择