让 AI Agent 通过 USB 或 Wi-Fi 操作 Android 手机

连接 Android 12 及以上手机，获取真实画面、输入文字、传输文件，并通过 rdp-cli 在同一会话中人工接管。

支持基线为 Android 12 及以上。已实测设备是运行 Android 12 的 Google Pixel 3，不代表所有品牌或后续系统版本均已验证。

准备手机

开启开发者选项和 USB 调试，连接数据线，在解锁的手机上确认调试授权。
无线连接需开启无线调试，使用手机当次显示的配对码和配对端口；连接端口另行读取，无需先接 USB。
Windows USB 连接需要适合手机及电脑架构的 WinUSB 驱动，ARM64 也需匹配的驱动。rdp-cli 不会自动安装驱动或关闭其他调试工具。 Linux (x86_64 / ARM64) 需要通过适当的 udev 规则或设备组，让普通用户有权访问手机 USB 设备；以下命令使用 Bash，运行 rdp-cli 时不要加 sudo。macOS 使用系统 USB 接口。

将 DEVICE_SERIAL、SESSION、OBSERVATION、PHONE_IP 和两个端口替换为实际值。连接后保存 data.session，每次截图后使用返回的 data.observation。用返回的 wifi: 设备 ID 替换 wifi:PHONE_GUID；自行为 PHONE_REF 取名，用于在这台电脑保存配对身份。出现提示时输入当次六位配对码，命令会通过标准输入发送。

Windows PowerShell: rdp-cli → .\rdp-cli.exe.

发现并连接

明确选择发现结果中的设备 ID。连接不会弹出窗口，也不会开启声音。

rdp-cli android devices
rdp-cli connect --protocol adb --device usb:DEVICE_SERIAL --transport usb
rdp-cli screenshot --session SESSION --out before.png

完成一项小任务

在已授权的手机上打开记事应用，新建空白笔记。查看 before.png，把 X、Y 替换成文字输入框的实际坐标，再点击。查看 focused.png，将这次响应的 data.observation 保存为 NEW_OBSERVATION 后粘贴文字。用 result.png 核对结果。这些命令直接操作手机，不需要打开电脑端查看窗口。

rdp-cli android touch --session SESSION --kind tap --x X --y Y --observation OBSERVATION
rdp-cli screenshot --session SESSION --out focused.png

中文、其他 Unicode 字符或多行文字使用显式剪贴板方式。它会替换手机剪贴板，不会同步电脑剪贴板。将示例文字改成你的笔记。手机旋转或观察值过期时，重新截图并查看后再操作。

rdp-cli android text --session SESSION --method clipboard --text "远端任务已完成。" --observation NEW_OBSERVATION
rdp-cli screenshot --session SESSION --out result.png

文件与文件夹

测试文件往返时，先在本机新建纯文本 note.txt，填入自己的测试内容。上传为 note.txt，将 data.transfer_id 保存为 UPLOAD_TRANSFER，等状态变成 completed。下载到另一个本机文件，把新传输 ID 保存为 DOWNLOAD_TRANSFER，再等待 completed，最后比较两个文件。路径相对于手机会话目录，不是应用私有目录。默认不覆盖同名文件。

rdp-cli files upload --session SESSION --local ./note.txt --path note.txt
rdp-cli files status --session SESSION --transfer-id UPLOAD_TRANSFER
rdp-cli files download --session SESSION --path note.txt --local ./note-returned.txt
rdp-cli files status --session SESSION --transfer-id DOWNLOAD_TRANSFER

无线连接

Wi-Fi 是 USB 的替代连接方式。如果同一手机已有 USB 会话，先运行 disconnect --session SESSION。明确配对，再用返回的设备 ID 和当前连接端口连接。保存新的 data.session，重新截图后再操作。

无线连接需开启无线调试，使用手机当次显示的配对码和配对端口；连接端口另行读取，无需先接 USB。

连接 Android 手机

macOS / Linux · Bash

printf '%s' '配对码: '
IFS= read -r -s rdp_pair_code
printf '\n'
printf '%s' "$rdp_pair_code" | rdp-cli android pair --host PHONE_IP --port PAIR_PORT --code-stdin --save-device-auth PHONE_REF
unset rdp_pair_code
rdp-cli connect --protocol adb --device wifi:PHONE_GUID --transport wifi --host PHONE_IP --port CONNECT_PORT --device-auth-ref PHONE_REF

Windows · PowerShell

$pairingCode = Read-Host '配对码' -AsSecureString
try {
  [System.Net.NetworkCredential]::new('', $pairingCode).Password |
    .\rdp-cli.exe android pair --host PHONE_IP --port PAIR_PORT --code-stdin --save-device-auth PHONE_REF
} finally {
  $pairingCode.Dispose()
}
.\rdp-cli.exe connect --protocol adb --device wifi:PHONE_GUID --transport wifi --host PHONE_IP --port CONNECT_PORT --device-auth-ref PHONE_REF

人和 Agent 共用会话

命令、原生窗口与授权浏览器共用一个持久会话；需要时随时暂停或接管。

rdp-cli watch --session SESSION --viewer window
rdp-cli watch --session SESSION --viewer web

观看与接管

使用边界

USB 列表为空时检查数据线和设备访问权限。ADB_DEVICE_BUSY 表示手机被别的调试工具占用，应明确关闭那条连接。Wi-Fi 连接应核对当前连接端口与已保存的手机身份，不能拿配对端口代替。输入命令成功表示已派发；新截图或完成的文件才能验证任务结果。

操作的是手机现有屏幕，实体触摸和其他调试工具仍可影响画面。
Unicode 粘贴明确修改手机剪贴板，不读取或同步电脑剪贴板。
手机播放声音需要在手机确认系统共享提示，并遵守应用的录音限制；手机麦克风是独立来源，不提供向应用注入电脑麦克风的功能。
音频默认关闭，重连不会恢复录音。临时组件仅部署到已授权手机，无需 Root 或更换输入法。

结束会话

关闭手机音频并断开。已完成的文件和用户安装的应用保留在手机上。

rdp-cli audio android --session SESSION --source off
rdp-cli disconnect --session SESSION

功能 · 命令参考