API가 없는 앱은 AI 에이전트가 손대기 어렵습니다. 코드로 부를 문이 없으니까요. Phone Harness는 이 문제를 사람처럼 풉니다. 화면을 보고, 글자를 읽고, 그 자리를 누릅니다.
이번에 맥에 Phone Harness를 깔고 Claude Code에게 아이폰을 맡겨 봤습니다. 설치하다 막힌 곳을 Claude Code가 직접 고쳤고, 앱 두 개를 오가며 정보를 표로 모았고, 막혔던 요령을 코드로 저장해 다음 실행에 다시 썼습니다.
이 글에서는 다음을 차례로 봅니다.
- Phone Harness는 무엇이고, 어떻게 동작하나
- 쓰기 전에: 텔레메트리 끄기, 민감한 화면 맡기지 않기
- 설치하다 막힌 점검을 직접 고친 과정
- 앱 두 개를 오가며 일 시키기
- 스스로 배우는 원리:
agent_helpers.py - 한계
숫자 읽는 법. [공식 문서] 는 Phone Harness 저장소·Anthropic이 직접 낸 자료, [직접 측정] 은 저희가 2026년 11월 3일 녹화에서 직접 돌려 본 결과입니다. 앱 화면에 나온 시세는 녹화 시점의 값일 뿐이고, 투자 판단의 근거가 아닙니다.
1. Phone Harness는 무엇인가
Phone Harness는 "에이전트가 휴대폰을 조작하게 해 주는" 오픈소스 도구입니다. MIT 라이선스이고, 저장소는 2026년 8월에 만들어졌습니다. 녹화 때 깃허브 별이 4천 개를 넘었고, 이 글을 쓰는 11월 16일에는 5천 개를 넘었습니다 [공식 문서] (phone-harness/phone-harness). 녹화에 쓴 버전은 11월 2일에 나온 0.3.3입니다 (릴리스).
아이폰에서는 이렇게 동작합니다 [공식 문서].
- 맥의 iPhone 미러링 앱으로 아이폰 화면을 맥에 띄웁니다. macOS 15 이상, iOS 18 이상이 필요합니다.
- 그 창을 찍습니다.
- 찍은 화면에서 글자를 읽습니다. 이것을 OCR(Optical Character Recognition, 글자 인식) 이라고 하고, 애플의 Vision OCR을 씁니다.
- 누를 글자를 찾으면 그 좌표에 탭·스와이프·입력 신호를 보냅니다.
미리 녹화한 매크로가 아닙니다. 매번 화면을 보고 다음 동작을 정합니다. 안드로이드는 adb로 같은 일을 하고, 같은 함수로 두 폰을 다 다룹니다.
2. 쓰기 전에 꼭 할 것
텔레메트리부터 끄기
텔레메트리(telemetry) 는 사용 기록을 개발사 서버로 보내는 기능입니다. Phone Harness 소스 코드 첫 줄에 opt-out 이라고 적혀 있습니다. 기본으로 켜져 있고, 직접 꺼야 꺼진다는 뜻입니다 [공식 문서] (telemetry.py).
코드를 열어 보면 실행할 때마다 보내는 항목에 에이전트가 넘긴 작업 내용(task, 최대 2만 자)과 출력(output)이 들어 있습니다. 화면에서 읽은 글자를 출력했다면 그 글자도 같이 갈 수 있다는 얘기입니다. 저희는 이걸 모르고 켜 둔 채 녹화했습니다.
설치하자마자 끄세요. 셋 중 하나면 됩니다 [공식 문서] (install.md).
phone-harness config set telemetry false
# 또는 환경 변수
export DO_NOT_TRACK=1
# 한 번만 끄려면 PHONE_HARNESS_TELEMETRY=0
민감한 화면은 맡기지 않기
이건 이 도구만의 이야기가 아닙니다. Claude Code는 모델과 대화하려고 프롬프트와 모델 출력을 네트워크로 보냅니다 [공식 문서] (Claude Code Data usage). 스크린샷이나 화면 글자도 대화의 일부라서 같이 갑니다. Codex를 쓰면 OpenAI로 갑니다. 내 컴퓨터에서 도는 로컬 모델이 아니라면 어느 도구든 같습니다.
그래서 계좌·비밀번호처럼 민감한 정보가 뜨는 앱은 맡기지 않는 게 좋습니다. 이번 시연에서는 거래를 하지 않았고 계좌 정보는 출력하지 말라고 했지만, 화면 자체는 모델이 봤을 수 있습니다.
에이전트가 앱을 대신 조작하는 건 앱마다 이용 약관에 어긋날 수 있습니다. 아래 앱들은 예시로 데모 녹화에만 썼습니다. 쓰시는 앱의 약관은 각자 확인해 주세요.
3. 설치하다 막힌 점검을 직접 고치기
설치는 공식 문서의 설정 프롬프트를 Claude Code에 그대로 붙여 넣으면 됩니다. 설치하고, 스킬을 등록하고, 설치 안내를 읽으라는 내용입니다. 0.3.3과 Claude Code용 스킬이 깔렸습니다 [직접 측정].
그런데 첫 점검(doctor)에서 막혔습니다. 화면은 멀쩡한데 결과는 계속 "세션 차단됨"이었습니다. Claude Code가 판정 코드를 직접 열어 원인을 찾았습니다 [직접 측정].
- 점검은 미러링 창 안에 맥 버튼이 있으면 "아이폰에 안내 창이 떠서 막혔다"고 판단합니다.
- 그런데 저희 맥 버전에서는 창 맨 위 툴바 버튼이 늘 잡혔습니다. 잡힌 버튼 다섯 개가 모두 창 위쪽 32픽셀, 제목 줄 안에 있었습니다.
- 그래서 정상인데도 막혔다고 본 것이었습니다.
Claude Code는 고칠 방법 세 가지를 냈고, 저희는 "설치된 패키지를 직접 고치기"를 골랐습니다. 미러링 창을 찾고, 찍고, 누르는 연결을 맡은 mirror.py에서 제목 줄 안의 버튼은 세지 않게 고쳤습니다. 다시 점검하니 아홉 항목이 모두 PASS였습니다. 업그레이드하면 이 수정이 사라진다는 주의도 남겼습니다 [직접 측정].
4. 앱 두 개를 오가며 일 시키기
첫 일은 이랬습니다. 그록(Grok) 봇 앱의 주식 데모 봇에게 "오늘 많이 오른 빅테크 종목 세 개"를 묻고, 1위 종목을 토스 증권에서 찾아 표로 정리하기. 조건은 "홈 탭, 내 주식, 구매하기는 절대 누르지 말 것"이었습니다.
가는 길에 세 번 막혔고, 그때마다 에이전트가 다른 방법을 찾았습니다 [직접 측정].
- 앱 열기가 검색창에서 멈춤. 스크린샷으로 확인한 뒤 보이는 앱 아이콘을 직접 눌렀습니다. 토스 때는 검색창에 이름을 직접 입력했습니다.
- 봇의 답. 마이크로소프트, 메타, 엔비디아 순이었고 1위는 2.74% 올랐다고 했습니다. 봇이 한 말이라 따로 검증하지는 않았습니다.
- 한글 줄을 못 읽음. 토스 검색 결과에서 OCR이 한글 줄을 읽지 못해, 스크린샷 좌표로 첫 결과를 눌렀습니다.
토스는 계좌 잔고가 보이는 홈 화면으로 열렸습니다. 영상에서는 가렸고, Claude Code도 계좌 정보는 출력하지 않고 증권 탭으로 넘어갔습니다.
녹화 시점(2026년 11월 3일) 토스 화면에서 읽은 값입니다 [직접 측정].
| 항목 | 값 |
|---|---|
| 정규장 종가 | $520.77 (+2.6%) |
| 1년 최저가 | $349.20 |
| 1년 최고가 | $551.15 |
Claude Code는 봇이 말한 값(+2.74%, $520.99)과 토스 값이 조금 다르다는 점, 출처와 집계 시점이 다를 수 있다는 점도 스스로 짚었습니다.
5. 스스로 배우는 원리: agent_helpers.py
이 도구가 화제가 된 이유는 따로 있습니다. 에이전트가 쓰다 막힌 요령을 agent_helpers.py라는 파일에 함수로 적어 두고, 다음 실행 때 그 함수를 바로 불러 씁니다. 모델이 학습하는 게 아니라, 자기가 쓰는 도구 코드를 늘려 가는 방식입니다.
오픈소스 코드로 확인한 흐름은 이렇습니다 [공식 문서].
- 스킬 문서(SKILL.md)에 "배운 것은
agent_helpers.py에 남기라"는 규칙이 있습니다. - 파일은
~/.phone-harness/agent-workspace에 저장됩니다. 설치 폴더 밖이라 업그레이드해도 지워지지 않습니다 (install.md). - 다음 실행 때
helpers.py가 시작하면서 이 파일을 자동으로 불러와, 안의 함수를 기본 명령 옆에 붙입니다 (helpers.py).
먼저 한글을 못 읽은 원인을 찾았습니다. 글자 인식이 영어로만 읽도록 되어 있었습니다. 이번에 Claude Code가 저장한 함수는 세 개입니다 [직접 측정].
screen_ko: 한국어와 영어를 같이 지정해 화면 글자를 읽습니다. 저장하고 바로 돌려 보니 기존 함수가 놓친 한글 라벨 여섯 개를 모두 잡았습니다.safe_tap: 누르기 전에 근처에 금지한 글자가 있으면 누르지 않고 멈춥니다. "구매하기" 같은 버튼을 코드로 막아 두는 셈입니다.open_app_spotlight: 손으로 앱을 열었던 순서를 그대로 옮긴 함수입니다. 저장할 때 "아직 실제로 써 보지 않았다"고 적어 뒀습니다.
다시 실행: 한 번 실패하고 고쳐 저장
정말 다음에 쓰는지 보려고 "그록 봇 앱을 다시 열어 달라"고만 했습니다 [직접 측정].
- 방금 저장한
open_app_spotlight를 처음으로 썼습니다. - 실패했습니다. 그록 대신 구글에서 "토스" 검색이 열렸는데, 함수는 성공이라고 했습니다. 리턴 키가 먹히지 않아 아까 남은 검색어가 그대로 검색된 것이었습니다.
- 리턴 없이 맨 위 결과의 앱 아이콘만 누르는 방식으로 바꾸자 열렸습니다. 이름이 같은 웹 검색 항목은 피했습니다.
- 성공한 방법대로 함수를 고쳐 다시 저장했고, 고친 함수로 그록 봇이 열리는 것까지 확인했습니다.
한 번 실패했지만 그 실패가 다시 도구 코드에 들어갔습니다. "쓸수록 나아진다"는 말이 이런 뜻입니다.
6. 한계
- 느립니다. 동작 하나에 몇 초씩 걸립니다 [직접 측정].
- 한글 화면에 약합니다. 기본 설정은 영어로만 읽어서, 이번에도 한글 라벨을 놓쳤습니다 [직접 측정].
- 글자만 봅니다. OCR은 아이콘을 못 봅니다. 글자 없는 버튼은 스크린샷과 이미지를 보는 모델이 필요합니다. 멀티터치, 카메라, Face ID 흐름도 안 됩니다 [공식 문서] (README Limits).
- 어느 화면으로 열릴지 모릅니다. 이번처럼 잔고 화면이 바로 뜰 수 있습니다.
- 고친 코드는 업그레이드하면 사라집니다. 설치 패키지를 직접 고쳤다면 업데이트 뒤 다시 확인해야 합니다.
agent_helpers.py는 남습니다. - 텔레메트리는 기본으로 켜져 있습니다. 위에서 본 대로 먼저 끄세요.
그래서 결제나 주문은 맡기지 말고, 읽고 정리하는 일부터 써 보시길 권합니다.
영상으로 보기
설치부터 막힌 곳 고치기, 앱 두 개 오가기, 요령 저장과 재실행까지 실제 화면 그대로 담았습니다.
출처
- phone-harness/phone-harness — README: 동작 원리, 요구 사항, Limits · 릴리스 0.3.3
- install.md — 텔레메트리 끄기, agent-workspace 위치
- SKILL.md — 배운 것을
agent_helpers.py에 남기는 규칙 - telemetry.py — opt-out 텔레메트리, 보내는 항목
- helpers.py —
agent_helpers.py자동 불러오기 - Anthropic, Claude Code Data usage












