Hermes Web UI

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

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

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

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

这使您能通过便捷的 Web UI 实现与 Hermes CLI 近乎 1:1 的对等体验，您可以通过 Hermes 环境中的 SSH 隧道安全访问。只需一条命令即可启动，一条命令即可通过 SSH 隧道在您的计算机上访问。Web UI 的每一部分都使用您现有的 Hermes 代理和现有模型，无需额外设置。

Docker

预构建镜像（amd64 + arm64）在每次发布时都会发布到GHCR。

有关涵盖所有3个compose文件、常见故障模式和绑定挂载迁移的综合设置指南，请参见docs/docker.md。README文档涵盖了5分钟快速入门路径。

5分钟快速入门（单容器）

最简单的设置：一个在进程内运行agent的WebUI容器。

git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
# 如果主机UID不是1000（例如macOS的UID从501开始），请编辑.env
docker compose up -d
# 打开 http://localhost:8787

容器会从挂载的~/.hermes卷自动检测您的UID/GID，因此agent写入的文件在主机上仍可被您读取。

要启用密码保护（如果将端口暴露在127.0.0.1之外则必需）：

echo "HERMES_WEBUI_PASSWORD=change-me-to-something-strong"
>> .env
docker compose up -d --force-recreate

手动 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

多容器设置

如果希望agent和WebUI在单独的容器中运行（为了隔离，或者因为您已在其他地方运行agent网关）：

# 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获取完整迁移方法。

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

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

常见故障模式

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

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 # 启用代理依赖的自动安装（默认禁用）
./start.sh

或内联执行：

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

环境变量完整列表：

功能特性

聊天与智能体

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

会话

• 创建、重命名、复制、删除会话，按标题和消息内容搜索
• 每个会话通过⋯下拉菜单执行操作——固定、移动到项目、归档、复制、删除
• 将会话固定/标星到侧边栏顶部（金色指示器）
• 归档会话（隐藏但不删除，可切换显示）
• 会话项目——带颜色的命名组，用于组织会话
• 会话标签——在标题中添加#tag以显示彩色标签并支持点击筛选
• 侧边栏按今日/昨日/更早分组（可折叠日期组）
• 下载为Markdown记录、完整JSON导出或从JSON导入
• 会话在页面重新加载和SSH隧道重连后保持
• 浏览器标签标题反映活动会话名称
• CLI会话桥接——来自hermes-agent SQLite存储的CLI会话在侧边栏显示金色“cli”徽章；点击可导入完整历史并正常回复
• 令牌/成本显示——每次对话显示输入令牌、输出令牌和预估成本（在设置中切换或使用/usage命令）

工作区文件浏览器

• 可展开/折叠的目录树（单击切换，双击导航）
• 带可点击路径段的面包屑导航
• 内联预览文本、代码、Markdown（已渲染）和图像
• 使用workspace://path/to/file的聊天链接在右侧预览窗格中打开文件
• 编辑、创建、删除和重命名文件；创建文件夹
• 二进制文件下载（由服务器自动检测）
• 目录导航时文件预览自动关闭（带未保存编辑保护）
• Git检测——工作区标题中显示分支名称和未提交文件计数徽章
• 右侧面板可拖动调整大小
• 语法高亮代码预览（Prism.js）

语音输入

• 输入框中的麦克风按钮（Web Speech API）
• 点击开始录音，再次点击或发送停止录音
• 实时临时转录文本显示在文本区域
• 沉默约2秒后自动停止
• 追加到现有文本区域内容（不替换）
• 浏览器不支持Web Speech API时隐藏（Chrome、Edge、Safari支持）

配置文件

• 输入框底部的配置文件芯片——下拉菜单显示所有配置文件，包含网关状态和模型信息
• 网关状态点（绿色=运行中）、模型信息、每个配置文件的技能数量
• 配置文件管理面板——从侧边栏创建、切换和删除配置文件
• 创建时从活动配置文件克隆配置
• 创建时可选自定义端点字段——创建时将基础URL和API密钥写入配置文件的config.yaml，因此无需手动编辑文件即可配置Ollama、LMStudio和其他本地端点
• 无缝切换——无需服务器重启；重新加载配置、技能、内存、定时任务、模型
• 按会话跟踪配置文件（记录创建时激活的配置文件）

身份验证与安全

• 可选密码认证——默认关闭，本地主机零摩擦访问
• 通过HERMES_WEBUI_PASSWORD环境变量或设置面板启用
• 可选Passkey/WebAuthn——使用密码登录后从设置->系统注册；至少存在一个Passkey后，登录页面仅显示Passkey登录
• 注册至少一个Passkey后，设置->系统可移除密码并保持仅Passkey登录。在选择无密码登录前，密码认证始终作为引导/恢复途径；Passkey为同源且存储在WebUI状态目录本地
• 带24小时TTL的签名HMAC HTTP-only cookie
• /login路径下的简约深色主题登录页面
• 所有响应均包含安全头（X-Content-Type-Options、X-Frame-Options、Referrer-Policy）
• 20MB POST请求体大小限制
• CDN资源使用SRI完整性哈希固定

主题

• 外观分为两个维度：主题（system、dark、light）和皮肤（default、ares、mono、slate、poseidon、sisyphus、charizard、sienna、catppuccin、nous、geist-contrast/Geist Contrast）
• 通过设置->外观（即时实时预览）或/theme命令切换
• 重新加载后保持（服务器端存储在settings.json中+本地存储实现无闪烁加载）
• 皮肤使用data-skin和CSS变量；深色模式通过.dark类实现，而非data-theme自定义主题维度——详见THEMES.md

https://github.com/jasonjcwu — 编辑器与对话记录优化（16个PR，v0.50.227 → v0.51.55）
通过活动轨道点击实现侧边栏折叠（#2054，整合#1884 + #1924）、编辑器芯片灯箱（#1758）、工具密集型首次交互的标题修复、会话切换期间的静默压缩状态（#2185）、并发发送丢失修复（#2186）、对话记录中的引导消息标记（#2187），以及一系列前端优化修复。

https://github.com/Jordan-SkyLF — 实时流与用户体验优化（12个PR，v0.50.18 → v0.51.58）
最初的工作区回退解析冲刺、实时推理卡片（#366、#367、#394–#397），以及近期的一系列更新：提供商配额卡片上的手动“刷新用量”按钮（#2150）、取消轮次状态分类（#2151）、Firefox侧边栏滚动稳定性（#2200）、早期临时会话标题（#2202）、目标感知的“新增功能？”更新横幅链接（#2207），以及设置中MCP工具溢出修复（#2210）。

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）
可配置的助手显示名称、思考/推理块显示，以及登录页面重构。

Repo

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