LLoneBot搭建教程

565

LLOneBot 完整搭建文档（Windows + Linux 桌面版 + Linux Docker 无桌面版）

⚠️风险前置警告

  1. LLOneBot 是 LiteLoaderQQNT 插件，仅支持 QQ NT（QQ9 新版桌面 QQ），不支持旧版 Tim、手机 QQ。
  2. 使用个人 QQ 账号运行机器人存在风控、限制、封号风险！强烈建议使用小号，不要使用日常大号。
  3. 协议标准：OneBot 11，兼容 NoneBot2 / Koishi / 云崽 / OlivOS 等框架。
  4. 项目地址LiteLoaderQQNT：https://github.com/LiteLoaderQQNT/LiteLoaderQQNTLLOneBot：https://github.com/LLOneBot/LLOneBot

目录

  1. Windows 系统搭建（一键脚本 + 手动安装双方案）
  2. Linux 桌面端（Ubuntu/Deepin 图形 QQNT）搭建
  3. Linux 服务器【无图形】Docker 部署（推荐服务器长期运行）
  4. LLOneBot 核心协议配置（正向 WS / 反向 WS，重中之重）
  5. NoneBot2 对接完整配置示例
  6. 常见报错与排坑大全

第一部分：Windows 系统搭建教程

前置要求

Windows10/11，安装 官方原版 QQ NT（QQ9），关闭所有安全软件拦截；完全退出 QQ 再操作。

方案 A：一键脚本安装（新手首选，推荐）

一键工具仓库：https://github.com/super1207/install_llob/releases

  1. 全部关闭 QQ（任务管理器结束所有 QQ 进程）
  2. 下载最新发布文件：Install-LLOneBot.ps1
  3. 文件右键 → 使用 PowerShell 运行；如果提示权限，以管理员身份打开 PowerShell，执行：
Set-ExecutionPolicy RemoteSigned
  1. 脚本自动完成：LiteLoaderQQNT 注入 + LLOneBot 插件安装
  2. 启动 QQ，打开 QQ 设置，侧边出现【LiteLoaderQQNT】即成功

方案 B：手动分步安装（适合一键脚本失败时）

  1. 关闭 QQ，下载 LiteLoaderQQNT：https://github.com/LiteLoaderQQNT/LiteLoaderQQNT/releases
  2. 解压压缩包，将文件夹放入 QQNT 安装根目录 默认路径：C:\Program Files\Tencent\QQNT
  3. 在目录内运行 install.bat 完成注入
  4. 下载 LLOneBot 插件：https://github.com/LLOneBot/LLOneBot/releases 下载 llonebot.zip
  5. 解压插件，不要嵌套文件夹，放入路径： QQNT目录/LiteLoader/plugins/
  6. 启动 QQ → 设置 → LiteLoaderQQNT → 启用 LLOneBot

Windows 验证

打开 QQ 设置 → LiteLoaderQQNT → LLOneBot

访问内置 WebUI：http://localhost:3080，设置访问密码。

第二部分：Linux 桌面系统搭建（Ubuntu / Deepin 有图形界面）

适用：本地装有 Linux 桌面，可以打开 QQ 图形客户端

1. 安装官方 Linux QQ NT（AppImage 版本）

前往腾讯官网下载 Linux QQ AppImage，赋予执行权限运行。

2. 一键安装 LiteLoaderQQNT

打开终端执行脚本：

bash <(curl -s -L "https://gitcode.com/gh_mirrors/li/LiteLoaderQQNT_Install/raw/main/install.sh")

脚本自动识别 QQ 路径，完成注入。

3. 安装 LLOneBot 插件

  1. 下载 llonebot.zip https://github.com/LLOneBot/LLOneBot/releases
  2. 插件目录路径（Linux QQNT）
~/.config/QQ/LiteLoader/plugins/
  1. 将解压后的 llonebot 文件夹放入上面路径

⚠️文件夹名称不能多层嵌套！

4. 启动 QQ

打开 QQ → 设置 → LiteLoaderQQNT → LLOneBot，打开 WebUI 配置 http://127.0.0.1:3080

第三部分：Linux 服务器【无图形界面】Docker 部署（服务器首选）

无需桌面，容器内置 VNC 网页端扫码登录 QQ

1. 先安装 Docker（如未安装）

curl -fsSL get.docker.com -o get-docker.sh
sudo sh get-docker.sh --mirror Aliyun

2. 启动 LLOneBot 容器（复制直接运行）

sudo docker run -d \
  --name llonebot \
  --restart=unless-stopped \
  -p 3000:3000 \
  -p 3001:3001 \
  -p 3080:3080 \
  -p 7081:7081 \
  initialencounter/llonebot:latest

端口说明：

  • 7081：网页 VNC，浏览器打开 服务器IP:7081 扫码登录 QQ
  • 3080：LLOneBot Web 管理面板
  • 3000：HTTP API
  • 3001：正向 WebSocket

3. 防火墙放行端口（必须操作！）

sudo ufw allow 3000/tcp
sudo ufw allow 3001/tcp
sudo ufw allow 3080/tcp
sudo ufw allow 7081/tcp

常用 docker 管理命令

# 停止容器
docker stop llonebot
# 重启容器
docker restart llonebot
# 查看日志
docker logs -f llonebot
# 删除容器（数据清空）
docker rm llonebot

登录流程：浏览器访问 服务器IP:7081 → 打开 QQ →扫码登录 → 打开 QQ 设置配置 LLOneBot

第四部分：LLOneBot 核心连接配置（重中之重！90% 人踩坑）

打开 LLOneBot WebUI http://localhost:3080

Token：自定义一串字符，LLOneBot 和机器人框架必须保持完全一致

两种连接模式，二选一

模式 1：反向 WebSocket【推荐！】

✅ LLOneBot 主动发起连接，适合本地部署、服务器跨机部署，不需要开放入站端口

适用：NoneBot2、Koishi

配置项：

  • ✅ 启用反向 WebSocket
  • 反向 WS 地址示例（本地 NoneBot）
ws://127.0.0.1:8080/onebot/v11/ws

如果机器人框架在另一台服务器：

ws://框架服务器IP:8080/onebot/v11/ws

模式 2：正向 WebSocket

✅ 机器人框架主动连接 LLOneBot

LLOneBot 地址：ws://127.0.0.1:3001

服务器部署需要防火墙放行 3001 端口

重要提醒

不要同时开启大量反向 / 正向连接；配置完成重启 QQ（重启 LLOneBot）生效

第五部分：对接 NoneBot2 完整配置示例

1. 安装适配器

pip install nonebot-adapter-onebot

2. .env 文件配置（反向 WS 场景，最常用）

DRIVER=nonebot.drivers.websockets
HOST=0.0.0.0
PORT=8080
ONEBOT_ACCESS_TOKEN=自定义你的密码（和LLOneBot一致）
ONEBOT_WS_URLS=[]

逻辑：NoneBot 开启 8080 端口等待连接 → LLOneBot 反向 ws 主动连接上来

正向 WS 模式 .env 参考

DRIVER=nonebot.drivers.websockets
ONEBOT_WS_URLS=["ws://127.0.0.1:3001"]
ONEBOT_ACCESS_TOKEN=自定义你的密码

启动机器人

nb run

日志出现 WebSocket connection established 代表连接成功。

第六部分：常见问题与排坑

1. QQ 设置里看不到 LiteLoaderQQNT

  • Windows：没有完全关闭 QQ；没有管理员权限运行注入脚本；QQ 版本过高存在校验
  • Linux：QQ 路径错误，重新执行一键安装脚本
  • 解决：彻底结束所有 QQ 进程，重新注入

2. WebUI http://127.0.0.1:3080打不开

  1. 确认 LLOneBot 插件已经启用
  2. 重启 QQ
  3. 关闭系统代理、防火墙
  4. Docker 部署确认端口映射正确

3. WebSocket 一直连接失败

❌ 最常见错误：正向、反向 WS 搞混！

  • 反向 WS：LLOneBot 填写框架地址
  • 正向 WS：框架填写 LLOneBot 地址 检查 token 两边完全一致；检查 IP、端口、路径 /onebot/v11/ws 不能漏写

4. 频繁掉线、消息收不全、风控

  1. 不要大号登录机器人
  2. 不要短时间大量群发消息
  3. 避免频繁重启 QQ
  4. Docker 环境稳定性普遍高于 Windows 桌面运行

5. 图片 / 语音无法发送

确认系统安装 ffmpeg；Docker 镜像自带 ffmpeg，一般无需额外处理

6. Linux Docker VNC 无法访问

检查服务器防火墙放行 7081 端口；浏览器不要开启代理。

补充链接汇总（方便复制）

LiteLoaderQQNT 一键安装脚本地址：

https://gitcode.com/gh_mirrors/li/LiteLoaderQQNT_Install/raw/main/install.sh

install_llob Windows 一键包发布页：

https://github.com/super1207/install_llob/releases

LLOneBot Releases：

https://github.com/LLOneBot/LLOneBot/releases

如果你需要，我可以把这份文档导出成纯文本无格式版本，你直接复制保存为 .md 文件。

纯文本无格式版本

LLOneBot 完整搭建文档（Windows + Linux 桌面 + Linux Docker 无桌面｜纯文本无格式）

⚠️风险前置警告

  1. LLOneBot 是 LiteLoaderQQNT 插件，仅支持 QQ NT（QQ9 新版桌面 QQ），不支持旧版 Tim、手机 QQ。
  2. 使用个人 QQ 账号运行机器人存在风控、限制、封号风险！强烈建议使用小号，不要使用日常大号。
  3. 协议标准：OneBot 11，兼容 NoneBot2 / Koishi / 云崽 / OlivOS 等框架。
  4. 项目地址 LiteLoaderQQNT：https://github.com/LiteLoaderQQNT/LiteLoaderQQNT LLOneBot：https://github.com/LLOneBot/LLOneBot

目录

  1. Windows 系统搭建（一键脚本 + 手动安装双方案）
  2. Linux 桌面系统搭建（Ubuntu/Deepin 图形 QQNT）
  3. Linux 服务器【无图形】Docker 部署（服务器长期运行推荐）
  4. LLOneBot 核心协议配置（正向 WS / 反向 WS）
  5. NoneBot2 对接完整配置示例
  6. 常见报错与排坑大全

=====================================================================

第一部分：Windows 系统搭建教程

前置要求

Windows10/11，安装官方原版 QQ NT（QQ9），关闭所有安全软件拦截；完全退出 QQ 再操作。

方案 A：一键脚本安装（新手首选）

一键工具仓库：https://github.com/super1207/install_llob/releases

  1. 全部关闭 QQ，任务管理器结束所有 QQ 进程
  2. 下载最新发布文件：Install-LLOneBot.ps1
  3. 文件右键 → 使用 PowerShell 运行；权限不足时，管理员打开 PowerShell 执行： Set-ExecutionPolicy RemoteSigned
  4. 脚本自动完成 LiteLoaderQQNT 注入 + LLOneBot 插件安装
  5. 启动 QQ，打开 QQ 设置，侧边出现【LiteLoaderQQNT】即成功

方案 B：手动分步安装（一键脚本失败备选）

  1. 关闭 QQ，下载 LiteLoaderQQNT：https://github.com/LiteLoaderQQNT/LiteLoaderQQNT/releases
  2. 解压压缩包，将文件夹放入 QQNT 安装根目录 默认路径：C:\Program Files\Tencent\QQNT
  3. 在目录内运行 install.bat 完成注入
  4. 下载 LLOneBot 插件：https://github.com/LLOneBot/LLOneBot/releases，下载 llonebot.zip
  5. 解压插件，禁止嵌套文件夹，放入路径： QQNT 目录 / LiteLoader/plugins/
  6. 启动 QQ → 设置 → LiteLoaderQQNT → 启用 LLOneBot

Windows 验证

打开 QQ 设置 → LiteLoaderQQNT → LLOneBot

访问内置 WebUI：http://localhost:3080，设置访问密码。

=====================================================================

第二部分：Linux 桌面系统搭建（Ubuntu / Deepin 有图形界面）

适用：本地装有 Linux 桌面，可以打开 QQ 图形客户端

  1. 安装官方 Linux QQ NT（AppImage 版本） 前往腾讯官网下载 Linux QQ AppImage，赋予执行权限运行。
  2. 一键安装 LiteLoaderQQNT 打开终端执行脚本： bash <(curl -s -L “https://gitcode.com/gh_mirrors/li/LiteLoaderQQNT_Install/raw/main/install.sh“) 脚本自动识别 QQ 路径，完成注入。
  3. 安装 LLOneBot 插件
  4. 下载 llonebot.zip https://github.com/LLOneBot/LLOneBot/releases
  5. 插件目录路径（Linux QQNT） ~/.config/QQ/LiteLoader/plugins/
  6. 将解压后的 llonebot 文件夹放入上面路径 ⚠️文件夹名称不能多层嵌套！
  7. 启动 QQ 打开 QQ → 设置 → LiteLoaderQQNT → LLOneBot，打开 WebUI 配置 http://127.0.0.1:3080

=====================================================================

第三部分：Linux 服务器【无图形界面】Docker 部署（服务器首选）

无需桌面，容器内置 VNC 网页端扫码登录 QQ

  1. 安装 Docker（未安装时执行） curl -fsSL get.docker.com -o get-docker.sh sudo sh get-docker.sh –mirror Aliyun
  2. 启动 LLOneBot 容器（直接复制运行） sudo docker run -d –name llonebot –restart=unless-stopped -p 3000:3000 -p 3001:3001 -p 3080:3080 -p 7081:7081 initialencounter/llonebot:latest

端口说明：

7081：网页 VNC，浏览器打开 服务器 IP:7081 扫码登录 QQ

3080：LLOneBot Web 管理面板

3000：HTTP API

3001：正向 WebSocket

  1. 防火墙放行端口（必须操作） sudo ufw allow 3000/tcp sudo ufw allow 3001/tcp sudo ufw allow 3080/tcp sudo ufw allow 7081/tcp

常用 docker 管理命令

停止容器

docker stop llonebot

重启容器

docker restart llonebot

实时查看日志

docker logs -f llonebot

删除容器（所有数据清空）

docker rm llonebot

登录流程：浏览器访问 服务器 IP:7081 → 打开 QQ →扫码登录 → 打开 QQ 设置配置 LLOneBot

=====================================================================

第四部分：LLOneBot 核心连接配置（重中之重）

打开 LLOneBot WebUI http://localhost:3080

Token：自定义一串字符，LLOneBot 和机器人框架必须保持完全一致

两种连接模式，二选一

模式 1：反向 WebSocket【推荐】

LLOneBot 主动发起连接，适合本地部署、服务器跨机部署，不需要开放入站端口

适用：NoneBot2、Koishi

配置项：

√ 启用反向 WebSocket

反向 WS 地址示例（本地 NoneBot）

ws://127.0.0.1:8080/onebot/v11/ws

机器人框架在另一台服务器填写：

ws:// 框架服务器 IP:8080/onebot/v11/ws

模式 2：正向 WebSocket

机器人框架主动连接 LLOneBot

LLOneBot 地址：ws://127.0.0.1:3001

服务器部署需要防火墙放行 3001 端口

重要提醒

不要同时开启大量反向 / 正向连接；配置完成重启 QQ（重启 LLOneBot）生效

=====================================================================

第五部分：对接 NoneBot2 完整配置示例

  1. 安装适配器 pip install nonebot-adapter-onebot
  2. .env 文件配置（反向 WS 场景，最常用） DRIVER=nonebot.drivers.websockets HOST=0.0.0.0 PORT=8080 ONEBOT_ACCESS_TOKEN = 自定义你的密码（和 LLOneBot 一致） ONEBOT_WS_URLS=[] 逻辑：NoneBot 开启 8080 端口等待连接 → LLOneBot 反向 ws 主动连接上来

正向 WS 模式 .env 参考

DRIVER=nonebot.drivers.websockets

ONEBOT_WS_URLS=[“ws://127.0.0.1:3001”]

ONEBOT_ACCESS_TOKEN = 自定义你的密码

启动机器人

nb run

日志出现 WebSocket connection established 代表连接成功。

=====================================================================

第六部分：常见问题与排坑

  1. QQ 设置里看不到 LiteLoaderQQNT Windows：没有完全关闭 QQ；没有管理员权限运行注入脚本；QQ 版本过高存在校验 Linux：QQ 路径错误，重新执行一键安装脚本 解决：彻底结束所有 QQ 进程，重新注入
  2. WebUI http://127.0.0.1:3080打不开
  3. 确认 LLOneBot 插件已经启用
  4. 重启 QQ
  5. 关闭系统代理、防火墙
  6. Docker 部署确认端口映射正确
  7. WebSocket 一直连接失败 最常见错误：正向、反向 WS 搞混！ 反向 WS：LLOneBot 填写框架地址 正向 WS：框架填写 LLOneBot 地址 检查 token 两边完全一致；检查 IP、端口、路径 /onebot/v11/ws 不能漏写
  8. 频繁掉线、消息收不全、风控
  9. 不要大号登录机器人
  10. 不要短时间大量群发消息
  11. 避免频繁重启 QQ
  12. Docker 环境稳定性普遍高于 Windows 桌面运行
  13. 图片 / 语音无法发送 确认系统安装 ffmpeg；Docker 镜像自带 ffmpeg，一般无需额外处理
  14. Linux Docker VNC 无法访问 检查服务器防火墙放行 7081 端口；浏览器不要开启代理。

=====================================================================

链接汇总（直接复制）

LiteLoaderQQNT 一键安装脚本地址：

https://gitcode.com/gh_mirrors/li/LiteLoaderQQNT_Install/raw/main/install.sh

install_llob Windows 一键包发布页：

https://github.com/super1207/install_llob/releases

LLOneBot Releases：

https://github.com/LLOneBot/LLOneBot/releases

THE END
机器人教程
喜欢就支持一下吧
点赞5 分享
一只冷漠的狐狸的头像-玄墨染青龙至尊
wordpress搭建教程-玄墨染
wordpress搭建教程
wordpress搭建教程
14天前 61
奈斯主题全解析：不同风格适合哪些网站与人群-玄墨染
奈斯主题全解析：不同风格适合哪些网站与人群
奈斯主题全解析：不同风格适合哪些网站与人群
12天前 60
字库星球飞扬体-玄墨染
字库星球飞扬体
字库星球飞扬体
14天前 50
XiunoBBS-玄墨染
XiunoBBS
XiunoBBS
14天前 50
凌哲QQ_BOT云平台使用教程-玄墨染
凌哲QQ_BOT云平台使用教程
凌哲QQ_BOT云平台使用教程
6天前 47
Discuz搭建教程-玄墨染
Discuz搭建教程
Discuz搭建教程
14天前 44
相关推荐
LLoneBot搭建教程-玄墨染
LLoneBot搭建教程
LLoneBot搭建教程
14天前 56
凌哲QQ_BOT云平台使用教程-玄墨染
凌哲QQ_BOT云平台使用教程
凌哲QQ_BOT云平台使用教程
6天前 47
云崽机器人搭建教程-玄墨染
云崽机器人搭建教程
云崽机器人搭建教程
14天前 38
AstrBot搭建教程-玄墨染
AstrBot搭建教程
AstrBot搭建教程
13天前 35