원문 zhongerxin/iPhone-use (README는 중국어가 기본, raw는
README.en.md) 저장소 메타(2026-10-10gh api확인): MIT, Python, 2026-10-06 생성, Stars 약 2,000, 최신 릴리스v0.3.8(2026-10-09). 같은 작성자의 cowart도 Codex 플러그인이다.
한 줄 요약
Codex에게 “메모 앱 열고 이 초안 써 둬”처럼 자연어로 시키면 USB로 연결된 실제 iPhone을 조작한다. 폰 쪽 실행은 Appium의 WebDriverAgent(WDA)가 맡고, iPhone Use는 그 위에 로컬 MCP 서버, 설치·사용 스킬, 사이드바 화면 위젯을 더한다. 탈옥이나 별도 Appium Server는 필요 없다.
구성
| 층 | 역할 |
|---|---|
| WDA Runner(폰) | 사용자 본인의 Apple 개발 팀으로 서명해 설치하는 온디바이스 자동화 서비스. 고정된 WDA 16.14.0 커밋을 쓴다 |
| appium-ios-device | USB 통신, 포트 포워딩(기본 18100), 화면 스트림 |
MCP 서버 iphone_use | Python 표준 라이브러리만으로 동작. 모델용 도구 17개 + 위젯 전용 2개 |
| 스킬 | iphone-use-setup(진단→기기 탐색→서명→빌드→기동), iphone-use(사용법) |
| 화면 위젯 | iPhone 프레임에 실시간 화면과 탭·드래그 표시. 사용자용이고, 모델 판단은 도구 관찰값만 쓴다 |
도구는 모두 pua_ 접두어다. 진단·준비(pua_doctor/pua_setup/pua_ready), 관찰(pua_observe/pua_find), 조작(pua_tap/pua_swipe/pua_type_text 등), 복합 동작(pua_batch/pua_scroll_find/pua_collect_list)으로 나뉜다. 폰 작업은 pua_ready가 ready=true를 돌려준 뒤에만 시작한다.
설계에서 볼 점
- 설치도 에이전트에게 맡긴다: README 첫머리에 Codex에 붙여 넣을 설치 프롬프트가 있다. Apple 계정 로그인, 기기 신뢰, 개발자 모드, 잠금 해제처럼 사람만 할 수 있는 단계는 “정확한 절차를 설명하고 기다리라”고 지시한다. 작성자의 기기 ID·서명 설정을 재사용하지 말라는 문장도 들어 있다.
- 접근성 트리 우선, 스크린샷 폴백: 압축한 접근성 트리로 화면을 읽고, 대상이 가려지거나 트리에 없으면 새 스크린샷을 보게 한다. 픽셀 좌표에
image.pixel_to_point를 곱해 포인트 좌표로pua_tap한다. mobile-mcp와 같은 전략이다. - 왕복 줄이기: 알려진 동작은
pua_batch한 번으로 묶고, 목록은 겹치게 스크롤하며 중복을 제거하고 수집 범위를 명시한다. 스크롤 검색은 호출당 최대 한 번만 스와이프한다. - 보수적 실패 처리: 텍스트 입력과 제출은 분리돼 기본으로 제출하지 않는다. 결과가 불확실한 변경은 실제 상태를 다시 읽은 뒤에만 재시도하고, 자동 동작 재실행은 하지 않는다. 비밀번호·인증 코드·Face ID는 사용자가 처리하고, 그동안 미리보기를 멈출 수 있다.
- 로컬 한정: WDA는 루프백 포워더로만 접근하고 원격
WDA_URL은 거부한다. 런타임 디렉터리는 700, 설정·이미지는 600 권한이며 화면 스트림은 디스크에 저장하지 않는다.
요구 사항과 주의
- macOS + Codex 데스크톱/CLI, 전체 Xcode(Command Line Tools만으로는 부족), Apple 개발 팀, USB로 연결한 실기기, Python 3.9+, Node.js 20.19+/22.12+/24+.
- 익명 사용 통계가 기본 켜짐: 자체 PostHog 프로젝트로 시작·도구 호출·연결 결과·소요 시간·오류 범주를 보낸다. 화면 이미지·입력 텍스트·기기 식별자는 보내지 않는다고 한다.
IPHONE_USE_ANALYTICS=0또는DO_NOT_TRACK=1로 끈다. - README에는 “저장소가 현재 비공개”라는 문장이 남아 있지만 2026-10-10에는 공개 상태다(문서가 공개 전 문구를 유지한 것으로 보인다).
X 반응
@Pluvio9yte(중국어, 2026-10-10)는 “Codex가 Mac의 iPhone 미러링으로 iPhone을 조작하면 너무 느렸는데, 이 오픈소스가 그 문제를 바로 해결했다”며 소개했다. 미러링 화면을 거치지 않고 WDA로 실기기를 직접 다룬다는 점이 체감 속도 차이로 받아들여진 셈이다.
@xxm459259(중국어, 2026-10-11)는 iPhone Use로 집에 있는 안 쓰는 물건을 중고 거래 앱 셴위(闲鱼)에 올려 실제로 팔았다.^[raw/articles/twitter-web-exporter/x-2109311597466530109.md] 에이전트가 한 일은 ① 앨범에서 해당 사진을 찾아 적당히 모자이크하고 방향을 바로잡기 ② 셴위에서 비슷한 상품을 검색해 적정 가격 조사 ③ 문구를 써서 등록 ④ 구매자 메시지에 답하고 거래 분쟁 이력이 없는 구매자를 골라 거래 완료 ⑤ 알리페이 회원 혜택에서 차이냐오 배송 쿠폰을 받아 택배 접수까지다. 세부는 대부분 본인이 명확히 지시했지만, 이 스킬은 다음에도 쓸 수 있어 MCP를 열지 않았거나 웹 인증이 번거로운 플랫폼은 앞으로 이 방식으로 다루겠다고 했다.
관련
- 2026-10-02-github-mobile-next-mobile-mcp — 클라이언트 무관 MCP로 iOS·Android를 모두 다루고, WDA 의존을 걷어낸 쪽
- 2026-04-04-agent-device-mobile-cli — iOS/Android 디바이스 제어 CLI
- 2026-11-14-github-phone-harness-phone-harness — WDA 대신 macOS iPhone 미러링 창 + Vision OCR로 실제 iPhone을 조작하는 CLI
- 2026-10-10-github-mobai-app-mobai-dev — 같은 문제를 원격 샌드박스 쪽에서 푼 도구(CI 빌드 + tailnet 실기기)
- computer-use-agent-landscape — 에이전트가 화면을 보고 조작하는 도구 전반
- moc-mobile-ai