Botagent

Name: phone-botagent
Author: Yehua-1145

把 QQ AI 机器人装进一台普通安卓手机。

不用 root，不用服务器，不用买云主机。电脑插上数据线点一下就能装完，装完手机上还有一个自己的控制台。

QQ 消息 → NapCat（QQ 协议端）→ 你的大模型 → 回复

📥 下载

方式	地址	说明
蓝奏云（国内推荐）	https://wwbxc.lanzoub.com/b011mly7ud	密码：byc6
GitHub Release	https://github.com/Yehua-1145/-QQbot-/releases/latest	需要魔法

下载后解压，进 Windows一键部署 目录，双击 BotagentDeploy.exe 即可。

Botagent-v1.1.zip          18.53 MB
SHA256  6B14CF1554B9AB77D875C18B292BA5E6BB7E3E02F7B821F1667DF555EA8DE411

两条路，选一条

	稳定版 v1.1（main）	实验版（手机直装） v2（分支 `v2-embedded-runtime`）
装法	电脑一键部署 / 手机直装（Termux）	只装一个 APK
需要 Termux	要	不要（Python 运行时打进 APK 里）
安装步骤	四步	填 QQ 号 + API Key → 点启动
体积	18 MB	34 MB
状态	✅ 稳定，已验证	🧪 真机能跑，还在打磨
适合	想稳定用的	想尝鲜、手机独立部署

v2 的代码在分支 v2-embedded-runtime，
单 APK 自带 Python 3.14 运行时，手机上一键启动，不需要 Termux、不需要电脑。
已在小米 6（无 root）上验证：装 APK → 填两个空 → 点启动 → 控制台跑在 8080。

30 秒了解它

一台吃灰的安卓手机  +  一根数据线  +  一个 QQ 小号
        ↓  电脑上点一下（约 5 分钟）
QQ 里出现一个会查电量、会截图、会发图、会按点自己干活的 AI

你会得到	不需要
QQ 里的 AI 助手（能执行命令、装应用、截图）	❌ 服务器 / 云主机
手机上的控制台（对话、状态、模型、自动任务）	❌ root（想让它操作界面才需要）
24 小时自动换图的图库	❌ 公网 IP / 域名
定时任务（每天几点让它自己干活）	❌ 花钱买服务

三步装好

① 手机开「开发者选项 → USB 调试」，插上数据线
② 电脑双击 BotagentDeploy.exe，填 QQ 号和 API Key
③ 点「开始部署」，等它自己跑完（约 5 分钟），手机扫码登录

装完手机上多一个 Botagent 图标，那就是控制台。

详细的图文步骤在安装一节；卡住了看常见问题。

关于功能边界：聊天机器人 vs 完整 Agent

这一点必须说在前面。

能力	无 root	有 root
QQ 聊天、扫码登录	✅	✅
发图（本地图库 / 联网搜图）	✅	✅
人设、多服务商、控制台	✅	✅
执行命令 / 读写任意文件	❌	✅
截屏 / 点按 / 全局操作手机	❌	✅
静默安装应用、发短信、调音量	❌	✅
给 QQ 里的自己装东西、改配置	❌	✅

也就是说：

没有 root：它是一个会聊天、会发图的 QQ 机器人，控制台能看到状态、换模型、改人设
有 root：它才成为真正的 Agent —— 能听懂「帮我截个图」「装个 App」「看一下电量」「把这张图发我」，并真的去执行

部署工具会自动检测 root：

检测到 root → 走全自动路径，装完即完整 Agent
没有 root → 仍然能装好并运行，但上面的工具能力会不可用（部署日志里会说明）

想用完整功能，请在一台可以 root 的手机上部署（本项目在小米 6 / LineageOS 18.1 + Magisk 上验证）。

它是什么

三块东西：

部件	跑在哪	干什么
Botagent 服务	手机 Termux	收发 QQ、调大模型、跑工具、管理图库
Botagent 控制台	手机 App	聊天、看状态、改模型、重启服务、编辑人设
一键部署工具	Windows	插线自动装完上面两样

特性

对话

支持私聊、群聊（@ 触发）、关注账号自动接话
流式输出：边生成边发，不用等整段说完
多服务商：DeepSeek / OpenAI / 通义千问 / 本地 Ollama / 任何 OpenAI 兼容接口
上下文记忆 + 长期记忆，会记住你说过的事
人设可改：写一段话换性格，下一句生效，不用重启

工具能力（需 root）

网页搜索、图片搜索
发图片、发文件、打包发送
读屏/点按/截图（需授权）
执行命令、读写文件（仅主人）
定时抓图填图库

手机控制台

五个页签，装在手机上点开就用：

页签	功能
对话	直接在手机上跟它聊，和 QQ 里是同一套能力
状态	QQ 在线状态、端口、图库数量，2 秒实时刷新
模型	填 API Key、切换服务商
控制台	重启 Bot / 协议端、重新生成登录二维码、抓图、看日志
设置	三套主题、人设编辑、使用说明、意见反馈、更多设置

另外还有：

人设编辑：写它的名字、性格、说话方式
使用说明：首次打开自动弹出，之后随时可看
图库管理：抓图模式开关（含风险确认）、每日自动换新、配置备份/恢复
意见反馈：App 内直接提交

电脑一键部署

插线 → 填 QQ 号 → 点「开始部署」

自动完成：

检测设备、判断是否有 root
手机没装 Termux → 自动下载并安装
配置存储权限、后台运行、电池优化白名单、开机自启
推送程序 + 配置，生成访问 token
启动服务，等端口就绪
装上手机控制台 App 并打开

有 root 全自动，没 root 也能全自动（通过 adb 驱动 Termux 完成输入）。

还带 一键卸载：可选保留配置，可选连 Linux 容器一起删。

不用 root 也能操作手机（无障碍通道）

以前"让 AI 点屏幕"必须 root。现在装了 Botagent App 并开启无障碍服务后，不 root 也能：

读当前界面（文字 + 坐标）   a11y_dump
按文字点按                  a11y_tap
填字 / 滑动 / 返回桌面       a11y_type / a11y_swipe / a11y_key
按包名打开 App              a11y_launch
截屏（Android 11+）         a11y_shot

开启方式两种：

① 部署时自动开（部署器用 adb 直接写系统设置，不需要 root）
② 手动：手机设置 → 无障碍 → 已下载的服务 → Botagent → 打开

App 里也能开：设置 → 让 AI 操作手机（无需 root）→ 打开无障碍设置，状态会显示是否已开。

和 root 的差别

	有 root	无 root（无障碍）
读界面 / 点按 / 输入 / 滑动	✅	✅
截图	✅	✅（Android 11+）
打开 App / 返回桌面	✅	✅
执行 shell 命令	✅	❌
静默装应用	✅	❌（只能弹安装器）
读写任意文件	✅	❌（限共享存储）

一句话：日常"操作手机"够用，重活（shell、静默装包）还得 root。

注意：重装 App 后系统会把无障碍关掉并标记为崩溃，需要重新开一次（
部署器会自动处理：先清空再写入，然后校验）。

架构

┌─────────────────────── 手机 ───────────────────────┐
│                                                    │
│  Botagent.apk（控制台外壳：一个 WebView）           │
│         │ http://127.0.0.1:8080/app                │
│         ▼                                          │
│  webui.py —— 网页控制台 + HTTP 接口                │
│  qq_bot.py —— QQ 收发、权限判断、发图               │
│  agent.py —— 大模型调用（流式）、工具执行           │
│  prefetch.py —— 定时抓图、图库维护                  │
│         │                                          │
│  Termux ─┤                                         │
│          └─ proot Ubuntu ─ Linux QQ ─ NapCat       │
│                              OneBot v11 :3001      │
└────────────────────────────────────────────────────┘

安装

方式 A：电脑一键部署（推荐）

手机打开「开发者选项 → USB 调试」，插线，屏幕上点「允许」
解压发布包，进入 Windows一键部署 目录
双击 BotagentDeploy.exe
选服务商、填 API Key（可以留空，装好后在控制台填）、填你的 QQ 号
点「开始部署」

装完会自动打开控制台。

方式 B：手机手动部署

前提：手机已装 Termux（官方版，不要用应用商店版）。

# 1. 把 aibot 目录拷到手机
# 2. 在 Termux 里
pkg install -y python curl proot-distro
cd ~/aibot && bash install.sh

怎么跟它说话

场景	条件
私聊	发送者在白名单里（默认只有主人）
群聊	群在白名单里，且必须 @ 机器人
关注账号	在指定群里，被标记的人说话会自动接（有冷却）
夜间免打扰	默认 03:00–07:00 仅主人可用

不在名单里的人：私聊不回，群里 @ 也不回。

怎么让它发图

消息里带上这些词会触发找图：

来张图  来点图  发图  搜图  图片  一张图  插画  图集

例子：

@机器人 来张 cos 图
@机器人 帮我搜 二次元 插画

优先使用手机本地图库，没有再联网找
非主人有冷却时间，主人不受限
图库可设为每天自动换新（删最旧的、抓新的）

权限

主人全权，其它一律访客。

能力	主人	访客
聊天	✅	✅
发图	不限	有冷却
安全图源	✅	✅
扩展图源（默认关闭）	需授权	需授权
执行命令 / 装应用 / 截图	✅	❌
看错误详情	✅	❌（显示友好提示）
改配置 / 看日志	✅	❌
夜间使用	✅	❌

主人在 QQ 里可以管理授权：

看权限                 查看当前名单
给 123456 权限          授权
收回 123456            收回

授权写入 aibot/perms.json，立即生效，不用重启。

配置

程序读取 aibot/config.json，主要字段：

{
  "api_key": "sk-...",              // 大模型 Key（也可在控制台填）
  "base_url": "https://api.deepseek.com",
  "model": "deepseek-chat",

  "owner_uid": 1000001,             // 主人 QQ
  "bot_uin": 1000002,               // 机器人 QQ

  "allowed_groups": [],             // 允许的群
  "safe_groups": [],                // 这些群只发安全内容
  "allowed_private_uids": [],       // 私聊白名单（空=只有主人）

  "persona": "",                    // 人设（也可在控制台写）
  "quiet_start": 3,                 // 夜间免打扰
  "quiet_end": 7,

  "rotate_enabled": true,           // 图库每日自动换新
  "rotate_hours": 24,
  "rotate_count": 40,

  "allow_remote": false             // 控制台是否允许局域网访问
}

改完不用重装：控制台点「重载配置」即可。

目录结构

aibot/
  agent.py        模型调用、工具执行、人设
  qq_bot.py       QQ 收发、权限、发图
  webui.py        网页控制台 + HTTP 接口
  prefetch.py     抓图与图库维护
  config.py       配置读写
  console.py      终端控制台（调试用）
  install.sh      安装脚本
  uninstall.sh    卸载脚本
  assets/         开屏图、头像

配置要求

手机

项	最低	推荐	说明
系统	Android 7.0	Android 10+	实测环境 LineageOS 18.1（Android 11）
架构	arm64-v8a	arm64-v8a	Linux QQ 只提供 arm64 包，32 位手机装不了
内存	3 GB	4~6 GB	常驻约 600~900 MB（QQ + 协议端 + Python）
可用存储	3 GB	5 GB	容器 ~1.5 GB + 图库 + 附件缓存，详见下表
CPU	骁龙 660 级	骁龙 835 级	实测小米 6 流畅
root	不强制	Magisk	完整 Agent 能力需要 root，详见上一节

存储占用参考：

proot Ubuntu 根文件系统     约 500 MB
Linux QQ + 运行库           约 700 MB
NapCat / Python 依赖        约 300 MB
图库（默认上限）            约 400 MB
日志与缓存                  约 100 MB
------------------------------------
合计                        约 2 GB（首次部署会下载约 2 GB）

网络

场景	要求
部署阶段	需要能访问 GitHub（下载 Termux）和 apt/pip 源，下载约 2 GB
运行阶段	需要能访问你选的大模型接口
图库抓图	需要能访问对应图源，部分站点可能需要代理

国内网络建议先开代理，或者用部署工具里内置的重试（它会自动换源）。

QQ 账号

建议用小号：非官方协议端有封号风险，别用主号
需要能扫码登录（手机 QQ 扫一扫）
部分账号会触发短信验证，需要人工完成一次

电脑（仅一键部署需要）

项	要求
系统	Windows 10 / 11（64 位）
数据线	支持数据传输（有些线只能充电）
驱动	多数情况免驱，异常见下方「驱动与连接」
其它	`adb.exe` 已内置在发布包里，不用自己装

macOS / Linux 用户可以用「手机端手动部署」方式，不需要电脑端工具。

驱动与连接

原理：部署走的是 adb（Android Debug Bridge） 通道，不依赖手机助手，也不需要安装手机厂商的全家桶。

正常情况：

Windows 10 / 11 自带 WinUSB 通用驱动，插上并在手机上点「允许 USB 调试」后即可识别
设备管理器里应出现 Android Device → Android ADB Interface（或类似名称），且无黄色感叹号

判定是否连接成功：打开命令提示符，执行

adb devices

输出	含义	处理
`<序列号> device`	✅ 正常	可以开始部署
`<序列号> unauthorized`	手机未授权	看手机屏幕，点「允许」，勾选「一律允许」
`<序列号> offline`	连接异常	拔插数据线，或 `adb kill-server` 后重试
列表为空	未识别	见下方排查
`adb: command not found`	没找到 adb	用发布包内置的 `adb.exe`，不要用其它版本

识别不到时的排查顺序：

换线：部分数据线只有充电针脚，必须用支持数据传输的线
换口：优先插主板后置 USB 口，避开前置面板和 USB Hub
看设备管理器：出现「未知设备 / Android」带黄色感叹号 → 装厂商 USB 驱动
- 小米：Mi USB Driver 或小米助手（装完可卸载，驱动会保留）
- 高通平台通用：Google USB Driver 也可尝试
关掉会抢占 adb 的软件：豌豆荚、手机助手、360 手机卫士、各类刷机工具会同时占用 adb 服务，表现为 offline 或列表为空。退出这些程序（必要时结束进程）后重试
换一条 USB 2.0 口：个别 USB 3.0 控制器与老机型兼容性差

无线调试（可选，Android 11+）：

不想用数据线可以走无线，但需要先用一次命令行：

:: 手机：开发者选项 → 无线调试 → 使用配对码配对
adb pair 192.0.2.10:配对端口
adb connect 192.0.2.10:调试端口
adb devices

连接成功后再运行部署工具，它会正常列出该设备。

注：无线调试对网络稳定性敏感，部署阶段建议还是用数据线，装完再拔。

常见问题

检测不到设备
换一根数据线（有些线只能充电），重新打开 USB 调试。

提示未授权
看手机屏幕，点「允许」，勾选「一律允许」。

小米 / MIUI 装不上
开发者选项里打开「USB 安装」和「USB 调试（安全设置）」。

无 root 自动化没成功
确认装了官方 Termux，并且首次初始化完成（出现 ~ $ 提示符）。

拉不出二维码
控制台点「重新生成二维码」。如果提示需要短信验证，去协议端后台完成验证。

消息不回
看控制台日志尾部，通常是 API Key 或网络问题。

滑动有条白边
用发布包内的最新 Botagent.apk，旧版 App 有这个问题。

免责声明

本项目是非官方第三方工具，与腾讯公司无隶属或合作关系。

使用非官方 QQ 协议端可能违反腾讯服务条款，存在账号被限制或封禁的风险
请使用小号测试，不要用主账号
聊天内容会发送给你自行配置的大模型服务商
部分图源需要遵守当地法律法规，仅限个人设备使用

完整条款见 DISCLAIMER.md。

成人图源的三层开关（2026-11-05 起）

成人向图源默认全局关闭，连主人也不开。要用必须同时满足：

层级	在哪控制	说明
① 总开关	控制台 → 设置 → 更多设置 → 深度抓图	关着时任何人都不能用（含主人），工具层直接拒绝
② 白名单	同一页的「深度抓图白名单」	只有名单里的 QQ 号 / 群号能用；留空 = 谁都不能用
③ 临时授权	主人私聊发「给 123456 r18 权限」	写入 `perms.json`，可随时收回

三者是与的关系：总开关关 → 白名单失效；总开关开但白名单没你 → 用不了。

查看当前状态：私聊发「看权限」，会返回总开关、白名单、临时授权三层信息。

// config.json
{
  "r18_prefetch": false,              // 总开关，默认 false
  "r18_allowed_uids": [],             // 白名单 QQ 号
  "r18_allowed_groups": []            // 白名单群号
}

关掉总开关时，模式会自动降回 normal，界面也不会再显示 R18。

让 AI 自己操作手机（有 root）

除了执行 shell，它还带一套界面自动化工具，能"看懂"界面再动手：

工具	作用
`ui_dump`	读出当前界面的文字控件和坐标（可筛选）
`ui_tap`	按文字点按钮，找不到会返回候选让你改口
`ui_type`	往输入框填字（可自动定位输入框）
`ui_swipe`	列表翻页 / 滑动
`ui_key`	返回、Home、删除等按键
`ui_wait`	等某个文字出现，确认上一步生效

工作方式是「看清再点」，不是瞎猜坐标：

ui_dump  →  看到「网络和互联网 @(360,1112)」
ui_tap   →  点它
ui_wait  →  等「互联网」出现，确认进去了

实测：让它"点进设置里的网络和互联网"，它会先 dump、再按文字点、再等待确认，
最后前台真的切到了 Settings$SubSettings。

边界（很重要）：

需要 root（无 root 拿不到 uiautomator）
依赖 App 暴露控件文字：原生界面好用；WebView / 游戏 / 图片界面读不到时，
自动回退到 OCR（tesseract + 中文包，离线，约 2~5 秒/屏）
OCR 文字会被拆出空格（「模型状态」），匹配前统一去空白再比
纯图标按钮用 icon_save + icon_tap：先 icon_save("back", x, y) 现场裁模板，
之后 icon_tap("back") 长期可用；匹配是边缘图 + 多尺度互相关，
同界面实测 0.72~0.98 命中、换界面 0.46 会被拒
用程序画的几何图标不可靠（真实截图上只有 0.5~0.66 分，会误点），必须用实拍裁剪
没有"看一眼截图就懂"的能力（当前文本模型看不了图），靠的是控件树的文字
涉及付款、删除、给别人发消息，提示词里要求它先问确认
访客拿不到这组工具，只有主人能用

已知限制与反馈

这个项目还不完善

先把话说清楚：它是一个个人项目，能跑通、够自己用，但离「成熟产品」还有距离。下面这些是已知的短板，遇到了不必意外。

兼容性

只在小米 6 / LineageOS 18.1（Android 11）+ Magisk 上完整验证过
其它机型、其它 ROM 可能遇到：proot 启动失败、后台被系统杀、adb 识别异常
32 位（armeabi）手机无法运行（Linux QQ 只提供 arm64 包）

能力边界

没有 root → 只能聊天和发图，没有工具能力（详见上文功能边界）
语音消息、表情包：暂未支持，后续版本计划加入（见下方「后续计划」）
视频消息、语音通话：暂无计划
群管理只做了基础功能（部分操作未实现）
单账号，不支持同时挂多个 QQ
记忆长度有限（上下文和长期记忆都有字数上限）
并发多人同时提问时会排队，响应会变慢

稳定性

依赖 NapCat + Linux QQ，上游一改登录机制就可能失效，需要等适配
二维码约 3 分钟过期，过期要手动重新生成
proot 容器长时间运行可能被系统回收，需要保活（部署时已配白名单，但不保证）
图库抓图依赖外部图源，图源挂掉时会抓不到
没有自动更新，升级需要手动重新部署或替换文件

体验

控制台是网页套壳，不是原生 App，动效和手感一般
界面文案只做了中文
首次部署要下载约 2 GB，网络差时很慢

后续计划（Roadmap）

已经排上日程、但当前版本还没有的能力：

计划	说明	状态
语音消息	收到语音能听懂、也能回语音	计划中
表情包	会发表情、能识别你发的表情	计划中
更多图源	提高抓图成功率，减少“什么都没有”的情况	计划中
插件机制	第三方插件 + 本人审查后才加载（哈希锁、权限声明、审查页）	规划中
自动更新	不用手动重新部署	待评估
原生界面	目前是网页套壳，手感一般	待评估
多账号	同时挂多个 QQ	远期

关于插件：不做「随便装」，而是「提交 → 我审代码 → 批准后才加载」。
批准时记录文件哈希，之后文件被改动就自动失效，需要重新审。
插件必须在清单里声明权限（联网 / 读写文件 / 执行命令 / 收发消息），审的时候一眼能看到。

说明：这些是计划，不是承诺。个人项目时间不确定，做出来会写进更新日志。
如果你特别需要其中某一项，可以开 Issue 说明场景，会优先考虑。

遇到问题怎么反馈

方式一：GitHub Issue（推荐，方便追踪）

👉 https://github.com/Yehua-1145/-QQbot-/issues

新建 Issue 时请带上：

1. 手机型号 + Android 版本 + ROM（如 小米6 / Android 11 / LineageOS 18.1）
2. 是否 root、用的哪种部署方式（一键部署 / 手动）
3. 复现步骤：我做了什么 → 期望什么 → 实际发生什么
4. 日志尾部：控制台 → 日志页签，复制最后 30 行左右
5. 截图（如果有界面问题）

方式二：软件内反馈（最快）

打开手机上的 Botagent App → 设置 → 反馈 → 写清楚问题 → 提交。

反馈会直接发到开发者那里，不用注册账号、不用开浏览器。

方式三：QQ 群里问

看仓库主页右侧的链接，或者直接开 Issue 问。

⚠️ 提交反馈前请注意

不要把下面这些东西贴进 Issue 或截图里：

API Key（sk- 开头）
控制台 token
QQ 号、群号
登录二维码
完整的 config.json

日志里如果出现这些，请自行打码——控制台日志已经做了自动脱敏（sk-***、token=***），但仍建议扫一眼再发。

关于 Bug 修复的预期

我能复现的问题会修；不能复现的，需要你提供足够信息
上游（NapCat / Linux QQ）导致的问题，我只能等或找替代方案
不保证响应时间，但有价值的 Issue 都会看

如果你自己动手改好了，欢迎直接提 PR。

许可

本项目原创代码采用 MIT License。

第三方组件：

组件	许可
NapCat	MIT
Termux / proot-distro	各自开源许可
Linux QQ	腾讯专有，本项目不重新分发

致谢

NapCat —— QQ 协议端
Termux / proot-distro —— Android 上的 Linux 环境
Linux QQ —— 腾讯官方客户端