Hermes Agent 配置 QQ 机器人接入完整教程

我用了一段时间 Hermes Agent，对比之前用的 OpenClaw，不得不说 Hermes 在理解任务、调用工具和整体智能程度上确实更胜一筹。今天我把整个配置过程一步步记下来，方便有需要的朋友参考。

这篇文章会一步步告诉你怎么配置 Hermes Agent，让 QQ 机器人连上来，这样你直接在 QQ 上就能跟 AI 助手聊天干活了。

🌐 第一步：让 Hermes Gateway 允许外网访问

Hermes Gateway 是 Hermes 的 API 网关服务，默认只监听本地回环 127.0.0.1。要让 QQ 机器人从外网连进来，得改一下配置，让它监听所有地址。

1.1 找到配置文件

Hermes 配置文件在这里：

~/.hermes/config.yaml

1.2 修改网关配置

这里有几个关键点要注意：

配置示例给你参考：

gateway:
  bind: 0.0.0.0:8642
  api_key: "你的API密钥"

platforms:
  qqbot:
    app_id: "你的QQ机器人AppID"
    secret: "你的QQ机器人密钥"
    enabled: true

1.3 验证配置对不对

改完配置启动网关后，用这个命令看看端口监听对不对：

ss -tlnp | grep :8642

正常结果应该显示 0.0.0.0:8642，如果只看到 127.0.0.1:8642 说明配置错了。

🤖 第二步：配置 QQ 机器人

2.1 获取 QQ 机器人凭证

去 QQ 开放平台创建好机器人之后，你会拿到两个东西：

• AppID：就是应用 ID
• Client Secret：就是应用密钥

把这两个填到 config.yaml 的 platforms.qqbot 下面就行了。

2.2 设置允许访问的用户

第一次启动网关如果提示 Unauthorized，别慌，去错误日志里就能找到你的 Open ID：

tail ~/.hermes/logs/errors.log

找到类似这行的日志，把用户 ID 抄下来：

Unauthorized request from user=87879BBBF48F24DF50EAFDC6671971E3

把这个 Open ID 放到环境变量 QQ_ALLOWED_USERS 里：

export QQ_ALLOWED_USERS="87879BBBF48F24DF50EAFDC6671971E3"

如果要允许多个用户，用逗号隔开就行。

🐛 第三步：解决启动常碰到的问题

3.1 “Image dimensions are too small” 错误

如果改完配置启动网关直接崩了，报这个错：

Image dimensions are too small

这是因为你用的模型不支持视觉功能，比如我现在用的 ark-code-latest 就不支持。解决方法很简单，在配置里把视觉辅助禁用就行了。

编辑 config.yaml，加上这段：

auxiliary:
  vision:
    enabled: false

3.2 看日志找问题

• 网关运行日志：~/.hermes/logs/gateway.log
• 错误日志：~/.hermes/logs/errors.log

⚙️ 第四步：配置 systemd 开机自动启动

要让 Hermes Gateway 开机就跑，我们给它配个 systemd 用户服务：

4.1 创建服务文件

文件路径：

~/.config/systemd/user/hermes-gateway.service

内容这么写：

[Unit]
Description=Hermes Agent Gateway
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/hermes gateway
WorkingDirectory=%h/.hermes
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

4.2 启用并启动服务

执行这几条命令：

systemctl --user daemon-reload
systemctl --user enable hermes-gateway
systemctl --user start hermes-gateway

4.3 检查运行状态

用这个命令看看跑起来没：

systemctl --user status hermes-gateway

看到 active (running) 就说明正常运行了。

🧠 第五步：导入长期记忆和自定义技能

Hermes Agent 支持持久化记忆，我们可以把之前整理好的长期记忆文件导进去，这样它就一直记得你的习惯和信息了。

5.1 从 FTP 下载记忆文件

按照我自己的操作规范，修改 /web/ 目录文件一定要先下载最新版本到本地，不能直接用旧版本覆盖云端。下载可以用 Python 脚本来做：

from ftplib import FTP
ftp = FTP('nickys.cn')
ftp.login('nicky', '密码')
with open('/tmp/MEMORY-20260421-2103.md', 'wb') as f:
    ftp.retrbinary('RETR /home/PCYUECHENG/work/20260421/MEMORY-20260421-2103.md', f.write)
ftp.quit()

5.2 保存到 Hermes 持久记忆

下载完读取文件内容，用 Hermes 的 memory 工具一条条存到用户记忆里。这样以后对话 Hermes 就能记住你的个人信息、操作习惯和各种规范了。

5.3 创建自定义技能

我习惯给常用操作做个自定义技能，比如连接 FTP，我就建了个 nickys-ftp 技能，把连接信息和操作规范都存在里面，以后用的时候直接调用就行，不用每次都输密码。

⏰ 第六步：设置定时提醒

Hermes 支持 cron 风格的定时任务，各种提醒都能设：

6.1 域名展期提醒

我自己设了两个：

• 每月 18 日早上 10:30 提醒我去 noip.com 给免费域名展期
• 2026年9月15日晚上 10:00 提醒我去 cc.cd 给自己和朋友的域名续费

创建命令类似这样：

cronjob action=create schedule="30 10 18 * *" prompt="提醒：登录 noip.com 确认 nicky.ddns.net 域名展期" name=noip-domain-renewal

6.2 每日自动备份提醒

每天晚上 11:30 提醒我执行备份，备份到本地同时传到 NAS，只发邮件摘要不发附件，省得邮箱满。

✅ 第七步：检查 QQ 机器人连接

全部配置完了，重启一下 Hermes Gateway 让配置生效：

systemctl --user restart hermes-gateway

看看进程跑起来没：

ps aux | grep hermes

正常情况下能看到两个 Hermes 进程在跑。这时候你去 QQ 给机器人发消息，它应该就能正常回复了。

✅ 今天完成的工作

今天在 Hermes Agent 上把 QQ 机器人整个配置流程走通了：

⚠️ 踩过的坑和注意事项

我把配置过程中碰到的问题整理一下，你别再踩了：

📌 总结

---

发布日期：2026-04-21 · 分类：技术文章