简介这是一套基于 OneBot v11 协议的 QQ 插件项目面向 QQ 机器人开发者和技术水平中级的爱好者核心价值在于借助 NapCat、Lagrange 等第三方客户端完成与 QQ 的消息连接实现私聊和群聊场景下文字、图片、语音、视频、文件等多种消息的收发与解析同时支持对压缩包自动识别解压降低文件处理成本适合在非官方客户端环境或自动化工作流中集成使用。压缩包共 12 个文件整体仅 67KB以 TypeScript 源码为主包含 5 个 .ts 文件如 api、channel、runtime 等核心模块另有 3 个 JSON 配置文件、README 说明、说明文件.txt 和附赠资源.docx清晰呈现出接口定义、渠道连接、运行逻辑与使用文档便于阅读和二次开发。目前已有 86 人学习下载。通过这份资源用户可以得到一份完整可用的 OneBot 插件工程骨架了解 NapCat、Lagrange 的接入流程以及多类型消息的处理思路附带的说明文档还涉及安装步骤、配置方法和常见问题排查能帮助读者快速理解协议交互细节并搭建自己的 QQ 消息收发插件。对于研究 OneBot v11 协议和 TypeScript 插件开发的读者这是一份体量紧凑、实用性强的参考实现。1. 先别急着写业务代码Moltbot 这个插件项目到底卡在哪一环很多人搭 QQ 机器人卡住的不是机器人逻辑而是“消息怎么从 QQ 跑到我的服务器”。你照着教程装了框架、写了插件结果 NapCat 也起了、QQ 也登录了就是收不到消息。这个项目把这一环拆成了标准答案Moltbot 作为 OneBotv11 协议插件去对接 NapCat 或 Lagrange 这类第三方客户端暴露的 WebSocket 接口用统一的 OneBotv11 消息格式处理私聊和群聊里的文字、图片、语音、视频、文件。换句话说它解决的问题不是“机器人怎么聊天”而是“机器人和 QQ 之间那条通道怎么稳定打通”。这套方案特别适合两类人一是想自建 QQ 机器人、但不想碰 QQ 私有协议的开发者二是群主或运维想把入群欢迎、文件存档、关键词回复这类脏活交给脚本。接下来我会从协议层拆起再给出一套能在 Linux 上跑通的最小配置最后把图片、语音、视频、文件收发里最容易翻车的几个参数单独拎出来讲。2. OneBotv11 连接层拆解从 NapCat 到 Lagrange 的角色分工2.1 协议插件在消息链路里的真实位置要理解 Moltbot 这个插件项目得先看懂一条完整链路QQ 账号 → 第三方客户端NapCat 或 Lagrange→ OneBotv11 标准接口 → Moltbot 插件 → 你的业务脚本。第三方客户端在这里做的事情是把 QQ 客户端的消息事件转成标准 JSON再通过 WebSocket 推给插件插件收到 JSON 后按事件类型分发最后调用同样的接口把回复发回去。OneBotv11 的意义在于把“QQ 是什么”这件事彻底抽象掉了——你写插件时面对的不是 QQ 私有协议而是一套 HTTP 和 WebSocket 的标准动作。这个项目对整个链路的处理方式是Moltbot 负责消费 OneBotv11 的上报事件把私聊消息、群消息、元事件拆开再提供发送 API。常见的部署做法是把它跑在一个有 Python 或 Node 运行时的服务器上对外只需要保证 6700 或 3001 这类端口能被连接器访问到。这样设计的好处是连接器挂了只影响通道不影响你的业务代码反过来也一样。我一般会在架构上做一层隔离把 OneBotv11 的 WebSocket 地址写进独立配置而不是硬编码在业务代码里。因为换连接器时只是地址和 Token 变了插件本身的收发逻辑不用动。这个项目把协议和业务解耦的思路正是它值得拿来当底座的原因。2.2 连接器对比什么时候选 NapCat什么时候选 Lagrange.OneBot标题里同时点了 NapCat 和 Lagrange这两个是当前最常见的 OneBotv11 第三方客户端实现二者对外的接口标准一致但落地形态差异很大。对比项NapCatLagrange.OneBot运行形态依赖本机已有的 QQ 桌面端进程独立运行无界面部署环境Windows 最顺Linux 需额外处理跨平台适合服务器安装方式下载后启动配置通过 WebUI 或文件下载核心后生成配置并启动登录方式扫码或手机确认登录已有 QQ扫码登录支持快速登录缓存资源占用偏高QQ 客户端本身要吃内存相对更低适合长期挂机复杂度定位适合人还在电脑前、要调试的开发期适合扔到服务器上跑的稳定期选型我没有统一答案按使用场景分如果你只是在自己电脑上调试想直观看到 QQ 窗口、手动确认登录状态NapCat 更顺手如果你要把机器人扔到云服务器长期跑不想为 QQ 客户端付额外内存Lagrange.OneBot 更干净。我在 Ubuntu 服务器上部署时一般用 Lagrange.OneBot配好 headless 方式后基本可以不管它。但要注意一个前提无论选哪个对外暴露的都是 OneBotv11 标准 WebSocket 接口Moltbot 完全不关心你选的是谁。这也意味着你的插件代码如果写得太依赖 NapCat 特有字段换到 Lagrange 时就会翻车。尽量只用 OneBotv11 规范里的字段这是这章最值得带走的一条经验。3. 把 Moltbot 跑通的最小闭环从解压到第一条消息3.1 下载、解压与依赖安装标题里的压缩包拿到手第一步是把它放到一个干净的目录里解压然后根据项目说明确定运行时。常见做法是先看根目录里是package.json还是requirements.txt这直接决定你用 Node 还是 Python 生态。mkdir -p /opt/moltbot cd /opt/moltbot # 上传 zip 后解压到当前目录 unzip MoltbotOneBotv11协议插件项目_*.zip -d ./src cd src # 如果是 Node 项目 # npm install # 如果是 Python 项目 # 建议先建虚拟环境再装依赖 python3 -m venv venv source venv/bin/activate pip install -r requirements.txt这段命令做了三件事建项目根目录、解压压缩包、安装依赖。这里我给两种依赖安装方式的原因是这个项目的运行时并没有规定死你在实际拿到包之后按包内README或package.json里的 scripts 判断即可。依赖安装阶段最常见的报错是网络超时国内服务器拉 PyPI 或 npm 源慢的话换国内镜像会快很多。依赖装完不要急着启动。我踩过的一个坑是Python 版本太新依赖里某个包不支持。建议先python3 --version确认版本再决定是否要降级到 3.10 或 3.9。版本不对时pip 会报一些看不懂的编译错误那不是你的问题是依赖兼容性问题。3.2 配置 OneBotv11 WebSocket地址、Token 和事件订阅解压完后打开配置文件核心是三个字段连接方式、连接地址、Token。连接方式常见的是“正向 WebSocket”和“反向 WebSocket”两种。正向是指 Moltbot 主动去连 NapCat 暴露的 ws 端口反向是指连接器主动连 Moltbot 监听的端口。# config.yaml 示例字段名以实际包内模板为准 onebot: mode: forward # forward 插件主动连连接器reverse 连接器连插件 ws_server: 127.0.0.1:6700 # NapCat/Lagrange 的 WebSocket 端口 token: your-token-here # 必须与连接器配置里的 token 一致 event_filter: - private_message # 订阅私聊消息 - group_message # 订阅群聊消息 - group_upload # 群文件上传事件配置字段里最容易被忽略的是event_filter。如果你只订阅了private_message那群里怎么 机器人它都不会回复这不是代码问题是订阅粒度不够。另一个隐藏问题是token如果你在连接器侧开了鉴权但插件侧没填连接会显示建立、然后立即断开日志里反复出现握手失败。地址这里注意如果 Moltbot 和 NapCat 跑在同一台机器127.0.0.1够用如果连接器在 Windows、插件在 Linux 服务器ws_server要填连接器所在机器的内网 IP并且 Windows 防火墙要放行对应端口。死磕本机回环地址是开发期最容易卡住的玄学之一。3.3 启动连接器并完成登录配置完插件侧接着要把连接器拉起来。以 NapCat 和 Lagrange.OneBot 两种方式分别说明。# NapCat 常见启动方式Windows 上一般是双击或命令行启动 # 项目目录内通常有启动脚本 npx napcat # Lagrange.OneBot 在 Linux 服务器上的典型启动流程 ./Lagrange.OneBot # 首次启动会生成 LagrangeConfig.json # 修改配置里的 Implementations 段打开 ForwardWebSocket 并填端口Lagrange.OneBot 首次启动后需要手工改一个配置文件重点是把ForwardWebSocket启用来并设置与插件一致的端口和 Token。改完重启进程终端里会输出一个登录二维码用手机 QQ 扫码确认。注意一个细节登录成功不等于链路通了。路径是“QQ 登录成功 → 连接器 → WS → Moltbot”。你需要打开 Moltbot 的日志看到类似OneBotv11 connected的输出才算闭环。只看 QQ 在线就以为完事是开发期最常见的误判。真正验证链路的方式很简单在静默状态下从另一个 QQ 窗口给机器人发一条任意文字看插件日志里有没有新事件进来。有说明通道通了没有回去查 IP、端口和 Token 三个值。4. 私聊与群聊消息处理文字、图片、语音、视频、文件的完整收发4.1 先看懂 OneBot 的消息结构从 CQ 码到消息段OneBotv11 规范把消息定义为两类形态CQ 码和消息段数组。CQ 码是老式写法形如[CQ:image,filexxx.jpg]消息段数组则是 JSON更结构化新框架普遍用这种。{ type: message, message: [ { type: text, data: { text: 你好 } }, { type: image, data: { file: abc.jpg, url: http://... } } ] }理解这个结构比什么都重要。因为“图片消息”不是一个二进制流而是一段元数据——真实图片内容在url字段或file指向的本地路径里。语音同理record段的file指向本地 amr/silk 文件。所以在写接收逻辑时你不能直接把整个消息体当文件处理得先遍历消息段按type分流。这条链路里最容易踩坑的是发送侧。你发图片时消息段里的 file 可以传三种形式本地绝对路径、HTTP URL、base64 字符串。本地路径要求连接器进程有权限读URL 要求连接器能访问外网base64 则完全不受文件路径限制。我在实际项目里优先用 base64省去权限问题代价是消息体变大。4.2 接收与落盘私聊群聊分流代码把消息从事件里抽出来并落盘是整个项目里最值得精写的部分。下面这段 Python 示例展示了从 OneBot 事件到本地文件的处理流程。import os import json import base64 import requests EVENT_DIR ./received_files def handle_message(event: dict): # 判断消息来自私聊还是群聊 msg_type event.get(message_type) # private / group if msg_type private: peer_id event[user_id] sender_id event[user_id] os.makedirs(f{EVENT_DIR}/private/{peer_id}, exist_okTrue) elif msg_type group: peer_id event[group_id] sender_id event[user_id] os.makedirs(f{EVENT_DIR}/group/{peer_id}, exist_okTrue) else: return # 遍历消息段按 type 分发处理 for seg in event.get(message, []): seg_type seg[type] data seg.get(data, {}) if seg_type text: text data.get(text, ) save_text(peer_id, sender_id, text) elif seg_type image: img_url data.get(url, ) save_binary_from_url( f{EVENT_DIR}/{private if msg_typeprivate else group}/{peer_id}/img_{sender_id}.jpg, img_url ) elif seg_type record: record_url data.get(url, ) save_binary_from_url( f{EVENT_DIR}/{private if msg_typeprivate else group}/{peer_id}/voice_{sender_id}.amr, record_url )逻辑说明函数先取message_type做私聊/群聊分流这里的peer_id决定了文件存到哪个目录。图片和语音消息走的是同一套路子——从url字段下载二进制。要注意语音 URL 下载到的原始格式通常是.amr或.silk不是 mp3做语音识别或转写前需要先转码。参数说明save_binary_from_url这个函数内部一般要加两个参数——下载超时和重试次数。我习惯设timeout10、retries3因为 QQ 图片 URL 有时会过期首次请求失败后等两秒重试就能成功。文件下载完成可以比一下大小小于 100 字节的直接删掉这种多半是 HTTP 错误页而不是真图片。4.3 发送侧路径、URL、base64 三种传参方式发送消息是另一个容易翻车的半区。OneBotv11 的send_msg动作接收message_type、user_id/group_id、message三个核心字段。消息内容同样是消息段数组不同文件类型传参方式有细微差异。def send_rich_message(ws_conn, target_type: str, target_id: int, segments: list): payload { action: send_msg, params: { message_type: target_type, # private / group user_id if target_type private else group_id: target_id, message: segments } } ws_conn.send(json.dumps(payload)) # 发送文字 本地图片的构造示例 segments [ {type: text, data: {text: 这是自动生成的图片}}, {type: image, data: {file: /opt/moltbot/output/chart.png}} ] # 发送 base64 图片的构造示例适合从网络拉图后直接转发 # import base64 # img_b64 base64.b64encode(open(chart.png, rb).read()).decode() # segments [{type: image, data: {file: base64:// img_b64}}]参数说明file字段传绝对路径时路径在连接器所在机器上解析。如果 Moltbot 跑在 A 服务器、NapCat 跑在 B 机器你就不能直接传 A 服务器的路径B 机器读不到。这种情况要么先传到 B 机器共享目录要么用 base64 方式内嵌后者最省心。视频和文件消息的发送参数同理区别在于file指向的路径要可访问且文件不超限。语音发送有个特殊点部分连接器要求 silk 编码你直接传 mp3 可能发出去但对方听不了也可能直接报错返回async send failed。最好的办法是在插件里先判断语音格式必要时转成 silk 再发。这个坑在第四节里会有更细的说明。5. OneBotv11 连接避坑指南5 个高频故障与排查路径5.1 私聊能通、群聊没反应现象给机器人发私聊消息能收到自动回复但群里 机器人完全没有响应。原因最常见是事件订阅配置漏了group_message。很多人在配置里只勾了私聊消息因为开发期一直在用私聊窗口测试上线后忘了补群聊订阅。另一个隐蔽原因是连接器侧的框架没有开启“群消息上报”这在 NapCat 的设置面板里是一个独立开关。解决回配置文件确认event_filter里同时包含private_message和group_message然后重启 Moltbot。如果配置没问题检查连接器管理面板的“事件上报”开关把 GroupMessage 打开。最后再用另一个号在群里发条消息看日志有没有新的 group 事件。5.2 WebSocket 连接成功但 3 秒后被踢下线现象日志先显示connected然后频繁输出disconnected或者EOF反复重连。原因Token 不一致是头号元凶。插件侧和连接器侧只要有一边写了 Token、另一边空着连接握手就无法完成表现很像连接建立后被服务端强制关闭。次要原因是反向 WebSocket 模式下有两方同时发起连接造成事件风暴连接器就会把多余连接掐掉。解决先把两侧 Token 统一关掉或统一填写排除鉴权问题然后把协议模式锁定为一种——要么全用正向要么全用反向不要在配置里混合。顺手检查一下有没有两个插件实例同时启动重复订阅也会导致互踢。5.3 图片能收到但机器人主动发图别人看不到现象私聊里收到图片正常落盘但脚本拼接文字加图片发送后对方只看到文字图片位置空白或显示“图片加载失败”。原因发送侧file字段传了一个 URL但连接器所在机器访问不了这个 URL。比如 URL 是内网 NAS 上的地址连接器跑在云服务器外网访问自然失败或者 QQ 图片 URL 有防盗链连接器下载时被拒。解决发送图片优先走本地路径或 base64。我先requests.get(image_url)把图下载到本地再以 base64 内嵌方式构造消息段基本能回避所有跨网络和防盗链问题。base64 的好处是消息数据自包含不再依赖连接器发起第二次 HTTP 请求。5.4 语音消息发出去但对方听不了现象语音发送返回成功接收方也收到了语音气泡但点击播放没有声音或提示格式不支持。原因OneBotv11 对语音的格式要求在不同连接器实现里不统一。Lagrange.OneBot 对 amr 的支持较好NapCat 在某些场景下更认 silk。如果你传的语音文件是 mp3 或非标准编码连接器可能直接透传导致接收端无法解码。解决发语音前强制做一次格式判定不符合要求的先转码。常见做法是利用 ffmpeg 统一转成 amr 再发转码参数-ar 8000 -ac 1 -ab 12.2k是最稳的一组。在你的脚本里加一个前置检查如果消息段类型是record先ffprobe看一眼编码不是预期编码就拒绝发送并打 warning 日志而不是盲目把文件丢出去。这个坑我曾经在生产群机器人上踩过用户投诉“机器人说话没声音”查了整整一天。5.5 机器人账号频繁掉线或者扫码登录后立刻被顶掉现象登录成功跑半天到一天后连接器掉线重扫二维码又能用循环往复偶尔出现“账号已在别处登录”的提示。原因多数情况是多个连接器实例同时挂同一个 QQ 号或者电脑/手机上原本就登录着这个号连接器一登录就把另一端顶掉。还有一种常见场景是服务器 IP 频繁变动QQ 触发异地登录保护会强制下线终端。解决给机器人配一个专用小号不在手机和电脑上同时登录也别在调试期反复切换连接器。连接器启动时优先用快速登录缓存避免每次重新扫二维码。部署稳定后不要再开着第二个 NapCat 实例去“看状态”一个号只对应一个连接器进程这是长期稳定运行的基本纪律。另外把连接器的登录缓存目录做好备份掉线时恢复比重新扫码省事得多。6. 自动部署与自检脚本把整个队列串成一条命令最后一章落到实践收尾如何把“解压、配置、启动、自检”这四个动作合成一个自动化步骤呼应项目包里“自动解”的定位。项目不是跑一次就完事服务器重启后要能自己爬起来才算落地。#!/bin/bash # auto_setup.sh —— 一键部署 Moltbot 到 Ubuntu 服务器 set -e BASE_DIR/opt/moltbot ZIP_FILE$1 if [ -z $ZIP_FILE ]; then echo 用法: $0 zip包路径 exit 1 fi echo [1/4] 解压项目到 $BASE_DIR mkdir -p $BASE_DIR unzip -o $ZIP_FILE -d $BASE_DIR/src cd $BASE_DIR/src echo [2/4] 安装依赖 if [ -f requirements.txt ]; then python3 -m venv venv source venv/bin/activate pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple elif [ -f package.json ]; then npm install --registryhttps://registry.npmmirror.com fi echo [3/4] 写入 OneBotv11 配置 cat config.yaml EOF onebot: mode: forward ws_server: 127.0.0.1:6700 token: ${WS_TOKEN:-} EOF echo [4/4] 启动后台进程 # nohup 方式适合初版生产建议用 systemd 托管 nohup ./start.sh logs/app.log 21 sleep 5 curl -s http://127.0.0.1:6700/get_login_info || echo 连接器尚未就绪复杂逻辑请看日志做完部署验证比什么都重要。我的习惯是发一条带图片和一段文字的测试消息给机器人然后去received_files目录确认文件确实落盘了再让机器人主动回一条。只有双向都通才算验收通过。最后说一个我自己的教训早期部署时图省事直接把 QQ 主号挂了上去结果群里文件转发需求一多账号很快被限制功能。后来所有测试和正式环境都改用专用小号把登录缓存目录定时备份掉线恢复从小时级降到分钟级。这事的本质是机器人能不能稳定挂下去核心不是插件写得有多花哨而是账号策略和连接器选型有没有克制住。希望这些参数和避坑思路能帮到你照着这套流程把消息链路跑通以后再往上堆业务逻辑会顺手很多。本文还有配套的精品资源点击获取