원문 보기
GitHub - unitedbyai/droidclaw: turn old phones into ai agents - give it a goal in plain english. it reads the screen, thinks about what to do, taps and types via adb, and repeats until the job is done.
Service

GitHub - unitedbyai/droidclaw: turn old phones into ai agents - give it a goal in plain english. it reads the screen, thinks about what to do, taps and types via adb, and repeats until the job is done.

unitedbyai
2026.02.19
·GitHub·by 이호민
#Agent#AI#Android#Automation#LLM

핵심 포인트

  • 1DroidClaw는 LLM(Large Language Model)을 활용하여 Android 스마트폰의 화면을 인식하고(Perception), 행동을 계획하며(Reasoning), ADB(Android Debug Bridge)를 통해 탭, 타이핑 등의 동작을 실행(Action)하는 AI 에이전트입니다.
  • 2이 시스템은 Perception → Reasoning → Action 루프를 반복하며, stuck loop detection, repetition tracking, vision fallback과 같은 견고한 오류 처리 메커니즘을 통해 복잡한 작업을 안정적으로 수행합니다.
  • 3사용자는 영어 목표를 직접 입력하는 interactive mode, AI 기반의 다단계/다중 앱 자동화를 위한 workflows, 그리고 LLM 없이 고정된 동작을 즉시 실행하는 flows의 세 가지 방식으로 DroidClaw를 활용할 수 있습니다.

DroidClaw는 오래된 Android 스마트폰을 AI 에이전트로 전환하여 영어로 주어진 목표를 수행하게 하는 시스템입니다. 이는 화면을 읽고, 생각하고, ADB(Android Debug Bridge)를 통해 탭(tap), 타이핑(type) 등의 작업을 실행하여 목표가 완료될 때까지 반복합니다. 특정 앱에 대한 API 연동 없이도 마치 사람이 사용하는 것처럼 앱을 제어할 수 있으며, ChatGPT, Gemini, Google Search와 같은 서비스에 기기 내에서 작업을 위임하고 그 결과를 다시 가져올 수 있습니다.

핵심 방법론은 간단한 "Perception → Reasoning → Action" 루프에 기반합니다.

  1. Perception (인지): ADB를 통해 현재 화면의 accessibility tree를 덤프(dump)하고 XML을 파싱(parse)하여 상호작용 가능한 UI 요소들을 추출합니다. 이전 화면과의 diff를 통해 변경 사항을 감지하며, 필요에 따라 스크린샷(screenshot)을 촬영합니다.
  2. Reasoning (추론): 인지된 화면 상태, 사용자의 목표, 그리고 이전 단계들의 기록(history)을 LLM(Large Language Model)에 전송합니다. LLM은 이를 바탕으로 think (생각), plan (계획), action (수행할 동작)을 반환합니다. 예를 들어, "I see the search icon at (890, 156). I should tap it."과 같은 추론 결과를 생성합니다.
  3. Action (실행): LLM이 결정한 동작(tap, type, swipe 등)을 ADB 명령을 통해 Android 기기에서 실행합니다. 각 동작의 결과(성공/실패 메시지)는 다음 단계에서 LLM에 피드백됩니다. 목표가 완료되었는지 확인하고, 완료되지 않았다면 다시 Perception 단계로 돌아가 루프를 반복합니다.

DroidClaw는 LLM이 UI를 제어할 때 발생할 수 있는 여러 실패 모드를 처리합니다:

  • Stuck Loop Detection: 화면이 3단계 동안 변하지 않으면, 복구 힌트(recovery hints)가 LLM 프롬프트(prompt)에 주입됩니다.
  • Repetition Tracking: 최근 동작들의 슬라이딩 윈도우(sliding window)를 추적하여 동일한 좌표를 3회 이상 탭하는 반복 루프를 감지하고 다른 시도를 하도록 지시합니다.
  • Drift Detection: 에이전트가 상호작용 없이 swipe, back, wait와 같은 탐색 동작만을 반복할 경우 직접적인 행동을 취하도록 유도합니다.
  • Vision Fallback: accessibility tree가 비어있는(예: 웹뷰, Flutter 앱, 게임) 경우, 스크린샷이 LLM에 전송되고 좌표 기반의 탭 제안이 제공됩니다.
  • Action Feedback: 모든 동작의 결과가 LLM에 피드백되어 에이전트가 자신의 행동 성공 여부를 인지합니다.
  • Multi-turn Memory: 대화 기록(conversation history)이 유지되어 LLM이 이전에 시도했던 내용에 대한 맥락을 가질 수 있습니다.

DroidClaw는 세 가지 사용 모드를 제공합니다:

  1. Interactive Mode: 사용자가 직접 목표를 입력하면 에이전트가 즉흥적으로 작업을 해결합니다. LLM을 사용하여 한 번의 작업이나 탐색, 빠른 명령에 적합합니다.
  2. Workflows: JSON 파일로 정의된 다단계 목표 시퀀스를 AI가 처리합니다. 각 단계는 다른 앱으로 전환할 수 있으며, LLM이 탐색, 탭, 타이핑 방법을 결정합니다. 멀티 앱 작업이나 반복적인 루틴에 유용하며, formData를 통해 특정 데이터를 주입할 수 있습니다.
  3. Flows: AI의 개입 없이 미리 정의된 탭 및 타이핑 시퀀스를 즉시 실행하는 YAML 기반의 매크로(macro)와 같습니다. LLM 호출이 없어 빠르며, 항상 동일하게 반복되는 단순 작업에 사용됩니다.

에이전트는 28가지의 기본 actions (예: tap, type, swipe, launch, home)과 더불어, 여러 수동 작업을 하나의 호출로 대체하는 multi-step skills를 가집니다. read_screen은 화면을 스크롤하며 모든 텍스트를 수집하고, compose_email은 Android intents를 사용하여 To, Subject, Body 필드를 채웁니다. 이들은 LLM의 의사결정 횟수를 크게 줄여줍니다.

LLM 공급자로는 Groq (무료), Ollama (로컬), OpenRouter, OpenAI, Bedrock 등이 지원되며, .env 파일을 통해 LLM_PROVIDER, MAX_STEPS, STUCK_THRESHOLD, VISION_MODE 등 다양한 설정을 구성할 수 있습니다.

내부 아키텍처는 kernel.ts가 중심 루프를 담당하며, sanitizer.ts는 화면을 파싱하고, llm-providers.ts는 LLM과 통신하며, actions.ts는 ADB 명령을 실행합니다. skills.ts는 복합 동작을 구현하고, workflow.ts와 flow.ts는 각각 워크플로우와 플로우를 관리합니다.

USB 연결 외에도 Tailscale을 사용하여 Android 기기와 컴퓨터를 동일한 Tailnet에 연결하면, Wi-Fi나 지리적 제약 없이 원격에서 Android 기기를 제어하고 AI 에이전트로 활용할 수 있습니다. 이는 구형 Android 기기를 API가 없는 앱에서도 항상 작동하는 AI 에이전트로 재활용하는 데 중요한 역할을 합니다.