Core-Mate/OpenGUI

언어: English | 简体中文 | 日本語

Android를 위한 모바일 GUI 에이전트 프레임워크.

OpenGUI는 AI 에이전트가 실제 기기에서 Android 앱 인터페이스를 보고, 이해하고, 조작할 수 있도록 돕습니다.

OpenGUI는 실제 Android 앱 UI를 읽고, 다음 단계를 계획하며, 모바일 동작을 수행하고, 구조화된 결과를 반환합니다.

OpenGUI를 시도하는 가장 빠른 방법은 Claude Code나 Codex가 사용자를 위해 부트스트랩(bootstrap)하도록 하는 것입니다.

Read ./skills/open-gui-bootstrap/SKILL.md and help me run OpenGUI. Only ask me for phone-side actions.

다음 사항이 필요합니다:

• Android 전화기 또는 에뮬레이터
• USB 디버깅(USB debugging) 활성화
• 접근성 서비스(AccessibilityService) 활성화
• 실제 작업 실행을 위한 모델 API 키

OpenGUI는 저장소 스크립트를 사용하여 백엔드(backend)를 시작하고 Android 클라이언트를 설치합니다:

cd server
./start.sh

cd client
./start.sh

백엔드와 Android 클라이언트가 실행된 후, 첫 번째 작업을 보냅니다:

cd server
pnpm opengui -- devices --json
pnpm opengui -- do "Observe the current Android screen and summarize what you see" --json

수동 설정 가이드: docs/get-started.md

.

[2026.5.16]

로컬 REST API, pnpm opengui -- ... CLI, 그리고 코딩 에이전트로부터 Android 앱 작업을 전달하기 위한 open-gui-remote-control 스킬을 통해 Codex / Claude Code 원격 제어 기능을 추가했습니다.

[2026.5.9]

접두사 명령(prefix commands), 슬래시 명령(slash commands), 허용 목록(allowlists), 그리고 길드 범위 명령 등록(guild-scoped command registration)을 포함하여 원격 Android 작업 전달을 위한 Discord IM 채널을 추가했습니다.

[2026.5.7]

Docker 기반 백엔드 설정 중 흔히 발생하는 PostgreSQL 및 Redis 포트 충돌을 방지하기 위해 로컬 시작 과정을 강화했습니다.

[2026.5.1]

.env.example, 시작 체크, 그리고 그래프 에이전트 VLM 환경 설정을 통해 백엔드 온보딩(onboarding)을 개선했습니다.

OpenGUI는 화면 이해, 작업 계획, 동작 실행, 검토 및 복구를 위한 Android GUI 에이전트 스택을 제공합니다.

이 저장소를 네 가지 실용적인 방식으로 사용할 수 있습니다:

• 주류 Android 앱 조작 (Operate mainstream Android apps): 실제 휴대폰에서 X, Reddit, Hacker News, Telegram, WeChat, Weibo, Xiaohongshu 및 기타 Android 앱 내의 모바일 작업을 AI가 처리하도록 합니다. -
• 배포된 워크플로우 실행 (Run shipped workflows): 이 저장소에는 실행 가능한 백엔드 (backend), Android 클라이언트 (client), 대기 중인 디스패치 경로 (standby dispatch path), 그리고 일련의 내장된 작업 기능 (built-in task capabilities)이 이미 포함되어 있습니다. -
• Claude 또는 Codex를 사용하여 부트스트랩 (Let Claude or Codex bootstrap it for you): 모델이 skills/open-gui-bootstrap/SKILL.md를 가리키게 한 뒤, 목표를 평이한 언어로 설명하면 모델이 설정, 빌드, 설치 및 로컬 디버깅 (local debugging)을 처리하도록 합니다. -
• Codex가 Android 앱을 제어하도록 허용 (Let Codex control Android apps): OpenGUI가 실행된 후, Codex 또는 Claude Code가 skills/open-gui-remote-control/SKILL.md를 가리키게 하여 로컬 CLI를 통해 장치를 나열하고, 작업을 디스패치 (dispatch)하며, 실행을 추적하도록 합니다. -
• 원격 작업자로서 휴대폰 운영 (Operate phones as remote workers): Feishu, Telegram, Discord 또는 REST API를 통해 작업을 디스패치하고, 장치를 대기 상태로 유지하며, 백엔드로부터 구조화된 결과 (structured results)를 받아옵니다.

장시간 실행되는 작업을 위해 설계됨 (Built for long-running tasks): OpenGUI는 몇 시간 동안 실행될 수 있는 모바일 워크플로우 (mobile workflows)에 맞춰 형성되었으며, 진행 상황, 검토 및 복구가 시스템 내부에서 유지됩니다. 실행 전 계획, 실행 후 요약 (Plan before action, summarize after execution): 앱을 건드리기 전에 OpenGUI는 목표를 실행 가능한 단계로 나눕니다. 실행 후에는 무엇이 일어났는지, 무엇이 작동했는지, 그리고 여전히 주의가 필요한 부분이 무엇인지에 대한 구조화된 요약을 반환합니다. 작업이 계속 진행될 수 있음 (The task can keep moving): Plan Supervisor는 작업 상태와 연속성을 유지하고, Executor Graph는 실시간 장치 상태 위에서 스크린샷 (screenshot), 비전 (vision), 액션 (action) 및 사용자 호출 (call-user) 루프를 실행하며, Summarizer는 구조화된 결과와 함께 실행을 종료합니다. 휴대폰을 대기 상태로 유지 가능 (Phones can stay on standby): 대기 중인 디스패치 경로 (standby dispatch path)를 통해 장치가 Feishu, Telegram, Discord 또는 REST 엔트리 포인트를 통해 원격 작업을 수신할 수 있습니다. 역할별로 모델 할당 가능 (Models can be assigned by role): 모델 라우팅 (model routing)은 계획 (planning)과 VLM 실행을 분리하여 팀이 작업별로 제공업체 (providers)를 선택할 수 있게 합니다. 시스템은 실제 모바일 워크플로우를 중심으로 구성됨 (The system is organized around real mobile workflows): 그래프 (graph), 장치 실행 경로 (device execution path), 그리고 모델 분할 (model split)이 이미 소스 트리 (source tree)에 존재합니다.

OpenGUI는 명시적인 오케스트레이션 레이어 (orchestration layers)를 갖춘 모바일 운영자 시스템 (mobile operator system)으로 구축되었습니다.

현재 소스 코드는 다음과 같은 구성 요소들을 노출합니다:

server/apps/backend/src/modules/graph-agent/graph/mobile-agent.graph.ts
메인 그래프 (main graph)용

server/apps/backend/src/modules/graph-agent/graph/executor.graph.ts
디바이스 측 실행 루프 (device-side execution loop)용

server/apps/backend/src/common/ws/standby.gateway.ts
대기 디바이스 디스패치 (standby device dispatch)용

client/core_network/.../StandbySocketManager.kt
지속적인 디바이스 대기 연결 (persistent device standby connections)용

client/core_accessibility/.../GestureService.kt
Android 측 액션 실행 (Android-side action execution)용

차원 (Dimension)	일반적인 phone-agent 데모	OpenGUI
실행 모델 (Execution model)	짧은 상호작용 루프 (Short interactive loop)	메인 그래프 및 실행 서브그래프 (Main graph plus executor subgraph)
작업 상태 (Task state)	대개 로컬이며 세션에 종속됨 (Usually local and session-bound)	백엔드 그래프에서 관리되는 작업 상태 (Task state managed in the backend graph)
디바이스 경로 (Device path)	종종 노트북 기반 제어 (Often laptop-driven control)	대기 및 실행 소켓을 갖춘 Android 클라이언트 (Android client with standby and execution sockets)
모델 사용 (Model usage)	하나의 모델이 대부분의 작업을 수행 (One model does most of the work)	계획 (Planning) 및 VLM 경로를 여러 제공자(providers)로 분할 가능 (VLM paths can be split across providers)
원격 조작 (Remote operation)	선택적인 추가 기능 (Optional add-on)	Feishu, Telegram, Discord, REST API 및 대기 디스패치가 백엔드에 내장됨 (Feishu, Telegram, Discord, REST API, and standby dispatch are built into the backend)

• Open X를 수행하고 특정 주제에 대한 최근 게시물을 수집

• 실제 휴대폰에서 Reddit 또는 Hacker News 스레드를 읽고 요약

• Feishu, Telegram, Discord 또는 REST API를 통해 원격으로 Android 작업 트리거

• Android 디바이스에서 반복적인 모바일 워크플로 (mobile workflows) 실행

• 상태 관리, 검토 및 수 시간이 걸리는 복구 작업이 필요한 긴 모바일 워크플로 실행

• Android 디바이스 또는 에뮬레이터가 필요합니다.

• USB 디버깅 및 AccessibilityService 권한이 필요합니다.

• 실행 품질은 모델, 앱 UI, 네트워크 상태 및 작업 길이에 따라 달라집니다.

• 아직 항상 켜져 있는 OS 레벨의 어시스턴트는 아닙니다. 작업은 현재 수동으로 또는 구성된 디스패치 채널을 통해 트리거됩니다.

• 시스템 설계상 장시간 실행되는 작업이 지원되지만, 신뢰성은 여전히 더 많은 실제 환경 테스트가 필요합니다.

• 즉시 실행 가능한 더 많은 작업 예시와 벤치마크 (benchmarks)가 여전히 필요합니다.

• 짧은 데모 영상과 더 많은 실제 앱 예시 추가.

• 원커맨드 (one-command) 로컬 설정 개선.

• 즉시 실행 가능한 더 많은 휴대폰 사용 작업 템플릿 추가.

• 실행 복구 및 실패 보고 기능 개선.

• Android GUI 에이전트 신뢰성을 위한 벤치마크 (benchmarks) 작업 추가.

• 모델 설정 및 비용 절감 프로필 (cost-saving profiles)에 대한 문서 확장.

skills/open-gui-bootstrap/SKILL.md로 시작하세요.

.

의도된 흐름은 간단합니다:

• Claude 또는 Codex를 해당 스킬 (skill)로 지정합니다.
• 작업을 평이한 언어로 설명합니다.
• 모델이 백엔드 부트스트랩 (bootstrap), APK 빌드, 설치 및 로컬 디버깅 (debugging)을 처리하도록 합니다.

다음의 경우에만 중단됩니다:

• 휴대폰 연결 또는 에뮬레이터 (emulator) 시작
• USB 디버깅 승인
• 접근성 서비스 (AccessibilityService) 활성화
• 오버레이 (overlay) 또는 배터리 권한 허용
• API 키 또는 봇 자격 증명 (credentials) 제공

백엔드와 Android 클라이언트가 실행된 후에는, skills/open-gui-remote-control/SKILL.md를 사용하여 Codex 또는 Claude Code가 로컬 CLI를 통해 휴대폰을 제어하도록 합니다:

cd server
pnpm opengui -- devices --json
pnpm opengui -- do "Observe the current Android screen and summarize what you see" --json
...

권장 프로필 (profiles):

전반적으로 가장 강력한 품질을 원한다면 계획 (planning), 감독 (supervision), 검토 (review) 및 비전 (vision) 단계 전반에 걸쳐 최신 Claude Opus 모델 제품군을 사용하세요.

이것은 최고의 실행 품질을 얻을 수 있는 가장 쉬운 방법이지만, 가장 비용이 많이 드는 경로입니다.

Planner 및 Supervisor와 같은 텍스트 측면의 역할에는 Qwen 3.6 Plus를 사용하고, VLM 측면에는 Doubao Pro를 사용하세요.

이 방식은 작업 길이, 스크린샷 양, 토큰 혼합 비율에 따라 다르지만, 전체 Opus 설정과 비교했을 때 모델 비용을 대략 10배에서 15배 정도 낮추면서 전체적인 시스템 구조를 유지할 수 있습니다.

권장 프롬프트 (prompts):

Read ./skills/open-gui-bootstrap/SKILL.md and help me run OpenGUI. Only ask me for phone-side actions.

Read ./skills/open-gui-bootstrap/SKILL.md and bootstrap OpenGUI with the latest Claude Opus model family for planning, supervision, review, and vision.

./skills/open-gui-bootstrap/SKILL.md를 읽고, Planner(플래너) 및 Supervisor(감독관)로는 Qwen 3.6 Plus를, VLM(시각 언어 모델) 실행에는 Doubao Pro를 사용하여 OpenGUI를 설정하세요.

./skills/open-gui-bootstrap/SKILL.md를 읽고, 기존의 모델 API를 사용하여 OpenGUI가 작동하도록 하세요.

저장소 스크립트를 직접 사용하세요:

cd server
./start.sh

cd client
./start.sh

참조 문서:

• docs/get-started.md
• server/start.sh
• client/start.sh
• server/apps/backend/README.md
• docs/DISCORD.md
• client/README.md

Discord는 선택적인 IM(인스턴트 메시징) 채널로 활성화할 수 있습니다. Discord 봇이 !opengui devices 또는 !opengui do ...와 같은 명령을 받으면, 백엔드(backend)가 대기 중인 Android 휴대폰으로 작업을 전달(dispatch)하고 해당 채널에 진행 상황을 다시 게시합니다.

이는 로컬 사용 시 필수 사항이 아닙니다. DISCORD_BOT_TOKEN이 비어 있으면 백엔드는 정상적으로 시작되며 Discord를 건너뜁니다.

전체 설정 가이드: docs/DISCORD.md.

flowchart LR
U["사용자 또는 IM 명령"] --> BS["Bootstrap Skill / API / IM 진입점"]
BS --> SP["Plan Supervisor"]
...

백엔드 그래프 (Backend graph): server/apps/backend/src/modules/graph-agent/graph/

작업 API (Task APIs): server/apps/backend/src/modules/task/task.controller.ts

대기 전달 (Standby dispatch): server/apps/backend/src/common/ws/standby.gateway.ts

IM 채널 전달 (IM channel dispatch): server/apps/backend/src/modules/im-channel/

Android 대기 연결 (Android standby connection): client/core_network/src/main/java/com/coremate/opengui/network/websocket/StandbySocketManager.kt

Android 실행 경로 (Android execution path): client/core_accessibility/src/main/java/com/coremate/opengui/accessibility/GestureService.kt

• skills/open-gui-bootstrap/SKILL.md
• docs/get-started.md
• server/apps/backend/README.md
• docs/DISCORD.md
• client/README.md
• CONTRIBUTING.md
• SECURITY.md
• CLAUDE.md

가장 유용한 프로젝트 피드백은 다음과 같습니다:

• 버그 및 기능 요청을 위한 open issues (오픈 이슈) 작성
• 실제 사용 사례 및 배포 피드백 공유
• 문서, 통합 및 수정 사항 기여

OpenGUI는 Business Source License 1.1 (BUSL-1.1)에 따라 소스 공개(source-available) 상태로 제공됩니다.

귀하는 비운영(non-production) 목적으로 소스를 복제, 수정, 배포 및 사용할 수 있습니다. 운영(Production) 사용, 상업적 이용, 호스팅 서비스 및 상업적 제품으로의 통합은 Core-Mate로부터 별도의 상업용 라이선스(commercial license)를 취득해야 합니다.

본 버전에 대하여:

• 변경 날짜 (Change Date): 2030-04-29
• 변경 라이선스 (Change License): Apache License, Version 2.0

이는 공개 소스(public source)이지만, 변경 날짜 전까지는 OSI 승인 오픈 소스(open source)가 아닙니다.

LICENSE를 참조하십시오.