这篇教程来说一下我怎么用 AstrBot 和 NapCat 给自己的 QQ 号接上了 AI 机器人。
一直想给自己的 QQ 弄个 AI 机器人,但翻了一圈资料发现要么协议不稳定,要么配置复杂到不想看。后来找到了 AstrBot + NapCat 这套组合,才发现原来可以这么简单——NapCat 负责登录 QQ 账号并提供标准接口,AstrBot 负责接大模型和处理各种功能逻辑,两者通过 OneBot 协议对接,直接在本地运行,连容器都不用。
AstrBot 是一个开源的多平台聊天机器人框架,支持 QQ、微信、Telegram 等平台,原生支持 DeepSeek、OpenAI、Claude 等主流大模型。NapCat 则是基于 QQ 官方 Linux 版本的 OneBot 协议实现,能让你的 QQ 账号通过标准化接口被机器人程序调用。
注意
通过 NapCat 接入 QQ 存在触发腾讯风控机制的风险,建议使用有一定活跃度的 QQ 号,不要过于频繁地发送消息。
在开始之前,你需要准备:
如果你还没装 Python 和 Node.js:
bash# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip python3-venv -y
# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs -y
检查版本:python3 --version 和 node -v 应该都能正常输出。
第一步:部署 AstrBot AstrBot 是 Python 项目,直接用 pip 安装就行。
bash# 创建并进入目录(可选,方便管理)
mkdir ~/astrbot && cd ~/astrbot
# 创建虚拟环境(推荐,避免污染系统包)
python3 -m venv venv
source venv/bin/activate
# 安装 AstrBot
pip install astrbot -U
#如果是国内网络无法下载可以尝试使用下面的方式。如果还是不行就需要在电脑下载再上传(这里不多说了)
# 使用清华源(推荐,综合最稳)
pip install astrbot -U -i https://pypi.tuna.tsinghua.edu.cn/simple
# 或使用阿里云源(速度快)
pip install astrbot -U -i https://mirrors.aliyun.com/pypi/simple/
安装完成后,初始化配置:
bashastrbot init
这一步会在当前目录生成 data/cmd_config.json 和 data/provider_config.json 等配置文件。
然后启动 AstrBot:
bashastrbot start
默认情况下,AstrBot 会:
在 0.0.0.0:6185 开启 WebUI 管理界面
在 0.0.0.0:6199 开启 WebSocket 服务(供 NapCat 连接)
首次访问 http://你的服务器IP:6185,默认账号密码都是 astrbot,登录后记得修改密码。
如果你希望 AstrBot 在后台运行,可以使用
tmux或nohup。这里我们先用前台运行方便调试
NapCat 提供了预编译的二进制文件,直接下载对应架构的版本即可。
先去NapCat 官方 Release 页面 找最新版本,根据你的系统下载对应的文件。比如对于 Linux x86_64:
bashcd ~
wget https://github.com/NapNeko/NapCatQQ/releases/download/vX.X.X/napcat-linux-x64 # 替换成实际版本号
chmod +x napcat-linux-x64
然后运行 NapCat(建议创建一个专门的工作目录):
bashmkdir ~/napcat && cd ~/napcat
mv ~/napcat-linux-x64 ./napcat
./napcat
首次运行会自动生成配置文件并提示你扫码登录。如果没自动弹出二维码,你可以通过 WebUI 来登录:
NapCat 默认会在 0.0.0.0:6099 开启 WebUI。访问 http://你的服务器IP:6099,会要求输入 Token。Token 可以在 NapCat 第一次运行时输出的日志中找到,或者在生成的 config.json 里查看。
登录 WebUI 后,点击「扫码登录」,用手机 QQ 扫描二维码,完成登录。
现在 AstrBot 和 NapCat 都在同一台机器上运行,只需要配置 NapCat 把消息通过 WebSocket 转发给 AstrBot。
在 NapCat 的 WebUI 中:
点击左侧「网络配置」
点击「新建」-> 选择「WebSocket 客户端」(注意是客户端,不是服务端)
勾选「启用」
消息格式选择 Array
URL 填写:ws://127.0.0.1:6199/ws (因为都在本地,直接用 localhost)
心跳间隔填 5000,重连间隔填 5000
点击保存
保存后,NapCat 会主动连接 AstrBot 的 WebSocket 服务。如果成功,你会在 AstrBot 的终端看到类似 aiocqhttp(OneBot v11) 适配器已连接 的日志。
如果连接失败,检查:
AstrBot 是否正在运行(确保 6199 端口被监听)
NapCat 配置的 URL 是否正确(是 ws:// 不是 http://)
服务器防火墙是否允许本地回环(一般默认允许)
机器人搭好了,现在给它装上“大脑”。
在 AstrBot WebUI 中:
点击左侧「配置」->「模型供应商」
点击「添加」,选择 DeepSeek
填入你的 DeepSeek API Key(可以去 platform.deepseek.com 申请,新用户有免费额度)
保存配置
然后回到「消息平台」,确保已经添加了「QQ 个人号」适配器(通常在 AstrBot 初始化时自动添加了,如果没有就手动加一个)。
用手机 QQ 给机器人账号发一条消息,比如发送 /help。如果机器人有回复,说明大功告成了!
你还可以在 AstrBot 的插件市场安装各种插件,比如天气查询、图片生成、群管理等功能,让机器人更强大。
现在 AstrBot 和 NapCat 都是前台运行,关掉终端就停了。推荐用 pm2 或 systemd 来守护。
用 pm2(推荐,简单):
bashnpm install -g pm2
# 启动 AstrBot(先激活虚拟环境)
cd ~/astrbot
pm2 start "source venv/bin/activate && astrbot start" --name astrbot
# 启动 NapCat
cd ~/napcat
pm2 start ./napcat --name napcat
# 保存 PM2 配置
pm2 save
pm2 startup
或者用 systemd(自行搜索编写 unit 文件,这里不展开了)。
确认 AstrBot 是否启动且监听 6199 端口:netstat -tlnp | grep 6199
确认 NapCat 配置的 URL 是 ws://127.0.0.1:6199/ws,不是 ws://localhost:6199/ws(有的系统解析 localhost 有问题)
如果 AstrBot 使用了虚拟环境,确保 astrbot start 在虚拟环境下执行
确保手机和服务器网络通畅,可以尝试用 TIM 扫码代替 QQ
新注册的 QQ 号可能更容易触发风控,建议用有好友/群的老号
可以尝试将 NapCat 的 protocol 配置改为 pad 或 phone(在 config.json 中修改)
检查 AstrBot 的模型配置是否正确,API Key 是否有效
在 AstrBot WebUI 的 「日志」 里查看是否有报错
试着在 AstrBot 终端发送测试命令,看能否正常调用 AI
检查服务器的防火墙是否开放了 6185(AstrBot)和 6099(NapCat)端口
如果是云服务器,记得在安全组中放行这些端口
确认程序确实在监听 0.0.0.0 而不是 127.0.0.1(AstrBot 默认监听所有地址,NapCat 也是)
好了,以上就是完整的非 Docker 搭建过程。全程不需要容器,所有组件直接跑在宿主机上,方便调试和修改。核心就是三步:装 AstrBot、装 NapCat、把它们连起来。
接下来我打算折腾一下玩客云。等弄好了再来写教程。
有问题欢迎在评论区留言交流~🧐


本文作者:acac
本文链接:
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!