hermes-web-ui/README_zh.md

Hermes Web UI English

Hermes Agent 的全功能 Web 管理面板。
管理 AI 聊天会话、监控用量与成本、配置平台渠道、
管理定时任务、浏览技能 —— 全部在一个简洁响应式的 Web 界面中完成。

npm install -g hermes-web-ui && hermes-web-ui start

移动端

---

功能特性

AI 聊天

• 聊天前端通过 Socket.IO /chat-run 实时流式更新；聊天运行通过 Hermes agent bridge 执行
• 多会话管理 — 创建、重命名、删除、切换会话
• 自建会话数据库 — Web UI 会话使用本地 SQLite；Hermes state.db 仅作为只读来源用于 Hermes 历史 API
• 按来源分组会话（Telegram、Discord、Slack 等），可折叠手风琴面板
• 活跃会话实时指示器 — 正在进行的会话置顶并显示旋转图标
• 按最新消息时间排序会话列表
• Markdown 渲染，支持语法高亮和代码复制
• 工具调用详情展开（参数 / 结果）
• 文件上传支持
• 文件下载支持 — 支持下载用户上传的文件和 Agent 生成的文件，兼容 local、Docker、SSH、Singularity 等多种 terminal backend
• 会话搜索 — Ctrl+K 搜索 Web UI 本地会话库；不包含只读 Hermes 历史会话
• 全局模型选择器 — 自动从 ~/.hermes/auth.json 凭证池发现可用模型
• 每个会话显示模型标签和上下文 Token 用量

平台渠道

在一个页面统一配置 8 个平台：

平台	功能
Telegram	Bot Token、提及控制、表情回应、自由回复聊天
Discord	Bot Token、提及、自动线程、表情回应、频道白名单/黑名单
Slack	Bot Token、提及控制、Bot 消息处理
WhatsApp	启用/禁用、提及控制、提及模式
Matrix	Access Token、Homeserver、自动线程、私信提及线程
飞书	App ID / Secret、提及控制
微信	扫码登录（浏览器扫码，自动保存凭证）
企业微信	Bot ID / Secret

• 凭证管理写入 ~/.hermes/.env
• 渠道行为设置写入 ~/.hermes/config.yaml
• 每个平台已配置/未配置状态检测

用量分析

• Token 总用量明细（输入 / 输出）
• 会话数及日均统计
• 预估费用追踪及缓存命中率
• 模型使用分布图
• 30 天每日趋势（柱状图 + 数据表格）

定时任务

• 创建、编辑、暂停、恢复、删除 Cron 任务
• 立即触发执行
• Cron 表达式快捷预设

模型管理

• 从凭证池自动发现模型（~/.hermes/auth.json）
• 从每个 Provider 端点获取可用模型（/v1/models）
• 添加、更新、删除 Provider（预设 & 自定义 OpenAI 兼容）
• OpenAI Codex 和 Nous Portal OAuth 登录
• Provider URL 自动检测，支持非 v1 API 版本（如 /v4）
• Provider 级别模型分组，支持切换默认模型

多配置文件

• 创建、重命名、删除、切换 Hermes 配置文件（Profile）
• 克隆现有配置文件或从归档导入（.tar.gz）
• 导出配置文件用于备份或分享
• 配置文件级别的配置和缓存隔离

文件浏览器

• 浏览远程后端文件（local、Docker、SSH、Singularity）
• 上传、下载、重命名、复制、移动和删除文件
• 创建目录
• 查看文件内容，支持语法高亮

群聊

• 多 Agent 聊天房间，通过 Socket.IO 实时通信
• @提及路由 — 提及 Agent 触发上下文回复
• 上下文压缩 — 历史消息超过 Token 阈值时自动摘要压缩
• 输入状态和回复进度指示器
• 房间创建、删除和邀请码管理
• Agent 管理 — 添加/移除房间中的 Agent，支持独立 Profile
• SQLite 消息持久化
• 移动端响应式布局，可折叠侧边栏

技能与记忆

• 浏览和搜索已安装的技能
• 查看技能详情和附件
• 用户笔记和档案管理

日志

• 查看 Agent / Server / Error 日志
• 按日志级别、日志文件和关键词过滤
• 结构化日志解析，HTTP 访问日志高亮

认证

• 基于 Token 的认证（首次运行自动生成或通过 AUTH_TOKEN 环境变量设置）
• 可选的用户名/密码登录 — 通过初始 Token 认证后在设置页面设置
• 可通过 AUTH_DISABLED=1 禁用认证

设置

• 显示（流式输出、紧凑模式、推理过程、费用显示）
• Agent（最大轮次、超时时间、工具强制执行）
• 记忆（启用/禁用、字符限制）
• 会话重置（空闲超时、定时重置）
• 隐私（PII 脱敏）
• 模型设置（默认模型 & Provider）
• Profile 和 Provider 配置

Web 终端

• 集成终端，基于 node-pty 和 @xterm/xterm
• 多会话支持 — 创建、切换、关闭终端会话
• 通过 WebSocket 实时传输键盘输入和 PTY 输出
• 支持窗口大小调整

---

快速开始

npm 安装（推荐）

npm install -g hermes-web-ui
hermes-web-ui start

打开 http://localhost:8648

一键安装（自动检测系统）

自动安装 Node.js（如未安装）和 hermes-web-ui，支持 Debian/Ubuntu/macOS：

bash <(curl -fsSL https://cdn.jsdelivr.net/gh/EKKOLearnAI/hermes-web-ui@main/scripts/setup.sh)

WSL

bash <(curl -fsSL https://cdn.jsdelivr.net/gh/EKKOLearnAI/hermes-web-ui@main/scripts/setup.sh)
hermes-web-ui start

WSL 使用与其他本地安装相同的 Web UI 后台启动流程；Web UI 不再单独启动 gateway 服务。

Docker Compose

单容器部署，内置 Hermes Agent 运行时：

# 使用预构建镜像（推荐）
WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d

# 或从源码构建
docker compose up -d --build

docker compose logs -f hermes-webui

打开 http://localhost:6060

• Hermes 持久化数据目录：./hermes_data
• Web UI 认证 Token 存储在 ./hermes_data/hermes-web-ui/.token
• 首次启动并开启认证时，Token 会打印到容器日志中
• 运行参数全部由 docker-compose.yml 环境变量驱动

更详细的说明与排错见：docs/docker.md

Hermes Agent 运行时发现

Web UI 启动后端聊天能力时，会优先使用包含 run_agent.py 的源码目录，例如 ~/.hermes/hermes-agent。如果找不到源码目录，会退回到已安装 hermes 命令所使用 的 Python 环境，再退到系统 Python。因此源码安装和 pip install hermes-agent 这类 包安装方式都可以兼容。

Web UI 环境变量

这些变量只用于配置 Hermes Web UI 自身。Provider API Key 和 Hermes Agent 相关设置仍通过 Hermes profile 管理。

变量	默认值	说明
PORT	8648	Web UI 监听端口。
BIND_HOST	0.0.0.0	Web UI 绑定地址。如需 IPv6，可显式设置为 ::。
HERMES_WEB_UI_HOME	~/.hermes-web-ui	Web UI 数据目录，用于认证 token、登录凭据、日志、数据库和默认上传目录。兼容支持 HERMES_WEBUI_STATE_DIR 作为别名。
UPLOAD_DIR	$HERMES_WEB_UI_HOME/upload	覆盖上传目录。
CORS_ORIGINS	*	Koa CORS origin 配置。
AUTH_DISABLED	未设置	设置为 1 或 true 可关闭 Web UI 认证。
AUTH_TOKEN	自动生成	显式指定 bearer token。未设置时，Web UI 会在 HERMES_WEB_UI_HOME 下自动生成。
PROFILE	default	初始 Hermes profile 名称。
LOG_LEVEL	info	Server 日志级别。
BRIDGE_LOG_LEVEL	$LOG_LEVEL 或 info	Bridge 日志级别。
MAX_DOWNLOAD_SIZE	200MB	最大文件下载大小。
MAX_EDIT_SIZE	10MB	最大可编辑文件大小。
WORKSPACE_BASE	/opt/data/workspace	Workspace 浏览根目录。

CLI 命令

命令	说明
hermes-web-ui start	后台启动（守护进程模式）
hermes-web-ui start --port 9000	自定义端口启动
hermes-web-ui stop	停止后台进程
hermes-web-ui restart	重启后台进程
hermes-web-ui status	查看运行状态
hermes-web-ui update	更新到最新版本并重启
hermes-web-ui upgrade	update 的别名
hermes-web-ui -v	显示版本号
hermes-web-ui -h	显示帮助信息

update / upgrade 会先尝试执行 npm cache clean --force，再执行 npm install -g hermes-web-ui@latest 并重启。缓存清理是 best-effort；如果清理失败，只提示 warning，升级安装会继续执行。

自动配置

启动时 BFF 服务器会自动：

• 初始化 Web UI 数据目录、本地数据库和内置技能
• 启动 /chat-run 使用的 Hermes agent bridge
• 启动成功后自动打开浏览器

---

开发

git clone https://github.com/EKKOLearnAI/hermes-web-ui.git
cd hermes-web-ui
npm install
npm run dev

• 前端：http://localhost:5173
• BFF 服务器：http://localhost:8648

npm run build   # 构建输出到 dist/

项目开发规范见：DEVELOPMENT.md。

架构

浏览器 → BFF (Koa, :8648) → Socket.IO /chat-run
                ↓
        Hermes agent bridge → Hermes Agent runtime
                ↓
           Hermes CLI / profiles
           ~/.hermes/config.yaml  (渠道行为配置)
           ~/.hermes/auth.json    (凭证池)
           腾讯 iLink API         (微信扫码登录)

前端采用 多 Agent 可扩展架构 — 所有 Hermes 相关代码都按命名空间组织在 hermes/ 目录下（API、组件、视图、Store），可以方便地并行接入新的 Agent。

BFF 层负责：Socket.IO 聊天流式推送、Hermes agent bridge、文件上传与下载（多 Backend 支持：local/Docker/SSH/Singularity）、会话 CRUD、配置/凭证管理、微信扫码登录、模型发现、技能/记忆管理、日志读取和静态文件服务。

技术栈

前端： Vue 3 + TypeScript + Vite + Naive UI + Pinia + Vue Router + vue-i18n + SCSS + markdown-it + highlight.js

后端： Koa 2（BFF 服务器）+ node-pty（Web 终端）

Star 历史

许可证

BSL-1.1