Skip to content

安卓 App 部署 ​

这一篇带你在安卓手机上安装 Neo-MoFox:准备运行环境、创建 Bot 实例、用 SnowLuma 登录 QQ,再检查机器人能否正常回复。

本页对应 MoFox-Android 的 snowluma-migration 分支(Beta)。页面配图来自该分支 App 的实际界面;截图中的账号与实例名仅用于演示,填写时换成自己的信息。

它是什么? ​

MoFox Android App 把一套 Debian 13 运行环境装进手机,通过 proot 运行 Neo-MoFox、SnowLuma 和 WebUI。你不需要另外安装 Termux,也不需要 root 手机。

  • Neo-MoFox 是机器人主程序,负责处理消息、调用模型和运行插件。
  • SnowLuma 负责 QQ 登录与 OneBot v11 接入;它是全局共享组件,可以在首次引导时安装,也可以在首次启动时再装。
  • WebUI 是浏览器里的管理面板,创建实例时可以选择安装。

App 支持创建多个实例,但当前主要支持一组 Bot 与 SnowLuma 同时运行;切换实例前,先停止当前运行的进程。

开始之前的准备 ​

检查项要求
手机系统Android 7.0(API 24)或更高
CPU 架构64 位 ARM(arm64-v8a)
应用可用空间体检最低要求 2 GB,建议至少预留 4 GB
可用内存至少 1 GB
网络能访问所选代码镜像、软件源和模型服务;安装期间保持连接稳定
QQ 账号准备用于 Bot 的 QQ 号,以及你自己的主人 QQ 号
模型服务准备硅基流动的 API Key

首次引导会自动检查系统、架构、空间和内存。如果检查不通过,按页面提示处理后再继续。

还没有模型账号,可以使用 硅基流动注册入口(含邀请码),也可以直接打开 普通控制台。API Key 是调用模型的凭据,创建后留好,稍后填进实例向导。

第一步:下载并安装 APK ​

  1. 打开 MoFox-Android 发布页,查看维护者提供的 APK 与版本说明。
  2. 选择支持 arm64-v8a 的安装包;例如发布页提供的 universal 包也包含 ARM64,不必只找文件名带 arm64 的文件。Beta 期间可能提供预发布版或 Nightly,先核对版本说明。
  3. 下载完成后,在手机文件管理器中打开 APK;如果系统阻止安装,按提示为当前文件管理器允许“安装未知应用”。
  4. 完成安装,打开 MoFox。

APK 中包含运行环境,下载和后续安装会占用较多空间,建议连接 Wi-Fi 并保持电量充足。

MoFox-Android 发布页中的 APK 下载附件

图:发布页的 APK 下载入口,安装前核对版本与架构说明。

第二步:首次启动引导 ​

首次打开会进入 OOBE(开箱引导),依次完成协议、系统体检、运行环境准备和保活设置。完成后进入主界面,后续创建实例不用重复准备基础环境。

第 1 步:欢迎与协议 ​

  1. 阅读欢迎页上的 用户协议、隐私政策 和 前台保活 说明。
  2. 可以点 阅读最终用户许可协议 或 阅读遥测隐私协议 查看全文。
  3. 确认接受后,点 同意并继续。
首次启动的欢迎页:协议入口与同意并继续按钮

图:首次启动的欢迎与协议页。

第 2 步:系统体检 ​

App 会检查 CPU 架构、应用可用空间、可用内存、Android 版本。全部通过后点 下一步;如果显示读取失败或某项不满足,先处理对应问题并重新检查。

系统体检结果页:架构、应用空间、内存与 Android 版本

图:手机上的实际体检结果,各项数值以自己的设备为准。

第 3 步:准备运行环境 ​

进入这一页后,先确认可选组件,再点 开始准备。页面不会在你刚进入时自动开始安装。

  1. Debian 13 与基础依赖 是必需组件,会依次解压系统并安装 Python、Git、curl、uv 等依赖。
  2. 安装 SnowLuma(可选) 默认关闭。现在要接入 QQ,可以打开;暂时关闭也能完成初始化,之后首次启动 SnowLuma 时会自动安装。
  3. 点 开始准备,查看状态卡片和下方日志。
  4. 等待显示 基础运行环境已就绪,或 基础环境和 SnowLuma 已就绪,再点 继续。
准备运行环境页:SnowLuma 可选开关与开始准备按钮

图:运行环境准备入口,截图时尚未开始安装。

准备过程需要联网,耗时受手机性能与网络影响。保持 App 在前台;失败时先看日志中的具体错误,再点 重试,不要连续重复启动任务。

第 4 步:配置后台保活 ​

这一页提供三个入口:

  • 通知权限 → 去授权:允许 App 显示前台服务的常驻通知。
  • 忽略电池优化 → 去设置:允许 MoFox 在后台持续运行。
  • 应用锁定 → 说明:按手机系统的要求允许自启动,并在最近任务中锁定 MoFox。

按提示设置后完成引导,在完成页点 开始使用。日后可以从 设置 → 查看保活状态 重新检查权限与服务,详见保活体检。

第三步:创建你的第一个 Bot 实例 ​

实例是一套独立的 Bot 配置与目录。打开底部 实例 标签,点 创建实例,进入八步向导。

向导顺序是:镜像源检测 → 用户协议 → 实例信息 → 账号配置 → 模型配置 → 网络配置 → 确认摘要 → 安装执行。配置页面填完后点 下一步。

实例列表与创建实例入口

图:演示实例记录,用于展示入口,未实际安装或启动。

第 1 步:镜像源检测 ​

App 会检测 GitHub(官方)、GHProxy 加速 和 ikun镜像加速喵 的连通情况并显示延迟。选择可用的源,必要时点重新检测;后续下载失败时也可以返回更换。

实例向导的镜像源检测页:下载源与检测结果

图:镜像源检测与选择页。

第 2 步:用户协议 ​

阅读从所选镜像源取得的 Neo-MoFox 用户许可协议,勾选 我已阅读并同意 后继续。

实例向导的用户许可协议页

图:阅读协议后勾选同意,再进入下一步。

第 3 步:实例信息 ​

填写容易辨认的 实例名称,例如“小柒”。名称最长 32 个字符,同一台手机上的实例不要重名。

实例向导的实例名称输入页

图:实例名称填写入口。

第 4 步:账号配置 ​

字段填什么
Bot QQ 号机器人准备登录的 QQ 号,必填
Bot 昵称(可选)机器人使用的昵称,可以留空
主人 QQ你自己用来管理机器人的 QQ 号,必填

Bot QQ 与主人 QQ 的用途不同,别把两者填反。向导要求 QQ 号为 5–12 位数字。

账号配置页:Bot QQ、可选昵称与主人 QQ

图:号码仅为填写示例,请换成自己的 Bot 与主人 QQ。

第 5 步:模型配置 ​

服务商预置为 硅基流动 SiliconFlow。把控制台创建的 API Key 完整粘贴进输入框;点眼睛图标可检查是否粘贴完整。

还没有密钥,点页面中的 获取密钥,或使用 注册入口(含邀请码) / 普通控制台。模型与请求地址由 App 预置,部署后可以编辑实例配置继续调整。

模型配置页:硅基流动 API Key 输入框与获取密钥入口

图:截图尚未填写 API Key;填入有效密钥后继续。

第 6 步:网络配置 ​

  • WebSocket 端口:默认 8095,用于 Bot 与 SnowLuma 通信,没有冲突时保持默认。
  • 更新通道:稳定版对应 main,开发版对应 dev;第一次部署建议选择稳定版。
  • 安装 WebUI 管理面板:开启后会安装浏览器管理界面。
  • WebUI 访问密钥:开启 WebUI 后必填,点右侧骰子生成并保存好;关闭 WebUI 则无需填写。

API Key 与 WebUI 密钥都不要出现在公开截图或反馈日志中。

网络配置页:端口、更新通道、WebUI 安装开关与访问密钥

图:截图中的 WebUI 密钥未填写,开启 WebUI 后需先生成或填入。

第 7 步:确认摘要 ​

核对镜像源、实例名、Bot QQ、主人 QQ、模型与网络配置。发现错误,可以点对应区域的编辑入口返回修改;确认后再点 开始安装。

实例安装前的确认摘要页

图:演示配置的确认摘要,截图时尚未执行安装。

第 8 步:安装执行 ​

点 开始安装 后,App 会显示任务列表与日志,依次完成克隆源码、同步依赖、生成配置、写入核心与模型配置、写入 SnowLuma 适配器配置、安装 WebUI、写入 SnowLuma 配置和注册实例。关闭 WebUI 时会跳过其安装任务。

可以展开日志查看当前操作。等显示 安装完成 后返回实例列表。

安装失败时,实例会保留为未完成或失败状态。先查看错误原因,再从该实例的 继续安装 入口恢复;已完成任务会被保留,不必重新创建实例。

第四步:启动 Bot 并登录 QQ ​

启动 Bot ​

  1. 在 实例 标签中打开刚安装完成的实例。
  2. 点第一行的 启动,等待 Bot 状态变为 运行中。
  3. 查看 Bot 日志,确认初始化没有阻断运行的错误。

如果另一实例正在运行,先去停止它,再回到当前实例启动。

实例详情中的 Bot、SnowLuma、WebUI 与日志入口

图:演示实例详情,用于展示入口,未实际安装或启动。

启动 SnowLuma,登录 QQ ​

  1. 点实例详情中的 SnowLuma 按钮。首次启动时,如尚未安装,App 会先安装并校验组件,请查看 SnowLuma 日志等待完成。
  2. 出现 QQ 登录 浮层后,看其中来自虚拟屏幕的 QQ 窗口。
  3. 如果窗口显示已记住账号的快捷登录界面,点浮层里的 点击登录;如果显示二维码,用另一台设备上准备给 Bot 使用的 QQ 账号扫描,并在 QQ 中确认。
  4. App 检测到登录成功后会收起浮层。继续查看 SnowLuma 与 Bot 日志,确认消息连接正常。

浮层里的 收起 只关闭窗口;取消登录 会停止 SnowLuma。二维码过期或画面长时间没有变化时,可以停止 SnowLuma 再重新启动,查看新画面与日志。

打开管理面板并验证 ​

  • Bot 运行且安装了 WebUI 时,点 WebUI 打开 Neo-MoFox 管理面板。
  • SnowLuma 运行时,点 SnowLuma WebUI 打开其控制台;本地默认地址是 http://127.0.0.1:5099,优先使用 App 提供的入口访问。
  • 用主人 QQ 给 Bot 发一条消息,确认它能接收并回复;再让 App 在后台运行一会儿,检查连接是否保持。

按钮不可用时,先确认实例已安装完成、对应进程已启动,并等待日志输出访问地址。

认识主界面 ​

底部四个入口分别是:

入口常用操作
概览查看当前实例、Bot / SnowLuma 状态、内存与存储占用、设备信息;进入全部实例或终端
实例创建实例、打开实例详情、启动与停止进程、查看日志、打开 WebUI
终端在内置 Debian 环境中执行命令;实例详情的“Bot 目录终端”会直接进入该实例仓库
设置调整外观和终端触感,查看保活状态,备份与导入,配置 AI 运维助手
App 概览页中的实例入口与设备资源信息

图:实际概览页;截图时尚未创建实例。

实例详情顶部还提供 文件管理、实例信息 和 Bot 目录终端。改配置可以直接打开文件管理里的 TOML 编辑器,不需要先学终端命令。

保活体检:让 Bot 不掉线 ​

打开 设置 → 查看保活状态,根据实际状态逐项处理:

检查项操作
通知权限点 去授权,允许通知
忽略电池优化点 去设置,允许后台运行
前台保活服务状态为已关闭时点 开启,确认出现常驻通知
开机自启声明显示是否已声明开机广播;实际启动仍受系统策略限制
厂商自启动 / 最近任务锁定点 打开设置,按系统要求允许自启动,并锁定最近任务卡片
设置中的保活状态页:当前权限与前台服务状态

图:设置中的保活复查页面,截图保留实际未授权状态。

厂商自启动与任务锁定无法通过统一接口完整检测,要在手机系统设置中自行确认。返回 App 后点右上角刷新;如果仍会掉线,再检查系统的后台高耗电、应用冻结或省电策略。

修改主人 QQ 等账号信息 ​

创建实例前,在向导 账号配置 页填写。实例建好后,直接编辑配置文件:

  1. 先停止 Bot;修改前可以去 设置 → 备份与导出 留一份备份。
  2. 进入实例详情,点顶部的 文件管理 文件夹图标。
  3. 在 Bot 仓库 中打开 config/core.toml,进入 TOML 编辑器。
  4. 本页对应 App 生成的配置将账号写在 [bot] 段,主人字段为 owner_qq。把引号里的值换成你的 QQ 号,例如:
toml
[bot]
owner_qq = "123456789"
  1. 点右上角 保存。如果编辑器提示 TOML 错误,先修正后保存。
  2. 返回实例详情,重新启动 Bot,使配置生效。

不同 Neo-MoFox 版本的配置结构可能变化;如果已有文件采用 [permissions] 的 owner_list,按该文件的注释和核心配置说明修改,不要另外添加旧格式字段。

需要通过终端操作时,可用实例详情的 Bot 目录终端 进入仓库,或从 实例信息 → 路径 复制实际目录。修改配置无需删除实例。

实例信息页中的账号配置与实际路径入口

图:演示实例的信息与路径,操作时以自己实例的目录为准。

备份、更新与升级 ​

  • 备份:进入 设置 → 备份与导出,选择实例,可以完整导出或选择配置、SnowLuma 登录态、日志等内容。
  • 导入:先停止目标实例的 Bot 与 SnowLuma,再备份当前文件、核对目标实例后导入。导入可能覆盖同名文件,完成后重新启动并验证。
  • 更新 App:查看发布页的版本说明,再下载 APK 覆盖安装。Beta 版本升级前先备份,别直接清除应用数据。
  • 更新 Bot:在 WebUI 或实例终端中操作,见更新与升级;更新后重新检查 QQ 连接与回复。

完整备份可能含模型密钥、WebUI 密钥或 QQ 登录态,请保存在自己控制的地方,分享前删去敏感内容。

常见问题 ​

准备运行环境没有开始? ​

先检查是否停在 等待开始…。这一页需要先确认 SnowLuma 开关,再点底部 开始准备。已在运行时,保持 App 前台并查看日志;失败后按明确错误处理再重试。

SnowLuma 安装或启动失败? ​

确认设备为 arm64-v8a、基础运行环境已准备完成,再查看 SnowLuma 日志中的第一条明确错误。下载失败先检查网络;启动失败先停止进程后重试。

如果 QQ 已登录却不能收发消息,查看 SnowLuma 日志中的 QQ 启动、组件加载和适配器连接错误,并在反馈中提供机型、系统版本和相关日志。

QQ 登录浮层不出现,或没显示二维码? ​

先确认 SnowLuma 正在运行并查看其日志。画面来自虚拟桌面的 QQ 窗口,已记住账号时可能显示快捷登录而非二维码,按画面点 点击登录。需要扫码时使用另一台设备;二维码过期可停止 SnowLuma 后重新启动。

Bot 切到后台就掉线? ​

从 设置 → 查看保活状态 检查通知、电池优化和前台服务,再到系统设置允许自启动、后台运行,并锁定最近任务卡片。不同厂商限制不同,完成授权后仍需实际观察后台运行情况。

WebUI 打不开? ​

确认实例安装完成、对应进程运行中;Neo-MoFox WebUI 还要求创建实例时已选择安装。等日志输出访问地址后再点按钮,必要时停止并重新启动对应进程。

安装失败后实例还在? ​

这是为了保留断点。打开失败实例,查看错误信息,选择 继续安装。只有确定不再需要该实例时才删除。

下一步 ​

需要反馈 App 问题时,提供手机型号、Android 版本、App 版本、卡住的步骤与错误日志,去 MoFox-Android Issues 提交;先去掉日志中的密钥和登录凭据。

贡献者

The avatar of contributor named as ikun-1145141 ikun-1145141
The avatar of contributor named as minecraft1024a minecraft1024a

页面历史

Released under the GPL-3.0 License.