
> 你可以把本文章发给 Workbuddy、Codex等Agent帮你完成搭建
> ADP 发布渠道还没有支持QQ，所有本篇文章使用 Napcat QQ 第三方框架实现

![ScreenShot_2026-06-25_101301_202.png](https://developer.qcloudimg.com/http-save/yehe-12417104/8dbd5989884e3a9f399b8c6bcea8b4da.png)

## 一、架构：ADP提供AI能力，QQ群中对话，需要一个 bridge

ADP 把智能体的对话能力做成了开放 API（[SSE 流式](https://cloud.tencent.com/document/product/1759/129202) ）。你在控制台把应用发布到正式环境，拿到 AppKey，就能通过 `https://wss.lke.cloud.tencent.com/adp/v2/chat` 调它——传一条 `user_query` 字符串，流式返回回复文本。

QQ 这边，官方没有给个人开发者用的「机器人收发消息」开放接口，社区有一层协议端来填这个空。NapCatQQ（[NapNeko/NapCatQQ](https://github.com/NapNeko/NapCatQQ)）是其中比较活跃的一个：基于 NTQQ 实现的 OneBot v11 协议端，9.6k star，TypeScript 写的，更新很勤。它对外暴露标准 OneBot v11 接口——HTTP 服务器收消息、反向 WebSocket 推事件。

中间那段把两边对接起来的消息转发服务，就是 bridge。完整链路：

```
QQ消息 → NapCat(反向WS) → bridge(FastAPI) → ADP v2 chat(SSE) → bridge攒齐回复 → NapCat(HTTP) → QQ
```

三段职责：

| 环 | 谁来做 | 干什么 |
| --- | --- | --- |
| AI能力 | 已经做好 | 智能体本身、流式回复、访客隔离、用量统计 |
| 协议端 | NapCatQQ | QQ 收发消息，转成 OneBot v11 事件 |
| bridge | 你自己写 / 用现成的 | 收 OneBot 事件、拼成 ADP 认识的格式、调 ADP、把回复转回 NapCat |

ADP 侧不用动，协议端装个 NapCatQQ 就行。真正要写的是 bridge 那一环。

## 二、实现步骤

### ADP 侧：拿 AppKey

进控制台打开你的应用，**应用发布 → 服务状态 → API 管理**。页面下方列出这个应用的 AppKey（名称、创建时间）。一个应用最多两个 AppKey，没有就点「创建」，创建完**立刻复制保存**，页面关掉就看不到了。

调用时带这个 AppKey 请求 v2 chat 接口，传一条 `user_query` 字符串，开 SSE 流式接收。ADP 侧就这些，剩下的都是 bridge 的活。

### 协议端：NapCatQQ + OneBot11 配置

去 [NapCatQQ Release](https://github.com/NapNeko/NapCatQQ/releases) 下最新版，按它的文档装好、扫码登录当机器人的那个 QQ。

改它的 OneBot11 配置文件（路径形如 `/data/napcat/data/config/onebot11_<你的机器人QQ>.json`），开两样东西：HTTP 服务器（给 bridge 发消息用）和反向 WebSocket 客户端（把 QQ 消息推给 bridge）：

```json
{
  "network": {
    "httpServers": [
      {
        "name": "adp-bridge-http",
        "enable": true,
        "host": "127.0.0.1",
        "port": 3001,
        "enableForcePush": true,
        "messagePostFormat": "array",
        "token": ""
      }
    ],
    "websocketClients": [
      {
        "name": "adp-bridge-ws",
        "enable": true,
        "url": "ws://127.0.0.1:8080/onebot/v11/ws",
        "messagePostFormat": "array",
        "reportSelfMessage": false,
        "token": ""
      }
    ]
  }
}
```

- HTTP 端口默认 **3001**，避开常被占的 3000。换了的话 bridge 那边 `NAPCAT_HTTP_URL` 也要同步。
- `reportSelfMessage: false` 别改——机器人自发消息不进事件流，否则回环。
- 改完重启 NapCat。
  
​![Clipboard_Screenshot_1782353346.png](https://developer.qcloudimg.com/http-save/yehe-12417104/abd9c08ea854332a77bc98d39a41a913.png)

### bridge 侧：四个要处理的点

自己写 bridge 的话，有四件事必须处理：

**1. 收 OneBot 事件。** 起一个 WebSocket 服务监听 NapCat 的反向 WS 连接（上面的 `ws://127.0.0.1:8080/onebot/v11/ws`），收到 `post_type=message` 的事件就处理。群消息带 `message_type=group`，私聊带 `message_type=private`。

**2. 拼 `user_query`。** ADP v2 的对话接口只收一条 `user_query` 字符串，没有「这是群聊、谁发的、之前聊过啥」这种独立字段。标准做法是拼一个结构化文本：

```
[System]    全局规则（默认禁 Markdown，QQ 客户端不渲染）
[Context]   type=group | from=张三(123456) | session=group_924777972
[History]   最近 N 轮对话
[Current]   本轮真实消息（已剥掉 @机器人 的 CQ 码）
```

让 LLM 自己从这段文本读上下文。超长时 `[System]/[Context]/[Current]` 永远保留，从 `[History]` 头部丢。

**3. 访客 ID 隔离。** `VisitorId` 按来源拼：群聊 `group_<群号>`，私聊 `qq_<QQ号>`。整群共享一个上下文，私聊每人独立。ADP 那边的用量统计、会话关联都靠这个 ID。

**4. 接 SSE 事件流。** ADP v2 流式返回一堆事件：`text.delta` 累积文本、`message.done` 是完整回复、`response.completed` 标记结束、`error` 要把错误消息发回用户。攒齐再发比流式分段稳，QQ 消息分段太碎体验差。多轮上下文存 bridge 内存里就行，重启即清——不是 ADP 服务端状态。

**v1 接口已废弃**：`wss.lke.cloud.tencent.com/v1/qbot/chat/sse` 会报 `460030 该应用类型不支持当前请求`，老教程里的 v1 URL 别照抄，只用 v2。

## 三、已有实现：adp-napcat-bridge

上面这套不用从零写。[deadmau5v/adp-napcat-bridge](https://github.com/deadmau5v/adp-napcat-bridge) 已经把 bridge 那一环实现好了——FastAPI 写的，MIT 协议，Python 3.12+，代码量不大，逻辑清晰。特性包括：原生解析 ADP v2 SSE 事件流、群/私聊访客 ID 隔离、结构化 user_query 拼装、内存多轮上下文（默认 6 轮可配）、白名单 + @触发模式、流式/非流式可切、System Prompt 可配、Docker 多架构镜像（amd64 + arm64）。

想直接用就往下看操作步骤；想改逻辑（换存储、加权限、接多 bot）可以 fork 它当底座，代码结构很清楚：

```
adp-napcat-bridge/
├── main.py             # FastAPI 入口
├── adp_client.py       # ADP v2 SSE 客户端
├── napcat_client.py    # OneBot v11 HTTP 客户端
├── handler.py          # 消息处理：白名单/触发/历史/user_query 拼装
├── config.py           # .env 配置加载
├── constants.py        # 项目级常量
├── docker-compose.yml  # bridge + NapCat 容器编排
└── docs/DEPLOYMENT.md  # 完整部署文档
```

欢迎 fork 参考，按自己场景改。

## 四、用 adp-napcat-bridge 跑起来

### 准备

- 一个已经发布到正式环境的 ADP 应用（控制台「应用发布」点过「发布」）
- ADP 应用的 AppKey（上面「ADP 侧」拿的）
- 一台能跑 Docker 或 Python 3.12+ 的机器
- NapCatQQ 已经部署、机器人 QQ 已扫码登录、OneBot11 配置按上面「协议端」那段改好

### 启动 bridge

最省事是 Docker Compose，compose 文件里连 NapCat 一起编排了：

```bash
git clone https://github.com/deadmau5v/adp-napcat-bridge.git
cd adp-napcat-bridge
cp .env.example .env
```

编辑 `.env`，至少填一项：

```bash
# 从 ADP 控制台「应用发布 → 服务状态 → API 管理」拿到
ADP_BOT_APP_KEY=你的AppKey
```

启动：

```bash
docker compose up -d
```

不用 Docker 手动跑：

```bash
uv venv --python 3.12 .venv
uv pip install -r requirements.txt
.venv/bin/python main.py
```

启动成功会看到：

```
✓ NapCat 连接成功 | 机器人QQ: 12345678 | 昵称: ...
Bridge 服务就绪，等待消息...
✓ NapCat 反向 WebSocket 已连接
```

出现 `NapCat 反向 WebSocket 已连接` 就说明两端通了。群里 @机器人 发一句话，有回复就算跑通。

### 关键配置项（`.env`）

只挑几个你会动到的，完整列表看仓库的 `.env.example`。

| 环境变量 | 默认 | 干嘛的 |
| --- | --- | --- |
| `ADP_BOT_APP_KEY` | 必填 | ADP 控制台拿到的 AppKey |
| `ADP_CHAT_URL` | `https://wss.lke.cloud.tencent.com/adp/v2/chat` | v2 接口地址，一般别动 |
| `BRIDGE_TRIGGER_MODE` | `at` | `at` = 群里 @机器人 才回；`always` = 所有消息都回 |
| `BRIDGE_ALLOWED_GROUPS` | 空 | 群白名单，逗号分隔；**空 = 全过**，要限群就填 |
| `BRIDGE_ALLOWED_USERS` | 空 | QQ 白名单，同上 |
| `BRIDGE_MAX_HISTORY_TURNS` | 6 | 拼进每次请求的最近对话轮数；0 = 不带历史 |
| `BRIDGE_STREAMING_SEND` | false | `true` 按 ADP 片段分段发；`false` 攒齐再发（默认更稳） |
| `BRIDGE_SYSTEM_PROMPTS` | 禁 Markdown 模板 | 每次请求头部带的全局规则，多行用 `\n` |

### 验证

不想在群里发真消息扰人，可以本地模拟一条 OneBot 事件打过去：

```python
import asyncio, json, websockets

async def main():
    async with websockets.connect("ws://127.0.0.1:8080/onebot/v11/ws") as ws:
        await ws.send(json.dumps({
            "post_type": "message",
            "message_type": "private",
            "user_id": 3XXXXXX1,
            "self_id": 2XXXXXX4,
            "raw_message": "你好",
            "message": [{"type": "text", "data": {"text": "你好"}}],
            "sender": {"user_id": 3XXXXXX1, "nickname": "tester"},
        }))
        await asyncio.sleep(15)

asyncio.run(main())
```

机器人在私聊里回了话，链路就通了。

## 五、常见问题

- **报 `460030 该应用类型不支持当前请求`**：还在用 v1 接口。v1 已废弃，这桥只支持 v2。`ADP_CHAT_URL` 保持默认那个 `adp/v2/chat`，别照抄老教程。
- **报 `460919 会话 ID 已存在`**：用了文档示例里的固定 UUID。每次请求要用新生成的 `ConversationId`，bridge 自动生成，别自己传固定的进去。
- **群里 @ 了机器人没反应**：按顺序查三样——`BRIDGE_ALLOWED_GROUPS` 白名单有没有这个群；触发模式是不是 `at`（默认要 @ 才回）；NapCat 的 WS 还连着没（看 bridge 日志有没有 `NapCat 反向 WebSocket 已连接`）。
- **ADP 回复里夹带 `#`、`**` 这种 Markdown 符号**：QQ 客户端不渲染 Markdown，会原样显示。默认 `BRIDGE_SYSTEM_PROMPTS` 已经带「严禁 Markdown」规则，换了 System Prompt 又忘加就会出符号，加回去就行。
- **回环（机器人自己回自己）**：检查 NapCat 配置里 `reportSelfMessage` 是不是 `false`。
- **端口冲突**：NapCat HTTP 默认 3001，被占了就改 NapCat 配置里的 `httpServers[].port` 和 bridge `.env` 里的 `NAPCAT_HTTP_URL`，两边同步。
- **AppKey 泄露**：`.env` 加进 `.gitignore`；怀疑泄露就去控制台「API 管理」停用那个 AppKey 再创建新的。

## 六、长期挂着

跑通之后想长期挂着，用 tmux 守一下进程：

```bash
tmux new-session -d -s adp-bridge -x 200 -y 50 'cd /data/adp-bridge && .venv/bin/python main.py; exec bash'
tmux capture-pane -t adp-bridge -p -S -100    # 看日志
tmux kill-session -t adp-bridge               # 停服务
```

NapCatQQ 基于 NTQQ 协议端实现，项目 README 里写明「仅用于提高易用性、实现消息推送类功能」「由此造成的问题由使用者和提供违规使用教程者负责」。这套是个人/小圈子用的，要正式对外还是走 ADP 官方渠道（微信客服、企业微信等）或 OpenClaw 生态。

你可以把本文章发给 Workbuddy、Codex等Agent帮你完成搭建 ADP 发布渠道还没有支持QQ，所有本篇文章使用 Napcat QQ 第三方框架实现

把腾讯云 ADP 智能体接进 QQ 群

腾讯云 ADP 的发布渠道目前没有 QQ，但它的对话能力是开放 API，控制台能拿到 AppKey 自己调。本文记录用第三方框架 NapCatQQ（基于 NTQQ 的 OneBot v11 协议端）把 ADP 智能体接进 QQ 群的完整过程：先拆架构——ADP 出 AI 能力、NapCatQQ 当协议端收发消息、中间一个 bridge 做对接；再讲每环的实现要点（拿 AppKey、配 OneBot

腾讯云 智能体开发平台 社区运营

人工智能

本文介绍如何通过NapCatQQ框架搭建ADP智能体与QQ的对接方案，详细解析架构设计、实现步骤及常见问题。使用ADP开放API提供AI能力，结合NapCatQQ协议端实现消息收发，并推荐现成的adp-napcat-bridge项目快速部署。适合开发者快速搭建QQ机器人，实现智能对话功能。

容器编排

代码解释

TypeScript

WebSocket

智能体

服务器

OpenClaw

Python

Docker

容器

Agent

JSON

2026年中大促 | AI 领航 智绘未来

apigw

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

把腾讯云 ADP 智能体接进 QQ 群-腾讯云开发者社区-腾讯云

把腾讯云 ADP 智能体接进 QQ 群

把腾讯云 ADP 智能体接进 QQ 群

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐