Hermes Web UI

Hermes Agent 是一款运行在服务器上的高级自主代理，可通过终端或消息应用访问，它能记住所学内容，运行时间越长，能力越强。

Hermes WebUI 是一款轻量级、深色主题的 Web 应用界面，可在浏览器中使用 Hermes Agent。与 CLI 体验完全一致——所有可通过终端完成的操作，都能通过此 UI 实现。无需构建步骤，无需框架，无需打包工具。仅需 Python 和原生 JS。

布局：三面板。左侧边栏用于会话和导航，中间为聊天区域，右侧为工作区文件浏览。模型、配置文件和工作区控制项位于输入框底部——在输入时始终可见。圆形上下文环可直观显示令牌使用情况。所有设置和会话工具均位于 Hermes Control Center（侧边栏底部的启动器）中。

• 支持完整配置文件的浅色模式：自定义设置，配置密码
• 带内联预览的工作区文件浏览器
• 会话项目、标签和工具调用卡片

这使你能通过便捷的 Web UI 获得与 Hermes CLI 几乎 1:1 的功能对等体验，可通过 Hermes 环境中的 SSH 隧道安全访问。单条命令即可启动，单条命令即可通过 SSH 隧道在你的电脑上访问。Web UI 的每一部分都使用你现有的 Hermes 代理和现有模型，无需任何额外设置。

Agent + WebUI

docker compose -f docker-compose.two-container.yml up -d

Agent + Dashboard + WebUI

docker compose -f docker-compose.three-container.yml up -d

两个compose文件默认使用命名Docker卷，通过这种方式从根本上解决了UID/GID问题。如果需要使用绑定挂载来共享现有主机目录，请参阅docs/docker.md获取完整迁移方案。

已知限制（#681）：在双容器设置中，从WebUI触发的工具在WebUI容器中运行，而非agent容器。如果需要在WebUI的文件系统中使用git/node等工具，请使用单容器设置、扩展WebUI Dockerfile或使用社区一体化镜像。

已知限制（#681）：在双容器设置中，从WebUI触发的工具在WebUI容器中运行，而非agent容器。如果需要在WebUI的文件系统中使用git/node等工具，请使用单容器设置、扩展WebUI Dockerfile或使用社区一体化镜像。

常见故障模式

PermissionError、UID=$(id -u)、.env、.env: permission denied、fix_credential_permissions()、HERMES_SKIP_CHMOD=1、.env、/workspace、UID=$(id -u)、.env、git: command not found、hermes-agent-src、.hermes、keep-id。有关这些问题的深入分析，请参阅docs/docker.md。

[!NOTE] 默认情况下，Docker Compose绑定到127.0.0.1（仅本地主机）。要在网络上暴露，请在docker-compose.yml中将端口更改为“8787:8787”，并设置HERMES_WEBUI_PASSWORD以启用身份验证。

[!NOTE] 默认情况下，Docker Compose绑定到127.0.0.1（仅本地主机）。要在网络上暴露，请在docker-compose.yml中将端口更改为“8787:8787”，并设置HERMES_WEBUI_PASSWORD以启用身份验证。

127.0.0.1、"8787:8787"、docker-compose.yml、HERMES_WEBUI_PASSWORD

start.sh自动发现的内容

HERMES_WEBUI_AGENT_DIR、~/.hermes/hermes-agent、../hermes-agent、.venv、python3、HERMES_WEBUI_STATE_DIR、~/.hermes/webui-mvp、HERMES_WEBUI_DEFAULT_WORKSPACE、~/workspace、HERMES_WEBUI_PORT、8787。如果自动发现找到了所有内容，则无需其他操作。

覆盖配置（仅在自动检测失败时需要）

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
export HERMES_WEBUI_PYTHON=/path/to/python
export HERMES_WEBUI_PORT=9000
export HERMES_WEBUI_AUTO_INSTALL=1 # 启用agent依赖的自动安装（默认禁用）
./start.sh

或内联执行：

HERMES_WEBUI_AGENT_DIR=/custom/path ./start.sh 9000

环境变量完整列表：

HERMES_WEBUI_AGENT_DIR、HERMES_WEBUI_PYTHON、HERMES_WEBUI_HOST、127.0.0.1、HERMES_WEBUI_PORT、8787、HERMES_WEBUI_STATE_DIR、~/.hermes/webui-mvp、HERMES_WEBUI_DEFAULT_WORKSPACE、~/workspace、HERMES_WEBUI_DEFAULT_MODEL、openai/gpt-5.4-mini、HERMES_WEBUI_PASSWORD、HERMES_WEBUI_EXTENSION_DIR、/extensions/、HERMES_WEBUI_EXTENSION_SCRIPT_URLS、HERMES_WEBUI_EXTENSION_STYLESHEET_URLS、HERMES_HOME、~/.hermes、HERMES_CONFIG_PATH、~/.hermes/config.yaml

从远程机器访问

服务器默认绑定到127.0.0.1（仅回环地址）。如果在VPS或远程服务器上运行Hermes，请从本地机器使用SSH隧道：

ssh -N -L <本地端口>:127.0.0.1:<远程端口> <用户名>@<服务器地址>

示例：

ssh -N -L 8787:127.0.0.1:8787 user@your.server.com

然后在本地浏览器中打开http://localhost:8787。

http://localhost:8787。当start.sh检测到通过SSH运行时，会自动为您打印此命令。

start.sh

使用Tailscale在手机上访问

Tailscale是基于构建的零配置网状。在服务器和手机上安装它，它们将加入同一个私有网络——无需端口转发、无需SSH隧道、无需公网暴露。

Hermes Web UI具有完全响应式设计和移动优化布局（汉堡菜单侧边栏、抽屉式侧边栏顶部标签、触控友好控件），因此非常适合作为手机上的日常代理界面。

设置步骤：

• 在服务器和iPhone/Android手机上安装Tailscale。
• 启动WebUI，监听所有接口并启用密码身份验证：

HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD=your-secret ./start.sh

• 在手机浏览器中打开http://<服务器的Tailscale IP>:8787（在Tailscale应用中或在服务器上使用tailscale ip -4命令查找服务器的Tailscale IP）。

http://<服务器的Tailscale IP>:8787、tailscale ip -4

就是这样。流量通过***进行端到端加密，密码身份验证在应用层保护UI。您可以将其添加到主屏幕，获得类似应用的体验。

提示：如果使用Docker，请在docker-compose.yml的环境变量中设置HERMES_WEBUI_HOST=0.0.0.0（已是默认值）并设置HERMES_WEBUI_PASSWORD。

提示：如果使用Docker，请在docker-compose.yml的环境变量中设置HERMES_WEBUI_HOST=0.0.0.0（已是默认值）并设置HERMES_WEBUI_PASSWORD。

HERMES_WEBUI_HOST=0.0.0.0、docker-compose.yml、HERMES_WEBUI_PASSWORD

手动启动（不使用start.sh）

如果您希望直接启动服务器：

cd /path/to/hermes-agent # 或任何sys.path可找到Hermes模块的位置
HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py

[!NOTE] 使用代理的venv Python（或任何已安装Hermes代理依赖的Python环境）。系统Python会缺少openai、httpx及其他必要包。

健康检查：

curl http://127.0.0.1:8787/health

运行测试

测试会动态发现仓库和Hermes代理——无硬编码路径。

cd hermes-webui
pytest tests/ -v --timeout=60

或显式使用代理venv：

/path/to/hermes-agent/venv/bin/python -m pytest tests/ -v

测试在8788端口的隔离服务器上运行，并使用单独的状态目录。生产数据和实际cron任务绝不会被触及。当前测试数量：100多个测试文件中的3309个测试。

功能

聊天与代理

• 通过SSE实现流式响应（生成令牌时即时显示）
• 多提供商模型支持——任何Hermes API提供商（OpenAI、Anthropic、Google、DeepSeek、Nous Portal、OpenRouter、MiniMax、Z.AI）；模型下拉列表根据已配置的密钥动态生成
• 处理消息时发送新消息——自动加入队列
• 内联编辑任何历史用户消息并从该点重新生成
• 一键重试上次助手响应
• 直接从编辑器底部取消正在运行的任务（发送按钮旁的停止按钮）
• 内联工具调用卡片——每张卡片显示工具名称、参数和结果片段；多工具轮次的全部展开/折叠切换
• 子代理委托卡片——子代理活动显示独特图标和缩进边框
• 内联渲染Mermaid图表（流程图、序列图、甘特图）
• 思考/推理展示——Claude扩展思考和o3推理块的可折叠金色主题卡片
• 危险shell命令的审批卡片（允许一次/会话/始终/拒绝）
• 网络中断时SSE自动重连（SSH隧道弹性）
• 文件附件在页面重新加载后保持
• 消息时间戳（每条消息旁显示HH:MM，悬停显示完整日期）
• 代码块复制按钮，带有“已复制！”反馈
• 通过Prism.js实现语法高亮（Python、JS、bash、JSON、SQL等）
• AI响应中的安全HTML渲染（粗体、斜体、代码转换为markdown）
• rAF限流令牌流，实现长响应期间更流畅的渲染
• 编辑器底部的上下文使用指示器——令牌计数、成本和填充条（模型感知）

会话

• 创建、重命名、复制、删除会话，按标题和消息内容搜索
• 每个会话通过⋯下拉菜单执行操作——固定、移至项目、归档、复制、删除
• 将会话固定/标星至侧边栏顶部（金色指示器）
• 归档会话（隐藏但不删除，可切换显示）
• 会话项目——带颜色的命名分组，用于组织会话
• 会话标签——在标题中添加#tag以生成彩色标签并支持点击筛选
• 侧边栏按今日/昨日/更早分组（可折叠日期组）
• 下载为Markdown记录、完整JSON导出或从JSON导入