Hermes Agent怎么接入QQ？详细接入步骤指南

Hermes Agent是由Nous Research开发的“自进化”开源AI智能体框架，能从任务中自动提炼技能、跨会话持久记忆用户偏好，越用越懂你。接入QQ的核心价值在于：让你在国内用户基数最大的即时通讯平台上，拥有一个7×24小时在线、会自我成长、能处理复杂任务的AI数字助手。

本文大纲

👉 一、接入前的关键信息：官方已原生支持
👉 二、第一步：在QQ开放平台创建Bot并获取凭证
👉 三、第二步：在Hermes Agent中配置QQ Bot
👉 四、第三步：启动Gateway并测试
👉 五、高级配置：精细化权限与语音消息
👉 六、常见问题与排障指南
👉 七、企业级延伸：实在Agent——从“个人助手”到“数字员工”
👉 总结

图源：AI生成示意图

一、接入前的关键信息：官方已原生支持

2026年4月16日，腾讯QQ正式宣布，QQ Bot插件已正式合入Hermes Agent官方文档。这意味着你无需任何第三方桥接工具或社区适配方案，直接在Hermes Agent的Messaging Platforms配置中选择QQ Bot通道即可。

接入后支持的消息类型：文字、语音、图片等消息类型收发，更多消息类型和通道能力正在迭代中。Hermes Agent的QQ Bot适配器通过QQ官方Bot API（v2）实现，支持私聊（C2C）、群聊@提及、频道消息和语音消息转写。

实现原理简述：适配器通过WebSocket长连接持续接收QQ网关推送的消息，通过REST API发送回复，并自动下载和处理图片、语音、文件等附件。

二、第一步：在QQ开放平台创建Bot并获取凭证

首先，你需要在QQ开放平台注册一个Bot应用，获取接入所需的App ID和App Secret。

1. 登录QQ开放平台：访问 https://q.qq.com，使用你的QQ账号登录。
2. 创建Bot应用：点击“创建应用”，填写应用名称、描述等信息，完成注册。
3. 获取凭证：创建成功后，在应用详情页记录下 App ID 和 App Secret（密钥），这两个凭证将在Hermes Agent侧配置时使用。
4. 启用必需的Intents：在QQ开放平台的机器人设置中，至少开启以下事件订阅权限：
   • C2C消息：私聊消息接收
   • 群聊@消息：群内被@时接收消息
   • 频道消息：QQ频道内的消息（可选）
5. 选择沙箱模式或发布：测试阶段建议使用沙箱模式，仅允许指定测试用户与Bot对话；正式上线前需提交审核并发布。

三、第二步：在Hermes Agent中配置QQ Bot

凭证准备好后，在Hermes Agent侧完成对接配置。官方提供了交互式和手动两种配置方式。

方式一：交互式配置（推荐）

运行以下命令启动Gateway配置向导：

hermes setup gateway

在平台列表中使用方向键选择 QQ Bot，按照提示依次填入App ID和App Secret，保存即可。

方式二：手动配置环境变量

在 ~/.hermes/.env 文件中添加以下内容：

QQ_APP_ID=your-app-id
QQ_CLIENT_SECRET=your-app-secret

💡 提示：输入App Secret时屏幕不会显示任何字符，直接粘贴后按回车即可。密钥会被安全保存在 ~/.hermes/.env 中，权限自动设为0600（仅所有者可读写）。

四、第三步：启动Gateway并测试

配置完成后，启动Gateway服务并测试连接。

1. 安装依赖：QQ Bot适配器需要 aiohttp 和 httpx 两个Python包，运行以下命令安装：

   pip install aiohttp httpx

2. 启动Gateway：

   hermes gateway start

   如果希望在前台运行以便观察日志，可使用 hermes gateway run。

3. 测试连接：在QQ App中搜索你的Bot名称，发送一条消息（如“你好”）。如果一切正常，Bot应该能够流式回复。

📌 沙箱模式提醒：如果Bot处于沙箱模式，它只能接收来自QQ指定测试通道的消息，无法响应普通用户的私聊或群聊。如需对外使用，请在QQ开放平台提交审核并发布。

五、高级配置：精细化权限与语音消息

5.1 访问控制：DM与群聊权限管理

为适应不同使用场景，Hermes Agent提供了精细化的访问控制配置，可通过 ~/.hermes/config.yaml 文件进行调整：

platforms:
  qq:
    enabled: true
    extra:
      app_id: 'your-app-id'
      client_secret: 'your-secret'
      markdown_support: true
      dm_policy: 'open'        # open | allowlist | disabled
      allow_from:              # 当dm_policy为allowlist时，填写允许的用户OpenID
        - 'user_openid_1'
      group_policy: 'open'     # open | allowlist | disabled
      group_allow_from:        # 当group_policy为allowlist时，填写允许的群OpenID
        - 'group_openid_1'

策略说明：

5.2 定时任务与通知推送

通过设置 QQ_HOME_CHANNEL 环境变量，可以指定一个默认的接收渠道，用于Cron定时任务和系统通知的推送：

QQ_HOME_CHANNEL=your-channel-openid
QQ_HOME_CHANNEL_NAME=我的工作频道

5.3 语音消息转文字（STT）

Hermes Agent支持将QQ语音消息自动转写为文字，采用两阶段处理：

1. QQ内置ASR（免费）：优先使用腾讯自带的语音识别能力，语音消息附件中会包含 asr_refer_text 字段。
2. 自定义STT提供商（备用）：如果QQ内置ASR未返回文本，适配器会调用OpenAI兼容的STT API。默认使用智谱GLM-ASR，也可配置OpenAI Whisper等其他服务。

在 ~/.hermes/.env 中配置STT：

QQ_STT_API_KEY=your-stt-api-key
QQ_STT_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4
QQ_STT_MODEL=glm-asr

或在 config.yaml 中配置：

stt:
  provider: 'zai'       # zai (GLM-ASR), openai (Whisper), etc.
  baseUrl: 'https://open.bigmodel.cn/api/coding/paas/v4'
  apiKey: 'your-stt-key'
  model: 'glm-asr'

六、常见问题与排障指南

• 🔧 Q1：Bot刚连接上就断开？
  可能原因及解决方案：检查凭证是否正确，确保已在QQ开放平台启用必需的Intents，沙箱模式下的Bot只能接收测试通道消息。
• 🔧 Q2：语音消息无法转文字？
  排查步骤：检查语音消息附件中是否包含 asr_refer_text；验证 QQ_STT_API_KEY 设置；查看Gateway日志。
• 🔧 Q3：消息无法送达？
  排查步骤：检查Intents设置；检查 QQ_ALLOWED_USERS 访问限制；群聊需确保Bot被@提及；检查 QQ_HOME_CHANNEL 配置。
• 🔧 Q4：连接报错或网络不通？
  排查步骤：确保 aiohttp 和 httpx 已安装；检查网络连通性；查看日志获取重连行为。

七、企业级延伸：实在Agent——从“个人助手”到“数字员工”

Hermes Agent为个人开发者和AI爱好者提供了灵活、低成本的QQ接入方案，但如果你需要将AI能力真正融入企业核心业务流程——比如自动处理ERP订单、审核财务单据、跨系统同步数据——一个更专注于企业级应用的平台会更为合适。

实在Agent是实在智能推出的企业级AI智能体平台，融合了自研的TARS大模型（大脑）、ISSUT智能屏幕语义理解技术（眼睛） 和 RPA自动化引擎（手脚），形成“思考-感知-执行”三位一体架构。其核心差异化在于：

• 不依赖API的“眼睛”：企业大量老旧内网系统、ERP软件没有标准API接口。实在Agent的ISSUT技术通过计算机视觉识别屏幕上的按钮、输入框和表格，无论软件多陈旧，都能实现非侵入式的无缝操作。
• 企业级安全与稳定：全面适配信创环境，支持私有化部署，具备全链路可溯源审计能力，7×24小时全天候稳定运行。
• 全行业全场景深耕：深度覆盖跨境、制造、电商、金融等全行业，可落地财务智能审核、供应链管理、HR入离职办理等数百种高复杂度真实业务场景。

目前，实在Agent已服务超5000家企业，包括华电华南、中航光电等头部客户，实现财务审核92个业务类型全覆盖、66%初审工作替代率，年处理单据超25万笔。

总结

Hermes Agent接入QQ的流程可归纳为“三步走”：QQ开放平台创建Bot获取App ID和App Secret → 运行 hermes setup gateway 选择QQ Bot并填写凭证 → 启动Gateway并在QQ中测试。整个过程基于官方原生支持的QQ Bot插件，无需任何第三方工具，配置约5-10分钟即可完成。接入后，你可以在QQ中与Agent进行文字、语音、图片等多种形式的交互，并通过高级配置实现精细化的权限管理和定时任务推送。

如果你想把Hermes Agent这类AI智能体的能力，从“个人聊天助手”升级为能真正融入企业业务流程的“数字员工”——让AI替你操作ERP、审核财务单据、跨系统同步数据——不妨了解一下「实在Agent」。它将大模型的思考力与RPA的执行力深度融合，为AI提供了一个可靠、可配置、可信赖的企业级行动底座。