无需注册 QQ 小号，基于 QQ 官方开放平台的 AI 聊天机器人。 支持私聊、群聊、长期用户记忆和本地可视化控制台。
机器人通过官方 AppID / AppSecret 接入，不需要额外注册用于挂机的 QQ 小号。开发者仍需登录开放平台，创建机器人并获得所需权限。本项目是独立开源项目。
- 私聊与群聊 @回复；获准接收普通群消息后，可启用观察或自主接话模式。
- 本地管理 API、提示词、用户记忆、私聊个人设置、群设置、用量和备份，无需前端构建。
- 支持 OpenAI 兼容 Chat Completions 和 Anthropic Messages；预置 DeepSeek 官方接口。
- 按聊天场景隔离近期对话与长期资料，提供频率限制和每日 tokens 预算。
- 内置日常聊天、编程助手、写作伙伴三套通用提示词，可自行新增。
- 以本地插件扩展功能；“预约提醒”支持 AI 创建、查询、修改、删除预约，重复规则和控制台管理，送达受 QQ 实际授权与频控限制。
当前处理文字消息，图片、语音和文件不做内容解析。
- 登录 QQ 开放平台，按平台要求注册开发者并创建机器人。
- 在机器人开发设置中取得 AppID 和 AppSecret。AppSecret 是应用密钥。
- 按平台要求配置私聊 / 群聊权限、测试成员和测试群；如果要求 IP 白名单，填写当前网络的公网出口 IP。
- 准备模型服务的 API Key。可以使用 DeepSeek 官方 API，也可以使用支持下表协议的服务，填写该服务提供的地址、Key 和模型名。
普通群消息接收、自主接话和主动发送取决于机器人实际获得的官方权限；程序不会自动替你开通权限。
GitHub 源码版需要 Windows + Node.js 24 或更新版本。安装包含 npm 的 Node.js，重新打开终端。
下载仓库 ZIP 并解压，在包含 package.json 的项目目录打开 PowerShell，安装依赖：
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-dependencies.ps1脚本使用固定版本的包管理器和锁文件，首次安装需要联网。无需全局安装 pnpm。
双击 start.cmd，浏览器会打开 http://127.0.0.1:17860；未自动打开时手动访问该地址。已有便携版且带有 runtime/、node_modules/ 时，可直接启动。
打开控制台 API 与机器人：
- 选择 通用对话 API，或点击 新配置。
- 填写配置名称、协议、Base URL、模型名称和 API Key。
- 点击 保存 API，再点击 使用这个 API。保存配置和启用配置是两个操作。
- 回到 运行概览 → 本机对话，发送一句话，确认能得到回答。本机测试无需先启动 QQ 机器人，但会使用模型额度。
- 需要 AI 调用预约等插件时，在 API 与机器人 → 测试插件调用 检查已保存的配置。测试只调用本机演示工具，不创建预约或发送消息，会使用少量模型额度。普通聊天正常不代表接口支持工具调用。
| 用途 | 协议 | Base URL | 模型示例 |
|---|---|---|---|
| DeepSeek 官方普通对话 | Chat Completions | https://api.deepseek.com |
deepseek-flash |
| DeepSeek 官方搜索 | Anthropic Messages | https://api.deepseek.com/anthropic |
deepseek-flash |
| 其他兼容服务 | 按服务文档选择上述协议 | 服务提供的基础地址 | 当前 Key 获准使用的模型 |
Base URL 不要追加 /chat/completions 或 /v1/messages。不同平台的 Key 不通用；模型名以服务文档或“查询模型列表”为准。
需要联网搜索时，选择 DeepSeek 官方搜索，填写对应平台 Key，保持 Anthropic Messages 协议和对应基础地址，保存并启用。搜索由模型按需调用，开关开启不代表每条问题都会搜索，实际可用性取决于账户和模型。普通兼容接口不自动支持这项搜索功能。
仍在 API 与机器人 页面：
- 填写自己的 QQ AppID 和 AppSecret，保留适合本机的 WebSocket；保存 QQ 配置。
- 点击右上角 启动机器人，确认状态变为“运行中”。
- 按平台提供的方式将机器人加入获准的测试环境。私聊直接发文字；群聊默认需要 @机器人。
如果平台要求使用 Webhook，需自行准备公网 HTTPS 回调地址，映射到配置的端口和路径，并在平台完成回调配置。默认本机 WebSocket 方式不需要把控制台暴露到公网。
没有回复时先确认本机对话能用，再检查控制台日志、QQ 权限、测试成员 / 群和 IP 白名单。
提示词工作室： 编辑或新建提示词，保存后再点击启用。群设置可以指定独立提示词，也可以跟随当前提示词。
个人模式（QQ 私聊）： 打开侧栏 个人模式，选择已发现的私聊用户，或点击“按用户标识添加”提前配置。机器人收到私聊后会自动发现用户；旧版已保存的私聊会话和长期资料也会出现在列表中。这里使用 QQ 平台提供的私聊用户标识，不一定是 QQ 号，也不与群成员标识通用。
点击“管理”可设置：
| 设置 | 行为 |
|---|---|
| 回复状态与用户备注 | 开启 / 关闭该用户的私聊回复，备注也用于预约提醒的目标显示 |
| 人格提示词与回复 API | 单独指定，或跟随当前全局提示词和 API；API Key 在“API 与机器人”中保存 |
| 发送间隔 | 留空跟随全局，填写 0 取消额外等待，支持 0–3600 秒 |
| 每小时最多回复 | 只计成功发送的模型回答，0 表示不额外限制；计数在重启后保留 |
| 每日 tokens | 0 跟随全部模型总预算，非零同时受个人预算和总预算限制 |
| 免打扰 | 开始与结束需一起填写，按北京时间执行，可跨午夜；相同时间表示不启用 |
保存后对新消息立即生效。未单独设置的用户保持原有行为，继续使用全局 API、提示词、发送间隔及性能与记忆限制。保存时如有回答或记忆整理正在进行，等待完成后再保存。
关闭回复或免打扰期间，该私聊的聊天与指令都保持安静，不调用模型、不保存新的对话正文；已有记忆保留。发送间隔和每小时次数限制用于普通聊天，帮助、模型、重置及记忆指令仍可使用。已保存的预约提醒独立执行，不受私聊回复开关与免打扰控制；暂停预约请到“插件管理 → 预约提醒”操作。
用户列表显示近期对话轮数、本小时回复次数和今日用量；详情可查看按提示词保存的近期对话、管理长期资料，并清空该私聊所有提示词下的近期正文。清空保留长期资料、记忆开关、群聊数据与已用预算；QQ 中的 /重置 仍只清空当前提示词下的近期对话。
个人用量包含该私聊的模型回答、插件调用的每轮模型请求和长期资料整理；缺少上游用量时按保守估算计入，失败请求也会保留已报告用量或估算。按北京时间每日归零，重启不会重置当天用量。私聊、本机测试及群聊共用的总预算仍在 群聊模式 → 群聊资源 → 全部模型每日 tokens 上限 设置。个人模式只管理 QQ 私聊，本机对话使用全局配置。删除某套 API 或提示词前，先将引用它的私聊设置改为跟随全局或另一配置。
群聊模式： 选择已发现的群或填写平台群标识，保存所需模式：
| 模式 | 普通群消息 | @机器人 |
|---|---|---|
| 轻量 | 不记录、不自动回复 | 正常回复 |
| 观察 | 在获得接收权限时记录上下文并判断，不自动接话 | 正常回复 |
| 全能 | 在获得接收权限时合并上下文，按判断自主接话 | 优先回复 |
建议先用观察模式确认能收到普通消息，再切换全能。群详情可设置频率、免打扰、模型、提示词和预算；“让Bot加入当前话题”会立即尝试生成并发送一次，需要有效群上下文和发送权限。群原文、接话记录与话题摘要默认保留 12 小时，可在“群聊资源”中调整为 1–168 小时。
用户记忆： 长期资料可在界面编辑，自动整理可关闭。不同群、私聊和本机用户的资料分开保存；自动整理可能额外消耗模型额度。
| 指令 | 用途 |
|---|---|
/帮助 或 /help |
查看帮助 |
/模型 或 /model |
查看当前模型 |
/重置 或 /reset |
清空当前近期对话，保留长期资料 |
/记住 内容 |
保存一条长期资料 |
/记忆 |
查看自己的资料 |
/忘记 |
清空长期资料 |
打开 插件管理 → 预约提醒，启用插件并确认当前模型通过“测试插件调用”。然后直接用自然语言私聊 Bot，或在群聊里 @Bot，无需固定命令：
本插件到时优先回复同一聊天最近收到的有效消息，没有有效消息时尝试主动发送。当前官方接口文档列有主动消息能力，其实际可用性取决于机器人获准的权限、频控与接收方设置，接收开关本身不能证明接口一定获准。
程序为对话回复预留安全余量，使用私聊55分钟、群聊4分钟。当前单聊文档顶部写60分钟、最多4次回复，msg_id 字段另写5分钟，描述存在不一致，实际以平台返回为准；群聊文档写5分钟、最多5次回复。建议先在 QQ 中说“十秒后提醒我喝水”测试。远期与重复规则可以保存，但不能保证每次准点送达。单聊发送说明、群聊发送说明
| 操作 | 示例 |
|---|---|
| 相对时间 | 十秒后提醒我喝水；十分钟后提醒我喝水（私聊） |
| 绝对时间 | 明天早上八点提醒我开会 |
| 重复提醒 | 每天八点叫我吃早饭；每周一早上八点提醒我开周会；每隔半小时叫我休息 |
| 查询 | 现在有哪些预约？我有哪些喝水提醒？ |
| 修改 | 把喝水的提醒推迟半小时 |
| 删除 | 删除今天下午五点喝水的预约；取消今天下午五点喝水的预约 |
| 暂停 / 恢复 | 暂停我的周会提醒；恢复我的周会提醒 |
AI 理解时间和事项，调用插件保存成功后才确认；时间不明确或多条预约都符合要求时会追问。查询读取本机已保存的记录，修改、删除和暂停会先查询对应预约，再执行操作。“取消预约”也按删除处理：移除预约及其发送记录，停止后续执行；需要暂时停用请使用暂停。
查询和操作请在创建预约的原聊天进行。 私聊中只能管理本人在该私聊的预约，群聊中只能管理本人在该群创建的预约；群里创建的预约不会出现在私聊查询中。自然预约、查询和修改会使用模型额度；已保存预约的到时发送由本地调度完成，不再调用模型。本机对话页面没有 QQ 发送目标，不能代替 QQ 聊天创建预约。
私聊预约发回原私聊，群聊预约发回原群；统一采用北京时间。支持绝对／相对时间、每天、工作日、每周、每月、固定间隔及结束时间。工作日指周一至周五；每月没有对应日期时跳过该月。
控制台 插件管理 → 预约提醒 可查看全部预约，按事项、ID、目标和状态筛选，手动新建、编辑、暂停、恢复、删除，并查看发送记录。点击“编辑”会在选中预约的紧邻下方展开表单；再次点击或点“收起”关闭。已完成和旧版已停止的记录也可删除。手动新建前，先与 Bot 私聊或在目标群里 @Bot，让控制台发现发送目标。关闭插件会暂停该功能并保留数据。
电脑开机且机器人连接正常时才会尝试发送。离线恢复后，24小时内仅尝试补最近的一次，重复预约跳过旧周期；更久的单次预约标为错过。发送失败停止重试，请在“记录”中核对错误码和平台授权后恢复；也可在原聊天发一条消息，提供新的对话回复窗口。结果未知时先核对接收方，避免重复提醒。
关闭网页不会关闭机器人。点击控制台左下角 退出程序，才会关闭服务；电脑休眠会影响连接。
密钥、提示词、记忆和预约保存在本机 data/。在 存储与环境 点击“创建数据备份”，可将配置、记忆、用户资料和插件数据保存到 backups/。这些文件含本机密钥和聊天资料，应自行保管。模型对话所需的消息和资料会发往你选用的模型服务。
迁移到另一台电脑时：
- 退出程序，完整复制
data/，不要只复制运行中的memory.sqlite。 - 在目标电脑按第 2 步安装项目和依赖，再将保存的
data/放入项目目录。 - 启动控制台，核对配置和记忆；平台启用 IP 白名单时，更新目标网络的公网出口 IP。
恢复备份时，先退出程序并保存当前 data/ 的完整副本，再将备份中的 settings.json、memory.sqlite 和 users/ 恢复到 data/。恢复前将旧 users/ 和 SQLite 的 -wal、-shm 文件移到安全副本中，避免与恢复数据混用。
功能放在 plugins/插件名/，通过注册表接入。插件向 AI 提供工具，并可拥有独立管理页面；无需增加前端构建。开发接口与新增插件步骤见 插件接入规范。
| 问题 | 处理 |
|---|---|
| 提示找不到 Node 或依赖 | 安装 Node.js 24 或更新版本，重开终端，再执行第 2 步的依赖安装命令 |
| 双击后打不开控制台 | 运行 console.cmd 查看输出，或检查 data/logs/error.log；已启动时访问 http://127.0.0.1:17860 |
| 模型 401 / 403 | 核对当前配置的 Key、服务平台与账户权限 |
| 模型 404 | 检查基础地址和模型名称，尝试“查询模型列表” |
| QQ 无法连接或群里不回复 | 检查 AppID、AppSecret、平台权限、测试成员 / 群和 IP 白名单；轻量群聊需要 @机器人 |
| 收不到普通群消息 | 确认官方平台已经开通相应接收权限；先用观察模式检查群上下文 |
| 官方搜索失败 | 确认使用 DeepSeek 官方搜索配置、对应 Key、Anthropic 协议及账户授权 |
| 查询或删除找不到预约 | 确认预约插件已启用，在创建预约的原私聊或原群操作，并说明要处理的事项；控制台可查看所有目标的记录 |
| 预约已保存但到时未收到 | 查看“插件管理 → 预约提醒 → 记录”的状态和错误码；核对有效回复窗口、回复次数、实际主动发送授权和频控 |
| 私聊需要单独的模型或提示词 | 在“个人模式”选择用户后保存回复 API 和人格提示词；留空跟随全局 |
| 私聊不回复但本机测试正常 | 检查“个人模式”的回复开关、北京时间免打扰、发送间隔、每小时次数与个人 / 总预算，再检查 QQ 平台权限与日志 |
| 删除 API 或提示词被拒绝 | 先在个人模式和群聊模式中更换引用该配置的设置，再删除 |
| 修改 QQ 配置被拒绝 | 先停止机器人，再修改凭证或接收方式 |
修改 .env 后没有变化 |
.env 只在首次创建配置时导入；日常配置通过控制台保存 |
| 运行时出现 EACCES / EPERM | 退出旧服务，再从正常 Windows 环境双击 start.cmd 启动 |
使用 console.cmd 时，它运行的也是完整控制台服务，无需再双击 start.cmd 或另外启动无界面机器人。
接入能力参考 腾讯官方 QQ SDK；模型地址和名称参考 DeepSeek 官方文档。