跳转到主要内容
YumeBot 是基于 NapCatQQ 的 QQ 机器人框架，让您的 QQ 机器人快速拥有强大功能。

​
准备工作

开始之前，请确保您有：
  • Java 17 或更高版本（检查：java -version）
  • 一个 QQ 小号（用作机器人账号，避免使用主号）
  • NapCatQQ（QQ 机器人框架）

​
一、配置 NapCatQQ

​
1. 下载并安装

访问 NapCatQQ Release 下载最新版本。

​
2. 登录机器人账号

启动 NapCatQQ，使用您的机器人 QQ 号登录。
建议使用小号作为机器人账号，避免风控。

​
3. 配置 WebSocket 连接

在 NapCatQQ 中配置 WebSocket 客户端：
1

打开网络配置

进入 NapCatQQ 设置 → 网络配置
2

新建 WebSocket 客户端

点击”新建” → 选择”WebSocket 客户端”
3

填写连接地址

填写：ws://127.0.0.1:5795/ws
4

保存并连接

保存配置，确保连接状态正常

​
二、下载 YumeBot

打开终端，克隆 YumeBot 项目： 
git clone https://github.com/YumeYuka/YumeBot.git
cd YumeBot

​
三、配置 YumeBot

在项目 config 目录下创建 config.json 文件： 
{
  "bot": {
    "selfId": 123456789,
    "nickname": "YumeBot"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 5795,
    "accessToken": "",
    "timeout": 30000
  },
  "log": {
    "level": "INFO",
    "enableConsole": true,
    "enableFile": true,
    "logPath": "./logs",
    "maxFileSize": 10485760,
    "maxFiles": 7
  }
}
配置说明
  • selfId: 您的机器人 QQ 号
  • nickname: 机器人昵称
  • host 和 port: 必须与 NapCatQQ 的 WebSocket 地址一致

​
四、启动机器人

在项目目录下运行： 
.\gradlew.bat run
首次运行会下载依赖，需要等待几分钟。

​
启动成功

看到以下日志说明启动成功： 
[INFO] YumeBot 启动中...
[INFO] 正在连接到 NapCatQQ: ws://127.0.0.1:5795
[INFO] WebSocket 连接成功
[INFO] ═══════════════════════════
[INFO]   示例插件已加载
[INFO]   Example Plugin Loaded
[INFO] ═══════════════════════════
[INFO] YumeBot 启动完成！

​
五、测试机器人

机器人启动后，YumeBot 已经自带了示例插件。

​
测试示例插件

在机器人所在的 QQ 群中发送：
发送: 你好机器人回复: @你 你好！我是 YumeBot 示例插件！

​
使用更多插件

YumeBot 自带了多个实用插件，无需额外配置即可使用！

示例插件

问候、时间查询、信息展示

原神插件

角色查询、武器资料、游戏资讯
想了解更多插件？

探索插件市场

查看所有可用插件，发现更多功能

​
常见问题

可能原因：
  • NapCatQQ 未启动或未正常登录
  • WebSocket 地址配置错误
  • 端口 5795 被其他程序占用
解决方法：
  1. 确认 NapCatQQ 正在运行且已登录
  2. 检查 config.json 中的 host 和 port
  3. 确认 NapCatQQ 的 WebSocket 客户端配置正确
  4. 检查防火墙是否阻止连接
可能原因：
  • 机器人未加入测试群
  • 机器人被禁言
  • 关键词不匹配
解决方法：
  1. 确认机器人已加入群聊
  2. 检查机器人是否被禁言
  3. 尝试发送其他命令测试
  4. 查看控制台日志排查问题
可能原因：
  • 未安装 Java
  • Java 版本过低
  • 环境变量未配置
解决方法：
  1. 下载安装 Java 17+
  2. 配置环境变量
  3. 重启终端后再试
可能原因：
  • 网络问题
  • Maven 仓库连接慢
解决方法：
  1. 等待首次构建完成（仅首次较慢）
  2. 配置国内 Maven 镜像
  3. 使用稳定的网络环境

​
接下来做什么？

探索插件市场

查看所有可用插件，让机器人功能更丰富

开发自己的插件

学习插件开发，创建专属功能

查看 API 文档

了解完整的 API 和功能

查看示例代码

学习更多实用的代码示例
推荐流程：先测试自带插件 → 探索插件市场 → 根据需求选择插件 → 尝试开发自己的插件