Waydroid

에이전트가 안드로이드 화면을 그림이 아니라 좌표 붙은 텍스트로 읽고 조작하게 해주는 MCP 서버 겸 CLI. 조작을 녹화해 매크로로 만들고, 매크로가 어긋날 때만 에이전트를 부른다.

왜

에이전트로 안드로이드를 조작할 때 병목은 adb가 아니다. 실측하면 adb 왕복은 0.01초다. 진짜 비용은 에이전트가 큰 스크린샷을 읽고 "버튼이 저기쯤"이라고 추정하는 시간이다.

UI 계층을 탭가능 목록으로 압축하면 홈 화면 한 장이 191바이트가 된다. 같은 화면의 이미지가 69KB이니 1/350이고, 좌표는 추정이 아니라 조회 결과다.

이전:  [1920x1056 이미지]        → 눈으로 훑고 좌표 추정
이후:  [1] 설정 (960,1260) ...   → 즉시 선택

무엇을 하나

툴	하는 일
screen	탭가능 목록. 트리를 못 읽으면 축소 이미지로 폴백
tap	라벨 또는 좌표로 탭하고 바뀐 화면을 함께 반환
swipe / send	스와이프, 문자·키 입력
record	start~`stop` 사이의 조작을 매크로 스크립트로 생성
device	세션 제어와 진단

tap이 결과 화면을 함께 주므로 왕복이 절반이 된다. 헛짚은 탭도 즉시 드러난다.

MCP와 CLI가 같은 코어를 쓴다. 매크로 셸은 CLI를 부르므로 녹화한 대로 재생된다. 구현을 나누면 "녹화한 대로 재생되지 않는" 버그가 나는데, 그건 원인 찾기가 최악이다.

설치

python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/waydroid-mcp bootstrap      # adb 키 상태 확인과 필요한 명령 출력
.venv/bin/waydroid-mcp session start  # gamescope 작은 창으로 Waydroid 기동
.venv/bin/waydroid-mcp screen

adb로 붙으므로 Waydroid 전용이 아니다. 실기기나 다른 에뮬레이터에도 screen/tap은 그대로 쓸 수 있다. Waydroid에 한정되는 것은 세션 제어와 adb 키 부트스트랩뿐이다.

Waydroid를 쓸 때 알아둘 것

• 창이 없으면 컨테이너가 동결되고 adb 호출이 에러 없이 멈춘다. 세션만 띄우지 말고 창까지 띄운다. 이 경우 툴이 frozen으로 사유를 알려준다
• Waydroid에는 adb 승인 팝업이 없다. 호스트 공개키를 컨테이너에 직접 넣어야 하고, sudo가 필요한 것은 그 한 번뿐이다
• gamescope를 중첩해 안드로이드는 1280x720으로 렌더하고 창만 작게 띄운다. 화면 인식 도구는 내부 해상도를 보므로 창을 줄여도 인식이 깨지지 않는다

매크로

조작을 녹화하면 이런 스크립트가 나온다. 기대 화면 검증문이 공짜로 따라온다 — 실제로 그 화면에서 눌러 성공했다는 사실이 근거다.

step 1 expect "카메라"
wm-tap '카메라'

step 2
wm-key HOME

finish

export WM_BIN=/path/to/waydroid-mcp MACRO_REPORT=$PWD/report.txt
bash rec.sh; echo $?

종료 코드로 사유가 구분된다.

코드	뜻	대응
0	정상
2	타임아웃	기다리던 화면이 안 나옴
3	기대 화면 불일치	팝업 등 다른 화면 — 처리하고 복귀
4	디바이스 이상	동결·연결 끊김
5	진행 없음	눌러도 반응 없음 — 반복해도 소용없다

3과 5를 나누는 것이 중요하다. 3은 다른 화면을 처리하고 돌아오면 되지만, 5는 눌러도 반응이 없으니 같은 조작을 반복해봐야 소용없다.

실패하면 보고 파일에 단계·기대·실제 화면이 남는다. 에이전트는 이 파일만 읽고 판단하므로 화면을 다시 뜨는 왕복이 필요 없다.

단계: 1
사유: 기대 화면 불일치 (코드 3)
기대: 카메라
--- 실제 화면 ---
[1] 옵션 (1035,41)
[2] 셔터 (1178,333)

이렇게 해서 에이전트는 조작의 주체가 아니라 예외 처리자가 된다. 정상 구간에서는 토큰을 쓰지 않는다.

캔버스 앱 검증 — 화면 지문

게임처럼 캔버스로 그리는 앱은 UI 트리가 비어서 라벨로 검증할 수 없다. 그렇다고 좌표만 나열하면 한 번 어긋난 뒤 끝까지 엉뚱한 곳을 누른다.

그래서 화면을 성긴 격자(8x5)로 줄여 칸별 평균 밝기를 지문으로 쓴다.

waydroid-mcp fingerprint                  # 지금 화면의 지문
waydroid-mcp expect-screen <지문>          # 그 화면인가? 아니면 종료 3

녹화 시 라벨이 없는 단계에는 이 지문이 자동으로 붙는다.

step 3 expect-screen 6a97cacaad909093...
wm-tap '640,400'

정확한 해시가 아니라 평균 + 허용오차인 것이 요점이다. 애니메이션과 안티에일리어싱 때문에 같은 화면도 픽셀은 매번 다르다. 실측에서 같은 홈 화면은 40/40칸 일치, 카메라 화면은 0/40으로 갈렸다.

조절 손잡이:

인자	뜻
--tol	칸별 밝기 허용오차(기본 14). 키우면 관대해진다
--min-match	일치해야 할 칸 비율(기본 0.85)

부분만 바뀌는 화면(팝업 하나 뜬 정도)은 --min-match를 낮춰야 통과한다. 반대로 비슷한 화면을 구분해야 하면 올린다. 환경마다 다르니 실제로 재보고 잡는다.

개발

python3 -m pytest tests/ -q    # 전부 가짜 adb로 돈다. 실기기 불필요

실기기 확인은 docs/manual-verification.md.

한계

• input tap 한 번에 0.6초, uiautomator dump는 1.6초가 든다. 전자는 매번 JVM을 띄우는 비용이고, monkey 네트워크 모드(포트 바인딩 실패)와 /dev/input 직접 쓰기(evdev가 아님)로는 우회할 수 없었다. 더 줄이려면 안드로이드 안에 상주 프로세스가 필요하다
• 캔버스로 그리는 앱(게임, 일부 Flutter)은 UI 트리가 비어서 이미지로 폴백한다. 구조적 한계라 없앨 수 없다
• uiautomator dump는 같은 앱에서도 성공과 실패를 오간다. 일시적 실패라 재시도로 넘기고, 끝까지 안 되면 이미지 폴백으로 떨어진다. 조용히 옛 화면을 주는 일은 없다

다른 접근성 서비스와 같이 쓰기 (중요)

uiautomator dump는 다른 접근성 서비스의 바인딩을 약 0.8초 끊는다. 실측했다 — 덤프 도중 상대 서비스의 바인딩이 0으로 떨어지고 곧 다시 붙는다. 상대 앱은 "접근성 서비스가 중지되었습니다" 같은 알림을 띄우고, 스크립트가 돌고 있었다면 깨질 수 있다.

프로세스 자체는 죽지 않고 설정도 유지되지만, 끊겼다 붙는 것만으로 자동화 도구에는 치명적이다.

해결: 트리 조회를 끈다

waydroid-mcp --no-tree screen        # 또는 WM_NO_TREE=1

--no-tree면 uiautomator를 아예 부르지 않는다. 실측에서 상대 바인딩이 25회 관측 내내 유지됐다.

잃는 것이 거의 없다. 접근성 자동화가 붙는 대상은 대개 게임 같은 캔버스 앱이고, 그런 앱은 트리가 애초에 비어 있다. 덤프해서 얻는 것 없이 상대만 끊고 있었던 셈이다.

이 모드에서는:

	동작
screen	축소 이미지
tap "x,y"	그대로 동작 (input 명령은 접근성과 무관)
tap "라벨"	좌표로 지정하라는 오류

정리하면 트리가 필요한 화면과 접근성 도구가 도는 화면은 대개 겹치지 않는다. 겹칠 때는 트리를 포기하는 쪽이 맞다.