AI 에이전트가 안드로이드 스마트폰을 조작하게 하는 오픈소스 앱 'Buddy' 제작기 (Claude Code / Codex / MCP)

Claude Code나 Codex와 같은 코딩 에이전트는 터미널 환경에서는 매우 유능합니다. 그렇다면, 그 '손'을 스마트폰 화면까지 뻗어 나간다면 어떨까요? 이러한 생각을 바탕으로 안드로이드 앱 Buddy를 제작했습니다.

• 리포지토리: https://github.com/ghorbelhamdi/buddy-android
• 라이선스: Apache 2.0
• 대응 환경: Android 11 이상, 64비트. root나 PC가 필요 없습니다.

화면에 떠 있는 채팅 말풍상자에 원하는 작업을 글자 또는 음성으로 전달합니다. 그러면 에이전트가 화면을 읽고, 터치 및 입력을 통해 앱을 조작합니다.

본 기사에서는 어떤 원리로 작동하는지에 초점을 맞춰 소개하겠습니다.

• 설치된 앱 사용 (설정 변경, 폼 입력, 여러 쇼핑 앱에서의 가격 비교 등)
• 알림을 계기로 동작 (예: '이 사람에게 메시지가 오면 영업시간으로 답장하기'와 같은 규칙)
• 정해진 시간에 태스크 실행
• 화면을 사용하지 않는 백그라운드 브라우저에서 웹 검색
• 내장된 Linux 환경에서 명령어를 실행하여 작은 앱 빌드
• 자신의 MCP 서버를 연결하여 툴 추가

지원하는 에이전트는 Claude Code, Codex, OpenCode, Antigravity, Grok의 5가지입니다. 사용자의 구독(Subscription), API 키, 또는 로컬 모델 중 어느 것으로든 사용할 수 있습니다. OpenCode의 무료 모델을 이용하면 계정도 필요 없습니다.

크게 세 가지 부품으로 구성되어 있습니다.

Buddy 앱 (화면/UI/키 관리)
│ 127.0.0.1의 MCP 서버 (토큰 포함)
▼
...

안드로이드 사용자 접근성 서비스(Accessibility Service)를 사용하여 화면상의 요소(텍스트, 버튼, 입력란)를 목록 형태로 가져오고, 터치 및 입력을 수행합니다. 매번 스크린샷을 모델에 전송하는 것이 아니라, 기본적으로는 요소의 목록을 텍스트로 전달합니다. 지도나 게임처럼 요소 추출이 불가능한 화면에서만 스크린샷을 사용합니다.

에이전트의 CLI(Command Line Interface)는 스마트폰 안에서 작동합니다. Buddy는 작은 Alpine Linux를 앱 전용 영역에 배포하고, proot으로 실행합니다. Claude Code 등은 공식 인스톨러로 그 안에 설치됩니다. root 권한화는 필요하지 않습니다.

앱은 127.0.0.1에서 MCP 서버를 구축하고, read_screen, tap, type_text, open_app, confirm 등의 툴을 제공합니다. 에이전트의 관점에서 볼 때, 스마트폰은 'MCP 툴이 많이 붙어 있는 환경'입니다. 에이전트마다 출력 형식이 다르기 때문에, 셸 스크립트(Shell Script)의 헬퍼가 5가지 출력을 하나의 이벤트 형식으로 통일했습니다.

종속 라이브러리는 거의 없으며, Java와 Bash로 작성되었습니다.

에이전트에게 스마트폰을 만지게 하는 이상, 이 부분이 가장 중요하다고 생각합니다.

• 승인 카드(Approval Card): 전송, 게시, 구매, 삭제 등 조작을 수행하기 전에 Buddy 자신이 카드를 내밀어 확인 절차를 거칩니다. 이는 프롬프트 요청이 아니라, 터치 직전에 앱 측에서 멈추는 메커니즘입니다.
• 앱별 모드(App-specific Mode): 메시지, SNS, 이메일, 통화, 쇼핑, 금전과 관련된 앱은 처음부터 엄격한 모드(Hard)로 설정됩니다.
• 자신을 조작하지 않음: 에이전트는 Buddy의 말풍선이나 승인 카드를 터치할 수 없습니다. 즉, 스스로를 승인하는 것은 불가능합니다.
• API 키는 Linux 측에 전달되지 않음: 키는 Android Keystore에서 암호화되어 저장되며, 앱 내부 리레이(Relay)가 요청에 첨부합니다. 에이전트에게는 보이지 않습니다.
• 화면의 문자는 '내용'일 뿐 '지시'가 아님: 알림이나 웹 페이지의 글자에 지시사항이 적혀 있더라도 따르지 않도록, 툴의 결과로만 전달됩니다.

2.3에서 추가된 기능입니다. 에이전트가 자신만을 위한 보이지 않는 화면에서 앱을 조작하는 동안에도 사용자는 평소처럼 스마트폰을 사용할 수 있습니다. 화면 잠금 상태에서도 계속 작동하며, 승인이 필요할 경우 잠금 화면의 알림에 '승인' 또는 '거부'가 표시됩니다.

구현 방식은 약간 다릅니다.

Buddy는 내장 Linux의 adb를 스마트폰 자체의 '무선 디버깅(Wireless Debugging)'과 페어링합니다 (PC는 사용하지 않습니다. 설정 앱 조작도 Buddy가 스스로 수행합니다).
이 adb를 통해,
app_process
를 사용하여 작은 헬퍼(helper)를 shell 사용자로 실행합니다. - 이 헬퍼가 가상 디스플레이를 만들고, 앱 실행, 터치 주입, 화면 캡처를 담당합니다.

다른 앱이 작동하는 가상 디스플레이를 만들 수 있는 것은 shell 사용자뿐이기 때문에, 이 경로를 택하게 되었습니다.

기기별 차이점 때문에 상당히 고생했습니다. 예를 들어 Samsung의 경우, 프레임워크가 헬퍼에게 설정 객체를 요구하면서 충돌(crash)이 발생했습니다. Android 17의 Pixel에서는 개발자 옵션이 활성화되었는지 앱에서 읽을 수 없게 되었고, 페어링 설정 다이얼로그에서 포트 번호도 사라졌습니다. 이 모든 것은 사용자분들께서 제기해주신 Issue 덕분에 해결할 수 있었습니다.

자신의 PC에서 Ollama, LM Studio, llama.cpp의 서버를 구동할 수 있다면, AI 기업에 아무것도 전송하지 않고 사용할 수 있습니다. 설정 → API 키 → Ollama를 선택하고 PC 주소만 입력하면 됩니다.

솔직히 말해, 작은 모델에는 한계가 있습니다. RTX 2060 Super(8 GB)로 테스트했을 때, Qwen3의 4B나 8B는 "배터리 잔량을 알려줘"와 같은 1단계 요청은 처리할 수 있지만, 화면을 여러 번 조작하는 작업에서는 실패가 두드러졌습니다. 실용성을 위해서는 도구 호출(tool calling)에 능숙한 큰 모델이 필요합니다.

• 은행 앱이나 비밀번호 관리 앱처럼 화면 캡처를 금지하는 앱의 내부 내용은 볼 수 없습니다.
• 게임처럼 요소가 없는 화면은 위치를 지정한 탭만 가능하며, 실패하기 쉽습니다.
• 비밀번호, 일회용 코드(one-time code), 결제 정보의 입력은 사용자에게 맡깁니다.

APK는 GitHub의 Releases에 있습니다.

설치 후, 사용자 접근성 서비스(user accessibility service)를 활성화하고, 사용하려는 에이전트를 앱 내에서 설치 및 로그인하면 사용할 수 있습니다.

"에이전트가 PC를 조작하게 한다"는 이야기는 자주 접하지만, 매일 휴대하는 스마트폰에서도 같은 것이 가능하다니 활용도가 상당히 넓어질 것 같습니다. 코드는 모두 공개되어 있으므로, 작동 원리에 관심 있는 분들은 꼭 읽어보시길 바랍니다. 버그나 요청 사항은 Issue로 받고 있습니다.