ghcr.io/nesquena/hermes-webui:latest

Hermes Web UI

https://hermes-agent.nousresearch.com/ 是一款运行在服务器上的高级自主智能体，可通过终端或消息应用访问，能记住所学知识并随着运行时间增长而变得更强大。

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

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

设置 Hermes，以便你可以在所有设备上原生访问它：

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

这使你通过便捷的 Web UI 获得与 Hermes CLI 几乎1:1 的对等体验，可通过 Hermes 环境中的 SSH 隧道安全访问。启动只需一条命令，通过 SSH 隧道在电脑上访问也只需一条命令。Web UI 的所有部分均使用你现有的 Hermes 智能体和现有模型，无需额外设置。

---

目录

• 为什么选择 Hermes — 是什么以及如何比较
• 快速开始 — 克隆 + bootstrap.py / start.sh / ctl.sh
• 功能特性 — 聊天、会话、工作区、语音、配置文件、安全、主题、面板、移动设备
• 配置与访问 — 自动发现、覆盖配置、远程/Tailscale/手机访问、手动启动
• Nix flake/模块 — 声明式安装和服务
• 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）。

[!NOTE] 停止服务器。每种启动方式都有自己的停止路径，因为只有 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 启动的服务器——它仅管理自己启动的进程。

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

1. 将其模型用作聊天提供商（目前支持）：在 设置 → 提供商 中添加，作为自定义 OpenAI 兼容提供商，配置 base_url = http://127.0.0.1:8642/v1 以及您的 bearer token。
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 实例时也可正常工作。多实例部署需要会话亲和性，否则回调可能会到达不同进程并导致状态验证失败。
• 带签名 HMAC 的 HTTP-only cookie，TTL 为 24 小时
• \login 路径下的简约深色主题登录页面
• 所有响应均包含安全头（X-Content-Type-Options、X-Frame-Options、Referrer-Policy）
• 20MB POST 请求体大小限制
• CDN 资源使用 SRI 完整性哈希固定

远程访问（SSH隧道、Tailscale、手机）

服务器默认绑定到 127.0.0.1。要从其他机器访问，可使用SSH隧道（ssh -N -L 8787:127.0.0.1:8787 user@host，start.sh 会通过SSH为你打印此命令），或将服务器和手机加入 Tailscale 网络，并在设置 HERMES_WEBUI_HOST=0.0.0.0 和 HERMES_WEBUI_PASSWORD 后浏览 http:// :8787。完整步骤（包括社区ARM64-Android现场报告）：docs/remote-access.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] 使用代理venv Python（或任何已安装Hermes代理依赖的Python环境）。系统Python会缺少 openai、httpx 和其他必需包。

健康检查：

curl http://127.0.0.1:8787/health

---

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（例如macOS的UID从501开始），请编辑.env
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 获取完整迁移方法。

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

源码边界说明（#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/why-hermes.md — 为何选择 Hermes、其核心设计理念，以及与 Claude Code / Codex / OpenCode / Cursor 的详细对比
• docs/onboarding.md — 首次运行向导、服务提供商设置、本地模型服务器 Base 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 — 自托管部署的可选动态回忆预填充功能及 Gateway 支持的浏览器聊天
• 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——无论是直接合并、纳入批量发布，还是从大型提案中提取——都对项目产生了影响，我们感谢所有花时间贡献的人。

已有超过 326 位贡献者 提交的代码被纳入发布标签。完整且持续更新的贡献者名单——包括所有提交过一两个 PR 的人以及在设计和架构工作方面的特别致谢名单——可在 CONTRIBUTORS.md 中查看。以下是部分最活跃贡献者的快照：

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

查看 CONTRIBUTORS.md 获取所有 326 位贡献者的完整排名列表——包括提交 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）、工作树状态显示（#2109）+ 受保护删除（#2156）（用于生命周期总览 #2057）、会话渲染后去重（#2166）、原生 WebUI 快速路径（#2170）、尾部窗口响应修剪（#2171）、过期流保护扩展（#2158）、CSP 报告收集器（#2160），以及在移动/响应式设计、会话侧边栏和工作区状态机方面的大量优化。

https://github.com/Michaelyklam — 近期版本最活跃贡献者（118 个 PR，v0.50.240 → v0.51.198）
贡献包括：生产环境 Docker 强化（#1921，移除具有 sudo 权限的 staging 用户）、配置文件作用域技能端点（#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 — 编辑器 + transcript 优化（16 个 PR，v0.50.227 → v0.51.132）
贡献包括：通过活动轨道点击折叠侧边栏（#2054，整合 #1884 + #1924）、编辑器芯片灯箱（#1758）、工具密集型首轮标题修复、会话切换期间的静默压缩状态（#2185）、并发发送丢失修复（#2186）、transcript 内引导消息徽章（#2187），以及一系列前端优化修复。