eggbrid2/mobileClaw

화면을 보고, 앱을 제어하며, 도구를 구축하고, 컨텍스트를 기억하며, 스스로의 기술을 라우팅할 수 있는 오픈 소스 Android AI 에이전트 런타임 (runtime).

MobileClaw는 실제 휴대폰에서 LLM 에이전트 (LLM agents)를 실행하기 위한 실험적인 Android 앱입니다. 이 프로젝트는 Android 자동화 (automation), 모바일 AI 에이전트 (mobile AI agents), 접근성 기반 휴대폰 제어 (accessibility-based phone control), 온디바이스 Python 도구 (on-device Python tools), 멀티 에이전트 워크플로우 (multi-agent workflows), 그리고 VPN/프록시 (proxy) 운영의 교차점에 위치합니다.

아이디어는 간단합니다. 모바일 에이전트는 단순히 사용자의 기기에 대해 채팅만 해서는 안 됩니다. 화면을 관찰하고, 적절한 도구를 선택하며, Android 기능을 통해 행동하고, 새로운 워크플로우를 생성하며, 작업 전반에 걸쳐 개선될 수 있도록 충분한 메모리 (memory)를 유지할 수 있어야 합니다.

디버그 빌드 (debug build)가 실행 중인 Xiaomi 기기에서 캡처되었습니다. 이것은 목업 (mockup)이 아닌 실제 에이전트 실행 결과입니다: MobileClaw는 WebView MiniAPP을 생성 및 실행하고, 네이티브 AI 페이지 (native AI Page)를 생성하며, 스티커를 포함한 멀티 에이전트 그룹 채팅을 유지하고, 비전 팩 (vision packs)을 통해 온디바이스 모델 (on-device models)을 관리하며, 자신의 기술/VPN/런타임 (runtime) 인터페이스를 노출합니다.

MobileClaw 사용법, Android 에이전트 개발, 로컬 모델 (local models), 기술 (skills), ROM 호환성, 그리고 실제 기기 버그에 대해 논의하려면 WeChat 그룹에 참여하세요.

이 WeChat 그룹 QR 코드는 2026년 5월 28일까지 유효합니다. 만약 만료되었다면, 최신 README를 확인하거나 업데이트된 초대 링크를 요청하세요.

대부분의 모바일 AI 앱은 채팅 인터페이스 (chat surfaces)입니다. MobileClaw는 에이전트를 위한 작은 운영 계층 (operating layer)에 더 가깝습니다.

사용자의 요청은 범위가 지정된 작업 (scoped task)으로 전환됩니다. 해당 작업은 역할 (role), 짧은 계획 (plan), 필터링된 도구 세트 (tool set), 그리고 실행 루프 (execution loop)를 부여받습니다. 이러한 구조가 이 프로젝트의 핵심입니다:

사용자 목표 (user goal) -> 작업 유형 (task type) -> 역할 스케줄러 (role scheduler) -> 플래너 (planner) -> 허용된 기술 (allowed skills) -> 관찰 (observe) -> 행동 (act) -> 검증 (verify)

이것이 중요한 이유는 모든 도구가 항상 사용 가능할 때 휴대폰 자동화가 빠르게 실패하기 때문입니다. MobileClaw는 휴대폰 제어, 웹 리서치, 파일 작업, 앱 구축, 이미지 생성, VPN 제어, 기술 관리, 그리고 코드 실행을 서로 다른 작업 모드 (task modes)로 유지합니다.

프로젝트는 여전히 빠르게 진행되고 있습니다. 일부 기능은 일상적으로 사용할 수 있을 만큼 안정적이지만, 일부는 연구 단계(research-grade)로 기기별 수정이 필요합니다. 이와 같은 종류의 Android 에이전트는 성능을 높이기 위해 실제 기기, 실제 ROM의 특이사항(quirks), 그리고 실제 사용자가 필요하기 때문에 코드를 공개합니다.

휴대폰 제어 및 앱 자동화를 위한 Android AI 에이전트 (Android AI agent).
좌표 기반의 탭(tapping) 및 스크롤(scrolling)을 포함한 VLM 스타일의 화면 읽기 (VLM-style screen reading).
AccessibilityService를 통해 실제 Android 앱을 조작할 수 있는 AI 어시스턴트.
작업 계획(task planning), 역할 라우팅(role routing), 범위 제한된 도구 주입(scoped tool injection)을 갖춘 모바일 에이전트 런타임 (Mobile agent runtime).
장기 실행 작업 및 중단 가능한 작업을 지원하는 멀티 에이전트 그룹 채팅 (Multi-agent group chat).
AI가 생성한 미니 앱 및 네이티브 Android 페이지.
다운로드 가능한 Gemma LiteRT 모델을 통한 선택적 온디바이스 로컬 모델 런타임.
Clash/Mihomo 구독 가져오기 및 Android VPN 제어.
Android 상에서의 임베디드 Python 실행 및 동적 기술 생성 (dynamic skill creation).
Android가 유용한 트리(tree)를 노출할 때 XML을 통한 접근성 기반 화면 읽기 (Accessibility-based screen reading).
see_screen을 통한 비전 우선(Vision-first) 화면 읽기: 스크린샷을 캡처하고, 상호작용 가능한 대상을 표시하며, 직접적인 동작을 위한 좌표를 반환합니다.
XML이 비어 있거나 오해의 소지가 있는 경우(특히 Flutter, React Native, WebView 및 게임 스타일의 UI의 경우)를 위한 원시 screenshot 폴백(fallback).
탭(Tap), 길게 누르기(long press), 스크롤(scroll), 텍스트 입력(text input), 뒤로 가기/홈 내비게이션(back/home navigation), 앱 실행(app launch), 설치된 앱 목록 조회.
더 신뢰할 수 있는 텍스트 삽입 경로를 위한 경량 IME 존재.
사용자의 메인 화면과 분리된 앱 실행을 위한 숨겨진 가상 디스플레이(virtual display) 지원.
백그라운드 화면 XML 및 스크린샷 도구: bg_launch, bg_read_screen, bg_screenshot, bg_stop.
ROM 인지형 설정 가이드, 그리고 가상 디스플레이로의 앱 실행을 차단하는 기기를 위한 선택적 루트(root) 또는 일회성 ADB 활성화 권한 서비스.

TaskClassifier는 요청을 PHONE_CONTROL, WEB_RESEARCH, APP_BUILD, VPN_CONTROL, SKILL_MANAGEMENT, 그리고 CODE_EXECUTION과 같은 작업 유형으로 매핑합니다. TaskPlanner는 도구 실행 전에 계획 호출(planning call)을 수행합니다. TaskToolPolicy

각 태스크에 대해 어떤 도구가 표시될지 제어합니다. RoleScheduler는 내장된 역할과 사용자가 생성한 역할 중에서 선택합니다. AgentRuntime은 반복적인 인지 가드 (perception guards), 스크린샷 컨텍스트 트리밍 (screenshot context trimming), 구조화된 관찰 (structured observations), 그리고 태스크 이벤트 (task events)를 포함하는 ReAct 스타일의 루프를 실행합니다.

내장된 역할 (Built-in roles)은 다음과 같습니다:

일반 어시스턴트 (General assistant)
코더 (Coder)
웹 에이전트 (Web agent)
전화 상담원 (Phone operator)
크리에이터 (Creator)
스킬 관리자 (Skill admin)
VPN 운영자 (VPN operator)

역할은 단순한 페르소나 (personas)가 아닙니다. 역할은 선호하는 태스크 유형, 키워드, 스케줄러 우선순위, 강제 스킬, 그리고 모델 오버라이드 (model overrides)를 선언할 수 있습니다. 사용자가 생성한 역할도 동일한 스케줄러에 참여합니다.

MobileClaw는 다음과 같은 주입 레벨 (injection levels)을 가진 네이티브 스킬 레지스트리 (native skill registry)를 보유하고 있습니다:

레벨 0 (Level 0): 핵심 런타임 요구 사항을 위해 항상 사용 가능합니다.
레벨 1 (Level 1): 태스크 인지 스킬 (task-aware skills).
레벨 2 (Level 2): 온디맨드 스킬 (on-demand skills), 주로 사용자에 의해 생성되거나 승격됩니다.

내장된 스킬 그룹은 다음과 같습니다:

전화 및 인지 (Phone and perception): see_screen, screenshot, read_screen, tap, scroll, input_text, navigate, list_apps.
웹 (Web): web_search, fetch_url, 숨겨진 WebView 브라우징, 페이지 콘텐츠 추출, JavaScript 실행.
파일 및 첨부 파일 (Files and attachments): 파일 생성/읽기/목록화, HTML 페이지 생성, 사용자 저장소 액세스, 파일 카드, 이미지/파일/html/웹페이지/검색 결과 첨부 파일.
생성 (Creation): 이미지 생성, 비디오 생성, 문서 생성, 아이콘 생성.
앱 (Apps): HTML 미니 앱 생성 및 네이티브 Compose AI 페이지 생성.
코드 (Code): 임베디드 Python 실행, 런타임 순수 Python 패키지 설치, 쉘 실행 (shell execution), 콘솔 편집.
메모리 및 사용자 데이터 (Memory and user data): 시맨틱 메모리 (semantic memory), 사용자 프로필 사실, 사용자 설정, 스킬 노트.
메타 도구 (Meta tools): 스킬 생성, 설명을 통한 스킬 생성, 마켓플레이스 스킬 탐색/설치, 역할 관리, 모델 전환, 역할 전환, 채팅 세션 관리.
VPN: vpn_control을 통한 시작/중지/상태 확인.

동적 스킬 (Dynamic skills)은 앱 저장소에 저장된 Python 또는 HTTP 정의일 수 있습니다. 네이티브 및 쉘 스킬은 일반적인 메타 스킬 경로를 통해 에이전트에 의해 의도적으로 생성되지 않습니다.

MobileClaw에는 두 가지 앱 빌딩 경로가 있습니다:

HTML 미니 앱 (mini-apps)은 WebView 내부에서 실행되며, HTTP, SQLite, Python, shell, 메모리, 설정 (config), 파일, 클립보드, 기기 정보, 앱 실행, URL 열기, 공유 및 에이전트에게 질문하기를 위한 Claw JavaScript 브릿지 (bridge)를 사용합니다. - AI 페이지 (AI Pages)는 JSON으로 저장되는 네이티브 Compose 페이지입니다. 이들은 컴포넌트 DSL을 렌더링하며 HTTP, shell, 알림 (notification), 진동 (vibration), 앱 실행, URL 열기, 클립보드, 인텐트 (intents), 전화 다이얼러, SMS 작성기, 알람 및 페이지 간 탐색 (navigation)과 같은 액션 단계 (action steps)를 실행합니다.

두 방식 모두 채팅을 통해 스킬 (skills)을 통해 생성됩니다. 미니 앱은 웹과 유사한 빠른 도구에 적합합니다. AI 페이지는 워크플로우가 네이티브처럼 느껴져야 할 때 더 좋습니다.

후속 편집 (Follow-up edits)은 아티팩트 (artifact) 컨텍스트를 유지합니다. 사용자가 AI 페이지를 생성한 후 "그 페이지"를 변경해 달라고 요청하면, MobileClaw는 최근 페이지 ID를 다음 작업으로 전달하며, 일회성 HTML로 되돌아가는 대신 ui_builder를 통해 업데이트를 다시 라우팅합니다.

MobileClaw에는 Android 에이전트 사용을 위해 설계된 VPN 스택이 포함되어 있습니다:

Clash/Mihomo 구독 가져오기.
매번 다시 구독할 필요 없이 런타임 설정 (runtime configs)을 재구축할 수 있도록 원본 YAML을 저장합니다.
지원되는 파싱된 프록시 (proxy) 유형에는 YAML로부터의 HTTP, SOCKS5, Shadowsocks, SSR, VMess, Trojan 및 VLESS가 포함됩니다.
노드 지연 시간 (latency)은 수명이 짧은 mihomo 프로세스를 통해 테스트됩니다.
런타임 설정은 선택된 노드와 MATCH, GLOBAL을 중심으로 구축됩니다.
Android VpnService가 TUN 인터페이스를 생성합니다.
mihomo가 로컬 혼합 프록시 (mixed proxy)를 제공합니다.
hev-socks5-tunnel이 Android TUN 트래픽을 mihomo로 브릿징 (bridge)합니다.
앱 HTTP 및 WebView 트래픽은 활성화된 프록시 경로를 사용할 수 있습니다.

이 스택은 Xray를 사용하지 않습니다. mihomo가 프록시 프로토콜을 처리하며, Android에 여전히 TUN-to-SOCKS 브릿지가 필요하기 때문에 hev를 유지합니다.

일반 채팅 (Normal chat)은 텍스트, 이미지 첨부, 파일 첨부, 스트리밍 출력 (streaming output), 작업 로그 (task logs), 상세 시트 (details sheets), 접힌 긴 콘텐츠 (collapsed long content), 별도 첨부 메시지를 지원합니다.
그룹 채팅 (Group chat)은 사용자 및 AI 첨부 파일을 지원합니다.
그룹 채팅에는 작은 작업 풀 (task pool)이 있습니다. 긴 작업은 에이전트 (agent)와 풀 슬롯 하나를 점유하며, 그룹 전체를 점유하지는 않습니다.
용량이 확보되면 에이전트는 새로운 사용자 턴 (user turns)에 의해 중단될 수 있습니다.
그룹 채팅의 역할 (roles)은 각자 고유한 말풍선 스타일 (bubble style)을 가질 수 있습니다. 에이전트는 기본적으로 네이티브 Markdown 말풍선을 선택하도록 권장되며, 이후 프리셋 (presets), 텍스트 색상, 글꼴 (font family), 글꼴 두께 (font weight), 글꼴 크기 (font size), 그라데이션 (gradients), 배경 이미지, 패턴, 감정 필드 (emotion fields), 모서리별 곡률 (per-corner radius), 패딩 (padding), 그림자 (shadows), 작은 장식, 그리고 가벼운 텍스트/테두리 애니메이션을 조정할 수 있습니다.
네이티브 Markdown 스타일링이 충분히 표현력이 부족한 경우에만 역할이 HTML 말풍선 렌더링 (HTML bubble rendering)을 선택할 수 있습니다. HTML 말풍선은 커스텀 템플릿, 높이, 투명 배경, 선택적 JavaScript, 선택적 네트워크 이미지를 지원하지만, 성능과 앱 같은 일관성을 위해 네이티브 렌더링이 권장되는 경로로 유지됩니다.
내장된 ChineseBQB 스티커는 썸네일 그리드에서 검색하거나 즐겨찾기에 추가할 수 있습니다. 스티커를 선택하면 일반 첨부 파일로 대기 상태가 되는 대신, 스티커/이미지 메시지로 직접 전송됩니다.
의미론적 메모리 (Semantic memory)는 영구적인 키-값 (key-value) 사실을 저장합니다.
대화 메모리 (Conversation memory)는 최근의 사용자 및 어시스턴트 메시지를 저장합니다.
에피소드 메모리 (Episodic memory)는 작업 결과, 사용된 기술, 성찰을 기록한 다음, 로컬 캐릭터 n-gram 임베더 (character n-gram embedder)를 통해 유사한 과거 작업을 검색합니다.
사용자 프로필 추출 (User profile extraction)은 구조화된 프로필 사실을 의미론적 메모리에 기록합니다.
작업 메모리 (Working memory)는 활성 프롬프트 (active prompt)의 범위를 제한하기 위해 작업 단계들을 다듬습니다 (trim).

MobileClaw는 LiteRT-LM을 통해 선택된 온디바이스 모델 (on-device models)을 실행할 수 있습니다:

로컬 모델 관리 (Local model management)는 설정 (Settings)에서 이루어지며, 다운로드, 가져오기, 삭제, 활성화 및 모델 선택 제어 기능을 포함합니다.
내장된 다운로드 옵션에는 Gemma 4 E2B 및 Gemma 4 E4B LiteRT-LM 패키지가 포함됩니다.
멀티모달 (Multimodal)
.task

리소스 패키지는 별도로 다운로드하거나 가져올 수 있으며, 현재 Android LiteRT-LM 채팅 경로는 .litertlm 텍스트 런타임 (text runtime) 파일을 사용합니다.

모델 다운로드는 Hugging Face, ModelScope 및 사용자가 제공한 커스텀 직접 URL 등 여러 소스를 지원합니다.
공식 Hugging Face 다운로드를 위해 Hugging Face 토큰이 지원되지만, 국내 미러 사이트나 커스텀 URL로는 전송되지 않습니다.
활성화된 경우 텍스트 전용 요청에는 로컬 채팅 (Local chat)이 사용됩니다. 도구 호출 (Tool calls), 이미지 입력, 웹 접속 또는 사용 불가능한 로컬 모델은 가능한 경우 자동으로 구성된 클라우드 엔드포인트 (cloud endpoint)로 폴백 (fallback)됩니다.
루프백 API 서버 (loopback API server)는 스킬 (skills), 동적 스킬 설치/삭제, 메모리 및 설정을 로컬 HTTP 스킬에 노출합니다.
LAN 콘솔 서버 (LAN console server)는 브라우저 UI, SSE 작업 이벤트, 세션/메시지 API, 스킬 내보내기/가져오기 API, 메모리/설정 API 및 다운로드 가능한 OpenClaw CLI 스크립트를 노출합니다.
콘솔 페이지는 에이전트 (agent)가 console_editor를 통해 편집할 수 있습니다.

app/src/main/java/com/mobileclaw
├─ agent
│ ├─ TaskSession.kt 작업 유형, 작업 계획, 도구 정책
...

요구 사항:

Android Studio Ladybug 이상
JDK 21
Android 11 이상 기기 또는 에뮬레이터
OpenAI 호환 채팅 엔드포인트 및 API 키

git clone https://github.com/eggbrid2/mobileClaw.git
cd mobileClaw
./gradlew :app:assembleDebug

디버그 APK:

app/build/outputs/apk/debug/app-debug.apk

이 앱은 Kotlin 2.2, Jetpack Compose, Room, DataStore, WebView, OkHttp, Gson, Jsoup, SnakeYAML, Chaquopy Python 3.11, LiteRT-LM, mihomo 및 hev-socks5-tunnel을 사용합니다.

MobileClaw는 사용자가 승인한 Android 기능을 명시적인 에이전트 도구 (agent tools)로 변환하여 작동합니다. 기능에 따라 다음을 요청할 수 있습니다:

화면 읽기, 스크린샷, 제스처 및 입력을 위한 접근성 서비스 (Accessibility service) 권한
Android VpnService를 위한 VPN 권한
포그라운드 (Foreground) VPN 상태 및 AI 페이지 알림을 위한 알림 (Notification) 권한.
사용자가 선택한 첨부 파일 및 사용자 저장소 도구를 위한 파일 및 미디어 접근 권한.
장시간 실행되는 기능 및 시각적 어시스턴트 기능을 위한 오버레이 (Overlay)/백그라운드 관련 권한.
표준 API를 차단하는 ROM에서 특권 가상 디스플레이 (Virtual-display) 헬퍼를 사용하기 위한 선택적 ADB 활성화.

루트 (Root) 권한은 필수 요구 사항이 아닙니다. 일부 백그라운드 디스플레이 기능은 여전히 ROM별 설정, 루트 권한 또는 번들로 제공되는 shell-uid 헬퍼가 필요할 수 있습니다.

비표준 Android 뷰 (View)에서의 더욱 강력한 UI 자동화.
더 나은 VLM 그라운딩 (Grounding) 및 동작 검증.
더 안전한 동적 기술 (Skill) 검토 및 승격.
더 나은 작업 정책 및 역할 스케줄링 휴리스틱 (Heuristics).
더욱 재현 가능한 VPN 구독 및 mihomo 예외 케이스 처리.
가상 디스플레이 실행 동작에 대한 ROM 호환성 보고서.
더 나은 문서, 데모 및 소규모 역할/기술 프리셋.

PR (Pull Request)을 생성하기 전에 CONTRIBUTING.md를 읽어주세요. 기기별 동작에 대해서는 ROM 호환성 이슈 템플릿을 사용하고 docs/recipes/rom-compatibility-report.md의 체크리스트를 포함해 주세요.

eggbrid2/mobileClaw

요약

핵심 포인트

화면을 보고, 앱을 제어하며, 도구를 구축하고, 컨텍스트를 기억하며, 스스로의 기술을 라우팅할 수 있는 오픈 소스 Android AI 에이전트 런타임 (runtime).

댓글