rddmwmddr/android-ad-cleaner · 上手攻略

  • 仓库：rddmwmddr/android-ad-cleaner
  • 链接：https://github.com/rddmwmddr/android-ad-cleaner
  • 分类：agent（工具型 / Android 系统设置自动化）
  • 作者：spark
  • 更新：2026-10-30

是什么

rddmwmddr/android-ad-cleaner 是一套用来"关掉国产安卓手机系统里的广告、热搜、资讯推荐和营销推送"的自动化方案。它的核心不是一个手机 App，而是一套跑在电脑上的脚本引擎：通过 adb 连上你的安卓手机，用 uiautomator2 读屏、找入口、拨开关，把厂商在系统设置里埋的那些广告开关一个个关掉。

项目自我定位是"不 root、不解锁、不刷机"，且只操作"系统和 App 自带的公开开关"——它不卸载、不停用系统应用（明确不用 pm uninstall 和 pm disable-user）、不改 system 分区、不装模块。挂起广告包（pm suspend）这一步会要求机主点头，并且可以用一条命令还原。

仓库当前版本为 v0.2.7（2026-10-29），MIT 许可，最近一次提交也在 2026-10-29，属于活跃维护中的项目。仓库同时提供 Python CLI（tool/run.py）和一条命令的桌面客户端（Mac / Windows 图形界面）。

解决什么问题

国产安卓系统（ColorOS / HyperOS / OriginOS / MagicOS / EMUI）的广告不是一处开关能关完的，它们散落在七八个层级：

类别 例子 处理方式
系统广告 个性化广告、广告跟踪（OAID）、智能推荐服务 系统设置里的开关
热搜和资讯 下拉搜索的热榜、负一屏资讯、浏览器信息流 各 App 设置里的开关，浏览器切简洁首页
推广位 商店轮播、开屏、悬浮活动、签到福利 商店「服务管理」里的开关
营销推送 各 App 的「内容与营销」「活动优惠」通知 按渠道（channel）逐个关
广告组件 com.opos.ads、com.miui.systemAdSolution 等 pm suspend 挂起（需机主同意，可还原）
快应用 广告一点就跳进去的"免安装小程序" quickapp off 关闭

痛点在于：这些开关的名字和层级随品牌和系统小版本变化。同一句"个性化广告"，在小米和 vivo 的路径完全不同；系统一升级，菜单名就改。所以项目采用"机型脚本"这个抽象——每台机型一份脚本，记着"打开哪个 App、点哪几个字进设置页、关哪几个开关、留哪几个"，电脑照着它在手机上点。

项目还额外解决了两个工程问题：一是把"关营销通知"从 App 级总开关细化到渠道级（同一个 App 的订单、快递、更新通知可以保留，只关"内容与营销"）；二是把整个流程做成 AI 智能体可执行——仓库根目录带一份 AGENTS.md 规范，让 Claude Code / Codex / Trae / Cursor 这类能跑命令的工具按标准流程代办。

快速安装

路径 A：桌面客户端（最省事，不需要 Python）

从 Releases 下载 v0.2.7：

  • Mac Apple 芯片（M1+）：AndroidAdCleaner-0.2.7-mac-arm64.dmg，已签名并通过苹果公证，双击即开
  • Mac Intel 芯片（macOS 11+）：AndroidAdCleaner-0.2.7-mac-intel.dmg
  • Windows 10/11 安装版：AndroidAdCleaner-0.2.7-windows-setup.exe（Windows SmartScreen 提示时选「更多信息」→「仍要运行」）
  • Windows 10/11 免安装版：AndroidAdCleaner-0.2.7-windows-portable.zip

路径 B：Python CLI（要接 AI 智能体走这条）

# 装 adb
brew install android-platform-tools      # macOS
# sudo apt install adb                   # Linux
# Windows：下载 platform-tools 解压到 C:\platform-tools 并加进 PATH

adb version                              # 确认能出版本号

git clone https://github.com/rddmwmddr/android-ad-cleaner
cd android-ad-cleaner
pip3 install -r requirements.txt         # Python 3.9+

手机端准备（三条路径都要）：设置 → 关于手机 → 连点版本号进开发者模式 → 打开「USB 调试」。仓库 docs/00-打开开发者模式.md 有五个品牌的带截图教程。

不想插线可用无线调试（手机与电脑同一 Wi-Fi）：

adb pair 192.168.31.100:37xxx      # 配对端口：弹窗里的地址
# 输入 6 位配对码
adb connect 192.168.31.100:41xxx   # 连接端口：无线调试页面上方显示的地址

配对端口和连接端口是两个不同的数字；配对只做一次，但每次打开无线调试连接端口都会变。

核心用法

一、桌面客户端五步

  1. 连接手机——插线即认出，内置开启 USB 调试的图文教程
  2. 检测——型号、系统版本、机型脚本、快应用、广告组件
  3. 选择要关的——营销通知按渠道勾选，服务类默认不勾
  4. 执行——进度条和实时日志，可随时暂停
  5. 完成——每一步的结果，最后提醒关闭开发者模式

二、Python CLI 命令清单

# 看连上了哪些设备
python3 tool/run.py devices
# 输出示例：7f386895   OPPO Find N3 典藏版   PHN110   PHN110_16.0.5.1201(CN01)   机型脚本：无

python3 tool/run.py -s <序列号> check        # 只读检查，不改任何东西
python3 tool/run.py -s <序列号> backup       # 改动前快照
python3 tool/run.py -s <序列号> recipe       # 跑该机型的脚本
python3 tool/run.py -s <序列号> chan-scan    # 列出营销通知渠道
python3 tool/run.py -s <序列号> chan-off backups/<型号>-<时间>/channels.tsv
python3 tool/run.py -s <序列号> quickapp     # 检测快应用
python3 tool/run.py -s <序列号> quickapp off # 关闭快应用
python3 tool/run.py -s <序列号> finish       # 收尾，提醒关闭开发者模式
python3 tool/run.py -s <序列号> dev-off --yes # 从电脑关闭开发者模式（执行后连接断开）

不带 -s <序列号> 即默认对唯一连接的设备操作；多设备时必须显式指定。

三、让 AI 智能体代跑

把下面这段原样发给能执行命令的 AI（Claude Code / Codex / Trae / Cursor / WorkBuddy 桌面版）：

请克隆 https://github.com/rddmwmddr/android-ad-cleaner ，读仓库里的 AGENTS.md，
然后帮我给连着电脑的这台手机去广告。每一步改之前告诉我要改什么。

AI 会依次：克隆仓库读 AGENTS.md → 检查并补装 adb 和 Python → 跑 run.py devices 报告认到哪台机 → 存改动前快照 → 跑机型脚本或照清单一页页关 → 列出营销通知渠道给你确认 → 检测快应用并征求挂起同意 → 收尾汇报 → 提醒关闭开发者模式。

跑的过程中手机要保持亮屏、解锁、插着线，不要动手机（脚本正在点屏幕，你一碰坐标就乱）。有机型脚本的机型全程 4–6 分钟。

四、只有手机、没有电脑

走 docs/03-用聊天AI.md：用 DeepSeek / 豆包 / ChatGPT 网页版配合 prompts/ 里的提示词，照着 docs/清单/ 下各品牌的手动清单自己点。清单里还标注了每个品牌要关多少个渠道。

五、还原

见 docs/05-还原.md：挂起的包和通知渠道各一条命令即可回滚；App 内的开关按清单路径手动打开。

典型适用场景

  • 换新机或系统大版本更新后，厂商重新打开了一批默认开关，想一次性恢复干净状态
  • 家里长辈/孩子的手机广告满天飞，由子女代为设置
  • REDMI / ColorOS / OriginOS 老机型性能吃紧，砍掉营销推送和商店推广位后后台负载下降明显
  • 不接受 root、不接受刷机、不接受装 Xposed 模块的用户——这是它最大的差异化
  • 想批量沉淀机型脚本的贡献者：docs/04-给新机型写脚本.md 有一份写脚本的规范，脚本放在 recipes/<品牌>-<型号>/recipe.py，可提 PR

坑与注意

  1. 机型脚本不是 100% 覆盖。README 里的实测表自己列了 ❌ 和 ⚠️：OPPO Find X9 Ultra、Find N3 典藏版是「❌ 页面和 N6 不同，待补」；荣耀 WKL-AN20 是「路径逐项实测，新脚本整轮待复测」；小米 K70 是「9 段专用脚本，目标 20 项」。"同品牌参考脚本"不等于"专用适配"——不要因为你是 OPPO 就默认 Find X8s 的脚本能套到你机器上。找不到入口的步骤会跳过，不会乱点，但对应的广告也就没关掉。
  2. 系统小版本一变，设置页名字和层级也会变。脚本按"型号 + 系统版本"存放，版本对不上时引擎会提示。你的 ColorOS 16.0.10 和 16.0.5 是两套路径。
  3. 必须全程守着手机：亮屏、解锁、不碰屏。锁屏会让脚本直接中断（v0.2.7 加了提示音提醒解锁）。
  4. 折叠屏要合上用外屏操作。展开后系统设置和 App 是左右分栏、底部还有任务栏，引擎会找错位置（docs/01-准备工作.md 明确写了这一条）。
  5. 必须先备份。仓库提供 backup 快照，但快照本身也有坑：小米 15 / HyperOS 4 上 pm list packages 会返回 0 字节却 exit 0（v0.2.7 已加 cmd package list packages 回退），且失败时不留半成品快照目录。跑之前手动确认 backups/ 下真有文件。
  6. 只能充电的线连不上。认不到手机先别怀疑脚本，换根能传数据的线。
  7. "拨了 N 个"这个数字曾经虚高。v0.2.7 把它改成"实际处理成功的项数"——但老版本（≤0.2.6）仍然会把没确认、点不动的项算进去。如果你用旧版，看到"拨了 99 个"别当真。旧版不会自动更新，请重新下载。
  8. 外部 adb server 会打架。如果电脑上有别的工具（Iriun Webcam 等）先起了 adb server，客户端连的是 127.0.0.1:5037，对方退出后你的连接会彻底消失。CHANGELOG 的"未发布"段正在修这个问题（会明确报"adb 连接断开"而不是误报"没装 xxx"），当前版本可能报"本机没有安装 xxx"。
  9. 误点开关的说明文字会变成拨开关。v0.2.6 出现过 tap 隐私 命中"不涉及隐私数据"这类说明文字、直接把功能关掉的事故（issue #247）。v0.2.7 改为"包含匹配时跳过开关所在行的文字"，但如果你用旧版仍有风险。
  10. v0.2.7 才有的新功能：营销通知清单显示软件名（用手机上 3 KB 的 dex 读名，跟随系统语言，用完删除）、执行中可暂停、执行结束/暂停生效/需要解锁时的提示音、新版本提示（只带客户端版本号请求）、adb 下载自动换腾讯云镜像（固定 platform-tools 37.0.1，核对 SHA-256）。
  11. 原生鸿蒙不支持。README 明确：仅支持通过 adb 连接的安卓设备，暂不支持使用 HDC 的原生鸿蒙。
  12. 不要在手机解锁状态下跑账号相关页面。项目声明不截账号页和手机号页，不替你同意任何 App 的用户协议——遇到协议页要自己点「取消」或「以后再说」。
  13. 法律责任自负。项目只调用系统和厂商 App 公开提供的设置项，但厂商界面随系统更新变化，结果以你的手机为准。

与同类对比

方案 是否 root 覆盖范围 可还原 适合谁
本项目 否 系统广告 + 渠道级推送 + 推广位 + 快应用 + 广告包 是，一条命令 想全自动且不愿 root 的用户
手动逐项关 否 同上，但极耗时（27 个渠道要十几分钟） 天然可逆 愿意自己掌握每一步的人
Xposed / LSPosed 模块 是 更彻底，可拦截更多层 需重启或恢复镜像 愿意折腾、愿意 root 的人
Root 方案（PM 模块等） 是 最彻底 需刷机或重刷 高阶玩家
厂商"纯净模式" 否 很有限，且各品牌叫法不一 — 不想折腾的人

同类项目里做"去广告"的不少，但大多要 root。本项目的差异点在于不 root + 渠道级精细控制 + 可还原 + 支持 AI 智能体一键执行。代价是它高度依赖机型脚本的覆盖度，而覆盖度是逐机型、逐系统版本人工补的，这是它目前最大的短板。

一句话推荐结论

如果你用的是国产安卓（小米 / OPPO / vivo / 一加 / 荣耀 / 华为）并且不想 root，这是目前少见的、能把系统广告、热搜、资讯推荐和营销推送一次性清干净还能一键还原的方案，值得试；但动手前务必先看 README 实测表里你那个型号的 ✅/⚠️/❌ 标记，对号入座再决定。

⚠️ 核验说明：本文基于 2026-10-30 抓取的仓库 README、docs/01-准备工作.md、docs/02-用AI智能体.md 与 CHANGELOG.md（含"未发布"段）。版本号 v0.2.7 与发布日期 2026-10-29 来自 README 首段；platform-tools 37.0.1 与 SHA-256 校验来自 CHANGELOG v0.2.7 新功能节。CHANGELOG"未发布"段中若干修复（如外部 adb server 断连识别）尚未落到已发布版本，本文已在对应坑位注明。