MoFox 一键包使用指南 (重构版)
简介
MoFox 一键包是一个集成了 Python 环境、数据库工具和 VS Code 编辑器的多服务机器人管理工具，旨在为用户提供开箱即用的机器人部署、管理和维护体验。本指南将引导您完成从安装、配置到启动的完整流程，帮助您快速部署属于自己的机器人。
环境要求
在开始之前，请确保您的系统满足以下要求：
- 操作系统: Windows (推荐 Windows 10 及以上版本)
- 网络连接: 用于在首次启动时下载核心组件及更新依赖。
TIP
Git 和 Python 已被内置到一键包中，您无需额外安装。
快速上手：首次运行与配置向导
请跟随以下步骤完成您的第一次启动和配置。
1. 下载与解压
从发布渠道下载 OneKey-Plus.zip 压缩包，并将其解压到您希望存放的任意目录。
重要提示: 请勿在压缩包内直接运行程序。脚本会检测并阻止在临时文件夹中运行的行为。
2. 启动一键包
进入解压后的 onekey-plus 目录，找到并双击运行 启动一键包程序.bat。
程序在第一次运行时，会自动执行一个初始化的流程。
第一阶段：自动更新与环境初始化
程序会自动从 GitHub 拉取最新的 MoFox-Bot 主程序，并下载所有必需的依赖库。
这个过程可能需要几分钟，具体时间取决于您的网络状况。请耐心等待，直到窗口提示更新和依赖检查完毕。
第二阶段：交互式配置向导
更新完成后，程序会自动进入交互式配置向导。您需要根据命令行提示完成几个关键设置。
用户许可协议 (EULA)：
- 您需要先阅读并同意用户许可协议。输入
yes以继续。
- 您需要先阅读并同意用户许可协议。输入
核心配置:
- 设置主人QQ: 输入您的 QQ 号码，您将成为 Bot 的最高管理员。
- 设置Bot QQ: 输入准备作为机器人使用的 QQ 号码。
- 高级编辑: 完成后，向导会自动调用内置的 VS Code 编辑器打开核心配置文件，方便您进行检查或进行高级设置。关闭 VS Code 后，在命令行窗口按回车即可继续。
模型配置:
- 设置 API Key: 您需要输入从 SiliconFlow 获取的 API Key，这是驱动 Bot AI 对话的核心。
Napcat 适配器配置:
- 您可以配置 Bot 在 QQ 群聊和私聊中的响应规则（如白名单或黑名单模式），保持默认即可开始使用。
配置 Napcat WebSocket
TIP
如果你的机器人可以正常收发消息就不用管它
- 待一键包中的服务完全启动后，访问 Napcat 的 WebUI,它的网址通常是127.0.0.1:6099,TOKEN是napcat。
- 在 WebUI 中找到并点击“网络配置”选项。
- 新建一个 WebSocket 客户端 (反向 WebSocket)。
- 将端口号从默认的
8082修改为8095。 - 保存配置并启动该客户端。
第三阶段：进入主控面板
当您完成所有配置步骤后，初始化流程便全部结束。程序会自动启动主控面板。
主控面板使用指南
主控面板是您未来管理和运行 Bot 的核心界面。每次（在首次初始化后）运行 启动一键包程序.bat 都会直接进入此面板。
面板主要分为三个区域：
1. 快捷启动服务管理
这个区域提供了启动和管理 Bot 核心服务的快捷选项。
1. 启动服务组合: （推荐） 提供预设的服务组合。选择内置适配器组合可以一键启动MoFox-Core主程序和Napcat 服务，这是让 Bot 在 QQ 平台运行起来的标准方式。2. 启动 MoFox-Core 主程序: 单独启动 Bot 的核心逻辑服务。3. 启动 Napcat 服务: 单独启动 Napcat QQ 适配器服务。4. 启动 vscode: 启动内置的 VS Code 编辑器，并自动打开 Bot 的核心代码目录，方便您进行二次开发或插件调整。5. 查看运行状态: 显示所有服务的当前状态（运行中、已停止、未启动）。6. 启动数据库管理程序: 启动内置的SQLiteStudio并自动加载 Bot 的数据库文件，方便您查看和管理数据。
2. BOT 管理
这个区域提供了快速访问 Bot 配置文件和数据的入口。
11. 打开配置文件: 提供一个子菜单，让您可以快速用 VS Code 打开核心配置、模型配置或 Napcat 适配器配置，无需手动寻找文件路径。12. 打开数据文件夹: 在文件浏览器中打开存放 Bot 数据库、日志等核心数据的data文件夹。13. 打开插件文件夹: 在文件浏览器中打开plugins文件夹，方便您安装或管理插件。14. 删除数据库: （危险操作！） 此选项会删除数据库文件，导致所有用户数据、记忆和学习内容丢失。请仅在需要彻底重置时使用。
3. 其他功能
这个区域提供了一些高级维护和调试工具。
7. 安装/更新依赖包: 如果您手动安装了新插件或怀疑依赖损坏，可使用此功能重新安装。8. 查看系统信息: 显示一键包的工作路径和内置的 Python 版本。9. 切换Bot主程序分支: 允许您在master(稳定版) 和dev(开发版) 分支之间切换。切换后，需要运行启动更新程序.bat来拉取对应分支的代码。10. 启动知识库学习工具: 启动一个独立的工具，用于管理和训练 Bot 的本地知识库。
目录结构
onekey-plus/
├── core/ # <-- 核心服务和工具目录
│ ├── Bot/ # <-- MoFox-Bot 主程序
│ ├── Napcat/ # <-- Napcat QQ 适配器
│ ├── SQLiteStudio/ # <-- 数据库管理工具
│ └── vscode/ # <-- 内置的 VS Code 编辑器
│
├── python_embedded/ # <-- 内置的、隔离的 Python 环境
│
├── 启动一键包程序.bat # <-- (推荐) 程序主入口
├── 启动更新程序.bat # <-- 手动执行更新流程
└── ... (其他核心脚本)使用内置 Python 执行命令
如果您需要手动执行某些 Python 脚本，可以直接调用 python_embedded 内的 python.exe。
命令格式:
# 语法: .\python_embedded\python.exe [要执行的脚本路径] [可选参数]
# 示例: 从 onekey-plus 根目录手动执行核心控制脚本
.\python_embedded\python.exe onekey.py
# 示例: 手动安装一些需要的依赖
.\python_embedded\python.exe -m pip install requests常见问题 (FAQ)
Q: 我该如何修改 Bot 的详细配置？ A: 在主控面板选择
11. 打开配置文件，程序会自动使用内置的 VS Code 打开对应的.toml文件。VS Code 提供了语法高亮和错误检查，是推荐的编辑方式。Q: 如何安装新插件？ A: 在主控面板选择
13. 打开插件文件夹，然后将您的插件文件夹放入其中即可。Q: 我想切换到开发版体验新功能，该怎么做？ A: 在主控面板选择
9. 切换Bot主程序分支，选择dev开发版。设置成功后，退出主控面板，然后运行根目录下的启动更新程序.bat来拉取最新的开发版代码。Q: 我不小心把主控面板关了，但 Bot 还在运行，如何关闭它？ A: Bot 的每个服务（如
MoFox-Core 主程序、Napcat 服务）都运行在独立的命令行窗口（通常是 PowerShell 或 CMD 窗口）中。要关闭某个服务，直接关闭对应的那个命令行窗口即可。Q: 更新后启动时报错
ModuleNotFoundError: No module named 'xxx'怎么办？ A: 这是因为主程序更新后新增了依赖包，但本地环境还没有安装。请按以下步骤解决：方法一：通过主控面板（推荐）
- 在主控面板选择
7. 安装/更新依赖包 - 选择
1. 更新 / 重装 Bot本体依赖或3. 更新 / 重装 所有依赖 - 等待依赖安装完成后，重新启动 Bot
方法二：手动命令行安装
如果知道缺少的具体包名（如报错
No module named 'aiohttp'），可以在一键包根目录下打开命令行，执行：powershell.\python_embedded\python.exe -m pip install aiohttp或者直接重装所有依赖：
powershell.\python_embedded\python.exe -m pip install -r .\core\Bot\requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simpleTIP
如果安装过程中遇到网络问题，程序会自动尝试多个国内镜像源（清华、阿里云、豆瓣等），请耐心等待。
- 在主控面板选择
感谢使用 MoFox 一键包，祝您使用愉快！
贡献者
minecraft1024a
ikun-11451