couch-tv完整入门指南:3种部署方式,5分钟打造你自己的电视遥控器
couch-tv完整入门指南:3种部署方式,5分钟打造你自己的电视遥控器
couch-tv 是一个免费开源项目,帮你把电视变成自己的:用一个带玻璃时钟和风景场景的电视主屏幕替换 Google TV 默认主页(没有广告),再把手机变成完整的电视遥控器——方向键、音量、打字输入、电源开关全都有,还可以选配 Claude AI 助手,说一句"放部喜剧"它就找到并开播。这篇文章带你用 3 种部署方式,从零开始 5 分钟搭建好自己的电视遥控器。
1分钟了解 couch-tv:它是什么
一句话概括:你自己的 Google TV 主页 + 手机遥控器,外加可选的 Claude 助手。核心能力包括:
| 功能 | 说明 |
|---|---|
| 🏠 场景主屏幕 | 5 套风景场景每 20 秒轮换(夜晚、黄昏、水面、雾、黎明),支持自己的照片和 Classic 风格 |
| 📱 手机遥控器 | 手机浏览器打开即用,方向键、音量、打字、电源按钮一应俱全 |
| 🔍 按名字找片 | "放 Bluey",couch-tv 自动找到该剧在哪个流媒体平台并直接开播 |
| ▶️ Keep watching | 跨 App 的"续看"栏目,最多 10 部剧,按人区分 |
| 🧒 儿童模式 | 只放你选好的节目,退出需要家长 PIN 码 |
| 🤖 AI 助手(可选) | 接入 Claude 等 AI 服务,"放部搞笑的"这种模糊需求也能搞定 |
| 🏠 智能家庭 | 可接 Home Assistant:空调、场景、门铃卡片 |
1分钟兼容性检查:我的电视能用吗
先说结论:Google TV / Android TV 体验最完整,三星、LG、Roku、Apple TV 等也有对应方案(多为 Beta)。在电视上打开 设置 → 系统 → 关于,看到 "Android TV OS" 字样就说明支持。
不确定也不怕,项目自带只读检测脚本,不改动电视任何内容:
.venv/bin/python scripts/find-tvs.py # 列出 Wi-Fi 上所有电视
.venv/bin/python scripts/check-tv.py <电视地址> # 判断这台电视能跑哪几种方式
脚本通过探测各品牌电视的端口来识别设备(比如 Roku 的 8060 端口),全程只读。完整兼容矩阵见 docs/PLATFORMS.md。
3种部署方式对比:5分钟选对你的方案
couch-tv 提供三种运行方式,按"要不要一台常开的电脑"来区分:
| A. 仅电视主页 | B. 电脑桥接 | C. 电视内运行(On-TV) | |
|---|---|---|---|
| 新主屏幕 | ✅ | ✅ | ✅ |
| 手机遥控器 | ❌ | ✅ | ✅ |
| 需要常开的电脑 | 不需要 | 需要(Mac / Linux / 树莓派) | 不需要 |
| 远程开机电视 | ❌ | ✅(Wake-on-LAN) | ❌ |
| 跨 App 续看 | 部分 | ✅ | 部分 |
| AI 助手 | ❌ | ✅(Claude) | 可选(自带 API key) |
选择建议:只想换个清爽主页 → 方式 A;有一台家里常开的电脑或 NAS → 方式 B(功能最全、测试最充分);没有常开电脑但想要手机遥控器 → 方式 C。
方式一:AI 代部署(新手最快路径)
这是官方推荐的最简单方式:把仓库交给 AI agent,它会自动找电视、问问题、给出计划,你确认之前不会改动电视任何东西。
第 1 步:克隆仓库
git clone https://gitcode.com/gh_mirrors/co/couch-tv
cd couch-tv
python3 -m venv .venv && .venv/bin/pip install -r bridge/requirements.txt
第 2 步:打开 AI 编程助手(如 Claude Code),对它说:"set this up on my TV"(在我的电视上部署)。
它会读取 AGENTS.md 中的指令,按顺序执行:
- 找电视:运行 scripts/find-tvs.py 和 scripts/check-tv.py,向你念出检测结果;
- 提问:谁看这台电视、喜欢什么视觉风格、常用哪些 App、要不要儿童模式和 PIN 码;
- 复述计划:把完整方案读给你听,等你明确说"yes"才会动手;
- 部署并验证:装好主页、配好遥控器,最后教你怎么撤销。
整个过程你只需要回答几个问题 + 在电视上按两次"允许"。
方式二:电脑桥接(功能最全,B 方案)
适合家里有一台 Mac、Linux 主机或树莓派可以常开。全部步骤在 docs/SETUP.md,这里给你精简版。
第 1 步:开启电视开发者模式(所有方式都需要)
- 电视上:设置 → 系统 → 关于 → Android TV OS 版本号,连续按 7 次,解锁开发者选项;
- 打开 USB debugging(USB 调试),如有 Network debugging 也打开;
- 记住电视的 IP 地址(设置 → 网络 → 你的 Wi-Fi),建议在路由器上给电视设固定地址。
第 2 步:配置 config.json
cp config.example.json config.json
打开 config.example.json 照着填:tvs 填电视 IP、people 填家里成员名字、weather 填城市坐标、country 填两位国家码。每个字段的完整说明在 docs/CONFIG.md。
第 3 步:配对电视
.venv/bin/python bridge/pair_tv.py living-room
电视会显示一个 6 位验证码,输入即可,电视会把它识别为"Couch TV bridge"遥控器。
第 4 步:构建手机遥控器并启动 bridge
cd remote && npm ci && npm run build && cd ..
.venv/bin/python bridge/server.py
在手机上打开 http://你的电脑地址:5400,点"添加到主屏幕",遥控器就装好了(docs/REMOTE.md 有 iPhone / Android 的详细步骤)。
第 5 步:把主屏幕装到电视上
TV_IP=<电视地址> APK=couch-tv-home.apk BRIDGE_URL=http://<电脑地址>:5400 sh tv-home/tools/apply.sh
apply.sh 会安装 App 并设为主页。放心:它只关环境模式广告,电视自带主页和设置 App 都保持开启,随时可安全撤销。
想让 bridge 常驻运行? 用 macOS 的 launchd 或 Linux 的 systemd 示例文件:
- macOS:bridge/examples/couch-tv-bridge.plist.example
- Linux:bridge/examples/couch-tv-bridge.service.example
用 Docker 跑在 NAS 上? 仓库自带 Compose 配置(Synology 等 NAS 均可):
docker compose -f examples/docker/compose.yaml up -d --build
原理和排坑细节见 docs/DOCKER.md 与 examples/docker/compose.yaml。
方式三:On-TV 模式(不用任何电脑)
方式 C 把 bridge 直接装进电视上的一个 App(dev.couchtv.ontv,显示名 Couch TV):手机遥控器由电视自己提供(http://<电视IP>:5400),电视通过自己的调试端口控制自己,家里什么都不用常开。
步骤精简版(完整指南见 on-tv/README.md):
- 开启开发者模式(同方式二第 1 步);
- 安装
couch-tv-ontv.apk(从 Releases 下载,或用sh scripts/build-apk.sh自行构建):
.venv/bin/python on-tv/scripts/real-tv.py --ip <电视IP> install couch-tv-ontv.apk
- 电视上打开 Couch TV App,它会显示地址和一个 6 位配对码;
- 手机打开该地址、输入配对码,遥控器配好;
- (可选)在 App 里打开 Use as home screen,让它接管主页。
注意:方式 C 不能远程开机电视(电视休眠后 App 也睡了);Samsung/LG/Roku/Apple TV 等非 Android 电视不支持此方式,请走方式 B。
装好之后:5分钟玩出花样
1. 在电视上改设置,不用碰电脑
主页底部齿轮图标(或按遥控器设置键)打开 Home settings:语言、天气城市、场景、12/24 小时制、App 顺序、人物列表、快捷按钮,全部可视化修改。
2. 按住 App 名称的 OK 键即可拖动调整 App 顺序;App Store 磁贴里可以添加新 App。
3. 开启儿童模式(可选):给小孩建一个 profile 并标记 "kid": true,再配置儿童主页——一排放大海报的节目架 + 最多 6 个允许的 App,退出要家长 PIN。详见 docs/TV-HOME.md。
4. 换个心情换个景:不满意的内置场景?任意一张照片都能用 docs/MAKE-A-SCENE.md 一键做成带玻璃时钟的自定义场景。
安全、隐私与撤销
- 数据不出门:你的设置、密钥、观看历史全部只存在自己的电脑和电视上;
- bridge 无密码:默认同网段任何人(包括孩子)都能用遥控器,建议访客走访客 Wi-Fi,或在
config.json里设置bridge.pairing_key加密码; - 绝不端口转发:bridge 只适合内网,远程使用请走自建 VPN;
- 随时可撤销:
apply.sh不删除任何东西。恢复 Google 主页:
TV_IP=<电视地址> sh tv-home/tools/undo.sh
完整卸载指南(含只用电视遥控器的撤销法)见 docs/UNINSTALL.md。
延伸阅读
| 想了解 | 看这里 |
|---|---|
| 全部部署细节与撤销 | docs/SETUP.md |
| config.json 每个字段 | docs/CONFIG.md |
| 手机遥控器安装细节 | docs/REMOTE.md |
| 电视主页全部功能 | docs/TV-HOME.md |
| 各品牌电视专属指南(三星/LG/Roku…) | docs/README.md |
| 故障排查 | docs/TROUBLESHOOTING.md |
最后提醒:部署前建议给电视和电脑都设好路由器固定 IP,这是后续 90% 小问题的根源。现在去克隆仓库、交给你的 AI 助手,5 分钟后你的电视就不一样了 🛋️




