安卓 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
- 打开 MoFox-Android 发布页,查看维护者提供的 APK 与版本说明。
- 选择支持
arm64-v8a的安装包;例如发布页提供的universal包也包含 ARM64,不必只找文件名带arm64的文件。Beta 期间可能提供预发布版或 Nightly,先核对版本说明。 - 下载完成后,在手机文件管理器中打开 APK;如果系统阻止安装,按提示为当前文件管理器允许“安装未知应用”。
- 完成安装,打开 MoFox。
APK 中包含运行环境,下载和后续安装会占用较多空间,建议连接 Wi-Fi 并保持电量充足。

图:发布页的 APK 下载入口,安装前核对版本与架构说明。
第二步:首次启动引导
首次打开会进入 OOBE(开箱引导),依次完成协议、系统体检、运行环境准备和保活设置。完成后进入主界面,后续创建实例不用重复准备基础环境。
第 1 步:欢迎与协议
- 阅读欢迎页上的 用户协议、隐私政策 和 前台保活 说明。
- 可以点 阅读最终用户许可协议 或 阅读遥测隐私协议 查看全文。
- 确认接受后,点 同意并继续。

图:首次启动的欢迎与协议页。
第 2 步:系统体检
App 会检查 CPU 架构、应用可用空间、可用内存、Android 版本。全部通过后点 下一步;如果显示读取失败或某项不满足,先处理对应问题并重新检查。

图:手机上的实际体检结果,各项数值以自己的设备为准。
第 3 步:准备运行环境
进入这一页后,先确认可选组件,再点 开始准备。页面不会在你刚进入时自动开始安装。
- Debian 13 与基础依赖 是必需组件,会依次解压系统并安装 Python、Git、curl、uv 等依赖。
- 安装 SnowLuma(可选) 默认关闭。现在要接入 QQ,可以打开;暂时关闭也能完成初始化,之后首次启动 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。
第 5 步:模型配置
服务商预置为 硅基流动 SiliconFlow。把控制台创建的 API Key 完整粘贴进输入框;点眼睛图标可检查是否粘贴完整。
还没有密钥,点页面中的 获取密钥,或使用 注册入口(含邀请码) / 普通控制台。模型与请求地址由 App 预置,部署后可以编辑实例配置继续调整。

图:截图尚未填写 API Key;填入有效密钥后继续。
第 6 步:网络配置
- WebSocket 端口:默认
8095,用于 Bot 与 SnowLuma 通信,没有冲突时保持默认。 - 更新通道:稳定版对应
main,开发版对应dev;第一次部署建议选择稳定版。 - 安装 WebUI 管理面板:开启后会安装浏览器管理界面。
- WebUI 访问密钥:开启 WebUI 后必填,点右侧骰子生成并保存好;关闭 WebUI 则无需填写。
API Key 与 WebUI 密钥都不要出现在公开截图或反馈日志中。

图:截图中的 WebUI 密钥未填写,开启 WebUI 后需先生成或填入。
第 7 步:确认摘要
核对镜像源、实例名、Bot QQ、主人 QQ、模型与网络配置。发现错误,可以点对应区域的编辑入口返回修改;确认后再点 开始安装。

图:演示配置的确认摘要,截图时尚未执行安装。
第 8 步:安装执行
点 开始安装 后,App 会显示任务列表与日志,依次完成克隆源码、同步依赖、生成配置、写入核心与模型配置、写入 SnowLuma 适配器配置、安装 WebUI、写入 SnowLuma 配置和注册实例。关闭 WebUI 时会跳过其安装任务。
可以展开日志查看当前操作。等显示 安装完成 后返回实例列表。
安装失败时,实例会保留为未完成或失败状态。先查看错误原因,再从该实例的 继续安装 入口恢复;已完成任务会被保留,不必重新创建实例。
第四步:启动 Bot 并登录 QQ
启动 Bot
- 在 实例 标签中打开刚安装完成的实例。
- 点第一行的 启动,等待 Bot 状态变为 运行中。
- 查看 Bot 日志,确认初始化没有阻断运行的错误。
如果另一实例正在运行,先去停止它,再回到当前实例启动。

图:演示实例详情,用于展示入口,未实际安装或启动。
启动 SnowLuma,登录 QQ
- 点实例详情中的 SnowLuma 按钮。首次启动时,如尚未安装,App 会先安装并校验组件,请查看 SnowLuma 日志等待完成。
- 出现 QQ 登录 浮层后,看其中来自虚拟屏幕的 QQ 窗口。
- 如果窗口显示已记住账号的快捷登录界面,点浮层里的 点击登录;如果显示二维码,用另一台设备上准备给 Bot 使用的 QQ 账号扫描,并在 QQ 中确认。
- 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 运维助手 |

图:实际概览页;截图时尚未创建实例。
实例详情顶部还提供 文件管理、实例信息 和 Bot 目录终端。改配置可以直接打开文件管理里的 TOML 编辑器,不需要先学终端命令。
保活体检:让 Bot 不掉线
打开 设置 → 查看保活状态,根据实际状态逐项处理:
| 检查项 | 操作 |
|---|---|
| 通知权限 | 点 去授权,允许通知 |
| 忽略电池优化 | 点 去设置,允许后台运行 |
| 前台保活服务 | 状态为已关闭时点 开启,确认出现常驻通知 |
| 开机自启声明 | 显示是否已声明开机广播;实际启动仍受系统策略限制 |
| 厂商自启动 / 最近任务锁定 | 点 打开设置,按系统要求允许自启动,并锁定最近任务卡片 |

图:设置中的保活复查页面,截图保留实际未授权状态。
厂商自启动与任务锁定无法通过统一接口完整检测,要在手机系统设置中自行确认。返回 App 后点右上角刷新;如果仍会掉线,再检查系统的后台高耗电、应用冻结或省电策略。
修改主人 QQ 等账号信息
创建实例前,在向导 账号配置 页填写。实例建好后,直接编辑配置文件:
- 先停止 Bot;修改前可以去 设置 → 备份与导出 留一份备份。
- 进入实例详情,点顶部的 文件管理 文件夹图标。
- 在 Bot 仓库 中打开
config/core.toml,进入 TOML 编辑器。 - 本页对应 App 生成的配置将账号写在
[bot]段,主人字段为owner_qq。把引号里的值换成你的 QQ 号,例如:
[bot]
owner_qq = "123456789"- 点右上角 保存。如果编辑器提示 TOML 错误,先修正后保存。
- 返回实例详情,重新启动 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 还要求创建实例时已选择安装。等日志输出访问地址后再点按钮,必要时停止并重新启动对应进程。
安装失败后实例还在?
这是为了保留断点。打开失败实例,查看错误信息,选择 继续安装。只有确定不再需要该实例时才删除。
下一步
- 人设与性格调教:调整机器人的角色与表达。
- 插件使用:安装与配置扩展功能。
- 内置插件说明:了解已有功能的用法。
- WebUI 使用指南:在浏览器里管理 Bot。
需要反馈 App 问题时,提供手机型号、Android 版本、App 版本、卡住的步骤与错误日志,去 MoFox-Android Issues 提交;先去掉日志中的密钥和登录凭据。
