IT相关 · 2026年8月15日

Hermes Agent 搭建 Web 前端：Open WebUI 连接内置 API Server 全攻略

前言

Hermes Agent 除了提供命令行终端、桌面应用和 TUI 界面之外，还内置了一个 OpenAI 兼容的 API Server，可以用来连接 Open WebUI 等第三方 Web 前端。本文将详细介绍如何配置 Hermes 的 API Server 并将其连接到 Open WebUI。

环境准备

  • 服务器：Debian 12
  • Hermes Agent：已安装并运行
  • Open WebUI：通过 Docker 部署

第一步：配置 Hermes 内置 API Server

1. 编辑环境变量

Hermes 的 API Server 配置通过环境变量管理，位于 ~/.hermes/.env 文件中：

# API SERVER (Built-in API server for Open WebUI / other frontends)
API_SERVER_ENABLED=true
API_SERVER_KEY=你的API密钥
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642

各项说明：

  • API_SERVER_ENABLED=true：启用 API Server
  • API_SERVER_KEY：API 访问密钥，Open WebUI 连接时需提供此密钥
  • API_SERVER_HOST=0.0.0.0：监听所有网络接口（如需限制仅本地访问，可改为 127.0.0.1）
  • API_SERVER_PORT=8642：监听端口

如果你的 ~/.hermes/.env 文件中没有这些配置，手动添加即可。

2. 重启网关使配置生效

systemctl --user restart hermes-gateway
# 或
systemctl restart hermes-gateway

注意：修改 API_SERVER_HOST 和 API_SERVER_PORT 后必须编辑 .env 文件并重启 Hermes 网关才能生效。

3. 验证 API Server 是否启动成功

curl http://127.0.0.1:8642/health

预期返回：

{"status": "ok", "platform": "hermes-agent", "version": "版本号"}

4. 测试 API 接口

使用 curl 测试 models 接口，确认 API Key 有效（将 你的密钥 替换为 API_SERVER_KEY 的实际值）：

curl -H "Authorization: Bearer 你的密钥" http://172.17.0.1:8642/v1/models

如果返回模型列表，说明 API Server 配置成功。

第二步：部署 Open WebUI

1. 使用 Docker 运行

docker run -d \
  --name open-webui \
  --restart unless-stopped \
  -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 \
  -e OPENAI_API_KEY=你的密钥 \
  -e OLLAMA_DISABLE=true \
  -e ENABLE_OLLAMA_API=false \
  -e WEBUI_NAME="My AI" \
  ghcr.io/open-webui/open-webui:latest

关键环境变量说明：

  • OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1：指向 Hermes 的 API Server 地址
  • OPENAI_API_KEY：与 API_SERVER_KEY 保持一致
  • OLLAMA_DISABLE=true：禁用 Ollama（Hermes 不依赖 Ollama）
  • ENABLE_OLLAMA_API=false：禁用 Ollama API 暴露
  • WEBUI_NAME：自定义页面标题

2. 启动验证

Open WebUI 启动需要 2-3 分钟完成数据库迁移和模型下载。启动完成后：

docker ps | grep open-webui

查看端口映射是否为 0.0.0.0:3000->8080/tcp，然后访问 http://你的IP:3000。

第三步：在 Open WebUI 中配置

如果使用 Docker 启动时未设置 OPENAI_API_BASE_URL 和 OPENAI_API_KEY，也可以在 Open WebUI 的 Web 界面手动配置：

  1. 打开 http://你的IP:3000，登录后点击左侧边栏底部的用户头像
  2. 在弹出菜单中选择 “Settings”
  3. 进入 “Admin Settings” 标签页
  4. 在 “Models” 部分点击 “Add Model”
  5. 配置模型信息：
    • Type：选择 OpenAI Compatible
    • Model Base URL：http://172.17.0.1:8642/v1
    • API Key：填入你的 API_SERVER_KEY
    • Model ID：选择要使用的模型

常见问题

Q1：Open WebUI 连接 Hermes API 失败，返回 401

检查 API_SERVER_KEY 和 OPENAI_API_KEY 是否一致。在 Hermes 的 ~/.hermes/.env 中查看当前密钥：

grep API_SERVER_KEY ~/.hermes/.env

Q2：容器启动后一直 unhealthy

Open WebUI 启动需要 2-3 分钟（数据库迁移、模型下载），刚启动就判断失败是常见误区。至少等待 3 分钟后再检查。

Q3：容器内没有 ps/ss/netstat 等工具

Debian Slim 镜像没有这些工具，可以用替代方案：

# 查看主进程
docker exec open-webui cat /proc/1/cmdline | tr '' ' '

# 查看监听端口
docker exec open-webui cat /proc/net/tcp6

Q4：API Server 未启动

检查配置和日志：

systemctl status hermes-gateway
grep api ~/.hermes/.env

重启网关：

systemctl restart hermes-gateway

总结

通过配置 Hermes 的内置 API Server，可以将 Hermes Agent 的能力开放给 Open WebUI 等第三方 Web 前端，获得更友好的对话界面。整个流程分为三步：

  1. 在 ~/.hermes/.env 中启用并配置 API Server
  2. 启动 Open WebUI，配置其指向 Hermes API Server
  3. （可选）通过 Nginx 反向代理，绑定域名访问

Hermes Agent 的 API Server 是 OpenAI 兼容的，除了 Open WebUI 之外，也可以连接到任何支持 OpenAI API 格式的 Web 前端。

标签：