---
title: "Open WebUI | Hermes Agent"
type: source
tags:
  - "hermes-agent"
  - "open-webui"
  - "integration"
  - "api-server"
  - "docker"
date: 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 是默认稳定选择