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 代理和现有模型，无需额外设置。

手动 docker run（不使用 compose）

docker pull ghcr.io/nesquena/hermes-webui:latest
docker run -d \
-e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
-v ~/.hermes:/home/hermeswebui/.hermes \
-e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
-v ~/workspace:/workspace \
-p 127.0.0.1:8787:8787 \
ghcr.io/nesquena/hermes-webui:latest

本地构建

docker build -t hermes-webui .
docker run -d \
-e WANTED_UID=$(id -u) -e WANTED_GID=$(id -g) \
-v ~/.hermes:/home/hermeswebui/.hermes \
-e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
-v ~/workspace:/workspace \
-p 127.0.0.1:8787:8787 \
hermes-webui

多容器设置

如果希望将代理和 WebUI 放在单独的容器中（出于隔离目的，或因为您已在其他位置运行代理网关）：

# 代理 + WebUI
docker compose -f docker-compose.two-container.yml up -d

# 代理 + 仪表板 + WebUI
docker compose -f docker-compose.three-container.yml up -d

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

[!IMPORTANT] 已知限制（#681）：在双容器设置中，从 WebUI 触发的工具运行在WebUI 容器中，而非代理容器。如果需要在 WebUI 文件系统上使用 git/node 等工具，请使用单容器设置、扩展 WebUI Dockerfile，或使用社区 https://github.com/sunnysktsang/hermes-suite%E3%80%82

[!IMPORTANT] 源代码边界说明（#2453）：多容器设置默认将 hermes-agent-src 以只读方式挂载到 WebUI 中。这可防止 WebUI 端重写源代码，但仍是一种实现耦合桥梁，而非稳定的代理 API 边界。有关当前源代码/API 解耦情况，请参阅 docs/rfcs/agent-source-boundary.md。

常见故障模式

有关上述每种情况的详细说明，请参阅 docs/docker.md。

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

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

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

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

健康检查：

curl http://127.0.0.1:8787/health

设置与配置

• Hermes Control Center（侧边栏启动按钮）—— 对话标签页（导出/导入/清除）、偏好设置标签页（模型、发送键、主题、语言、所有开关）、系统标签页（版本、密码）
• 发送键：Enter（默认）或 Ctrl/Cmd+Enter
• 显示/隐藏 CLI 会话开关（默认启用）
• 令牌使用量显示开关（默认关闭，也可通过 /usage 命令）
• 控制中心始终在对话标签页打开；关闭时重置
• 未保存更改保护——关闭时若存在未持久化的更改，会提示放弃/保存
• 定时任务（Cron）完成提醒——悬浮通知和任务标签页上的未读徽章
• 后台代理错误提醒——非活动会话遇到错误时显示横幅

https://github.com/dobby-d-elf — 前端可靠性与动效优化（6个PR，v0.51.38 → v0.51.58）
已删除目录的工作区回退机制（#2138）、iPhone PWA底部滚动修复（#2143）、新的“活动：X个工具”编辑器底部微光动画（#2203），以及后续动画调整（#2212）。

https://github.com/JKJameson — 编辑器与会话优化（10个PR）
每个会话的持久化编辑器草稿（#1956），以及编辑器和会话侧边栏的一系列优化改进。

https://github.com/gabogabucho — 西班牙语本地化与引导向导
完整的西班牙语（es）本地化，覆盖所有UI字符串，以及一次性引导向导，在首次启动时指导新用户完成提供商设置。

https://github.com/deboste — 反向代理认证与移动响应式布局（PR #3、#4、#5）
首批社区PR中的三个：修复EventSource/fetch以在反向代理设置中使用URL源，修正配置中的模型提供商路由，并添加移动响应式布局及dvh视口修复。早期基础工作。

https://github.com/indigokarasu — 视觉重设计提案（PR #213）
纯CSS实现的全UI重设计——规范的设计标记、替换表情标签栏的图标侧边栏、一致的表单卡片、面包屑导航，以及7个基于自定义属性的内置主题。该PR未直接合并，但塑造了v0.50.0中发布的设计语言和主题架构。

https://github.com/zenc-cp — ReAct循环的防幻觉保护（PR #133）
三层防护方案（临时防幻觉提示、实时令牌过滤、会话历史清理），目前仍在流式处理管道中使用。

https://github.com/Hinotoi-agent — 配置文件与会话安全（PR #351、#2048）
配置文件.env密钥隔离修复（PR #351），防止配置文件间的API密钥泄露；会话导入工作区验证（PR #2048），阻止通过精心构造的JSON文件读取根目录（/）的***。

https://github.com/Sanjays2402 — 无限滚动与起始跳转竞争条件修复（PR #1949）
通过生成令牌+互斥锁组合，修复了v0.51.30中无限滚动预加载与起始跳转的_ensureAllMessagesLoaded之间的竞争条件。#1942和#1962中提出的简单标志检查方法对await后的竞争无效，Sanjays2402的修复方案是正确的。

https://github.com/fxd-jason — 实时审批与澄清功能的SSE实现（PR #1350、#1355）
将1.5秒HTTP轮询替换为SSE长连接，用于审批和澄清功能，将延迟从最高1.5秒降至接近即时。解决了所有正确性细节（原子订阅+快照、锁内通知、队列头部 payload、尾部事件重发）。

https://github.com/happy5318 — 自定义提供商模型去重（PR #1947）
修复了不同命名的自定义提供商中相同模型在选择器中被静默去重的问题，Opus在原始测试中发现了需要增强的竞争条件。

https://github.com/NocGeek — 流式滚动与手动 cron 输出持久化（7个PR）
工具/队列卡片插入时的流式滚动视口稳定性（#1360），手动 cron 运行输出和元数据持久化（#1372，从搁置的#1352拆分）。

https://github.com/DavidSchuchert — 德语翻译（PR #190）
完整的德语本地化（de），覆盖所有UI字符串、设置标签、命令和系统消息——并对i18n系统进行了压力测试，发现了多个尚未可翻译的元素，并在同一PR中修复。

https://github.com/Bobby9228 — 移动版配置文件按钮（PR #265）
在移动导航流程中添加配置文件入口，使手机端可切换配置文件。

https://github.com/kevin-ho — OLED主题（PR #168）
第7个内置主题：纯黑背景搭配暖色调强调色，旨在降低烧屏风险。

https://github.com/andrewy-wizard — 中文本地化（PR #177）
初始简体中文（zh）本地化。首批非英语本地化之一。

https://github.com/DelightRun — WebUI会话的session_search修复（PR #356）
追踪到流式处理路径中缺失的SessionDB注入，该问题导致WebUI会话的工具功能静默失效。

https://github.com/lawrencel1ng — Bandit安全修复（PR #354）
系统性Bandit扫描修复：urlopen前的URL scheme验证、MD5的usedforsecurity=False设置，以及40多个裸露的except: pass块替换为适当的日志记录。

https://github.com/shaoxianbilly — Unicode文件名下载（PR #378）
正确的Content-Disposition头，使用RFC 5987 filename*=UTF-8''...编码，确保非ASCII文件名下载时不崩溃。

https://github.com/lx3133584 — 反向代理的CSRF修复（PR #360）
解决了在Nginx Proxy Manager等工具后托管且端口非80/443时的实际使用障碍。

https://github.com/betamod — 安全审计（PR #171）
全面的CSRF/SSRF/XSS/环境竞争条件审计，已在v0.39.0中发布。

https://github.com/TaraTheStar — 机器人名称+思考块+登录重构（PR #132、#176、#181）
可配置的助手显示名称、思考/推理块显示，以及登录页面重构。

仓库

git@github.com:nesquena/hermes-webui.git