Hermes WebUI 使用教程

它是什么、适合谁

如果你在服务器上跑着 Hermes Agent，平时靠终端或者 Telegram/Discord 之类的聊天软件跟它打交道，那么 Hermes WebUI 给你的是第三种、也是最直观的一种方式：浏览器里的完整控制台。左边是会话列表，中间是聊天，右边是工作区文件浏览器，模型、Profile、工作区切换都常驻在输入框下方，用起来和终端里的 Hermes 几乎一模一样。

它适合两类人：一是想在手机/平板上随时指挥 Agent 的自托管用户（响应式布局 + Tailscale/SSH 隧道即可安全访问）；二是想在同一份数据上换一种操作方式的人——WebUI 复用你现有的 Hermes 配置、模型和记忆，不需要任何额外注册或配置。

快速开始

服务器上（Linux/macOS/WSL2）一条命令：

./start.sh

启动后本地打开 http://127.0.0.1:8787，首次进入会有一套引导向导帮你完成模型供应商配置。想让它在后台常驻（家用 NAS/服务器场景）：

./ctl.sh start      # 后台运行
./ctl.sh status     # 查看 PID、端口、日志路径与健康状态
./ctl.sh logs --lines 100
./ctl.sh restart
./ctl.sh stop

Docker 用户：

cp .env.docker.example .env
docker compose up -d
# 打开 http://localhost:8787

从另一台电脑访问远程服务器上的 WebUI（服务默认只监听 127.0.0.1）：

ssh -N -L 8787:127.0.0.1:8787 user@your.server.com
# 然后本地浏览器打开 http://localhost:8787

手机上用

WebUI 对手机做了专门适配：侧边栏变成汉堡抽屉、文件面板从右侧滑出、触控目标不小于 44px。推荐用 Tailscale 组网后从手机直连：

HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD=你的密码 ./start.sh

然后在手机浏览器打开 http://<服务器Tailscale IP>:8787。流量经 WireGuard 端到端加密，应用层再有密码保护，可以直接"添加到主屏幕"当 App 用。

常用操作

新建与切换会话：左侧栏点新会话按钮即可开聊；会话可重命名、复制、删除、置顶（金色标记）、归档（隐藏不删除），还能按"今天/昨天/更早"折叠分组。
组织会话：给会话移动到带颜色的"项目"分组，或在标题里加 #标签 生成彩色标签、点击过滤。
切换模型与 Profile：输入框下方的底栏有模型下拉（按已配置的 Key 动态列出 OpenAI/Anthropic/DeepSeek/OpenRouter 等）和 Profile 切换器（显示网关状态与模型信息），切换 Profile 无需重启服务。
编辑与重试：任何一条历史消息都能就地编辑并从该点重新生成；上一条回答不满意可一键重试；任务运行中可随时点 Stop 取消。
斜杠命令：输入 / 唤起自动补全——/help、/clear、/compress、/model <名称>、/workspace <名称>、/new、/usage（token/费用统计）、/theme。
控制中心：侧边栏底部的启动器按钮，内含会话导出/导入/清空、偏好设置（发送键、主题、语言、各类开关）、系统信息（版本、密码管理）。
面板：顶栏可切到 Tasks（cron 任务的增删改查与运行历史）、Skills（技能浏览/编辑）、Memory（直接编辑 MEMORY.md 与 USER.md）、Todos（当前会话任务清单）、Spaces（工作区管理）。
工作区文件：右侧面板可浏览目录树、预览文本/代码/Markdown/图片、编辑与新建文件，聊天中出现 workspace://路径 链接会直接在右侧打开；工作区头部还会显示 git 分支与未提交文件数。
语音输入：输入框旁的麦克风按钮（支持 Web Speech API 的浏览器），点一下开始、再点或发送即停止，静音约 2 秒自动结束。
主题：控制中心或 /theme 切换亮/暗模式与多套皮肤（default、ares、mono、slate 等），即时预览并持久化。

常见问题

打开要密码吗？ 默认不要（本机访问零摩擦）；设置 HERMES_WEBUI_PASSWORD 后启用密码认证，登录页还支持注册 passkey/WebAuthn，注册后可以改成纯 passkey 登录。
端口能改吗？ 可以，HERMES_WEBUI_PORT=9000 ./start.sh 9000 或在环境变量里设。
右侧工作区是空的？ 多半是工作区目录没挂对，默认工作区是 ~/workspace，可用 HERMES_WEBUI_DEFAULT_WORKSPACE 指定。
Docker 启动报权限错误？ 宿主 UID 与容器不匹配，在 .env 里设 UID=$(id -u)；工作区显示为空同理。
Windows 能装吗？ 官方 bootstrap 暂不支持原生 Windows，请用 Linux/macOS/WSL2；社区有 Windows 原生方案（Python 3.11+ + start.ps1）可参考。
网页和 CLI 的会话互通吗？ 互通。CLI 会话会带金色 cli 徽章出现在侧边栏，点开即可导入完整历史并在网页里继续回复。

更新与版本

WebUI 内置自更新检查：设置面板的 System 页可查看当前版本，检测到新版本时页面顶部会出现更新横幅并附更新说明链接。用 Docker 部署的用户拉取上游 GHCR 的 latest 镜像重建容器即可；源码部署用 git pull 后重启。状态（会话、设置）存放在 ~/.hermes/webui/，更新不影响已有数据。