注:服务器部署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
但该微信用户没有被授权

常见原因:

  1. pairing code 没批准
  2. pairing 批准了但 gateway 没重启/没加载
  3. allowlist 没配置
  4. 当前微信 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

说明微信消息到了,但用户没授权。

解决顺序:

  1. pairing list
  2. pairing approve
  3. 微信重新发 /status
  4. 必要时配置 allowlist
  5. 重启 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: localDeliver: weixin:chat_id 的区别
  • cron 任务为什么创建成功但微信没收到
  • Gateway is not running 提示如何理解
Logo

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目,面向数字基础设施四大核心场景(服务器、云计算、边缘计算、嵌入式),全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐