在 WSL 环境下完整安装 Hermes Agent（爱马仕）并配置微信机器人的实战记录-程序员充电站

从零开始，在 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`