0 Fork 0

Files

T

xiaoli-cli bot bdf1d1a29a feat: 添加 OneBot v11 QQ 机器人插件

功能:
- WebSocket 正向/反向连接 OneBot 实现
- 接收私聊和群消息，转发给 AI 处理
- AI 回复自动发回 QQ
- 支持 @机器人 / 前缀 / 全部消息 三种触发模式
- 群白名单、管理员配置
- 手动发消息命令
- 支持 go-cqhttp / Lagrange / LLOneBot / NapCat 等

文件:
- onebot/onebot.py - 插件代码
- onebot/README.md - 使用教程
- plugin_registry.json - 注册表更新

2026-04-30 02:50:31 +08:00

3.5 KiB

Raw Blame History

OneBot v11 QQ 机器人插件

让 xiaoli-cli 成为 QQ 机器人，通过 OneBot 协议连接 QQ 消息平台

什么是 OneBot

OneBot 是一个聊天机器人应用标准，支持 QQ、微信等平台。常见的 OneBot 实现：

实现	语言	说明
go-cqhttp	Go	最流行，功能全
Lagrange.Core	C#	轻量，NTQQ 协议
LLOneBot	TypeScript	QQNT 插件形式
NapCat	TypeScript	另一个 QQNT 方案

前置准备

1. 安装依赖

pip install websocket-client

2. 安装 OneBot 实现

以 Lagrange 为例：

# 下载 Lagrange
# https://github.com/LagrangeDev/Lagrange.Core/releases

# 编辑配置 appsettings.json，设置正向 WebSocket
{
  "Implementations": [{
    "Type": "ForwardWebSocket",
    "Host": "0.0.0.0",
    "Port": 8080
  }]
}

# 启动，扫码登录
./Lagrange.Core

3. 安装插件

# 方式1: 通过插件码安装
/plugin install onebot

# 方式2: 手动复制
cp onebot/onebot.py /path/to/xiaoli-cli/plugins/

使用教程

方式一：正向 WebSocket（推荐）

xiaoli-cli 主动连接 OneBot 服务：

# 连接
/onebot connect ws://127.0.0.1:8080

# 查看状态
/onebot status

方式二：反向 WebSocket

xiaoli-cli 监听端口，等 OneBot 主动连接：

# 启动监听（默认 8765 端口）
/onebot listen 8765

然后在 OneBot 配置中设置反向 WebSocket 地址为 ws://你的IP:8765。

配置触发方式

# 只响应 @机器人 的消息（默认）
/onebot config trigger_mode at

# 响应所有消息
/onebot config trigger_mode all

# 响应以特定前缀开头的消息
/onebot config trigger_mode prefix
/onebot config trigger_prefix !

群白名单

# 只在指定群响应
/onebot config group_whitelist 123456789
/onebot config group_whitelist 987654321

手动发消息

# 发私聊
/onebot send private 123456 你好

# 发群聊
/onebot send group 123456789 大家好

命令速查

命令	说明
`/onebot connect <ws_url>`	正向 WebSocket 连接
`/onebot listen [port]`	反向 WebSocket 监听
`/onebot disconnect`	断开连接
`/onebot status`	查看状态
`/onebot config <key> <val>`	配置参数
`/onebot send <type> <id> <msg>`	手动发消息
`/onebot help`	显示帮助

工作原理

QQ 用户发消息
    ↓
OneBot 实现 (Lagrange/go-cqhttp)
    ↓ WebSocket 推送
onebot 插件 (接收消息)
    ↓ 注入上下文
xiaoli-cli AI 引擎 (处理消息)
    ↓ 生成回复
onebot 插件 (发送回复)
    ↓ OneBot API
QQ 用户收到回复

常见问题

Q: 连接不上怎么办？ A: 检查 OneBot 实现是否启动，端口是否正确，防火墙是否放行。

Q: 群里不回复？ A: 检查 trigger_mode 设置，以及是否在群白名单中。

Q: 支持图片/语音吗？ A: 当前版本只处理文本消息。图片消息会提取文本部分处理。

Q: 安全性如何？ A: 建议设置群白名单，不要在公开群暴露。管理员功能可后续扩展。

3.5 KiB Raw Blame History