Android 设备 / 模拟器 (APK 安装)

APK 直装是最轻量、配置步骤最少的使用方式。它直接运行在真实的 Android 系统或第三方模拟器中，不涉及任何 Linux 内核与容器技术。

---

准备工作

1. 下载安装包：前往 GitHub Releases 下载最新发布的 PicoOnebot.apk；
2. 运行环境：
   • 实体设备：Android 7.0 及以上版本的手机、平板或开发板（如搭载 Android 系统的树莓派、香橙派）；
     • 必须支持运行 32 位（armeabi-v7a）应用。手表 QQ 底包只有 32 位原生库，纯 64 位且厂商未内置转译层的机型（如 Pixel 7 及之后）无法安装，请参考 纯 64 位设备的备选方案；
   • 电脑模拟器：MuMu 模拟器、雷电模拟器、逍遥模拟器、BlueStacks 或 Android Studio AVD 等。

---

安装与运行步骤

1. 安装 APK

将下载好的 APK 文件传输至 Android 设备或拖入电脑模拟器窗口中完成安装。

2. 授予权限并启动

1. 启动 PicoOnebot 应用；
2. 按照系统提示授予通知权限与必要的基础运行权限；
3. 应用将自动拉起内置服务并在局域网开放控制台端口（默认为 6099）。

3. 访问控制台

在同一局域网内的电脑或手机浏览器打开：

http://<设备IP地址>:6099

获取设备 IP 地址

• 实体手机：可在「设置 -> WLAN / Wi-Fi -> 当前连接的网络详情」中查看 IPv4 地址；
• 模拟器：若在电脑本地运行，通常可在浏览器直接访问 http://127.0.0.1:6099 或 http://localhost:6099（若模拟器使用的是桥接网卡模式，则访问模拟器的桥接 IP）。

4. 扫码登录与网络配置

1. 输入初始密码 picopico 登录控制台，并按提示修改密码；
2. 使用手机 QQ 扫描网页中的二维码完成登录；
3. 在控制台左侧进入「网络配置」，添加对应机器人框架的反向 WebSocket 地址。

---

无法安装：纯 64 位设备的备选方案

安装时若出现如下报错，说明这台设备不支持运行 32 位（armeabi-v7a）应用：

Failure [INSTALL_FAILED_NO_MATCHING_ABIS: Failed to extract native libraries, res=-113]

原因

PicoOnebot 以官方手表 QQ 为底包，而手表 QQ 只提供 armeabi-v7a 一种架构的原生库，官方没有 64 位版本，本项目也无法在 APK 层面补齐。因此能否安装完全取决于设备是否保留了 32 位运行能力：

设备类型	能否安装	说明
传统 64 位机型（abilist 含 armeabi-v7a）	可以	绝大多数 2024 年以前的手机、平板、开发板
纯 64 位芯片 + 厂商内置 32 位转译层	可以	如搭载骁龙 8 Elite 5 / 天玑 9400 的国产旗舰（小米、vivo、OPPO、荣耀等），系统自带用户态转译
纯 64 位且厂商未提供转译	不可以	如 Pixel 7 及之后机型、部分三星与日版 / 海外版机型

可通过 ADB 确认设备支持的架构列表，输出中没有 armeabi-v7a 即属于最后一类：

adb shell getprop ro.product.cpu.abilist

NOTE

这不是安装器的问题。换用其他安装器、开启开发者选项或重新签名均无法解决，请直接参考下方备选方案。

备选方案

方案 A：手机内运行虚拟机（光速虚拟机 / VMOS Pro）

光速虚拟机、VMOS Pro 等应用会在手机内运行一套完整的 Android 系统，并自带 32 位转译层，官方均宣称支持在纯 64 位系统上运行 32 位应用。原理与本项目 Docker 镜像内置 libndk 转译一致。

使用步骤：

1. 安装虚拟机应用，创建一个 Android 实例（建议选择 Android 10 / 12 镜像，环境更接近真机；Android 7.1 镜像更省内存但兼容性稍差）；
2. 将 PicoOnebot_<version>.apk 导入虚拟机并在虚拟机内安装、启动；
3. 在虚拟机内打开浏览器访问 http://127.0.0.1:6099 进入 WebUI；若需要在宿主手机或电脑浏览器访问，需使用虚拟机提供的端口映射功能，或查看虚拟机实例的 IP；
4. 按 安装与运行步骤 完成扫码登录与网络配置。

注意事项：

• 虚拟机进程本身同样受宿主系统后台管控，需要为虚拟机应用加白名单（忽略电池优化、允许自启动、锁定后台），否则 PicoOnebot 会随虚拟机一起被杀；
• 转译层有性能开销，虚拟机环境也可能被手表 QQ 的风控识别，登录成功率与稳定性需自行实测；
• 本项目未与任何虚拟机厂商合作，相关软件的收费策略与稳定性请以其官方说明为准。

方案 B：电脑模拟器

在电脑上使用 MuMu、雷电、BlueStacks 等模拟器安装 APK。x86 模拟器内置 ARM 转译，可直接运行 32 位应用。步骤见本页 安装与运行步骤。

方案 C：Docker 一体化容器（推荐用于长期挂机）

若有 Linux 服务器或支持 Binder 的主机，直接使用官方镜像，镜像已内置 Redroid 与 ARM 转译层，无需关心设备架构。详见 Docker 一体化容器部署。

方案 D：Waydroid

Linux 桌面用户可使用 Waydroid 并安装 libndk 转译层，仓库内提供了 scripts/install-waydroid.sh 一键脚本。

---

实体设备长期运行注意事项

实体 Android 手机由于厂商自带激进的电池管理与进程冻结策略，常导致后台应用被系统清理：

• 忽略电池优化：进入系统「设置 -> 电池 / 应用电池管理」，将 PicoOnebot 设置为「无限制 / 允许高耗电后台运行」；
• 自启动与关联启动：在手机管家中开启 PicoOnebot 的「允许自启动」与「允许后台活动」；
• 应用锁后台：在多任务卡片界面长按或下拉 PicoOnebot 卡片，锁定后台任务；
• 锁屏保持 Wi-Fi 连接：确保系统设置中「休眠期间保持 Wi-Fi 连接」已开启。