62 lines
3.8 KiB
Markdown
62 lines
3.8 KiB
Markdown
---
|
||
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 是默认稳定选择
|