QQ 接入 AI Agent 的两种路径
2026 年 QQ 机器人接入有两条主要路径：
| 路径 | 说明 | 稳定性 | 适用场景 |
|---|---|---|---|
| QQ 开放平台（官方） | 腾讯官方 API，合规安全 | ★★★★★ | 频道/群机器人 |
| NapCat / Lagrange（第三方） | 基于 NTQQ 协议的开源方案 | ★★★★☆ | 个人号机器人 |
建议：正式用途选官方开放平台，个人折腾选 NapCat。
方案一：QQ 开放平台（官方推荐）
1. 注册 QQ 机器人
- 前往 QQ 开放平台
- 注册开发者账号（支持个人和企业）
- 创建机器人应用：
- 选择「群聊机器人」或「频道机器人」
- 填写机器人名称、头像、简介
- 记录关键信息：
AppID: 123456789
AppSecret: xxxxxxxxxxxxxxxx
Token: xxxxxxxxxxxxxxxx
2. 配置权限
在机器人管理页面：
- 开启「被动回复」能力
- 如需主动推送，申请「主动消息」权限（需审核）
- 配置沙箱环境用于测试
3. 部署 Agent 服务
# 使用 OpenClaw 框架
git clone https://github.com/nicepkg/openclaw.git
cd openclaw && npm install
# 配置 .env
cat > .env << 'EOF'
# QQ 开放平台配置
QQ_APP_ID=123456789
QQ_APP_SECRET=xxxxxxxxxxxxxxxx
QQ_TOKEN=xxxxxxxxxxxxxxxx
# AI 模型
LLM_API_KEY=sk-xxxxxxxx
LLM_MODEL=gpt-4o
EOF
pm2 start dist/index.js --name qq-agent
4. 实现消息处理
QQ 开放平台使用 WebSocket 推送消息，核心处理逻辑：
// QQ Bot 消息处理示例
const { Client, Intents } = require('qq-bot-sdk');
const client = new Client({
appId: process.env.QQ_APP_ID,
token: process.env.QQ_TOKEN,
intents: [Intents.GROUP_MESSAGES, Intents.C2C_MESSAGES]
});
client.on('message', async (event) => {
const { content, author, groupId } = event;
// 调用 AI 生成回复
const reply = await callLLM(content);
// 发送回复
if (groupId) {
// 群聊回复
await client.sendGroupMessage(groupId, reply);
} else {
// 私聊回复
await client.sendDirectMessage(author.id, reply);
}
});
client.connect();
5. 上架审核
- 完善机器人资料（头像、简介、使用说明）
- 提交审核（通常 1-3 个工作日）
- 审核通过后即可被用户搜索和使用
方案二：NapCat（个人号方案）
优势
- 用你自己的 QQ 号当机器人
- 支持 OneBot 11 协议，生态丰富
- 功能完整（私聊、群聊、群管理）
风险
- 非官方方案，存在封号风险
- 建议使用小号
部署步骤
1. 安装 NapCat
# Docker 部署（推荐）
docker run -d \
--name napcat \
-p 3001:3001 \
-e ACCOUNT=你的QQ号 \
-e TOKEN=your_token \
mlikiowa/napcat:latest
2. 配置 OneBot 接口
NapCat 启动后提供 OneBot 11 标准的 HTTP 和 WebSocket 接口：
HTTP API: http://localhost:3001
WS API: ws://localhost:3001
WS Event: ws://localhost:3001/event
3. 接入 AI Agent
# Python 示例（使用 nonebot2 框架）
import nonebot
from nonebot.adapters.onebot.v11 import MessageEvent, Message
nonebot.init()
@nonebot.on_message()
async def handle_msg(event: MessageEvent):
text = event.get_plaintext()
# 调用 AI
reply = await call_ai(text)
await event.finish(reply)
async def call_ai(text: str) -> str:
import httpx
async with httpx.AsyncClient() as client:
resp = await client.post(
"https://api.openai.com/v1/chat/completions",
headers={"Authorization": "Bearer sk-xxx"},
json={
"model": "gpt-4o",
"messages": [
{"role": "system", "content": "你是AI助手，回答简洁。"},
{"role": "user", "content": text}
]
},
timeout=30
)
return resp.json()["choices"][0]["message"]["content"]
nonebot.run()
QQ 邮箱 Agent（新能力）
2026 年 QQ 邮箱全面 Agent 化，这是一个新的接入点：
- 通过 Agent Mail 为你的 Agent 创建专属邮箱
- Agent 可以收发邮件、处理邮件中的任务
- 适合需要异步交互的场景（Agent 处理完任务后邮件通知用户）
配置步骤：
1. 访问 agent.qq.com 注册 Agent 邮箱
2. 获取 SMTP/IMAP 凭据
3. 在 Agent 框架中配置邮件收发能力
4. Agent 可以读取邮件内容并自动回复
给 AI Agent 的接入指令
请将以下 Agent 接入 QQ：
方案A（QQ 开放平台）：
1. 在 q.qq.com 创建 QQ 机器人应用，获取 AppID、AppSecret、Token
2. 实现 WebSocket 消息监听（群消息 + 私聊消息）
3. 收到消息后调用 LLM 生成回复
4. 通过 QQ Bot API 发送回复
5. 提交审核上架
方案B（NapCat 个人号）：
1. Docker 部署 NapCat，登录 QQ 号
2. 通过 OneBot 11 接口监听消息事件
3. 收到消息后调用 LLM 生成回复
4. 通过 OneBot send_msg API 发送回复
原文出处：本教程基于 阿里云开发者社区 - OpenClaw 接入教程 改写。
有问题？评论区见。