Hermes 集成 Open WebUI 完整指南

发布于 2026-05-10 14:44

Hermes 集成 Open WebUI 完整指南

将 Hermes Agent 配置为 OpenAI-compatible API Server，并接入 Open WebUI 作为可视化对话界面。本文所有配置和命令均经过实际环境验证，可直接参考操作。

目录

  1. 方案概述
  2. 前置条件
  3. 配置 Hermes API Server
  4. 启动 Hermes Gateway
  5. 验证 OpenAI-compatible API
  6. 安装 Open WebUI
  7. 在 Open WebUI 中配置 Hermes
  8. 系统架构与工作流程
  9. 使用技巧与最佳实践
  10. 常见问题排查

方案概述

Hermes Agent 支持以 OpenAI-compatible 的形式对外提供 API 服务，这意味着任何兼容 OpenAI API 规范的客户端（包括 Open WebUI、LangChain、Dify 等）都可以无缝对接。本方案使用 Open WebUI 作为前端对话界面，负责用户交互和会话管理；所有模型推理请求通过 Hermes Gateway 转发至实际的后端模型提供商（如 OpenRouter、Ollama 等）。

核心优势：

  • 不需要修改模型提供商配置，即插即用
  • Open WebUI 仅承担界面展示和会话存储，不下载模型权重
  • 统一 API 入口，便于多客户端接入

前置条件

在开始之前，请确保：

  • 已正确安装并配置 Hermes Agent，模型提供商（如 OpenRouter、Ollama 等）可正常使用
  • 本地已安装 Docker 及 Docker Compose
  • ~/.hermes/.env 配置文件已存在且 Hermes 可正常启动
  • 系统端口 8642（Hermes API）和 8080（Open WebUI）未被占用

配置 Hermes API Server

编辑 Hermes 的环境配置文件：

文件路径： ~/.hermes/.env

在文件中增加或修改以下配置项：

GATEWAY_ALLOW_ALL_USERS=true
API_SERVER_PORT=8642              # API Server 监听端口，默认 8642
API_SERVER_HOST=127.0.0.1         # 监听地址，默认仅允许本地访问；如需远程访问可改为 0.0.0.0
API_SERVER_MODEL_NAME=hermes-agent  # 对外暴露的模型名称
API_SERVER_ENABLED=true          # 启用 API Server
API_SERVER_KEY=test123            # API 访问密钥，请替换为你的安全密钥

配置项说明：

配置项 说明
GATEWAY_ALLOW_ALL_USERS 允许所有用户通过 Gateway 访问，设为 true 时无需额外鉴权
API_SERVER_PORT API 服务监听端口，可根据需要修改，需与 Open WebUI 配置保持一致
API_SERVER_HOST 建议开发阶段保持 127.0.0.1，生产环境如需外网访问可设为 0.0.0.0
API_SERVER_MODEL_NAME 对外暴露的模型标识名，后续 Open WebUI 中配置需与此一致
API_SERVER_ENABLED 必须设为 true 才会启动 API Server
API_SERVER_KEY Bearer Token 认证密钥，建议使用强密码并妥善保管

注意： 修改 .env 后需要重启 Hermes Gateway 才能生效。

启动 Hermes Gateway

在终端中执行以下命令启动 Gateway：

hermes gateway run

启动成功后，终端应无报错输出。保持该进程运行（建议使用 tmux 或 screen 等工具在后台持久运行）。

如需后台运行，可使用 nohup：

nohup hermes gateway run > /tmp/hermes-gateway.log 2>&1 &

日志会输出到 /tmp/hermes-gateway.log，方便后续排查问题。

验证 OpenAI-compatible API

启动后，可以通过 curl 快速验证 API 是否正常工作：

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer test123" \
  -H "Content-Type: application/json" \
  -d '{"model": "hermes-agent", "messages": [{"role": "user", "content": "Hello!"}]}'

预期结果： 接口正常返回 JSON 格式的流式或完整响应，choices 字段中包含模型回复内容。

验证要点：

  • 状态码为 200：API 正常工作
  • 状态码为 401：检查 API_SERVER_KEY 是否与请求头中的 Bearer Token 一致
  • 连接被拒绝：检查 hermes gateway run 是否已在运行，以及端口是否被占用

安装 Open WebUI

Docker 方式（推荐）

使用以下命令拉取并运行 Open WebUI 容器：

docker rm -f open-webui && \
docker run -d \
  --name open-webui \
  --network host \
  -e ENABLE_PIPELINES=false \
  -v open-webui:/app/backend/data \
  --restart unless-stopped \
  ghcr.io/open-webui/open-webui:main

参数说明：

参数 说明
--network host 使用主机网络，使容器直接监听宿主机端口，无需端口映射
-e ENABLE_PIPELINES=false 禁用 Pipeline 功能，避免不必要的依赖
-v open-webui:/app/backend/data 数据持久化卷，保存用户、会话和配置信息
--restart unless-stopped 开机自动重启，仅在手动停止时不会重启

使用国内镜像加速（可选）

如果 GitHub Container Registry (ghcr.io) 拉取速度较慢，可使用南京大学镜像源：

docker rm -f open-webui && \
docker run -d \
  --name open-webui \
  --network host \
  -e ENABLE_PIPELINES=false \
  -v open-webui:/app/backend/data \
  --restart unless-stopped \
  ghcr.nju.edu.cn/open-webui/open-webui:main

安装成功确认

启动完成后，在浏览器中访问：

http://127.0.0.1:8080/

如果正常出现 Open WebUI 登录/注册页面，则说明安装成功。

首次使用需要注册管理员账号，注册完成后即可登录进入主界面。

在 Open WebUI 中配置 Hermes

步骤一：配置 API 连接

  1. 使用管理员账号登录 Open WebUI
  2. 进入 Admin Panel（管理面板）
  3. 导航至 Settings -> Connections
  4. 滚动页面到 OpenAI 配置区域，填入以下信息：
    • API Base URL: http://localhost:8642/v1
    • API Key: test123（需与 .env 中的 API_SERVER_KEY 保持一致）
  5. 点击 Save 保存配置

步骤二：添加模型

  1. 在 Admin Panel 中导航至 Settings -> Models
  2. 点击 Add Model 按钮
  3. 填写模型信息：
    • Model Name: hermes-agent（必须与 .env 中 API_SERVER_MODEL_NAME 的值一致）
    • Model ID: hermes-agent
    • Base URL: 直接回车即可使用上方已保存的全局默认值，或手动输入 http://localhost:8642/v1

添加完成后，hermes-agent 模型将出现在模型列表中，用户在新建对话时即可选择使用。

系统架构与工作流程

整个集成方案的架构如下：

flowchart TB
    A[User] --> B[Open WebUI\n前端界面]
    B --> C[HTTP 请求\nlocalhost:8080]
    C --> D[Hermes Gateway\nlocalhost:8642]
    D --> E[模型提供商\nOpenRouter/Ollama等]
    E --> F[LLM 推理]
    F --> G[响应返回\n通过相同路径]

工作流程说明：

  1. 用户在 Open WebUI 前端界面输入问题并提交
  2. Open WebUI 以 OpenAI-compatible 格式向 Hermes Gateway（localhost:8642）发起 HTTP 请求
  3. Hermes Gateway 对请求进行鉴权（验证 API Key），然后根据模型名称路由到配置的模型提供商
  4. 模型提供商（如 OpenRouter 或 Ollama）执行 LLM 推理
  5. 推理结果沿相同路径返回，最终在 Open WebUI 界面展示给用户

关键说明： Open WebUI 在此架构中只负责界面渲染和会话记录的存储与管理，不参与模型下载和推理计算。所有模型权重和计算都由后端模型提供商处理。

常见问题排查

Q: API 返回 401 Unauthorized？

原因： API 认证密钥不匹配。

排查步骤：

  1. 检查 ~/.hermes/.env 中的 API_SERVER_KEY 值
  2. 检查 Open WebUI 中 Settings -> Connections -> OpenAI 的 API Key 配置
  3. 确认两端使用的密钥完全一致（注意前后无多余空格或换行）
  4. 修改后需重启 hermes gateway run 进程使配置生效

Q: 模型列表为空，找不到 hermes-agent？

原因： Hermes Gateway 未正常运行或 API Server 未启用。

排查步骤：

  1. 确认 hermes gateway run 进程正在运行
  2. 检查 .env 中 API_SERVER_ENABLED=true 是否已设置
  3. 在浏览器中直接访问 http://localhost:8642/v1/models 查看模型列表（需带 Authorization 头）
  4. 检查 hermes gateway run 的输出日志是否有错误信息

Q: 网络连接失败 / Connection Refused？

原因： 通常是网络配置或防火墙问题。

排查步骤：

  1. 确认 Hermes Gateway 绑定的地址：如果 API_SERVER_HOST=127.0.0.1，则仅允许本机访问
  2. 如果 Open WebUI 运行在 Docker 容器中，使用 --network host 确保容器与宿主机共享网络命名空间
  3. 检查端口是否被其他程序占用：lsof -i :8642 或 netstat -tlnp | grep 8642
  4. 确认防火墙规则未阻止相关端口的通信

Q: 对话过程中出现响应超时？

原因： 后端模型提供商响应缓慢或无法连接。

排查步骤：

  1. 直接调用后端模型提供商的 API，确认其响应是否正常
  2. 检查 Hermes Gateway 日志中是否有上游连接错误
  3. 确认网络环境可以正常访问模型提供商的服务地址

附录：完整环境变量参考

环境变量 默认值 说明
GATEWAY_ALLOW_ALL_USERS - 是否允许所有用户访问 Gateway
API_SERVER_PORT 8642 API 服务器监听端口
API_SERVER_HOST 127.0.0.1 API 服务器监听地址
API_SERVER_MODEL_NAME hermes-agent 对外暴露的模型名称
API_SERVER_ENABLED - 是否启用 API Server
API_SERVER_KEY - API 访问密钥（Bearer Token）

文档最后更新时间： 2026-05-10

本文档所有配置和命令均已通过实际环境验证，如遇到问题请对照常见问题排查章节检查。

← 返回博客列表
文章信息

标题: Hermes 集成 Open WebUI 完整指南

发布时间: 2026-05-10 14:44