告别网络卡顿!手把手教你用国内镜像极速安装Hermes(亲测有效,含卸载)

最近在指导同事使用 Hermes 时，发现不少人被“安装”这道门槛卡住——
要么 GitHub 连不上，要么 pip、npm 下载慢到怀疑人生。

为了让更多人能顺利跑起来，我们整理了一套完全适配国内网络环境的安装流程整理如下，照着做基本一次通过。适用于网络条件不佳的个人电脑或云服务器安装Hermes。

说明：本文所有操作均以 Linux 系统（Ubuntu）为例。Windows / macOS 用户可参考思路，但命令路径可能略有差异。

一、准备工作：安装基础环境

1️⃣安装Git

这一步比较简单直接去网上搜索Git安装包下载安装，注意勾选 Add Python to PATH。

2️⃣ 安装 Python 3.1（或更高版本）

Windows：前往 python.org 下载安装包，勾选 Add Python to PATH。
macOS / Linux：推荐使用 pyenv 或系统包管理器安装。

安装完成后，在终端用下面的指令验证一下，如果出现版本号代表安装成功：

python --version

3️⃣ 安装 Node.js 22

Hermes 依赖 Node.js 22，版本太高或太低都可能出问题。

官方推荐使用 nvm（Node Version Manager）安装，这样可以同时安装和管理多个Node版本，如果不想折腾，也可以直接在网上下载安装包一键安装。

# 安装 nvm（如果还没装）curl -o- https://gitee.com/mirrors/nvm/raw/master/install.sh | bash# 重新加载配置source ~/.bashrc# 安装 Node.js 22nvm install 22nvm use 22# 验证node --version   # 应显示 v22.x.x

二、下载 Hermes 源代码（使用 GitCode 镜像）

由于 GitHub 访问不稳定，我们直接用国内 GitCode 镜像 克隆：

https://gitcode.com/GitHub_Trending/he/hermes-agent.git .hermes/hermes-agent

找一个目录，用命令行进入该目录，执行以下git指令下载代码

cd ~git clone https://gitcode.com/GitHub_Trending/he/hermes-agent.git .hermes/hermes-agent

完成后，Hermes 代码存放在 ~/.hermes/hermes-agent 目录。

三、配置包管理器国内源（加速下载）

🐍 配置 uv 使用清华 PyPI 镜像

bashcd ~/.hermes/hermes-agent# 创建 uv 配置文件目录mkdir -p ~/.config/uv# 写入清华源配置cat > ~/.config/uv/uv.toml << 'EOF'[[index]]url = "https://pypi.tuna.tsinghua.edu.cn/simple"default = trueEOF

📦 配置 npm 使用淘宝镜像

npm是安装Node.JS后附带的软件包管理管理器，安装Herems过程中会使用到，国内访问速度较慢，需要使用镜像，这里建议安装cnpm来替代npm，后续直接用cnpm安装软件包：

npm config set registry https://registry.npmmirror.comnpm install -g cnpm --registry=https://registry.npmmirror.com

四、安装 Playwright 浏览器（配置国内下载镜像）

Herems安装过程中会自动安装Playwright测试浏览器，下载速度极慢，导致安装过程卡住，建议先手动安装Playwright，这样Herems检测到已安装会自动跳过这一步。这里还是使用国内镜像：

# 安装 Playwright（指定版本）cnpm install playwright@1.48.0 --force# 设置浏览器下载镜像export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/# 安装 Chromium 浏览器npx playwright install chromium

补充 Python 依赖

这一步是为Herems能方便的接入微信做准备，不需要的可以跳过：

pip install aiohttp cryptographypip install qrcode

五、执行官方安装脚本

cd ~/.hermes/hermes-agentbash scripts/install.sh

执行过程中如果出现 Restore local changes now? [Y/n] 的提示，请务必输入 n（不恢复本地修改）。

安装完成后会自动进入Hermes设置向导，根据指引设置好模型的API。如果你的电脑上还安装了OpenClaw，会问你是否需要导入OpenClaw的设置，这里根据自行需求来选择，如果对Herems不熟悉的同学，建议先选择n，跳过。

选择模型提供商

选择模型版本

完成设置

六、验证安装是否成功

source ~/.bashrchermes --version   # 应输出版本号hermes doctor      # 诊断环境，确保没有红色错误

七、安装 Hermes 后台服务（用于对外通信）

Herems安装后，还只能通过命令行与其对话，如果要通过外部IM工具通信，需要执行指令安装和启动后台服务：

hermes gateway install

八、设置微信连接通道（扫码 + 配对）

hermes gateway setup

选择 微信连接（WeChat）
按提示扫码登录
登录成功后，用微信向自己发一条任意消息
微信会返回一条配对指令

在终端执行配对命令（将 HGPxxxxx 替换为实际弹出的代码）：

hermes pairing approve weixin HGPxxxxx

九、开始使用 🎉

至此，Hermes 已完全安装并连接到你的微信。
现在你可以直接通过微信与 Hermes 交互，让它帮你处理各种任务了。

十、如何完整卸载 Hermes？

如果以后不再使用 Hermes，或想彻底重装，可以按以下步骤干净卸载：

1️⃣ 停止并移除 gateway 服务

hermes gateway stophermes gateway remove

2️⃣ 删除 Hermes 可执行文件（通常由 uv / pip 安装）

# 查找 hermes 命令位置which hermes# 假设输出为 /home/你的用户名/.local/bin/hermesrm -f /home/你的用户名/.local/bin/hermes

3️⃣ 删除 Hermes 数据和配置文件

# 源代码及数据目录rm -rf ~/.hermes# uv 配置（如果不再使用 uv 也可保留）rm -rf ~/.config/uv# npm 全局安装的 Playwright（可选）npm uninstall -g playwright

4️⃣ （可选）移除 Node.js 22（如果你不需要了）

nvm uninstall 22

5️⃣ 清理环境变量

编辑 ~/.bashrc 或 ~/.zshrc，删除任何手动添加的 HERMES_ 相关变量以及 PATH 中指向 Hermes 的条目。
然后执行：

source ~/.bashrc

完成以上步骤后，Hermes 即从系统中彻底移除。如果需要重装，重新执行安装流程即可。

写在最后

以上流程已在多台无法直连 GitHub 的 Linux 机器上验证通过。
如果在执行中遇到新的错误，请记录报错截图 + 执行命令，通过搜索引擎或官方社区查找解决方案，也可以直接向我提问。

祝你使用愉快，效率起飞！ 🚀