服务器部署Hermes【超详细版本】(二):微信 Weixin Gateway 与 Docker Compose 常驻运行
服务器部署Hermes超详细指南,由于过于详细,所以分为三部分;结尾有踩坑点说明。
注:服务器部署Hermes超详细指南,由于过于详细,所以分为三部分;结尾有踩坑点说明。
Hermes Agent 云服务器部署(一):基础环境、Docker 镜像、目录挂载与模型配置
Hermes Agent 云服务器部署(二):微信 Weixin Gateway 与 Docker Compose 常驻运行
Hermes Agent 云服务器部署(三):面试题库、Cron 定时任务与故障排查
本笔记记录 Hermes Agent 从“终端聊天可用”到“微信私聊可用”的配置过程。
重点包括:Weixin Gateway、微信配对授权、Docker Compose 后台常驻、两个 SSH 窗口如何操作、常见错误排查。前提:第 1 部分已经完成:
- Docker 镜像
nousresearch/hermes-agent:latest已成功拉取/root/.hermes数据目录已存在- 模型 API 已配置成功
- 终端聊天界面已经可以正常回复
1. 终端聊天能回复,不代表微信能回复
在 setup 完成后,Hermes 可能进入终端聊天界面:
Welcome to Hermes Agent! Type your message or /help for commands.
在这个界面输入:
你好
如果 Hermes 能回复,说明:
模型 provider 配置成功
API Key 可用
模型名称可用
Hermes Agent 本体可以调用模型
但是这只能说明“本地终端聊天”没问题。
微信聊天还需要另一个组件:
Hermes Gateway
Gateway 负责:
- 连接微信 / Telegram / Discord 等消息平台
- 接收微信消息
- 把消息转交给 Hermes Agent
- 把 Agent 回复发回微信
- 执行 cron 定时任务调度
所以:
终端聊天可用 ≠ 微信聊天可用
微信要正常回复,必须启动:
gateway run
2. 退出终端聊天界面
如果当前还在终端聊天界面:
Welcome to Hermes Agent! Type your message or /help for commands.
可以输入:
/exit
或者按:
Ctrl + C
命令解释
/exit 是 Hermes 终端聊天界面的退出命令。
Ctrl + C 是 Linux 终端中断当前前台程序的快捷键。
注意:
- 如果当前运行的是
chat,按Ctrl + C只是退出聊天 - 如果当前运行的是
gateway run,按Ctrl + C会停止微信网关
3. 临时启动微信 Gateway
最初可以用临时方式启动 gateway:
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent gateway run
命令解释
docker run
创建并运行一个新的容器。
-it
交互式运行,适合在终端里实时查看输出。
--rm
容器退出后自动删除容器。
-v /root/.hermes:/opt/data
把宿主机 /root/.hermes 映射到容器内 /opt/data。
这保证临时容器也能读取同一套配置、API Key、微信登录状态和 cron 数据。
-e TZ=Asia/Shanghai
设置容器时区为北京时间。
nousresearch/hermes-agent
使用 Hermes Agent 镜像。
gateway run
启动 Hermes Gateway。
临时启动方式的问题
这种方式适合测试,但不适合长期运行。
原因:
SSH 断开,gateway 可能停止
按 Ctrl+C,gateway 会停止
容器是临时的,没有固定名字
不方便 docker exec / logs / restart 管理
当 gateway 停止时,微信会收到类似消息:
⚠️ Gateway shutting down — Your current task will be interrupted.
这不是 Hermes 崩溃,而是你正在运行的 gateway 被停止了。
4. 配置微信平台
在 setup 或 gateway setup 中,出现平台列表:
Select platforms to configure:
[ ] 1. Telegram
[ ] 2. Discord
...
[ ] 12. WeCom (Enterprise WeChat)
[ ] 13. WeCom Callback (Self-Built App)
[ ] 14. Weixin / WeChat
应选择:
14. Weixin / WeChat
不要选:
12. WeCom
13. WeCom Callback
区别说明
| 选项 | 含义 |
|---|---|
| Weixin / WeChat | 个人微信 |
| WeCom | 企业微信 |
| WeCom Callback | 企业微信自建应用回调 |
当前目标是在个人微信里和 Hermes 聊天,所以选择:
Weixin / WeChat
5. 配置 direct messages 授权方式
配置微信时出现:
How should direct messages be authorized?
→ Use DM pairing approval (recommended)
Allow all direct messages
Only allow listed user IDs
Disable direct messages
选择:
Use DM pairing approval (recommended)
选项解释
| 选项 | 含义 | 是否推荐 |
|---|---|---|
| Use DM pairing approval | 第一次私聊需要配对码批准 | 推荐 |
| Allow all direct messages | 所有人都可以私聊调用 Agent | 不推荐 |
| Only allow listed user IDs | 只允许白名单用户 | 推荐但需要手动配置 |
| Disable direct messages | 禁用私聊 | 不适合当前场景 |
当前选择 pairing approval 的原因:
既安全,又方便
第一次从微信发消息时,Hermes 会给一个 pairing code。服务器端批准后,该微信用户就能正常聊天。
6. 微信收到 pairing code
启动 gateway 后,在微信里发送:
/status
或:
你好
如果用户未授权,微信会收到类似:
Hi~ I don't recognize you yet!
Here's your pairing code: `NENVYLJQ`
Ask the bot owner to run:
hermes pairing approve weixin NENVYLJQ
这说明:
微信消息已经成功到达 Hermes Gateway
但当前微信用户还没有授权
此时不是故障,而是需要批准配对。
7. 为什么 docker exec hermes hermes 会失败
曾经尝试执行:
docker exec -it hermes hermes pairing list
结果报错:
OCI runtime exec failed:
exec: "hermes": executable file not found in $PATH
原因
docker run nousresearch/hermes-agent setup 能正常运行,是因为镜像内部有 entrypoint。
当你执行:
docker run ... nousresearch/hermes-agent setup
实际上 Docker 会先运行镜像的 entrypoint,再把 setup 交给 entrypoint 处理。
但是:
docker exec -it hermes hermes pairing list
是在已经运行的容器里直接找一个叫:
hermes
的可执行文件。
这个可执行文件在容器内不一定存在于 $PATH,所以会失败。
正确做法
用新的临时容器执行 Hermes CLI 命令,并挂载同一个数据目录:
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing approve weixin NENVYLJQ
8. 批准微信配对
当微信收到配对码:
NENVYLJQ
在服务器执行:
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing approve weixin NENVYLJQ
命令解释
docker run -it --rm
启动一个临时 Hermes CLI 容器,执行完自动删除。
-v /root/.hermes:/opt/data
使用和 gateway 一样的数据目录。
这很重要,因为 pairing 信息保存在 /root/.hermes 中。
nousresearch/hermes-agent pairing approve weixin NENVYLJQ
执行 Hermes pairing approve 命令。
参数解释:
| 参数 | 含义 |
|---|---|
pairing |
配对管理 |
approve |
批准配对 |
weixin |
平台是微信 |
NENVYLJQ |
微信收到的配对码 |
批准成功后,在微信里重新发送:
/status
如果有回复,就说明授权成功。
9. 查看 pairing 列表
如果不确定配对码,可以执行:
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing list
作用
列出当前等待批准的配对请求。
如果微信里显示的配对码和命令里显示的配对码有差异,以服务器上 pairing list 显示的为准。
10. /status 的作用
微信私聊发送:
/status
正常会返回 Hermes Gateway 状态。
例如可能看到:
Agent Running: No
Connected Platforms: weixin
解释
Agent Running: No
不代表 Hermes 没启动。
它通常表示:
当前没有正在执行中的 agent 任务
如果你随后发送:
你好
Hermes 能回复,就说明服务正常。
Connected Platforms: weixin
说明微信平台已连接。
11. /sethome 的作用
微信授权成功后,发送:
/sethome
作用
把当前微信会话设置为 Hermes 的 home channel。
后续 cron 定时任务、主动推送、默认投递目标等,可能会使用这个 home channel。
执行成功后,Hermes 可能会提示当前 home 设置为某个微信 chat_id,例如:
o9cq80y9HMRyFHDRQ5NMyWk8cYcc@im.wechat
这个 ID 后续创建 cron 任务时非常重要。
比如 cron 投递到微信时可能需要:
weixin:o9cq80y9HMRyFHDRQ5NMyWk8cYcc@im.wechat
12. 为什么需要 Docker Compose 常驻运行
临时运行 gateway 的方式是:
docker run -it --rm ... gateway run
缺点:
终端关闭服务就停
Ctrl+C 服务就停
容器无固定名字
服务器重启后不会自动恢复
管理不方便
因此需要 Docker Compose 后台常驻运行。
目标是让 Hermes Gateway 作为后台服务运行:
容器名固定为 hermes
服务器重启后自动启动
可以 docker compose restart
可以 docker compose logs 查看日志
13. 创建 Docker Compose 文件
在服务器执行:
cd /root
cat > compose.hermes.yml <<'EOF'
services:
hermes:
image: nousresearch/hermes-agent:latest
container_name: hermes
restart: unless-stopped
command: gateway run
volumes:
- /root/.hermes:/opt/data
environment:
- TZ=Asia/Shanghai
mem_limit: 3500m
cpus: "2.5"
EOF
命令解释
cd /root
切换到 root 用户主目录。
将 compose 文件放在 /root 下,方便管理。
cat > compose.hermes.yml <<'EOF'
...
EOF
创建文件 /root/compose.hermes.yml。
这是 shell heredoc 写法,用于把多行内容写入文件。
compose 文件逐行解释
services:
定义 Docker Compose 管理的服务列表。
hermes:
定义一个服务,名字叫 hermes。
image: nousresearch/hermes-agent:latest
使用镜像:
nousresearch/hermes-agent:latest
container_name: hermes
指定容器名称为:
hermes
这样后续可以稳定使用:
docker ps
docker logs hermes
docker compose restart hermes
restart: unless-stopped
设置重启策略。
含义:
除非手动停止,否则容器异常退出或服务器重启后会自动启动
这是服务器长期运行服务常用配置。
command: gateway run
容器启动后执行:
gateway run
即启动 Hermes Gateway。
volumes:
- /root/.hermes:/opt/data
挂载数据目录。
含义:
宿主机 /root/.hermes
映射到容器内 /opt/data
这样配置、微信登录状态、cron、题库等数据不会因为容器删除而丢失。
environment:
- TZ=Asia/Shanghai
设置时区为北京时间。
mem_limit: 3500m
限制容器最多使用约 3.5GB 内存。
服务器本身是 4G 内存,加了 4G swap。限制 Hermes 容器内存是为了避免容器把整台机器内存吃满。
cpus: "2.5"
限制容器最多使用约 2.5 个 CPU 核心。
服务器是 4 核,给 Hermes 留 2.5 核,避免它占满全部 CPU。
14. 启动 Hermes Gateway 常驻容器
执行:
docker compose -f /root/compose.hermes.yml up -d
命令解释
docker compose
使用 Docker Compose v2。
-f /root/compose.hermes.yml
指定 compose 文件路径。
up
创建并启动服务。
-d
后台运行,也叫 detached mode。
如果成功,会看到类似:
[+] Running 2/2
✔ Network root_default Created
✔ Container hermes Started
这说明容器已经在后台启动。
15. 查看容器是否运行
执行:
docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}"
命令解释
docker ps
列出正在运行的容器。
--format "table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}"
按指定格式输出表格,只显示关键信息。
正常应该看到:
CONTAINER ID IMAGE STATUS NAMES
7bb1315ac9f6 nousresearch/hermes-agent:latest Up 12 seconds hermes
其中:
NAMES = hermes
STATUS = Up ...
说明 Hermes Gateway 正在运行。
16. 查看 Gateway 日志
执行:
docker compose -f /root/compose.hermes.yml logs -f hermes
命令解释
docker compose -f /root/compose.hermes.yml logs
查看 compose 服务日志。
-f
follow,持续跟踪日志输出。
hermes
只查看 hermes 这个服务的日志。
正常启动时会看到类似:
Dropping root privileges
Syncing bundled skills into ~/.hermes/skills/ ...
Done: 0 new, 0 updated, 89 unchanged. 89 total bundled.
┌─────────────────────────────────────────────────────────┐
│ ⚕ Hermes Gateway Starting... │
├─────────────────────────────────────────────────────────┤
│ Messaging platforms + cron scheduler │
│ Press Ctrl+C to stop │
└─────────────────────────────────────────────────────────┘
注意
这个命令只是看日志。
按:
Ctrl + C
只会退出日志查看,不会停止后台容器。
这是非常重要的一点。
17. 两个 SSH 窗口如何使用
当时使用了两个 SSH 窗口。
第一个窗口
用于看日志:
docker compose -f /root/compose.hermes.yml logs -f hermes
这个窗口可以观察:
- 微信是否收到消息
- 用户是否 unauthorized
- gateway 是否重启
- cron 是否执行
- agent 是否报错
如果不想继续看日志,可以按:
Ctrl + C
退出日志查看。
这不会停止 Hermes 服务。
第二个窗口
用于执行管理命令,例如:
docker ps
docker compose -f /root/compose.hermes.yml restart hermes
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing approve weixin 配对码
总结
| 窗口 | 用途 |
|---|---|
| 第一个窗口 | 看实时日志 |
| 第二个窗口 | 执行管理命令 |
18. Gateway shutting down 是什么
微信曾收到:
⚠️ Gateway shutting down — Your current task will be interrupted.
原因
通常是因为执行了:
docker compose -f /root/compose.hermes.yml restart hermes
或者停止了临时 gateway:
Ctrl + C
解释
这条消息表示:
当前 Gateway 正在关闭
正在执行的任务会被中断
它不一定是错误。
如果是你主动重启容器导致的,这是正常现象。
19. 常用 Compose 管理命令
启动服务
docker compose -f /root/compose.hermes.yml up -d
后台启动 Hermes Gateway。
查看运行状态
docker ps
查看正在运行的容器。
查看实时日志
docker compose -f /root/compose.hermes.yml logs -f hermes
持续查看日志。
查看最近 100 行日志
docker compose -f /root/compose.hermes.yml logs --tail=100 hermes
适合排查问题,不会一直阻塞终端。
重启服务
docker compose -f /root/compose.hermes.yml restart hermes
用于修改 .env 或配置后让服务重新加载。
停止服务
docker compose -f /root/compose.hermes.yml down
停止并删除 compose 创建的容器和网络。
注意:
不会删除 /root/.hermes 数据目录
再次启动服务
docker compose -f /root/compose.hermes.yml up -d
20. 检查微信相关日志
如果微信没有回复,可以查看日志:
docker compose -f /root/compose.hermes.yml logs --tail=200 hermes | grep -Ei "weixin|wechat|pair|auth|error|account|login|poll|message"
命令解释
docker compose -f /root/compose.hermes.yml logs --tail=200 hermes
查看最近 200 行 Hermes 日志。
grep -Ei "weixin|wechat|pair|auth|error|account|login|poll|message"
筛选包含关键字的日志。
参数:
| 参数 | 含义 |
|---|---|
-E |
使用扩展正则 |
-i |
忽略大小写 |
关键字含义:
| 关键字 | 说明 |
|---|---|
weixin / wechat |
微信相关日志 |
pair |
配对相关 |
auth |
授权相关 |
error |
错误 |
account |
微信账号 |
login |
登录 |
poll |
轮询 |
message |
消息 |
21. Unauthorized user 日志
日志中曾出现:
WARNING gateway.run: Unauthorized user: o9cq80y9HMRyFHDRQ5NMyWk8cYcc@im.wechat
这说明:
微信消息已经到达 Gateway
但该微信用户没有被授权
常见原因:
- pairing code 没批准
- pairing 批准了但 gateway 没重启/没加载
- allowlist 没配置
- 当前微信 chat_id 和批准的不是同一个
处理思路
优先处理 pairing:
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing list
然后批准:
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing approve weixin 配对码
如果仍然 unauthorized,可以考虑配置 allowlist。
22. allowlist 的作用
日志里还出现过:
WARNING gateway.run: No user allowlists configured. All unauthorized users will be denied.
意思是:
当前没有配置用户白名单
未授权用户会被拒绝
如果 pairing 机制没有正确生效,可以手动把自己的微信 ID 加入 Weixin allowlist。
例如微信 ID 是:
o9cq80y9HMRyFHDRQ5NMyWk8cYcc@im.wechat
可以编辑:
nano /root/.hermes/.env
追加类似配置:
WEIXIN_ALLOWED_USERS=o9cq80y9HMRyFHDRQ5NMyWk8cYcc@im.wechat
然后重启 gateway:
docker compose -f /root/compose.hermes.yml restart hermes
注意
不同 Hermes 版本的 allowlist 环境变量名可能略有差异。
如果设置后无效,应查看官方文档或当前 .env 中已有的 Weixin 配置项。
23. 微信普通聊天测试顺序
授权成功后,建议按这个顺序测试微信:
第一步:测试状态命令
/status
如果有回复,说明微信 Gateway 通了。
第二步:设置 home channel
/sethome
如果成功,会将当前私聊会话设置为默认投递目标。
第三步:测试普通模型回复
你好,用一句中文回复我
如果 Hermes 回复中文,说明:
微信 Gateway 正常
用户授权正常
模型调用正常
消息回传正常
24. 为什么优先用私聊测试
当前部署目标是微信个人聊天。
普通微信群可能存在限制:
- iLink bot 身份可能无法收到普通微信群消息
- Hermes 可能默认禁用 group messages
- 群聊用户授权更复杂
- 群聊容易误触发 API 调用
所以先用微信私聊测试最稳。
建议配置:
WEIXIN_DM_POLICY=pairing
WEIXIN_GROUP_POLICY=disabled
含义:
| 配置 | 含义 |
|---|---|
WEIXIN_DM_POLICY=pairing |
私聊使用配对授权 |
WEIXIN_GROUP_POLICY=disabled |
禁用群聊 |
25. 重新运行 gateway setup
如果微信配置缺失,可以重新运行:
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent gateway setup
命令解释
gateway setup
进入消息平台配置向导。
可以重新选择:
Weixin / WeChat
并完成扫码登录、授权策略设置。
26. 查看 Hermes 数据目录中的微信配置
可以执行:
grep -R "WEIXIN\|weixin\|wechat" -n /root/.hermes | head -80
命令解释
grep -R
递归搜索目录。
"WEIXIN\|weixin\|wechat"
搜索微信相关关键字。
-n
显示行号。
/root/.hermes
搜索 Hermes 数据目录。
head -80
只显示前 80 行,避免输出太多。
用途
检查是否存在:
- Weixin 配置
- account_id
- allowed users
- dm policy
- group policy
- token / login state
27. 当前阶段最终状态
完成第 2 阶段后,应该达到:
容器后台运行
docker ps
能看到:
hermes Up ...
Gateway 日志正常
docker compose -f /root/compose.hermes.yml logs --tail=100 hermes
能看到 Gateway started,没有持续报错。
微信 /status 有回复
微信发送:
/status
能收到回复。
微信 /sethome 成功
微信发送:
/sethome
能成功设置 home channel。
微信普通聊天可用
微信发送:
你好
Hermes 能调用模型并回复。
28. 第 2 部分常用命令汇总
启动 Hermes Gateway
docker compose -f /root/compose.hermes.yml up -d
查看容器
docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}"
查看实时日志
docker compose -f /root/compose.hermes.yml logs -f hermes
查看最近日志
docker compose -f /root/compose.hermes.yml logs --tail=100 hermes
重启 Gateway
docker compose -f /root/compose.hermes.yml restart hermes
停止 Gateway
docker compose -f /root/compose.hermes.yml down
重新配置 Gateway
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent gateway setup
查看 pairing 列表
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing list
批准微信 pairing
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing approve weixin 配对码
查看微信相关日志
docker compose -f /root/compose.hermes.yml logs --tail=200 hermes | grep -Ei "weixin|wechat|pair|auth|error|account|login|poll|message"
29. 本阶段易踩坑汇总
坑 1:以为终端聊天能回复,微信就一定能回复
实际:
终端聊天只验证模型调用
微信聊天必须启动 gateway
坑 2:用临时 docker run 跑 gateway
表现:
SSH 断开或 Ctrl+C 后,微信收到 Gateway shutting down
解决:
使用 Docker Compose 后台常驻:
docker compose -f /root/compose.hermes.yml up -d
坑 3:配对码没批准
表现:
Hi~ I don't recognize you yet!
Here's your pairing code: ...
解决:
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing approve weixin 配对码
坑 4:docker exec hermes hermes ... 报错
表现:
exec: "hermes": executable file not found in $PATH
原因:
容器内没有直接叫 hermes 的可执行命令。
解决:
用新的临时容器执行 CLI:
docker run -it --rm \
-v /root/.hermes:/opt/data \
-e TZ=Asia/Shanghai \
nousresearch/hermes-agent pairing list
坑 5:看日志时按 Ctrl+C 以为会停止服务
如果运行的是:
docker compose -f /root/compose.hermes.yml logs -f hermes
按 Ctrl+C 只会退出日志查看,不会停止后台服务。
如果运行的是:
docker run -it --rm ... gateway run
按 Ctrl+C 会停止 gateway。
坑 6:微信 Unauthorized user
表现:
Unauthorized user: xxx@im.wechat
说明微信消息到了,但用户没授权。
解决顺序:
- pairing list
- pairing approve
- 微信重新发
/status - 必要时配置 allowlist
- 重启 gateway
第 3 部分将记录:
Hermes Agent 云服务器部署(三):面试题库、Cron 定时任务与故障排查
会详细解释:
/root/.hermes/interview和/opt/data/interview的关系- 如何放入 txt / md 面试题文件
- 为什么 Hermes 能读 txt,但可能被安全审批拦截
/approve、/deny、/stop怎么用- 为什么自然语言创建任务可能生成不存在的脚本
Script not found: /opt/data/scripts/check_and_send.sh的原因/cron在微信里 Unknown command 的原因- 用 SSH 创建 cron 任务
Deliver: local和Deliver: weixin:chat_id的区别- cron 任务为什么创建成功但微信没收到
Gateway is not running提示如何理解
openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目,面向数字基础设施四大核心场景(服务器、云计算、边缘计算、嵌入式),全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构
更多推荐
所有评论(0)