---
title: 将 LobeHub 连接到 QQ
description: 了解如何创建 QQ 机器人并将其连接到您的 LobeHub 代理作为消息渠道，使您的 AI 助手能够在 QQ 群聊和私聊中与用户互动。
tags:
  - QQ
  - 消息渠道
  - 机器人设置
  - 集成
---

# 将 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](https://q.qq.com)，使用您的 QQ 账号登录。

  ### 创建应用

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

  ### 复制应用凭证

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

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

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

  ![](/blog/assets276a4e8748e9bd300b30dcd9d0e24980.webp)

  ### 配置事件接收方式（仅 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）**。复制此地址用于第三步。

  ![](/blog/assetsf9317924035e48fcb1d1ae586568ea5f.webp)
</Steps>

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

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

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

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

  ### 选择事件类型

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

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

  ![](/blog/assets737e194726e134bc205a37d74eaee98e.webp)

  ### 验证回调

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

## 第四步：发布机器人

<Steps>
  ### 提交审核

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

  ### 等待审核通过

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

  ![](/blog/assets862c2fcdfd3a9e51c44c721c47e1ff5a.webp)
</Steps>

## 第五步：测试连接

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

## 填写你的平台身份（推荐）

**高级设置**里有一个可选字段影响日常使用体验，建议一开始就填好。

### 你的平台用户 ID

也就是你自己的 QQ `tiny_id`（平台级用户标识符 ——**不是**对外可见的 QQ 号，两者不一定一致），用于：

- **配对审批** — 当 **私信策略** 为 **配对审批** 时为必填项，`/approve <code>` 是属主命令，runtime 会用这个 ID 校验发起人。
- **AI 工具主动推送** — 让 Agent 能主动联系你（提醒、通知），把内部用户引用映射到你的 QQ 账号。
- **防自锁** — 自动被 **允许的用户** 信任，给好友收紧 bot 时不会把自己挡在外面。

获取方式：先用任意消息私信 bot 一次，然后在 server log 里查看入站事件 payload 中的 `tiny_id` 字段（或在 OpenAPI 控制台读取，如果有）。把那串长数字 ID 粘贴到 LobeHub 高级设置的 **你的平台用户 ID** 字段。

> QQ 没有一个稳定的 "默认服务器" 概念可让 AI 工具默认指向，因此 QQ 渠道不展示 **默认服务器** 字段。

## 将机器人添加到群聊

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

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

## 接入策略

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

### 允许的用户 ID（全局）

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

### 私信策略

- **开放 (Open)（默认）** — 任何与机器人有上下文交集的 QQ 用户都可以私信（若设置了全局白名单则受其约束）。
- **白名单 (Allowlist)** — 私信需要发送者在 **允许的用户 ID** 里。和 `Open` 的差别在白名单为空时：`Allowlist` 模式**全部拒绝**。
- **配对审批 (Pairing)** — 与 `Allowlist` 共享同一份名单，但非名单用户被拒后会收到一次性配对码，由你（属主）通过 `/approve <code>` 审批。审批通过的用户会被自动追加到 **允许的用户 ID**，后续 DM 直通。需先填 **你的平台用户 ID**（runtime 用它校验 `/approve` 发起人），并需要部署 Redis。
- **禁用 (Disabled)** — 机器人忽略所有私信，只在群聊里被 `@提及` 时回复。

### 群组策略

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

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

跨平台细节见 [渠道概览](/docs/usage/channels/overview#direct-message-policy)。

## 配置参考

| 字段             | 是否必需 | 描述                                                         |
| -------------- | ---- | ---------------------------------------------------------- |
| **应用 ID**      | 是    | 来自 QQ 开放平台的 App ID                                         |
| **App Secret** | 是    | 来自 QQ 开放平台的 App Secret                                     |
| **连接模式**       | 否    | `websocket`（默认）或 `webhook`，根据 QQ 开放平台配置选择                  |
| **允许的用户 ID**   | 否    | 逗号或空格分隔的 QQ `tiny_id`。全局闸门 — 私信和群聊 @ 都受其约束                 |
| **私信策略**       | 否    | `open`（默认）、`allowlist`、`pairing` 或 `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。
