讓 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

功能 · 命令參考