Hermes Agent接入消息平台
Hermes Agent 是一个支持多平台交互的开源 AI Agent 系统。它通过统一的 Messaging Gateway 接入不同的消息平台，让用户能够在日常使用的聊天应用中与 Agent 交互，并复用 Hermes 的意图理解、工具调用、Skill 执行和记忆管理等能力。
目前，Hermes 官方文档列出了 27+ 个消息平台及相关集成渠道，主要包括：
- 海外即时通信平台：Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、LINE、SimpleX。
- 国内办公与社交平台：QQ Bot、飞书（Feishu/Lark）、钉钉（DingTalk）、企业微信（WeCom）、微信（Weixin）、腾讯元宝（Yuanbao）。
- 企业协作平台：Microsoft Teams、Google Chat。
- 其他消息与通知渠道：Email、SMS、ntfy、Home Assistant、BlueBubbles（iMessage）、Webhooks 等。
- 其他集成入口：Microsoft Graph Webhook、Microsoft Teams Meetings、Open WebUI 等
本文以 QQ Bot 为例，介绍如何将 Hermes Agent 接入 QQ。整个过程并不是简单地把 QQ 消息转发给大模型，而是新增一条消息平台适配链路：QQ 负责消息入口和出口，Hermes Gateway 负责平台连接、事件分发与 Agent 调度，Agent 负责实际任务执行。
本文基于 Docker 部署的 Hermes Agent，结合实际操作和容器内源码，梳理 QQ Bot 的配置、适配器初始化、Token 认证、WebSocket 连接与故障排查流程。
整体架构：从 QQ 消息到 Agent 回复
Hermes 的 QQ 适配器使用官方 QQ Bot API v2。根据本次检查的源码，入站事件通过 WebSocket 接收，出站消息通过 REST API 发送。
里有三个需要重点理解的组件：
- QQAdapter：负责 QQ 协议交互，包括获取 Token、建立 WebSocket 连接、处理入站事件和发送消息。
- GatewayRunner：负责平台适配器的注册、生命周期管理，以及消息向 Agent 执行流程的分发。
- Agent 执行循环：接收消息后，根据模型决策调用可用工具或 Skill，完成任务后返回结果。
因此，接入 QQ 不需要重写 Agent 核心逻辑。只要平台适配器能够将 QQ 消息转换为 Hermes 的统一消息事件，并将 Agent 回复发送回 QQ，就能复用现有的 Agent 能力。
通过 hermes gateway setup 配置 QQ Bot
完成 Hermes 的基础配置和模型验证后，就可以通过官方提供的交互式向导配置消息平台。
hermes gateway setup如果 Hermes 部署在 Docker 容器中，可以在宿主机执行：
docker exec -it hermes-agent /opt/hermes/.venv/bin/hermes gateway setup该命令用于配置消息平台，不是重新配置大模型，也不是安装 Skill。Hermes 会展示平台菜单、当前配置状态，并在配置结束后提示启动或重启 Gateway。
配置 QQ Bot
获取 AppID 和 AppSecret
首先在 QQ 开放平台 创建或进入机器人应用，获取对应的 AppID 和 AppSecret。
确认容器内的配置文件
本次部署中，Hermes 的数据目录是 /opt/data，凭证保存在：
/opt/data/.env需要注意，容器里的 .env 文件和 Docker 启动时注入的环境变量并不是一回事。Hermes 会在自身启动流程中加载 dotenv 文件；单独执行 docker exec ... python3 启动的进程，并不一定会自动加载该文件。
因此，检查独立进程的 os.environ，不能直接证明 Gateway 进程读取到的值是什么。
配置环境变量
在 /opt/data/.env 中配置：
QQ_APP_ID=你的_APPID
QQ_CLIENT_SECRET=你的_APPSECRET可以使用脚本修改文件，但要注意三个问题：
- 同一个变量只保留一条有效配置，避免重复项造成维护和排查困难。
- 修改前备份文件，并将权限限制为当前部署所需的最小范围。
Hermes 如何加载并启用 QQ 平台
环境变量如何进入配置
相关文件：
/opt/hermes/hermes_cli/env_loader.py
/opt/hermes/gateway/config_env.py
/opt/hermes/gateway/config.py在 gateway/run.py 的启动流程中，Hermes 会调用 load_hermes_dotenv() 加载环境配置。env_loader.py 负责读取 .env 等配置来源；config_env.py 则负责将环境变量映射到 Gateway 的平台配置。
QQ 对应的映射定义位于 config_env.py 的 _ENV_STEPS 配置中，核心结构为：
_Cred(
Platform.QQBOT,
(("QQ_APP_ID", "QQ_CLIENT_SECRET"),),
optional=(
("app_id", "QQ_APP_ID"),
("client_secret", "QQ_CLIENT_SECRET"),
),
then=_qq_home,
)这里的 optional 表示把存在的环境变量映射到平台配置的 extra 字典中。_Cred 还会通过 _enable_from_env() 处理平台启用逻辑。
需要注意：这段定义中的凭证分组允许候选变量中的任意一个满足启用分支的条件，并不等于它已经验证了两个凭证都有效。真正建立 QQ 连接时，AppID 和 AppSecret 仍然都必须可用。
PlatformConfig 的 from_dict() 会将平台配置中的非固定字段归入 extra，而 QQ 适配器正是通过 config.extra 读取这些参数。
QQAdapter 如何被注册
核心文件：
/opt/hermes/gateway/run.py在 _BUILTIN_ADAPTERS 中，QQ 平台注册关系为：
Platform.QQBOT: (
"qqbot",
"QQAdapter",
"check_qq_requirements",
"QQBot: aiohttp/httpx missing or QQ_APP_ID/QQ_CLIENT_SECRET not configured",
)Gateway 通过这个注册表找到 QQ 适配器，并检查它所需的依赖。
QQ 适配器的实现文件是：
/opt/hermes/gateway/platforms/qqbot/adapter.py初始化时，适配器会优先读取平台配置中的 extra.app_id 和 extra.client_secret；如果对应值不存在，再通过 _resolve_qq_secret() 解析环境或当前 Profile 的密钥。
这意味着，排查凭证问题时不能只看 .env 文件，还要确认最终进入适配器的值来自哪里。
platform_toolsets 的作用
本次配置中已经存在：
platform_toolsets:
qqbot: [hermes-qqbot]它控制的是 QQ 平台上 Agent 可以使用的工具集合，而不是 QQ 连接本身。
可以将这几个概念区分开：
- 凭证配置：决定是否具备访问 QQ API 的必要信息。
- 平台启用和适配器注册：决定 Gateway 是否尝试启动 QQ 通道。
platform_toolsets：决定 QQ 对话中的 Agent 可以使用哪些工具。
三者共同影响接入结果，但不能互相替代。
测试验证
