Hermes WebUI安装与配置常见问题

踩坑一：Web UI 连接 Hermes Gateway 时的「Connection lost」错误

**问题现象**：打开 Hermes WebUI 后，界面显示 Error: Connection lost，每隔几秒重试一次，但始终连不上。

**根因**：Hermes Agent 需要先启动 Gateway，才能让 Web UI 连接。Gateway 端口默认 8787，但如果用 Docker 部署时没有正确映射端口，Web UI 根本找不到 Gateway。

解决方案：

# 先启动 Hermes Gateway（后台运行）
python -m hermes_cli.main gateway &
# 或者用 systemd 服务
systemctl --user start hermes-gateway

# 验证 Gateway 是否正常
curl http://localhost:8787/health
# 应返回 JSON 状态

# 再启动 Hermes WebUI
cd hermes-webui
python3 bootstrap.py --host 0.0.0.0

如果用的是 Docker Compose，确保 docker-compose.yml 中 Gateway 和 WebUI 在同一网络，并且端口映射正确：

services:
  hermes-gateway:
    image: nousresearch/hermes-agent
    ports:
      - "8787:8787"  # Gateway API
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}

  hermes-webui:
    image: ghcr.io/nesquena/hermes-webui
    ports:
      - "3000:3000"  # Web UI
    environment:
      - HERMES_GATEWAY_URL=http://hermes-gateway:8787
    depends_on:
      - hermes-gateway

防止方法：始终先确认 Gateway 处于 Running 状态，再启动 Web UI。可以写一个启动脚本串联两者：

#!/bin/bash
python -m hermes_cli.main gateway &
sleep 3
python3 bootstrap.py --host 0.0.0.0

踩坑二：Web UI 密码验证失败的无限循环

**问题现象**：在浏览器打开 Web UI 后，要求输入密码。输入 HERMES_WEBUI_PASSWORD 环境变量中设置的密码后，页面刷新又要求输入密码，反复循环。

**根因**：Hermes WebUI v0.50.x 引入了 PBKDF2 密钥存储机制，第一次设置密码后会生成 ~/.hermes/webui/.pbkdf2_key 和 ~/.hermes/webui/. signing_key 两个文件。如果修改了 .env 中的密码但没有删除旧密钥文件，Web UI 仍然使用旧的密钥验证。

解决方案：

# 停止 Web UI
# 删除旧的密钥文件
rm -rf ~/.hermes/webui/.pbkdf2_key ~/.hermes/webui/.signing_key

# 确认 .env 文件密码正确
cat ~/.hermes/config.yaml | grep -A5 'webui:'
# 确保有:
# password: your_password

# 重启 Web UI
python3 bootstrap.py --host 0.0.0.0

另一个常见原因：在 systemd 服务中运行 Gateway 但密码通过 systemctl set-environment 设置，没有传递给 Docker 容器内部进程。需要用 Environment= 字段在 systemd unit 文件中传递：

[Service]
Environment="HERMES_WEBUI_PASSWORD=letmein"
Environment="HERMES_GATEWAY_URL=http://localhost:8787"
ExecStart=/usr/bin/python3 /usr/local/bin/bootstrap.py --host 0.0.0.0

踩坑三：端口冲突导致 Web UI 无法启动

**问题现象**：Error: Port 3000 is already in use，Web UI 启动失败。

**根因**：Hermes WebUI 默认占用端口 3000，但服务器上可能有 Node.js 应用、Nginx、其他 Web 服务也在用这个端口。

解决方案：

# 查看端口占用
lsof -i :3000
# 或
ss -tlnp | grep 3000

# 使用 --port 参数指定其他端口
python3 bootstrap.py --host 0.0.0.0 --port 8080

# 永久修改：在 .env 中添加
echo "PORT=8080" >> ~/.hermes/webui/.env

如果配合 Nginx 反向代理，确保代理配置指向正确端口：

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

踩坑四：Profile 切换后对话「消失」

**问题现象**：在 Web UI 中切换了 Profile（比如从 default 切换到 work），之前的对话记录全部不见了。以为数据丢了，但其实只是显示问题。

根因：Hermes Agent 的 Profile 机制和 Web UI 的会话管理之间存在设计不匹配。Profile 包含独立的配置（模型提供方、API 密钥、记忆容器），但 Web UI 把 Profile 当成「命名空间」用来隔离对话。当两个概念的映射关系不清晰时，用户会困惑为什么切换 Profile 后对话「消失」了——因为新 Profile 下的会话列表确实是从空开始的。

解决方案：

理解这个设计逻辑：Profile = 配置命名空间，会话是独立的，不存在跨 Profile 共享。正确的使用方式是：

• 在 `Settings > Profiles` 中创建不同的 Profile（比如分别对应不同项目）
• 每个 Profile 有独立的会话历史
• 如果需要跨项目共享某个对话，手动复制 Session ID 到目标 Profile

避免踩坑的做法：在开始使用前规划好 Profile 结构，不要在使用过程中频繁切换。如果需要导出某个对话，在当前 Profile 内使用 Export Session 功能。

踩坑五：API Key 格式错误导致「Invalid API key」

**问题现象**：连接 Hermes Agent 到 Open WebUI 或其他客户端时，提示 Invalid API key，但 API Key 从 Anthropic Console 复制过来明明是对的。

根因：两种常见错误：

1. **Bearer Token 格式问题**：有些客户端要求请求头写成 Authorization: Bearer sk-ant-...，但 Hermes Gateway 实际期望的是 Authorization: Bearer anthropic-api-key: sk-ant-...（带前缀）

2. **环境变量未传递进 Docker**：如果 Gateway 运行在 Docker 里，但 ANTHROPIC_API_KEY 没有通过 -e 或 env_file 传入，Gateway 拿到的 key 就是空的

解决方案：

检查环境变量是否正确传入：

# 宿主机验证
echo $ANTHROPIC_API_KEY
# 应该返回 sk-ant-... 开头的内容

# Docker 内验证
docker exec  env | grep ANTHROPIC

如果用 Docker Compose，创建一个 .env 文件：

ANTHROPIC_API_KEY=sk-ant-your-key-here

然后在 docker-compose.yml 中引用：

services:
  hermes-gateway:
    image: nousresearch/hermes-agent:v0.14.0
    env_file:
      - .env
    ports:
      - "8787:8787"

如果连接 Open WebUI，正确的连接配置：

URL: http://YOUR_SERVER_IP:8787
API Key: sk-ant-your-key-here  # 不带 Bearer 前缀，直接填 key 本身
Model: claude-sonnet-4-20250514  # 或其他已配置模型

验证安装是否成功的检查清单

运行以下命令逐一确认：

# 1. Gateway 健康检查
curl http://localhost:8787/health
# 期望：{"status": "ok", "version": "0.14.x"}

# 2. Web UI 可访问
curl http://localhost:3000/
# 期望：返回 HTML 页面

# 3. API 模型列表
curl http://localhost:8787/v1/models \
  -H "Authorization: Bearer sk-ant-your-key-here"
# 期望：返回已配置的模型列表

# 4. 防火墙开放端口
sudo ufw status | grep -E '3000|8787'
# 期望：显示为 ALLOW

总结

Hermes WebUI 给 Hermes Agent 补上了缺失的聊天界面，让自托管 AI Agent 的使用体验接近 ChatGPT。但安装配置过程中有 5 个高频踩坑点：

1. Gateway 未启动就先开 Web UI → Connection lost

2. 修改密码后没删旧密钥文件 → 密码验证循环

3. 端口 3000 被占用 → 启动失败

4. 不理解 Profile 和会话的隔离关系 → 对话「消失」

5. Docker 内环境变量没传进去 → Invalid API key

按本文的顺序排查，基本能在 10 分钟内定位并解决所有问题。

👉 想快速上手 AI Agent？试试 MiniMax，国内可直接访问，Token 计划性价比高：

https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link

相关工具文章：

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews