背景

Hermes Agent 默认在终端里交互，但终端对很多人来说不够直观。hermes-webui 是社区维护的专用 Web 前端，提供流式聊天、工具调用卡片、会话管理、文件浏览等功能，是目前体验最好的 Hermes 浏览器客户端。

本文介绍 hermes-webui 的安装、配置和日常使用。

hermes-webui 是什么

先厘清三个概念：

hermes-webui hermes dashboard Open WebUI
定位 专用聊天前端 内置管理面板 通用 LLM 前端
仓库 nesquena/hermes-webui 内置命令 hermes dashboard open-webui/open-webui
聊天体验 流式输出、工具卡片、Mermaid 图 嵌入式终端 TUI 通用聊天界面
Hermes 特性 工具调用卡片、审批流、子代理卡片 配置编辑、Cron、技能、日志 无（不知道 Hermes 的存在）
适合场景 日常聊天 + 工作区 管理/运维/配置 多模型对比

推荐组合：hermes-webui 负责聊天，hermes dashboard 负责管理。两者互补。

安装

前置条件

  • Python 3（系统自带即可）
  • 已安装 Hermes Agent（hermes doctor 能正常运行）

手动安装（推荐）

1
2
3
4
5
cd ~
git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 -m venv .venv
.venv/bin/pip install pyyaml python-dotenv requests

依赖只有三个包，没有构建步骤，前端是原生 JS。

启动

1
python3 server.py

默认监听 http://127.0.0.1:8787。

关于 bootstrap.py

仓库提供了 python3 bootstrap.py 一键脚本，会尝试自动检测/安装 Hermes Agent。如果系统已经装好了 Hermes，这个脚本可能卡在 agent 发现阶段。直接用上面的手动方式更可靠。

配置

通过环境变量控制行为：

变量 默认值 说明
HERMES_WEBUI_HOST 127.0.0.1 监听地址
HERMES_WEBUI_PORT 8787 端口
HERMES_WEBUI_STATE_DIR ~/.hermes/webui 状态/数据目录
HERMES_WEBUI_PASSWORD （无） 认证密码（暴露到网络时建议设置）
HERMES_WEBUI_AGENT_DIR 自动检测 hermes-agent 源码路径

示例：修改端口并设置密码

1
2
3
HERMES_WEBUI_PORT=9000 \
HERMES_WEBUI_PASSWORD=mysecret \
python3 server.py

后台运行

ctl.sh 守护进程

仓库自带 ctl.sh 脚本：

1
2
3
4
5
6
cd ~/hermes-webui
./ctl.sh start        # 后台启动，PID 写入 ~/.hermes/webui.pid
./ctl.sh status       # 查看 PID、运行时间、端口、健康状态
./ctl.sh logs --lines 100
./ctl.sh restart
./ctl.sh stop

systemd 用户服务（开机自启）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
cat > ~/.config/systemd/user/hermes-webui.service << 'EOF'
[Unit]
Description=Hermes WebUI
After=network.target

[Service]
Type=simple
WorkingDirectory=%h/hermes-webui
ExecStart=%h/hermes-webui/.venv/bin/python3 server.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now hermes-webui

查看状态：

1
2
systemctl --user status hermes-webui
journalctl --user -u hermes-webui -f

功能概览

聊天界面

  • 流式输出：实时显示 AI 回复，不是等全部生成完再一次性弹出
  • 工具调用卡片：Hermes 执行 terminal、file、web 等工具时，以卡片形式展示输入/输出，而不是一堆原始 JSON
  • 子代理卡片：delegate_task 生成的子任务有独立的进度展示
  • Mermaid 图表：AI 生成的 Mermaid 语法直接渲染成图
  • 审批流程：危险命令执行前的确认交互，在 WebUI 里直接操作

会话管理

  • 搜索历史会话（FTS5 全文检索）
  • 置顶、归档、导出会话
  • 跨会话上下文延续

文件浏览器

  • 浏览工作区文件
  • 自动检测 Git 仓库状态
  • 直接查看文件内容

语音输入

支持 Web Speech API，浏览器端语音转文字。

内置 Dashboard

Hermes Agent 自带一个管理面板，和 hermes-webui 互补：

1
2
3
hermes dashboard              # http://127.0.0.1:9119
hermes dashboard --port 8080  # 自定义端口
hermes dashboard --no-open    # 不自动打开浏览器

需要额外依赖：

1
pip install 'hermes-agent[web,pty]'

Dashboard 包含：Status、Chat（嵌入式 TUI）、Config（150+ 字段可视化编辑）、API Keys、Sessions、Logs、Analytics、Cron、Skills。

踩坑记录

端口被占用

如果之前手动运行过 server.py，端口可能没释放：

1
fuser -k 8787/tcp

然后再启动 systemd 服务。

缺少依赖

server.py 会导入 run_agent，需要 pyyaml、python-dotenv、requests 三个包。缺了的话服务能启动但 agent 功能静默失败。确保都装了：

1
.venv/bin/pip install pyyaml python-dotenv requests

暴露到网络

默认只监听 127.0.0.1，安全。如果需要从其他设备访问：

  1. 设置 HERMES_WEBUI_HOST=0.0.0.0
  2. 必须设置 HERMES_WEBUI_PASSWORD，否则任何能访问端口的人都能读你的会话

总结

hermes-webui 是目前 Hermes Agent 体验最好的 Web 前端：

  1. 轻量：三个 Python 依赖，无构建步骤
  2. 专用：工具卡片、审批流、子代理展示都是 Hermes 特有的
  3. 易部署：ctl.sh 或 systemd 二选一

配合内置的 hermes dashboard 做管理，日常使用和运维都能覆盖。

参考资料