Neo-MoFox

Appearance

Neo-MoFox Android 官方部署指南（Beta） ​

本文介绍使用 MoFox Android App 部署 Neo-MoFox 的官方 Android 方式。

当前 Android 版本仍处于 Beta 测试阶段，可能存在安装失败、后台进程被系统终止、部分机型兼容性不佳、升级后需要重新配置等问题。请勿将 Beta 版本用于无法接受中断或数据丢失的生产场景，并在升级或导入配置前做好备份。

1. 部署方式说明 ​

MoFox Android App 会在应用内部安装一套独立的 Debian 13 运行环境，并通过 proot 运行 Neo-MoFox、NapCat 和 WebUI。整个过程不依赖 Termux，也不要求设备获取 Root 权限。

使用本应用部署后，可以直接在 Android App 中完成：

  • 首次运行环境初始化；
  • Neo-MoFox 实例创建与配置；
  • Bot 和 NapCat 的启动、停止与重启；
  • NapCat QQ 扫码登录；
  • Neo-MoFox WebUI 和 NapCat WebUI 访问；
  • 运行日志查看；
  • Debian 终端访问；
  • 实例配置备份与恢复；
  • Android 后台保活设置检查。

2. 使用要求 ​

部署前请确认设备满足以下条件：

  • Android 7.0 或更高版本；
  • 64 位 ARM 设备（arm64-v8a）；
  • 保留充足的内部存储空间，建议至少预留 4 GB；
  • 使用稳定的 Wi-Fi 或移动网络；
  • 安装过程中保持设备电量充足，建议连接充电器；
  • 可以正常访问所选代码镜像、Python 软件源及模型 API 服务。

当前版本暂不支持：

  • 32 位 ARM 设备；
  • x86 或 x86_64 Android 设备；
  • 将运行环境安装到外置 SD 卡；
  • 保证所有厂商系统均能长期后台运行。

3. 部署前准备 ​

开始部署前，需要准备：

  1. 用作 Bot 的 QQ 账号；
  2. 主人 QQ 号；
  3. SiliconFlow API Key；
  4. 一个用于保护 WebUI 的访问密钥；
  5. 稳定的网络连接。

建议 Bot QQ 使用独立账号。第三方协议接入可能触发平台风控，请自行了解并承担相应账号风险。

4. 获取并安装应用 ​

请从以下官方渠道获取安装包：

Beta 测试期间，安装包可能以预发布版或 Nightly 版本提供。Nightly 是自动构建的最新预览版本，包含最新改动，但稳定性通常低于正式发布的 Beta 版本。

下载适用于 arm64-v8a 的 APK 后：

  1. 在 Android 文件管理器中打开 APK；
  2. 如果系统阻止安装，按提示允许该文件管理器“安装未知应用”；
  3. 完成安装后启动“MoFox”；
  4. 首次安装建议不要恢复旧版本应用数据，先完成一次全新部署。

请勿安装来源不明、被重新签名或经过二次修改的 APK。

5. 首次启动与运行环境初始化 ​

首次启动会进入初始化向导。

5.1 阅读说明和协议 ​

阅读应用说明、用户协议和隐私政策。确认接受相关条款后继续。

5.2 系统体检 ​

应用会检查设备架构、可用空间和运行环境。出现不满足项时，应先根据页面提示处理，不建议强行继续。

5.3 安装 Debian 运行环境 ​

应用会依次执行：

  1. 解压 Debian 13 rootfs；
  2. 安装 Python、Git、curl、uv 等基础依赖；
  3. 安装全局 NapCat 运行组件。

此步骤耗时受设备性能和网络质量影响，可能持续数分钟。安装期间请保持 App 在前台，不要清理后台、锁屏或切换网络。

如果安装失败，可保留错误页面中的日志并点击重试。反复失败时请先更换网络，再重新执行。

5.4 配置后台保活 ​

按引导完成以下设置：

  • 允许通知权限；
  • 允许忽略电池优化；
  • 在厂商系统设置中允许自启动；
  • 将 MoFox 锁定在最近任务中；
  • 启用前台保活服务。

不同厂商系统的设置名称可能不同。即使完成全部设置，Beta 版本也无法保证进程永远不会被系统终止。

6. 创建 Neo-MoFox 实例 ​

初始化完成后，在“管理”页面选择“创建实例”。

6.1 镜像源检测 ​

应用会检测可用的代码镜像并显示延迟。通常选择检测结果中可用且延迟较低的源即可。如果后续下载失败，可以返回并更换镜像源。

6.2 同意 Neo-MoFox 用户协议 ​

阅读并同意 Neo-MoFox 用户许可协议后才能继续部署。

6.3 填写实例信息 ​

为实例填写容易识别的名称。多个实例应使用不同名称，方便后续管理和备份。

6.4 配置账号 ​

填写：

  • Bot QQ；
  • Bot 昵称；
  • 主人 QQ。

请仔细核对 QQ 号码。错误的账号配置可能导致消息无法正常收发。

6.5 配置模型 ​

填写 SiliconFlow API Key。模型与请求地址由应用预置，部署完成后可以继续在 Neo-MoFox 配置中调整。

API Key 属于敏感凭据，不要截图公开，也不要发送给不可信人员。

6.6 配置网络和 WebUI ​

  • WebSocket 端口默认使用 8095，没有端口冲突时建议保持默认；
  • 更新通道建议选择“稳定版”；
  • 建议安装 WebUI 管理面板；
  • 使用随机生成按钮创建强度足够的 WebUI 访问密钥，并妥善保存。

6.7 确认并开始安装 ​

在摘要页面核对全部信息后开始安装。应用将自动完成：

  1. 克隆 Neo-MoFox；
  2. 同步 Python 依赖；
  3. 生成默认配置；
  4. 写入核心、模型和适配器配置；
  5. 安装 WebUI；
  6. 写入 NapCat 配置；
  7. 注册本地实例。

安装过程中不要强制关闭 App。若安装失败，实例会以“未完成”或“失败”状态保留，可以从管理页面选择“继续安装”。

7. 启动和验证 ​

部署完成后，进入实例详情页进行验证。

7.1 启动 Bot ​

点击 Bot 区域的“启动”，等待状态变为“运行中”。随后检查日志中是否出现模型、插件和 WebUI 初始化成功的信息。

7.2 启动 NapCat 并登录 ​

点击 NapCat 区域的“NapCat”或“启动”。首次登录时，应用会显示二维码；使用对应 QQ 扫码并确认登录。

二维码过期时，停止 NapCat 后重新启动即可重新获取。

7.3 检查 WebUI ​

Bot 运行后，点击“WebUI”进入 Neo-MoFox 管理面板。NapCat 运行后，可以点击“NapCat WebUI”进入 NapCat 控制台。

如果按钮不可用，请先确认对应进程已经启动，并等待日志输出 WebUI 地址。

7.4 完成基础验证 ​

建议至少检查：

  • Bot 和 NapCat 状态均为运行中；
  • NapCat 已使用正确 QQ 登录；
  • Neo-MoFox WebUI 可以打开；
  • 模型 API Key 有效；
  • Bot 能接收消息并产生正常回复；
  • App 切到后台一段时间后进程仍在运行。

8. 日常使用 ​

  • 在“管理”页面管理实例和查看运行状态；
  • 在实例详情页查看 Bot、NapCat 日志；
  • 在“终端”页面进入内置 Debian 环境；
  • 在“设置 → 保活状态”检查后台权限；
  • 修改关键配置前先创建备份；
  • App 或 Neo-MoFox 升级后重新执行一次基础验证。

不熟悉 Linux 命令时，不要在终端中删除 /root、/usr 或实例目录。

9. 备份与恢复 ​

进入“设置 → 备份与导出”，选择需要操作的实例。

完整备份可以包含：

  • Neo-MoFox 配置；
  • NapCat 配置；
  • NapCat 登录态；
  • 运行日志。

导入备份会覆盖目标实例中的同名文件。导入前应：

  1. 停止目标实例的 Bot 和 NapCat；
  2. 先导出目标实例当前备份；
  3. 确认备份文件来自可信来源；
  4. 核对导入目标实例；
  5. 导入完成后重新启动并验证配置。

不要把包含 API Key、WebUI 密钥或登录态的备份上传到公开网盘、公开聊天群或代码仓库。

10. 常见问题 ​

10.1 初始化长时间没有进度 ​

  • 保持 App 在前台并关闭省电模式；
  • 检查剩余存储空间；
  • 切换稳定网络；
  • 等待当前操作结束后再点击重试，避免连续重复启动任务。

10.2 下载 Neo-MoFox 或依赖失败 ​

  • 返回镜像源检测页面更换镜像；
  • 检查 GitHub、镜像站和 Python 软件源是否可访问；
  • 避免使用会拦截 HTTPS 或修改证书的代理软件。

10.3 NapCat 安装或启动失败 ​

  • 确认设备为 arm64-v8a；
  • 检查运行环境初始化是否完整；
  • 查看 NapCat 日志中的第一条明确错误；
  • 停止 NapCat 后再重新启动，避免重复进程。

10.4 App 切到后台后 Bot 停止 ​

  • 打开通知权限；
  • 关闭系统对 MoFox 的电池优化；
  • 开启自启动和后台运行权限；
  • 在最近任务中锁定 MoFox；
  • 避免使用第三方清理工具结束进程。

10.5 WebUI 无法打开 ​

  • 确认 Bot 或 NapCat 对应进程正在运行；
  • 等待启动日志输出完成；
  • 返回实例详情页后重新进入 WebUI；
  • 尝试停止并重新启动对应进程。

10.6 安装失败后实例仍然存在 ​

这是用于断点续装的正常行为。进入失败实例，查看错误原因后选择“继续安装”。如果确认不再需要，可以删除该实例后重新创建。

11. Beta 版本已知限制 ​

  • 后台保活能力受 Android 厂商系统影响较大；
  • 当前主要支持单个 Bot 和单个 NapCat 同时运行；
  • 不同版本间的配置和运行环境可能发生变化；
  • 自动升级、异常恢复和设备兼容性仍在持续完善；
  • Nightly 构建未经完整发布验证，可能出现回归问题；
  • 部分故障仍需要通过安装日志、运行日志或终端手动排查。

12. 获取帮助与反馈 ​

反馈问题时，请提供：

  • 手机品牌、型号和 Android 版本；
  • MoFox Android App 版本；
  • 问题发生在哪个步骤；
  • 页面错误信息和相关日志；
  • 是否使用代理、VPN 或特殊网络环境；
  • 问题是否可以稳定复现。

请先删除日志中的 API Key、WebUI 密钥、QQ 登录态、访问 Token 等敏感信息，再通过项目的 GitHub Issues 提交反馈。

MoFox Android 是 Neo-MoFox 的官方 Android 部署方式之一。Beta 阶段的目标是尽早发现不同设备和系统环境中的兼容性问题；感谢测试者在做好备份和风险评估的前提下参与测试。

贡献者

The avatar of contributor named as micraft1024a micraft1024a

页面历史

Released under the GPL-3.0 License.

Copyright © 2025 MoFox Studio