OpenShamrock OneBot 机器人实战手册：三步把 QQ 变成你的可编程机器人

OpenShamrock OneBot 机器人实战手册三步把 QQ 变成你的可编程机器人【免费下载链接】OpenShamrockA Bot Framework based on Xposed with OneBot11项目地址: https://gitcode.com/gh_mirrors/op/OpenShamrockOpenShamrock 是一个基于 LSPosed 的 Xposed 模块它把自己挂进真实的 QQ 客户端进程替你实现 OneBot 11/12 协议让你用自己的服务器驱动一个真实 QQ 号收发消息。很多人卡在模块装好了、机器人却一点反应没有这一步这篇手册就是照着这条链路给你讲清楚的。读完你能把模块作用域、RPC 连接配置和第一条消息回发都跑通。它底层在干什么OpenShamrock 的路线不是重写 QQ 协议而是让 QQ 自己干活模块在 QQ 启动时注入自己的类加载器接管消息、联系人、群组这些内部数据再把它们翻译成 OneBot 11/12 标准的消息体和事件推给你的服务器。相当于请了一个住在你 QQ 里的翻译官QQ 内部说什么它转成服务器能懂的格式服务器下的命令它再翻译回去执行。跑起来之前要备好这几样已 root 的设备。没 root 就装不了 LSPosed模块根本加载不进来。LSPosed 框架本体并且把 OpenShamrock 模块的作用域勾选到 QQ以及系统进程。作用域漏勾是QQ 完全无反应的第一大原因。QQ 版本 9.0.70 及以上。低版本不在维护范围内出了问题不会修。一台能稳定访问手机所在网段的服务器。连不通 RPC 地址后面一切无从谈起。它能替你干这几件事收发消息这是最核心的一块QQ 里收到的文本、图片、语音、表情都会被转成 OneBot 格式推给服务器服务器调用发送接口消息就以你 QQ 的身份发出去。场景比如做客服自动应答服务器匹配到关键词后直接回一条预设文本整条链路不用你碰 QQ 界面。联系人与好友管理查好友列表、搜索用户、发送好友请求这些操作都有对应接口服务器侧拿到的是结构化的数据而不是截图。比如让机器人每天把新增好友整理成一条汇总消息发给你。群组操作群成员列表、禁言、群公告、群文件这些动作都能由服务器发起。比如自动审核入群申请收到群事件后机器人查看申请人资料符合条件就同意并打一条欢迎语。这些能力的接口集中在 kritor 服务层与 QQ 通信用的协议结构定义在 protobuf 模块看源码时可以顺着这两处找。跟着走从配置到第一条消息跑通把模块挂上作用域在 LSPosed 管理器里确认 OpenShamrock 模块处于启用状态然后在作用域设置里同时勾选QQ和系统进程重启 QQ。系统进程负责息屏保活相关的能力漏掉它后期容易掉线。进 QQ 后留意状态栏附近Shamrock 会弹出配置同步的提示没弹出来就说明注入没成功回管理器检查模块是否启用。调通 WebSocket 连接接下来打开 Shamrock 应用本体找到RPC 配置部分被动 RPC 默认端口是5700把rpc_address填成服务器的 IP 地址rpc_address.ticket填一个你和服务器约定的 token。保存后 QQ 侧会带着这个地址和 token 向服务器发起 WebSocket 连接。在服务器端打印收到的连接信息能看到握手成功就对了token 不一致会被直接拒掉。发出第一条回复连上之后在服务器侧先调一个查询登录信息的接口确认链路然后把 OneBot 客户端库连到ws://服务器IP:5700token 用同一个。随便找个好友给你的 QQ 号发一句话服务器会收到消息事件调用发送接口回一句收到QQ 里出现这条回复就算跑通了。拿它接几个真实活儿如果你要做一个自动客服任务就是用户消息进来命中关键词就回预设答案没命中就升级给人工OpenShamrock 负责把消息事件推给服务器并把回复发出去关键词表和兜底逻辑写在你的服务器端QQ 端不需要改任何东西。如果你要做定时提醒比如每天早上八点往群里发当日待办服务器到点调用发送群消息接口即可定时逻辑在服务器侧用计划任务实现机器人端只是执行出口。如果你要做群内监控留档把群消息实时写入数据库、命中敏感词就 管理员事件流是持续推送的服务器边收边过滤动作发言、禁言再通过群组接口回写。三个任务的共同点是OpenShamrock 管协议和投递你的服务器管逻辑边界划清之后机器人升级、换服务器都不用动 QQ 端。调优与避坑网络与连接RPC 端口5700要在服务器防火墙里放行并确认手机和服务器处于同一网段或路由可达。鉴权 token 建议设得长一点且随机配置里支持第二个 token可以给不同客户端分开用泄露时影响面小。如果服务器在公网、手机在 NAT 后面可以把方向反过来服务器主动连手机省掉端口映射。常见症状与解法症状QQ 启动后 Shamrock 完全没反应。原因通常是模块没启用或作用域没勾 QQ 和系统进程。解法回 LSPosed 管理器逐项核对改完重启 QQ看状态栏是否弹出配置同步提示。症状提示主进程未启动不会同步配置。原因QQ 主进程当时没在运行或已退到后台被系统回收。解法把 QQ 切到前台再进 Shamrock 应用触发同步同时检查电池优化设置别让它被杀。症状服务器收不到 WebSocket 连接。原因rpc_address填错、端口没放行或两端 token 不一致。解法先在服务器端抓日志看有没有连接尝试再核对配置里的地址、端口和ticket三项。症状私聊消息正常群里发不出去。原因发送的group_id不对或群里自回复被过滤。解法用事件里自带的群号字段回填别手打群号群内消息的回发行为受enable_self_message配置影响按场景开关。症状QQ 升级后模块行为异常甚至闪退。原因QQ 内部结构变了模块的注入点没跟上。解法把 OpenShamrock 升到适配新 QQ 版本的 release 再观察别用旧版硬扛。下一步动作先翻一遍 kritor/service/ 下的服务类把你用到的接口方法名和参数确认清楚。再对照 xposed/src/main/assets/config.properties 把所有配置项过一遍重点看rpc_port、token 和debug这几项。需要排障时打开debug模式在 Shamrock 应用的日志页里看初始化顺序哪一步断了就查哪一步。如果以后要扩展自定义消息或字段去 protobuf/src/main/java/protobuf/ 对照现有结构下手。先把登录信息查询接口跑通它返回成功就说明从模块注入到 RPC 回传这条链路已经完整。【免费下载链接】OpenShamrockA Bot Framework based on Xposed with OneBot11项目地址: https://gitcode.com/gh_mirrors/op/OpenShamrock创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考