astrbot-for-android

Introduction: 在 Android 手机上本地部署和管理 AstrBot 与 NapCat,内置 PRoot Ubuntu 运行环境,支持原生管理界面、WebUI、日志、备份恢复和独立更新,无需 Root。
More: Author   ReportBugs   
Tags:
AstrBot for Android

AstrBot for Android

简体中文 | English

把 AstrBot 和 NapCat,装进你的 Android 手机。

一个 APK · 本地运行 · 原生管理 · 内置 WebUI

Kotlin Jetpack Compose PRoot Ubuntu

Version 1.4.1 Android 8.0 and above ARM64 MIT License JunWan666

下载 APK · 界面预览 · 项目架构 · 开始使用 · SnowLuma 手动部署 · 使用指南 · 源码构建 · 更新记录

AstrBot for Android(AstrBot 运行管理器) 是面向 Android 设备的 AstrBot 与 NapCat 本地部署及运行管理应用。通过单个 APK 集成 PRoot Ubuntu 运行环境与服务组件,提供环境初始化、服务启停、状态监控、日志查看、备份恢复及独立在线更新等功能,无需 Root。

应用采用 Kotlin 与 Jetpack Compose 构建原生管理界面,支持简体中文与英文,通过内置 WebView 访问 AstrBot 和 NapCat 的 WebUI,在手机端完成 QQ 登录、模型接入与插件配置,并提供人设管理、局域网访问、SSH 终端与 cpolar 内网穿透扩展。

当前版本为 1.4.1。本轮通过构建时预配置桌面依赖,缩短全新安装后的初始化等待,完善离线修复进度和 Linux QQ 启动衔接;完整 APK 比 1.4.0 增加约 175 MiB,现约 1 GiB。SnowLuma 手动部署及运行管理仍为预览功能,适用许可范围仍需确认,不附带其程序。完整变化见更新记录。

界面预览

以下八张手机实机截图展示服务管理、人设、常用网页、分类设置、扩展、权限及两套内置后台。

首页:服务状态、启停与资源占用

首页 · 服务与资源

人设:社区市场、搜索与本地预设

人设 · 搜索与切换

网页:带网站图标的常用地址与内置访问入口

网页 · 常用地址

设置:运行与权限、数据与维护、通用分类

设置 · 分类管理

扩展:终端与桌面、远程连接和 AI 工作台

扩展 · 按需安装

权限:Shizuku 授权、后台子进程统计和息屏白名单

权限 · 状态与统计

应用内的 AstrBot 管理后台

AstrBot · 内置后台

应用内的 NapCat 管理后台

NapCat · 内置后台

功能特性

功能 说明
双服务管理 AstrBot / NapCat 独立或一键启停,查看运行、连接和异常状态
内置后台 直接打开原 WebUI,预填有效的初始凭据,也可使用外部浏览器
固定缩放 默认 75%,支持 100% / 75% / 50% / 25%,关闭双指缩放
本机互联 新装准备 ws://127.0.0.1:6199/ws、空 token 的 OneBot 配对,保留自定义连接
局域网访问 两套 WebUI 可分别开放局域网访问,显示可复制地址,保留后台鉴权
人设库 内置 4 款参考社区精选整理的预设,注明来源与改编内容;支持自行新增、删除(含内置预设)、搜索、分类和默认切换,提供外部人设市场入口
实时日志 在服务详情中查看,自动跟随最新输出,可暂停、复制和脱敏导出
资源概览 显示应用及托管进程内存、手机总内存和占比,单独查看存储使用情况
备份与恢复 支持本机快照、便携备份和更新回退,自动清理未受保护的旧自动快照
SSH 扩展 默认安装、按需启动,支持修改密码、端口和局域网访问设置
Ubuntu 终端 内置本机交互终端,支持多会话、平滑触摸滚动、方向键与粘贴回车;Android 9 及以上支持选字放大镜
Linux QQ 预置轻量桌面与通用工具,原版 ARM64 QQ 按需安装;打开时自动准备桌面,支持内嵌操作及可选的局域网访问
cpolar 扩展 按需安装,内嵌官方 WebUI 登录与隧道管理,默认提供 SSH、AstrBot、NapCat 三个隧道
DeepSeek Harness 按需准备独立 Node.js 与官方工作台,显示分阶段安装进度,可选局域网访问,自行配置模型
常用网页 自定义 HTTP / HTTPS 网址,自动获取图标,在应用内访问并保存各页面缩放比例
权限管理 提供官方 Shizuku 离线安装入口,检查后台子进程数量与有效上限,按需设置本应用的息屏省电白名单
Android 设备访问 默认关闭,分别授权终端工具读屏、点击和输入;支持设备状态查询与共享目录文件交换
中英文界面 支持跟随系统、简体中文与 English,覆盖管理界面、通知与操作提示
后台引导 提供通知、电池优化、后台无限制、自启动权限及任务锁定入口,可选择在最近任务中隐藏
更新管理 App 检查新版后可选择内置下载校验安装,或交给外部浏览器下载;AstrBot、NapCat 独立更新

设置、扩展和权限采用分类标题与分组卡片,连续排列,小屏或大字号下可滚动。底部“网页”默认提供 DeepSeek 官网首页,可自行增删网址。QQ 下载显示大小、进度和速度,下载阶段可暂停、继续或停止。Linux QQ 的桌面随环境离线准备,局域网访问默认关闭,与手机共用同一个桌面会话。进入服务详情后,底部导航切换为该服务的概览、连接、凭据和日志,凭据页可重置忘记的后台密码或口令。

项目架构

原生 App 负责界面、前台服务和进程管理,AstrBot 与 NapCat 在本机 PRoot Ubuntu 中运行。默认 QQ 消息通过 OneBot 连接 AstrBot,再调用用户配置的模型;终端与扩展分别管理,设备访问由用户按需开启和授权。

项目架构:Android 原生 App 管理 PRoot Ubuntu 中的服务,展示默认 QQ 消息链路、可选扩展与设备访问

开始使用

  1. 从 Releases 下载完整 APK,在 ARM64 Android 手机上安装,打开 App 完成环境初始化。
  2. 点击“启动全部”,等待 AstrBot 和 NapCat 就绪。
  3. 打开 NapCat 后台登录 QQ,在 AstrBot 后台配置模型、平台和插件。
  4. 按“设置 → 后台运行”的引导调整手机权限,再按需使用人设、备份、SSH 和 cpolar。“设置 → 权限”提供 Shizuku 的官方离线安装包及授权入口,Android 12 及以上可分别查看本应用、全机已跟踪的后台子进程数量及有效上限,并按需调整上限;安装后仍需启动和授权 Shizuku。系统未公开的数量不会显示为 0。

完整包内置运行环境,初始化无需另外下载 Ubuntu 或安装项目依赖。QQ 登录、模型调用和在线更新需要网络,账号与 API Key 直接在对应 WebUI 中配置。更多操作见使用指南。

设备与空间

  • Android 8.0 / API 26 及以上,ARM64 架构,无需手机 Root。
  • 完整 APK 约 1022 MiB(1 GiB),比 1.4.0 增加约 175 MiB。新增预配置桌面资源用于加快全新初始化,同时保留原始离线依赖供已有环境修复;安装后还需为运行环境、QQ 数据和备份预留空间。
  • 环境准备空间不足时显示预估提醒,可选择“仍然继续”;实际可写空间耗尽仍会导致操作失败。
  • 运行占用随插件、模型调用及 QQ 状态变化;首页显示实际应用内存,不预分配虚拟机内存。
  • 持续运行需要按手机系统设置后台权限。可选开启无障碍后台辅助及默认关闭的开机恢复服务,详见后台运行。

cpolar 在“设置 → 扩展组件”中单独下载安装,客户端不打入 APK。登录官方 WebUI 后自动保存令牌,可管理三个默认隧道;隧道目标服务需在 App 中启动,服务能力以 cpolar 账号套餐为准。

可选方案:SnowLuma 手动部署

SnowLuma 是另一个提供 OneBot v11 接口的 QQ 互操作项目。NapCat README 推荐其作为 NapCat Gui 替代品;希望了解其他接入方式的用户,可以阅读本项目整理的手机手动部署与 AstrBot 对接教程。

教程使用 App 的通用 Ubuntu、桌面、原版 QQ 和终端,由用户另行获取官方完整包、手动部署并连接 AstrBot。App 默认方案仍为 NapCat,使用本教程时保持 NapCat 停止。SnowLuma 采用源码可见非商业许可,原生组件另有专有条款;请先阅读官方 LICENSE 和 EULA。本仓库不附带其程序,示例命令需用户自行复制执行;专用入口仍待许可审核,教程不代表上游背书或额外授权。

源码构建

使用 JDK 17、Android SDK 35、NDK 和 Python 3.11+。编译应用源码:

./gradlew.bat :core:compileKotlin :app:compileBootstrapReleaseKotlin

完整 APK 需要另外准备运行镜像、原生资源和许可输入,大型资源与本机配置不进入 Git。准备好输入和长期签名后,Windows 双击根目录 build.bat,其他系统执行 python3 -B tools/build_release.py,即可完成正式构建、签名和校验。默认输出到 dist/,具体步骤见构建指南。

长期密钥及密码位于 Git 已忽略的 .local/signing/,后续版本持续复用;首次创建与备份方法见一键构建正式包。

更新

“设置 → 关于 → 检查更新”管理 App 安装包:发现新版后弹窗显示说明,可选择“下载并安装”或使用外部浏览器下载。内置下载完成后自动校验,再进入系统安装器;缺少安装权限时引导授权,返回后继续。当前已是适用的最新版本时会明确提示。AstrBot 与 NapCat 各有独立的程序更新入口。内置流程保留签名校验、断点续传、安装前快照和组件失败回退,APK 安装由系统确认。

默认接入本项目的 GitHub 签名更新通道:Releases 存放安装包和 AstrBot 程序包,updates 分支托管签名目录,NapCat 直接下载上游官方 Shell 包。只有 QQ、Python 或底层依赖变化时,才需要匹配的运行环境升级。配置方式见更新与分发。

交流与反馈

加入 QQ 交流群

欢迎加入 QQ 交流群,交流 App 使用、AstrBot / NapCat 配置、人设分享和功能建议。也可以通过 GitHub Issues 反馈问题,便于跟进和检索。

文档

开源协议与致谢

本项目原创代码采用 MIT License,Copyright © 2026 JunWan666。使用或分发时请保留版权声明和许可文本。

感谢 AstrBot、NapCatQQ、PRoot、Ubuntu、Termux 及相关开源项目。第三方组件遵循各自的许可与分发条款,详见 NOTICE 和 第三方声明。

Star History

AstrBot for Android Star History
Apps
About Me
GitHub: Trinea
Facebook: Dev Tools
AI Daily Digest