Companion Remote zh

电视遥控与 Companion

🌐 English · Русский · 中文

在你的局域网内，用手机控制另一台设备（通常是 Android TV）上运行的 ClashFest。开关 VPN、把订阅分享到电视、查看状态、重命名设备。无账号、无云、无中继 —— 一切都留在你的 Wi-Fi 内。

---

你能做什么

• 在局域网内按友好名称（客厅、卧室……）发现 ClashFest/SlothClash 设备。
• 通过扫描电视上的 QR 安全配对（无摄像头的控制端如 PC 可输入 PIN）。
• 开关电视上的 VPN。
• 一键把手机上的某个订阅分享到电视。
• 查看状态（已连接 / 活动配置文件 / 流量）并重命名设备。

设置

在电视上（代理端 agent）

1. 在电视上打开 ClashFest → Remote control 入口（主页或设置中）。
2. 开启 Allow remote control。默认关闭 —— 像 ADB 调试一样，需要你主动开启。
3. 电视会显示一个 QR 码（以及用于核对的 ip:port）。保持它在屏幕上。
   • 若要配对 PC / 无摄像头的控制端，改选 Show pairing PIN —— 6 位数字，有效约 60 秒。

在手机上（控制端 controller）

1. 打开 ClashFest → Companion（设置，或 ＋ 面板 → Control a TV）。
2. 扫描电视的 QR（或输入 PIN）。
3. 配对完成！设备出现在列表中。配对后会立即提示你把活动订阅分享给它。

两台设备必须在同一局域网内。配对需要你实际看到电视屏幕（QR/PIN）—— 这就是安全凭证。

故障排查

• 配对后立刻「Unreachable」 —— 确认两台设备在同一 Wi-Fi（非访客隔离 / 不同 VLAN）。模拟器不能作为代理端 —— 其 10.0.2.15 是内部 NAT，真实设备无法访问。
• QR 过期 —— 电视会持久化端口，但重装后请重新打开遥控界面以获取新 QR。
• 发现不到设备 —— 部分路由器会屏蔽 mDNS/组播；重试或直接扫描 QR 配对。

安全模型

机制	原因
默认关闭 —— 需在电视上显式开启	不会静默暴露到网络
QR/PIN 配对携带 ip:port + 令牌 + TLS 证书指纹	需实际看到电视 = 在场证明
TLS（自签名、按指纹固定）	流量（含订阅）加密；无法 MITM
按设备的 bearer 令牌，可通过取消配对撤销	单个控制端泄露 ≠ 全部；易于撤销
网关上的命令白名单	即便令牌泄露也无法造成任意破坏
代理内核 REST API 始终绑定 127.0.0.1	内核 API 不接触局域网 —— 网关是唯一可审计的入口

---

面向开发者 —— 协议（v1）

Companion 是一个位于应用已有控制（VpnService 开关、订阅导入）之前、以及（后续）Mihomo external-controller REST API 之前的、轻量而安全的局域网网关。

• 发现： mDNS/NSD 服务 _clashctl._tcp。TXT 键：app（clashfest|slothclash）、id（稳定设备 id）、name、ver、fp（TLS 指纹）。
• 配对 QR： clashctl-pair://<ip>:<port>?id=<deviceId>&name=<name>&app=<app>&fp=<sha256>&token=<token>
• 传输： HTTPS（自签名、固定）。每个请求携带 Authorization: Bearer <token>。
• 端点（v1）：
  • GET /v1/status → { running, activeProfile, uploadTotal, downloadTotal, mode }
  • POST /v1/power { "action": "on" | "off" | "toggle" }
  • POST /v1/subscription { "url", "name" }（代理端拉取 + 导入）或 { "payload": "<yaml>" }
  • POST /v1/rename { "name" } → 持久化 + 重新广播 mDNS
  • POST /v1/pair { "pin" } → 签发 bearer 令牌（由 PIN 门控，无需 bearer）
• 第二阶段： ANY /v1/core/* 白名单代理到本地 external-controller（代理组选择、/traffic、/connections），以及用于实时推送的 WS /v1/events。

共享的传输契约位于 clash-companion 仓库，使 ClashFest、SlothClash 及未来任何控制端都遵循逐字节一致的协议。