QQBot 事件配置

ISkyPro 能否收到消息，取决于 Bot 登录状态、连接模式、QQ 平台事件订阅、群权限和插件处理结果。先确认 WebUI 仪表盘显示 Bot 在线，再排查事件配置。

WebSocket

WebSocket 模式由 ISkyPro 主动连接 QQ 网关，适合本机运行或没有公网回调地址的部署。

建议配置：

• WebUI Bot 登录页选择 WebSocket。
• 私域 / 公域事件订阅先使用自动；如果群消息收不到，再按机器人类型手动选择。
• QQ 开放平台如果已经配置 Webhook 回调地址，排查时要确认你实际使用的是 WebSocket 还是 Webhook，不要两条路线混用。

Webhook

Webhook 模式由 QQ 平台向你的公网 HTTPS 地址发送事件。

需要同时满足：

• WebUI Bot 登录页选择 Webhook。
• ISkyPro 或反向代理能被公网 HTTPS 访问。
• QQ 开放平台回调地址填写到实际公网 URL。
• QQ 开放平台事件配置中勾选需要的事件。
• 群消息至少要勾选 GROUP_MESSAGE_CREATE。

群消息

群消息常见还需要用户侧开关：

• 在手机 QQ 中打开对应群的机器人设置。
• 开启机器人可获取全部群内消息。
• 确认机器人仍在群内，且没有被禁言或移除。

如果只收到被 @ 的消息，优先检查群内“可获取全部群内消息”开关和 QQ 平台事件订阅。

常见排查

• Bot 未登录：回到 WebUI 重新验证 Bot ID / Secret。
• 模式不一致：WebUI 选了 WebSocket，但 QQ 平台按 Webhook 回调配置排查，或反过来。
• Webhook 不可达：公网域名、证书、反向代理或端口转发不可用。
• Webhook 签名失败：确认回调密钥和平台配置一致。
• 未订阅事件：Webhook 模式下到 QQ 平台勾选群、单聊、频道或私信事件。
• 群全量消息未开启：在手机 QQ 群机器人设置中开启。
• 插件没有响应：查看 WebUI 日志，确认事件是否进入框架、是否被 v1 插件拦截、是否被 v2 插件过滤。