从零搭一个会记事、会主动找你的 QQ AI 陪聊机器人

从零搭一个会记事、会主动找你的 QQ AI 陪聊机器人用开源项目暖屿 小满Warm Isle DeepSeek NapCat把一台 2C4G 的云服务器变成 7×24 小时在线的 QQ 陪伴机器人。它能聊天、记得住你、发表情包、发语音条还会在合适的时候主动找你。项目信息Gitee主仓https://gitee.com/menran/warm_isleGitHub镜像GitHub - Anran3366/Warm-Isle: 一个私人 QQ 陪聊机器人会聊天、记得住你、发表情包、发语音条、能看图、会在合适的时候主动找你 配一个功能完整的网页后台多机器人账号、知识库、语音克隆、聊天记录检索。 · GitHub开源协议AGPL-3.0技术栈Java 21 · Spring Boot 3 · SQLite · Vue 3 · Docker Compose一、它和“调个 API 转发消息”有什么不同如果你只是想让 QQ 里有个东西能回话网上现成的转发脚本很多收消息 → 拼 prompt → 调 DeepSeek → 发回去一百行代码就能跑。但真用起来很快就会遇到三个问题它记不住你。每次对话都是白纸昨天说过的过敏、前天提过的考试全靠你重复。它不是“一个人”。说话没有固定语气一会儿像客服一会儿像 GPT半夜还在问你“早安”。它不会主动找你。你不说话它就永远沉默——而这恰恰是“陪聊”和“问答”最大的区别。暖屿补的就是这三件事人设、记忆、主动性。模型只负责“说话”剩下的交给业务层。二、它能做什么像微信一样聊天回复拆成 1–3 条短句带打字延迟不发小作文。长期记忆每天中午自动把对话提炼成「事实卡 每日摘要」下次聊天自动带上按「机器人账号 × 聊天对象」隔离不会串台。主动消息早安、晚安、沉默 6 小时、跟进你提过的事默认 23:30–08:00 静默每天最多 3 条两条间隔不少于 2 小时。人设每个机器人账号可以启用不同人设也能上传小说/聊天记录自动提炼说话风格。表情包聊天中自动收集、打标签按情绪和时段发送支持按关键词现场搜图。语音条MiMo TTS 合成支持音色克隆、概率发送、每日上限对方发语音会自动转文字进上下文。图片理解本地 CLIP/NSFW/OCR 预筛通过后再送视觉模型敏感图不下载、不上传。多机器人账号每个号独立 NapCat 容器、独立 SQLite可扫码、切换、下线、删除。双协议端新建账号时可选 NapCat 或 SnowLuma业务层不用改。知识库 / 每日复盘 / 成本统计 / 关系与心情 / 后台扫码登录。三、整体架构你的手机 QQ │ 私聊消息 ▼ ┌─────────────┐ OneBot v11 ┌──────────────────┐ │ NapCat │ ◄─────────────► │ 暖屿 Warm Isle │ │ 或 SnowLuma │ WebSocket │ Spring Boot │ └─────────────┘ └────────┬─────────┘ │ ┌────────────────────┼────────────────────┐ ▼ ▼ ▼ DeepSeek API SQLite记忆 imageguard本地预筛协议端登录真实 QQ把消息翻译成 OneBot v11 的 JSON暖屿负责人设、记忆、主动消息、表情、语音、图片DeepSeek只负责“根据上下文生成一句话”。协议端和业务层解耦今天用 NapCat明天换 SnowLuma业务代码不用动。四、你需要准备什么项说明服务器Ubuntu 22.04/24.042C4G 起2G 能跑但图片预筛容易 OOMQQ 小号强烈建议用小号别拿主号机房 IP 有风控概率DeepSeek API Keyhttps://platform.deepseek.com充 10 块钱能聊很久域名可选有域名才能自动上 HTTPS没有就先 IP 强密码别长期裸奔Linux 基础会ssh、会改文件、会看docker logs安全组只开22 / 80 / 443。后台 8080、协议端 3001、预筛 8081 都不要对公网开放。五、部署跟着复制就行1. 安装 Dockercurl -fsSL https://get.docker.com | sudo sh sudo systemctl enable --now docker sudo usermod -aG docker $USER # 重新登录 SSH 后生效 docker compose version # 需要 v22. 拉代码sudo git clone https://gitee.com/menran/warm_isle.git /opt/warm-isle cd /opt/warm-isleGitHub 访问不稳定时用 Gitee两个仓库内容基本一致以 Gitee 为准。3. 构建 jar后端是 Spring Boot前端产物会打进 jar所以要先构建一次sudo apt install -y openjdk-21-jdk maven ​ # Node 20 curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs ​ bash deploy/linux/build-jar.sh # 产物target/qqbot.jar服务器内存小、构建容易 OOM也可以在自己电脑上构建好再scp target/qqbot.jar传到服务器。4. 配置.envcd deploy/linux cp .env.example .env chmod 600 .env vim .env最少填这 5 项DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxx ADMIN_PASSWORD换成一串很长的随机字符 PUBLIC_BASE_URLhttp://你的服务器IP QQBOT_WHITELIST你的QQ号 TZAsia/Shanghai几个容易踩的点变量名必须是QQBOT_WHITELIST这种全大写、点换下划线的形式qqbot.whitelist在容器里不生效QQBOT_WHITELIST留空 任何人私聊都会回千万别这么上线想发语音条再填MIMO_API_KEY小米 MiMo TTS/ASR想收掉线邮件再填SMTP_HOST/SMTP_USER/SMTP_PASS/ALERT_EMAILQQ 邮箱用授权码不是登录密码。5. 起容器sudo docker compose up -d --build sudo docker compose ps正常会看到qqbot、napcat、imageguard、caddy等容器 running。图片预筛需要三个 ONNX 模型clip_vision/clip_text/nsfw约 900MB。没有模型时图片理解不可用获取方式见deploy/linux/README.md。6. 扫码登录 QQ浏览器打开http://你的服务器IP/用.env里的ADMIN_PASSWORD登录。进「机器人账号」→「添加账号」→「扫码登录」→ 手机 QQ 扫码 → 状态变成「在线」。两个常见现象显示在线但发消息不回协议端连着、QQ 掉登录了点「刷新二维码」重扫过几小时又离线多半是 QQ 把设备踢了。项目自带看门狗每 5 分钟检查一次掉线会发邮件需配 SMTP并且“连得上但没登录”时只发二维码、不反复重启容器。六、第一次使用把人设和记忆配起来1. 给它一个人设后台 →「人设」→ 新建。可以手写也可以上传小说/聊天记录自动提炼风格。实测最影响“像不像人”的是这几条说话像发微信短句为主可以分几条发 对方说得少你就更少 不要用书面语、不要用列表、不要作为 AI 不确定就说不太确定别编。2. 设置可聊天的 QQ「机器人账号」→ 卡片里的「可聊天的 QQ」→ 从好友列表选择或直接输入 QQ → 保存。留空 不限制仅建议在试运行时短时间使用。3. 记忆与主动消息记忆每天 12:00 自动抽取后台可看事实卡、摘要、待确认项主动消息「主动消息」页可开关、改时段和频率主人 QQ在账号页填你自己的号只有这个号能让机器人改昵称/换头像。4. 验证用白名单里的号发一句在吗正常会收到 1–3 条短句。如果没反应docker logs qqbot --tail 50 # 业务层有没有收到消息 docker logs napcat --tail 50 # 协议端有没有掉登录 curl http://127.0.0.1:8080/api/ping # 后端活着吗七、进阶玩法多账号每个账号独立容器、独立库、独立人设。后台「机器人账号」→ 添加可选全新账号空库复制当前账号带记忆/人设的副本迁移旧账号数据旧号删除数据搬过去。单机内存有限3.6G 的机器建议不超过 3 个号开新号前先看「关于」页的内存。切换协议端账号卡片 →「切换接入」→ NapCat ↔ SnowLuma。会重建协议端容器聊天记录和记忆不动切换后重新扫码即可。知识库「知识库」→ 上传文件 → 选择解析类型persona生成人设style只学说话风格raw仅入库供检索。解析只在每天 00:05–06:05 跑内存低于 500MB 会自动暂停。语音与表情语音配置MIMO_API_KEY后可在聊天里说“发条语音”也可设置概率自动发表情聊天中收到的图会自动入库后台审核机器人按情绪和时段挑选发送。八、常见问题现象排查页面打不开docker compose ps看 caddy/qqbot 是否 Up80 端口是否放行扫码后离线看 napcat 日志账号可能被风控换号或等一会机器人不回白名单是否包含该 QQ看docker compose logs qqbot图片不理解imageguard 是否 OOM模型文件是否齐全curl 127.0.0.1:8081/health语音发不出MIMO_API_KEY是否配置日志搜「语音发送失败」更新代码git pull→cd deploy/linux docker compose up -d --build qqbot数据备份tar czf qqbot-$(date %F).tar.gz -C deploy/linux/data qqbot九、安全与合规请务必看QQ 风控NapCat / SnowLuma 都是第三方非官方客户端违反 QQ 用户协议有封号风险。请用小号、别群发、别做营销项目仅供学习与技术研究。协议端授权NapCat 与 SnowLuma 并非 AGPL 开源许可商业使用需单独获得授权。AGPL-3.0你可以自用、修改、部署如果把修改版作为网络服务对外提供需要公开修改后的源码。后台安全强密码、.env权限 600、不要长期开“一键放通”、尽量上 HTTPS。数据聊天记录和记忆都在deploy/linux/data/的 SQLite 里务必定期备份到另一台机器。十、项目地址Giteehttps://gitee.com/menran/warm_isleGitHubGitHub - Anran3366/Warm-Isle: 一个私人 QQ 陪聊机器人会聊天、记得住你、发表情包、发语音条、能看图、会在合适的时候主动找你 配一个功能完整的网页后台多机器人账号、知识库、语音克隆、聊天记录检索。 · GitHub项目还在持续更新欢迎提 Issue、Fork或者直接部署一套自己的。