1. Hermes Agent 接入 QQ 的完整链路与踩坑场景Hermes Agent 是一个可自我成长、长记忆、跨平台的 AI 智能体框架它能自主创建技能并在使用中不断改进越用越聪明。而 QQ 接入这件事本质上是把 Hermes Agent 的对话能力挂到 QQ 开放平台的机器人通道上让你在私聊窗口或群聊 里直接调用智能体写代码、读文件、做总结、跑自动化任务。适合谁适合已经装好 Hermes Agent、配好了大模型 APIDeepSeek、Kimi、MiniMax、OpenAI 等但卡在“机器人灵魂不在线”这一步的开发者。我自己第一次配的时候机器人加进 QQ 消息列表后发消息收到的提示是“该机器人的‘灵魂’不在线请检查它的主机服务部署环境”。这句话看着吓人其实只是 AppID 和 AppSecret 还没写进 Hermes 的网关配置里。整条链路可以拆成四段QQ 开放平台创建机器人拿凭证、Hermes 终端跑hermes gateway setup写网关、启动网关并做配对授权、最后用一条消息往返验证 QQ 侧能收到智能体回复。这里有个容易混淆的点很多人以为要公网 IP、要域名备案、要自己写回调校验。实际上 Hermes Agent 的 QQ 网关走的是长连接模式你本地或内网服务器只要能正常访问网络就能跑不需要暴露端口。但“不需要公网”不等于“不需要配置”AppID、AppSecret、网关地址、模型 Base URL 这几项一个都不能少。下面我会把每一步的命令、配置片段、验证动作和真实报错都摊开讲你照着做基本能在十几分钟内打通。另外提醒一句QQ 开放平台的 AppSecret 只显示一次忘记只能重置。我建议拿到之后立刻存进密码管理器别像我一样截图完就关页面后面重置了一次才找回来。2. TaoToken 前置把模型网关和 Key 准备好Hermes Agent 本身不产出模型能力它是个调度壳真正回你消息的是背后的大模型。所以在你动 QQ 配置之前先把模型侧的 Base URL、API Key、Model ID 这三件套准备好。我这边统一用 TaoToken 做模型网关原因是它同时兼容 OpenAI 风格和 Anthropic 风格的接口Hermes 里换模型只要改 Model IDBase URL 不用动。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。这个 Key 就是后面配置里的api_key字段。注意不要把它提交到 GitHermes 的配置文件一般在用户目录下权限设成 600 比较稳妥。Base URL 填https://taotoken.net/api注意这里不带任何查询参数。如果你用的是 Claude Code 或 Anthropic SDK 风格的调用Base URL 也是同一个TaoToken 会自动识别路径。Model ID 按你实际要用的填比如claude-sonnet-4-5、gpt-4o、deepseek-chat这类具体以控制台模型列表为准。如果你还没决定用哪个模型可以先到 https://taotoken.net/models 看一眼可用列表再决定 Model ID。想先验证 Key 能不能通最直接的办法是去 https://taotoken.net/chat 发一句话能正常回就说明 Key 和网关都没问题。这一步别跳过因为后面 QQ 不回复时你要能区分是模型侧挂了还是 QQ 网关挂了。对于长期跑编码任务或 Agent 自动化的场景可以考虑 Coding Plan额度更稳适合 Hermes 这种会持续调用模型的智能体。配置入口在 https://taotoken.net/coding-plan 。把模型侧跑通之后我们再进 QQ 开放平台。3. 可复制配置AppID、AppSecret 与网关地址填写位置这一节是核心我把 QQ 开放平台拿到的凭证和 Hermes 网关配置的对应关系写清楚。先创建机器人打开 QQ 开放平台 https://q.qq.com/qqbot/openclaw/login.html 用手机 QQ 扫码登录点“创建机器人”系统会自动生成机器人账号。创建完成后记录两个值AppID 和 AppSecret。AppSecret 只显示一次务必保存。回到 QQ 软件你会看到新建的机器人已经进了消息列表还会发一条欢迎消息。此时发消息会提示“灵魂不在线”这是正常的因为 Hermes 还没绑定。接下来进 Hermes 终端执行hermes gateway setup方向键选择QQ Bot回车确认。然后依次输入 Bot ID / AppID 和 AppSecret。访问策略直接回车用默认的 DM 配对审批即可主频道 OpenID 留空回车。最后问“重启网关以应用更改”输入y。配置写完后Hermes 会在配置目录生成网关配置文件。以常见的 TOML 结构为例内容大致如下路径以你本机实际为准通常在~/.hermes/gateway.toml或项目下的config/gateway.toml[gateway.qqbot] enabled true app_id 你的AppID app_secret 你的AppSecret access_policy dm_pairing main_channel_openid [model] base_url https://taotoken.net/api api_key 你的TaoToken Key model_id claude-sonnet-4-5如果你更习惯 JSON 结构等价写法是{ gateway: { qqbot: { enabled: true, app_id: 你的AppID, app_secret: 你的AppSecret, access_policy: dm_pairing, main_channel_openid: } }, model: { base_url: https://taotoken.net/api, api_key: 你的TaoToken Key, model_id: claude-sonnet-4-5 } }这里三件套必须齐全Base URL 填https://taotoken.net/apiKey 填你刚创建的Model ID 填你要用的模型。少任何一个QQ 侧都会表现为“不回复”或“灵魂不在线”。配置改完记得重启网关hermes gateway restart注意AppSecret 不要带空格复制时容易多一个换行导致鉴权失败。粘贴后建议用cat -A看一眼有没有多余字符。4. 验证请求一条消息往返确认 QQ 侧收到回复配置写完先看网关状态hermes gateway status看到Gateway started说明网关起来了。如果没起来直接跑hermes gateway前台启动能看到实时日志方便排错。启动成功后回到 QQ私聊机器人发一句话比如“你好帮我总结一下这段话”。第一次对话时Hermes 会提示需要配对授权日志里会给一个配对码类似KZ****。执行hermes pairing approve qqbot KZ****授权完成后再发一条消息这次应该能收到智能体回复。群聊场景则是 机器人 提问Hermes 会自动调用能力并记忆上下文。验证成功的标志有三个QQ 侧收到回复文本、Hermes 日志里出现模型请求和响应记录、hermes gateway status显示连接正常。如果只收到“灵魂不在线”说明 AppID/AppSecret 没写对或网关没重启如果收到“模型调用失败”说明 Base URL 或 Key 有问题回到 TaoToken 侧检查。我实测下来一条消息往返的完整链路是QQ 客户端 → QQ 开放平台 → Hermes 网关长连接 → Hermes 调度模型 → TaoToken 网关 → 模型返回 → 原路回传 QQ。任何一环断了都会表现为不回复所以排错要按这个顺序逐段确认。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错讲。第一个高频错误是401 Unauthorized通常出现在模型调用阶段原因是 TaoToken Key 填错或过期。检查api_key字段确认没有多余空格必要时到 https://taotoken.net/api-keys 重新生成一个。如果 Key 没问题看 Base URL 是不是写成了带路径的形式正确值是https://taotoken.net/api。第二个是local proxy failed这个多半是本地网络或网关端口冲突。先hermes gateway restart如果还不行检查是否有其他进程占用网关端口。注意这里不要引入任何网络代理工具Hermes 直连即可。第三个是reading choices相关报错比如error reading choices field这通常是模型返回结构不符合预期原因可能是 Model ID 填了一个不存在的模型或者 Base URL 指向了不兼容的端点。确认 Model ID 在 TaoToken 控制台模型列表里存在Base URL 用标准值。第四个是OAuth相关报错出现在 QQ 开放平台鉴权阶段比如OAuth failed或invalid app_secret。这说明 AppSecret 不对或者 AppID 和 AppSecret 不匹配。AppSecret 只显示一次如果你重置过必须把新值重新写进网关配置并重启。还有一个隐蔽的坑群聊 无响应。先确认机器人已加入群组再确认群聊场景下访问策略是否允许。DM 配对审批模式下群聊可能需要额外授权。最后如果提示依赖缺失执行pip install aiohttp httpx装完重启网关。把这几类报错对照一遍基本能覆盖 90% 的接入问题。6. 语义一致 CTA继续用 TaoToken 打通你的智能体QQ 侧打通之后Hermes Agent 的记忆和技能会随着对话积累越来越强这时候模型调用的稳定性就变得更重要。如果你打算长期跑编码任务或 Agent 自动化建议把模型侧统一收敛到 TaoTokenBase URL 固定https://taotoken.net/api换模型只改 Model ID网关配置不用动。需要继续接入其他通道或排查模型侧问题可以从接入文档入手https://taotoken.net/doc 。想先验证某个模型在 Hermes 里的表现直接到 https://taotoken.net/chat 发几条消息试试。长期编码和 Agent 场景走 Coding Planhttps://taotoken.net/coding-plan 。Key 管理在 https://taotoken.net/api-keys 控制台在 https://taotoken.net/console 。最后留一个实用技巧Hermes 的网关日志会记录每次模型请求的耗时和 token 用量跑一段时间后回看日志能发现哪些技能调用最频繁据此调整 Model ID 或访问策略比盲目换模型有效得多。
