QQ 机器人接入

这篇教程将手把手教你如何把 Hermes Agent 接入 QQ，让它能陪你聊天、处理消息，甚至听懂语音。

准备工作：像“开店”一样申请材料

在开始之前，你需要先“开个店”——在 QQ 开放平台申请一个机器人“营业执照”。

第 1 步：申请 QQ 机器人应用

1. 访问 q.qq.com 并注册登录。
2. 点击“创建应用”，记下系统给你的 App ID 和 App Secret（这相当于你的店铺账号和密码，非常重要）。
3. 在“权限管理”里，勾选你需要的“服务项目”：私聊消息、群 @ 消息、频道消息等。记得开启“消息接收”的开关，否则机器人会“失聪”。
4. 建议先在“沙箱模式”下测试，就像店铺试营业，只有你能看到。

第 2 步：安装“搬运工”依赖

Hermes 需要两个小工具来搬运消息，打开终端（命令行）输入：

pip install aiohttp httpx

配置机器人：两种“装修”方式

方式一：懒人自动配置（推荐）

在终端运行：

hermes gateway setup

然后从列表里选择 QQ Bot，跟着提示输入你的 App ID 和 App Secret 即可，就像用向导装修房子。

方式二：手动配置（更灵活）

用文本编辑器打开（或新建）~/.hermes/.env 文件，填入：

QQ_APP_ID=你的App ID
QQ_CLIENT_SECRET=你的App Secret

如果你想更精细地控制（比如只允许特定好友私聊），可以在 ~/.hermes/config.yaml 里进行高级设置，例如：

platforms:
  qqbot:
    enabled: true
    extra:
      app_id: "你的App ID"
      client_secret: "你的App Secret"
      dm_policy: "allowlist"  # 只允许白名单用户私聊
      allow_from:
        - "用户OpenID"

听懂语音：免费“翻译官”与备用“同传”

QQ 机器人自带一个免费的语音转文字“翻译官”（腾讯 ASR），它会在你收到语音时自动附上文字。如果它没听清，Hermes 会调用你配置的备用“同传”——默认是智谱的 glm-asr 模型，你也可以换成 OpenAI Whisper 等。一般默认配置就够用，无需额外设置。

常见问题“急救箱”

• 机器人一连接就掉线？ 检查 App ID/Secret 是否填错，或者机器人是否还在沙箱模式（沙箱模式只能收到测试消息）。
• 语音转不了文字？ 先看日志里有没有报错，再检查 QQ_STT_API_KEY 是否配置正确。
• 消息收不到？ 去 q.qq.com 检查“消息接收”的开关是否打开，或者私聊权限是否被限制。

小结与下篇预告

到这里，你的 QQ 机器人已经“活”起来了！它现在能接收消息、回复文字，甚至听懂语音。核心就是三步：申请应用、配置密钥、启动网关。

下篇预告：机器人光会聊天可不够，下一篇我们将介绍如何给 Hermes 接入飞书，让它成为你团队里的“智能助理”，敬请期待！