从零开始，在 Windows WSL2 Ubuntu 中安装 Nous Research 的开源 AI 智能体 Hermes Agent，并绑定微信个人号实现聊天机器人。本文记录了踩过的所有坑和解决方案。

---

一、背景与动机

Hermes Agent 是一个强大的开源 AI 智能体框架，支持 CLI、TUI、以及多种聊天平台（微信、Telegram、Discord 等）。由于官方安装脚本默认从 GitHub 和国外源拉取代码及依赖，国内用户在 WSL 环境下安装时往往会遇到网络超时、依赖下载失败、权限报错等一系列问题。本文详细记录了完整的安装过程以及每个卡点的解决办法。

环境信息

• 宿主机：Windows 11

• WSL 版本：WSL2，Ubuntu 24.04

• Python 版本：3.11.15（由 uv 管理）

• Hermes Agent 版本：main 分支

---

二、安装前的准备

2.1 确保 WSL 网络正常

WSL 默认可以访问外网，但国内访问 GitHub、raw.githubusercontent.com、npm 官方源、PyPI 官方源速度较慢甚至超时。建议提前配置好国内镜像或代理。

2.2 安装必要基础工具

bash

sudo apt update
sudo apt install -y curl git unzip

---

三、安装 Hermes Agent

3.1 初始尝试：直接使用官方脚本（失败）

bash

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

报错：

text

curl: (35) Recv failure: Connection reset by peer

原因：国内无法稳定访问 raw.githubusercontent.com。

解决：修改 hosts 文件或使用国内镜像克隆代码。

3.2 替换为 GitCode 镜像克隆

bash

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

然后手动执行安装脚本（此时脚本内的 git clone 会因为目录已存在而跳过）：

bash

./scripts/install.sh

3.3 安装卡在 “Installing dependencies...”

脚本运行到 → Installing dependencies... 后长时间无响应。

原因：uv 包管理器默认从国外 PyPI 源下载，速度极慢。

解决：中断脚本（Ctrl+C），手动使用国内镜像安装依赖。

bash

cd ~/.hermes/hermes-agent
source venv/bin/activate   # 脚本已创建好 venv
uv pip install -e ".[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

完成后重新运行 ./scripts/install.sh，它会跳过已安装的依赖。

3.4 安装 Node.js 依赖时卡住

脚本执行到 → Installing Node.js dependencies (browser tools)... 再次卡住。

原因：npm install 使用国外源。

解决：配置 npm 淘宝镜像，中断后重试。

bash

npm config set registry https://registry.npmmirror.com
./scripts/install.sh   # 重新运行

3.5 Playwright 浏览器下载失败（404）

后续步骤中 Playwright 尝试下载 Chromium，报错：

text

Downloading Chrome for Testing 147.0.7727.15 ... from https://npmmirror.com/mirrors/playwright//builds/cft/147.0.7727.15/linux64/chrome-linux64.zip
Error: Download failed: server returned code 404

原因：淘宝镜像中没有对应版本的 Chromium 文件。

解决：跳过浏览器工具（不影响核心聊天功能）。

bash

export HERMES_SKIP_BROWSER=1
./scripts/install.sh

脚本会跳过 Playwright 安装，继续完成后续配置。

---

四、配置 DeepSeek API 作为模型后端

安装完成后，使用向导配置 API：

bash

hermes model

• 选择 provider：deepseek

• 输入 API Key（去 DeepSeek 官网 申请）

• 选择模型：deepseek-v4-pro 或 deepseek-v4-flash

也可以直接编辑 ~/.hermes/config.yaml：

yaml

model:
  provider: deepseek
  model: deepseek-v4-flash
  api_key: sk-xxxxxxxx
  base_url: https://api.deepseek.com/v1

---

五、配置微信聊天平台

5.1 安装微信适配器依赖

bash

cd ~/.hermes/hermes-agent
source venv/bin/activate
uv pip install aiohttp cryptography qrcode

注意：不要直接用 pip install，否则会报 externally-managed-environment 错误。使用 uv pip 或 python -m pip。

5.2 运行网关配置向导

bash

hermes gateway setup

• 选择 weixin

• 终端会显示二维码，用手机微信扫描并确认登录

• 设置私聊授权方式：推荐选择 Use DM pairing approval (recommended)

• 选择是否将当前微信账号设为主频道：Y

5.3 启动网关

bash

hermes gateway run

遇到的第一个问题：网关提示未授权用户

text

WARNING gateway.run: No user allowlists configured. All unauthorized users will be denied.
Unauthorized user: xxxxxx6Z3VKKd5qu-ABCxxxxBWORkbs@im.wechat

原因：你的微信账号尚未获得机器人授权。

解决：在另一个终端执行配对批准命令。

bash

cd ~/.hermes/hermes-agent
source venv/bin/activate
hermes pairing approve weixin <机器人发来的配对码>

配对码会由机器人自动发送给你（首次私聊时回复的消息中包含类似 RL8XwGHU 的代码）。批准后网关日志会显示：

text

Approved! User ... can now use the bot~

5.4 让网关在后台持续运行（WSL 环境建议）

WSL 下 systemd 服务不稳定，推荐使用 tmux：

bash

sudo apt install tmux -y
tmux new -s hermes
cd ~/.hermes/hermes-agent
source venv/bin/activate
hermes gateway run

然后按 Ctrl+B，再按 D 脱离会话。之后可关闭终端，网关继续运行。重新进入会话：

bash

tmux attach -t hermes

---

六、完整安装流程图解

---

七、常见问题汇总

问题现象	原因	解决方案
curl: (35) Recv failure	GitHub raw 域名被阻断	修改 hosts 或使用 gitcode 镜像
uv pip install 卡住	国外 PyPI 源慢	添加 -i https://pypi.tuna.tsinghua.edu.cn/simple
npm install 卡住	国外 npm 源慢	npm config set registry https://registry.npmmirror.com
Playwright 下载 404	镜像缺少对应版本	跳过：HERMES_SKIP_BROWSER=1
pip install 报 externally-managed-environment	使用了系统 pip 而非虚拟环境	用 uv pip 或 python -m pip
微信机器人不回复，提示 Unauthorized	未批准用户	hermes pairing approve weixin <code>
关闭终端后网关停止	WSL 不支持 systemd 服务	使用 tmux 或 nohup

---

八、最终效果

• 在微信中向机器人发送消息，能正常收到 DeepSeek 模型的回复。

• 支持私聊和群聊 @（需另外配置白名单）。

• 网关可使用 tmux 长期运行，WSL 重启后重新 tmux attach 并再次运行 hermes gateway run 即可。

---

九、总结

Hermes Agent 是一个功能非常丰富的 AI 智能体框架，但在国内网络环境下安装确实需要一些额外的手动干预。主要克服了以下几个难点：

1. 代码获取：使用 GitCode 镜像代替 GitHub。

2. Python 依赖：为 uv 指定清华源。

3. Node.js 依赖：为 npm 配置淘宝源。

4. 浏览器工具：跳过（非必需）。

5. 微信授权：理解配对审批机制。

希望这篇记录能帮助同样在 WSL 上尝试 Hermes Agent 的读者少走弯路。如果你在安装过程中遇到其他问题，欢迎在评论区交流！