配置通道 - QQ | LightVela

摘要

QQ 通道支持两种接入方式：扫码授权，或在 QQ 开放平台创建机器人后拿到 AppID 与 AppSecret 填回 LightVela 管理台的「通道」卡片，后者整个过程约 5–10 分钟。准备工作是一个作为机器人管理员的 QQ 账号，以及完成模型配置（或直接使用套餐自带的模型积分）。国内站五个通道中，微信、企业微信、飞书为扫码授权，QQ 与钉钉则可扫码或填写应用凭证。接入完成后即可在 QQ 里与 Hermes Agent 对话，且它与其他通道共享同一份人格与长期记忆。

QQ 通道可直接按管理台提示扫码连接，也可在 QQ 开放平台创建机器人后使用 App ID 与 App Secret 手动绑定。只有选择手动绑定时，才需要事先取得这两个凭证。

本页覆盖

用 QQ 扫描管理台二维码连接，或选择手动绑定
手动绑定时，在 QQ 开放平台注册并创建机器人
手动绑定时获取 App ID 与 App Secret
手动绑定时在 LightVela 填入参数完成接入
在 QQ 中与 Hermes Agent 进行对话

扫码连接

1. 进入管理台

2. 选择 QQ 扫码方式

找到 QQ 通道卡片，点击 + 连接，在「选择 QQ 连接方式」中选择 扫码连接，再点击 下一步。按页面提示用 QQ 扫描二维码并完成授权。

扫码后确认 QQ 卡片显示 已连接，再按下文验证消息收发。若扫码方式不可用，可选择手动绑定。

手动绑定已有 QQ 机器人

手动绑定时，在 QQ 卡片点击 + 连接，选择 App ID / Secret 绑定，再按以下步骤准备并填入凭证。

手动绑定 QQ 机器人的 App ID 和 App Secret 表单

1. 注册 QQ 开放平台

访问 QQ 开放平台，使用手机 QQ 扫描页面上的二维码进行注册/登录。首次访问时，扫码后系统会自动完成注册，并将当前 QQ 与开放平台账号绑定。

在手机 QQ 扫码后选择同意，即完成注册，进入 QQ 机器人配置页。

2. 创建 QQ 机器人

在 QQ 开放平台的机器人页面，点击「创建机器人」新建一个 QQ 机器人。

3. 获取 App ID 与 App Secret

机器人创建完成后，在页面中找到 AppID 与 AppSecret，分别点击右侧「复制」按钮，保存到本地记事本或备忘录。

创建完成后，QQ 中会自动添加该机器人至消息列表，并发送第一条欢迎消息。此时尚未完成与 LightVela 的绑定，发送消息会收到"该机器人去火星了，稍后再试吧"——属于正常现象，继续下一步即可。

4. 在 LightVela 填入参数

回到管理台的「连接 QQ」弹窗，将刚才复制的参数依次粘贴到输入框：

AppID：粘贴已复制的 AppID
AppSecret：粘贴已复制的 AppSecret

5. 点击「绑定 QQ 机器人」

LightVela 使用上述凭证连接 QQ 开放平台上的机器人，等待几十秒后页面提示保存成功，「已接入通道」列表中新增"QQ"记录。

验证 QQ 消息收发

回到 QQ，找到刚连接的机器人，发送消息：

你好

几秒内收到 Hermes Agent 回复。

QQ 卡片显示 已连接 后，还可点击测试，再到 QQ 确认收到来自 LightVela 的测试消息。页面提示“测试消息已发送”只表示发送命令被接受，不能证明 QQ 侧已收到；随后从 QQ 向机器人发送“你好”，确认 Agent 能回复。

如果测试消息未到达，检查当前 Bot、QQ 连接和手动绑定凭证，必要时重新连接；测试消息到了但没有回复时，检查模型与积分，并查看诊断中心。

✅ 支持 QQ 群聊 @ 对话

QQ 绑定成功后，LightVela 会默认开启 Hermes 的 QQ 群聊策略。将机器人加入 QQ 群后，群成员 @ 机器人即可发起对话。当前默认策略为 open，表示机器人所在 QQ 群内的成员都可以 @ 它对话；普通未 @ 的群消息不会作为对话触发。

成功状态

扫码授权已完成，或手动绑定的 QQ 机器人已创建
在 QQ 卡片确认显示 已连接，再从该平台发送测试消息。
QQ 中的机器人能以 AI 方式正常回复消息
QQ 群内 @ 机器人时能收到 Hermes Agent 回复

支持的消息类型

接入成功后，QQ 机器人除了能够接收、回复基础文本信息外，还支持更多消息类型，详情如下：

QQ 机器人支持的消息类型和功能	是否支持
接收文本信息	✅ 已支持
接收图片	✅ 已支持
接收文件	✅ 已支持
接收语音消息	✅ 已支持
回复文本信息	✅ 已支持
回复图片	✅ 已支持
回复文件	✅ 已支持
回复内容支持 Markdown 格式	✅ 已支持
主动发送消息（如定时发送提醒）	✅ 已支持
历史消息引用	❌ 暂不支持

常见问题

现象	可能原因	处理方式
机器人回复"我的'灵魂'不在线，请检查你的主机服务部署环境"	未在 LightVela 配置 AppID/AppSecret，或凭证错误	重新复制 QQ 开放平台的参数，确认首尾无空格后在 LightVela 重新填入
机器人回复"该机器人去火星了，稍后再试吧"	QQ 机器人已创建但尚未与 LightVela 绑定	按本页流程完成 AppID/AppSecret 的配置
完成所有配置后机器人仍不回复	模型未配置或体验积分耗尽	检查「管理 → 模型」中的主模型及检测结果
找不到 AppSecret	AppSecret 仅在创建时可见	在 QQ 开放平台点击「重置密钥」生成新值，再在 LightVela 重新填入
AppSecret 泄露	—	前往 QQ 开放平台「重置密钥」，并在 LightVela 重新填入新的 AppSecret
二维码过期	超过有效期未扫码	关闭弹窗，重新点击「连接」

通道说明

消息类型：支持文本、图片、文件、语音等多种类型，详见上方「支持的消息类型」
群聊支持：绑定后默认开启群内 @ 对话；当前控制台使用 open 策略，允许机器人所在 QQ 群内成员 @ 它对话。需要收敛到指定群时，请在 Hermes 实例配置中切换到 allowlist 并维护允许列表；通道卡片暂不提供该开关
凭证管理：AppSecret 仅在创建时明文可见，遗失或泄露需重置

下一步

配置通道 - 微信 — 日常个人场景，扫码即用
配置通道 - 飞书 — 办公场景，支持多人共享
配置技能 — 扩展 Hermes Agent 能力

配置通道 - QQ

本页目录