Companion Remote zh

远程控制与 Companion

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

在局域网内从你的桌面端控制运行在另一台设备上的代理客户端——通常是电视上的 ClashFest，或无头主机上的 SlothClash。开关其 VPN、向其推送订阅、查看状态、重命名。无账户、无云、无中继——一切都留在你的 Wi-Fi 内。

这里 SlothClash 是控制端；另一台设备作为代理端运行。

---

你能做什么

• 按友好名称（客厅、卧室……）在局域网中发现代理端。
• 用 PIN 安全配对（桌面无摄像头，因此使用代理端显示的验证码——或粘贴代理端的配对字符串）。
• 切换代理端 VPN 开/关。
• 一步推送你的某个订阅到代理端。
• 查看状态（运行中 / 激活配置文件 / 流量）并重命名设备。
• 解除配对以立即吊销访问。

设置步骤

在代理端（例如电视）

1. 打开其应用 → 远程控制入口。
2. 启用允许远程控制。默认关闭——如同开启调试，你需主动选择。
3. 选择显示配对 PIN——一个 6 位验证码，短时有效。（同时显示 QR 及其 ip:port。）

在桌面端（控制端）

1. 打开 SlothClash → Companion。
2. 输入代理端的 PIN（或粘贴其 clashctl-pair://… 字符串）。
3. 配对完成！设备出现在列表中，随后可立即将激活订阅推送给它。

两台设备必须在同一局域网。配对需要你亲眼看到代理端屏幕（PIN/QR）——这份在场即安全凭证。

故障排除

• 配对后立刻「不可达」 — 确认两台设备在同一 Wi-Fi（无访客隔离 / 不同 VLAN）。
• 发现不到 — 部分路由器屏蔽 mDNS/多播；改用 PIN 或粘贴的配对字符串直接配对。
• 代理端更换 / 重装 — 重新打开其远程控制界面获取新 PIN 并再次配对。

安全模型

机制	原因
默认关闭——需在代理端显式开启	不做静默的网络暴露
PIN / QR 配对携带 ip:port + 令牌 + TLS 指纹	需要亲眼看到代理端 = 在场证明
TLS（自签名、固定） 由配对指纹校验	流量（含推送的订阅）加密；无法中间人
按设备的 bearer 令牌，解除配对即吊销	一个被攻破的控制端 ≠ 全部；易于吊销
内核 REST API 始终绑定在 127.0.0.1	网关是唯一可审计的局域网入口

---

面向开发者 — 协议（v1）

Companion 是代理端控制（VPN 开关、订阅导入）前的一个轻量安全局域网网关。

• 发现： mDNS 服务 _clashctl._tcp。TXT 键：app（clashfest|slothclash）、id、name、ver、fp（TLS 指纹）。
• 配对字符串： 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" }
  • POST /v1/pair { "pin" } → 签发 bearer 令牌

共享的协议约定位于 clash-companion 仓库，因此 ClashFest、SlothClash 及任何未来的控制端都逐字节遵循同一协议。