企业官网建设流程全解析

1. Hermes Agent 接入 QQ 的完整链路与踩坑场景

Hermes Agent 是一个可自我成长、长记忆、跨平台的 AI 智能体框架，它能自主创建技能并在使用中不断改进，越用越聪明。而 QQ 接入这件事，本质上是把 Hermes Agent 的对话能力挂到 QQ 开放平台的机器人通道上，让你在私聊窗口或群聊 @ 里直接调用智能体：写代码、读文件、做总结、跑自动化任务。适合谁？适合已经装好 Hermes Agent、配好了大模型 API（DeepSeek、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 ID，Base URL 不用动。

先拿 Key。打开 https://taotoken.net/api-keys ，登录后创建一个 API Key，复制出来。这个 Key 就是后面配置里的api_key字段。注意不要把它提交到 Git，Hermes 的配置文件一般在用户目录下，权限设成 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/api，Key 填你刚创建的，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 自动化，建议把模型侧统一收敛到 TaoToken，Base URL 固定https://taotoken.net/api，换模型只改 Model ID，网关配置不用动。

需要继续接入其他通道或排查模型侧问题，可以从接入文档入手：https://taotoken.net/doc 。想先验证某个模型在 Hermes 里的表现，直接到 https://taotoken.net/chat 发几条消息试试。长期编码和 Agent 场景走 Coding Plan：https://taotoken.net/coding-plan 。Key 管理在 https://taotoken.net/api-keys ，控制台在 https://taotoken.net/console 。

最后留一个实用技巧：Hermes 的网关日志会记录每次模型请求的耗时和 token 用量，跑一段时间后回看日志，能发现哪些技能调用最频繁，据此调整 Model ID 或访问策略，比盲目换模型有效得多。