# 블루스택 ADB 연결과 포트 설정: MAS에 BlueStacks 추가 > BlueStacks 5에서 ADB를 켜고 ADB 포트를 찾아 Macro Automation Studio에 연결하고, Windows와 Mac에서 기기를 찾을 수 없음, offline 오류를 해결합니다. Source: https://automationmacro.com/ko/docs/bluestacks-setup-guide (기기, updated 2026-09-05) 이 가이드는 블루스택 ADB 연결 방법을 보여 줍니다: ADB를 켜고, ADB 포트를 찾고, BlueStacks 인스턴스를 Macro Automation Studio(MAS)에 기기로 추가합니다. 블루스택 ADB 연결은 Windows의 BlueStacks 5와 Apple Silicon Mac용 BlueStacks 빌드를 다루며, 사람들이 가장 자주 만나는 오류로 마무리합니다. ## 시작하기 전에 - Windows 10 또는 11, 또는 Apple Silicon Mac에 MAS가 설치되어 있고 로그인한 상태. 체험용 MAS는 [다운로드 페이지](/download)에서 무료로 받을 수 있습니다. - [bluestacks.com](https://www.bluestacks.com/)에서 BlueStacks를 설치하고 한 번 실행한 상태. - 인스턴스가 Android 홈 화면까지 완전히 부팅된 상태. - 자동화할 앱이 BlueStacks 안에 설치되어 있고 로그인된 상태. ## 1. BlueStacks 설치
1. 공식 사이트에서 BlueStacks 5를 받아 설치 프로그램을 실행합니다. 2. BlueStacks를 시작하고 홈 화면을 기다립니다. 3. MAS에 기기를 추가하기 전에 자동화할 앱을 설치하고 로그인합니다.
1. [bluestacks.com/mac](https://www.bluestacks.com/mac)에서 Apple Silicon 빌드인 BlueStacks Air를 받습니다. 2. DMG를 열고 **BlueStacks**를 **Applications**로 옮깁니다. 3. Applications에서 시작하고 홈 화면을 기다립니다.
BlueStacks 다운로드 및 설치 화면
최신 BlueStacks 5 빌드를 설치하고 첫 부팅이 끝날 때까지 기다립니다.
## 2. 권장 설정 MAS는 템플릿 이미지를 픽셀 단위로 비교하므로 템플릿을 캡처한 뒤에는 디스플레이가 바뀌면 안 됩니다. 측면 도구 모음의 톱니바퀴 아이콘으로 **Settings**를 열고 다음과 같이 설정합니다: | 탭 | 설정 | 값 | |---|---|---| | **Performance** | CPU allocation | 2코어. 개발 중에는 더 줘도 됩니다 | | **Performance** | Memory allocation | 4 GB 이상, 가능하면 더 | | **Display** | Resolution | 세로, 540 x 960 | | **Display** | Pixel density | 240 DPI | **Save changes**를 클릭하고 BlueStacks가 요청하면 인스턴스를 다시 시작합니다. MAS 기준선에 맞춰 작성된 매크로는 **540x960**, **240 DPI**를 기대합니다. 직접 쓴 매크로는 Asset Lab에서 캡처한 해상도를 기대합니다. 실행이 버벅이면 백그라운드 앱을 닫고 인스턴스에 코어와 메모리를 더 주세요.
BlueStacks 성능 및 디스플레이 설정
안정적인 MAS 인스턴스를 위한 Performance와 Display 설정.
> [!WARNING] > 템플릿을 캡처한 뒤 해상도나 DPI를 바꾸면 모든 매칭 위치가 어긋나고 클릭이 엉뚱한 곳에 떨어집니다. 디스플레이 설정은 한 번 정하고 유지하세요. ## 3. BlueStacks 5에서 ADB 켜기 BlueStacks는 ADB가 꺼진 채로 설치됩니다. MAS에는 켜져 있어야 합니다.
1. 측면 도구 모음의 톱니바퀴 아이콘을 클릭해 **Settings**를 엽니다. 2. **Advanced** 탭을 클릭합니다. 3. **Android Debug Bridge**를 켭니다. 4. **Save changes**를 클릭합니다. 5. 토글 아래에 표시되는 주소를 적어 둡니다. 예를 들어 `127.0.0.1:5555`입니다. 콜론 뒤의 숫자가 ADB 포트입니다. 첫 인스턴스는 보통 5555이며, 아래 스크린샷은 5625입니다.
1. 측면 도구 모음의 톱니바퀴 아이콘이나 상단 바의 메뉴 아이콘으로 **Settings**를 엽니다. 2. Android Debug Bridge 옵션을 찾습니다. 공식 BlueStacks Air 설정 안내에는 Performance, Display, Graphics, Preferences, About만 있고 ADB 토글이 없습니다. macOS용 이전 BlueStacks 빌드에는 Preferences에 있었습니다. 3. 빌드에 옵션이 있으면 켜고 저장한 뒤 `127.0.0.1` 뒤의 포트를 적어 둡니다. 4. 없으면 MAS는 이 빌드에 연결할 수 없습니다. Mac에서 ADB를 제공하는 다른 에뮬레이터나 [클라우드 기기](/docs/cloud-devices)를 사용하세요.
로컬 포트가 표시된 BlueStacks ADB 활성화 화면
Android Debug Bridge가 켜진 Advanced 탭. 여기서 포트는 5625입니다.
## 4. 블루스택 ADB 포트와 MAS의 스캔 방식 MAS는 에뮬레이터를 찾기 위해 `adb devices`를 실행하지 않습니다. 실행 중인 프로세스를 스캔해 다음 조건이 모두 맞는 포트만 남깁니다: - 프로세스 이름에 `hd-player` 또는 `bluestacks`가 들어 있습니다. - 포트가 5555에서 8500 사이입니다. - 소켓이 `127.0.0.1`, `0.0.0.0` 또는 모든 인터페이스에서 수신합니다. 조건에 맞는 포트는 **Add New Device** 대화 상자에 `Bluestacks` 레이블로 나타납니다. 예를 들어 `5555 - Bluestacks`입니다. MAS는 기기 그룹을 열 때와 **Refresh**를 클릭할 때마다 스캔합니다. BlueStacks 인스턴스마다 자기 포트로 수신하므로 인스턴스 두 개는 항목 두 개가 됩니다. ## 5. MAS에서 블루스택 ADB 연결 1. 사이드바에서 **Device Groups**를 열고 그룹을 열거나 새로 만듭니다. 2. **Add Device**를 클릭합니다. 3. 최대 50자의 **Device Name**을 입력합니다. 4. **Port**에서 이 인스턴스의 `Bluestacks` 항목을 고릅니다. 목록이 비어 있으면 **Refresh**를 클릭합니다. 5. BlueStacks가 MAS 목록에 없는 포트를 표시하면 **Custom Port**를 선택하고 입력합니다. MAS는 1024부터 65535까지 받습니다. 6. 필요하면 **Startup Macro**를 고릅니다. 7. **Add Device**를 클릭한 뒤 기기 카드에서 **Start**를 클릭합니다. 카드가 **Connecting**을 거쳐 **Running**으로 바뀝니다. MAS는 자체 adb 서버를 시작하고, `127.0.0.1:`의 오래된 항목을 제거한 뒤, 그 주소로 `adb connect`를 실행합니다. ## BlueStacks의 매크로 BlueStacks 자체 매크로 녹화기는 고정 좌표의 탭을 재생합니다. MAS 매크로는 화면을 먼저 보는 파이썬 스크립트입니다: 템플릿 매칭으로 버튼을 찾고, OCR로 텍스트를 읽고, 재시도로 느린 로딩이나 팝업을 흡수합니다. [시작하기](/docs/getting-started)에서 첫 매크로를 실행하고, [이미지 인식 매크로](/docs/guides/image-recognition-macros)에서 녹화한 루틴을 화면 인식 매크로로 다시 만들고, [스케줄러](/docs/scheduler)로 매일, 매주, 매월 실행합니다. > [!NOTE] > MAS에서 기기를 시작하기 전에 BlueStacks 녹화기를 멈추세요. 둘 다 같은 화면에 입력을 보내 서로 방해합니다. ## 여러 BlueStacks 인스턴스 **Multi-Instance Manager**에서 만든 인스턴스는 각각 자기 ADB 포트로 수신합니다. 같은 기기 그룹에 각각 별도 기기로 추가하고, 각각 매크로와 설정 프로필을 지정한 뒤, 그룹의 **Start All**과 **Stop All**을 사용하세요. 기기별 인수와 프록시는 [기기 그룹](/docs/device-groups)을 참고하세요. ## 문제 해결 ### BlueStacks 5에서 ADB 켜기 MAS의 **Port** 목록이 비어 있고 `adb connect 127.0.0.1:5555`가 "cannot connect" 또는 "connection refused"로 응답합니다. ADB가 꺼져 있습니다. **Settings**를 열고 **Advanced**를 클릭한 뒤 **Android Debug Bridge**를 켜고 **Save changes**를 클릭하고 인스턴스를 다시 시작한 다음, **Add New Device**에서 **Refresh**를 클릭하세요. **Advanced** 탭에 그런 토글이 없으면 공식 사이트에서 최신 BlueStacks 5를 설치하세요. ### ADB 포트 찾기 또는 바꾸기 포트는 **Android Debug Bridge** 토글 아래에 `127.0.0.1:`로 표시됩니다. BlueStacks는 시작할 때 포트를 배정하고 5555가 사용 중이면 다른 포트로 옮기므로, 인스턴스를 만들거나 복제하거나 삭제한 뒤 바뀔 수 있습니다. 공식 ADB 안내에는 직접 지정하는 항목이 없습니다. 바뀌면 MAS의 카드에서 **Edit Device**를 클릭하고 새 포트를 고르세요. 인스턴스를 같은 순서로 시작하면 포트가 안정적으로 유지됩니다. ### ADB 기기를 찾을 수 없음 카드가 "Failed to start device"와 함께 **Error**로 끝나거나, 로그에 "unable to connect to device"가 표시되거나, 스크립트가 `DeviceNotConnectedError`를 발생시킵니다. - 인스턴스가 아직 부팅 중입니다. 홈 화면을 기다린 뒤 **Start**를 다시 클릭하세요. - 카드의 포트가 BlueStacks에 표시된 포트와 다릅니다. **Edit Device**로 고치세요. - 업데이트가 ADB를 다시 껐습니다. **Advanced** 탭을 확인하세요. - 터미널에서 `adb connect 127.0.0.1:`를 실행하세요. "connected to"가 나오면 MAS도 연결됩니다. ### 기기가 offline으로 표시됨 `adb devices`에 `127.0.0.1: offline`이 나오고 명령이 멈춥니다. 인스턴스 안의 adb 데몬이 응답을 멈춘 것으로, 보통 절전, 업데이트, 또는 같은 컴퓨터의 두 번째 adb 서버 뒤에 일어납니다. 카드에서 **Stop**을 클릭하고, 인스턴스를 다시 시작하고, 자체 adb 서버를 실행하는 다른 도구를 닫은 뒤 **Start**를 클릭하세요. MAS가 처음부터 다시 연결합니다. 계속 offline이면 MAS를 다시 시작해 adb 서버를 깨끗하게 시작하세요. 더 많은 해결법은 [ADB 문제 해결](/docs/adb-troubleshooting)에 있습니다. ### Mac에서의 블루스택 ADB Mac에서는 두 가지가 다릅니다. 첫째, MAS에 adb 바이너리가 필요합니다. 앱 번들 안, PATH, Homebrew 폴더 순으로 찾습니다. MAS가 "ADB executable not found. Please install ADB using your package manager"를 표시하면 Homebrew로 adb를 설치하고 MAS를 다시 시작하세요: ```bash brew install android-platform-tools ``` 둘째, MAS는 항상 `127.0.0.1`로 연결하므로 BlueStacks가 같은 Mac에서 실행되며 ADB를 제공해야 합니다. BlueStacks Air는 Apple Silicon용 유일한 빌드이고 문서화된 설정에 ADB 토글이 없습니다. 토글이 없으면 MAS는 조작할 수 없습니다. ## 파이썬으로 제어 카드가 **Running**이면 매크로의 `src/app.py`가 `mas` 패키지로 BlueStacks를 조작합니다. 포트는 MAS가 고르므로 스크립트에서 참조할 일이 없습니다. ```python import mas size = mas.get_screen_size() mas.log(f"BlueStacks screen is {size.width}x{size.height}") match = mas.find_object_retry(1234, total_tries=3, time_sleep=2.0) if match: mas.click(match.x, match.y) ``` 모든 네임스페이스는 [SDK 개요](/docs/sdk)에서, 완전한 첫 스크립트는 [파이썬으로 안드로이드 에뮬레이터 제어하기](/docs/guides/control-an-emulator-from-python)에서 읽어 보세요.