astrbot-for-android
AstrBot for Android
简体中文 | English
把 AstrBot 和 NapCat,装进你的 Android 手机。
一个 APK · 本地运行 · 原生管理 · 内置 WebUI
下载 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 手动部署及运行管理仍为预览功能,适用许可范围仍需确认,不附带其程序。完整变化见更新记录。
界面预览
以下八张手机实机截图展示服务管理、人设、常用网页、分类设置、扩展、权限及两套内置后台。
首页 · 服务与资源 |
人设 · 搜索与切换 |
网页 · 常用地址 |
设置 · 分类管理 |
扩展 · 按需安装 |
权限 · 状态与统计 |
AstrBot · 内置后台 |
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,再调用用户配置的模型;终端与扩展分别管理,设备访问由用户按需开启和授权。
开始使用
- 从 Releases 下载完整 APK,在 ARM64 Android 手机上安装,打开 App 完成环境初始化。
- 点击“启动全部”,等待 AstrBot 和 NapCat 就绪。
- 打开 NapCat 后台登录 QQ,在 AstrBot 后台配置模型、平台和插件。
- 按“设置 → 后台运行”的引导调整手机权限,再按需使用人设、备份、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 交流群,交流 App 使用、AstrBot / NapCat 配置、人设分享和功能建议。也可以通过 GitHub Issues 反馈问题,便于跟进和检索。
文档
- 使用指南:后台配置、人设、网页、权限、设备访问、扩展、资源和备份。
- SnowLuma 手动部署:官方原包的手机手动部署、AstrBot 对接、常见问题及来源许可。
- 构建指南:开发环境、运行资源和 APK 构建。
- 更新与分发:应用签名、更新通道和 GitHub 发布。
- 发行材料:第三方许可、依赖清单和源码伴随包。
- 更新记录 · 参与开发 · 提交规则。
开源协议与致谢
本项目原创代码采用 MIT License,Copyright © 2026 JunWan666。使用或分发时请保留版权声明和许可文本。
感谢 AstrBot、NapCatQQ、PRoot、Ubuntu、Termux 及相关开源项目。第三方组件遵循各自的许可与分发条款,详见 NOTICE 和 第三方声明。

