Hermes-webui：面向 Hermes Agent 的自托管 Web 控制台

前言：

随着 Claude Code、Codex CLI、OpenCode、Cursor 等 AI Coding 工具的发展，AI Agent 正在从"命令行助手"逐渐走向"长期运行的个人智能体"。但命令行工具虽然强大，却存在一些使用门槛：移动端访问不方便、会话管理不直观、文件预览不友好、任务状态难以可视化。

nesquena/hermes-webui 正是围绕这一痛点构建的项目。它是 Hermes Agent 的轻量级 Web 界面，可以把原本主要通过终端或消息应用使用的 Hermes Agent，搬到浏览器中使用。用户可以在网页中完成聊天、会话管理、文件浏览、任务查看、Skills 管理、Memory 编辑、Profiles 切换等操作。项目官方描述非常直接：

复制代码

Hermes WebUI: The best way to use Hermes Agent from the web or from your phone!

也就是说，它的目标不是重新发明一个 Agent，而是为已有的 Hermes Agent 提供一个接近 CLI 功能完整度的 Web UI。

发布时间(v0.51.208)：2026-06-02

一、项目背景：为什么需要 Hermes WebUI？

Hermes Agent 的核心价值在于：

复制代码

长期记忆
自托管运行
多模型接入
离线任务调度
跨平台消息访问
自动沉淀技能

但如果只通过命令行交互，对于一些用户来说仍然不够友好。例如：

手机上不方便使用终端；
多会话不方便切换；
工作区文件不方便浏览；
历史会话不容易整理；
Cron 任务、Memory、Skills 不够直观；
远程服务器上的 Agent 不方便用图形界面管理。

Hermes WebUI 的出现，就是为了把 Hermes Agent 的能力进行 Web 化、可视化和移动端友好化。

它解决的不是"大模型能力"本身，而是 Agent 操作界面与长期运行体验 的问题。

二、项目框架设计

Hermes WebUI 的设计非常克制：没有复杂前端框架，没有构建步骤，没有 bundler。

官方 README 中明确说明：

复制代码

No build step, no framework, no bundler.
Just Python and vanilla JS.

整体架构可以理解为：

复制代码

Hermes WebUI
├── Python Backend
│   ├── HTTP 路由
│   ├── 身份认证
│   ├── 会话管理
│   ├── SSE 流式输出
│   ├── Workspace 文件操作
│   ├── Profiles 管理
│   ├── Memory / Skills / Cron 面板接口
│   └── Hermes Agent 调用桥接
│
├── Static Frontend
│   ├── index.html
│   ├── style.css
│   ├── ui.js
│   ├── messages.js
│   ├── sessions.js
│   ├── workspace.js
│   ├── panels.js
│   ├── commands.js
│   └── boot.js
│
├── Docker / Compose
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── docker-compose.two-container.yml
│   └── docker-compose.three-container.yml
│
└── Tests / Docs
    ├── tests/
    ├── docs/
    ├── ARCHITECTURE.md
    ├── TESTING.md
    └── THEMES.md

三、后端设计：Python 标准库 HTTP Server

项目后端主要位于 api/ 目录。根据官方架构说明，核心模块包括：

复制代码

api/
├── auth.py          # 密码登录、签名 Cookie、Passkeys/WebAuthn
├── config.py        # 配置发现、模型检测、可重载配置
├── helpers.py       # HTTP 工具函数、安全响应头
├── models.py        # Session 模型、CRUD、CLI SQLite 会话桥接
├── onboarding.py    # 首次运行引导
├── profiles.py      # Profile 状态管理
├── routes.py        # GET / POST 路由处理
├── state_sync.py    # 状态同步
├── streaming.py     # SSE 流式输出、取消、压缩
├── updates.py       # 自更新检查
├── upload.py        # 文件上传
└── workspace.py     # 文件操作、工作区、Git 检测

后端的几个重点设计如下。

1. SSE 流式响应

Hermes WebUI 使用 SSE，也就是 Server-Sent Events，实现模型回复的 token 级流式输出。用户发送消息后，可以看到内容逐步生成，而不是等待完整响应结束后一次性返回。

这类设计对于 AI Chat UI 很重要，因为它直接影响交互体验。

2. 会话持久化

Hermes WebUI 支持创建、重命名、复制、删除、搜索、归档、置顶会话，并且可以按照项目和标签组织会话。

这使它比普通命令行会话更适合长期使用。

3. Workspace 文件操作

WebUI 提供右侧工作区文件浏览器，支持：

复制代码

目录树展开
面包屑导航
文本预览
代码预览
Markdown 渲染
图片预览
文件创建、编辑、删除、重命名
Git 分支与脏文件检测

这使用户可以一边与 Agent 对话，一边查看项目文件。

4. Profile 管理

Hermes WebUI 支持多个 Profiles，用户可以在 UI 中创建、切换和删除 profile。

每个 profile 可以绑定不同模型、配置、记忆、skills 和工作空间。这对多项目、多模型、多用户习惯管理非常实用。

5. 安全机制

项目支持可选密码认证、Passkeys/WebAuthn、签名 HMAC Cookie、安全响应头、POST body 大小限制等机制。

默认情况下本地使用尽量零摩擦；如果暴露到网络，则建议设置 HERMES_WEBUI_PASSWORD。

四、前端设计：Vanilla JS + 三栏布局

Hermes WebUI 前端位于 static/ 目录，采用传统的 HTML、CSS、JavaScript 文件组织方式：

复制代码

static/
├── index.html
├── style.css
├── ui.js
├── workspace.js
├── sessions.js
├── messages.js
├── panels.js
├── commands.js
└── boot.js

1. 三栏式界面

官方 README 描述的核心布局是 three-panel layout：

复制代码

左侧：Sessions / Navigation
中间：Chat
右侧：Workspace File Browser

这种布局非常适合 Agentic Coding 场景：

左侧管理历史会话；
中间与 Agent 对话；
右侧查看项目文件和工作区状态。

模型、Profile、Workspace、上下文使用量等控制项被放在输入框底部，用户在输入时始终可见。

这比把配置隐藏在多层设置菜单中更适合 AI 工作流，因为模型和上下文状态会频繁影响任务效果。

3. Context Ring 上下文指示

项目提供上下文使用量显示，包括 token 数、成本估算和填充条。

这对于长上下文任务非常关键，用户可以及时判断是否需要压缩、清理或切换会话。

4. Slash Commands

Hermes WebUI 支持 / 命令自动补全，例如：

复制代码

/help
/clear
/compress [focus topic]
/compact
/model <name>
/workspace <name>
/new
/usage
/theme

这种设计保留了 CLI 的效率，同时又通过 Web UI 降低了使用门槛。

五、关键功能解析与技术破局

1. CLI 体验 Web 化

Hermes WebUI 的核心不是做一个简单聊天页面，而是尽量接近 Hermes CLI 的完整体验。

官方强调：

复制代码

Full parity with the CLI experience.
Everything you can do from a terminal, you can do from this UI.

这意味着它不是"玩具聊天壳"，而是 Hermes Agent 的图形化工作台。

2. 持久记忆与长期上下文

很多 AI 工具的问题在于每次对话都从零开始，用户需要反复解释：

复制代码

我是谁
我的项目是什么
我用什么技术栈
我之前做过什么
我的偏好是什么
当前任务上下文是什么

Hermes Agent 强调持久记忆，而 Hermes WebUI 则提供 Memory 面板，让用户可以查看和编辑 MEMORY.md 与 USER.md 等记忆文件。

这使得 AI Agent 更接近长期个人助理，而不是一次性问答机器人。

3. 自托管任务调度

Hermes 的一个重要区别是 self-hosted scheduling。

它可以在用户离线时执行 cron jobs，并把结果通过 Telegram、Discord、Slack、Signal、Email 等渠道发送出去。

Hermes WebUI 提供 Tasks 面板，用于查看、创建、编辑、运行、暂停和删除定时任务。

这意味着 Agent 不只是"你问它答"，还可以成为一个长期运行的自动化执行系统。

4. 多模型与多 Provider 支持

Hermes WebUI 支持多 Provider 模型接入，包括：

复制代码

OpenAI
Anthropic
Google
DeepSeek
OpenRouter
Nous Portal
MiniMax
Xiaomi MiMo
Z.AI

同时模型下拉列表会根据已配置的 key 动态填充。

这类设计对开发者很友好，因为用户不必绑定单一模型供应商，可以根据任务类型切换不同模型。

5. Workspace + Agent 的深度结合

普通 Chat UI 只能聊天，而 Hermes WebUI 把聊天与工作区结合起来。

例如：

复制代码

AI 回答中出现 workspace://path/to/file
用户点击后，右侧文件面板直接打开该文件

这使得 Agent 可以围绕真实项目文件工作，而不是只停留在纯文本交流。

6. Skills 面板：让 Agent 能力可视化

Hermes 支持 skills 系统，并且具备自我改进能力：Agent 可以从经验中写入和保存自己的 skills。

Hermes WebUI 提供 Skills 面板，支持：

复制代码

查看 skills
按分类搜索
预览 skill 内容
创建、编辑、删除 skills
查看关联文件

这使得 Agent 的长期能力沉淀变得可见、可管理。

7. 手机和远程访问友好

Hermes WebUI 支持移动端响应式布局：

复制代码

移动端汉堡侧边栏
右侧文件面板 slide-over
触控目标最小 44px
手机上保持完整聊天高度

同时，项目推荐通过 SSH Tunnel 或 Tailscale 安全访问远程服务器上的 WebUI。

典型场景：

复制代码

Hermes Agent 跑在家中服务器或云服务器
用户在手机浏览器中访问 WebUI
通过 Agent 查看任务、发起对话、管理文件和定时任务

8. 极简技术栈带来的可维护性

当前很多 WebUI 项目使用复杂前端栈：

复制代码

React / Vue / Next.js
Vite / Webpack
Node.js
前端构建
服务端框架
数据库 ORM

Hermes WebUI 反其道而行之：

复制代码

Python 标准库 HTTP Server
Vanilla JS
静态 HTML/CSS
无构建步骤
无 bundler

这种设计的优势是：

部署简单；
依赖少；
调试直观；
更适合服务器和 homelab 场景；
不需要维护复杂前端构建链。

对于自托管 AI 工具来说，这一点非常有价值。

六、使用教程

1. 环境要求

推荐环境：

复制代码

Linux
macOS
WSL2
Python 3.11+
Docker 可选
已有或可自动安装 Hermes Agent

项目 README 明确说明，当前 bootstrap 原生 Windows 尚未正式支持，Windows 用户建议使用 WSL2，或者参考社区维护的原生 Windows 安装方案。

2. 快速启动

克隆仓库：

复制代码

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

运行 bootstrap：

复制代码

python3 bootstrap.py

bootstrap 会自动完成以下操作：

复制代码

检测 Hermes Agent
如果缺失则尝试安装 Hermes Agent
查找或创建 Python 环境
安装 WebUI 依赖
启动 Web Server
等待 /health 健康检查
打开浏览器
进入首次运行引导

启动后，默认访问地址通常是：

复制代码

http://127.0.0.1:8787

3. 使用 start.sh 启动

也可以使用 shell launcher：

复制代码

./start.sh

如果希望指定端口：

复制代码

./start.sh 9000

或者通过环境变量指定：

复制代码

HERMES_WEBUI_PORT=9000 ./start.sh

4. 使用 ctl.sh 管理后台服务

对于自托管服务器、homelab 或云主机，推荐使用 ctl.sh 管理生命周期：

复制代码

./ctl.sh start
./ctl.sh status
./ctl.sh logs --lines 100
./ctl.sh restart
./ctl.sh stop

日志默认写入：

复制代码

~/.hermes/webui.log

PID 默认写入：

复制代码

~/.hermes/webui.pid

5. 常用环境变量配置

如果自动发现失败，可以手动指定：

复制代码

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
export HERMES_WEBUI_PYTHON=/path/to/python
export HERMES_WEBUI_PORT=9000
export HERMES_WEBUI_HOST=127.0.0.1
./start.sh

常用变量说明：

变量	作用
`HERMES_WEBUI_AGENT_DIR`	Hermes Agent 路径
`HERMES_WEBUI_PYTHON`	Python 可执行文件
`HERMES_WEBUI_HOST`	绑定地址
`HERMES_WEBUI_PORT`	端口，默认 8787
`HERMES_WEBUI_STATE_DIR`	WebUI 状态目录
`HERMES_WEBUI_DEFAULT_WORKSPACE`	默认工作区
`HERMES_WEBUI_DEFAULT_MODEL`	默认模型
`HERMES_WEBUI_PASSWORD`	启用密码登录
`HERMES_HOME`	Hermes 基础目录
`HERMES_CONFIG_PATH`	Hermes 配置文件路径

6. 远程访问：SSH Tunnel

默认情况下，服务绑定到：

复制代码

127.0.0.1

如果 Hermes WebUI 部署在远程服务器上，可以通过 SSH 隧道访问：

复制代码

ssh -N -L 8787:127.0.0.1:8787 user@server

然后在本机浏览器打开：

复制代码

http://127.0.0.1:8787

这种方式比较安全，因为 WebUI 不需要直接暴露公网端口。

7. 远程访问：Tailscale

如果你希望手机访问服务器上的 Hermes WebUI，可以使用 Tailscale：

复制代码

HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PASSWORD=your-password ./start.sh

然后通过服务器的 Tailscale IP 访问：

复制代码

http://<server-tailscale-ip>:8787

注意：只要绑定到 0.0.0.0 或暴露给局域网/公网，就应该设置强密码。

8. Docker 快速部署

项目提供 Docker Compose 支持。

单容器方式：

复制代码

git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
docker compose up -d

访问：

复制代码

http://localhost:8787

如果要启用密码保护：

复制代码

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

9. 手动 docker run

也可以直接拉取 GHCR 镜像：

复制代码

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

10. 多容器部署

如果希望 Agent 和 WebUI 分离，可以使用：

复制代码

docker compose -f docker-compose.two-container.yml up -d

如果还想加入 Dashboard：

复制代码

docker compose -f docker-compose.three-container.yml up -d

需要注意的是，官方 README 提到 two-container 模式存在一个限制：从 WebUI 触发的 tools 运行在 WebUI 容器内，而不是 agent 容器内。因此如果工具需要 git、node 或其他环境，可能需要使用单容器方案或扩展 WebUI 镜像。

11. 健康检查

服务启动后可以检查：

复制代码

curl http://127.0.0.1:8787/health

如果返回正常结果，说明 WebUI 服务已经可用。

12. 运行测试

项目提供较完整的测试体系：

复制代码

cd hermes-webui
pytest tests/ -v --timeout=60

如果要显式使用 Hermes Agent 的 venv：

复制代码

/path/to/hermes-agent/venv/bin/python -m pytest tests/ -v

官方 README 中提到，测试使用隔离 server 和独立 state directory，不会触碰生产数据和真实 cron 任务。

七、适合哪些用户？

Hermes WebUI 适合以下用户：

已经使用 Hermes Agent 的用户；
希望通过浏览器或手机访问 Agent 的用户；
有 homelab、NAS、VPS、自托管服务器的开发者；
希望长期运行 AI Agent 并管理任务、记忆和 skills 的用户；
想要多模型、多 profile、多工作区管理的 AI 重度用户；
关注 Agentic AI、自托管 AI 工作流、个人 AI 助手的开发者。

如果只是偶尔问 AI 一个问题，Hermes WebUI 可能显得偏重；但如果你希望构建一个长期运行、能积累记忆、能执行任务、能连接工作区的个人 Agent，它的价值就非常明显。

八、项目优势与不足

优势

第一，部署简单。

项目不依赖复杂前端构建链，Python + Vanilla JS 的组合降低了部署和维护成本。

第二，CLI 能力 Web 化程度高。

它不是普通 Chat UI，而是围绕 Hermes Agent 的完整工作流构建。

第三，适合自托管。

默认本地绑定，支持 SSH Tunnel、Tailscale、Docker、Compose、多容器部署，很适合个人服务器和 homelab。

第四，功能覆盖全面。

聊天、会话、文件、任务、Skills、Memory、Profiles、主题、安全认证、移动端适配都有覆盖。

第五，安全意识较强。

支持密码、Passkeys、签名 Cookie、安全响应头、SRI、POST body 限制等设计。

第六，社区活跃。

项目 Star 和 Fork 数较高，Release 频繁，贡献者数量多，说明生态关注度较高。

不足

第一，依赖 Hermes Agent。

它本身不是独立 Agent，需要已有或自动安装 Hermes Agent。

第二，Windows 原生支持仍有限。

官方 bootstrap 当前主要推荐 Linux、macOS 或 WSL2，原生 Windows 方案更多依赖社区维护。

第三，多容器部署存在边界问题。

two-container 模式下，WebUI 触发的 tools 运行位置可能与用户预期不同，需要理解容器边界。

第四，对新手概念较多。

Hermes Agent、Profiles、Skills、Memory、Cron、Workspace、Gateway 等概念较多，初次使用需要适应。

第五，暴露网络时需要谨慎。

如果绑定 0.0.0.0 或通过公网访问，必须启用密码，并最好配合 Tailscale、反向代理认证或 VPN 使用。

九、总结

nesquena/hermes-webui 是一个非常值得关注的 AI Agent Web 控制台项目。

它的核心价值不是重新训练模型，也不是做一个简单聊天页面，而是把 Hermes Agent 的长期记忆、任务调度、多模型接入、Skills、Profiles、Workspace 等能力统一搬到浏览器中。

它代表了一类 AI 工具的发展方向：

复制代码

命令行 Agent
→ Web 化控制台
→ 自托管长期运行
→ 手机远程访问
→ 记忆、任务、文件、模型统一管理

对于希望打造个人 AI 助手、长期自动化 Agent、服务器端 AI 工作流的开发者来说，Hermes WebUI 是一个非常有参考价值的开源项目。

互动话题

你认为未来个人 AI Agent 最重要的能力是什么？

长期记忆和用户画像；
自托管和数据可控；
手机端随时访问；
离线定时任务；
自动沉淀 Skills；
多模型自由切换；
与本地文件和代码仓库深度结合。

欢迎在评论区分享你的观点。

Hermes-webui：面向 Hermes Agent 的自托管 Web 控制台

前言：

一、项目背景：为什么需要 Hermes WebUI？

二、项目框架设计

三、后端设计：Python 标准库 HTTP Server

1. SSE 流式响应

2. 会话持久化

3. Workspace 文件操作

4. Profile 管理

5. 安全机制

四、前端设计：Vanilla JS + 三栏布局

1. 三栏式界面

2. Composer Footer 常驻控制区

3. Context Ring 上下文指示

4. Slash Commands

五、关键功能解析与技术破局

1. CLI 体验 Web 化

2. 持久记忆与长期上下文

3. 自托管任务调度

4. 多模型与多 Provider 支持

5. Workspace + Agent 的深度结合

6. Skills 面板：让 Agent 能力可视化

7. 手机和远程访问友好

8. 极简技术栈带来的可维护性

六、使用教程

1. 环境要求

2. 快速启动

3. 使用 start.sh 启动

4. 使用 ctl.sh 管理后台服务

5. 常用环境变量配置

6. 远程访问：SSH Tunnel

7. 远程访问：Tailscale

8. Docker 快速部署

9. 手动 docker run

10. 多容器部署

11. 健康检查

12. 运行测试

七、适合哪些用户？

八、项目优势与不足

优势

不足

九、总结

互动话题