接入 QQ：NapCat 与 OneBot v11 全流程实操

QQ 是国内用户最多的场景。OneBot v11 路线以 NapCat 作为协议实现端，本页是完整对接记录，配不上就照着连接排查走一遍。

先建立方向感

OneBot v11 反向 WebSocket 的「反向」指：机器人框架是服务端，NapCat 是客户端。NapCat 主动连过来，而不是框架去连 QQ。所以配置顺序是：先把框架这头的服务器开好，再去 NapCat 填地址。

第一步：框架侧创建机器人实例

1. 打开 WebUI 左侧「机器人」
2. 点「+ 创建机器人」
3. 类型选 OneBot v11
4. 表单填写：

• ID：随意，用于区分实例
• 启用：勾上
• 反向 WebSocket 主机地址：一般填 0.0.0.0（监听所有网卡）
• 反向 WebSocket 端口：默认 6199
• 反向 WebSocket Token：NapCat 侧配了 token 才需要填，两侧一致

1. 保存

第二步：部署 NapCat

推荐官方文档列的一键脚本方式：

• Windows：参考 NapCat 官方指南的 Shell 手动启动教程
• Linux：NapCat.Installer 一键脚本，支持 Ubuntu 20+ / Debian 10+ / CentOS 9
• Docker Compose：下载 NapCat-Docker 仓库的 astrbot.yml 编排文件，把 6199 端口映射的注释去掉，在文件所在目录执行 compose up；Linux 下加 NAPCAT_UID / NAPCAT_GID 环境变量对齐权限

NapCat 装好后扫二维码登录一个 QQ 号——这个号就是未来的机器人号。

第三步：NapCat 侧配置连接

打开 NapCat 的 WebUI（地址在 NapCat 日志里；Docker 部署用 docker logs napcat 查）：

1. 「网络配置」→「新建」→「WebSockets 客户端」
2. 勾选启用
3. URL 填框架侧地址，按部署形态三选一：

• 都在同一台机器非 Docker：ws://127.0.0.1:6199/ws
• 只有 NapCat 在 Docker：ws://宿主机IP:6199/ws
• 两个都在同一 compose 网络：ws://astrbot:6199/ws（容器名直连）

1. 心跳间隔、重连间隔可改为 1000（1 秒）
2. 保存

第四步：验证

框架 WebUI →「数据」→「日志」，出现蓝色的 aiocqhttp(OneBot v11) 适配器已连接 字样即成功。如果若干秒后出现「适配器已被关闭」则是连接超时，回连接排查。

安全提醒

官方文档原话级别的提醒：不了解部署和网络配置的话，千万不要把 NapCat 的端口暴露到公网。NapCat 持有 QQ 登录态，暴露等于把账号交出去。