给 Hermes Agent 装上 Open WebUI：从零到一的完整实践

本文面向刚接触 AI 工具链的读者，用尽量通俗的语言解释：为什么要给 Hermes Agent 装 Open WebUI、这样做能带来什么好处、以及具体的实现路径。

一、先搞清楚三个问题

1.1 Hermes Agent 是什么

Hermes Agent 是 Nous Research 开源的一个 AI Agent 框架，核心能力包括：

自动调用工具（代码执行、文件操作、网络搜索等）
多平台消息网关（Telegram、Discord、Slack 等）
技能系统（Skills），可以从经验中学习并自我改进
内置 OpenAI 兼容的 API Server（运行在 localhost:8642）

但它自带的交互方式主要是命令行（CLI）和各种聊天平台的 Bot，没有一个统一的、可视化的 Web 界面。

1.2 Open WebUI 是什么

Open WebUI 是一个开源的、自托管的 AI 对话 Web 界面，你可以把它理解为"部署在自己电脑上的 ChatGPT 网页版"。

它的核心能力：

支持连接任何 OpenAI 兼容的后端（Ollama、OpenAI API、自定义 API 等）
完整的对话管理（历史记录、文件夹、标签）
内置 RAG（知识库检索）、Web 搜索、代码解释器
多用户、权限管理、模型管理
完全本地运行，数据不出本机

1.3 为什么要把它俩连起来

单独使用 Hermes Agent，你只能：

在终端黑窗口里打字对话
或者在 Telegram 等聊天软件里跟 Bot 聊天

而给 Hermes Agent 装上 Open WebUI 之后，你获得了一个现代化的 Web 控制面板，可以同时享受：

能力	之前（纯 CLI）	之后（+ Open WebUI）
对话界面	黑色终端窗口	美观的网页，支持 Markdown、代码高亮
历史记录	终端滚动，容易丢	自动保存，支持搜索、文件夹分类
多轮对话管理	靠记忆	可视化分支、重新生成、继续对话
文件上传	命令行操作	拖拽上传，模型自动解析
知识库	无	RAG 支持，上传文档即可问答
联网搜索	Hermes 自带	Open WebUI 集成，配置更灵活
多人使用	单人终端	多账号、权限控制

二、架构图：数据是怎么流的

2.1 整体架构

flowchart TB
    subgraph Browser["浏览器"]
        UI["Open WebUI 前端
http://localhost:8080"]
    end

    subgraph Local["本机服务"]
        OW["Open WebUI 后端
Python 服务"]
        HG["Hermes Gateway
API Server :8642"]
        HA["Hermes Agent 核心
模型调用 / 工具执行"]
    end

    subgraph External["外部服务"]
        DashScope["阿里云 DashScope
qwen3.6-plus"]
    end

    UI <-->|HTTP| OW
    OW <-->|OpenAI API 格式
POST /v1/chat/completions| HG
    HG <-->|内部调用| HA
    HA <-->|API 请求| DashScope

2.2 一次对话的完整流程

sequenceDiagram
    actor User as 用户
    participant OW as Open WebUI
    participant HG as Hermes Gateway
    participant HA as Hermes Agent
    participant API as 模型提供商

    User->>OW: 在网页输入问题
    OW->>HG: POST /v1/chat/completions
    Note over OW,HG: 使用 OpenAI 兼容格式
    HG->>HA: 转发请求到 Agent 核心
    HA->>API: 调用 qwen3.6-plus 等模型
    API-->>HA: 返回模型输出
    HA-->>HG: 返回处理后的响应
    HG-->>OW: 返回 JSON 响应
    OW-->>User: 在网页展示回答

2.3 部署位置示意

flowchart LR
    subgraph D盘["D: 盘（推荐安装位置）"]
        direction TB
        H["Hermes-Agent\nD:\Program\Hermes-Agent"]
        O["Open-WebUI\nD:\Program\Open-WebUI"]
    end

    subgraph C盘["C: 盘（配置目录）"]
        direction TB
        Config["Hermes 配置\n~/.hermes/config.yaml"]
        Data["Open WebUI 数据\nD:\Program\Open-WebUI\data"]
    end

    H -.->|读取| Config
    O -.->|读取| Data

三、实现路径：一步步做了什么

3.1 第一步：摸清家底

在开始之前，先确认几个关键信息：

检查项	命令/路径	结果
Hermes 安装路径	`D:\Program\Hermes-Agent`	Python 3.14.2 + uv
Hermes 可执行文件	`D:\Program\Hermes-Agent\.venv\Scripts\hermes.exe`	v0.8.0
Hermes 配置	`~/.hermes/config.yaml`	使用 qwen3.6-plus
磁盘空间	D 盘空闲约 693 GB	充足

3.2 第二步：配置 Hermes 的 API Server

Hermes 内置了 API Server 平台，默认监听 localhost:8642，但需要手动在配置中启用。

在 ~/.hermes/config.yaml 中添加：

platforms:
  api_server:
    enabled: true

注意：api_server 不需要 token 或 api_key 就能启动（绑定 127.0.0.1 时）。如果绑定 0.0.0.0 则需要设置 API_SERVER_KEY。

启动 Gateway 验证：

hermes gateway run

验证 API Server 是否就绪：

curl http://127.0.0.1:8642/health
# 预期返回: {"status": "ok", "platform": "hermes-agent"}

curl http://127.0.0.1:8642/v1/models
# 预期返回: hermes-agent 模型信息

3.3 第三步：安装 Open WebUI

Open WebUI 需要 Python 3.11（官方推荐），因此单独创建一个虚拟环境：

# 创建 Python 3.11 虚拟环境（安装在 D 盘）
uv venv "D:\Program\Open-WebUI" --python 3.11

# 安装 pip
D:\Program\Open-WebUI\Scripts\python.exe -m ensurepip

# 安装 Open WebUI
D:\Program\Open-WebUI\Scripts\pip3.exe install open-webui

安装完成后，可执行文件位于：

D:\Program\Open-WebUI\Scripts\open-webui.exe

3.4 第四步：启动 Open WebUI 并连接到 Hermes

通过环境变量告诉 Open WebUI：你的后端是 Hermes，不是 OpenAI 官方。

set OPENAI_API_BASE_URL=http://127.0.0.1:8642/v1
set OPENAI_API_KEY=dummy
set DEFAULT_MODELS=hermes-agent
set ENABLE_OLLAMA_API=false
set DATA_DIR=D:/Program/Open-WebUI/data
set PYTHONUTF8=1

D:\Program\Open-WebUI\Scripts\open-webui.exe serve --host 127.0.0.1 --port 8080

环境变量说明：

变量	值	作用
`OPENAI_API_BASE_URL`	`http://127.0.0.1:8642/v1`	指向 Hermes API Server
`OPENAI_API_KEY`	`dummy`	Hermes 不校验 Key，填任意值
`DEFAULT_MODELS`	`hermes-agent`	默认选中 Hermes 模型
`ENABLE_OLLAMA_API`	`false`	禁用 Ollama，避免连接超时
`DATA_DIR`	`D:/Program/Open-WebUI/data`	数据存储在 D 盘
`PYTHONUTF8`	`1`	强制 UTF-8 编码，避免 Windows 乱码

3.5 第五步：配置 Web 搜索（可选但推荐）

Open WebUI 内置了联网搜索能力，可以配置多个搜索引擎：

搜索引擎	费用	是否需要 API Key
DuckDuckGo	免费	否
Brave Search	免费 2000 次/月	是
SearXNG	免费（自建）	否

配置方式（环境变量）：

# 使用 Brave Search
set ENABLE_WEB_SEARCH=true
set WEB_SEARCH_ENGINE=brave
set BRAVE_SEARCH_API_KEY=your-brave-api-key

# 或者使用 DuckDuckGo（零配置）
set ENABLE_WEB_SEARCH=true
set WEB_SEARCH_ENGINE=duckduckgo

3.6 第六步：创建快捷启动脚本

手动输入环境变量太麻烦，写成批处理脚本一键启动：

@echo off

REM 启动 Hermes Gateway
echo [1/2] Starting Hermes Gateway...
start "Hermes Gateway" /MIN cmd /c "set PYTHONIOENCODING=utf-8 && set PYTHONUTF8=1 && D:\Program\Hermes-Agent\.venv\Scripts\hermes.exe gateway run"

REM 等待 Hermes 就绪
:wait_hermes
timeout /t 2 /nobreak >nul
curl -s http://127.0.0.1:8642/health >nul
if %errorlevel% neq 0 goto wait_hermes

REM 启动 Open WebUI
echo [2/2] Starting Open WebUI...
start "Open WebUI" /MIN cmd /c "set OPENAI_API_BASE_URL=http://127.0.0.1:8642/v1 && set OPENAI_API_KEY=dummy && set ENABLE_OLLAMA_API=false && set DEFAULT_MODELS=hermes-agent && set ENABLE_WEB_SEARCH=true && set WEB_SEARCH_ENGINE=brave && set BRAVE_SEARCH_API_KEY=your-brave-api-key && set DATA_DIR=D:/Program/Open-WebUI/data && set PYTHONUTF8=1 && D:\Program\Open-WebUI\Scripts\open-webui.exe serve --host 127.0.0.1 --port 8080"

echo.
echo Services started:
echo   Hermes API:  http://127.0.0.1:8642
echo   Open WebUI:  http://127.0.0.1:8080
pause

建议创建三个脚本放在 D:\Program\Open-WebUI\ 目录：

脚本	用途
`start.bat`	一键启动所有服务
`stop.bat`	一键停止所有服务
`restart-hermes.bat`	单独重启 Hermes Gateway

四、踩坑记录与排错

4.1 问题一：Ollama 连接超时导致页面卡顿

现象：Open WebUI 加载模型列表时特别慢，每次都要等 2-3 秒。

原因：Open WebUI 默认会尝试连接 localhost:11434（Ollama 默认端口），如果没装 Ollama，就会反复超时。

解决：启动时设置 ENABLE_OLLAMA_API=false。

4.2 问题二：Windows 控制台 Unicode 编码错误

现象：Hermes 日志中大量 UnicodeEncodeError: 'gbk' codec can't encode character。

原因：Windows 默认使用 GBK 编码，而 Hermes 的日志包含 Unicode 字符（如警告图标）。

解决：启动 Hermes 时设置 PYTHONUTF8=1。

4.3 问题三：“No models found”

现象：浏览器里显示找不到模型。

原因分类：

flowchart TD
    A["Open WebUI 显示
No models found"] --> B{"Hermes 是否在运行？"}
    B -->|否| C["运行 start.bat
或 restart-hermes.bat"]
    B -->|是| D["浏览器缓存了旧状态"]
    D --> E["按 Ctrl+Shift+R
强制刷新页面"]

验证命令：

# 检查 Hermes
curl http://127.0.0.1:8642/health

# 检查 Open WebUI
curl http://127.0.0.1:8080/

4.4 问题四：Hermes Gateway 意外退出

现象：用着用着模型突然找不到了。

排查步骤：

检查 Hermes Gateway 窗口是否还在
如果消失了，双击 restart-hermes.bat 重启
浏览器按 Ctrl+Shift+R 强制刷新

五、文件速查表

所有关键文件的位置：

文件/目录	路径	说明
Hermes 安装目录	`D:\Program\Hermes-Agent`	主程序
Hermes 配置	`C:\Users\<用户名>\.hermes\config.yaml`	平台配置、模型配置
Hermes 虚拟环境	`D:\Program\Hermes-Agent\.venv`	Python 依赖
Open WebUI 虚拟环境	`D:\Program\Open-WebUI`	Python 3.11
Open WebUI 数据	`D:\Program\Open-WebUI\data`	数据库、上传文件
Open WebUI 数据库	`D:\Program\Open-WebUI\data\webui.db`	SQLite 数据库
启动脚本	`D:\Program\Open-WebUI\start.bat`	一键启动
停止脚本	`D:\Program\Open-WebUI\stop.bat`	一键停止

六、总结

给 Hermes Agent 装上 Open WebUI，本质上是在命令行工具外面包了一个现代化的 Web 界面。你获得的核心收益：

可视化：告别黑窗口，获得类 ChatGPT 的网页体验
持久化：对话历史自动保存，支持分类管理
扩展性：知识库、联网搜索、代码解释器开箱即用
多用户：可以分享给团队成员使用

整个方案完全本地运行，数据不出本机，适合对隐私有要求的场景。

参考链接

Hermes Agent GitHub: https://github.com/NousResearch/hermes-agent
Open WebUI GitHub: https://github.com/open-webui/open-webui
Brave Search API: https://api-dashboard.search.brave.com/