将 LobeHub 连接到 QQ

通过将 QQ 渠道连接到您的 LobeHub 代理，用户可以通过 QQ 群聊、频道和私聊与 AI 助手互动。

前置条件

• 一个拥有有效订阅的 LobeHub 账户
• 一个 QQ 账户

连接模式

LobeHub ��持两种 QQ 机器人连接模式：

• WebSocket（推荐） — 持久连接。事件通过 WebSocket 实时推送，无需配置回调地址。这是新机器人的默认模式。
• Webhook — 无状态 HTTP ��调。如果您的机器人已在 QQ 开放平台配置了回调地址且无法切换，请使用此模式。

注意： 在 QQ 开放平台上，一旦机器人配置了 Webhook 回调地址，就无法切换到 WebSocket 模式。尚未配置回调地址的新机器人应使用 WebSocket 模式。

第一步：创建 QQ 机器人

<Steps> ### 打开 QQ 开放平台

访问 q.qq.com，使用您的 QQ 账号登录。

创建应用

在 QQ 开放平台控制台中，点击 创建机器人。填写机器人名称、描述和头像。

复制应用凭证

应用创建完成后，进入 开发设置，复制以下内容：

• App ID — 机器人的唯一标识符
• App Secret — 机器人的密钥

重要提示： 请妥善保管您的 App Secret，切勿公开分享。

配置事件接收方式（仅 Webhook 模式）

如果您使用的是 Webhook 模式，请在 QQ 开放平台中导航到 开发设置 → 回调配置。您需要在完成第二步后将 LobeHub 的回调地址粘贴到此处。

如果您使用的是 WebSocket 模式（默认），请跳过此步骤 — 无需配置回调地址。 </Steps>

第二步：在 LobeHub 中配置 QQ

<Steps> ### 打开渠道设置

在 LobeHub 中，导航到您的代理设置，然后选择 渠道 标签页。��平台列表中点击 QQ。

输入应用凭证

填写以下字段：

• 应用 ID — 来自 QQ 开放平台的 App ID
• App Secret — 来自 QQ 开放平台的 App Secret

选择连接模式

在 高级设置 中，选择 连接模式：

• WebSocket（默认）— 推荐新机器人使用
• Webhook — 适用于已在 QQ 开放平台配置了回调地址的机器人

保存配置

点击 保存配置。您的凭证将被加密并安全存储。

• 在 WebSocket 模式 下，机器人会自动连接到 QQ 网关，无需额外配置。
• 在 Webhook 模式 下，保存后将显示 回调地址（Callback URL）。复制此地址用于第三步。

</Steps>

第三步：在 QQ 开放平台配置回调（仅 Webhook 模式）

如果您使用的是 WebSocket 模式，请跳过此步骤。

<Steps> ### 粘贴回调地址

返回 QQ 开放平台，导航到 开发设置 → 回调配置。将您从 LobeHub 复制的 回调地址 粘贴到此处。

选择事件类型

订阅您的机器人需要的消息事件。常用事件包括：

• GROUP_AT_MESSAGE_CREATE — 在群聊中被 @提及时触发
• C2C_MESSAGE_CREATE — 收到私聊消息时触发
• AT_MESSAGE_CREATE — 在频道中被 @提及时触发
• DIRECT_MESSAGE_CREATE — 频道私信时触发

验证回调

QQ 开放平台将向您的回调地址发送验证请求。LobeHub 会通过 Ed25519 签名验证自动处理此请求。 </Steps>

第四步：发布机器人

<Steps> ### 提交审核

在 QQ 开放平台中，进入 版本管理 并创建一个新版本。提交机器人进行审核。

等待审核通过

QQ 会对您的机器人进行审核。审核通过后，机器人将发布并可投入使用。在沙盒测试阶段，您可以直接添加测试用户而无需发布。

</Steps>

第五步：测试连接

在 LobeHub 的渠道设置中点击 测试连接 以验证集成。然后打开 QQ，找到您的机器人并发送消息。机器人应通过您的 LobeHub 代理进行响应。

将机器人添加到群聊

要在 QQ 群聊中使用机器人：

1. 将机器人添加到 QQ 群聊中
2. 在消息中 @提及机器人以触发响应
3. 机器人将在群聊中回复

接入策略

两个独立的策略控制入站消息，默认都为 开放。

允许的用户 ID（全局）

填入 允许的用户 ID 后，所有入站消息（私信和群聊 @提及）都必须来自列表里的 QQ tiny_id。留空则不做用户级过滤。tiny_id 来自 OpenAPI 事件 payload —— 用户对外可见的 QQ 号不一定就是平台 ID。

私信策略

• 开放 (Open)（默认） — 任何与机器人有上下文交集的 QQ 用户都可以私信（若设置了全局白名单则受其约束）。
• 白名单 (Allowlist) — 私信需要发送者在 允许的用户 ID 里。和 Open 的差别在白名单为空时：Allowlist 模式全部拒绝。
• 禁用 (Disabled) — 机器人忽略所有私信，只在群聊里被 @提及 时回复。

群组策略

控制机器人会在哪些 QQ 群里响应。

• 开放 (Open)（默认） — 在机器人加入的任何群里被 @ 都响应。
• 白名单 (Allowlist) — 只在 允许的频道 ID 列出的群里响应（使用 OpenAPI 事件 payload 里的群 ID）。
• 禁用 (Disabled) — 忽略所有群聊流量，机器人只接受私信。

跨平台细节见 渠道概览。

配置参考

字段	是否必需	描述
应用 ID	是	来自 QQ 开放平台的 App ID
App Secret	是	来自 QQ 开放平台的 App Secret
连接模式	否	websocket（默认）或 webhook，根据 QQ 开放平台配置选择
允许的用户 ID	否	逗号或空格分隔的 QQ tiny_id。全局闸门 — 私信和群聊 @ 都受其约束
私信策略	否	open（默认）、allowlist 或 disabled — 控制谁可以私信机器人
群组策略	否	open（默认）、allowlist 或 disabled — 控制机器人在哪些群中响应
允许的频道 ID	否	逗号或空格分隔的 QQ 群 ID。仅在群组策略为白名单时使用

功能限制

• 不支持消息编辑 — QQ 机器人 API 不支持编辑已发送的消息。更新的回复将作为新消息发送。
• 不支持表情回应 — QQ 机器人 API 不支持表情回应功能。
• 不支持输入状态提示 — QQ 机器人 API 不提供输入状态指示器功能。
• 消息长度限制 — 超过 2000 个字符的消息将被自动截断。

故障排除

• 机器人无法连接（WebSocket 模式）： 验证 App ID 和 App Secret 是否正确。确保机��人在 QQ 开放平台上未配置回调地址 — 一旦设置了回调地址，WebSocket 模式将不可用。
• 回调地址验证失败（Webhook 模式）： 确保您已在 LobeHub 中保存配置，并正确复制了 URL。LobeHub 会自动处理 Ed25519 验证。
• 机器人未响应： 验证 App ID 和 App Secret 是否正确，机器人是否已发布（或您是沙盒测试用户），以及是否订阅了所需的消息事件。
• 群聊问题： 确保机器人已被添加到群聊中。@提及机器人以触发响应。
• 测试连接失败： 仔细检查 LobeHub 渠道设置中的 App ID 和 App Secret。