Companion Remote ru

ТВ-пульт и Companion

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

Управляйте инстансом ClashFest на другом устройстве — обычно Android TV — с телефона, по вашей локальной сети. Включайте/выключайте VPN, шарьте подписку на ТВ, смотрите статус и переименовывайте устройство. Без аккаунтов, без облака, без релея — всё остаётся в вашем Wi-Fi.

---

Что можно

• Находить устройства ClashFest/SlothClash в LAN по понятному имени (Гостиная, Спальня, …).
• Сопрягать безопасно, сканируя QR на ТВ (или вводя PIN для устройств без камеры, например ПК).
• Включать/выключать VPN на ТВ.
• Шарить одну из подписок телефона на ТВ в один тап.
• Смотреть статус (подключено / активный профиль / трафик) и переименовывать устройство.

Настройка

На ТВ (агент)

1. Откройте ClashFest на ТВ → пункт Remote control (на Главной или в Настройках).
2. Включите Allow remote control. По умолчанию выключено — как ADB-отладка, включаете осознанно.
3. ТВ покажет QR-код (и свой ip:port для проверки). Оставьте на экране.
   • Для сопряжения ПК / устройства без камеры выберите Show pairing PIN — 6-значный код, действует ~60с.

На телефоне (контроллер)

1. Откройте ClashFest → Companion (Настройки или шторка ＋ → Control a TV).
2. Отсканируйте QR ТВ (или введите PIN).
3. Сопряжено! Устройство появится в списке. Сразу после сопряжения предложат пошарить активную подписку на него.

Оба устройства должны быть в одной локальной сети. Сопряжение требует физически видеть экран ТВ (QR/PIN) — это доказательство присутствия.

Траблшутинг

• «Unreachable» сразу после сопряжения — убедитесь, что оба устройства в одном Wi-Fi (не гостевая изоляция / разные VLAN). Эмулятор не может быть агентом — его адрес 10.0.2.15 внутренний NAT, недостижим с реального устройства.
• QR устарел — ТВ персистит порт, но после переустановки переоткройте экран remote-control для свежего QR.
• Ничего не находится — некоторые роутеры блокируют mDNS/multicast; попробуйте снова или сопрягайтесь прямым сканом QR.

Модель безопасности

Механизм	Зачем
По умолчанию OFF — явное включение на ТВ	Никакой тихой сетевой экспозиции
QR/PIN-сопряжение несёт ip:port + токен + отпечаток TLS-сертификата	Требует физически видеть ТВ = доказательство присутствия
TLS (self-signed, pinned) по отпечатку из QR	Трафик (включая подписки) зашифрован; MITM невозможен
Пер-устройство bearer-токен, отзывается un-pair'ом	Один скомпрометированный контроллер ≠ все; лёгкий отзыв
Whitelist команд на шлюзе	Даже утёкший токен не сделает произвольного вреда
REST API ядра остаётся на 127.0.0.1	API ядра не касается LAN — шлюз это единственная аудируемая точка входа

---

Для разработчиков — протокол (v1)

Companion — это тонкий безопасный LAN-шлюз перед существующими контролами приложения (тумблер VpnService, импорт подписки) и — позже — REST API external-controller от Mihomo.

• Discovery: mDNS/NSD сервис _clashctl._tcp. TXT-ключи: app (clashfest|slothclash), id (стабильный device id), name, ver, fp (отпечаток TLS).
• Pairing QR: clashctl-pair://<ip>:<port>?id=<deviceId>&name=<name>&app=<app>&fp=<sha256>&token=<token>
• Транспорт: HTTPS (self-signed, pinned). 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)
• Фаза 2: ANY /v1/core/* whitelist-прокси к localhost external-controller (выбор прокси-группы, /traffic, /connections), плюс WS /v1/events для live-пуша.

Общий wire-контракт лежит в репо clash-companion, чтобы ClashFest, SlothClash и любой будущий контроллер говорили байт-в-байт по одному протоколу.