Hermes Desktop 完整指南:安装、构建与使用

Hermes Desktop 完整指南：安装、构建与使用

如果你用 Hermes Agent 有一阵子了，大概率经历过这个场景：终端里跑着 hermes，切出去干别的，回来忘了聊到哪了。或者想给不碰命令行的同事安利，对方看到黑窗口直接劝退。

Hermes Desktop 就是解决这个问题的。它给 Hermes Agent 套了一个原生桌面窗口，但底层跑的是同一个 Agent。配置、API Key、会话记录、技能、记忆，和 CLI 完全共享。你在终端里配好的东西，桌面端打开就能用。

当前最新版本：v0.15.2（2026-05-29），基于 Electron + React + TypeScript，支持 macOS / Windows / Linux。

一句话定位

Hermes Desktop 不是独立产品，也不是 CLI 的"简化版"。它就是一个带图形界面的 Hermes Agent 运行时——安装到 ~/.hermes，和 CLI 共用同一套数据和配置。

安装方案一：一键安装（推荐）

如果你还没装 Hermes CLI，用这条命令一步到位，Agent 运行时 + 桌面端一起装好：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --include-desktop

脚本会自动处理 Python 3.11+、Git、ripgrep 等依赖，然后构建桌面端。首次运行会引导你选择模型和配置 API Key。

⚡ 没有预编译安装包

官方 GitHub Releases 目前只发布 Python wheel 和源码包（`hermes_agent-0.15.2-py3-none-any.whl`），**没有预编译的 .dmg / .exe / .AppImage**。`--include-desktop` 是从源码本地构建，不是下载二进制包。

安装方案二：已有 CLI，从源码构建

如果你已经装了 hermes CLI，直接：

hermes desktop

这条命令会自动完成：安装 Node 依赖 → TypeScript 编译 → Vite 打包 → electron-builder 输出 → 启动应用。

首次构建需要 5-15 分钟（取决于网络），后续构建走内容指纹缓存，几秒就完成。

常用构建参数

参数	作用
`hermes desktop`	完整构建 + 启动
`hermes desktop --build-only`	只构建不启动（CI / 验证用）
`hermes desktop --skip-build`	跳过构建，直接启动已有产物
`hermes desktop --force-build`	忽略缓存，强制全量重建
`hermes desktop --source`	开发模式，Vite 热重载 + Electron 调试
`hermes desktop --cwd <path>`	指定初始工作目录

安装方案三：让 Hermes 自己帮你构建

这是最省事的方式——你不需要记任何命令。已经装了 Hermes CLI 的话，直接在对话里告诉它：

"帮我构建 Hermes Desktop"

Hermes 会自动完成：配置 npm 镜像 → 安装 Node 依赖 → 编译 TypeScript → 打包 Electron → 启动应用。整个过程你只需要确认一两次，剩下的它自己跑。

如果你在国内，可以加一句"用国内镜像"，它会自动配好 npmmirror 和 Electron 二进制镜像，不用手动折腾环境变量。

这也是我自己用的方式——第一次构建花了十来分钟，之后就快了。

国内构建加速（镜像配置）

从国内网络构建时，npm 和 Electron 二进制下载会非常慢甚至超时。需要配置镜像。

第一步：配置 npm 镜像

cat > ~/.npmrc <<'EOF'registry=https://registry.npmmirror.comstrict-ssl=falseEOF

第二步：设置 Electron 二进制镜像（环境变量）

⚠️ 不要写进 .npmrc

npm 11+ 会忽略 `.npmrc` 里的 `electron_mirror` 并报警告。正确的做法是在构建命令前设置环境变量：

ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ \  hermes desktop --build-only

第三步：验证依赖完整性

npm install 返回 up to date in 993ms 不代表真的装好了——没有 package-lock.json 的情况下 npm 无法校验。务必检查：

# node_modules 应该 > 1 GBdu -sh ~/.hermes/hermes-agent/node_modules# Electron 二进制必须存在ls ~/.hermes/hermes-agent/node_modules/electron/dist# node-pty 原生模块必须编译好（否则终端功能崩溃）ls ~/.hermes/hermes-agent/node_modules/node-pty/prebuilds/darwin-arm64/pty.node

如果 node_modules 不到 200 MB，删掉重装：

rm -rf ~/.hermes/hermes-agent/node_modulescd ~/.hermes/hermes-agentELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ \  npm install

构建流程（6 步）

hermes desktop 实际执行了以下步骤：

步骤	脚本	做什么
1	`assert-root-install.cjs`	检查根目录 `node_modules` 存在
2	`write-build-stamp.cjs`	写入内容指纹（Git SHA + 版本号）
3	`stage-native-deps.cjs`	复制原生模块到输出目录
4	`tsc -b`	TypeScript 编译
5	`vite build`	React 渲染进程打包
6	`electron-builder --dir`	输出未打包的 .app 到 `release/`

构建产物在 apps/desktop/release/mac-arm64/Hermes.app（Apple Silicon），约 300 MB。

验证构建成功

file ~/.hermes/hermes-agent/apps/desktop/release/mac-arm64/Hermes.app/Contents/MacOS/Hermes# 应输出: Mach-O 64-bit executable arm64du -sh ~/.hermes/hermes-agent/apps/desktop/release/mac-arm64/Hermes.app# 应输出: ~300 MB

macOS 特殊行为：自安装

在 macOS 上首次启动构建好的 Hermes.app 时，应用会自动把自己安装到 /Applications/Hermes.app，然后删除 release/ 下的构建产物。这不是 bug，是设计如此——开发构建会自我提升为正式安装。

所以 ls release/mac-arm64/ 在启动后为空是正常的。要保留构建副本的话，启动前先 cp -R 一份。

功能概览

桌面端围绕"聊天优先"设计，左侧边栏导航：

•对话：核心界面，完整的 Agent 交互

•文件浏览器：不离开应用就能浏览工作目录

•语音：支持语音输入和 TTS 输出（macOS 首次需授权麦克风）

•设置面板：管理 Provider、模型、工具集、MCP 服务器，不用手改 YAML

•Gateway 管理：配置消息平台（Telegram、Discord 等）

•会话管理：浏览和切换历史会话

•自动更新：后台检查更新，一键升级

常见问题

Q: 构建成功但启动闪退？

检查 node-pty 是否编译成功（见上文验证步骤）。如果缺失，从仓库根目录执行：

cd ~/.hermes/hermes-agent && npm rebuild node-pty

Q: hermes desktop 报 "unpacked app not found"？

说明从未成功构建过。先 hermes desktop --build-only 完成构建，不要用 --skip-build。

Q: 桌面端和 CLI 的配置会冲突吗？

不会。它们读写同一个 ~/.hermes/config.yaml 和 ~/.hermes/.env，完全互通。

Q: 能切换界面语言吗？

目前不支持。桌面端 UI 文本全部硬编码为英文，i18n 还在社区需求阶段，可以关注 Hermes Agent 项目主页^[1] 的更新动态。

总结

Hermes Desktop 把终端里的 Agent 搬进了原生窗口，配置互通、会话共享。安装路径三条：一键脚本（--include-desktop）适合新用户，hermes desktop 适合习惯命令行的用户，直接让 Hermes 对话式构建最省事。国内构建记得配镜像，装完验证一下 node_modules 大小和 electron/dist 是否存在。

构建一次之后，日常使用就是双击图标的事。

参考链接

[1] Hermes Agent 项目主页: https://github.com/NousResearch/hermes-agent