---
name: rt-onboard
description: 把一台新设备接入 rt 设备网络（装客户端、登录、上线、验证可连），并按需接管安卓手机控制或电脑控件树控制。当用户说"帮我把这台机器装到 rt 上""我要加一台设备到 rt 网络""新电脑怎么接入 rt""让这台手机连上 rt""rt 怎么安装""给我这台机器装 rt"时使用。也在用户已装但"登录不上/上线了但别人连不上/设备名想改"时使用。触发词：接入rt、装rt、安装rt、新设备、加设备、rt登录、rt上线、连上rt、把xx接入rt。
---

# rt 设备接入

> 你正在帮用户把一台设备接入 **rt**（跨平台设备网络）。接入完成后，
> **同一账号下的所有设备可以互相免密 SSH**。

**这份文档负责「装上去并验证」，不负责排障。** 出问题转 `rt-diagnose` skill。

---

## ⚠⚠⚠ 开始之前：必须先跟用户确认的一件事

**rt 的设备是免密 SSH的。** 接入用的账号密码一旦给了你，就等于
**你拿到了这个账号下所有设备的 shell**（含手机、含能装东西的电脑）。

所以：

1. **明确告知用户这一点**，用一句话说清：「给我密码 = 我能进你账号下所有设备」。
2. **不要把密码写进任何文件、任何命令行、任何日志**。见下面「凭证处理」。
3. 用户若只想装**一台**，提醒他：**设备配额**是限制（免费版 2 台），但**登录权限是账号级的**。

> 用户明确说"我信任你，直接给密码"时，照做，但把上面第1 点说一遍就够了，不要反复劝。

---

## 硬性约束

1. **先问清目标平台**（Windows / macOS / Linux / Android-Termux）—— 四条安装命令不同，**猜错会让用户白跑一遍**。
2. **每一步都要有"怎么确认成功了"** —— rt 的失败高度依赖平台与权限，靠猜会连错方向。
3. **不要替用户输验证码**（邮箱验证码在他手机上/邮箱里）。让用户自己跑 `rt register`，你在旁边看输出。
4. **不可逆操作先问**：删设备、删 `~/.rt`、改防火墙、动系统 sshd 配置。这些都要先说明后果。
5. **改完让用户验证**，不要只说"我搞定了"。

---

## 第 0 步：分清「装得上」和「能连」

rt 接入有**两件独立的事**，混在一起就会得出错误结论：

| 阶段 | 判据 | 谁来判断 |
|---|---|---|
| ① 装完并上线 | 设备出现在 `rt ls` 且「可连接」列是绿的 | 客户端自己 |
| ② 别人能连上它 | 另一台设备 `rt ssh <名字>` 能进 | **要另一台设备才能验** |

**注意**：本机 `rt ls` 看到自己「可连接」，**不等于**别人也能连 ——
还要看 `keys_version` 是否同步（心跳周期，最长十几分钟）。

---

## 第 1 步：装客户端

| 平台 | 命令 |
|---|---|
| **Windows** | `irm https://rt-web-b4t.pages.dev/install.ps1 \| iex`（**管理员** PowerShell） |
| **macOS / Linux** | `curl -fsSL https://rt-web-b4t.pages.dev/install.sh \| bash` |
| **Android（Termux）** | 同上，但在 **Termux** 里跑 |

**两条命令都支持预演**，先跑一次只检查不安装 —— 用户拿不准时这很有用：

```bash
bash install.sh --check# Linux / macOS / Termux
irm https://rt-web-b4t.pages.dev/install.ps1 | iex# Windows（加 -check）
```

**怎么确认成功**：命令结束时打印出 rt 的安装路径（Linux 常见 `/usr/local/bin/rt`，
Termux 是 `$PREFIX/bin/rt`，都没写权限时是 `~/.local/bin/rt`）。

### ⚠ 平台相关的三个坑

- **Termux 不要加 sudo**。提权后反而读不到 `$PREFIX` 里的配置，sshd 起不来。
- **Windows 装完 `rt up` 会告诉你 `authorized_keys` 的真实路径**：
  它在 `%ProgramData%\ssh\administrators_authorized_keys`，**不在** `~\.ssh\`。
  （Windows 的 sshd 跑在 LocalSystem，读不到管理员的用户目录。）
- **Linux 上 `rt up` 可能需要 root**（要起 sshd 并监听 22）。没root 会自动降级到 **8022**，
  **这是正常降级不是错误**，不用让用户折腾 sudo。

### ⚠ Termux 额外依赖

Termux 的 `/etc` 是只读的，cloudflared 需要 proot 盖一层可写的：

```bash
pkg install proot
```

**怎么确认**：`proot --version` 有输出即可。这条**漏了后面必然失败**，是最常见的 Termux 装机坑。

---

## 第 2 步：登录

```bash
rt login    # 已有账号
rt register # 没账号：走邮箱验证码
```

**登录的真相**（理解了就不会卡在这）：

- `rt register` 会往邮箱发验证码 → **验证码在用户手里**，你不要索要。
- 登录成功后会往 `~/.rt/config` 写 `token=`。**这个 token 就是账号身份**，
  而 rt 的设备是免密 SSH 的 ⇒ **拿到 token ≈ 拿到全账号的设备**。
- `~/.rt/config` 里有 `token_exp`（有效期）。过期后 `rt ls` 之类会开始报错，
  让用户重跑 `rt login`。

### ⚠ 凭证处理（红线）

> **rt 的设备是免密 SSH 的** —— 拿到账号登录态，就等于能进这个账号下**所有设备**。
> 下面表格里的每一行都受这条约束。

| 做 | 不做 |
|---|---|
| 让用户在自己终端里跑 `rt login` | 让用户把密码发在对话里再由你代跑 |
| 需要时读 `~/.rt/config` 的 `token=` | 把 token 写进脚本/文件/命令行 |
| 引用时写 `<TOKEN>` 占位符 | 回显完整 token |

用户已经给了密码时：**用密码交互式登录**（`rt login` 自己会问），
不要写 `rt login --password=xxx` 这类形式 —— 会进 shell 历史与进程列表。

---

## 第 3 步：上线

```bash
rt up
```

它做四件事：起 sshd → 开隧道 → 上报地址 → **自动在后台起看门狗保活**。

**怎么确认成功**：命令结束时打印出隧道域名（形如 `xxx-yyy-zzz.trycloudflare.com`）。

**三个可选项**：

```bash
RT_NAME=我的机器 rt up   # 自己起名（上线后也能 rt fix-name 改名）
RT_AUTO_WATCHDOG=0 rt up # 省后端额度（但设备断了不会自愈）
```

### ⚠ 上线了但别人连不上

按这个顺序查（**不要跳步**）：

```bash
rt ls -v <设备名>    # 看 keys_version 是否为 0
rt doctor <设备名>   # 逐段自查：钥匙 → 隧道 → sshd
```

最常见的原因：**新设备的公钥还没同步**（心跳周期，最长十几分钟）。
`ssh` 报认证失败时，让用户**等几分钟再试**，不要立刻重装。

---

## 第 4 步：验证（**必须做，不能跳**）

```bash
rt ls          # 本机看：设备在列表里、「可连接」列是绿的
rt status      # 看隧道域名与本机地址
```

**真正的端到端验证要另一台设备**：

```bash
# 在另一台同账号设备上
rt ssh <设备名> hostname        # 能回显对端主机名 = 真的连上了
```

**只有本机时能验到哪一步**：`rt ls` 里自己那行绿了= 客户端自认正常，
**不等于**别人能连（钥匙可能还没同步）。如实告诉用户这一点，不要说成"完全好了"。

---

## 第 5 步（可选）：安卓手机控制

手机装好 rt 之后，还能**读屏、点按、输入文字、启动 App**。要三步：

1. **手机上开两个开关**（设置 → 开发者选项）：
   `USB 调试` + **「仅充电模式下允许 ADB 调试」**。
   ⚠ **后一条不开，整个 ADB 通道被禁**；Android 15 以后才有这个开关。**它优先于无线调试**。
   **怎么确认**：`rt ssh <手机名> "getprop init.svc.adbd"` 输出 `running`。
2. **配对一次**：`rt adbpair <连接端口> <配对码> <连接端口> <手机设备名>`
   （配对码是手机无线调试页上弹出的那 6 位数）。**只需做一次**，重启换网都不用重配。
3. **固定端口**：`rt adbtcp` ⇒ 看到 `✓ 固定端口就绪`。
   ⚠ 这一步不能省：无线调试端口**每次开关都变**，切移动数据时系统还会直接停用它。

之后就能：

```bash
rt android tree              # 读控件树（主线，最快最准）
rt android tap-text 搜索     # 按文字点（自动算中心点，**不用手算坐标**）
rt android text "hello"      # 输入英文/数字（走 adb，不需要额外依赖）
                             # ⚠ 中文要先 `rt setup-u2` —— 它装在 **rt 跑的这台机器** 上，
                             #   被控手机不用装；见 docs/ADB-AUTOMATION.md「中文输入」一节
rt android app com.tencent.mm   # 启动 App
rt android tap-input         # 点空白输入框（按 class=EditText 找，换分辨率也对）
rt android doctor            # 通道出问题先跑它
```

⚠ 通道（转发 + adb）死掉时别手工折腾：`bash tools/rt-android-ready.sh <设备名>` 一条命令重建并自检。
要发一条微信这类**限时整链验证**，用 `tools/rt-wechat-send.py`（~19s），别用 `flow run`（每步 dump，慢）。

### ⚠ 一条设备就绪后能反复用的「操作流」

一串操作可以**录成脚本，之后一条命令重放**（全程零截图、按控件树定位）：

```bash
rt android flow start 发消息     # 开始录
rt android tap-text 搜索         # 正常敲命令，每步自动记账
rt android flow stop             # 存成 ~/.rt/flows/发消息.flow
rt android flow run 发消息 "李四" "在吗"   # 回放，{{1}} {{2}} 顺序替换
```

要点：**只记「意图」不记坐标**（坐标每次读树现算）、**自动补等待**、
**失败那步不录**、**回放卡住会停下并报出卡在第几步**。

### ⚠ rt 不会替你做的事

**转账、付款、输入支付密码** —— 这些 rt 不代劳，请用户自己在手机上操作。
解锁可以用用户自己的锁屏密码（`rt unlock`，它会自动读后端存的密码）。

---

## 第 6 步（可选）：电脑控件树控制

`rt ui` 让 AI 直接操作电脑（读控件树、点击、输入、按键、截图）——
认的是**真控件**（按钮、输入框、菜单），不是猜坐标。

```bash
rt ui doctor        # 首次会自动装依赖，只装一次
rt ui tree          # 读当前窗口控件树
rt ui click 保存     # 按名字点
rt ui type "hello"
rt ui screen
rt ui tree --device m1-macbookair   # 控制别的机器
```

**怎么确认成功**：`rt ui doctor` 全绿；`rt ui tree` 能列出控件名与坐标。

### ⚠ 三个必踩的坑

- **密码别写命令行**（会进进程列表）：用 `rt ui type --file /path/to/secret` 或 `--stdin`。
- **首次使用**会往 `~/.rt/pylibs` 装几个开源库（不污染系统环境、不需要管理员）。
- **macOS 首次还需手动授权**：系统设置 → 隐私与安全性 → 辅助功能 → 给终端授权。
  ⚠ **没授权会报 `window.crypto.subtle is undefined`**（局域网入口不是 Secure Context，
  浏览器不提供 WebCrypto）—— 这不是 rt 的 bug。

---

## 完成后要给用户什么

一句话结论 + **他下次怎么自己看一眼**：

```
rt ls        # 所有设备与「可连接」状态（**只看这一列**）
rt doctor    # 一键体检
rt status    # 本机的隧道域名与地址
```

## 转人工的情况

- 邮箱验证码收不到、账号被锁
- 配额与计费问题
- `rt up` 报客户端自身的段错误 / 崩溃现场
- 服务端返回异常（用量、额度、版本）

这些不是客户端能修的，让用户把 `rt doctor --report` 的内容发给 rt 维护者。

## 相关信息

- **排障** → 用 `rt-diagnose` skill（本文档只管接入，装完出问题转它）
- **能力对照表**（bash 版 vs Windows 版差在哪）：仓库 `docs/CAPABILITY.md`，
  由代码自动生成，不会过期。