# 使用指南 ## 首次运行 安装完整 APK 后打开应用,完成运行环境初始化,再点击首页“启动”。首页只管理 AstrBot,显示 App 与组件版本、启动阶段和资源占用;后台探测确认就绪后才显示运行中。模型、插件、人设与运行日志可从首页快捷入口进入。 AstrBot 的模型和插件沿用原项目的 WebUI;QQ 官方机器人和微信官方 ClawBot 可从首页进入原生页面配置。配置通过 AstrBot 接口保存,不额外维护第二套机器人配置。 ## 消息平台 首页“消息平台”区域提供 QQ 官方机器人和微信官方机器人入口,每页只管理对应平台。启动 AstrBot 后,原生页面通过上游的本机会话接口自动连接,无需再次填写后台密码。未绑定时进入页面直接获取并显示官方授权二维码,扫码授权成功后自动保存并接入,无需先点“添加接入”。已绑定时直接显示机器人,可重新绑定、启用、停用或删除本机接入;删除前需确认,删除后直接回到扫码区域,不会注销官方平台上的机器人。如需撤销官方授权,请在对应官方平台操作。需要多个机器人时可用“绑定其他机器人”。名称等选项收在“更多设置”;其余平台与高级配置保留。首页显示未绑定、已绑定以及适配器运行、停止、停用或异常状态;“已绑定”表示本机已有保存的接入配置,消息能否收发仍需发送消息验证。会话令牌仅保存在页面内存,重启服务后重新建立本机会话;升级后仍在使用旧进程时,按页面提示重启 AstrBot 一次。 - **QQ 官方机器人**:默认使用 QQ 扫码并按官方页面完成机器人授权,也可切换“手动填写 AppID / Secret”。请在 QQ 开放平台确认测试成员或发布范围。本页新增采用 WebSocket,不需要公网回调;已有 Webhook 配置仍保留其方式与高级设置。官方机器人的身份和权限与个人 QQ 不同。 - **微信官方机器人**:通过微信官方 ClawBot(openclaw-weixin / iLink)接口扫码授权机器人。页面取得机器人 Token 后自动保存,AstrBot 使用 Token 收发消息,不托管微信客户端账号登录态。此入口不是公众号或企业微信。当前上游要求 AstrBot 4.22.0 及以上、Android 微信 8.0.69 及以上,并具备 ClawBot 功能。使用长轮询,无需公网回调。原生配置接口未提供时请更新 AstrBot,也可在其后台配置。 微信入口使用官方 ClawBot 机器人授权。非官方个人账号托管或协议登录存在账号受限风险,与本入口的接入方式不同;使用 ClawBot 仍需遵守微信平台规则。 状态区分未配置、停用、准备、运行、异常和待检测。“适配器运行”表示 AstrBot 已启动适配器,远端回调与消息往返仍需发消息验证。配置变更、观察记录过期或旧版不能提供可靠状态时显示待检测;缺少适配器时提示更新 AstrBot。 本机会话仅用于 App 内配置,不关闭后台密码认证,也不修改用户密码。普通浏览器和局域网访问仍需按 AstrBot 要求登录并完成必要的密码设置。运行服务由 App 管理,更新和重启优先使用 App 的操作入口。 默认 Ubuntu DNS 自动跟随手机当前网络,切换网络后刷新;手工修改的 `etc/resolv.conf` 保留。普通操作成功提示在首页短暂显示后自动消失;错误与存储空间告警保留。扫码授权成功后无需再点保存;若保存失败,请停留在当前页面直接重试,无需重新扫码。配置已保存但连接加载异常时会单独提示,请查看连接状态与运行日志。二维码授权需要手机能访问对应平台;请求失败时可点击“重新扫码”,持续失败可查看 AstrBot 运行日志。 ## 后台登录与缩放 服务详情的“凭据”页可查看、隐藏和复制初始信息。AstrBot 后台默认使用 75% 缩放,可切换 100%、75%、50%、25%,也可从连接页打开外部浏览器。 App 内打开 AstrBot 后台时会自动填入仍有效的初始凭据。点击登录后,在设密页填写并确认新密码即可进入后台。首次改密后使用新密码登录。 所有内置网页的“×”关闭按钮位于右上角三点菜单左侧,点击直接返回打开它之前的 App 页面,不需要反复退出网页历史,也不会停止正在运行的服务。 “网页”中的收藏地址未填写协议时默认补充 `http://`,例如 `127.0.0.1:3080`;手动填写的 `https://` 保持不变。收藏网页默认缩放 50%,可在右上角菜单调整,每个地址单独记忆;已保存的缩放设置继续生效。 ## APK 安装问题 完整包要求 Android 8.0 及以上、ARM64 系统。从项目 Release 下载完整 APK,并与同页 `SHA256SUMS` 中的摘要核对;下载未完成、文件被修改或摘要不一致时请重新下载。不要直接解压再重新压缩 APK。 初始化时出现“Ubuntu 资源完整性校验失败”,表示从 APK 读取的内置环境摘要与随包清单不一致,尚未开始解包。请从官方 Release 重新下载完整 APK,核对摘要后覆盖安装并重试。若仍失败,请提供 App 版本、手机型号、Android 版本、APK 下载来源及设置中导出的诊断包。 正式构建同时携带 v1、v2、v3 签名,沿用长期证书。若安装器仍提示“安装包没有签名文件”,请提供手机型号、Android 版本和下载文件的 SHA-256,以便区分文件损坏与系统安装器兼容问题;仅凭该提示无法判断实际缺少哪种签名。 ## 服务与局域网访问 首页启动、停止和重启只操作 AstrBot;QQ 官方机器人与微信官方 ClawBot 从首页配置。进入 AstrBot 详情后,底栏切换为“概览 / 连接 / 凭据 / 日志”。 在对应服务的“连接”页开启局域网访问后,使用同一网络下的设备访问页面显示的地址。每套后台单独控制,原有登录鉴权保留;App 内仍使用本机地址。网络切换后请使用当前显示的局域网地址。 1.4.0 新增 AstrBot 实例检查:启动前通过独立锁避免重复实例,并检查配置中的实际后台端口,包括默认 6185。已有实例响应时保留原进程,提示先在原会话停止;确认来自本环境、已运行超过启动宽限期且连续无响应的旧 AstrBot,才尝试先正常结束、必要时强制结束该 Python 进程,等待端口释放后再启动。不会按端口或进程名称批量结束 Ubuntu、桌面或 QQ,也不依赖读取 Android 限制的 `/proc/net/tcp`。无法确认身份的占用仍需用户处理,不会无限重复拉起。 ## 人设管理 首页“人设管理”打开 AstrBot 自己的人设页面,与模型配置、插件管理使用同一套后台登录和缩放设置。管理器不再提供独立人设库或内置预设;已导入 AstrBot 的人设和用户原有文件保留,旧版未完成的人设修改仍会按恢复记录处理。 ## 任务 底部导航为“首页 / 终端 / 任务 / 网页 / 设置”。五个页面在同一窗口内直接切换;终端键盘收起时可以通过底部导航切换页面,已有会话保持运行。 任务页管理用户自己部署的 Ubuntu 程序。先在终端完成安装与依赖准备,再点击“添加任务”,填写名称、Ubuntu 绝对运行目录和启动命令。命令支持环境变量、引号和多行脚本;保存后手动点击启动,不会在保存时执行。 任务使用非交互方式运行,请让主程序持续在前台,不要添加 `&`、`nohup` 或后台守护参数;需要输入密码、确认或交互控制时使用终端。任务页不会自动识别或接管普通终端中已经运行的程序。页面显示进程运行状态,不代表程序的网络接口或业务连接已经就绪。 每个任务可启动、停止、重启、查看或清空日志;停止后可在更多菜单中编辑,删除前需要确认,运行中的任务会先停止。删除仅移除任务配置和日志,保留程序文件及安装目录。最多保存 32 个任务,同时运行 8 个。 进程由前台运行服务持有,切换页面或返回桌面不主动停止。停止只处理该任务拥有的进程树,不按程序名或端口结束其他服务。环境更新、备份或恢复等维护会停止任务并注明原因,完成后需手动重新启动。任务不随开机自动启动;Android 杀掉 App 或底层进程后,任务仍可能中断,不能以任务管理代替系统后台权限。 日志最多保留当前和一个轮转文件,每个 512 KiB;常见凭据脱敏,超长单行省略。部分程序需要启用无缓冲输出,例如 Python 使用 `-u`,才会及时显示日志。任务名称、命令和输出不加入管理器诊断包。任务配置与日志保存在本机 App 数据中,覆盖升级保留,当前便携备份不包含任务配置;卸载 App 前请自行记录所需命令。 程序如果在启动时输出可识别的初始密码(如 `initial credentials: user=… password=…` 或 `Initial password: …`),可以在“任务 → 日志”顶部查看或单独复制。密码暂存在内存,停止任务或清空日志后失效。升级前已脱敏的日志无法恢复原密码,如程序会重新生成初始密码,可重启任务后查看。 ## 权限与后台子进程 “设置 → 权限”提供可选的 Shizuku 接入。没有安装时可提取随包的未修改官方安装包,校验摘要及原签名后打开系统安装器;未允许安装应用时先引导授权。安装后在 Shizuku 中启动服务,再返回本应用点击授权。非 Root 的 Android 11 及以上设备通常可在手机开启开发者选项与无线调试后完成配对;较旧系统通常需要电脑 ADB。重启手机后需重新启动 Shizuku,内置安装包不会直接获得 ADB 权限。 授权后可在 Android 12 及以上读取后台派生子进程的有效上限,按需设为 256,或恢复系统默认。此设置影响全机应用,与开发者选项中的“后台进程限制”不同;App 不会自动修改,也不关闭系统的全部进程监控。以页面重新检测的有效值为准,厂商系统可能不支持、覆盖或重置配置。此功能不能阻止所有厂商清理或内存不足导致的退出。 页面分别显示 Shizuku 服务版本及 UID、系统配置值和实际有效值。仅配置保存成功时会提示“尚不能确认实际生效”;未公开有效值时不会推测系统上限。授权后仍检测失败,可打开 Shizuku 确认服务与后台运行权限,返回重新检测;“复制检测信息”包含机型、Android 版本及操作结果,便于排查厂商差异。 权限页的“后台子进程”并列显示本应用已跟踪数量、全机已跟踪数量及有效上限。数量来自 Android 最近一次活动子进程记录,按本应用 UID 统计,不是全机所有 Linux 进程的数量;系统记录可能短暂滞后,可通过“重新检测”更新,并查看检测时间。缺少授权、系统未提供或记录格式无法识别时显示“—”,不会以 0 代替未知。32 是 Android 12 起的常见默认上限,由全机共享;256 是可选参考值,不预先创建或分配进程,运行稳定时无需强制修改。常用操作集中在主页面,Shizuku 配置步骤、统计口径和保活限制可点各卡片右侧说明查看;小屏或较大系统字号下可滚动浏览。 部分系统会阻止 Shizuku 启动检测服务。App 会在已授权的兼容版本上尝试备用连接;若仍然失败,请打开 Shizuku 确认运行状态后返回“权限”重试,并复制检测信息用于排查。授权状态本身不代表系统设置已经生效。 “息屏省电白名单”调整 Android 的休眠豁免;部分系统的“后台耗电无限制”会同步到同一份白名单,不能理解为两层独立保护。厂商额外的后台策略仍可能需要单独允许。“自启动”是自动拉起许可,既不代表运行期间不受休眠影响,也不等于已经开启 App 的“开机恢复服务”;子进程上限则是独立的全机数量限制。 ## 后台运行 在“设置 → 后台运行”中,每项右侧显示当前状态。通知和电池优化读取系统状态,从系统设置返回后自动刷新;后台耗电、自启动、最近任务锁定没有可靠的通用检测接口,需要按说明完成设置后勾选“我已按说明检查并完成设置”,显示“已手动确认”。确认记录可随时取消,点击设置按钮不会自动标记完成。 每项详情只提供一个主要操作按钮,优先打开本机对应设置,无法直达时自动尝试备用入口。顶部将“系统检查”和“手动确认”分开计数。 “在最近任务中隐藏”默认关闭。开启后隐藏本应用的最近任务卡片,减少误划关闭,仍可从桌面图标或运行通知进入;关闭开关后恢复显示。后台运行页集中在一个页面,小屏幕或较大字号下可上下滑动。此开关不代替系统的电池和子进程限制设置,也不保证进程不会被系统终止。 1.4.0 新增“后台运行 → 运行辅助”子页面,将辅助开关与系统后台设置分开,减少主页面滚动: - **无障碍后台辅助**:默认关闭,由用户在系统无障碍设置中开启。通过系统绑定的服务和不接收触摸的透明小窗口辅助后台驻留;状态区分系统已开启、实际连接、窗口是否可用。它不读取屏幕、文字或通知,不点击或输入,与“终端设备辅助”的读屏和控制授权独立。关闭不会停止已运行的服务。 - **开机恢复服务**:默认关闭,不依赖无障碍或 Shizuku。开启后,开机首次解锁、应用覆盖更新或后台辅助重新连接时,尝试恢复保存为开启状态的 AstrBot、SSH、cpolar、Harness、桌面与独立 QQ;用户之前停止的服务保持停止。终端中执行的命令、手动部署程序及设备控制权限不会自动恢复。页面记录最近恢复请求是否成功交给运行服务,实际就绪状态仍以首页和对应扩展为准。 不同厂商的设置名称和行为可能不同,仍需按系统要求允许自启动和后台运行。辅助服务不能解除 Android 的后台子进程限制。手机系统终止应用后,可重新打开 App,按保存的运行意图恢复服务;系统“强行停止”应用后须手动打开,后台辅助无法保证应用或 Linux 子进程永不被终止。 ## 终端 从底部“终端”进入。首次使用前先在首页准备 Ubuntu 环境;终端直接进入现有环境,无需启动 SSH 或额外下载终端组件。 点击标签栏右侧的 + 新建终端,点击标签在不同会话间切换,最多保留 8 个会话。程序正在一个终端输出日志时,可以另开终端执行其他命令,原会话继续运行。顶部键盘按钮左侧的 − / + 可快速调整字号,首次默认最小值 10,主动调整后保存选择。Ctrl 为单次组合键,下方提供 Esc、Tab 和方向键;第一排末尾为“粘贴”,第二排末尾为“回车”,多行粘贴前会要求确认。 上下键对齐,左右键位于下键两侧,Tab 在左下角: ```text Ctrl Esc ↑ / 粘贴 Tab ← ↓ → 回车 ``` 长按输出可选择文字,拖动两端手柄调整选区,点击“复制”;Android 9 及以上在长按和拖动时显示放大镜,松手收起,旧版 Android 保留原有选字功能。也可全选,或在右上角菜单复制终端内容。滑动查看历史支持惯性滚动,不显示滚动条;查看历史时保留当前位置,点击“最新输出”回到底部并继续跟随日志。 返回页面、切换标签或打开其他应用不会主动停止终端;关闭标签只结束该会话和由此启动的进程。通知中的“结束全部终端”关闭所有终端进程。App 被系统终止、手机重启或运行环境维护会结束全部会话,命令不会自动重放。近期输出仅保存在内存中,每个会话最多 512 KiB,界面显示最多 2,000 行;命令与输出不写入管理器日志。 如果显示“Shell 已退出(137)”,先保留现场查看系统日志。Android 12 及以上可能因后台子进程数量限制而清理 PRoot 或 Shell;确认日志含 `Trimming phantom processes` 后,可在“设置 → 权限”中通过已授权的 Shizuku 检测并按需调整上限;也可在已授权的 ADB 电脑上执行 `adb shell device_config put activity_manager max_phantom_processes 256`,再用 `adb shell dumpsys activity settings` 检查实际生效值。该系统设置需用户主动授权和操作,App 不会自动修改;部分系统可能不支持或重置。撤销用 `adb shell device_config delete activity_manager max_phantom_processes`。退出码 137 也可能有其他原因,不能只凭退出码确定。恢复会话后需手动重启被清理的程序,已安装文件通常仍保留。 这里提供的是 PRoot Ubuntu 用户态环境,Ubuntu 的 root 不代表手机 Root。手动部署的软件需自行维护和备份,并遵守各自许可;不会自动加入首页服务管理。终端会话与 SSH 会话互相独立。 若显示“Shell 已退出(143)”,通常对应 SIGTERM,但程序也可能自行返回此退出码,不能仅凭数字判定系统清理。先在“日志与诊断 → 管理器”查看对应 `terminal` 记录,包含会话编号、退出码、运行时长、息屏/休眠及电池优化状态;主动结束会话会记录 `stop-requested`,不保存命令或输出。旧版运行器曾存在启动线程结束后提前停止会话的问题;1.3.0 已从当前源码重编并核对运行器。升级后仍退出时,应结合对应日志继续排查。 “设置 → 权限 → 息屏省电白名单”可在 Shizuku 运行并授权后,仅为本应用添加系统休眠豁免;由用户主动操作,写入后读取用户白名单并用 Android 电池优化接口确认。移除按钮仅移除本应用的用户白名单条目,保留系统内置豁免。未使用 Shizuku 时也可打开系统电池优化设置。该功能补充已有前台服务和唤醒锁,可能增加息屏耗电;不关闭全机休眠,不调整其他应用,不保证阻止厂商清理、内存回收或子进程终止。子进程数量上限仍是独立设置。 Ubuntu 同时映射本应用运行目录的 Android 宿主路径,程序通过 `/proc` 获得文件路径后可继续读取同一文件。此映射随每次启动建立,无需用户创建路径链接。 ## SSH “设置 → 扩展组件 → SSH 终端”默认已安装,按需启动。默认账号 `root`、端口 `8022`,密码随机生成,仅监听本机。 可以查看或修改密码、调整端口、单独开启局域网访问,也可卸载和重新安装 SSH 扩展。这里的 `root` 属于 Ubuntu 运行环境,不赋予手机 Root 权限。SSH 提供交互终端和命令执行,不包含 SFTP。 ## 语言 在“设置 → 语言”选择跟随系统、简体中文或 English。语言选择保存在本机,切换时页面会重新创建,服务继续运行。Android 13 及以上也支持系统的应用语言设置。 这里只切换管理器界面、通知和自身提示。AstrBot 的 WebUI 语言由各自项目控制;已有人设正文、用户输入和历史日志不翻译,不更改数据库标识或备份格式。 ## DeepSeek Harness 在“设置 → 扩展组件 → DeepSeek Harness”按需安装。首次需联网并准备至少 1.5 GiB 可用空间,使用独立 Node.js 24 和固定版本的官方 npm 包,不替换其他服务的运行环境。安装期间显示进度,完成后启动本机工作台,点击“打开工作台”在内置页面配置模型与 API Key、选择工作目录。 安装依次显示下载、校验、解压、系统依赖、程序依赖和验证六个阶段。下载量保留一位小数,下载结束后补齐最终计数;依赖安装显示已用时、本阶段耗时、最近输出以及获取或编译活动。阶段序号表示完成步骤,不表示剩余时间;首次依赖编译可能需要几分钟,没有可靠的总百分比或预计完成时间。可打开日志查看实际输出。 工作台默认只监听 `127.0.0.1:3080`。关闭页面不会停止服务,可在扩展页停止或重新启动,并查看日志。卸载扩展删除程序与专用 Node.js,保留 `/manager/extensions/harness/workspace` 及独立 `home` 目录中的配置;清除 App 数据或重建环境前需要自行备份,这些数据不在普通机器人备份范围内。该项目属于官方开发预览版,保留其模型操作确认流程。 “访问地址”显示当前 Wi-Fi 或以太网 IP。按需开启“允许局域网访问”后,工作台重启并绑定一个具体网卡地址;上游不支持 `0.0.0.0`。点击“复制访问链接”取得含认证凭据的链接,在同一网络的其他设备使用。链接不要公开分享;关闭开关后重新绑定本机地址,换网后需重新启动以更新绑定地址。 ## Android 设备访问与共享文件 设置、扩展和权限使用小字分类标题与分组卡片,所有菜单连续排列,小屏或大字号可以滚动。 在“设置 → 权限 → Android 设备访问”主动开启。默认只允许查询设备和本 App 的服务状态;“允许读屏”和“允许点击和输入”分别开启,可随时关闭,在通知栏也能关闭整个会话。桥接只使用本 App UID 可连接的私有 Unix 套接字,不监听网络端口。关闭后撤销令牌,App 进程重启后需重新开启;锁屏时拒绝读屏和输入操作。 Shizuku 提供截图、按键及固定的点击、滑动等操作,不向 Ubuntu 开放任意 shell 身份命令。可选开启系统无障碍中的“终端设备辅助”,补充界面结构读取和中文输入;文字插入当前获得焦点的非密码编辑框,部分 App 的自绘输入框可能不支持。仅用 Shizuku 输入时支持普通 ASCII 文本。没有这两类后端时仍能查询设备与 App 状态;截图需要 Shizuku。此功能不会自行解锁手机。 新开 Ubuntu 终端可直接执行下列命令。已有终端也可使用完整路径 `/manager/bin/android-device`。dsh 通过其普通终端工具调用这些命令,可先让它阅读 `android-device --help`,不需要修改 dsh 本体。 ```bash android-device info android-device app-status android-device tree android-device screenshot /android-share/screen.jpg android-device tap 200 500 android-device swipe 200 800 200 300 --duration 400 android-device input '你好' android-device key back ``` 截图返回原屏幕尺寸和缩小后的图像尺寸,按原始屏幕像素传入点击坐标。输入内容也可通过标准输入传入,避免保存到 Shell 历史。桥接不将输入文本、界面内容、图片或会话令牌写入管理器日志。 `/android-share` 是本 App 与 Ubuntu 共用的文件目录,环境变量 `ANDROID_SHARED_DIR` 指向此处。“导入文件”通过系统文件选择器复制文件进去,每次上限 512 MB;“导出文件”可保存目录顶层的普通文件。已有终端若看不到新映射,重新打开该终端。该目录不会自动映射其他 App 的私有数据,卸载本 App 会删除目录内容,请先导出重要文件。 Ubuntu 中的 `root` 是 PRoot 模拟身份,不是手机 Root。Shizuku 通常使用 ADB shell 身份,也不能普遍读取其他应用的 `/data/data`。`/sdcard/Android/data` 的访问另受 Android 版本及厂商限制,挂载路径不会绕过这些权限。 ## cpolar 内网穿透 在“设置 → 扩展组件 → cpolar 内网穿透”安装。需先初始化 Ubuntu 环境;目前支持 ARM64 手机,按需从 [cpolar 官网](https://www.cpolar.com/download)下载 Linux ARM64 客户端 3.3.12,校验摘要并检查运行能力后安装,客户端不打入 APK。 安装后启动 cpolar,点击“打开后台”使用官方账号登录并管理隧道,默认提供 SSH 和 AstrBot 两个预设,目标使用创建时的服务端口(默认 8022、6185)。已有账号、自建隧道及已删除的预设保留;修改目标服务端口后,请同步修改隧道配置。客户端和目标服务分别启停,可按需在连接设置中开启局域网后台访问。 后台地址为 `http://127.0.0.1:9200`,默认只监听本机。在 cpolar 页开启“局域网访问”后,同一网络的设备可通过显示的 `http://手机IP:9200` 访问官方后台并登录;连接 Wi-Fi 或开启热点后可复制地址。切换访问范围会重启正在运行的 cpolar,隧道短暂断开;账号和自建隧道保留,不会重建已删除的默认隧道。关闭后重新限制为本机访问。 内嵌页面默认 75% 缩放,可在右上角切换固定比例或打开外部浏览器。客户端状态和后台就绪状态分别检查;“后台已就绪”表示管理页可访问,隧道在线情况以官方后台为准。免费临时地址可能变化,域名、地区与带宽能力以 cpolar 账号套餐为准。请为需要开放的目标服务设置登录认证。 登录与隧道配置保存在应用私有目录的 `cpolar.yml`,WebUI 修改后继续使用同一份配置,不包含在 AstrBot 本机快照或便携备份中。日志隐藏已知令牌,支持实时跟随、暂停、复制和导出。运行环境维护时暂停并在维护结束后恢复。卸载扩展会清除客户端、配置与已保存的登录信息,保留 AstrBot 及 SSH 的数据。 ## Linux QQ 与内置桌面 在“设置 → 扩展组件 → Linux QQ”中管理独立原版 QQ。桌面、noVNC、中文字体、GCC、G++、make、Python 和 curl 等通用依赖随完整 APK 提供,首次初始化时离线准备,不再需要单独安装桌面。已有环境在首次使用时补齐缺失组件,保留现有文件;修复入口位于“QQ 设置 → 修复内置桌面”。依赖维护期间会暂时停止服务与终端,完成后恢复原服务,终端需手动重新打开。 桌面依赖在打包阶段预先安装、配置,全新初始化时释放预安装资源,检查软件包状态并准备通用兼容工具和本机访问凭据,避免逐包执行安装。已有环境不会覆盖预安装资源,缺失组件或修复时使用保留的原始离线包,保留较新版本及已有配置。修复页面显示当前阶段、软件包和已用时;各阶段计数独立,不代表整体百分比或预计剩余时间。完整包包含两类桌面资源,体积以对应版本附件为准。 主页面未安装时显示“安装 QQ”;安装后显示“打开 QQ”和“停止 QQ”。打开时自动启动桌面与 QQ,等待图形窗口就绪后进入;未登录时在 QQ 窗口自行扫码。退出页面继续运行,重复打开复用已有会话,停止 QQ 保留桌面。桌面本身不会因为完成初始化就自动常驻。 局域网访问只有一个入口,默认关闭。在“局域网访问 → 局域网设置”中允许访问并保存,桌面会自动准备,随后显示地址与访问密码。默认局域网端口为 `6082`,本机内嵌访问仍使用 `127.0.0.1:6081`,底层 VNC 仅监听本机;手机和远端浏览器显示同一个桌面与 QQ 会话。关闭局域网访问或修改端口只调整网页网关,不重启桌面或 QQ。远端连接需输入密码,仅在可信网络开启;密码离开页面后自动隐藏。 用户点击安装后从腾讯官网下载独立 Linux ARM64 QQ **3.2.34-53644**,地址、大小和 SHA-256 见 `app/src/main/assets/runtime/desktop/sources.json`。下载约 198 MiB,安装后约 640 MiB;下载阶段显示大小、进度、速度,支持暂停、继续和停止。点击打开 QQ 会准备桌面并进入同一个图形会话;登录数据独立保存在 `/manager/extensions/desktop/qq-home`。更新保留登录数据,失败时恢复旧程序。Linux QQ 与 AstrBot 可同时运行。 其他图形程序可在“QQ 设置 → 打开桌面”中仅准备桌面,无需安装或启动 QQ,再从同页复制终端图形环境配置并按目标程序官方教程手动操作。原版 QQ 程序位于 `/manager/extensions/desktop/qq/opt/QQ/qq`。还提供 `desktop-start`、`qq-desktop` 命令,手动启动的进程由所在终端管理。停止整个桌面会影响其上的 QQ 与托管程序,执行前会提示。第三方程序的原生注入、权限及消息接入兼容性需单独确认。 桌面安装时会同时编译独立的 glibc 兼容工具 `guest-compat`。`guest-compat 程序 参数…` 为该次运行提供匿名 ELF 动态库的文件加载兼容,以及 `/proc/locks` 无权读取时的实际 POSIX 锁记录查询。只查询本应用可访问的进程和内核锁,不把“打开了某个文件”伪装成持锁。工具不下载、修改或安装外部程序。 高级使用者可执行 `guest-compat configure --help`,配置自己提供的外部动态库、初始化函数、等待模块和启动延时。初始化函数需符合“无参数、返回 int”的 C ABI;默认没有额外动态库。从 1.5.1 起,App 的“打开 QQ”及终端的 `qq-desktop` 都会读取用户保存的兼容配置,并在 QQ 启动时加载所指定的库;没有配置则照常启动。其他终端程序仍需显式执行 `guest-compat --profile 程序 参数…` 才会读取这份配置。外部文件由使用者自行准备并遵守其许可。普通图形程序无需设置此配置。 保存配置后直接点击“打开 QQ”,不必单独执行兼容启动命令。若本应用管理的 QQ 已运行且配置发生变化,会先重启 QQ 再打开,保留桌面和登录数据;配置未变则复用现有会话。执行 `guest-compat clear-profile` 可删除配置,再次点击“打开 QQ”会恢复普通启动。配置命令本身不会关闭 QQ,也不会下载或安装外部组件。手动从终端启动的 QQ 仍由该终端管理,应先自行停止,避免重复启动;终端可用 `qq-desktop --no-profile` 临时绕过已保存配置,不删除它。 原版 QQ 启动时还会设置权限为 `0700` 的独立 `XDG_RUNTIME_DIR`,使其他程序可以从标准环境变量确定它的通信目录,避免 PRoot 用户编号与 procfs 中 Android 编号不同导致路径不一致。 桌面离线依赖的来源、版本和摘要见 `runtime/desktop-packages.lock.json`,完整 APK 会增加对应资产体积;独立 QQ 仍按需下载。“QQ 设置 → 卸载 QQ”只移除独立程序,保留登录数据、内置桌面与局域网设置。新建的本机快照会同时保存独立 QQ 的 `.config/QQ` 和 `.local/share/QQ`;便携导出时需勾选“QQ 会话”。QQ 程序、桌面访问密码及扩展设置不随便携备份迁移。 ## 内存与存储 首页的“本应用内存”按同一应用 UID 下可读取进程的 PSS 汇总,包含托管的服务进程;隔离的 WebView 渲染进程不在该统计内。“手机总内存”是设备物理内存,“应用占比”以它为分母。无法完整读取时会提示部分数据。 首次初始化或准备升级、修复环境时,若 App 可用空间低于保守预估,会显示实际可用量、建议预留量以及“仍然继续”按钮。这个估算只作提醒;环境已初始化后的日常启动不会再次按完整解包大小拦截。系统设置显示的剩余空间与 App 实际可写空间可能不同;空间耗尽仍会导致操作失败并影响手机使用,建议先清理存储。备份、恢复及更新中的其他空间检查仍按各自操作执行。 ## 日志、备份与恢复 服务日志默认跟随最新输出,可以暂停、选择复制和脱敏导出。点击“导出”可选择“直接分享”或“保存到文件”,无需先在文件管理器中查找。日志页的“清理”删除当前分类及其轮转归档,之后继续记录新日志。Linux QQ、cpolar 和 Harness 日志也提供清理入口。 排查问题优先使用“设置 → 日志与诊断 → 导出诊断包”,可直接分享 ZIP 或另存为文件。包内含手机厂商与型号、Android/API 与安全补丁版本、App/组件/WebView 版本、系统时区、内存与存储、电池优化和服务状态,以及各分类的有限大小脱敏日志;还会记录网页资源来源、最近一次环境检查和 Android 可提供的本应用进程退出记录。已在权限页检测过子进程上限时,附带本次 App 进程内最近的检测结果与时间,未检测或系统不支持的项目会明确标记,不猜测数值。导出不会停止服务、恢复未完成操作或主动申请 Shizuku 权限。 诊断包不附带业务配置、数据库、插件文件或 QQ 登录会话,终端只附带运行状态与退出码,不收集命令或输出。已识别的凭据会脱敏,但服务日志仍可能包含聊天内容或个人信息,发送前应核对。直接分享的临时文件保留在应用缓存中,后续导出会清理超过 24 小时的分享文件;长期留档请选择保存到文件。 “环境检查与修复”会分别检查基础运行文件、AstrBot 网页资源和 Python 依赖。AstrBot 更新后将网页放在数据目录是受支持的情况;网页版本未知或与核心不同会单独提示。整套内置环境修复只适用于匹配的组件组合,组件独立更新后会在暂停服务和解包前提示,不用旧内置组件覆盖新程序。 日常故障先运行“环境检查与修复”。检测到可处理的问题时,点击“自动修复可处理项”:补回可确认系统包版本的缺失基础文件;按 pip 的包版本和文件记录修复 Python 依赖;恢复与当前 AstrBot 核心匹配的网页。网页优先使用本机或 APK 内置资源,更新过的核心若缺少匹配资源,则从官方对应版本 Release 下载,保留现有核心版本。检查包括网页入口引用的本地脚本和样式文件,避免入口存在但缺少资源时误报正常。 修复先准备资源,再短暂停止服务与终端,备份被替换文件并逐项验证;不同版本的包、额外安装的软件、配置、数据库和会话保持不变。验证失败会撤回本次文件替换,未完成的修复在下次进入时恢复;终端需手动重开,服务按原运行状态恢复。已安装其他版本、无法确认的依赖不自动降级;系统直接终止进程等无法通过补文件解决的问题仍需诊断。修复可处理部分后会重新检查并列出剩余异常,提供“分享诊断”。 若旧操作提示“暂不能整套修复环境”,表示整套替换被拦截,不代表现有服务一定损坏,也不影响按项目修复。弹窗会列出已知版本差异;版本号相同但程序文件或依赖记录不同的情况,可展开“检测详情”查看对应文件与摘要。版本无法识别时会明确标注,不推断为用户自行更新。诊断保留本次失败操作、发生阶段、问题编号及差异项。 Ubuntu 服务和新开的终端继承手机的系统时区,插件直接调用 `datetime.now()` 时使用该时区。更新 App 或更改手机时区后,重新启动相关服务、重新打开终端;插件自己指定的时区仍以其配置为准。 “设置 → 日志与诊断 → 清理日志”可清理管理器各分类日志及识别出的服务历史日志。正在写入、近期使用或无法安全确认的上游日志保留,不删除配置、数据库、QQ 会话和备份。管理器日志已有容量限制;手动清理可立即释放保留的历史记录。 本机快照保存 `persistent` 中的用户配置、数据库及会话,并包含已安装的独立 Linux QQ 数据目录,跳过运行锁和临时套接字。快照适合本机恢复与更新回退,仍要求环境兼容;便携 ZIP 用于跨手机导入。旧快照保持原有内容。自动快照默认最多 10 份、合计 2 GiB,可在设置中调整;手动和回退依赖的快照保留。 需要换手机时使用“便携备份 → 导出”。导出前选择内容,点击“直接分享”发送 **ZIP**,或选择“保存到文件”: - AstrBot 数据:模型与平台配置、插件、人设、数据库及聊天数据。 - QQ 会话:可选,包含已有的独立 Linux QQ 登录数据;迁移后仍可能需要重新扫码,不包含 QQ 程序。 文件内包含 `manifest.json`、所选内容的 `data/…` 文件及 `complete.json` 完成记录。程序、Ubuntu 镜像、Android 权限、管理器设置、cpolar、SSH 和 Harness 配置不随便携备份导出。导出会短暂停止服务,制作完成后恢复,再保存到你选择的位置或打开系统分享面板。备份包含配置、密钥及所选登录会话,只应分享给可信接收方。 在新手机先初始化环境,再选择“导入便携备份”,查看包含内容并确认恢复。**允许跨手机和组件版本导入**,同时兼容旧版不含 QQ 会话的 ZIP;不要求版本摘要相同,也不要求 ZIP 文件排列顺序一致。只替换已包含的内容,未选中的数据保留;导出时不存在的 QQ 会话目录会跳过,避免换机时清除另一份本地会话。恢复前创建本机恢复点,切换后检查数据库及原本运行的服务,失败时尝试回退。不同版本的软件或插件仍可能不兼容,QQ 登录跨设备后也可能需要重新扫码;独立 QQ 程序需另外安装。 仍检查文件内容是否完整、是否存在重复或越界路径,避免损坏备份覆盖现有数据。当前 ZIP 及单个文件上限为 2 GiB、解包数据合计 8 GiB,最多 50,000 项。备份可能包含 API Key、数据库及登录凭据,未经加密,请妥善保存。卸载应用或清除数据也会删除本机备份;需要保留的数据应先导出到应用外。 ## 更新 新版说明弹窗还可选择“使用外部浏览器下载”。外部浏览器下载的文件不经过 App 内的自动校验与安装前快照;使用内置“下载并安装”可保留完整流程。 “设置 → 关于 → 检查更新”用于管理器 APK,AstrBot 保留独立程序更新。管理器页面只需点击“检查管理器更新”:有新版时弹出版本说明,点击“下载并安装”后自动下载、校验,再创建一致性数据快照并打开系统安装器;仍需在系统界面确认安装。若尚未允许安装 APK,会引导前往系统设置,授权并返回后继续。当前没有适用新版时会明确提示已是最新版本。取消下载保留续传进度,取消安装后可再次检查并继续安装,无需重新下载。 进入 **设置 → 关于 → AstrBot 程序更新 → 检查 AstrBot 更新**,默认直接查询其 **官方 GitHub 最新稳定 Release**,无需等待本项目更新目录。有新版时查看版本说明并点击“下载并更新”,自动下载、检查文件、备份、安装和恢复原启停状态;没有新版时明确提示。上游不可访问和没有新版分别提示。检查和下载阶段不停止服务,安装阶段会暂停服务与终端;终端中的手动命令需要重新执行。稳定版本同时根据 Release 标记及版本标签判断;上游误把 alpha/beta 标为正式版时,会继续查找近期正式版本。 AstrBot 同时获取对应提交的源码与同版 Dashboard,安装前检查现有 Python 依赖和可观察的数据迁移实现;不自动修改 Python 环境。新增依赖不满足时会在替换前停止并提示更新运行环境。迁移实现发生未适配变化时同样保留当前程序,等待管理器适配。上游新版不保证与现有插件或依赖兼容,启动验证失败时恢复原程序和数据。 在同页的“更新通道”可选择包含 Alpha、Beta、RC 的官方预发布版本,默认仍为稳定版。预发布版本可能迁移数据库或改变插件接口,请先备份。切回稳定通道不会自动降级已安装的预发布版;需要恢复时使用“回退 AstrBot”,同步恢复对应的数据快照。 “导入更新包”支持**完全离线导入**:选择同版本的 **Source code (zip)** 与 **Dashboard ZIP**,可以分两次添加,也可以一次选两份。如果 ZIP 已包含主程序与同版网页资源,也可单选。App 按包内版本识别,先展示已选文件,并提示还差哪一份。关闭窗口后可回来继续,也可清除已选文件。不联网查询 Release、比较官方内容或下载缺失文件。文件齐全且通过格式与运行兼容性检查后,可直接在窗口中点击“备份并安装”,稍后也可从“查看待安装更新”继续。显式导入 Alpha/Beta 不会开启预发布自动检查。 原有包含 `manifest.json`、`manifest.sig` 和 `program.tar.bin` 的签名维护 ZIP 仍可离线导入,无需解压。官方 4.30.0-alpha.1、4.30.0-beta.1 的适配维护包要求管理器版本代码至少为 `10052`;1.5.0 无法通过重新签名获得新的迁移适配,需先更新管理器。更新说明支持 Markdown 标题、列表、链接与代码块。 “应用与组件版本”中的“组件版本匹配”表示安装的组件版本与配套记录一致。它用于检查版本组合,QQ 官方机器人和微信官方 ClawBot 的绑定及连接状态在首页查看。 管理器 APK 继续使用本项目 GitHub 签名通道;组件默认使用各自的官方 Release,定制构建仍可指定原有签名目录。管理器没有适用新版时会如实提示;已下载的新版本可在再次检查后继续安装。发布者接入方式见[更新与分发](更新与分发.md)。 ## 旧版本升级 1.5.0 移除 NapCat 与 SnowLuma 的内置程序、专用部署教程和运行入口。近期上游公开源码及原下载渠道发生变化,为明确第三方授权与分发边界、减少维护不确定性,本项目不再提供这两个组件的专用集成。背景和截至日期见 [README 的调整说明](../README.md#关于-napcat-与-snowluma)。历史 Release 的介绍仅适用于对应版本。 1.5.0 专注 AstrBot、QQ 官方机器人与微信官方 ClawBot。升级停用旧版内置消息客户端及其专用入口,新环境不再安装它们。已有 AstrBot 数据、账号资料、独立 Linux QQ 和用户手动安装的软件保留。旧备份仍可导入数据,不会恢复旧程序或旧版专用启停功能。 Ubuntu 终端、桌面、通用动态库兼容工具和共享目录继续可用。终端中自行安装的 Linux 程序遵循各自许可,运行和维护由用户自行管理。 忘记 AstrBot 后台密码时,在服务详情的“凭据”页重置,App 会生成随机密码并撤销旧登录会话,仅恢复 AstrBot 原运行状态,保留模型、插件、聊天及平台配置。首次使用新密码登录后仍需改密。