Phone Harness(phone-harness) — 탈옥·앱 설치 없이 AI 에이전트가 실제 아이폰·안드로이드 조종하는 법
MIT 오픈소스 Phone Harness v0.3.3으로 Claude Code·Codex가 Mac iPhone Mirroring과 Android ADB를 통해 실제 스마트폰을 제어하는 원리, 설치, 클라우드·MCP 한계를 정리했습니다.


Q. Claude Code나 Codex 같은 코딩 에이전트가 내 실제 아이폰이나 안드로이드를 직접 조작할 수 있나요? 네. 오픈소스 **Phone Harness(
phone-harness/phone-harness)**를 쓰면 탈옥이나 Xcode 설정, 스마트폰 내 별도 앱 설치 없이도 에이전트가 화면을 읽고 탭·스크롤·타이핑을 수행할 수 있습니다. 아이폰은 Mac의 iPhone Mirroring 창을, 안드로이드는 ADB 연결을 활용합니다.
⚠️ 정확도 가드레일: 이 글은 2026년 11월 22일 기준
phone-harness/phone-harness공식 GitHub 저장소(Stars 5,444 · Forks 565 · MIT 라이선스)와 최신 릴리즈0.3.3(2026-11-02) 문서를 직접 열어 확인한 내용입니다. 클라우드 폰 요금($20 플랜·예약 보증금)과 MCP 지원 범위는 서비스 업데이트에 따라 달라질 수 있습니다.
30초 요약
- 탈옥·앱 설치 불필요: 스마트폰에 별도 에이전트 앱을 깔지 않고, Mac iPhone Mirroring(iOS) 또는 ADB(Android)로 제어합니다.
- 통일된 Python 헬퍼:
open_app(),tap_text(),type_text(),screen()같은 동일한 인터페이스로 로컬·클라우드 기기를 모두 다룹니다. - 에이전트 광범위 연동: Claude Code, OpenAI Codex CLI, Hermes Agent, OpenClaw와 클라우드 전용 MCP(
https://mcp.phone-harness.com/mcp)를 지원합니다. - 명확한 한계: Face ID·카메라·멀티터치는 불가하며, DRM 영상은 검은 화면으로 보입니다. 실제 기기 제어 권한을 넘기므로 보안 범위 설정이 필수입니다.
Phone Harness란 무엇인가
Phone Harness는 AI 코딩 에이전트에게 실제 스마트폰의 눈과 손 역할을 붙여 주는 오픈소스 CLI·자동화 하네스입니다. 2026년 8월 공개된 이후 빠르게 성장해 11월 22일 기준 GitHub 스타 5,444개, 포크 565개를 기록했으며 MIT 라이선스로 배포됩니다.
기존 모바일 자동화 도구(Appium, XCTest 등)는 Xcode 프로젝트 구성이나 기기별 테스트 러너 설치가 번거로웠습니다. 반면 Phone Harness는 개발자가 이미 쓰고 있는 Mac의 iPhone Mirroring 또는 Android ADB를 그대로 감싸, 에이전트가 tap_text("Weather")처럼 직관적인 Python 헬퍼 호출만으로 앱을 열고 화면을 읽게 설계되었습니다.
Q. 스마트폰에 아무 앱도 설치하지 않고 어떻게 화면을 읽고 터치하나요? iPhone은 macOS 15+의 기본 기능인 iPhone Mirroring 창을 캡처해 Apple Vision OCR로 텍스트를 읽고 macOS 접근성(Accessibility) 입력 이벤트를 보냅니다. Android는 USB 또는 Wi-Fi ADB로 스크린샷과 접근성 트리(Accessibility Tree)를 읽어 입력을 전달합니다.

플랫폼별 요구사항과 동작 방식
로컬 기기와 클라우드 기기 모두 동일한 Python 헬퍼(helpers.py) 뒤에서 동작하므로 한 번 짠 스크립트를 환경만 바꿔 재사용할 수 있습니다.
| 구분 | 필요 환경 및 조건 | 화면 인식 방식 | 입력 전달 방식 | 주요 제약 |
|---|---|---|---|---|
| 로컬 iPhone | macOS 15+, iOS 18+, iPhone Mirroring 페어링, 접근성·화면녹화 권한 | Apple Vision OCR | macOS 입력 이벤트 | 잠금 해제 시 미러링 일시 중단 |
| 로컬 Android | macOS·Linux·Windows, ADB 및 USB 디버깅 | 접근성 트리 + 스크린샷 | USB/Wi-Fi ADB input | PIN 잠금 해제는 사용자 필요 |
| Cloud Android | Phone Harness Cloud 계정 + ADB ($20 플랜) | 접근성 트리 + 브라우저 뷰 | 호스팅 ADB | 임시 세션 또는 저장 기기 선택 |
| Cloud iPhone | Phone Harness Cloud 예약 ($20 환불 보증금 + 월/연 플랜) | 실시간 브라우저 뷰 | HTTPS 원격 명령 | 대기자 큐 순서대로 할당 |
특히 최신 0.3.3 릴리즈 이후에는 원격 MCP 서버(https://mcp.phone-harness.com/mcp)가 추가되어 로컬에 장비를 꽂지 않고도 클라우드 Android·iPhone을 MCP 클라이언트에 바로 연결할 수 있습니다. (단, 공식 문서상 해당 MCP 엔드포인트는 현재 클라우드 기기 전용으로 안내됩니다.)
설치 및 코딩 에이전트 연동 순서
설치는 Python 3.12 기반 uv 환경에서 에이전트에게 공식 셋업 프롬프트를 넘기거나 CLI를 직접 실행하면 됩니다.
- CLI 설치 및 스킬 등록:
uv로 Python 3.12 환경에phone-harness를 설치한 뒤phone-harness skill로 에이전트 스킬을 등록합니다. - 환경 진단:
phone-harness doctor를 실행하면 macOS 권한(접근성·화면 녹화)이나 ADB 연결 상태를 자동으로 점검합니다. - 에이전트 실행: Claude Code나 Codex CLI에서 작업을 지시하면 에이전트가
~/.phone-harness/agent-workspace에 헬퍼 스크립트를 만들어가며 화면을 탐색합니다.
phone-harness <<'PY'
open_app("Notes")
tap_text("New Note")
type_text("hello from the harness")
print([o["text"] for o in screen()][:10])
PY
에이전트가 웹 브라우저 대신 모바일 앱을 다뤄야 하는 실무 테스트나 QA에서는 CodeGraph MCP 가이드나 AFFiNE 로컬 워크스페이스 정리처럼 로컬 컨텍스트 도구와 함께 묶어 쓰면 개발·검증 루프가 훨씬 짧아집니다.

도입 전 반드시 확인할 한계와 보안 주의점
편리함만큼 실제 내 폰의 화면과 입력 권한을 AI에게 여는 도구이므로, 물리적·보안적 경계를 먼저 정해야 합니다.
- OCR의 한계: Apple Vision OCR은 텍스트 위주로 화면을 파악하므로, 텍스트 라벨이 없는 아이콘 버튼은 스크린샷을 찍어 비전 지원 모델에게 좌표를 판단시켜야 합니다.
- 민감 흐름 미지원: 멀티터치 제스처, 카메라 촬영, Face ID 인증 흐름은 자동화할 수 없으며, 넷플릭스 등 DRM 보호 영상은 보안상 검은 화면으로 캡처됩니다.
- 권한 격리 권장: 개인 금융·메신저 앱이 깔린 주력 폰에 에이전트를 바로 붙이기보다, 테스트용 서브 기기나 Phone Harness Cloud의 격리된 Android 세션을 우선 쓰는 편이 안전합니다.
토리스의 판단
실제 모바일 앱 QA나 2FA·앱 전용 플로우 자동화가 필요한 1인 개발자라면 가장 먼저 시험해 볼 만한 도구입니다. 다만 개인 메인 폰에 바로 연결해 자율 실행을 맡기면 의도치 않은 메시지 발송이나 결제 탭 위험이 있으므로, 로컬에서는 테스트 전용 안드로이드 기기나 별도 계정으로 시작하고, 다중 기기·상시 실행이 필요하다면 클라우드 세션을 검토하는 편이 좋습니다. 더 자세한 자동화 구축 문의는 토리스 서비스 안내에서도 확인할 수 있습니다.
출처
광고
YOUTUBE · TORIS STUDIO