在浏览器里调教 AI 助手:Hermes WebUI 全解-夜雨聆风

在浏览器里调教 AI 助手:Hermes WebUI 全解

用了一年 Claude Code，我最后还是回到了终端。但说实话，有些场景下，能在浏览器里调出 AI 助手，比在终端里切来切去舒服得多。

最近在 GitHub 上发现了一个项目，叫 Hermes WebUI，来解决这个问题。它让 Hermes Agent（一个自托管的 AI 助手）有了一个完整的浏览器界面，而且不需要任何构建工具。

什么是 Hermes WebUI

Hermes Agent 是一个跑在你服务器上的自主 AI 助手，通过终端或消息应用访问。它最核心的特点是跨会话记忆——知道你是谁、你的项目用什么规范、你的工作流习惯。随着运行时间变长，它会越来越懂你的环境。

Hermes WebUI 就是这个助手的浏览器界面。官方说它是”最优雅的 Hermes 使用方式”，我体验下来觉得这个说法不算夸张。

核心特点：

三栏布局：左侧会话导航、中央对话、右侧工作区文件浏览
与 CLI 完全对等的功能——终端能做的，浏览器里都能做
无需构建步骤、无需前端框架、无需打包器，用的是 Python + 原生 JS
深色主题，开箱即用

和 Claude Code 比起来怎么样

这是最核心的问题。我直接说结论：

能力	Claude Code	Hermes
跨会话记忆（自动）	部分支持	完全支持
定时任务（自托管）	不支持	支持
消息应用接入	Telegram/Discord 预览	10+ 平台
自托管 Web UI	无	有
自我改进的技能系统	无	有
Python/ML 生态	无	原生支持
开源	否	是（MIT）

Hermes 的记忆系统是它最强的部分。它会自动保存用户画像、助手笔记和技能（skills），不需要你每次重新解释项目背景。Claude Code 也有 CLAUDE.md/MEMORY.md 的项目上下文，但那是项目级别的，不是跨项目的全局记忆。

安装有多简单

git clone https://github.com/nesquena/hermes-webui.gitcd hermes-webui./start.sh

启动脚本会自动完成：

检测 Hermes Agent 是否存在，不存在则自动安装
查找或创建包含 WebUI 依赖的 Python 环境
启动 Web 服务器并等待健康检查
自动打开浏览器进入首次引导向导

Docker 用户更简单：

git clone https://github.com/nesquena/hermes-webuicd hermes-webuicp .env.docker.example .envdocker compose up -d# 打开 http://localhost:8787

远程访问：SSH 隧道和 Tailscale

服务器绑定在 127.0.0.1（本地回环），默认只允许本地访问。如果在 VPS 上运行，有两种方式：

SSH 隧道（推荐，适合临时访问）：

ssh -N -L 8787:127.0.0.1:8787 user@your.server.com# 然后本地浏览器打开 http://localhost:8787

start.sh 会自动检测 SSH 连接并打印这个命令。

Tailscale（适合长期手机访问）：

在服务器和手机上都安装 Tailscale
启动时设置密码并监听所有接口：

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

手机浏览器打开 http://<服务器Tailscale IP>:8787

Tailscale 是基于 WireGuard 的零配置 VPN，不需要端口转发、不需要公网暴露、不需要 SSH 隧道。Hermes WebUI 本身是响应式布局，针对手机做了优化（汉堡菜单、触摸友好的控件），可以直接加到手机桌面当 App 用。

安全措施

默认关闭密码认证（本地使用零摩擦）
开启后使用 HMAC 签名 + 24 小时 TTL 的 HTTP-only Cookie
所有响应头包含安全策略（X-Content-Type-Options、X-Frame-Options、Referrer-Policy）
20MB POST body 大小限制
CDN 资源使用 SRI 完整性哈希

功能亮点

会话管理

创建、重命名、复制、删除、搜索
Pin/Sticky 会话置顶
按日期分组（今天/昨天/更早）
支持导出为 Markdown 完整 JSON

工作区文件浏览

目录树展开/折叠
文本、代码、Markdown（渲染后）、图片直接预览
创建、编辑、删除、重命名文件和文件夹
Git 状态检测（分支名、dirty 文件数）

语音输入

浏览器原生 Web Speech API
点击录音，再次点击或发送停止
自动在 2 秒静音后停止
实时转录显示在文本框

7 套内置主题

Dark（默认）、Light、Slate、Solarized Dark、Monokai、Nord、OLED。切换即时生效，不闪屏。

技术架构

系统架构图

Mermaid 图片占位符 1

请手工上传本地图片后替换这里。本地文件：D:\chenjingyang\my_skill\wechat_md_publisher\images\mermaid-1778081081614-1.png

请求处理流程

Mermaid 图片占位符 2

请手工上传本地图片后替换这里。本地文件：D:\chenjingyang\my_skill\wechat_md_publisher\images\mermaid-1778081081617-2.png

关键模块说明

后端 (Python)

文件	行数	职责
`server.py`	~154	HTTP 路由外壳 + 认证中间件
`api/routes.py`	~2250	所有 GET/POST 路由处理，是后端核心
`api/streaming.py`	~660	SSE 流式引擎、Agent 执行、取消支持
`api/config.py`	~1110	自动发现、模型检测、配置热重载
`api/auth.py`	~201	密码认证、HMAC 签名 Cookie
`api/models.py`	~377	会话模型 CRUD、CLI 会话桥接
`api/workspace.py`	~288	文件操作、Git 状态检测

前端 (Vanilla JS)

文件	行数	职责
`ui.js`	~1740	DOM 辅助、Markdown 渲染、工具卡片、Token 指示器
`panels.js`	~1438	定时任务、技能、记忆、设置面板
`sessions.js`	~800	会话 CRUD、折叠分组、搜索
`messages.js`	~655	发送、SSE 处理器、流式渲染
`boot.js`	~524	移动端导航、语音输入
`commands.js`	~267	斜杠命令自动补全
`workspace.js`	~286	文件预览、文件操作、Git 徽章

数据流向

用户输入 → messages.js → /api/chat → routes.py                                         ↓                                   streaming.py                                         ↓                              Hermes Agent (本地/远程)                                         ↓                              SSE text/event-stream                                         ↓                              messages.js (流式渲染)                                         ↓                                   DOM (实时更新)

状态数据与代码仓库分离：

~/.hermes/webui-mvp/

— WebUI 会话、设置、工作区状态
~/.hermes/

— Hermes Agent 原生状态（记忆、技能、定时任务）

总结

Hermes WebUI 解决的是一个很具体的问题：当你想在浏览器里用 AI 助手，又不想失去终端的完整能力。它做到了几乎 1:1 的 CLI 功能映射，同时给了一个现代化的界面。

对于已经在用 Hermes Agent 的人，这是体验升级。对于没用过 Hermes 的人，WebUI 是很好的入门入口——一行命令就能跑起来，不需要理解底层就能用。

项目地址：https://github.com/nesquena/hermes-webui

相关链接

Hermes Agent 主项目：https://github.com/NousResearch/hermes-agent
官方文档：https://github.com/nesquena/hermes-webui/blob/main/README.md
Docker 部署详解：docs/docker.md
故障排查：docs/troubleshooting.md