NapCat + AstrBot 搭建 QQ 机器人:从零到可用的完整流程

想在 QQ 群里跑一个机器人?现在最成熟的方案是 NapCat(QQ 协议实现)+ AstrBot(机器人框架) 的组合:NapCat 负责和 QQ 通信,AstrBot 负责插件和智能回复。这篇文章记录完整搭建流程。

架构说明

QQ 客户端 ←→ NapCat(QQ 协议,OneBot 实现)
                  ↑ WebSocket
              AstrBot(插件框架 + LLM 接入)

• NapCat:开源的 QQ 协议实现,以无头模式运行,提供 OneBot 标准的 HTTP/WebSocket 接口
• AstrBot:Python 写的机器人框架,支持插件系统、多平台接入、LLM 对话

第一步:部署 NapCat

NapCat 提供容器镜像,一条命令搞定:

docker run -d --name napcat 
  -p 6099:6099 -p 3001:3001 
  -v /opt/napcat/config:/app/napcat/config 
  mlikiowa/napcat-docker:latest

启动后需要扫码登录:进入容器看二维码,用 QQ 手机端扫码,机器人即上线。

第二步:部署 AstrBot

AstrBot 同样支持 Docker:

docker run -d --name astrbot 
  -p 6185:6185 
  -v /opt/astrbot/data:/AstrBot/data 
  soulter/astrbot:latest

启动后访问 http://<服务器IP>:6185 打开管理面板,首次会要求设置管理员密码。

第三步:对接

在 AstrBot 管理面板添加 NapCat 适配器:

1. 协议选 OneBot V11(WebSocket 客户端)
2. 地址填 ws://127.0.0.1:3001(NapCat 的 WS 端口)
3. 保存后看日志确认连接成功

连接成功后,机器人就会响应群消息和私聊消息。

第四步:接入 LLM

AstrBot 的杀手锏是 LLM 对话能力。在面板的"模型提供商"里配置:

• Provider 类型:OpenAI 兼容接口
• API Key 和 Base URL 填你的中转站地址(比如自建的中转网关)
• 模型名填支持的模型

配置好后,群里 @机器人 就能触发 AI 对话。AstrBot 还支持记忆、多轮上下文、工具调用,深度玩法很多。

第五步:内网穿透(可选)

如果机器人跑在家里没有公网 IP 的机器上,用 Cloudflare Tunnel 把管理面板暴露出去:

ingress:
  - hostname: astrbot.example.com
    service: http://localhost:6185

这样手机在外面也能随时打开管理面板看状态、改配置。

踩坑记录

1. 双响应问题:同一个消息被多个适配器同时处理,机器人会回复两遍。排查插件监听逻辑,确认只有一个处理器响应。
2. 扫码登录时效:NapCat 的二维码有效期短,生成后尽快扫。登录后建议把会话信息持久化,重启不用重新扫码。
3. 端口冲突:6099 是 NapCat 的 OneBot HTTP 端口,3001 是 WebSocket 端口,部署前确认没被占用。
4. 机器人风控:新 QQ 号直接高频发消息容易触发风控,先小规模测试,再逐步放开。

总结

NapCat + AstrBot 的组合成熟度高、插件生态丰富,从部署到能用大概半小时。跑起来之后,定时提醒、AI 对话、群管理都能做,是性价比很高的 QQ 机器人方案。