원문 zhongerxin/iPhone-use (README는 중국어가 기본, raw는 README.en.md) 저장소 메타(2026-10-10 gh 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-deviceUSB 통신, 포트 포워딩(기본 18100), 화면 스트림
MCP 서버 iphone_usePython 표준 라이브러리만으로 동작. 모델용 도구 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를 열지 않았거나 웹 인증이 번거로운 플랫폼은 앞으로 이 방식으로 다루겠다고 했다.

관련