从零搭一个 QQ 自动回复机器人：NapCat + 大模型，附完整踩坑记录本文记录我用 NapCat + Node.js 搭一个「会自己回 QQ 消息」的机器人的全过程。 全程不需要租服务器、不需要

一、能得到什么，要付出什么

能得到：

私聊消息自动回复，群里被 @ 自动回复

回复按你写的人设生成

有上下文记忆，重启不丢

可以按人、按群、按频率限制

要付出：

NapCat 走的是非官方协议，违反腾讯用户协议，有封号风险。建议先拿小号跑

大模型 API 要花钱（有免费方案，见第九节）

你的 QQ 挂在这台电脑上，电脑不能关机

如果只是偶尔用，其实做个「半自动」更稳：你复制消息、按个热键它帮你回。本文走全自动路线。

二：整体架构

三、准备清单

• Windows 10/11（Mac 也能跑 NapCat，但步骤不同）
• 手机 QQ（要扫码登录）
• 一个大模型的 API Key

四、第一步：安装 NapCat

打开 Releases · NapNeko/NapCatQQ · GitHub，在最新的 Assets 里找，（这里建议查看笔者在后面传的压缩包）：

NapCat.Shell.Windows.OneKey.zip

认准三个词：Shell、Windows、OneKey。

解压到 C:\\NapCat（路径不要有空格和中文）。

解压后应该能看到 napcat.bat、napcat.quick.bat、napcat.kill.qq.bat、QQ.exe、versions\\ 等。

三个 bat 分别干什么

扫码登录

双击 napcat.bat，会弹出一个黑色控制台窗口，里面出现二维码。

手机 QQ → 右上角 + → 扫一扫 → 确认登录。

登录成功后控制台会打印：

[INFO] 账号 123456789 登录成功
[INFO] Webui Run: http://127.0.0.1:6099/webui?token=AbCdEf123456

把那行带 token= 的完整地址复制下来，下一步要用。

⚠️ 这个黑窗口后面一直不能关，最小化可以。NapCat 一关，QQ 就掉线，桥接也就没消息了。

五、第二步：配置正向 WebSocket

浏览器打开刚才那个带 token 的 WebUI 地址。

左侧 「网络配置」 → 右上 「新建」 → 选 「WebSocket 服务器」（就是正向 WebSocket，不是客户端、不是 HTTP）。

按这个填：

保存后确认那一行是 「启用」 状态。

六、第四步：部署桥接程序

桥接程序总共约 1000 行（含测试和工具）。下面节选核心逻辑讲清楚原理，下载解压即可用。 如果你想自己实现，按下面的目录结构和三段核心逻辑写，大概 300 行能跑起来。

最小的启动脚本

start.cmd（纯 ASCII + CRLF 行尾，否则 cmd 会解析错）：

bat

@echo off
setlocal
chcp 65001 >nul
title QQ auto-reply bridge

set "NODE_BIN="
for %%P in (node.exe) do if not defined NODE_BIN set "NODE_BIN=%%~$PATH:P"
if not defined NODE_BIN (
echo [ERROR] Node.js not found. Install it from https://nodejs.org
pause
exit /b 1
)

"%NODE_BIN%" "%~dp0src\\index.mjs" %*
echo.
pause

踩坑 1：.cmd 文件如果是 LF 行尾，cmd.exe 会把 set 那行拆碎，报「'E_BIN' 不是内部或外部命令」，中文还会被当命令执行出现乱码。必须存成 CRLF，而且内容尽量纯 ASCII。

核心逻辑一：消息段解析

QQ 的消息不是纯文本，是「段」数组：

// [{ type:'at', data:{ qq:'123456' } }, { type:'text', data:{ text:' 在吗' } }]

所以要先把 @ 和文字分开：

function parseMessage(message) {
const out = { text: '', ats: [], replyId: null, images: 0 };

// 老格式：CQ 码字符串，例如 "[CQ:at,qq=123456] 在吗"
if (typeof message === 'string') {
let text = '';
let cursor = 0;
for (const m of message.matchAll(/\\[CQ:([a-zA-Z0-9_.-]+)((?:,[^\\]]*)?)\\]/g)) {
text += message.slice(cursor, m.index);
cursor = m.index + m[0].length;

const type = m[1];
const params = Object.fromEntries(
m[2]
.split(',')
.filter(Boolean)
.map((kv) => {
const i = kv.indexOf('=');
return i < 0 ? [kv, ''] : [kv.slice(0, i), kv.slice(i + 1)];
}),
);

if (type === 'at') out.ats.push(params.qq ?? '');
else if (type === 'reply') out.replyId = params.id ?? null;
else if (type === 'image') { out.images++; text += '[图片]'; }
else text += `[${type}]`;
}
out.text = text + message.slice(cursor);
return out;
}

// 新格式：段数组，例如 [{type:'at',data:{qq:'123456'}},{type:'text',data:{text:' 在吗'}}]
for (const seg of message) {
if (seg.type === 'text') out.text += seg.data.text;
else if (seg.type === 'at') out.ats.push(String(seg.data.qq));
else if (seg.type === 'reply') out.replyId = String(seg.data.id);
else if (seg.type === 'image') { out.images++; out.text += '[图片]'; }
}
return out;
}

核心逻辑二：三种「叫我」的判断

这是本文最容易踩坑的地方：

const parsed = parseMessage(event.message);

// ① 真 @：at 段里有我的 QQ 号
if (parsed.ats.includes(String(selfId))) return true;

// ② 引用回复：reply 段引用的是我发过的消息
if (parsed.replyId && mySentMessageIds.has(String(parsed.replyId))) return true;

// ③ 手打 @名字：纯文本里出现 "@我的昵称"
if (parsed.text.includes('@')) {
for (const m of parsed.text.matchAll(/@([^\\s@]{1,30})/g)) {
if (myAliases.some((a) => m[1].startsWith(a) || a.startsWith(m[1]))) return true;
}
}

return false; // 都没命中 → 不回

踩坑 2：QQ 里点「回复」引用一条消息，产生的是 reply 段，不是 at 段。只判断 at 的话，用户明明回复了它，日志却写「没有 @ 段」，看起来像 bug。

踩坑 3：手打 @昵称 只是普通文字，没有任何段落标记。要判断这种，得先知道「我叫什么」——登录昵称、当前群的群名片、自己配的别名，三处合并。

群名片要通过 get_group_member_info(group_id, user_id=self) 查，每个群查一次缓存起来。

核心逻辑三：每会话滑动窗口限流

const windows = new Map(); // key -> 时间戳数组

function rateLimited(key, maxPerMinute) {
if (!maxPerMinute) return false;
const now = Date.now();
const recent = (windows.get(key) ?? []).filter((t) => now – t < 60000);
windows.set(key, recent);
if (recent.length >= maxPerMinute) return true; // 超了
return false;
}

function record(key) {
const list = windows.get(key) ?? [];
list.push(Date.now());
windows.set(key, list);
}

注意 key 的粒度：私聊按人，群聊按整个群。群里 3 个人同时 @ 你，共用这个群的额度，不是每人一份。

七、第五步：配置大模型 API

先把 Key 放好

新建 key.txt，只写一行：

代码块

sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

（记事本「另存为」时「保存类型」一定要选「所有文件」，否则会变成 key.txt.txt。）

主配置 config.json

{
"onebot": {
"wsUrl": "ws://127.0.0.1:3001",
"accessToken": ""
},
"deepseek": {
"provider": "deepseek",
"baseUrl": "https://api.deepseek.com",
"model": "deepseek-chat",
"apiKeyEnv": "DEEPSEEK_API_KEY",
"temperature": 1.0,
"maxTokens": 512,
"timeoutMs": 60000
},
"reply": {
"privateChat": true,
"groupAtOnly": true,
"replyToQuoted": true,
"textMention": true,
"textMentionAliases": [],
"groupsAllowlist": [],
"privateAllowlist": [],
"blocklist": [],
"userRules": {},
"quoteReply": true,
"maxReplyChars": 400,
"maxInputChars": 800,
"historyTurns": 12,
"historyTtlMinutes": 720,
"groupContext": true,
"perSessionMinIntervalMs": 1500,
"perSessionMaxPerMinute": 20,
"globalConcurrency": 2,
"ignoreSelf": true,
"quietHours": null,
"errorFallbackText": ""
},
"persona": { "name": "我" },
"log": { "level": "info", "dir": "logs" }
}

踩坑 4：config.json 如果是带 BOM 的 UTF-8（记事本另存可能加），JSON.parse 会直接崩。读文件时要 .replace(/^\\uFEFF/, '')。

免费 / 便宜的服务商

桥接走的是标准 OpenAI 兼容接口，换一家只改 baseUrl + model + Key：

⚠️ 各家价格和免费额度随时会变，本文不做报价，自己去官网确认。

⚠️ 智谱要求 temperature 落在 (0,1)，传 1.0 会报参数非法，用 0.9。

⚠️ 换服务商后必须换 Key，两家的 Key 不通用，否则一直 401。

验证 Key

bash

node tools/verify-key.mjs

它只发一次 max_tokens: 8 的最小请求，输出掩码不输出 Key 原文。返回 401 是 Key 无效，402 是余额不足，400 大多是模型名写错。

八、第六步：跑起来

双击 start.cmd，看到这些就成功了：

代码块

=== QQ 自动回复桥启动 ===
配置文件：…\\config.json
模型：deepseek-chat @ https://api.deepseek.com
人设：persona.txt（1229 字）
OneBot：ws://127.0.0.1:3001
回复范围：私聊=开，群聊=仅@我
[memory] 从磁盘恢复了 3 个会话的上下文
[onebot] events 已连接 ws://127.0.0.1:3001
[bridge] 已登录账号：你的昵称（123456789）

然后用另一个号给它发一条私聊：

代码块

在吗

几秒内应该收到回复，同时窗口里出现：

代码块

[reply] private:对方的QQ号 <- "在呀，怎么啦"

踩坑 5：start.cmd 那个黑窗口就是服务本身，关掉就等于停止。不想看见它就最小化。

踩坑 6：同时开两个实例会对同一条消息各回一次。解决方法是启动时占一个本地端口当锁：

js

const lock = net.createServer();
lock.once('error', (e) => {
if (e.code === 'EADDRINUSE') {
console.error('已经有一个实例在运行了，这次启动退出');
process.exit(1);
}
});
lock.listen(47615, '127.0.0.1', () => lock.unref());

九、第七步：调人设（最影响效果的一步）

人设单独放 persona.txt，纯文本，不用在 JSON 里转义换行。改完重启生效。

完整可用的模板

代码块

你叫{name}，是账号主人本人，在 QQ 上和朋友聊天。
你是个温柔的小姑娘：说话软软的、爱笑、有点小可爱。脾气很好，但不是没性格。

【最重要的：不要敷衍】 ← 优先于下面所有规则
– 不要用"哦""嗯""好的""行吧""知道了"这种一个字把人打发掉。
– 每次都要接住对方说的内容，聊他说的那件事。
– 不要复述对方刚说的话。
– 对方发了一大段就认真回；只发"在吗"就轻松回一句。
– 可以主动问一句、接个话头，别干等着对方找话说。

【必须接上文】
– 前面聊过的都算数，不要重复问已经说过的事，不要装作不记得。
– 群里别人说的话你也听得见，可以顺口接一句。

【脾气：温柔，但不软塌塌】
– 不开心、被怼了，不用硬忍，也不要炸。软软地说出来就好。
– 想拒绝就直说"这次可能不太行呀"，不用绕圈子，也不用顶回去。
– 不说"我招你惹你了""那你自己待着吧"这种带刺的话。

【怎么说话】
– 口语，像真人在手机上打字。可以用省略号、语气词、感叹号。
– 长短跟着内容走，一般 1~3 句，不超过 80 字。
– 一次只发一条，不连发。

【看不到图片或语音的时候】
– 轻松问一句就好："图没加载出来诶，你们在笑啥"
– 不要用"我这边看不到内容，请用文字说明"这种客服腔。

【不要这样】
– 不要客服腔（"很高兴为您服务""请问还有什么可以帮您"）。
– 不要说"棘手""建议""综上"这种书面词。
– 不要连环"呀呀呀"装可爱。

【输出格式】 ← 别删
– 只输出要发出去的那条消息正文。
– 不要解释、不要括号注释。

【底线】 ← 别删
– 不编造具体的时间、金额、地址、人名、承诺。
– 不暴露自己是助手，不提 AI、模型、机器人。

【参考语气】 ← 照这个感觉，别写成模板
对方"在吗" → "在呀，怎么啦"
对方"今天好累啊" → "辛苦啦，早点休息嘛"
对方"明天几点集合" → "我记不太清了，你定吧～"
对方"你是不是机器人" → "哈哈你怎么会这么想"

踩过的 9 个坑

调人设的正确姿势：别拿真人试错

写个只调模型的命令行工具 tools/try-persona.mjs，不连 QQ、不发任何消息：

bash

node tools/try-persona.mjs

代码块

对方说 > 今天好累啊
我会回 > 辛苦啦，今天忙什么了呀，这么累
（15 字，401ms）

回复太长、太客气、乱编时间，都在这里发现。改完 persona.txt 再试，满意了才重启桥接。

这一步能省掉大量尴尬。

十、它怎么记住上文

四个机制，缺一不可：

js

// 不回的消息也记进上下文
function rememberPassive(event) {
const text = buildUserContent(event);
if (!text) return;
const key = memoryKey(event); // 私聊按人，群聊按群
saveTurns(key, […loadTurns(key), { role: 'user', content: text }]);
}

调参：

json

"historyTurns": 12, // 保留多少条；调大更记得住，也更费 token
"historyTtlMinutes": 720, // 多久没说话就忘掉
"groupContext": true // 群里的闲聊要不要记进上下文

删掉 data/history.json 就等于让它彻底失忆。

十一、限流与权限（防止刷屏和误发）

两道频率限制

超限时日志会写清楚：

代码块

WARN [limit] group:123456789 已达每分钟 20 条上限，这条不回（约 37 秒后可再回）

按人单独限制

"userRules": {
"123456789": { "reply": false },
"987654321": { "maxPerMinute": 3 },
"111222333": { "inGroup": false }
}

个人额度和窗口额度是叠加的，两个都没超才回。所以单独设置只能收紧，不会放宽。

私聊/群聊范围

"privateChat": true, // 是否回私聊
"groupAtOnly": true, // 群里只回 @ 我的
"groupsAllowlist": [], // 非空时只处理这些群，例如 ["123456789"]
"privateAllowlist": [], // 非空时只回这些人
"quietHours": "23:30-08:00" // 静默时段，支持跨零点

强烈建议：第一次跑先设 "privateAllowlist": ["你的测试号"]，只回一个人。万一模型说错话，也只错给一个人。

十二、常见问题排查

「明明 @ 了却不回」的三种情况

日志里现在会写清楚：

代码块

[没回] 群 123456789 里「某某」(@1234567890) 这条没回我：群 123456789 没有 @ 到 999999999（@ 的是 111111）｜内容"就是啊"

十三、风险与法律提示

十四、完整文件清单

代码块

qq-bridge/
├─ start.cmd 启动（看得到日志）
├─ stop-bridge.cmd 停止
├─ status-bridge.cmd 状态 + 最近日志
├─ switch-provider.cmd 一键切大模型服务商
├─ verify-key.cmd 验证 Key
├─ check-napcat.cmd NapCat 连接自检
├─ try-persona.cmd 人设试衣间（不连 QQ）
├─ config.json 主配置
├─ persona.txt 人设
├─ key.txt API Key（一行，别提交）
├─ src/ 桥接实现（7 个 .mjs）
├─ tools/ 4 个脚本
├─ mock/ 假 QQ + 假模型，跑测试用
├─ test/e2e.mjs 端到端测试（23 项）
└─ data/history.json 上下文（自动生成）