ghcr.io/nesquena/hermes-webui:0.51.857

Hermes Web UI

https://hermes-agent.nousresearch.com/ 是一款运行在服务器上的高级自主代理，可通过终端或消息应用访问，它能记住所学知识，运行时间越长能力越强。

Hermes WebUI 是 https://hermes-agent.nousresearch.com/ 的轻量级深色主题浏览器 Web 应用界面。与 CLI 体验完全一致——所有可在终端执行的操作，都能通过此 UI 完成。无需构建步骤、无需框架、无需打包工具，仅需 Python 和原生 JS。

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

支持完整配置文件的浅色模式

自定义设置，配置密码

带有内联预览的工作区文件浏览器

会话项目、标签和工具调用卡片

这使你通过 Hermes 环境的 SSH 隧道安全访问时，能获得与 Hermes CLI 几乎1:1 的功能对等的便捷 Web UI。单命令即可启动，单命令即可通过 SSH 隧道在本地计算机上访问。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）。

停止服务器。每种启动方式都有自己的停止路径，因为只有 ctl.sh start 会写入 PID 文件（~/.hermes/webui.pid）：

启动方式	停止方法
python3 bootstrap.py	在终端中按 Ctrl-C（前台运行）
./ctl.sh start	./ctl.sh stop（发送 SIGTERM，等待后发送 SIGKILL）
分离的 bootstrap.py（无 --foreground）或 ./start.sh	通过 lsof -i :8787（或 ss -tlnp）查找 PID 并 kill

./ctl.sh stop 无法停止直接通过 bootstrap.py 或 start.sh 启动的服务器——它仅管理自己启动的进程。

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

两个可选的自托管部署功能——将动态会话回忆预填充附加到浏览器对话（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。

• 内存占用：社区测试显示，原生环境约 330 MB，而 WSL2+Docker 环境约 1080 MB（具体数值因配置而异）。
• 支持功能：聊天、工作区浏览器、会话管理、所有主题。
• 已知限制：工作区浏览器中可能显示部分 POSIX 风格文件路径；依赖 bash 的代理工具可能无法在原生环境中正常工作。
• 原生 Windows 安装：安装 Python 3.11+，然后在 PowerShell 中进入 hermes-agent 根目录：python -m venv venv → pip install -r requirements.txt → pwsh .\start.ps1（脚本会自动发现 venv\Scripts\python.exe）。
• WSL2 兼容性：WSL2 并非必需条件——WSL2 构建的虚拟环境（venv/bin/python，ELF 格式）无法被原生 Windows Python 调用，因此请使用上述原生安装方法。如果需要完整的 bootstrap.py + Linux 运行时，WSL2 仍可作为并行安装选项使用。

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

身份验证与安全

• 可选密码身份验证——默认关闭，本地主机零摩擦使用
• 通过 HERMES_WEBUI_PASSWORD 环境变量或设置面板启用
• 可选 passkeys/WebAuthn——使用密码登录后，从设置 -> 系统进行注册；至少存在一个 passkey 后，登录页面才会显示 passkey 登录选项
• 注册至少一个 passkey 后，可在设置 -> 系统中移除密码并保持仅 passkey 登录。在选择无密码登录前，密码身份验证始终作为引导/恢复途径；passkeys 为同源且本地存储在 WebUI 状态目录中
• WebUI 会话的可选原生 OIDC 登录——在 config.yaml 中配置 webui_oidc.issuer、client_id、allow_claim 和 allow_values，或设置对应的 HERMES_WEBUI_OIDC_* 环境变量。只有这四个参数均存在时 OIDC 才会启用，若配置不完整，启动时会打印警告。
• 原生 OIDC 将 PKCE/state nonce 流程存储在进程内存中。这适用于默认的单进程服务器，且在负载均衡器后，当回调请求粘性指向同一 WebUI 实例时也可正常工作。多实例部署需要会话亲和性，否则回调可能会到达不同进程并导致状态验证失败。
• 带签名 HMAC 的 HTTP-only cookie，TTL 为 24 小时
• \login 路径下的极简深色主题登录页面
• 所有响应均包含安全头（X-Content-Type-Options、X-Frame-Options、Referrer-Policy）
• 20MB POST 请求体大小限制
• CDN 资源通过 SRI 完整性哈希固定

手动 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 + 仪表盘 + 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。

常见故障模式

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

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

文档

入门指南

• docs/why-hermes.md — 为何选择Hermes、其核心设计理念，以及与Claude Code / Codex / OpenCode / Cursor的详细对比
• docs/onboarding.md — 首次运行向导、提供商设置、本地模型服务器基础URL，以及安全重运行说明
• docs/troubleshooting.md — 常见故障的诊断流程（例如"AIAgent not available"）

使用与自定义

• THEMES.md — 主题+皮肤系统及自定义主题指南
• docs/workspace-git.md — 工作区Git控制功能
• docs/EXTENSIONS.md — 管理员控制的WebUI扩展注入

部署与运维

• docs/remote-access.md — SSH隧道、Tailscale和手机访问（包括社区ARM64-Android实地报告）
• docs/advanced-chat-setup.md — 自托管部署的可选动态召回预填充和基于网关的浏览器聊天功能
• docs/docker.md — Docker Compose配置、常见故障及绑定挂载迁移
• docs/supervisor.md — launchd、systemd、supervisord、runit和s6进程管理器配置
• docs/wsl-autostart.md — Windows登录时自动启动WSL2
• docs/onboarding-agent-checklist.md — 助手引导安装/重新安装的安全规则和通过/失败检查

贡献与设计

• CONTRIBUTING.md — 贡献风格、PR要求和本地验证
• ARCHITECTURE.md — 系统设计、所有API端点、实现说明
• TESTING.md — 手动浏览器测试计划和自动化覆盖率参考
• DESIGN.md — 设计标记和"冷静控制台"设计方向
• docs/UIUX-GUIDE.md — 源自设计文档和视觉资源的UI/UX原则
• docs/CONTRACTS.md — 供贡献者和代理使用的项目协议/RFC/设计索引
• docs/rfcs/README.md — 针对大型架构和持久性提案的RFC索引

发布历史与计划

• CHANGELOG.md — 每个版本的发布说明
• ROADMAP.md — 功能路线图和迭代历史
• SPRINTS.md — 包含CLI + Claude功能对等目标的未来迭代计划
• CONTRIBUTORS.md — 完整的社区贡献者名单

---

贡献者

Hermes WebUI的构建离不开开源社区的帮助。每一个PR——无论是直接合并、整合到批量发布中，还是从大型提案中提取的部分——都在塑造这个项目，我们感谢所有花时间做出贡献的人。

已有304位贡献者提交的代码被纳入发布版本。完整且持续更新的贡献者名单——包括所有提交过1-2个PR的贡献者，以及在设计和架构工作方面的特别感谢名单——详见CONTRIBUTORS.md。以下是部分主要贡献者的快照：

主要贡献者（按PR数量排序，包括整合/批量发布的工作）

详见CONTRIBUTORS.md获取所有304位贡献者的完整排名列表——包括3个及以上PR的表格、1-2个PR的名单，以及对设计和架构贡献的特别感谢说明。

重要贡献

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

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

https://github.com/rodboev — Windows/跨平台正确性+测试可靠性（83个PR，v0.51.223 → v0.51.384）
一系列广泛且持续的改进，重点是确保项目在Linux之外的系统上正常运行：ctl.sh的Windows进程树终止修复（#3670）、Windows本地全套件信号/孤儿进程处理、斜杠命令自动完成优化，以及数十个发布批次中交付的大量前端和基础设施修复。

https://github.com/bergeouss — 提供程序管理UI+Docker强化（70个PR，v0.48.0 → v0.51.385）
用于从设置中添加/编辑自定义提供程序的提供程序管理UI、OAuth提供程序状态检测（#1552）、双容器Docker设置、配置文件隔离强化（每个配置文件的.env密钥）、用户在设置→提供程序中看到的大部分内容、“在Finder中显示”上下文菜单（#1551）、网关状态卡片（#1552）、活动项目筛选器自动分配会话（#1550）、更新横幅中的“新增功能？”链接（#1549）、OpenRouter免费层实时获取（#1548）、凭据池401自我修复（#1553）、模型选择器中的内联提供程序芯片+组模型计数（#1644）。

https://github.com/ai-ag2026 — 会话恢复+审计基础设施（75个PR，v0.50.279 → v0.51.367）
自主AI贡献者（由Hermes Agent驱动），专注于耐用性：基于state.db的边车协调（#2041）、启动时恢复孤立的.json.bak文件（#2035）、只读会话恢复审计端点（#2036、#2040）、/health中的活动运行生命周期（#2039）、docs/rfcs/turn-journal.md中的崩溃安全轮次日志RFC（#2042）、仅追加轮次日志助手（#2059）、生命周期事件层（#2062）、Content-Security-Policy-Report-Only头（#2084）、每个定时任务的提示框切换（#2100）、分叉会话压缩谱系隔离（#2014）。

https://github.com/dso2ng — 会话谱系+诊断（30个PR，v0.50.227 → v0.51.327）
用于有限会话图诊断的/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），以及近期的一系列改进：提供程序配额卡片上的手动“刷新用量”按钮（#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()对话框替换（从#242中提取的PR #251）。

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类别）、网关状态alive-null分类（#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），以及编辑器和会话侧边栏的大量优化。