AI 에이전트로 USB 또는 Wi-Fi Android 휴대전화 제어하기

Android 12 이상에서 실제 화면을 캡처하고 텍스트와 파일을 다루며 같은 rdp-cli 세션에서 제어를 이어받는 방법입니다.

지원 기준은 Android 12 이상입니다. 실기기 검증 대상은 Android 12를 실행하는 Google Pixel 3이며, 모든 제조사나 이후 Android 버전을 검증했다는 뜻은 아닙니다.

휴대폰 준비

개발자 옵션과 USB 디버깅을 켜고 데이터 케이블을 연결한 다음, 잠금을 해제한 휴대폰에서 디버깅을 허용하세요.
Wi-Fi에서는 무선 디버깅을 켜고 휴대폰에 표시된 페어링 코드와 포트를 사용하세요. 연결 포트는 별도이며 USB 케이블은 필요하지 않습니다.
Windows USB 연결에는 휴대전화와 호스트 CPU 아키텍처에 맞는 WinUSB 드라이버가 필요하며 ARM64도 마찬가지입니다. rdp-cli는 드라이버를 자동 설치하거나 다른 디버깅 도구를 종료하지 않습니다. Linux (x86_64 / ARM64)에서는 적절한 udev 규칙 또는 장치 그룹으로 일반 사용자에게 휴대전화 USB 장치 접근 권한을 부여한 뒤 아래 명령을 Bash에서 실행하세요. rdp-cli를 실행할 때 sudo를 사용하지 마세요. macOS는 시스템 USB 인터페이스를 사용합니다.

DEVICE_SERIAL, SESSION, OBSERVATION, PHONE_IP 및 두 포트를 실제 값으로 바꾸세요. connect의 data.session과 매 스크린샷의 data.observation을 사용합니다. wifi:PHONE_GUID는 반환된 wifi: 기기 ID로 바꾸세요. PHONE_REF에는 이 컴퓨터에 페어링 정보를 저장할 이름을 정합니다. 입력 안내가 나오면 현재의 6자리 코드를 입력하세요. 명령이 표준 입력으로 전달합니다.

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를 만드세요. 업로드의 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을 저장하고 입력 전에 화면을 다시 캡처하세요.

Wi-Fi에서는 무선 디버깅을 켜고 휴대폰에 표시된 페어링 코드와 포트를 사용하세요. 연결 포트는 별도이며 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

사용자와 에이전트의 세션 공유

명령, 네이티브 창, 승인된 브라우저가 하나의 지속 세션을 공유합니다. 필요할 때 일시 중지하거나 제어권을 가져오세요.

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

기능 · 명령어 참조