一、项目介绍
AstrBot 安卓 App 是一款把你自己的 QQ 号变成 AI 聊天机器人的 Android 应用。它不是一个普通的单机聊天窗口，也不是一个本地大模型工具箱，而是把原本需要在电脑上通过命令行部署的多平台聊天机器人框架，完整打包进了一个手机安装包。用户只需要一部安卓手机，安装应用、等待环境初始化、扫码登录 QQ、填入大模型密钥，就能让这个 QQ 号自动收发消息、调用大语言模型与人对话。
它的底层框架是开源的 AstrBot——一个专注于把大语言模型接入日常社交工具的多平台聊天机器人框架，官方支持 QQ、微信、飞书、钉钉、Telegram、Discord 等十五种以上消息平台，并提供多轮对话、知识库、代码执行器、网页搜索、待办事项、长期记忆等高级能力。原始 AstrBot 采用 AGPL-3.0 协议，需要 Linux 或 Windows 环境、命令行操作与浏览器管理后台，对没有技术背景的用户并不友好。
这款安卓 App 的核心价值，在于把复杂系统封装成普通人也能上手的图形界面。它在手机内部通过 Ubuntu Proot 容器运行 AstrBot 主程序，并深度集成了 NapCatQQ 协议端，免去了手动配置 OneBot 通信接口的步骤。应用由 JunWan666 开发并在抖音等平台发布，采用 MIT 许可，无需 Root 即可运行，目标人群是学生、非 IT 从业者以及任何希望用自己的 QQ 号拥有一个 AI 助手的普通用户。
需要说明的是，当前版本聚焦 QQ 个人账号这一场景，暂不支持微信、Telegram、钉钉等其他平台登录；代码执行器依赖 Docker 沙箱，手机内的 Ubuntu 容器默认未安装，因此该功能在 App 内默认不可用。这种取舍是为了换取一键安装、零配置的完整体验。
二、项目结构
从技术构成上看，这款 App 并不是一个简单的 WebView 壳，而是一个分层打包的运行时系统。最外层是用 Kotlin 编写的原生 Android 应用界面，使用 Jetpack Compose 构建原生控件，负责环境初始化进度展示、服务启停按钮、运行状态监控、日志实时查看、配置备份与恢复、在线更新入口以及常驻通知管理。
中间层是基于 Code LFA 项目提供的安卓端 Ubuntu 容器环境，通过 Proot 技术在非 Root 手机上模拟出一个完整的 Linux 用户空间。首次启动时，App 会在这个容器内自动安装 Python 环境、uv 包管理器以及 NapCat 组件。NapCat 是一个高效稳定的 QQ 协议适配器，负责把 QQ 客户端的协议消息转换成 OneBot 标准事件，再转发给上层的 AstrBot 主程序。
最内层是 AstrBot 主程序本身，由 Python 编写，运行在容器内的虚拟环境中。它通过内置的 WebView 加载浏览器仪表盘，把消息平台、模型提供商、插件、指令、会话管理等全部配置暴露在图形界面中。App 预置了一条名为 pre-config 的通信接口，内部已经填好 NapCat 的连接地址与端口，用户无需手动创建或修改。整体结构可以概括为：原生 Kotlin 界面 + Ubuntu Proot 容器 + NapCat 协议端 + AstrBot 核心 + 内置 WebView 控制台。
三、版本与环境要求
在开始部署之前，请先确认你的手机满足以下条件。操作系统方面，应用要求 Android 8.0 及以上版本；架构方面，仅支持 ARM64 设备，也就是说市面上绝大多数近两年发布的安卓手机都可以运行，但部分老旧的 32 位设备或 x86 模拟器无法正常启动容器。应用无需 Root 权限，通过 Proot 即可在普通用户空间内运行 Linux 环境。
网络环境方面，首次启动必须在网络通畅的条件下进行，推荐使用家用 Wi-Fi 或手机 5G 流量。校园网、公司内网、公共 Wi-Fi 等存在限速、代理或端口限制的网络，可能导致 Ubuntu 镜像、Python 依赖或 NapCat 资源下载失败。初始化过程中需要从远程仓库拉取较大体积的文件，请预留充足的磁盘空间与电量，建议连接充电器并保持屏幕常亮。
大模型方面，你需要自备一个模型服务商的 API Key。AstrBot 支持 OpenAI、Anthropic、Gemini、DeepSeek、智谱清言、通义千问、Ollama 本地模型以及 Dify 等多种接入方式。如果你没有现成的密钥，可以前往对应服务商的开放平台注册账号并创建令牌。权限方面，首次启动后必须授予通知权限，否则系统会在息屏或切后台时杀死服务，机器人将无法持续收发消息。
四、本地部署步骤
整个本地部署过程不需要电脑、不需要命令行，全部在手机上完成。第一步是获取安装包。项目作者把运行时拆成了两部分分发：基础 Sandbox App 与 AstrBot 皮肤压缩包。你需要前往 Android-DIY-Sandbox 的 Releases 页面 下载最新的 Sandbox 安装包，再前往 AstrBot-android-lua 的 Releases 页面 下载最新的皮肤 zip 文件。先安装 Sandbox APK，安装完成后不要立即打开，而是在 Sandbox 设置页顶栏点击载入按钮，选择下载好的 zip 文件完成皮肤加载。
第二步是首次初始化。打开应用后，屏幕会显示白色进度条，表示正在联网下载 Ubuntu 容器、uv 包管理器与 NapCat 等资源。点击屏幕任意位置，可以在进度条页面与模拟终端日志页面之间切换。作者强烈建议你切入终端日志页面持续观察，这样能第一时间发现网络阻塞或下载失败。整个初始化过程耗时较长，尤其是 NapCat 组件对网络稳定性要求很高；如果中途卡住，可以直接关闭 App 再重新打开，系统会从中断处继续。如果终端提示 dpkg was interrupted 之类的系统包配置错误，最稳妥的做法是进入手机设置的应用管理，找到 AstrBot 应用并清除全部数据，然后重新启动。
第三步是登录 QQ。初始化完成后，NapCat 与 AstrBot 会同步启动，界面上会弹出 QQ 登录二维码。使用你手机上的 QQ 客户端扫码即可。扫码过程中可以自由切换后台，比如截图、切到 QQ 扫码，再切回 App 仍能正常进入控制台。登录成功后二维码窗口自动消失，内置 WebView 会加载 AstrBot 的浏览器仪表盘。此时请下拉通知栏，确认出现常驻的"正在运行"通知，千万不要手动划掉这条通知，否则服务会立即终止。
第四步是配置大模型。进入仪表盘后，前往"模型提供商"页面，新增一个提供商并填入你从服务商那里申请到的 API Key，选择对应的模型名称，保存后重启机器人即可。关于具体字段的填写方式，可以参考 AstrBot 官方文档的接入大模型服务章节。至此，你的 QQ 号已经具备自动回复能力，可以用另一个账号在私聊或群聊中 @ 它进行测试。
五、浏览器端部署：AstrBot WebUI 管理端
虽然 App 是安卓应用，但它的管理界面本质上是一个运行在本地 Web 服务上的仪表盘，App 只是用内置 WebView 把它嵌了进来。理解这一点后，你也可以在同一局域网内用电脑浏览器访问这个管理端，获得更大的操作屏幕。
首次进入控制台时，默认用户名与密码均为 astrbot。登录后系统会提示你立即修改密码，请务必完成这一步，避免本地服务被他人随意访问。管理端左侧导航包含"机器人""模型提供商""插件""指令""会话""日志""设置"等栏目。在"机器人 → 通信接口"页面，你会看到一条名为 pre-config 的预置条目，它就是 App 自动配置好的 NapCat 连接通道，不要修改或删除它，否则机器人会立刻失去与 QQ 的通信能力。
在"模型提供商"页面，点击新增按钮，选择你使用的服务商类型，填写 API Base URL（如有需要）、API Key 与默认模型名称。保存后回到机器人控制台，点击重启按钮让配置生效。如果你希望接入本地 Ollama 模型，可以在同一台机器或局域网另一台设备上运行 Ollama 服务，然后把 Base URL 填成对应地址。在"插件"页面，你可以开关翻译、网页搜索、记忆系统、天气查询等官方插件，每个插件都可以独立配置参数。日常运行中，如果想查看机器人为什么没有回复某条消息，打开"日志"页面即可看到完整的请求与错误堆栈。
六、API 用法
AstrBot 框架本身提供了完整的 RESTful API 与 WebSocket 接口，方便开发者把机器人能力集成到自己的业务系统中。在安卓 App 里，这些接口同样监听在容器内的本地端口上。默认情况下，管理后台运行在本机的 6185 端口，你可以通过浏览器访问 http://127.0.0.1:6185 进入仪表盘。
调用业务接口时，需要先在管理端"设置"中创建一个 Personal Access Token，后续所有请求都在 HTTP 头中携带 Authorization: Bearer <token>。常见的接口路径包括发送消息、获取会话列表、管理插件状态、读取运行日志等。发送消息接口通常接收目标平台、接收者 ID 与消息内容三个字段，返回值中包含消息 ID 与时间戳。除了 HTTP 接口，AstrBot 还暴露 WebSocket 网关，用于实时接收事件推送，例如当某条消息被机器人接收或回复完成时，网关会向已连接的客户端广播事件，适合做二次开发与自动化脚本。
对于普通用户而言，App 已经把这些 API 全部封装成了按钮与表单，不需要手写请求。但如果你是开发者，希望利用 AstrBot 的事件总线与流水线架构做扩展，可以参考官方文档中的事件列表与插件开发指南，用 Python 编写自己的插件，再通过 App 的插件目录加载。需要注意的是，安卓容器内没有预装 Docker，因此依赖代码执行器沙箱的插件在当前 App 环境下无法运行。
七、常见问题 FAQ
问一：首次初始化一直卡在 NapCat 安装进度怎么办？
这通常是网络不稳定导致的。可以先点击屏幕切到终端日志页面，观察最后一行报错。如果是超时或连接重置，直接关闭 App 重新打开，系统会断点续传；多次重启仍失败时，进入手机设置清除应用数据后重来。整个过程建议连接稳定的 Wi-Fi，并保持屏幕常亮。
问二：为什么扫码登录后收不到任何消息？
请依次检查：通知栏是否常驻"正在运行"通知且没有被手动划掉；管理端"通信接口"中的 pre-config 是否仍然存在且没有被修改；模型提供商是否已经填好有效的 API Key 并重启过机器人。另外，QQ 风控可能会对新登录的设备进行限制，可以在 QQ 客户端内完成安全验证后再试。
问三：通知权限被我拒绝了，现在机器人后台总被杀怎么办？
进入手机设置的应用管理，找到 AstrBot，在权限管理中重新打开通知权限。部分国产 ROM 还需要手动允许后台弹出、自启动、电池优化白名单等选项，否则系统在息屏一段时间后会终止容器进程。
问四：可以同时登录多个 QQ 号吗？
AstrBot 框架本身支持多实例部署，但当前安卓 App 的皮肤包只内置了一条 pre-config 通道，面向单账号场景做了简化。如需多账号，建议在电脑或服务器上部署原生 AstrBot，并按官方文档添加多个 QQ 协议端。
问五：清除应用数据后，我的配置和聊天记录还在吗？
清除应用数据会删除容器内的全部文件，包括 AstrBot 配置、NapCat 登录态与插件数据。建议在管理端或 App 的备份功能中定期导出配置压缩包；如果只是想解决初始化失败问题，可以先尝试重启 App 而非直接清除数据。