项目简介QQSafeChat 是一个运行在 Ubuntu 系统上的 QQ 自动回复机器人基于 NapCat 框架接入 QQ 消息收发通过 DeepSeek 大模型生成智能回复。支持私聊自动回复、群聊 回复、多人群切换、消息上下文记忆、回声消除等功能并提供一键安装脚本和 systemd 服务管理部署简单开箱即用。功能特性私聊自动回复智能应答好友私聊消息支持白名单过滤群聊 回复在群聊中被 时自动回复支持群白名单大模型驱动接入 DeepSeek API也可切换 OpenAI、硅基流动等兼容接口消息上下文记忆每个会话独立存储历史记录支持连续对话多人群切换预设多种聊天人格话痨、粘人、温柔等支持自定义回声消除自动过滤自己发出的消息避免死循环多消息分割支持同时发送多条消息模拟真人发条回复随机回复延迟1-3 秒随机延迟回复行为更自然管理命令!ping、!status、!help等命令在线管理WebUI 管理NapCat 自带 Web 管理界面可查看状态、管理配置一键安装脚本全自动部署无需手动操作systemd 服务支持开机自启、自动重启系统架构QQSafeChat 的整体架构由四个核心模块组成手机 QQ 扫码登录、NapCat 桥接层OneBot 协议、QQSafeChat 机器人主程序bot_main以及 DeepSeek LLM API。数据流为QQ 消息 → NapCat WebSocket → bot_main → LLM API → 回复发送。所需环境硬件要求组件要求操作系统Ubuntu 22.04 / 24.0464 位内存≥ 4GB网络能访问 GitHub 和 DeepSeek API架构x86_64软件依赖运行环境Python 3.8Node.js 18系统包zip、unzip、jq、curl、xvfb、screen、g、libnss3、libgbm1、libasound2Python 包requests、websocket-client核心组件Linux QQ 3.2.23、NapCat 最新版安装部署方法一一键安装推荐# 解压安装包 unzip QQSafeChat-Ubuntu.zip cd QQSafeChat-Ubuntu 赋予执行权限并运行一键安装脚本 chmod x install.sh sudo bash install.sh安装脚本会自动完成以下操作安装系统依赖包安装 Linux QQ 3.2.23 兼容版本下载并编译 NapCat含 napcat-linux-launcher安装 QQSafeChat 及其 Python 依赖创建 systemd 服务napcat.service qqsafechat.service方法二手动安装1. 安装系统依赖sudo apt update sudo apt install -y zip unzip jq curl xvfb screen g python3 python3-pip libnss3 libgbm1 libasound22. 安装 Linux QQ# 下载兼容版本 (3.2.23) wget https://dldir1.qq.com/qqfile/qq/QQNT/9a841627/linuxqq_3.2.23-44343_amd64.deb sudo dpkg -i linuxqq_3.2.23-44343_amd64.deb sudo apt install -f -y3. 安装 NapCatsudo mkdir -p /opt/napcat cd /opt/napcat sudo wget https://github.com/NapNeko/NapCatQQ/releases/latest/download/NapCat.Shell.zip sudo unzip -o -d napcat NapCat.Shell.zip sudo wget https://raw.githubusercontent.com/NapNeko/napcat-linux-launcher/refs/heads/main/launcher.cpp sudo g -shared -fPIC launcher.cpp -o libnapcat_launcher.so -ldl4. 安装 QQSafeChatsudo mkdir -p /opt/QQSafeChat cd /opt/QQSafeChat sudo cp -r /path/to/QQSafeChat/* . sudo pip3 install -r requirements.txt sudo mkdir -p history personas启动服务首次登录NapCat 启动后会产生二维码图片使用手机 QQ 扫码登录# 启动 NapCat后台运行 cd /opt/napcat nohup ./launcher.sh /dev/null 21 查看二维码 ls /opt/napcat/napcat/cache/qrcode.png 或通过 WebUI 扫码 浏览器访问 http://服务器IP:6099/webui?tokenYOUR_TOKEN启动 QQSafeChat# 确保 NapCat 已经启动并登录成功 # 然后启动机器人 cd /opt/QQSafeChat nohup python3 bot_main.py /dev/null 21 使用 systemd 服务管理# 启动 sudo systemctl start napcat sudo systemctl start qqsafechat 开机自启 sudo systemctl enable napcat sudo systemctl enable qqsafechat 查看状态 sudo systemctl status napcat sudo systemctl status qqsafechat 查看日志 journalctl -u napcat -f journalctl -u qqsafechat -f配置说明修改方法所有配置通过编辑 JSON 文件完成修改后重启服务生效。DeepSeek API 配置编辑/opt/QQSafeChat/settings/openai.json{ provider: deepseek, api_key: your_deepseek_api_key_here, base_url: https://api.deepseek.com, model: deepseek-v4-flash, temperature: 0.6 }参数说明参数说明默认值providerLLM 供应商deepseek/openai/siliconflow/mockdeepseekapi_keyAPI 密钥必填base_urlAPI 地址https://api.deepseek.commodel模型名称deepseek-v4-flashtemperature回复随机性0-10.6机器人配置编辑/opt/QQSafeChat/config.json{ napcat_ws_url: ws://127.0.0.1:3001, napcat_http_url: http://127.0.0.1:3000, napcat_access_token: , auto_reply: true, private_whitelist: [], group_whitelist: [], group_only_at_me: true, blacklist: [], reply_delay_min: 1.0, reply_delay_max: 3.0, split_delimiter: NEXT, split_min_pause: 0.5, split_max_pause: 3.0, history_max_messages: 400, persona_file: , command_prefix: ! }核心参数详解参数说明默认值napcat_ws_urlNapCat WebSocket 地址ws://127.0.0.1:3001napcat_http_urlNapCat HTTP API 地址http://127.0.0.1:3000auto_reply自动回复总开关trueprivate_whitelist私聊白名单QQ 号列表空表表示回复所有人[]group_whitelist群白名单群号列表空表表示回复所有群[]group_only_at_me群里只回复 机器人的消息trueblacklist黑名单QQ 号或群号列表[]reply_delay_min回复最小延迟秒1.0reply_delay_max回复最大延迟秒3.0persona_file人格文件personas/ 目录下的文件名NapCat 配置NapCat 的配置文件位于/opt/napcat/napcat/config/webui.jsonWebUI 端口和 token 配置onebot11_1550421257.jsonOneBot11 适配器配置WebSocket/HTTP 端口napcat_1550421257.jsonNapCat 核心配置管理命令在 QQ 中发送以下命令管理机器人命令功能!ping测试机器人是否在线返回 pong ✅!status查看运行状态LLM 供应商、当前人格等!help显示帮助信息多人群系统预设人格personas/目录下包含多种预设人格文件人格文件特点真实朋友-基础普通朋友式聊天真实朋友-开心小狗活泼热情风格真实朋友-懒懒感慵懒随意风格真实朋友-话痨话多爱聊风格真实朋友-更粘人粘人风格真实朋友-话痨高粘人话痨加粘人组合真实朋友-没有省略真实男友-基础男友风格真实男友-可爱可爱男友风格真实男友-更粘人粘人男友风格默认人格普通助手风格启用人格在config.json中设置persona_file字段{ persona_file: 真实朋友-话痨.txt }重启服务后生效。留空则不启用人格。项目文件说明QQSafeChat-Ubuntu/ ├── install.sh # 一键安装脚本 ├── README.md # 详细部署文档 └── QQSafeChat/ # 项目代码 ├── core/ # 核心模块 │ ├── llm_client.py # LLM 客户端支持 DeepSeek/OpenAI/SiliconFlow │ ├── napcat_bridge.py # NapCat OneBot 11 桥接层 │ ├── models.py # 数据模型定义 │ └── __init__.py ├── personas/ # 人格文件目录多种预设 ├── settings/ # 配置文件目录 │ └── openai.json # LLM 配置 ├── storage/ # 数据存储模块 │ ├── history_store.py # 对话历史管理 │ ├── persona_store.py # 人格文件管理 │ └── settings_store.py # 配置管理 ├── bot_main.py # 主程序入口 ├── config.json # 机器人配置 ├── requirements.txt # Python 依赖 └── run.sh # 运行脚本关键技术解析消息处理流程接收消息 → 消息过滤 → 回声消除 → 保存历史 → LLM 生成 → 发送回复NapCat 桥接层通过 WebSocket 接收 QQ 消息事件解析消息段中的纯文本消息过滤判断是否该回复白名单、黑名单、 检测回声消除检查消息是否为自己刚刚发出的防止死循环历史记录按会话维度存储对话记录格式化后作为 LLM 的上下文LLM 生成组装 system prompt 人格设定 历史记录调用 DeepSeek API发送回复支持多条消息分割、随机延迟模拟真人回复回声消除机制机器人发送消息后NapCat 会通过 WebSocket 回传同样的消息。如果不加处理机器人会以为自己收到了新消息再次回复形成无限循环。个人网站欢迎访问我的个人网站https://mythlj2.lovestoblog.com/了解更多项目与分享。