背景
Hermes Agent 默认在终端里交互，但终端对很多人来说不够直观。hermes-webui 是社区维护的专用 Web 前端，提供流式聊天、工具调用卡片、会话管理、文件浏览等功能，是目前体验最好的 Hermes 浏览器客户端。
本文介绍 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 | cd ~ |
依赖只有三个包，没有构建步骤，前端是原生 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 | HERMES_WEBUI_PORT=9000 \ |
后台运行
ctl.sh 守护进程
仓库自带 ctl.sh 脚本：
1 | cd ~/hermes-webui |
systemd 用户服务（开机自启）
1 | cat > ~/.config/systemd/user/hermes-webui.service << 'EOF' |
查看状态：
1 | systemctl --user status hermes-webui |
功能概览
聊天界面
- 流式输出：实时显示 AI 回复，不是等全部生成完再一次性弹出
- 工具调用卡片：Hermes 执行 terminal、file、web 等工具时，以卡片形式展示输入/输出，而不是一堆原始 JSON
- 子代理卡片：
delegate_task生成的子任务有独立的进度展示 - Mermaid 图表：AI 生成的 Mermaid 语法直接渲染成图
- 审批流程：危险命令执行前的确认交互，在 WebUI 里直接操作
会话管理
- 搜索历史会话（FTS5 全文检索）
- 置顶、归档、导出会话
- 跨会话上下文延续
文件浏览器
- 浏览工作区文件
- 自动检测 Git 仓库状态
- 直接查看文件内容
语音输入
支持 Web Speech API，浏览器端语音转文字。
内置 Dashboard
Hermes Agent 自带一个管理面板，和 hermes-webui 互补：
1 | hermes dashboard |
需要额外依赖：
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，安全。如果需要从其他设备访问：
- 设置
HERMES_WEBUI_HOST=0.0.0.0 - 必须设置
HERMES_WEBUI_PASSWORD，否则任何能访问端口的人都能读你的会话
总结
hermes-webui 是目前 Hermes Agent 体验最好的 Web 前端：
- 轻量：三个 Python 依赖，无构建步骤
- 专用：工具卡片、审批流、子代理展示都是 Hermes 特有的
- 易部署：ctl.sh 或 systemd 二选一
配合内置的 hermes dashboard 做管理，日常使用和运维都能覆盖。
