启动器部署(推荐)
这是官方最推荐的一条路:启动器(Neo-MoFox Launcher Next)是一个桌面应用,把 Neo-MoFox 的安装、更新、运行、日志排查全部收进一个图形窗口里。你只需要点点鼠标、照着向导填几个空,就能把机器人养起来——全程不需要敲命令。
适用平台:Windows 和 Linux 电脑。本篇是「一条龙」教程,从下载到 Bot 上线都在这里完成。让 Bot 连上 QQ 需要「平台适配器」(也叫协议端),本篇以 SnowLuma 为例。注意:SnowLuma 与 NapCat 的上游仓库已归档,启动器暂时无法一键下载安装它们——安装实例时请选「不安装平台」,协议端需要自己寻找下载,装好后到实例的「修改实例信息」里指定(见第三步与第六步)。
开始前,你需要准备

第一步:下载并安装启动器
启动器在 GitHub 的 Releases(发行版)页面下载。选最新的 nightly 预发布版本(标签形如 nightly-日期),然后按你的系统选文件。
- 在浏览器打开启动器的 Releases 页面:github.com/MoFox-Studio/Neo-MoFox-Launcher-Next/releases。
- 在版本列表里点开最新的 nightly 预发布版本(标题带
nightly-日期字样)。 - 往下找到 Assets(附件)区域,点开它,按下面的表格挑一个文件下载。
nightly 是测试版本
nightly 是自动构建出来的预发布测试版本,更新很勤但可能不稳定,仅供体验使用。遇到小毛病属正常现象,更新后多数会自己好。
按你的系统接着做:
下载哪个文件:
| 你的电脑 | 下载这个文件 |
|---|---|
| Windows 10/11 64 位(绝大多数人) | Neo-MoFox-Launcher-<日期>-nightly-win-x64-setup.exe(安装版,推荐)或 ...-portable.exe(便携版) |
| Windows x86(32 位)或 ARM 笔记本 | 文件名里带 win-ia32 或 win-arm64 的版本 |
装好后怎么打开:
- 双击下载的
setup.exe,会弹出安装向导,一路点下去即可,中途可以自选安装目录。 - 便携版(
portable.exe)更简单——不用安装,双击就能用,适合不想装软件的同学。

第二步:第一次打开,完成初始设置
装好后打开启动器,会先进入「初始设置」流程(也叫 OOBE,就是「开箱引导」——像新手机开机时的引导一样)。它一共五小步,做完一次以后就不会再出现。
1. 欢迎
你会看到「欢迎使用 Neo-MoFox」的页面。点 开始 即可。

2. 依赖检查与一键安装
机器人是用 Python 写的,跑起来还需要几个小工具。启动器会自动帮你检查这三样:
- Python —— 机器人程序本身使用的编程语言环境;
- uv —— Python 的依赖管理工具,负责装齐机器人需要的「零件」;
- Git —— 版本管理工具,负责下载和更新机器人代码。
每一项右侧都会标注 已安装 或 未安装。
- 三项都齐了:直接点 继续。
- 有缺的:点 安装缺失依赖,进度走完后每项会变成 已安装。
三项都齐时页面如下,点 继续 进入下一步:

有缺项时会出现「发现缺失依赖」区块,点 安装缺失依赖 一键补齐:

Linux 用户注意:可能需要输入 sudo 密码
在 Linux 上安装系统级依赖时,启动器会请你输入 sudo 密码(也就是你的管理员密码,输入时屏幕不显示是正常的)。密码只在本次安装期间保留在内存里,装完立即清除,不会写进硬盘。
另外,装完依赖点 继续 时,如果刚实际安装过东西,会弹窗提示你重启电脑——因为部分新装的工具要重启后才生效。点 退出启动器,重启电脑,再重新打开启动器,它会接着上次的位置继续,不用重做。
暂不安装会退出启动器
如果点 暂不安装,启动器会直接退出,要求你自行装好依赖再回来。除非你有特殊原因,否则建议直接点 安装缺失依赖 一键搞定。
3. 旧版数据迁移(没有旧版会自动跳过)
如果你以前用过旧版启动器,这一步会检测到旧的数据目录,并询问要不要把里面的实例搬过来:
- 页面会显示旧目录路径和实例数量,点 预览导入;
- 会列出每条实例记录,有冲突的条目会标记出来并自动跳过;
- 确认无误后点 确认导入,完成。
放心,导入只读取旧目录,不会改动旧目录里的任何文件。如果你没用过旧版启动器,这一步会自动跳过,直接进下一页。

4. 偏好设置
挑个外观:主题模式(跟随系统 / 浅色 / 深色)、主题颜色,还可以设置一张壁纸。最重要的是 默认安装目录——以后装机器人实例时默认放在这里,建议选个空间宽裕的盘。这些以后都能在设置页改,先随便选也不影响使用。

5. 完成
最后一页会汇总各依赖的检测结果,确认都是绿色勾后点 完成,就进入启动器主界面了。

第三步:创建第一个实例
「实例」就是一套独立的机器人。你可以养多个实例(比如两个不同 QQ 号的 Bot),互不干扰。
- 在启动器左侧导航栏找到 加号(+)按钮,点它;
- 选择 新鲜安装(另一项「手动导入」是用来登记电脑里已有的 Neo-MoFox 目录的,新手用不上);
- 进入安装向导,一共四个阶段:协议 → 配置 → 确认 → 安装。

1. 阅读并同意协议
向导会展示 MoFox 的用户许可协议(EULA)和隐私政策两份文本。看完勾选同意,点继续进入配置。

2. 配置:五个区块,一次填一个
配置阶段有五个可展开的区块,右上角会显示「几 / 5 已就绪」,填好一个收起一个即可。

区块一:实例身份
给机器人建档,四个字段都要填:
- 实例名称:在启动器里标识这套实例的名字,1-32 个字符,比如
我的第一只MoFox; - Bot 昵称:机器人在聊天里显示的昵称,1-32 个字符;
- Bot QQ 号:机器人用哪个 QQ 号登录,5-12 位纯数字。强烈建议用小号,避免大号有风险;
- 主人 QQ 号:你自己的 QQ 号,填了它,机器人才认得谁是老板。

区块二:模型服务
这里是给机器人的「大脑」配钥匙——API Key(必填):
- 在 API Key 输入框里粘贴你的密钥(默认使用硅基流动平台,密钥通常以
sk-开头); - 点旁边的 获取密钥 按钮,会直接打开硅基流动的注册/获取页面,注册后把生成的密钥复制过来;
- 输入框右侧有个小眼睛图标,点它可以显示明文,核对有没有粘贴错。
想用别家模型?(技术细节)
向导里只填 Key,默认对接硅基流动(接口地址 https://api.siliconflow.cn/v1)。安装时启动器会把你填的 Key 写进实例的模型配置文件 model.toml 的第一个模型提供商条目里。如果你想让机器人接别家的模型服务,装好后编辑实例目录下 mofox/config/model.toml,修改对应提供商的 base_url 和 api_key 即可。

区块三:平台与网络
安装平台:下拉框选适配器。「适配器」就是负责连 QQ 的那部分程序,内置两种:
SnowLuma —— 跨平台轻量,自带网页管理界面(WebUI),本篇以它为例;
NapCat —— 仅支持 Windows,本篇不展开它的用法,选它的话请自行参考 NapCat 的相关文档;
不安装平台 —— 只装机器人核心,不下载任何协议端。本教程请选这一项:下拉框下方的红色提示会告诉你,NapCat 与 SnowLuma 的上游仓库已归档,这两个平台暂时无法通过启动器直接安装。协议端需要你自己准备好,安装完实例后再到「更多 → 修改实例信息」里指定。

更新通道:选机器人跟哪个 分支 走。稳定版 (main) 是大众用的稳当版本;开发版 (dev) 能第一时间体验新功能,但可能不稳。新手选稳定版 (main) 即可。
WebSocket 端口:机器人内部通信用的「门牌号」,默认
8095,保持默认别动就行——协议端的 WS 客户端会连到这个端口(除非提示端口被占用,再改成别的 1024-65535 之间的数字)。

区块四:可选组件
这里可以勾选 安装 WebUI(Web 管理控制台)——一个用浏览器打开的可视化管理界面,支持一键更新等操作,默认已勾选,推荐保留。
勾选后会出现 WebUI / HTTP 路由访问密钥:
- 点 随机生成 按钮会自动生成一个密钥并复制到剪贴板;
- 这个密钥是进 WebUI 的「门禁卡」,请保存好,至少 8 位。
WebUI 装好即有
勾选安装 WebUI 后,它就是实例的一部分,装完就能用。具体怎么访问、怎么用,见 WebUI 文档。

区块五:安装位置
选择实例文件放在哪个目录:
- 默认会预填你在 OOBE 里设置的 默认安装目录,直接用就行;
- 也可以点浏览按钮换一个地方。启动器会检查这个目录能不能写入、硬盘剩余空间够不够;
- 装好后,实例文件在
你选的目录/<实例 ID>/下面,其中mofox是机器人本体。这次没有安装平台,所以不会有platform目录——协议端的目录稍后在「修改实例信息」里指向你自己准备的那份。

3. 确认
五个区块都亮起「已就绪」后,点继续进入确认页。这里用卡片汇总了你填的所有信息(实例信息、网络配置、安装选项、API Key、安装目录),最后核对一遍,没问题就点 开始安装。

4. 看进度
安装开始后,页面会实时显示进度和日志,后台依次执行这几件事:
- 安装 MoFox —— 下载机器人源码、同步 Python 依赖、生成配置文件;
- 安装平台 —— 只有上一步选了具体平台才会执行;本教程选了「不安装平台」,这一步会跳过;
- 安装 WebUI —— 下载 WebUI 插件包(如果勾选了);
- 配置 —— 把你填的 QQ 号、API Key、端口等写进配置文件;
- 完成 —— 把成品搬进实例目录,收工。
整个流程通常几分钟,取决于网速。中途失败不用重来:向导会停在失败的那一步,点重试就能从断点继续。安装过程中关掉窗口会取消安装并清理临时文件。
密钥是明文保存的
机器人按自己的配置格式保存密钥,API Key 和 WebUI 密钥会以明文写进实例目录里的配置文件。请妥善保护你的实例目录,不要随手把整个目录发给别人。

第四步:启动实例(先只启动 MoFox)
- 点左侧导航的 实例,进入实例列表页。你会看到刚才装的实例卡片,上面标着状态(运行中 / 已停止 / 启动中 / 错误);
- 点卡片上的 启动实例 按钮;
- 状态变成 运行中 后,再打开日志确认主程序正常启动。
此时实例里还没有协议端,平台的启动按钮和日志标签会显示为「未安装平台」,这是正常的——下一步就来补上。
想看日志:点卡片上的 查看日志,进入日志页。装了协议端之后会有两个标签页——一个是 MoFox(机器人本体的日志),一个是协议端(如 SnowLuma)的日志。每个进程还能分别启动、停止、重启。日志页支持关键词搜索(快捷键 Ctrl+Shift+F)、自动滚动和一键导出,排错非常好用。


第五步:添加协议端(自己准备 SnowLuma)
因为 SnowLuma / NapCat 的上游仓库已归档,启动器不再替你下载协议端。你需要自己找到可用的 SnowLuma 安装包(社区分流、历史镜像等都可以,请自行甄别来源是否可信),解压到本地一个固定的目录,例如 D:\MoFox\snowluma 或 /opt/snowluma。记住这个目录,下一步要用。
安装包要能被启动器识别。SnowLuma 的完整发行包解压后,根目录里应当能看到 index.mjs,以及 launcher.bat(Windows)或 launcher.sh(Linux)之类的启动入口——启动器就是靠这些文件判断「这是一个有效的平台目录」的。别把压缩包解出多套嵌套目录(例如解压后是 snowluma/SnowLuma-v1.x/... 这种),路径要直接指向含有 index.mjs 的那一层。
平台支持范围
SnowLuma 支持 Windows x64 和 Linux x64/arm64。Windows 和 Linux 桌面都能用;Linux 无头服务器(没有桌面、看不到 QQ 窗口)需要 VNC 等额外设置,属于进阶玩法。NapCat 仅支持 Windows x64。
第六步:在管理实例里改平台种类与路径
回到 实例 列表,在实例卡片右侧点 管理实例(滑杆图标)进入实例管理页;
在左侧点 更多,找到 修改实例信息,点右侧的 修改;
在弹出的「修改实例信息」对话框里:
- 平台种类:从「不安装平台」改成 SnowLuma(或 NapCat);
- 平台路径:点右侧的文件夹图标,选择第五步解压出来的协议端目录;也可以直接把路径粘进输入框。选完启动器会自动校验,不是有效目录时会提示「不是有效的平台安装目录」;
- 主程序路径与虚拟环境路径保持原样即可。

点 保存。启动器会自动停止相关进程并写入新的平台信息,保存成功后卡片上会显示
SnowLuma · 版本号。
平台路径还能随时改
以后换了协议端的安装位置,或想换成 NapCat,都可以再进这里改。注意切换平台种类时会清空平台路径,需要重新选一次目录。
第七步:QQ 登录,让 Bot 上线
协议端挂上之后,启动实例时它就会和你填的 QQ 号一起跑起来。第一次还需要登录 QQ——就像手机开机了还没插卡。以 SnowLuma 为例:
- 确认桌面版 QQ 已经打开,停在登录窗口就行。SnowLuma 的工作方式是自动发现正在运行的 QQ 进程并注入 hook,所以 QQ 得先开着;
- 点实例卡片上的 启动实例,再点 查看日志,切到 SnowLuma 标签。找到
listening ...后的 WebUI 地址(默认http://127.0.0.1:5099,以本机日志为准),以及initial credentials: user=admin password=...这行 初始登录凭据。复制password=后的值,下一步要用;

图中使用演示实例与示例密码,登录时请复制你本机日志中的实际值。初始凭据只在终端输出,不会写入 SnowLuma 的日志文件。
- 点日志里的那个网址(链接可以直接点,会打开浏览器;点不动就复制到浏览器)。下图的登录页只有一个 「输入访问令牌」 框,把刚才
password=后的值粘贴进去,点 进入控制台,无需填写用户名。登录后按提示修改初始密码;没有完成改密就重启时,SnowLuma 会重新生成密码,需要再从日志中取一次;

- 在电脑上打开的 QQ 登录窗口里,用手机 QQ 扫码登录——注意:要用 Bot 的那个 QQ 号(小号)登录,不是扫你自己的大号;
- 扫码成功后,回到 SnowLuma WebUI 的「进程注入」页,显示「qq 已在线」就说明登录成功。

这次得自己配一次 WS 客户端
安装向导选了「不安装平台」,启动器没有在安装时替你写好 WS 客户端。所以需要在 SnowLuma 的「节点配置 → WS 客户端」里点 新建 WS 客户端,「目标 URL」填 ws://127.0.0.1:8095(8095 是安装向导里的 WebSocket 端口,改过就填改后的),其他保持默认,保存。列表里显示「已连接」就通了。


顺便把 Bot 的 QQ 号填进适配器配置
安装时没选平台,启动器也没写 OneBot 适配器的 [bot] 小节。第一次启动后打开实例配置文件夹里的 config/plugins/onebot_adapter/config.toml,把 [bot] 下的 qq_id(Bot 的 QQ 号)和 qq_nickname(昵称)填上,保存后重启 Bot 生效。
第八步:验证 Bot 活着
最简单的办法——去聊天:
- 拉一个小群,把 Bot 的 QQ 号和你的主人号都拉进去;
- 在群里 @ 机器人昵称,随便说句话;
- 它回话了?恭喜,Bot 正式上线!🎉
也可以直接用主人号私聊机器人,能收到回复同样说明在线。
第九步:设置主人 QQ 号
好消息:你大概率已经完成了。安装向导的「实例身份」区块里填过的 主人 QQ 号,启动器会自动写进实例的配置文件 core.toml 的 [permissions] 小节(格式是 owner_list = ["qq:你的QQ号"])。启动器目前没有单独修改主人的界面,想换主人或加主人时,手动改这个文件即可:
- 实例卡片 → 管理,在实例管理页切到「更多」分区,点 打开配置文件夹——它会直接打开机器人安装目录下的
config文件夹; - 用记事本或任意文本编辑器打开里面的
core.toml; - 找到
[permissions]下面的owner_list,按["qq:123456789"]的格式填写 QQ 号(多个主人用英文逗号隔开,如["qq:123456789", "qq:987654321"]); - 保存文件,然后在启动器里重启实例让新配置生效。
实例管理:找到配置文件和常用工具
后面的配置教程经常提到 config/core.toml、config/model.toml 或 config/plugins/。对于启动器用户,这些路径都以当前实例的 Neo-MoFox 主程序目录为起点。每个实例各有一份配置,先确认自己打开的是要修改的那个实例。

从启动器打开配置文件夹
- 点左侧 实例,找到目标实例卡片,点 管理实例(滑杆图标)。
- 在实例管理页左侧点 更多。
- 找到 打开配置文件夹,点这一行右侧的 打开。系统文件管理器会打开该实例主程序目录下的
config文件夹。 - 按后续教程选择其中的
core.toml、model.toml或plugins子目录;编辑并保存后,按对应教程重启 Bot 或让配置生效。

如果不知道实例放在哪里,可以切到 信息查看,查看 MoFox 安装目录;点目录条目可以复制路径。新鲜安装通常是 你选的安装根目录/<实例 ID>/mofox/,配置则在它的 config/ 里。手动导入的实例以信息页显示的目录为准。
例如,「更多」截图中的演示实例使用 D:\MoFox\docs-demo\mofox 作为主程序目录,教程里的 config/core.toml 对它来说就是 D:\MoFox\docs-demo\mofox\config\core.toml。这个路径仅作说明,实际操作请用自己的实例路径。
「更多」里的几个文件入口
| 入口 | 打开的内容 | 常见用途 |
|---|---|---|
| 打开配置文件夹 | 主程序目录下的 config/ | 改主人、模型、人设和插件配置 |
| 打开插件文件夹 | 主程序目录下的 plugins/ | 查看插件目录,放入 .mfp 插件包 |
| 打开数据文件夹 | 主程序目录下的 data/ | 找到运行数据与数据库,按维护教程备份 |
| 打开实例文件夹 | Neo-MoFox 主程序目录(main.py 所在目录) | 找到项目文件与上述子目录 |
| 打开平台文件夹 | SnowLuma 等平台适配器的安装目录 | 查看协议端自己的配置与文件 |
打开配置文件夹进入的是 Bot 的配置目录;协议端的配置在打开平台文件夹对应的位置。修改模型、人设或 Bot 插件时,按教程进入 Bot 的 config/。如果文件夹不存在,启动器会提示失败,可以先到信息页核对路径和安装状态。
「更多」还提供 修改实例信息(平台种类与安装路径)、收藏实例和 删除实例。删除时会让你选择只移除记录,还是连文件一起删除;这是清理实例的入口,平时改配置用上面的打开按钮即可。
改平台种类或平台路径就走 修改实例信息:打开对话框,把「平台种类」换成 SnowLuma / NapCat,把「平台路径」指向自备的协议端目录,保存即可。详见第六步。如果之前是「不安装平台」,这里填好之后「打开平台文件夹」和日志页的平台标签就会恢复可用。
虚拟环境、终端和更新分别在哪里
虚拟环境:查看该实例的 Python 环境和已安装依赖,搜索并安装指定包版本,也可以查看包信息、升级或卸载依赖。一般安装和更新会自动同步所需依赖;遇到明确的依赖排查步骤时再使用这里的操作。

终端:打开实例的命令行,可以在主程序目录、虚拟环境和平台目录之间切换。这里用于执行命令;查看 Bot 与 SnowLuma 的运行输出,点管理页左下角的 运行日志。

更新:管理主程序分支、提交回退与平台版本,具体步骤见 更新与回滚。

本节配图来自启动器的实际界面,使用演示实例与示例路径、依赖数据,不代表你本机已经安装了图中的软件包。图中演示实例的平台适配器是 NapCat,SnowLuma 实例的「平台目录」对应 SnowLuma 自己的安装目录。
装好之后想干嘛
到这里,你的 Bot 已经完整上线了。接下来可以:
- 给 Bot 更新版本或切换 main / dev 分支 → 更新(启动器里点几下就能完成,见下一节)
- 了解更新通道 main 和 dev 的区别 → 更新通道
- 用浏览器管理 Bot → WebUI
- 给 Bot 装插件扩展功能 → 插件
- 调教 Bot 的人设 → 人设
更新与切换版本(简述)
这些都在启动器里完成,不用命令行:
- 实例管理 → 更新 分区:主程序目录是个 Git 仓库,这里能看当前分支和提交、落后多少个版本,支持一键拉取更新、切换分支、回退到指定提交;
- 平台适配器 也在同一分区:列出适配器仓库的全部 Release(含预发布版本),点一下就能升级;
- 启动器自己要更新时:在 设置 → 关于 里检查更新,会带你跳到下载页。
常见问题
1. OOBE 里依赖安装失败了?
多半是网络问题(这些工具需要联网下载,网络不稳容易中断)。先检查网络,必要时换个网络或热点,然后点 重新检查 再来一次。Linux 用户注意 sudo 密码输错也会失败,重试时重新输入即可。
2. 扫码登录超时、二维码过期了?
二维码是有时效的。回到日志页的 SnowLuma 标签,把 SnowLuma 进程 重启 一下(日志页里可以单独重启平台进程),再打开桌面版 QQ——登录窗口里会出现新的二维码,马上扫。
3. 实例启动失败、状态变成「错误」?
别慌,答案基本都在日志里:打开实例的 日志页,逐个标签(MoFox 和 SnowLuma)翻一翻,红色报错信息就是线索;常见原因是端口被占用(改一下 WebSocket 端口再启动)或依赖没装齐(重新跑一遍依赖安装)。如果是刚装完还没配协议端,先按第六步把平台种类和路径补上。实在解决不了,点日志页的 导出 把日志保存下来,带上日志去求助。
4. 安装到一半失败了?
向导会停在失败的步骤并保留现场,直接点 重试 就能从断点继续,已完成的步骤不会重跑。注意:重试只在当前这次会话有效,如果关掉了向导再进来,就需要重新开始安装了。
5. Bot 连上 QQ 后没反应?
依次检查:机器人是不是显示 运行中(实例卡片看状态);SnowLuma WebUI 的「进程注入」页是不是显示 qq 已在线(掉线了就重新扫码);日志页 SnowLuma 标签里有没有报错——QQ 刚自动升级到新版本时,SnowLuma 的注入可能暂时跟不上,等 SnowLuma 更新适配即可;群里是不是 @ 了它;主人 QQ 号是不是填对了(第九步)。还不行就导出日志去 FAQ 和社区找答案。
