让 Hermes 在 QQ 里当你的机器人

前置：Hermes 已装好、能跑

确认 hermes doctor 正常、模型已配好。QQ 接入是网关功能，模型没配机器人不会回话。

注册应用拿 AppID / Secret

打开 QQ 开放平台：https://q.qq.com，登录后：

• 创建一个新的机器人应用
• 记下 App ID 和 App Secret（这两个就是接 Hermes 的钥匙）

开通需要的消息权限

在机器人管理后台，把要用的意图（Intents）打开：

• C2C 单聊消息（私聊机器人）
• 群聊 @ 消息（群里 @ 机器人）
• 频道消息（可选，如果要进 QQ 频道）

先在沙箱模式下测试，稳定后再申请发布上线。

装依赖 + 配置 Hermes

QQ 适配器需要两个包：

pip install aiohttp httpx

推荐用交互式向导配置（选 QQ Bot）：

hermes gateway setup

也可以手动把 AppID 和 Secret 写进 ~/.hermes/.env：

# 必填
QQ_APP_ID=你的AppID
QQ_CLIENT_SECRET=你的AppSecret
# 可选：定时任务推送目标（周报/提醒发到哪个会话）
QQBOT_HOME_CHANNEL=你的OpenID
QQBOT_HOME_CHANNEL_NAME=Home
# 私聊白名单（逗号分隔用户 OpenID）
QQ_ALLOWED_USERS=用户OpenID1,用户OpenID2
QQ_ALLOW_ALL_USERS=false

启动网关测试

前台先跑一次看日志：

hermes gateway

确认无报错后装成后台服务：

hermes gateway install
hermes gateway start
hermes gateway status

测试：在 QQ 里私聊机器人发「你好」，或拉它进群 @ 它。收到回复即成功。

进阶配置（可选）

想要更细的控制，在 ~/.hermes/config.yaml 里加：

platforms:
  qqbot:
    enabled: true
    extra:
      app_id: "你的AppID"
      client_secret: "你的Secret"
      markdown_support: true
      dm_policy: "open"        # open | allowlist | disabled
      allow_from:
        - "用户OpenID"
      group_policy: "open"
      group_allow_from:
        - "群OpenID"

语音转文字：QQ 自带免费 ASR 优先；想用智谱 GLM-ASR 等，配 stt.provider 和 key 即可。

常见问题

• 启动报 aiohttp/httpx 缺失 → 装依赖。
• 机器人不回复群消息 → 检查群意图是否开通、group_policy 是否 allowlist 但群没加白。
• 沙箱模式测试 → 设 QQ_PORTAL_HOST=sandbox.q.qq.com 走沙箱路由。
• 语音没转文字 → 检查 STT 配置，或确认消息里带 QQ 自带 ASR 文本。