Hermes Agent WSL 安装与 Telegram / 微信 Bot 对接

文档简介

本文手把手带你在 WSL2 (Ubuntu) 环境下从零部署 Hermes Agent，并完成两大主流 IM 的 Bot 对接：

  • Telegram：通过 @BotFather 创建 Bot，拿到 Token 后 5 分钟上线，支持群聊、语音、文件。
  • 微信：通过腾讯 iLink Bot API 扫码登录个人微信，长轮询收消息，无需公网 IP、无需 webhook。

适用环境：Windows 11 + WSL2 Ubuntu 22.04/24.04。全程命令可直接复制运行。

一、WSL 环境准备

假设你已经装好 WSL Ubuntu（没装的话参考《WSL 安装 Ubuntu 并改名为所需名称》）。

确保系统有 curl（用来下载安装脚本），没有就装一下：

1
sudo apt update && sudo apt install -y curl

不用手动装 Python / pip / Node.js——Hermes 安装脚本会自己下载并准备好 Python 3.14、Node.js、所有依赖包，全部放在 ~/.hermes/ 目录下，跟系统环境完全隔离，不会跟你系统里的 Python / conda 环境冲突。

二、一键安装 Hermes Agent

直接跑官方一键脚本：

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

安装过程中会有几个交互提示：

提示 建议选择 说明
是否导入 OpenClaw 数据 YES 如果你之前用过 OpenClaw，直接迁过来
是否执行 migration YES 必须选 YES，否则数据库结构不对
Setup 类型 Quick setup 快速起步，后面再细调

安装完成后，验证一下命令是否可用：

1
2
hermes --version
hermes doctor

hermes doctor 会自检环境依赖，看到全部打勾就说明装好了。

安装路径说明

WSL 下 Hermes 的默认目录结构：

1
2
3
4
5
6
~/.hermes/
├── hermes-agent/          # 源码 + venv 虚拟环境
├── .env                   # 环境变量配置文件
├── config.yaml            # 主配置文件
├── logs/                  # 运行日志
└── weixin/                # 微信账号凭据（对接微信后生成）

重要：Hermes 用的是自己的 venv，不是系统 Python，也不是 conda。后面装依赖都要进到它的 venv 里装，这是最常见的踩坑点。

三、Gateway 的三种运行方式与 Web 管理界面

3.1 前台运行（调试用）

1
hermes gateway
  • 特点：日志直接打印在终端里，Ctrl+C 就停
  • 使用场景：刚配置完、排查问题、看实时日志。平时不这么跑——关了终端 Bot 就下线了。

3.2 后台运行（日常用）

1
2
3
4
hermes gateway start    # 后台启动
hermes gateway status   # 看状态
hermes gateway stop     # 停止
hermes gateway restart  # 重启
  • 特点：进程挂到后台，关终端也不影响
  • 使用场景：日常使用，配好 Bot 之后就这么跑

3.3 systemd 开机自启（长期常驻推荐）

想让 WSL 一开起来 Bot 就自动跑，不用每次手动启动，就用 systemd：

1
2
3
# 配置向导会帮你装 systemd 用户服务
hermes gateway setup
# 选 "Install systemd user unit"，一路确认就行

装好之后：

1
2
3
systemctl --user enable hermes-gateway   # 开机自启
systemctl --user start hermes-gateway    # 启动
systemctl --user status hermes-gateway  # 看状态
  • 特点：WSL 启动自动拉起，崩了自动重启
  • 使用场景：你想让这个 AI 助手 7×24 小时在线，随时手机发消息就能用

前提：WSL 里要先开 systemd（参考你那篇 WSL 安装文章里的 wsl.conf 配置）。

3.4 启动 Web 图形界面（hermes desktop）

Hermes 自带一个本地 Web 版管理界面，不用单独下载安装，直接跑命令就行：

1
hermes desktop

启动后终端会输出一个本地访问地址，类似：

1
Hermes Web UI running at http://localhost:8642

用 Windows 上的浏览器打开这个地址，就是完整的图形界面——可视化聊天窗口、配置面板、会话历史、Bot 管理都在里面。

它跟 Gateway 的关系：

Gateway hermes desktop
本质 后台服务进程 本地 Web 管理界面
跑什么 接 Telegram / 微信，收消息回消息 可视化聊天、改配置、看日志、管理会话
需要一直开着吗 要，Bot 在线全靠它 不用，用完关掉就行，不影响 Gateway 跑
适合干嘛 当 Bot 用，远程手机指挥 本地调试、可视化配置、看历史会话

简单说：

  • Gateway 是发动机，负责真正接 Telegram / 微信、跑 AI 推理，必须一直开着；
  • hermes desktop 是驾驶舱，给你个浏览器里的图形界面方便操作，用完关掉不影响 Bot 运行。

什么时候用 desktop？

  1. 刚装好想可视化配置 Bot、选模型、看日志
  2. 想看历史会话、管理多个 Agent 配置
  3. 不想在终端里敲命令，喜欢点鼠标

什么时候不用？

  • 你就想接个 Telegram / 微信 Bot，手机上发消息用 → 命令行 hermes gateway start 跑着就行，desktop 想开再开，不想开完全不影响。

四、Telegram Bot 对接（详细步骤）

4.1 创建 Bot 拿 Token

  1. 打开 Telegram，搜索 @BotFather（官方机器人管理工具）；
  2. 发送 /newbot；
  3. 输入 Bot 的显示名称（随便起，比如 “我的 Hermes”）；
  4. 输入 Bot 的用户名（必须唯一，且以 bot 结尾，比如 my_hermes_2026_bot）；
  5. BotFather 会回复一串 API Token，长这样：
1
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

这个 Token 就是你 Bot 的密码，别泄露给别人。 泄露了就找 BotFather 发 /revoke 重置。

4.2 获取你自己的 Telegram 用户 ID

光有 Bot 还不够，得限制只有你自己能用，不然谁都能白嫖你的 AI。

在 Telegram 搜索 @userinfobot，随便发一句话，它会回复你的数字 ID，类似：

1
123456789

把这个数字记下来。

4.3 写入 Hermes 配置

方式 A：交互式向导（推荐新手）

1
hermes gateway setup

在提示里选 Telegram，然后按提示粘贴 Bot Token 和你的用户 ID 即可，向导会自动写好配置。

方式 B：手动写 .env（推荐老手）

直接编辑 ~/.hermes/.env：

1
nano ~/.hermes/.env

加入两行：

1
2
3
4
5
6
# Telegram Bot Token（从 BotFather 拿到的那串）
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

# 你的 Telegram 用户 ID（从 @userinfobot 拿到的数字）
# 多个用户用英文逗号分隔
TELEGRAM_ALLOWED_USERS=123456789

保存退出（nano 是 Ctrl+O 回车，Ctrl+X）。

4.4 启动 Gateway 测试

1
hermes gateway

看到类似下面的日志就说明连上了：

1
2
[telegram] Connected to Telegram (polling mode)
Gateway started successfully

打开 Telegram，找到你刚才创建的 Bot，发一句 hello，如果 Hermes 正常回复，就说明对接成功了。

4.5 进阶：群聊配置

想在群里用 Bot？还需要做两步：

第一步：关掉 BotFather 隐私模式

  1. 给 @BotFather 发 /mybots；
  2. 选你的 Bot；
  3. 进 Bot Settings → Group Privacy → Turn off。

改完隐私模式后，必须把 Bot 从群里踢掉再重新拉进来，否则 Telegram 会缓存旧的隐私设置，Bot 还是看不到群消息。

第二步：配置群聊白名单（可选）

在 ~/.hermes/.env 里加：

1
2
3
4
5
6
7
# 允许哪些群聊使用 Bot（群 ID 是负数，比如 -1001234567890）
TELEGRAM_ALLOWED_CHATS=-1001234567890

# 群里必须 @Bot 才回复（不设置的话所有群消息都会触发）
# 在 config.yaml 里配：
# telegram:
#   require_mention: true

4.6 进阶：代理配置（国内必看）

国内直连 Telegram API 可能不通，需要走代理。在 ~/.hermes/.env 里加：

1
2
# 如果你本地跑了 Clash / V2Ray 之类的代理
TELEGRAM_PROXY=socks5://127.0.0.1:1080

支持 http://、https://、socks5:// 三种协议。

五、微信 Bot 对接（详细步骤）

微信对接走的是腾讯官方的 iLink Bot API，不是那种野路子 hook 方案，相对稳。

5.1 先装依赖

微信适配器需要两个 Python 包：aiohttp 和 cryptography。

注意：必须装到 Hermes 自己的 venv 里，别装到系统 Python！

1
2
3
4
5
# 进入 Hermes 源码目录
cd ~/.hermes/hermes-agent

# 用 Hermes 自己的 Python 装依赖
python3 -c "import pm; pm.sync_venv(['messaging'], explicit=True)"

这条命令会自动把 messaging 相关的所有依赖（包括 aiohttp、cryptography、终端二维码渲染）都装好。

5.2 扫码登录

运行配置向导：

1
hermes gateway setup

在提示里选 Weixin（微信）。

接下来向导会做这几件事：

  1. 向 iLink 服务器请求一个登录二维码；
  2. 在终端里直接打印二维码（ASCII 字符画）；
  3. 拿出手机微信，扫这个二维码；
  4. 手机上点确认登录；
  5. 终端显示「微信连接成功，account_id=xxx」。

如果终端二维码渲染不出来，向导会同时打印一个二维码 URL，用手机浏览器打开那个链接也能看到二维码。

登录成功后，账号凭据（account_id、token）会自动保存到 ~/.hermes/weixin/accounts/ 目录下，不用手动复制粘贴。

5.3 配置访问权限

编辑 ~/.hermes/.env：

1
nano ~/.hermes/.env

加上：

1
2
3
4
5
6
7
8
9
10
11
12
# 你的微信账号 ID（扫码成功后向导会自动写入，确认一下有没有就行）
WEIXIN_ACCOUNT_ID=你的account_id

# 私信策略：
#   open       = 任何人都能给 Bot 发消息（默认，不安全）
#   allowlist  = 只有白名单里的人能用（推荐）
#   disabled   = 关掉私信
WEIXIN_DM_POLICY=allowlist

# 白名单用户 ID（逗号分隔）
# 怎么获取你的微信 ID？随便给 Bot 发句话，然后看 gateway 日志里的 sender_id
WEIXIN_ALLOWED_USERS=你的微信user_id

5.4 启动 Gateway 测试

1
hermes gateway

看到日志里出现 [weixin] Connected to iLink API 就说明连上了。

打开微信，找到你扫码登录的那个 iLink Bot 账号（它会出现在你的通讯录里，类似一个服务号），发一句 你好，Hermes 应该会回复你。

5.5 微信对接的几个重要限制（必看）

官方文档明确说了，iLink Bot 身份有几个硬限制，别踩坑：

限制 说明
群聊基本没用 iLink Bot 身份通常收不到普通微信群的消息，群聊功能形同虚设。只能用私信（DM）。
不是你的个人微信号 登录后是一个独立的 Bot 身份（类似 a5ace6fd@im.bot），不是你平时用的微信号，好友看不到你的朋友圈。
每个 Token 只能跑一个实例 别同时开两个 gateway 连同一个微信账号，会互相踢。
会话过期要重扫 报错 errcode=-14 就是登录态过期了，重新跑一次 hermes gateway setup 扫码就行。

一句话总结微信对接：当你的私人微信助手用没问题，想拉群里当群管就别想了，iLink 侧不推群消息。

5.6 微信支持的功能

  • ✅ 文字消息（支持 Markdown 渲染，标题/表格/代码块都能显示）
  • ✅ 图片 / 视频 / 文件 / 语音收发（自动 AES-128-ECB 加解密）
  • ✅ 「正在输入…」状态提示
  • ✅ 长轮询收消息，不需要公网 IP、不需要 webhook
  • ❌ 普通微信群消息（iLink 不推送）

六、同时跑 Telegram + 微信

两个平台可以同时接。在 ~/.hermes/.env 里把两边的配置都写上，然后直接：

1
hermes gateway start

Gateway 会同时启动所有已配置的平台适配器。日志里应该能看到两行连接成功：

1
2
[telegram] Connected to Telegram (polling mode)
[weixin] Connected to iLink API

七、常见坑与排错

坑 1：Telegram 发消息完全没反应

症状：Gateway 启动了，Telegram 发消息石沉大海。

原因：99% 是依赖装错了环境。Hermes 用的是自己的 venv，你可能把 python-telegram-bot 装到系统 Python 里了。

解决：

1
2
3
4
5
# 进到 Hermes 目录
cd ~/.hermes/hermes-agent

# 用 Hermes 自己的 Python 装
./venv/bin/python -m pip install python-telegram-bot

然后验证：

1
hermes doctor

看到 ✓ python-telegram-bot 就对了。

坑 2：微信启动报 aiohttp and cryptography are required

原因：微信依赖没装对环境。

解决：

1
2
cd ~/.hermes/hermes-agent
python3 -c "import pm; pm.sync_venv(['messaging'], explicit=True)"

坑 3：微信报 Another local Hermes gateway is already using this Weixin token

原因：有另一个 gateway 进程还在跑，占着同一个 token。

解决：

1
2
3
4
5
6
7
8
# 先停掉所有 gateway
hermes gateway stop

# 确认进程都清了
ps aux | grep hermes

# 再重新启动
hermes gateway

坑 4：群里 Bot 不说话

按顺序排查：

  1. BotFather 隐私模式关了没？关完有没有把 Bot 踢出群再拉回来？
  2. TELEGRAM_ALLOWED_USERS 里有没有这个发消息的人？
  3. 配了 require_mention: true 吗？配了的话必须 @Bot 才会回。

坑 5：国内连不上 Telegram

检查代理：

1
2
3
4
# 确认代理在跑
curl -x socks5://127.0.0.1:1080 https://api.telegram.org -I

# 通了的话，在 .env 里加 TELEGRAM_PROXY

八、常用命令速查

命令 作用
hermes gateway setup 交互式配置平台（Telegram/微信等）
hermes gateway 前台启动 Gateway（看日志用）
hermes gateway start 后台启动
hermes gateway stop 停止
hermes gateway status 查看运行状态
hermes gateway restart 重启
hermes desktop 启动本地 Web 图形界面
hermes doctor 自检环境依赖
hermes pairing list 查看待审批的配对请求

九、总结

Hermes Agent 在 WSL 下的部署其实很简单，核心就三步：

  1. 跑一键脚本装本体；
  2. Gateway 后台跑起来；
  3. 接 Telegram / 微信 Bot。

最容易踩的坑就是「依赖装错 Python 环境」——记住一句话：Hermes 只认自己 venv 里的包，别往系统 Python 里瞎装。

Telegram 适合自己远程折腾、群聊协作；微信适合日常随手发消息问问题。两个一起开，手机上随时随地指挥你的 AI Agent 干活。