# 안드로이드 에뮬레이터 매크로: 기기 추가와 adb 포트

> Macro Automation Studio의 안드로이드 에뮬레이터 매크로 기기 설정: 자동 검색되는 에뮬레이터, adb 포트 규칙, 포트로 기기 추가, 클라우드 기기와 휴대폰 연결을 다룹니다.

Source: https://automationmacro.com/ko/docs/devices (기기, updated 2026-09-05)

Macro Automation Studio(MAS)의 안드로이드 에뮬레이터 매크로는 기기에서 시작합니다: 이 컴퓨터의 Android 에뮬레이터, MAS 클라우드의 클라우드 기기, 또는 고급 경로로 본인의 휴대폰. 이 페이지는 MAS가 안드로이드 에뮬레이터를 찾는 방법, 매크로 기기로 추가하는 방법, 그리고 나머지 두 종류가 어디에 맞는지 설명합니다.

## 시작하기 전에

- MAS가 설치되어 있고 활성 체험 또는 요금제로 로그인한 상태. [MAS 설치](/docs/install)를 참고하세요. 체험용 MAS는 [다운로드 페이지](/download)에서 무료로 받을 수 있습니다.
- 에뮬레이터의 경우: 에뮬레이터가 실행 중이고 설정에서 ADB가 켜져 있어야 합니다. 위치는 [BlueStacks](/docs/bluestacks-setup-guide), [LDPlayer](/docs/ldplayer-setup-guide), [MuMu Player](/docs/mumu-setup-guide), [MEmu](/docs/memu-setup-guide) 가이드에 있습니다.
- 클라우드 기기의 경우: 클라우드 기기 추가 옵션이 있는 요금제. [클라우드 기기](/docs/cloud-devices)를 참고하세요.

## MAS가 에뮬레이터 adb 포트를 찾는 방법

MAS는 에뮬레이터를 찾기 위해 `adb devices`를 실행하지 않습니다. 실행 중인 프로세스에서 알려진 에뮬레이터 이름을 찾고, 각 프로세스가 수신하는 TCP 포트를 읽은 뒤, 그 에뮬레이터의 알려진 범위 안에 있는 포트만 남깁니다. `127.0.0.1`, `0.0.0.0` 또는 모든 인터페이스에 바인딩된 포트만 인정합니다. 그 결과가 **Add New Device** 대화 상자의 **Port** 목록을 채우며, 포트마다 에뮬레이터 이름이 옆에 붙은 항목 하나가 표시됩니다.

| 에뮬레이터 | MAS가 찾는 프로세스 이름 | MAS가 인정하는 포트 |
|---|---|---|
| BlueStacks | `HD-Player`, `BlueStacks` | 5555부터 8500까지 |
| LDPlayer | `LdVBoxHeadless`, `Ld9BoxHeadless`, `dnplayer`, `LDPlayer`, `VBoxNetNAT` | 5555부터 5599까지의 홀수 포트 |
| Nox | `NoxVMHandle` | 62001부터 63000까지 |
| MEmu | `MEmuHeadless`, `MEmuHyper` | 21503과 그 위로 3으로 끝나는 30000 미만의 모든 포트 |
| MuMu Player | `NemuHeadless`, `MuMu` | 5555부터 5599까지의 홀수 포트, 7555, 16384부터 16576까지, 또는 26624부터 27264까지 |

에뮬레이터 인스턴스마다 자기 포트로 수신하므로 BlueStacks 창 두 개는 항목 두 개로 나타납니다. 사용하는 에뮬레이터가 표에 없거나 범위 밖 포트를 쓰더라도 포트를 직접 입력할 수 있습니다.

> [!TIP]
> MAS는 프로세스를 스캔하므로 기기를 추가하는 동안 에뮬레이터 창을 열어 두세요. 멈춘 인스턴스에는 찾을 포트가 없습니다.

## 안드로이드 에뮬레이터를 자동화 기기로 추가

1. MAS에서 **Device Groups**를 열고 **Create New Group**을 클릭합니다.
2. **Name**(3자에서 255자)을 입력하고 유형은 **Local**로 둔 채 **Create Group**을 클릭합니다.
3. 그룹을 열고 **Add Device**를 클릭합니다.
4. 최대 50자의 **Device Name**을 입력합니다.
5. **Port**에서 포트를 고릅니다. 다시 스캔하려면 **Refresh**를 클릭합니다. 포트가 없으면 **Custom Port**를 선택하고 직접 입력합니다(1024부터 65535까지).
6. 필요하면 **Startup Macro**를 고릅니다.
7. **Add Device**를 클릭합니다.

기기 카드에는 포트, 매크로, 상태가 표시됩니다: Stopped, Connecting, Starting, Running, Stopping 또는 Error. **Start**는 `adb connect 127.0.0.1:<port>`로 에뮬레이터에 연결하고 매크로를 실행하며, **Stop**은 실행을 끝냅니다. 포트 하나는 기기 하나에만 속할 수 있어 두 번 추가하면 "Port is already in use"로 실패합니다. 나중에 포트를 바꾸려면 **Edit Device**를 클릭합니다.

한 그룹의 여러 기기가 서로 다른 매크로, 인수, 설정 프로필을 가질 수 있고, **Start All**이 차례로 실행합니다. [기기 그룹](/docs/device-groups)을 참고하세요.

## 클라우드 기기

클라우드 기기는 MAS가 대신 실행해 주는 Android 기기입니다. **Cloud Devices** 페이지에서 **Create**로 만들며, Android 버전, 디스플레이 프리셋, DPI를 고르면 기기가 존재하는 동안 고정됩니다. **Start**가 부팅하고, **View**가 WebRTC로 스트리밍되는 실시간 화면을 열고, **Run**이 앱을 닫아도 계속되는 매크로를 실행합니다. 정지된 기기는 데이터를 유지하며, 계정당 클라우드 기기를 최대 20대까지 둘 수 있습니다. APK 설치와 할당량을 포함한 나머지는 [클라우드 기기](/docs/cloud-devices) 페이지에 있습니다.

## 본인 휴대폰

> [!WARNING]
> 휴대폰 조작은 앱에서 테스트된 기능이 아닙니다. 아래 단계는 MAS가 기기에 연결하는 방식에서 따라 나온 것이며, MAS 팀이 모든 휴대폰에서 검증하지는 않았습니다. 잘 되지 않으면 [Discord](https://discord.gg/macroautomationstudio)에서 물어보세요.

MAS는 모든 로컬 기기를 포트로 추가하고 항상 `127.0.0.1`로 연결합니다. USB 페어링 화면도 무선 페어링 화면도 없습니다. 따라서 휴대폰은 adb 데몬이 이 컴퓨터의 TCP 포트로 도달 가능할 때만 동작합니다. USB로는 adb 포트 포워딩으로 가능합니다.

1. 휴대폰에서 **개발자 옵션**과 **USB 디버깅**을 켠 뒤 휴대폰을 연결합니다.
2. 컴퓨터에서 `adb devices`를 실행하고 휴대폰의 승인 요청을 수락합니다. 휴대폰 시리얼이 `device`로 표시되어야 합니다.
3. 휴대폰의 adb 데몬이 TCP로도 수신하게 합니다: `adb tcpip 5555`.
4. 로컬 포트를 거기에 포워딩합니다: `adb forward tcp:5580 tcp:5555`. 비어 있는 로컬 포트라면 무엇이든 되며 5580은 예시입니다.
5. 확인합니다: `adb connect 127.0.0.1:5580`이 "connected"를 표시해야 합니다.
6. MAS에서 **Custom Port**를 `5580`으로 설정해 기기를 추가합니다.

휴대폰을 연결한 채 화면을 켜 두세요. 화면 크기와 DPI는 휴대폰에서 오므로 에뮬레이터에서 자른 템플릿은 맞지 않습니다. Asset Lab에서 휴대폰 화면으로 다시 자르세요.

> [!NOTE]
> MAS는 연결할 때 자체 adb 서버를 시작합니다. PATH에 다른 adb 빌드가 먼저 있으면 서버가 서로를 교체해 포워딩이 사라집니다. MAS를 먼저 시작한 뒤 MAS가 쓰는 것과 같은 adb 빌드로 포워딩을 설정하거나, `adb kill-server`를 실행하고 4단계를 반복하세요.

무선 디버깅도 휴대폰을 페어링하고 `adb connect <phone-ip>:<port>`로 연결한 뒤에는 같은 방식으로 동작합니다. 로컬 포트를 휴대폰의 adb 포트로 포워딩하고 그 로컬 포트를 MAS에 추가하세요.

## 파이썬으로 제어

SDK는 아래에 어떤 종류의 기기가 있는지 신경 쓰지 않습니다. `mas.get_device_info()`는 이름과 화면 크기를, `mas.get_screen_size()`는 크기만 반환하며, 모든 탭, 스와이프, 스크린샷은 같은 호출을 거칩니다. 스크립트는 기기가 이미 바인딩된 상태로 MAS가 실행하므로 코드에서 연결할 것이 없습니다. [SDK 개요](/docs/sdk)부터 시작하세요.

## 문제 해결

### Port 목록이 비어 있음

에뮬레이터가 실행 중이 아니거나, 설정에서 ADB가 꺼져 있거나, MAS가 스캔하는 에뮬레이터가 아닙니다. 에뮬레이터 부팅이 끝난 뒤 **Refresh**를 클릭하세요. 그래도 비어 있으면 에뮬레이터 설정에 표시된 포트로 **Custom Port**를 사용하세요. [ADB 문제 해결](/docs/adb-troubleshooting)을 참고하세요.

### Port is already in use

내 그룹의 다른 기기가 이미 그 포트를 갖고 있습니다. 포트는 한 번만 추가할 수 있습니다. 기존 항목을 제거하거나 다른 인스턴스의 포트를 고르세요.

### 기기가 Connecting에 머물거나 Error로 끝남

MAS가 `adb connect`를 완료하지 못했거나 에뮬레이터가 첫 명령을 거부했습니다. 포트를 확인하고, ADB가 켜져 있는지 확인한 뒤 [ADB 문제 해결](/docs/adb-troubleshooting)을 따르세요.