CleanYourTV：让 Claude Code 通过 ADB 清掉安卓电视的广告
说明：我们手上没有安卓电视，没有实机跑过。下面每一步都按 Gathin23/cleanyourtv 仓库的 README、PROMPT.md、故障排查文档和 Issues 整理，内容以 2026-10-21 仓库 main 分支为准。项目更新很快，动手前请再对照一下原仓库。
它能做什么，适合谁
作者做这个项目的起因是：父母家的电视在打开 Netflix 之前，首页先推一条赞助广告。CleanYourTV 要解决的就是这类首页广告、推荐位和厂商预装。
它的做法是：电脑和电视连同一个 Wi-Fi，通过 ADB（安卓调试桥）连上电视，让 Claude Code 这类能跑终端命令的编程助手照着仓库里的 PROMPT.md 一步步操作：
- 先备份：保存已安装应用列表和相关设置。
- 停用厂商的遥测、广告服务、推荐内容和不需要的预装应用，用的是
pm disable-user。只停用，不卸载，所以能还原。 - 装一个简洁桌面（包名
com.gathin.tvhome，约 405 KB），设成默认主页：纯黑背景，底部一排常用应用，风格接近 Apple TV。
仓库原话是：不需要 root、不刷机、不用数据线、什么都不卸载，改主意了一行命令还原。 作者说，把这个仓库给助手当参考，整个过程大约 15 分钟。
适合：家里有安卓电视、Google TV 或电视盒子，被开机广告和推荐位烦到的人；也适合想看看「把真实设备交给 AI 编程助手操作」是什么样的人。
不适合：不想碰开发者选项、不想在电脑上开终端的人。整个过程要你在电视上点授权、回答几道选择题，不是一键完成。
截至 2026-10-21，仓库约 1.44 万 Star，README 写的是已记录 147 款电视、49 个品牌。
哪些电视能用，哪些不能
| 情况 | 说明 |
|---|---|
| ✅ Android TV / Google TV | 小米、TCL、海信、索尼、一加、realme、Nvidia Shield 等大多数机型都能用（PROMPT.md 原文列举）。仓库 examples/ 里按型号收了停用清单，TCL、索尼、小米最多。 |
| ⚠️ 新桌面有系统版本要求 | 桌面 APK 要求 Android 8.0（API 26）及以上。有些设备的清理清单在，但系统版本太低，桌面装不上。 |
| ❌ 三星（Tizen） | 不支持。仓库记录了一台 2021 款 Tizen 电视：局域网里没有 ADB，没法停用应用。 |
| ❌ LG（webOS） | 不支持本项目的安卓桌面。社区有 webOS 方向的衍生项目，登记在 SHOWCASE.md，不属于本项目本身。 |
| ❌ Fire TV | PROMPT.md 写明不适用于 Fire TV，Fire OS 也限制替换默认桌面。仓库里有几份 Fire TV 的停用清单，只能参考着手动处理。 |
| ⚠️ 部分国行电视 | 有的会拒绝安装任何外部 APK（报 INSTALL_FAILED_VERIFICATION_FAILURE），有的不允许第三方桌面当主页。这类电视只能做「停用广告」这一半，换桌面做不了。不能只凭品牌判断，要看具体型号。 |
| ⚠️ 运营商定制盒子 | 有的运营商固件把 USB 调试和无线调试开关都去掉或锁成灰色，这样就完全连不上，本项目无从下手。 |
不在清单里的型号也可以试：PROMPT.md 会让助手在你的真实设备上自己排查。动手前先在机型清单里搜一下自己的型号，看对应目录的说明。
安装：准备工作
电视上打开 USB 调试：进入「设置 → 设备偏好设置 → 关于」，在「版本号 / Build」上连按 7 次确定键，返回后进「开发者选项」，打开 USB 调试。如果还有「网络调试」或「ADB 调试」开关，也一起打开。菜单名称因机型而异。电视保持开机。
电脑和电视连同一个 Wi-Fi：助手要在局域网里找到电视，默认走 ADB 的 5555 端口。也可以在电视的网络设置里查到 IP，直接告诉助手。
电脑上准备工具：
- 编程助手：仓库推荐 Claude Code，也说 Codex、Gemini CLI 能用。按官方说明安装并登录即可。
- Python 3：仓库自带的
tools/tv.py是纯 Python 写的 ADB 客户端，系统自带的adb被拦住时可以用它。 - adb（可选）：电视只支持「无线调试」配对时，要用官方
adb执行adb pair一次。 - 编译桌面的环境：JDK 17、Android SDK Platform 34、Build Tools 34.0.0。macOS 可以用
brew install openjdk@17 android-commandlinetools，再运行sdkmanager "platforms;android-34" "build-tools;34.0.0"。Windows 装好 Android Studio 即可。
克隆仓库：
bashgit clone https://github.com/Gathin23/cleanyourtv.git cd cleanyourtv仓库不提供现成的 APK，桌面由安装脚本现场编译，作者说大约一分钟。
先看一眼电视的 USB 口
有些盒子（例如小米盒子 S）开着 USB 调试时会切断 USB 口的供电，插在上面的 USB 音箱或 U 盘会没反应。做完把 USB 调试关掉就好，新桌面不需要它。
使用：把 PROMPT.md 交给 Claude Code
- 在仓库目录里启动 Claude Code，把
PROMPT.md两条分隔线之间的那段英文提示词贴进去，把<MODEL NAME HERE>换成你的电视型号。 - 告诉它你已经克隆了仓库。
PROMPT.md特别提到：这样助手会直接复用tools/和launcher/，不用从头写，只需要改launcher/.../values/config.xml。 - 在电视上点「允许 USB 调试」：助手连接时，电视会弹出「Allow USB debugging?」，用遥控器点允许。
- 回答三四道选择题：你平时用哪些应用、底部放哪四个、要不要保留语音助手、Chromecast 投屏和系统更新。没勾的才会被停用。
- 跟着它检查：每改一步，助手会从电视截图回来确认。最后它会交给你还原脚本、编译安装脚本，以及一份说明（怎么重新启用某个应用、怎么换快捷栏顺序和壁纸）。
可以这样跟 Claude Code 说（下面是我们写的示例，正式提示词以 PROMPT.md 原文为准）：
我已经在当前目录克隆了 cleanyourtv 仓库，请复用 tools/ 和 launcher/。
按照 PROMPT.md 的流程处理我的电视，型号是：<你的电视型号>。
要求：
1. 改动之前先完整备份，并生成还原脚本，告诉我放在哪；
2. 每批只停用少量应用，每批之后截图确认；
3. 碰到流媒体应用、语音助手、投屏、系统更新，先列清单问我；
4. 做完帮我关闭网络 ADB，并用 tools/adb-closed.py 确认端口已关闭。PROMPT.md 里的几条硬规矩
这些写在提示词里，助手会照做。你也要知道，方便盯着它：
- 系统应用只停用，不卸载（
pm disable-user --user 0）。 - 这些不能停：负责播放 HDMI 和电视信号的应用、输入源菜单、遥控器和蓝牙配对、屏幕键盘、Google Play 商店和 Play 服务。
- 分小批停用，每批之后截图，否则出了问题不知道是哪一个导致的。
pm命令一次只执行一条，连在一起写可能执行完第一条就悄悄停了。- 名字里带 factory、production、fac menu 的工厂菜单包，一律不要打开，只看不开也不行（见下面踩坑部分）。
备份和一行还原
用 PROMPT.md 时
助手在改动前会把完整的应用列表、已停用列表、getprop 输出和全部设置保存到备份目录，并写好一个能重新启用所有被停用应用的还原脚本。备份目录和还原脚本的位置一定要让它告诉你，自己记下来。
手动用仓库脚本时
tools/disable.sh 停用之前会先记录：清单里每个应用原来是启用、已停用还是没安装，当时的默认主页，还有三项动画缩放设置。记录保存在电脑的 ~/.cleanyourtv/，每台电视、每份清单各一份；同一份清单重复运行不会覆盖最初的记录。注意它不会保存完整应用列表和全部系统设置，需要完整快照的话要另外先存。
一行还原（把 IP 和清单路径换成你实际用过的）：
# Android TV
TV_HOST=192.168.1.50 tools/restore.sh examples/<你的机型>/debloat.txt
# Google TV：最后加上原桌面的备用包名
TV_HOST=192.168.1.50 tools/restore.sh examples/<你的机型>/debloat.txt com.google.android.apps.tv.launcherx几点要知道：
- 有记录时，会把主页还给当初真正占着它的那个桌面；你自己原本就停用的应用，还原后仍是停用。
- 找不到记录时，脚本会提示你，然后把清单里的应用全部启用、动画缩放恢复成
1.0。这和精确还原不完全一样。 - 还原不会卸载 CleanYourTV 桌面，想删的话到电视「设置 → 应用」里卸载。
- 电脑连不上电视时，也可以直接在电视「设置 → 应用」里把被停用的应用重新启用。
- Windows 用
tools/disable.ps1和tools/restore.ps1。
做完一定要关掉调试
ADB 的 5555 端口是明文连接，有的固件（ro.adb.secure=0）甚至不需要授权，同一局域网的任何设备都能拿到命令行。仓库要求做完之后：
- 在电视的开发者选项里关闭 USB 调试和网络 / ADB 调试，并撤销 USB 调试授权。
- 重启电视，在电脑上运行
python3 tools/adb-closed.py <电视IP>，确认端口已关闭。
用 nc 检查时，只有 Connection refused 才算关了。macOS 会拦 nc，报的 No route to host 证明不了任何事。
新桌面在关闭调试后照常工作。
踩坑与解决
以下全部来自仓库的 TROUBLESHOOTING.md、README 和相关 Issues。
连接类
| 现象 | 原因和解决办法 |
|---|---|
macOS 上 adb connect 报 No route to host，但端口明明是开的 | macOS 的「本地网络」隐私权限把官方 adb 拦了。别在这上面耗时间，改用仓库的 tools/venv/bin/python -I tools/tv.py（纯 Python 客户端，不依赖 adb 程序）。 |
电视上反复弹「Allow USB debugging?」，可 adb devices 已经能用 | 用了一把电视还没认可的密钥。tv.py 现在会复用 ~/.android/adbkey。每次用未授权的密钥连接，电视上就多排队一个弹窗，先按返回键把弹窗全部关掉，再继续。 |
| 开了 USB 调试，5555 端口一直打不开（部分 Google TV，如 Skyworth 代工的飞利浦） | 用官方 adb 走一次「无线调试」配对：adb pair <ip>:<端口> <配对码>，再 adb connect，然后 adb tcpip 5555，之后 tools/tv.py 就能用了。adb tcpip 打开的 5555 一般重启后就失效；Wi-Fi 断开时安卓也会自动关掉无线调试。 |
| 找不到「无线调试」开关（小米等） | 正常现象。这些机型只开 USB 调试，就会在 5555 端口打开网络 ADB。 |
| 开发者选项被隐藏，或点版本号要密码（运营商盒子） | 往往只是入口被锁。可以从 Play 商店装一个能按名称打开界面的应用（如 Activity Launcher），打开 com.android.tv.settings/.system.development.DevelopmentActivity，在那里打开 USB 调试。 |
| USB 调试是灰色的，也没有无线调试，连接一直超时（#227，Airtel 盒子） | 运营商固件去掉了开关，这时超时是固件问题，不是 Wi-Fi、路由器或网线的问题，别去折腾网络。没有这两个开关，本项目就无从下手。 |
电视在单独的 VLAN / IoT 网络里，调试开着但 tv.py 超时 | 路由器挡住了电脑访问电视。临时加一条只放行「电脑 → 电视 TCP 5555」的防火墙规则，关闭 ADB 后删掉。不要把整个网段放开。 |
| Windows 上第一条批处理命令变成乱码 | PowerShell 5.1 会在管道文本前加 BOM。tv.py 已经处理了，.ps1 脚本也改成了干净的 UTF-8。 |
Git Bash 把 /data/local/tmp 改成了 Windows 路径 | 脚本已经设置了 MSYS_NO_PATHCONV=1。编译前记得设置 JAVA_HOME 和 ANDROID_HOME。 |
安装和使用类
| 现象 | 原因和解决办法 |
|---|---|
装 APK 报 INSTALL_FAILED_VERIFICATION_FAILURE，连厂商自己的 APK 也装不上 | 部分国行电视拒绝一切外部安装。只做停用广告这一半，换桌面这一半在这台电视上做不了，别反复重试。 |
| Play 保护机制拦截桌面，提示「为旧版安卓构建」 | 旧版代码的目标 SDK 是 29，现在已是 34。如果你用的是旧版代码，拉取最新代码重新编译。 |
Android 14 上 adb install 卡住不动 | 它在等电视屏幕上的确认。改为先把 APK 推到电视上，再在 shell 里执行 pm install -r。 |
| 推送大文件时卡住 | 用 tools/b64push.py，它把 APK 拆成 base64 分块上传，并核对校验值。 |
| Google TV 停用原桌面后，主页被设置向导抢走，甚至系统反复崩溃、Wi-Fi 每分钟断一次 | 罪魁是 com.google.android.tungsten.setupwraith。已经卡住的话，先执行 tools/tv.py 'pm enable --user 0 com.google.android.apps.tv.launcherx' 把原桌面救回来。 |
| 停用 setupwraith 后电视直接掉线，重启也连不上 Wi-Fi | 首次开机时保存的 Wi-Fi 属于 setupwraith，停用它，安卓就会把这个网络删掉。停用前先运行 tools/tv.py "dumpsys wifi" | grep -o 'cname=[^ ]*' 检查；如果显示 setupwraith，先在设置里「忘记」这个 Wi-Fi 再重新连上。tools/disable.sh 在这种情况下会自动跳过它。已经掉线的话，用遥控器或 USB 键盘在电视上重新连 Wi-Fi。 |
| Google 自家 Chromecast / Google TV Streamer 停用 setupwraith 后，手机投屏提示 Untrusted device | 投屏凭据存在 setupwraith 里。要么不停用它（和原桌面），要么每次开机后先启用它、等凭据加载好再停用，详见故障排查文档。 |
| 换桌面后主页还是原来的，或按主页键进了工厂测试程序 | 一定要等新桌面装好、能正常运行，再停用原桌面；安装脚本已经按这个顺序执行。set-home-activity 显示 Success 不代表真的切换了，要用 dumpsys activity activities | grep mFocusedApp 确认。 |
| 国行小米电视（MiTV-AETP0 等）设置默认主页显示成功，但实际不生效 | 系统按包名白名单过滤第三方主页。仓库的设备说明里有可选的处理和回滚步骤。 |
| 打开工厂菜单后，输入源按键失灵、CEC 关闭，重启后 Play 服务、Netflix、投屏被禁用（#470，海尔 / CVTE 板） | 只是「看看这个包是干什么的」就会触发。要用 dumpsys package <包名> 看，不要启动它。已经触发了，按故障排查文档的步骤退出工厂模式，再重新打开 CEC。 |
| 切换桌面后没有屏幕键盘（小米） | 默认输入法指向了一个没安装的百度键盘。执行 tools/tv.py 'ime set com.google.android.inputmethod.latin/com.android.inputmethod.latin.LatinIME'。 |
| 播放直播电视、HDMI 或 Netflix 时，截图是空的（#92） | 电视本身的限制，不代表连接或播放有问题。截图前先按主页键。 |
| 部分联发科电视（小米等）上截图得到坏的 PNG | 截图前面混进了一行日志。先在电视上 screencap -p /data/local/tmp/s.png，再把文件拉回电脑。 |
| 重启后有些应用又被启用了（如 TCL Android 9 的用户中心） | 部分固件每次开机都会按自己的清单重新启用。在清单开头注明即可，不用每次重启后再停用一遍。 |
| 停用后收不到系统更新 | 多数清单会停用系统更新服务，需要更新时重新启用它。流媒体应用仍然可以通过保留的 Play 商店更新。 |
想顺便屏蔽应用内广告？
README 给了一个可选办法：安卓 9 及以上，用系统的「私人 DNS」指向去广告的 DNS（例如 AdGuard DNS）。它挡不住 YouTube 广告，而且这个 DNS 服务商能看到电视的所有 DNS 查询。如果应用无法播放或提示没有网络，就改回 private_dns_mode opportunistic。具体命令见原 README 的常见问题部分。
原项目与许可证
- 原仓库：github.com/Gathin23/cleanyourtv（项目网站 cleanyour.tv，仓库曾用名 tv-vibehack，旧链接仍可访问）。
- 中文说明：README.zh-CN.md。
- 许可证：GitHub 仓库页把许可证显示为「Other / NOASSERTION」。这很可能是因为 LICENSE 文件里除了 MIT 许可证正文（Copyright (c) 2026 Gathin），还附了一段字体说明：桌面用的 Outfit 字体采用 SIL Open Font License 1.1，GitHub 的自动识别认不出这种组合。项目中文 README 也写明「项目采用 MIT 许可证」。也就是说，代码按 MIT 开源，字体按 OFL 授权。
- 遇到问题可以去仓库的 Discussions 讨论。如果你的机型验证通过，也可以按 CONTRIBUTING.md 提交清单，下一个同型号的人就能少走弯路。
本页的边界
本页只做整理和中文导读，不代表原作者，也不对你的电视做任何担保。停用系统组件仍有可能出问题，所以一定要先备份、分小批操作，并确认还原路径可用。