ghcr.io/nesquena/hermes-webui:latest

Hermes Web UI

Hermes Agent 是一款运行在服务器上的高级自治代理，可通过终端或消息应用访问，能记住所学知识并随运行时间增长而变得更强大。

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

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

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

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

---

目录

• 为什么选择 Hermes — 功能介绍及对比分析
• 快速开始 — 克隆仓库 + bootstrap.py / start.sh / ctl.sh
• 功能特性 — 聊天、会话、工作区、语音、配置文件、安全、主题、面板、移动设备支持
• 配置与访问 — 自动发现、覆盖配置、远程/Tailscale/手机访问、手动启动
• Docker — 单容器和多容器部署
• 运行测试
• 架构 — 后端/前端布局、状态目录
• 文档 — 完整文档索引
• 贡献者

---

为什么选择 Hermes

大多数 AI 工具每次会话都会重置。它们不知道您是谁、您在做什么工作，也不了解您的项目遵循的约定。您每次都需要重新解释。

Hermes 跨会话保留上下文，可在您离线时运行计划任务，并且运行时间越长，对您的环境就越了解。它使用您现有的 Hermes 代理设置和现有模型，无需额外配置即可启动。

与其他代理工具的区别：

• 持久化记忆 — 用户配置文件、代理笔记以及保存可重用流程的技能系统；Hermes 会学习您的环境，无需重复学习
• 自托管调度 — cron 任务可在您离线时运行，并将结果发送到 、、Slack、Signal、电子邮件等
• 10+ 消息平台 — 终端中的同一代理可通过手机访问
• 自我改进技能 — Hermes 从经验中自动编写并保存自己的技能；无需浏览市场，无需安装插件
• 供应商无关 — 支持 OpenAI、Anthropic、Google、DeepSeek、OpenRouter 等
• 编排其他代理 — 可生成 Claude Code 或 Codex 处理繁重编码任务，并将结果整合到自己的记忆中
• 自托管 — 您的对话、您的记忆、您的硬件

与同类工具对比（领域正在快速变化 — 完整对比见 docs/why-hermes.md）：

† Claude Code 具有 CLAUDE.md/MEMORY.md 项目上下文和滚动自动记忆，但不支持完整的跨会话自动召回
‡ Claude Code 具有云托管调度（Anthropic 基础设施）和会话范围的 /loop 命令；无自托管 cron

最接近的竞争对手是 OpenClaw — 两者都是始终在线、自托管、开源的代理，具备记忆、cron 和消息功能。关键区别：Hermes 将自动编写和保存技能作为核心行为（OpenClaw 的技能系统以社区市场为中心）；Hermes 在更新中更稳定（OpenClaw 存在文档化的版本回归问题，ClawHub 曾发生涉及***技能的安全事件）；Hermes 原生运行在 Python 生态系统中。完整对比见 docs/why-hermes.md。

---

快速开始

运行仓库引导程序：

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py

或者继续使用 shell 启动器：

./start.sh

对于自托管 VM 或家庭实验室安装，ctl.sh 封装了常见的守护进程生命周期命令，无需依赖 fuser 或 pkill：

./ctl.sh start # 后台守护进程，PID 位于 ~/.hermes/webui.pid
./ctl.sh status # PID、运行时间、绑定的主机/端口、日志路径、/health 状态
./ctl.sh logs --lines 100 # 查看 ~/.hermes/webui.log 最后 100 行
./ctl.sh restart
./ctl.sh stop

ctl.sh start 在守护进程包装器后台以前台/无浏览器模式运行引导程序，将日志写入 ~/.hermes/webui.log，并支持 .env 文件及内联覆盖（例如 HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start）。

高级：动态召回预填充与网关支持的聊天

两个可选的自托管部署功能——为浏览器对话附加动态会话召回预填充（Joplin/Obsidian/Notion/llm-wiki 路由），以及通过运行中的Hermes Gateway 路由浏览器聊天——详见 docs/advanced-chat-setup.md。大多数用户不需要这两个功能。

引导程序将：

1. 检测 Hermes Agent，如果缺失，尝试官方安装程序（curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash）。
2. 查找或创建包含 WebUI 依赖项的 Python 环境。
3. 启动 Web 服务器并等待 /health 端点。
4. 打开浏览器，除非您传递 --no-browser 参数。
5. 引导您进入 WebUI 内的首次运行设置向导。

[!NOTE] 此引导程序暂不支持原生 Windows。请使用 Linux、macOS 或 WSL2。有关 Windows/WSL 登录时自动启动的说明，参见 docs/wsl-autostart.md。

如果安装后提供商设置仍未完成，引导向导会指引你使用 hermes model 完成设置，而非尝试在浏览器中复现完整的 CLI 设置。有关向导的分步指南、提供商选择、本地模型服务器 Base URL 以及安全重新运行的信息，请参阅 docs/onboarding.md。如果 AI 助手协助进行安装、重新安装、引导、提供商设置或首次运行支持，请在运行命令或检查日志前让其阅读 docs/onboarding-agent-checklist.md。

功能

聊天与智能体

• 通过 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 节流令牌流，长响应时渲染更流畅
• 输入框底部的上下文使用指示器——令牌计数、成本和填充条（模型感知）

会话

• 创建、重命名、复制、删除、按标题和消息内容搜索
• 每个会话通过 ⋯ 下拉菜单执行会话操作——固定、移动到项目、归档、复制、删除
• 固定/标星会话至侧边栏顶部（金色指示器）
• 归档会话（隐藏但不删除，可切换显示）
• 会话项目——带颜色的命名组，用于组织会话
• 会话标签——在标题中添加 #标签 以显示彩色标签并支持点击筛选
• 侧边栏按今天/昨天/更早分组（可折叠日期组）
• 下载为 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）

配置文件

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

身份验证与安全

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

斜杠命令

• 在输入框中输入 / 以显示自动补全下拉菜单
• 内置命令：/help、/clear、/compress [focus topic]、/compact（别名）、/model 、/workspace 、/new、/usage、/theme
• 使用方向键导航，Tab/Enter 选择，Escape 关闭
• 未识别的命令将直接传递给代理

兼容性

WebUI运行时状态中显示的版本仅为WebUI版本（当前运行的构建/镜像/标签）。它并非完整的兼容性映射。

在#1925和#2491中稳定代理边界的工作完成之前，WebUI在运行时执行、提供者/模型访问以及状态/模式使用方面仍与Hermes Agent内部耦合。实际上，WebUI直接导入Agent模块（api/config.py、api/providers.py、api/streaming.py）并直接读取Agent状态布局，因此版本不匹配可能导致导入错误或行为偏差。

兼容性策略

• WebUI发布分支会针对WebUI发布时可用的匹配Hermes Agent版本进行测试。
• 同时升级两者：同时升级或固定WebUI和hermes-agent（相同发布序列/版本/日期），尤其是在启用生产流量之前。
• 在#1925/#2491中的稳定API边界工作完成之前，运行固定的旧版本/新版本组合未经测试且不受支持。
• 当怀疑存在升级不匹配时，在问题报告中记录完整的hermes-agent + hermes-webui版本。

Docker用户：固定两个镜像标签（或相应的固定源代码修订版），而不是一侧使用latest而另一侧使用固定标签。升级多容器设置时，请遵循docs/docker.md中的代理镜像升级步骤（需要在重新创建前删除hermes-agent-src卷）。当前源代码边界状态在docs/rfcs/agent-source-boundary.md中跟踪。

https://github.com/franksong2702 — 最活跃的外部贡献者（148个PR，v0.49.3 → v0.51.153）
作为任期最长的外部贡献者，其贡献包括：会话标题保护（#301）、面包屑工作区导航（#302）、嵌入式工作区终端（#1099）、基于工作树的会话创建（#2053）、入职文档（#2052）、编辑器页脚容器查询、流式会话侧边栏豁免（#1327）、会话侧车修复、cron输出保留（#1295）、配置文件默认工作区持久化、手动/compress异步启动/状态端点（#2128）、工作树状态显示（#2109）+ 生命周期总览#2057的受保护删除（#2156）、会话渲染后去重（#2166）、原生WebUI快速路径（#2170）、尾部窗口响应修剪（#2171）、stale-stream保护扩展（#2158）、CSP报告收集器（#2160），以及在移动/响应式设计、会话侧边栏和工作区状态机方面的大量优化。

https://github.com/Michaelyklam — 近期版本最活跃的贡献者（117个PR，v0.50.240 → v0.51.139）
生产环境Docker强化（#1921，移除具有sudo权限的临时用户）、配置文件作用域技能端点（#1903）、配置文件作用域HERMES_HOME下的网关PID解析（#1901）、配置文件感知AIAgent缓存（#1898/#1904）、反斜杠LaTeX分隔符（#1848）、Codex配额错误显示（#1770）、shell路由HTML 503（#1836）、陈旧Kanban客户端恢复（#1828）、上下文自动压缩提示框生命周期（#1988）、/goal命令（#1866）、Kanban详情视图滚动（#1916）、CLI会话工具元数据保留（#1778）、繁体中文Kanban本地化补充（#1979）、v0.51.51移动版Insights分桶/布局（#2120/#2121）、Hermes运行适配器RFC（#2105，用于#1925）、从此处分支的绝对索引（#2198，用于#2184）、opencode-go自定义提供程序重叠路由（#2204，用于#1894）。

https://github.com/dso2ng — 会话谱系 + 诊断功能（25个PR，v0.50.227 → v0.51.153）
提供/api/session/lineage-report/端点用于有限会话图诊断（#2012）、过时Mermaid渲染错误清理（#1337）、session_source="fork"的续链隔离（#2063）、侧边栏徽章展开时延迟加载谱系报告（#2130），以及一系列围绕会话加载的前端可靠性修复。

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

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

https://github.com/aronprins — v0.50.0 UI全面改版（PR #242，外加9个后续PR）
项目最大的单项贡献：完整UI重新设计，将模型/配置文件/工作区控制项移至编辑器页脚，用Hermes控制中心（标签式模态框）替代齿轮图标设置面板，移除活动栏并改用内联编辑器状态，通过⋯操作下拉菜单重新设计会话列表，以及添加工作区面板状态机。此外还包括对话记录重新设计（#587）、侧边栏精简（#584）、三列布局重构（#899）、明暗主题 + 强调色皮肤（#627），以及共享confirm()/prompt()对话框替换（PR #251从#242中拆分）。

https://github.com/iRonin — 安全强化专项开发（PR #196–#204）
六个连续的聚焦安全PR：会话内存泄漏修复（过期令牌清理）、CSP + Permissions-Policy头、30秒慢客户端连接超时、通过环境变量实现可选HTTPS/TLS支持、自更新的上游分支跟踪修复，以及文件浏览器API中的CLI会话支持。这类专注、高质量的安全工作增强了自托管工具的可信度。

https://github.com/lucasrc — 认证强化三部曲（PR #2191、#2192、#2193）
三个协同安全PR均在v0.51.57中发布：带PBKDF2密钥分离的线程安全登录速率限制器、设置保存时的密码哈希缓存失效，以及完整的64字符HMAC-SHA256会话签名（含向后兼容迁移桥）。这类清晰解耦的安全工作可作为三个独立部分进行审核。

https://github.com/LumenYoung — 实时流关键路径正确性（8个PR，v0.51.47 → v0.51.99）
最初的过期流写回保护（#2136——后续两个版本扩展的bug类型）、网关状态存活空值分类（#2075）、压缩横幅锚点对齐（#2182），以及压缩完成时的上下文进度环自动刷新（#2188）。每个PR都针对代码库中最脆弱的子系统之一进行了小而精准的修复。

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

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

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

https://github.com/deboste — 反向代理认证 + 移动端响应式布局（PR #3、#4、#5）
最早的三个社区PR：修复EventSource/fetch以在反向代理设置中使用URL源、修正配置中的模型Provider路由，以及添加带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）
用SSE长连接替代1.5秒HTTP轮询实现审批和澄清功能，将延迟从最多1.5秒降至近实时。解决了所有正确性细节（原子订阅 + 快照、锁内通知、队列头 payload、尾随事件重发）。

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

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