phone-harness 설치 가이드: Claude Code·Codex로 아이폰 조작하기

AI가 코드를 작성하는 수준을 넘어 실제 스마트폰 화면을 보고 조작하기 시작했습니다. phone-harness를 연결하면 Claude Code나 Codex가 맥의 아이폰 미러링 창을 읽고 앱을 열거나, 버튼을 누르거나, 글자를 입력하고 화면을 스크롤할 수 있습니다.

이 글에서는 처음 설치하는 분도 따라 할 수 있도록 아이폰 연결부터 권한 설정, Claude Code·Codex 스킬 등록, 실전 명령어와 복사해서 쓸 수 있는 프롬프트까지 순서대로 살펴봅니다.

phone-harness란 무엇인가요?

phone-harness는 맥에서 실제 스마트폰을 제어할 수 있게 해주는 오픈소스 도구입니다. Claude Code와 Codex를 포함해 터미널 명령을 실행할 수 있는 AI 에이전트에서 사용할 수 있습니다. 최신 기능과 지원 범위는 phone-harness 공식 GitHub에서 확인할 수 있습니다.

아이폰에서는 macOS의 아이폰 미러링 창이 연결 통로가 됩니다. 도구가 미러링 창을 캡처하고, Apple Vision OCR로 화면의 글자를 읽습니다. 누르기와 키보드 입력은 macOS 입력 이벤트를 통해 전달합니다.

쉽게 말하면 AI에게 눈과 손을 하나씩 붙여주는 셈입니다.

• 눈: screenshot()과 ocr()로 화면을 확인합니다.
• 손: tap_text(), type_text(), swipe() 등으로 조작합니다.
• 확인: wait_stable() 뒤에 화면을 다시 읽어 결과를 검증합니다.

웹사이트나 API로 더 간단하게 처리할 수 있는 일이라면 굳이 휴대폰을 제어할 필요는 없습니다. iOS 전용 앱, 실제 기기 화면 테스트, 휴대폰에만 있는 작업처럼 스마트폰이 꼭 필요한 상황에 사용하는 것이 좋습니다.

설치 전에 확인할 것

아이폰에서 사용하려면 다음 환경이 필요합니다.

Apple의 아이폰 미러링 시스템 요구사항에 따르면 맥이 인터넷 연결을 공유하거나 AirPlay 또는 Sidecar를 사용하는 동안에는 아이폰 미러링을 사용할 수 없습니다. 아이폰 미러링은 지역에 따라 제공되지 않을 수도 있습니다.

Python 버전은 터미널에서 다음 명령으로 확인할 수 있습니다.

python3 --version

Python 3.10 이상이 표시되면 다음 단계로 넘어가면 됩니다.

1. phone-harness 설치하기

AI에게 설치를 맡기는 프롬프트

공식 README는 Claude Code나 Codex에 설치 과정을 맡기는 방법도 안내합니다. 아래 프롬프트를 그대로 붙여넣으면 AI가 공식 설치 문서를 먼저 읽고 필요한 단계만 안내하도록 요청할 수 있습니다.

phone-harness를 설치해줘.
https://github.com/ShawnPana/phone-harness 저장소를 ~/.phone-harness에 복제하고,
먼저 install.md를 읽은 뒤 phone-harness 명령을 어느 폴더에서나 실행할 수 있게 설치해줘.
그다음 phone-harness skill 명령으로 현재 사용 중인 AI의 스킬 폴더에 등록해줘.
일상적인 사용법은 SKILL.md에서 확인하고, 처음 연결할 때는 onboarding.md를 읽어 나에게 필요한 수동 작업을 한 단계씩 안내해줘.
권한 허용이나 아이폰 페어링처럼 내가 직접 해야 하는 작업에서는 멈추고 요청해줘.

직접 설치하려면 터미널을 열고 아래 명령어를 한 줄씩 실행합니다.

git clone https://github.com/ShawnPana/phone-harness ~/.phone-harness
cd ~/.phone-harness
pip install -e .

~/.phone-harness는 공식 문서가 안내하는 기본 설치 위치입니다. 마지막 명령은 필요한 의존성과 함께 phone-harness 명령어를 설치합니다.

설치가 끝났는지 확인해봅니다.

phone-harness --help

만약 pip 명령을 찾을 수 없거나 서로 다른 Python 환경이 섞인다면, 설치에 사용하는 Python과 실행에 사용하는 Python이 같은지 먼저 확인하세요.

2. 맥 권한 허용하기

아이폰 화면을 보고 조작하려면 phone-harness 명령을 실제로 실행하는 앱에 두 가지 권한이 필요합니다. 터미널에서 실행한다면 Terminal 또는 iTerm 같은 터미널 앱에 권한을 줍니다. Claude Code나 Codex의 자체 실행 환경을 사용한다면 macOS가 권한을 요청하는 실제 호스트 앱을 확인하세요.

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

환경 점검 명령도 실행해봅니다.

phone-harness --doctor ios

이 명령은 아이폰 미러링과 필수 권한을 순서대로 확인하고, 빠진 단계가 있으면 알려줍니다.

3. Claude Code와 Codex에 스킬 등록하기

스킬을 등록하면 AI 에이전트가 phone-harness의 사용법을 읽고 필요한 순간에 명령을 선택할 수 있습니다.

둘 다 사용한다면 두 위치에 모두 등록해도 됩니다.

mkdir -p ~/.claude/skills/phone-harness
phone-harness skill > ~/.claude/skills/phone-harness/SKILL.md

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness"
phone-harness skill > "${CODEX_HOME:-$HOME/.codex}/skills/phone-harness/SKILL.md"

phone-harness 저장소를 업데이트한 뒤에는 위의 phone-harness skill 명령도 다시 실행하세요. AI가 읽는 스킬 문서가 최신 코드와 맞춰집니다.

4. 첫 번째 아이폰 조작 실행하기

먼저 아이폰 미러링 앱을 열고 연결된 화면이 보이는지 확인합니다. 실제 아이폰은 잠긴 상태여야 합니다.

다음 예시는 메모 앱을 열고 화면이 안정될 때까지 기다린 다음, 화면에 보이는 글자 일부를 출력합니다.

phone-harness <<'PY'
open_app("Notes")
wait_stable()
print([item["text"] for item in ocr()][:15])
PY

화면에 보이는 특정 글자를 눌러보려면 tap_text()를 사용합니다.

phone-harness <<'PY'
open_app("Notes")
wait_stable()
print([item["text"] for item in ocr()][:20])
tap_text("New Note")
wait_stable()
PY

앱 언어와 화면 상태에 따라 버튼 이름은 달라질 수 있습니다. 먼저 ocr() 결과를 확인하고 실제로 보이는 문구를 tap_text()에 넣는 습관을 들이면 실패를 줄일 수 있습니다.

자주 쓰는 명령어

메모 앱에 글 작성하기

아래 코드는 메모 앱을 열고 새 메모 버튼을 누른 뒤 내용을 입력하는 기본 흐름입니다.

phone-harness <<'PY'
open_app("Notes")
wait_stable()

print([item["text"] for item in ocr()][:20])
tap_text("New Note")
wait_stable()

type_text("phone-harness로 작성한 첫 번째 메모입니다.")
wait_stable()
print([item["text"] for item in ocr()][:20])
PY

버튼의 이름은 아이폰 언어와 앱 버전에 따라 New Note, 새 메모 등으로 달라질 수 있습니다. 코드를 그대로 실행했는데 찾지 못한다면 ocr()에 출력된 문구로 바꾸세요.

화면을 읽으면서 목록 끝까지 확인하기

단순히 여러 번 스크롤하기보다 scroll_collect()를 사용하면 중복을 제거하면서 목록 끝까지 탐색할 수 있습니다.

phone-harness <<'PY'
def extract(rows):
    return [row["text"] for row in rows if row.get("text")]

result = scroll_collect(extract, key=lambda text: text, max_scrolls=10)
print(result["items"])
print(result["stop"])
PY

stop 값이 reached-end라면 실제 화면 이동이 멈춰 목록 끝에 도달한 것입니다.

Claude Code·Codex에 바로 써볼 프롬프트

스킬 등록까지 끝났다면 코드를 직접 작성하지 않고 자연어로 요청할 수 있습니다. 처음에는 범위가 작고 결과를 눈으로 확인하기 쉬운 작업부터 시작하세요.

연결 상태와 화면 확인

phone-harness를 사용해서 현재 아이폰 연결 상태를 확인해줘.
연결되어 있다면 현재 화면을 캡처하고, OCR로 읽은 글자 중 중요한 것만 알려줘.
아직 화면을 누르거나 변경하지는 마.

메모 앱에서 테스트 메모 작성

phone-harness로 아이폰의 메모 앱을 열어줘.
현재 화면을 OCR로 확인한 다음 새 메모 버튼을 찾아 눌러줘.
제목은 "phone-harness 테스트", 본문은 "AI 에이전트가 실제 아이폰에서 작성한 메모입니다."라고 입력해줘.
각 동작 뒤에는 wait_stable()로 기다리고 OCR 또는 스크린샷으로 결과를 확인해줘.
저장이나 외부 공유가 필요한 단계가 나오면 진행하기 전에 나에게 물어봐.

특정 설정 화면까지 이동

phone-harness를 사용해서 아이폰의 설정 앱을 열어줘.
화면의 텍스트를 읽으면서 배터리 설정 화면까지 이동해줘.
좌표를 추측하지 말고 ocr()와 tap_text()를 우선 사용해줘.
화면이 바뀔 때마다 결과를 확인하고, 설정값은 변경하지 마.

앱의 모바일 화면 점검

phone-harness로 [앱 이름]을 열고 첫 화면을 점검해줘.
화면에 잘린 문구, 겹친 요소, 누르기 어려워 보이는 버튼이 있는지 스크린샷을 기준으로 확인해줘.
필요하면 화면을 천천히 스크롤하되 로그인, 결제, 전송, 삭제는 실행하지 마.
발견한 문제를 화면 위치와 함께 목록으로 정리해줘.

반복 작업을 안전하게 요청하는 프롬프트 틀

phone-harness로 [앱 이름]에서 [목표 작업]을 수행해줘.

규칙:
1. 먼저 connection_state()로 연결 상태를 확인해줘.
2. 좌표를 추측하지 말고 ocr(), tap_text(), tap_icon()을 우선 사용해줘.
3. 각 동작 뒤에는 wait_stable()과 OCR 또는 스크린샷으로 결과를 검증해줘.
4. 메시지 전송, 게시, 결제, 삭제, 설정 변경은 실행 직전에 반드시 나에게 확인해줘.
5. 예상과 다른 화면이 나오면 반복해서 누르지 말고 현재 화면을 설명한 뒤 멈춰줘.

이 틀에서 앱 이름과 목표 작업만 바꿔도 비교적 안전하고 재현성 있게 작업을 맡길 수 있습니다.

현재 지원 범위와 한계

phone-harness는 실제 기기 자동화에 유용하지만 모든 아이폰 동작을 지원하는 것은 아닙니다.

• 아이폰은 한 번에 한 대, 한 세션만 제어할 수 있습니다.
• 멀티터치를 지원하지 않아 핀치 줌이나 두 손가락 동작은 할 수 없습니다.
• 아이폰 미러링에서는 카메라, 마이크, Face ID 흐름을 사용할 수 없습니다.
• DRM이 적용된 영상은 검은 화면으로 보일 수 있습니다.
• 글자 없는 아이콘은 OCR만으로 찾기 어려워 스크린샷과 비전 모델이 필요합니다.
• 실제 아이폰의 잠금을 해제하면 미러링이 멈춥니다.

꼭 알아둘 안전 원칙

phone-harness가 조작하는 대상은 시뮬레이터가 아니라 사용자의 실제 휴대폰입니다. 따라서 아래 작업은 AI가 임의로 완료하게 두지 않는 편이 안전합니다.

• 메시지나 이메일 전송
• SNS 게시물 업로드
• 상품 구매와 결제
• 사진, 메모, 파일 삭제
• 계정이나 시스템 설정 변경
• 개인정보가 포함된 화면 캡처

또한 type_text()는 기본적으로 글자를 한 글자씩 입력하는 대신 붙여넣습니다. 입력한 내용이 맥 클립보드에 남을 수 있으므로 비밀번호나 민감한 개인정보 입력에는 사용하지 않는 것이 좋습니다.

phone-harness 자주 묻는 질문

문제가 생겼을 때 확인할 것

Android에서도 사용할 수 있나요?

현재 phone-harness는 Android도 지원합니다. 아이폰 미러링 대신 adb로 USB 또는 Wi-Fi 연결을 사용합니다.

brew install android-platform-tools
phone-harness config set platform android
phone-harness --doctor android

Android에서는 개발자 옵션과 USB 디버깅을 켜야 합니다. Android 11 이상이라면 같은 네트워크에서 무선 디버깅으로 페어링할 수도 있습니다.

이번 글은 아이폰 설정을 중심으로 다뤘으므로 Android 연결은 공식 설치 문서의 최신 안내를 참고하세요.

마무리

phone-harness의 핵심은 단순히 아이폰 화면을 자동으로 누르는 데 있지 않습니다. AI가 화면을 읽고, 행동하고, 결과를 다시 확인하는 흐름을 실제 기기에서 만들 수 있다는 점이 중요합니다.

처음에는 메모 앱 열기나 화면 텍스트 확인처럼 안전하고 단순한 작업부터 시작해보세요. 익숙해진 뒤에는 모바일 앱 화면 점검, 반복 입력, 실제 기기 테스트처럼 자신에게 필요한 흐름으로 확장할 수 있습니다.

설치 후 첫 요청은 다음 한 문장으로 시작해도 충분합니다.

phone-harness로 현재 아이폰 연결 상태와 화면을 확인해줘. 아직 아무것도 누르지는 마.