Hermes Studio 安装教程：从下载安装到验证
Hermes Studio 安装教程：从下载安装到验证
Hermes Studio 是面向 Hermes Agent 的桌面应用、本地运行时和 Web 控制台。它不是单独安装 hermes-agent 命令行工具的教程，而是安装 Hermes Studio / Hermes Web UI，用来在图形界面里管理聊天、模型、Profile、平台渠道、Cron 任务、文件、日志和 Coding Agent。
项目地址：https://github.com/EKKOLearnAI/hermes-studio
适合谁安装
如果你希望用浏览器或桌面界面来管理 Hermes，而不是只在终端里使用 hermes，就应该安装 Hermes Studio。
它主要提供这些能力：
- 图形化聊天界面
- 模型和 Provider 管理
- Hermes Profile 管理
- 平台渠道接入配置
- 定时任务、Kanban、群聊管理
- 文件浏览器、Web 终端、日志查看
- Coding Agent 启动和监控
安装方式一：桌面应用（推荐）
最推荐普通用户直接下载桌面版。
打开 GitHub Releases：
https://github.com/EKKOLearnAI/hermes-studio/releases/latest根据自己的系统下载对应安装包：
- Windows：下载 Windows 安装包
- macOS：下载 macOS 安装包
- Linux：下载 Linux 安装包
安装完成后直接打开 Hermes Studio 即可。
桌面版会内置 Web UI 运行时，并且会使用原生 Hermes 数据目录：
- Windows：
%LOCALAPPDATA%\hermes，找不到时回退到%APPDATA%\hermes - macOS / Linux：
~/.hermes
Web UI 自身状态默认保存在：
~/.hermes-web-ui安装方式二：npm 安装 Hermes Web UI
如果你是在服务器上部署，或者想用浏览器访问 Web 控制台，可以使用 npm 安装。
先确认服务器已经有 Node.js，然后执行：
npm install -g hermes-web-uihermes-web-ui start启动后打开：
http://localhost:8648如果你在服务器上运行，需要把 localhost 换成服务器 IP 或者你配置好的域名。
常用维护命令：
hermes-web-ui statushermes-web-ui restarthermes-web-ui stophermes-web-ui update如果要指定端口启动：
hermes-web-ui start --port 9000然后访问：
http://localhost:9000安装方式三：Docker Compose 部署
如果你更喜欢容器化部署，可以使用 Docker Compose。
官方 README 里的推荐命令是：
WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d如果你想从源码构建，也可以进入项目目录后执行：
docker compose up -d --build查看日志：
docker compose logs -f hermes-webuiDocker Compose 默认访问地址：
http://localhost:6060默认数据目录：
./hermes_data首次启动并开启认证时，认证 Token 会打印在容器日志里；Web UI 的 token 默认保存在：
./hermes_data/hermes-web-ui/.token开发者源码运行
如果你是开发者，想从源码启动 Hermes Studio，可以使用下面流程：
git clone https://github.com/EKKOLearnAI/hermes-studio.gitcd hermes-studionpm installnpm run dev开发环境默认端口：
- 前端：
http://localhost:8649 - BFF 后端：
http://localhost:8647
构建生产版本：
npm run build首次登录和认证
Hermes Studio 支持 Token 认证，也支持用户名和密码登录。
默认登录信息通常是：
用户名：admin密码：123456首次登录后建议马上修改默认密码。
如果忘记默认账号密码，可以在服务器上执行：
hermes-web-ui reset-default-login如果登录 IP 被锁，可以执行：
hermes-web-ui clear-login-locks如果需要清理登录锁并重启服务：
hermes-web-ui clear-login-locks --restart验证是否安装成功
安装完成后，可以按下面几步检查。
1. 检查服务状态
npm 安装方式可以执行：
hermes-web-ui statusDocker Compose 部署可以执行：
docker compose psdocker compose logs -f hermes-webui2. 打开 Web 页面
根据安装方式访问对应地址：
npm 默认：http://localhost:8648Docker 默认：http://localhost:6060开发环境前端：http://localhost:8649能看到登录页或控制台页面，就说明 Web UI 已经正常启动。
3. 检查 Hermes Agent 运行时
Hermes Studio 是图形界面和控制台，但底层聊天能力仍然依赖 Hermes Agent 运行时。
Web UI 会优先寻找包含 run_agent.py 的 Hermes Agent 源码目录，例如：
~/.hermes/hermes-agent如果找不到源码目录，会退回到系统里已安装的 hermes 命令环境。
所以如果聊天无法运行，可以检查：
hermes doctorhermes --help4. 新建一条测试会话
进入 Hermes Studio 后，新建一条聊天会话，发送一句：
你好，测试一下是否可以正常回复如果能正常流式回复，说明 Web UI、Agent Bridge 和模型配置基本都正常。
常见问题
1. hermes-web-ui 命令不存在
说明 npm 全局安装没有成功，或者 npm 全局 bin 目录没有加入 PATH。
可以重新安装：
npm install -g hermes-web-ui然后重新打开终端再试。
2. 页面打不开
先检查服务是否启动：
hermes-web-ui status再检查端口是否被占用或被防火墙拦截。
npm 默认端口是 8648，Docker 默认端口是 6060。
3. 能打开页面，但聊天不能用
通常是 Hermes Agent 运行时或模型配置问题。可以在服务器上执行：
hermes doctorhermes model先确认 Hermes Agent 本身可用，再回到 Hermes Studio 里测试聊天。
4. 想升级到最新版
npm 安装方式可以执行：
hermes-web-ui update或者：
hermes-web-ui upgradeDocker 部署则重新拉取镜像并启动即可。
总结
安装 Hermes Studio 有三条主线：
- 普通桌面用户：下载 GitHub Releases 桌面版
- 服务器 Web 控制台：
npm install -g hermes-web-ui && hermes-web-ui start - Docker 部署：
WEBUI_IMAGE=ekkoye8888/hermes-web-ui docker compose up -d
注意，这篇教程安装的是 Hermes Studio / Hermes Web UI，不是只安装 Hermes Agent CLI。Hermes Agent 是底层运行时，Hermes Studio 是用来管理和使用它的图形化工作台。
文章分享
如果这篇文章对你有帮助，欢迎分享给更多人！