ghcr.io/nesquena/hermes-webui:0.52.298

Hermes Web UI

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

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

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

设置 Hermes 后，您可在所有设备上原生访问：

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

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

---

目录

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

如果您运行外部端点，有两种选项：

1. 将其模型用作聊天提供方（当前支持）：在 设置 → 提供方 中将其添加为自定义 OpenAI 兼容提供方，设置 base_url = http://127.0.0.1:8642/v1 并提供您的 Bearer 令牌。
2. 通过 Hermes Gateway API 服务器路由聊天（当前通过 HERMES_WEBUI_CHAT_BACKEND=gateway 支持）：参见 docs/advanced-chat-setup.md。完整的代理循环委托功能尚未发布；相关进度跟踪见 https://github.com/nesquena/hermes-webui/issues/1925。

认证与安全

• 可选密码认证——默认关闭，本地主机使用零摩擦
• 通过 HERMES_WEBUI_PASSWORD 环境变量或设置面板启用
• 已安装的PWA与WebUI自身密码配合使用效果最佳。支持反向代理，但代理基本认证可能会阻止已安装应用所需的service-worker更新请求，导致更新后显示空白屏幕；恢复步骤请参见 docs/troubleshooting.md
• 可选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实例时，也适用于负载均衡器后方。多实例部署需要会话亲和性，否则回调可能会到达不同进程并导致状态验证失败
• 带24小时TTL的已签名HMAC HTTP-only cookie
• /login 路径下的简约深色主题登录页面
• 所有响应均包含安全头（X-Content-Type-Options、X-Frame-Options、Referrer-Policy）
• 20MB POST请求体大小限制
• CDN资源通过SRI完整性哈希固定

Docker

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

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

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

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

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

以拥有Hermes主目录的用户身份运行Compose。sudo docker compose up -d可能会使${HOME}扩展为root用户的主目录，导致Docker挂载错误的.hermes目录而非实际的~/.hermes，WebUI启动时会显示config.yaml (not found, using defaults)。建议将用户添加到Docker组并运行docker compose up -d；如果必须使用sudo，请先设置绝对路径，例如HERMES_HOME=/home/you/.hermes HERMES_WORKSPACE=/home/you/workspace sudo -E docker compose up -d，然后使用docker compose config验证。

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

要启用密码保护（如果将端口暴露在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

多容器设置

如果希望代理和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。

[!IMPORTANT] 源码边界说明（#2453）：多容器设置默认将hermes-agent-src以只读方式挂载到WebUI。这可防止WebUI端的源码重写，但仍是实现耦合的桥梁，而非稳定的代理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

Start here

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

Using & customizing

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

贡献与设计

• CONTRIBUTING.md — 贡献规范、PR预期及本地验证方法
• ARCHITECTURE.md — 系统设计、所有API端点及实现说明
• TESTING.md — 手动浏览器测试计划和自动化覆盖率参考
• DESIGN.md — 设计标记和calm-console设计方向
• docs/UIUX-GUIDE.md — 源自设计文档和视觉资源的UI/UX原则
• docs/sse-streams.md — 跨客户端SSE端点参考：会话流、网关SSE探测范围、心跳及代理行为
• docs/CONTRACTS.md — 面向贡献者和代理的项目契约/RFC/设计索引
• docs/rfcs/README.md — 大型架构和持久性提案的RFC索引

发布历史与计划

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

---

贡献者

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

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

主要贡献者（按PR数量排序，含纳入批量发布的工作）

完整的326位贡献者排名列表（包括3个以上PR的表格、1-2个PR的名单，以及设计和架构贡献的特别致谢说明）详见CONTRIBUTORS.md。

重要贡献

https://github.com/franksong2702 — 最活跃的外部贡献者（180个PR，v0.49.3 → v0.51.384）
拥有所有外部贡献者中最长的贡献周期：会话标题保护（#301）、面包屑工作区导航（#302）、嵌入式工作区终端（#1099）、基于工作树的会话创建（#2053）、入门文档（#2052）、编辑器底部容器查询、流式会话侧边栏豁免（#1327）、会话边车修复、定时任务输出保留（#1295）、配置文件默认工作区持久化、手动/compress异步启动/状态端点（#2128）、工作树状态显示（#2109）+ 受保护删除（#2156）（用于生命周期总览#2057）、会话渲染后去重（#2166）、原生WebUI快速路径（#2171）、尾部窗口响应修剪（#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）。