本文记录了在国内网络环境下安装 Hermes Desktop 的完整流程。因国内网络环境原因，安装Hermes Dsektop桌面版过程中会卡住，也就是安装脚本需要从 GitHub 下载 ~114MB 的 Electron 二进制文件，在国内被墙/限速导致情况下会卡住，导致安装失败。所以教程附解决方案。

---

什么是 Hermes Desktop

Hermes Agent 是 Nous Research 出品的开源 AI Agent 框架，支持终端、消息平台（Telegram/Discord/Slack/飞书/微信等 20+ 平台）和桌面应用。

Hermes Desktop 是Hermes Agent的桌面客户端——和终端里用的 hermes 是同一个 agent，共享配置、API Key、会话、技能和记忆。你在终端开的会话，桌面端能接着聊；桌面端的设置，终端也能看到。

支持 macOS、Windows、Linux 三大平台。

---

安装前的准备

1. 安装 Node.js（≥ 18）

Desktop 是 Electron 应用，需要 Node.js 环境。

# Ubuntu / Debian / deepin
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 或通过 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 22

验证：

node --version   # 应输出 v22.x 或更高
npm --version    # 应输出 10.x 或更高

2. 安装 Hermes CLI

如果你还没装 Hermes，先装 CLI：

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

⚠️ 如果这条命令也卡住（GitHub 被墙），搜索镜像仓库代替，或者可以用代理：

curl -fsSL https://ghproxy.net/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

装完后运行 hermes setup 完成初始化配置（选择模型、填入 API Key 等）。

3. 确认 Python 环境

Hermes 需要 Python 3.10+：

python3 --version

---

正式安装 Hermes Desktop

问题：为什么安装会卡住？

hermes desktop 在构建过程中，需要从 GitHub 下载 Electron 运行时（约 114MB）。这个下载来自 github.com/electron/electron/releases。

国内网络访问 GitHub 的 release 资源经常被限速甚至超时，导致安装长时间卡在 "Build desktop app" 步骤。

Hermes 内部有自动修复机制——下载失败后会尝试切换到 npmmirror.com 镜像重试。但如果 GitHub 连接超时太久才触发失败判断，整个流程就会卡很久，甚至最终报错退出。

解决方案：预设 Electron 镜像

安装前先设置 ELECTRON_MIRROR 环境变量，让 Electron 直接从国内镜像下载，绕过 GitHub：

export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/

建议写入 ~/.bashrc 或 ~/.zshrc 永久生效：

echo 'export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/' >> ~/.bashrc
source ~/.bashrc

执行安装

设置好镜像后，直接运行：

hermes desktop

首次安装会经历以下步骤：

1. 安装 npm 依赖 — 约 1-2 分钟
2. 构建前端 — Vite 打包，约 30 秒
3. 下载 Electron 二进制 — 约 114MB，从镜像下载约 1-3 分钟
4. 打包应用 — electron-builder 打包，约 1 分钟

全部完成后会自动启动桌面应用。

💡 如果之前安装失败过，加 --force-build 强制重新构建：

hermes desktop --force-build

Linux 用户：配置 sandbox 权限

Linux 上 Electron 需要 SUID sandbox helper。构建完成后，hermes desktop 会尝试用 sudo 自动配置，但如果没有终端交互环境（比如通过脚本安装），需要手动执行：

sudo chown root:root ~/.hermes/hermes-agent/apps/desktop/release/linux-unpacked/chrome-sandbox
sudo chmod 4755 ~/.hermes/hermes-agent/apps/desktop/release/linux-unpacked/chrome-sandbox

如果你是从 git 源码安装（不是通过 install.sh），路径换成你的源码目录：

# 例如源码在 ~/hermes-agent
sudo chown root:root ~/hermes-agent/apps/desktop/release/linux-unpacked/chrome-sandbox
sudo chmod 4755 ~/hermes-agent/apps/desktop/release/linux-unpacked/chrome-sandbox

---

验证安装

# 检查构建产物是否存在
ls ~/.hermes/hermes-agent/apps/desktop/release/linux-unpacked/Hermes

如果看到文件存在，说明构建成功。运行 hermes desktop 即可启动。

查看桌面应用日志（排查启动问题）：

hermes logs gui -f

---

常见问题排查

Q1: 安装卡在 "Build desktop app" 步骤

原因：Electron 二进制下载被墙。

解决：确保设置了 ELECTRON_MIRROR，然后强制重建：

export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
hermes desktop --force-build

Q2: 报错 "ENOENT ... rename '.../linux-unpacked/electron' -> '.../linux-unpacked/Hermes'"

原因：之前下载的 Electron zip 文件损坏，解压后缺少二进制文件。

解决：清除缓存后重建：

# 清除 Electron 下载缓存
rm -f ~/.cache/electron/electron-*.zip

# 清除半成品构建
rm -rf ~/.hermes/hermes-agent/apps/desktop/release/*-unpacked

# 重新构建
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
hermes desktop --force-build

Q3: 报错 "Failed to configure Electron's Linux sandbox helper"

原因：Linux sandbox 需要 sudo 权限设置 SUID。

解决：手动执行（见上文「Linux 用户：配置 sandbox 权限」部分）。

Q4: npm install 很慢

原因：npm 默认从 registry.npmjs.org 下载，国内访问慢。

解决：切换 npm 镜像源：

npm config set registry https://registry.npmmirror.com

Q5: 从源码安装的用户，源码在哪？

通过 install.sh 安装的用户，源码在 ~/.hermes/hermes-agent/。

通过 git clone 安装的用户，源码在你 clone 的目录（如 ~/hermes-agent/）。

可以用这个命令确认：

head -1 $(which hermes)
# 输出类似: #!/home/kookboy/hermes-agent/.venv/bin/python
# 路径里的 hermes-agent 就是源码目录

Q6: 构建成功但启动后白屏

尝试：

# 查看日志
hermes logs gui -f

# 重置首次启动状态
rm ~/.hermes/hermes-agent/.hermes-bootstrap-complete

# 重建 venv（如果 Python 环境损坏）
rm -rf ~/.hermes/hermes-agent/venv
hermes desktop --force-build

---

完整安装流程（TL;DR）

# 1. 设置镜像（一次性，写入 shell 配置永久生效）
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
export CSC_IDENTITY_AUTO_DISCOVERY=false

# 2. 安装 Hermes CLI（如果还没装）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes setup

# 3. 构建 Desktop
hermes desktop --force-build

# 4. Linux sandbox 权限（仅 Linux 需要）
sudo chown root:root $(dirname $(head -1 $(which hermes) | sed 's/#!//')/../apps/desktop/release/linux-unpacked/chrome-sandbox)/chrome-sandbox
sudo chmod 4755 $(dirname $(head -1 $(which hermes) | sed 's/#!//')/../apps/desktop/release/linux-unpacked/chrome-sandbox)/chrome-sandbox

# 5. 启动
hermes desktop

---

总结一下：

Hermes Desktop 的安装卡住问题，99% 是国内网络访问 GitHub 下载 Electron 受限导致的。设置 ELECTRON_MIRROR 镜像后，整个安装过程通常 3-5 分钟就能完成。

如果你用的是企业内网或有自建镜像，可以把 ELECTRON_MIRROR 换成你的私有镜像地址。

更多 Hermes 使用文档：https://hermes-agent.nousresearch.com/docs/

---

教程环境：deepin Linux (6.18.19-amd64-desktop-rolling) / Node.js v24 / Hermes Agent v0.17.0