탈옥도, Xcode도, 폰에 설치할 앱도 없이 에이전트에게 내 폰을 쥐여 주는 도구. 에이전트는 짧은 Python 스크립트를 써서 screen()으로 화면 글자를 읽고 tap_text()로 누른다. 같은 회사의 클라우드 MCP 서버(2026-11-03-github-phone-harness-mcp)의 본체이며, 기본으로 켜진 텔레메트리가 스크립트와 출력까지 보낸다는 점을 알고 써야 한다.

개요

Shawn Pana가 만든 Python CLI다. MIT 라이선스이고 패키지는 phone-harness 0.3.3(Alpha)이다. 2026-11-14 수집 기준 ★4,980, 포크 516이다. 2026-08-07에 생성됐고 열린 이슈 28개와 PR 70개가 있다. 0.3.3(2026-11-02)에서 저장소가 ShawnPana/phone-harness에서 phone-harness 조직으로 옮겨졌다. 같은 릴리스에서 MCP 서버, openclaw 통합, Discord 서버도 발표됐다.

폰 네 종류를 같은 헬퍼로 다룬다. 그래서 한 폰에서 쓴 스크립트가 다른 폰에서도 돈다.

폰연결 방식화면 읽기입력
내 iPhonemacOS 15+의 iPhone 미러링 창(iOS 18+ 페어링)스크린샷 + Apple Vision OCR미러링 창에 보내는 HID 수준 이벤트
책상 위 Androidadb(USB 또는 Wi-Fi), macOS·Linux·Windows접근성 트리(Mac에서는 OCR 보조)adb input
클라우드 AndroidPhone Harness Cloud에 adb로 접속접근성 트리adb input
클라우드 iPhoneHTTPS API, 모든 OS서버 쪽 OCRHTTPS 명령

사용 방식

에이전트는 heredoc으로 스크립트를 넘긴다. 헬퍼는 미리 import되어 있다.

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
  • 설치는 에이전트에게 맡긴다. README의 설정 프롬프트를 에이전트에게 보내면 uv로 설치하고 스킬을 등록한 뒤 onboarding.md대로 안내한다. 사람이 할 일은 미러링 페어링, 손쉬운 사용·화면 기록 권한 허용, USB 디버깅 켜기 같은 물리적 단계뿐이다. phone-harness doctor로 준비 상태를 점검한다.
  • 헬퍼는 30여 개다. screen()은 보이는 글자를 탭 가능한 좌표와 함께 {text, confidence, x, y, w, h} 목록으로 돌려준다. tap_text, wait_for_text, scroll_until, scroll_collect(목록을 끝까지 넘기며 중복 제거) 등이 그 위에 있다. open_url, push_file은 클라우드 폰 전용이다.
  • SKILL.md가 작업 규칙을 정한다. 스크린샷보다 screen()으로 읽고, 동작 전에 무엇이 바뀌어야 하는지 정한 뒤 한 번에 하나씩 확인하라고 한다. 확인된 순서만 한 스크립트로 묶는다. 보내기·게시·구매·삭제·설정 변경 전에는 사용자에게 묻고, PIN·비밀번호·2FA 코드는 절대 입력하지 않는다. 사용자가 “내 폰”이라고 하면 클라우드 폰이 아니라 개인 폰을 뜻한다고 못 박는다.
  • 에이전트가 배운 것은 작업 공간에 남긴다. ~/.phone-harness/agent-workspace/agent_helpers.py에 자기 헬퍼를 저장하고, 업그레이드해도 지워지지 않는다.

연동

  • MCP: https://mcp.phone-harness.com/mcp. 클라우드 폰만 지원한다. 자세한 내용은 2026-11-03-github-phone-harness-mcp.
  • hermes-agent 플러그인: hermes plugins install phone-harness/phone-harness/integrations/hermes. 도구는 phone_exec 하나이고, 모델이 쓴 스크립트를 기본적으로 실행 전마다 승인받는다(한 번 답으로 세션 전체나 항상 허용도 가능). 휴리스틱 분류기가 “폰만 건드리는 스크립트”를 자동 실행하게 할 수 있지만 기본은 꺼져 있다. README도 우회될 수 있다고 적는다.
  • openclaw 플러그인: openclaw plugins install clawhub:phone-harness(OpenClaw 2026.10.9+). 승인 프롬프트에 스크립트 전체를 보여 준다. 프롬프트 한도가 512자라 500자가 넘는 스크립트는 아예 승인 대상에 오르지 않는다. 소유자만 폰을 조작할 수 있고, 샌드박스 세션과 messaging·minimal 프로필에는 도구가 없다. 스크립트 환경에서는 API 키·토큰 같은 이름의 변수를 뺀다.

클라우드와 비용

로컬 폰은 무료다. 클라우드 Android는 분당 5센트(신규 계정 80부터인 정액 구독이다. 요금표는 2026-11-03-github-phone-harness-mcp의 비용 구조와 같다. README는 클라우드 폰을 “stealth, real numbers, 2FA, unlimited devices”로 홍보한다. 온보딩은 사용자 폰으로 데모를 마친 뒤 클라우드 Android를 한 번 권하라고 지시한다. 데모는 phone-harness.com을 폰에서 열고, 사용자가 동의하면 GitHub 별을 대신 눌러 주는 것이다.

텔레메트리 — 기본으로 켜져 있다

소스(커밋 4bebff1)를 읽은 결과이며 실제로 실행해 보지는 않았다.

  • 설정을 건드리지 않으면 켜져 있다. 예외는 Hermes 아래에서 돌 때(옵트인)와 설정 파일을 읽을 수 없을 때다. 끄려면 phone-harness config set telemetry false, DO_NOT_TRACK=1, 또는 한 번만 PHONE_HARNESS_TELEMETRY=0.
  • 실행 한 번마다 PostHog로 이벤트 하나를 보낸다. 담기는 것은 스크립트 전문(최대 2만 자), 표준 출력의 끝부분(최대 2만 자), 헬퍼 호출과 그 인자(호출당 300자), 오류, 소요 시간이다. 에이전트 종류(Claude Code, Codex, Cursor 등을 환경 변수로 감지), OS·기기 정보, 설치 ID도 들어간다. 클라우드에 로그인하면 계정 ID와 세션 ID가 붙는다. cloud 명령의 출력만 제외된다.
  • 그래서 print(screen())으로 읽은 메시지·알림 글자나 type_text("...")로 입력한 문장이 그대로 전송될 수 있다. 확인한 문서 중에서는 install.md가 “usage telemetry”라고만 적고, 메인 README와 SKILL.md에는 언급이 없다. 무엇이 나가는지는 Hermes·OpenClaw 통합 README에만 적혀 있었다.

평가와 주의점

  • 근거는 문서와 소스 발췌뿐이다. 설치·실행하지 않았으므로 iPhone 미러링 경로의 속도·정확도는 확인하지 않았다. 실행하면 텔레메트리가 이 기기에서 나가므로 먼저 끄는 것이 순서다.
  • 로컬 iPhone 경로의 차별점은 Mac만 있으면 된다는 것이다. 2026-10-10-github-zhongerxin-iphone-use처럼 WebDriverAgent를 빌드하지 않고 macOS 기본 미러링 창을 쓴다. 대가로 접근성 트리가 없어 OCR이 글자만 본다. 라벨 없는 아이콘은 스크린샷과 비전 모델이 필요하다. 반면 2026-10-02-github-mobile-next-mobile-mcp는 시뮬레이터·실기기 접근성 트리를 쓴다.
  • README가 밝힌 한계: iPhone 잠금을 풀면 미러링이 멈추고, PIN으로 잠긴 Android는 사람이 풀어야 한다. 멀티터치, 카메라·Face ID 흐름은 안 되고 DRM 영상은 검게 나온다.
  • 진짜 계정이 걸린 폰을 넘기는 일이다. 동의 규칙은 SKILL.md의 지시일 뿐 기술적 차단이 아니다. 승인 게이트는 Hermes·OpenClaw 플러그인에만 있다. Claude Code에서 셸로 돌리면 에이전트 자체의 권한 설정이 유일한 문이다.
  • 0.x Alpha이고 열린 PR이 70개라 인터페이스가 자주 바뀔 수 있다.

관련 노트