企业官网建设流程全解析

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

【免费下载链接】OpenShamrockA Bot Framework based on Xposed with OneBot11项目地址: https://gitcode.com/gh_mirrors/op/OpenShamrock

OpenShamrock 是一个基于 LSPosed 的 Xposed 模块，它把自己挂进真实的 QQ 客户端进程，替你实现 OneBot 11/12 协议，让你用自己的服务器驱动一个真实 QQ 号收发消息。很多人卡在"模块装好了、机器人却一点反应没有"这一步，这篇手册就是照着这条链路给你讲清楚的。读完你能把模块作用域、RPC 连接配置和第一条消息回发都跑通。

它底层在干什么

OpenShamrock 的路线不是重写 QQ 协议，而是让 QQ 自己干活：模块在 QQ 启动时注入自己的类加载器，接管消息、联系人、群组这些内部数据，再把它们翻译成 OneBot 11/12 标准的消息体和事件推给你的服务器。相当于请了一个住在你 QQ 里的翻译官，QQ 内部说什么它转成服务器能懂的格式，服务器下的命令它再翻译回去执行。

跑起来之前要备好这几样

1. 已 root 的设备。没 root 就装不了 LSPosed，模块根本加载不进来。
2. LSPosed 框架本体，并且把 OpenShamrock 模块的作用域勾选到 QQ（以及系统进程）。作用域漏勾是"QQ 完全无反应"的第一大原因。
3. QQ 版本 9.0.70 及以上。低版本不在维护范围内，出了问题不会修。
4. 一台能稳定访问手机所在网段的服务器。连不通 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:5700，token 用同一个。随便找个好友给你的 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