GitHub · 项目涌现

呵

EKKOLearnAI/hermes-studio

二〇二六年八月二十六日·★ 7,933·⑂ 973·TypeScript·NOASSERTION ·最新发布 v0.6.15 · 2026-06-15 · GitHub 原仓库
摘要

Hermes Studio 是面向 Hermes Agent 的桌面应用、本地运行时与 Web 控制台，由 EKKOLearnAI 开发。它支持 agent 对话、模型与配置文件管理、平台渠道（Telegram、Discord、Slack 等 8 个平台）连接、cron 定时任务、看板、文件浏览器、编码 agent 运行、群聊、语音输入/输出、Web 终端及用量分析。以桌面应用（Windows/macOS/Linux）、npm CLI 包（`hermes-web-ui`）及 Docker 镜像形式发布。技术栈为 Vue 3 + TypeScript + Vite + Koa 2。

核心能力

领域 Hermes Studio 的功能
Agent 对话 运行 Hermes Agent 对话，支持流式响应、工具调用追踪、文件上传/下载及持久化本地会话。
本地控制面板 在一个仪表盘中管理配置文件、provider、模型、凭证、记忆、技能、插件、日志及运行时设置。
自动化 围绕同一 Hermes 配置文件配置平台渠道、cron 任务、看板任务、群聊房间及 MCP 服务器。
工作区工具 提供文件浏览器、Web 终端、语音输入/输出、编码 agent 运行器、设备发现及性能视图。
分发方式 以桌面应用（Windows/macOS/Linux）、npm CLI 包及 Docker 镜像形式发布。

功能特性

AI 对话

平台渠道

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

平台 功能特性
Telegram Bot token、提及控制、反应、自由回复对话
Discord Bot token、提及、自动线程、反应、频道允许/忽略列表
Slack Bot token、提及控制、机器人消息处理
WhatsApp 启用/禁用、提及控制、提及模式
Matrix Access token、homeserver、自动线程、DM 提及线程
飞书 App ID / Secret、提及控制
微信 二维码登录（浏览器扫码，自动保存凭证）
企业微信 Bot ID / Secret

用量分析

定时任务

看板

模型管理

多配置文件

文件浏览器

群聊

编码 Agent

技能与记忆

日志

管理与运行时管理

认证

CLI 维护命令：

# 删除持久化的登录 IP 锁定记录
hermes-web-ui clear-login-locks

# 删除登录锁定并重启正在运行的 Web UI 进程
hermes-web-ui clear-login-locks --restart

# 创建或重置默认超级管理员登录为 admin / 123456
hermes-web-ui reset-default-login

clear-login-locks 会删除 ${HERMES_WEB_UI_HOME:-~/.hermes-web-ui}/.login-lock.json。如果服务器正在运行，重启以清除内存中的锁定状态。reset-default-login 会更新 Web UI 账户数据库；如果 admin 用户已存在，其密码将重置为 123456，并将该账户启用为超级管理员。

设置

语音 / TTS / STT

Web 终端

桌面应用与更新

快速开始

桌面应用（推荐）

从 GitHub Releases 下载最新的 Hermes Studio 桌面安装程序。

桌面构建版本发布适用于 macOS、Windows 和 Linux，并在适用情况下提供单独的架构资源。桌面应用捆绑了 Web UI 运行时，并将 Hermes Agent 数据存储在原生 Hermes 位置：

桌面包装器将其自身的 Web UI 状态单独存储在 ~/.hermes-web-ui 中，除非设置了 HERMES_WEB_UI_HOME。

桌面自动更新首先从 https://download.ekkolearnai.com/latest 读取最新源。如果该端点不可用，更新程序将回退到 https://github.com/EKKOLearnAI/hermes-studio/releases/latest/download。

npm

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

打开 http://localhost:8648

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

有关详细说明和故障排除，请参阅 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、其本地 Hermes 运行时集成以及开发/预览辅助功能。Provider API 密钥和 Hermes Agent 设置通常通过 Hermes 配置文件管理；此处的环境变量是进程级别的覆盖。

变量 默认值 描述
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 也作为兼容别名受支持。
HERMES_WEBUI_STATE_DIR 未设置 HERMES_WEB_UI_HOME 的兼容别名。
HERMES_WEB_UI_DISABLE_MCP_AUTOINJECT 未设置 禁用启动时将受管理的 hermes-studio MCP 服务器注入到 Hermes 配置文件配置中。
HERMES_WEB_UI_ALLOW_TRANSIENT_MCP_AUTOINJECT 未设置 当 HERMES_WEB_UI_HOME 位于临时目录下（例如版本预览运行时）时，允许受管理的 MCP 注入。
UPLOAD_DIR $HERMES_WEB_UI_HOME/upload 上传根目录覆盖。文件存储在配置文件作用域的子目录下。
CORS_ORIGINS 仅同主机 HTTP、Socket.IO 和 WebSocket 请求的跨域允许列表，以逗号或空格分隔。仅在有意需要旧版通配符 CORS 时设置为 *。
AUTH_TOKEN 自动生成 显式 bearer token。如果未设置，Web UI 会在 HERMES_WEB_UI_HOME 下创建一个。
AUTH_JWT_SECRET AUTH_TOKEN 用于用户名/密码会话的 JWT 签名密钥覆盖。
PROFILE default 启动/默认 Hermes 配置文件。运行时请求使用前端选择且当前账户授权的配置文件。
LOG_LEVEL info 服务器日志级别。
BRIDGE_LOG_LEVEL $LOG_LEVEL 或 info Bridge 日志级别。
MAX_DOWNLOAD_SIZE 200MB 最大文件下载大小。
MAX_EDIT_SIZE 10MB 最大可编辑文件大小。
WORKSPACE_BASE 当前用户的主目录 工作区浏览的基目录。
HERMES_HOME 平台默认 Hermes 数据主目录。Windows 使用 %LOCALAPPDATA%\hermes；macOS/Linux 使用 ~/.hermes。
HERMES_BIN hermes 自定义 Hermes CLI 二进制路径。
HERMES_AGENT_ROOT 自动发现 包含 run_agent.py 的 Hermes Agent 源码检出目录。
HERMES_AGENT_BRIDGE_PYTHON 自动发现 用于启动 agent bridge 的 Python 解释器。
HERMES_AGENT_BRIDGE_UV 自动发现 用于在可用时启动 agent bridge 的 uv 可执行文件。
UV 自动发现 回退的 uv 可执行文件路径。
PYTHON 自动发现 用于 agent bridge 的回退 Python 可执行文件。
HERMES_AGENT_BRIDGE_ENDPOINT 平台默认 Agent bridge broker 端点。Windows 默认为 tcp://127.0.0.1:18765；macOS/Linux 默认为 ipc:///tmp/hermes-agent-bridge.sock。
HERMES_AGENT_BRIDGE_TIMEOUT_MS 120000 Node 请求到 bridge broker 的超时时间。
HERMES_AGENT_BRIDGE_CONNECT_RETRY_MS 5000 连接 bridge 套接字的短重试窗口。
HERMES_AGENT_BRIDGE_STARTUP_TIMEOUT_MS 120000 等待 Python bridge 就绪的超时时间。
HERMES_AGENT_BRIDGE_AUTO_RESTART 启用 在意外退出后自动重启 bridge broker。设置为 0、false、no 或 off 以禁用。
HERMES_AGENT_BRIDGE_RESTART_DELAY_MS 1000 Bridge 自动重启退避的基础延迟。
HERMES_AGENT_BRIDGE_PLATFORM cli 传递给 Hermes Agent 的平台标识。
HERMES_AGENT_BRIDGE_WORKER_TRANSPORT 平台默认 配置文件 worker 传输方式。设置为 tcp 使用环回 TCP，或 ipc/unix 使用 Unix 域套接字；Windows 默认为 TCP，macOS/Linux 默认为 IPC。
HERMES_AGENT_BRIDGE_WORKER_PORT_BASE 18780 TCP worker 端点的基端口。
HERMES_BRIDGE_PROVIDER 配置文件/默认 Bridge 运行的 provider 覆盖。
HERMES_BRIDGE_TOOLSETS 配置文件/默认 Bridge 运行的工具集覆盖。
HERMES_BRIDGE_MAX_TURNS 配置文件/默认 Bridge 运行的最大轮次覆盖。
HERMES_BRIDGE_SUPPRESS_PLATFORM_HINT cli 控制传递给 Hermes Agent 的 bridge 平台提示抑制。
HERMES_OPENROUTER_APP_REFERER https://hermes-studio.ai Bridge 运行发送的 OpenRouter 归属 referer。
HERMES_OPENROUTER_APP_TITLE Hermes Web UI Bridge 运行发送的 OpenRouter 归属标题。
HERMES_OPENROUTER_APP_CATEGORIES cli-agent,personal-agent Bridge 运行发送的 OpenRouter 归属类别。
HERMES_WEB_UI_MANAGED_GATEWAY 启用 控制 Web UI 管理的 Hermes gateway 进程处理。设置为 0、false、no 或 off 以改用 hermes gateway start。
HERMES_WEB_UI_DISABLE_GATEWAY_AUTOSTART 未设置 跳过启动 gateway 检查/自动启动。对于由其他服务管理 Hermes gateway 生命周期的仅仪表盘部署，设置为 1、true、yes 或 on。
HERMES_WEB_UI_DISABLE_SKILL_INJECTION 未设置 跳过启动时捆绑技能的注入。当捆绑技能在 Hermes Web UI 外部管理时，设置为 1、true、yes 或 on。当注入启用时，Web UI 仅更新其先前安装的技能或相同的现有捆绑副本；本地编辑和用户拥有的同名技能将被跳过。
HERMES_WEB_UI_STOP_GATEWAYS_ON_SHUTDOWN 生产环境启用 控制 Web UI 关闭时是否也停止受管理的 gateway 进程。设置为 0 或 false 以分离它们。
HERMES_GATEWAY_URL / GATEWAY_URL 未设置 用于代理路由的显式 Hermes gateway 上游 URL。
GATEWAY_HOST 127.0.0.1 用于代理路由的默认 Hermes gateway 上游主机。
GATEWAY_PORT 8642 用于代理路由的默认 Hermes gateway 上游端口。
HERMES_WEB_UI_PREVIEW_REPO 包仓库 版本预览使用的 GitHub 仓库。
HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_TRANSPORT 平台默认 版本预览 broker 传输方式。设置为 tcp 以在 macOS/Linux 上为预览使用环回 TCP；未设置时，预览遵循 HERMES_AGENT_BRIDGE_WORKER_TRANSPORT=tcp。
HERMES_WEB_UI_PREVIEW_AGENT_BRIDGE_ENDPOINT 隔离的预览端点 直接覆盖版本预览 broker 端点。
HERMES_WEB_UI_BACKEND_PORT 8648 Vite 开发代理使用的后端端口。
HERMES_WEB_UI_FRONTEND_PORT 8649 前端 Vite 开发服务器端口。

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 并重启。缓存清理尽力而为；如果失败，更新程序将继续安装。

自动配置

启动时，BFF 服务器会自动：

开发

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

npm run build   # 输出到 dist/

项目开发指南请参阅 DEVELOPMENT.md。

架构

浏览器 → BFF (Koa, :8648) → Socket.IO /chat-run
                ↓
        Hermes agent bridge → Hermes Agent 运行时
                ↓
           Hermes CLI / 配置文件
           配置文件 config.yaml    (渠道/provider 行为)
           配置文件 auth.json      (凭证池)
           Tencent iLink API      (微信二维码登录)

前端设计具有多 agent 可扩展性——所有 Hermes 特定代码都命名空间在 hermes/ 目录下（API、组件、视图、存储），使得添加新的 agent 集成变得简单。

BFF 层处理 Socket.IO 聊天流、Hermes agent bridge、配置文件感知的文件上传和基于路径的下载（多后端：本地/Docker/SSH/Singularity）、会话 CRUD、账户和配置文件作用域的管理、配置/凭证管理、微信二维码登录、模型发现、技能/记忆/插件管理、TTS/STT、编码 agent 代理、MCP/运行时管理、日志读取和静态文件服务。

技术栈

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

后端： Koa 2 (BFF 服务器) + node-pty (Web 终端)

星标历史

Star History Chart

许可证

BSL-1.1

同时见于 gh-search:llm、gh-search:ai-agent、gh-search:agent
译自 GitHub · 项目涌现 · 录于 二〇二六年八月二十六日