문제 해결

문제를 살펴볼 때는 항상 이 두 명령부터 실행하세요. doctor는 설정을 점검하고, serve --verbose는 접속 시도를 일어나는 그대로 모두 보여 줍니다.

droidline doctor
droidline serve --verbose

아래에서 해당하는 증상을 찾으세요. 내 Wi-Fi를 벗어났을 때만 생기는 문제는 연결 문제 해결에 있습니다.

코드에서 서버가 실행 중이 아니라고 나올 때

SERVER_NOT_RUNNING(Python에서는 ServerNotRunningError)은 127.0.0.1:8780에서 아무것도 응답하지 않았다는 뜻입니다.

• droidline serve를 실행하고 창을 열어 두세요. 창을 닫으면 서버가 멈춥니다.
• config.toml의 client.listen을 바꿨거나 DROIDLINE_HOST, DROIDLINE_PORT를 설정했다면, 코드도 같은 주소를 쓰는지 확인하세요.
• droidline doctor는 시도한 주소와, 에이전트 포트가 비어 있는지를 보여 줍니다.

서버가 시작되지 않을 때

"address already in use" 같은 에러는 다른 프로그램이 Droidline의 포트 중 하나를 쓰고 있다는 뜻입니다. 포트는 폰용 8779, 내 코드용 8780, Wi-Fi 탐색용 8778입니다.

• 다른 창이나 서비스로 droidline serve가 이미 실행 중일 수 있습니다. 먼저 그것을 멈추세요.
• 다른 포트를 쓰려면 config.toml에서 agent.listen, client.listen, discovery.listen을 바꾸세요. 폰은 다음에 페어링할 때 새 에이전트 포트를 알게 됩니다.

폰이 PC를 찾지 못할 때

이 Wi-Fi에서 페어링을 누르면 "응답한 PC가 없습니다"가 나오거나, 페어링한 뒤에도 폰이 전혀 접속하지 않는 경우입니다.

1. 두 기기가 같은 Wi-Fi 네트워크에 있는지 확인하세요. 게스트 네트워크와 일부 메시 시스템은 기기끼리 통신하지 못하게 막습니다. 기본 네트워크를 쓰세요.

2. Windows에서는 네트워크를 개인 네트워크로 설정하세요. 설정, 네트워크 및 인터넷, Wi-Fi, 사용 중인 네트워크, 네트워크 프로필 유형: 개인 네트워크 순서입니다. Windows는 공용 네트워크에서 들어오는 연결을 막습니다.

3. 개인 네트워크에서 droidline이 방화벽을 통과하도록 허용하세요. 허용 여부를 묻는 창을 닫아 버렸다면 Windows 보안, 방화벽 및 네트워크 보호, 방화벽에서 앱 허용을 차례로 열고 droidline의 개인에 체크하세요. 또는 관리자 권한 PowerShell에서 다음을 실행합니다.

   New-NetFirewallRule -DisplayName "Droidline" -Direction Inbound -Action Allow -Profile Private -Program "C:\Tools\droidline\droidline.exe"

4. macOS에서는 시스템 설정, 네트워크, 방화벽, 옵션을 차례로 열고 droidline에 대해 들어오는 연결을 허용하세요.

5. PC에서 VPN이 실행 중이면 로컬 네트워크에서 PC가 보이지 않을 수 있습니다. 페어링하는 동안 VPN을 잠시 멈추거나, PC 주소가 담긴 QR 코드로 페어링하세요.

그래도 6자리 코드 방식이 안 되면 대개 QR 코드는 됩니다. droidline pair를 실행하고 QR 코드를 스캔하세요.

페어링이 실패할 때

• PC에서 PAIRING_FAILED가 나오면 그 코드로 기다리는 폰이 없다는 뜻입니다. 코드는 5분 뒤 만료됩니다. 이 Wi-Fi에서 페어링을 다시 눌러 새 코드를 받으세요.
• QR 코드는 10분 동안 유효하고 폰 한 대만 페어링합니다. 다음 폰은 droidline pair를 다시 실행하세요.
• 앱에 PC가 이 폰을 알아보지 못한다고 나오면, droidline revoke로 폰이 제거됐거나 서버의 설정 폴더가 지워졌거나 옮겨진 것입니다. 다시 페어링하세요.

화면이 꺼지면 폰이 오프라인이 될 때

안드로이드와 많은 폰 제조사는 배터리를 아끼려고 백그라운드 앱을 멈춥니다. Droidline은 연결을 계속 열어 두어야 합니다.

1. Droidline의 설정 탭에서 배터리 최적화를 제한 없음으로 설정합니다.

2. 제조사가 따로 두는 백그라운드 앱 설정을 찾아, 각각에서 Droidline을 허용합니다. 보통 다음과 같은 곳에 있습니다.

   제조사	찾아볼 곳
   Samsung	설정, 배터리, 백그라운드 사용 제한: 절전 앱과 초절전 앱에서 Droidline을 빼거나, 절전 예외 앱에 추가
   Xiaomi, Redmi, POCO	앱 정보, Autostart 켜기, Battery saver: No restrictions
   OPPO, OnePlus, realme	앱 정보, 배터리 사용량, Allow background activity와 Allow auto launch
   vivo	설정, 배터리, Background power consumption management: Droidline 허용
   Huawei, Honor	설정, 배터리, App launch: Droidline을 Manage manually로 바꾸고 스위치를 모두 켜기

   메뉴 이름은 버전마다 다릅니다. 이름이 다르면 설정에서 "배터리"나 "백그라운드"로 검색하세요.

3. 사람이 지켜보지 않는 폰이라면 계속 충전해 두세요.

앱의 상태 탭에 연결 상태와 사용 중인 경로가 나옵니다. 앱이 잠든 것인지 네트워크 문제인지 구분할 때 도움이 됩니다.

접근성 스위치가 회색으로 비활성화될 때

Android 13 이상에서는 파일로 설치한 앱은 제한된 설정을 허용하기 전까지 접근성을 쓸 수 없습니다.

1. 설정, 앱, Droidline을 차례로 엽니다(또는 Droidline 앱의 설정 탭에서 앱 정보를 누릅니다).
2. 오른쪽 위의 점 세 개 메뉴를 누르고 제한된 설정 허용을 고릅니다.
3. 접근성 설정으로 돌아가 Droidline을 켭니다.

메뉴 항목이 없다면 먼저 접근성 설정을 한 번 열어 안드로이드가 시도를 기록하게 한 다음, 다시 찾아보세요.

접근성이 자꾸 저절로 꺼질 때

이때 명령은 NO_ACCESSIBILITY로 실패합니다. 일부 폰은 앱이 업데이트된 뒤, 앱이 비정상 종료된 뒤, 또는 절전 기능이 앱을 종료했을 때 접근성 서비스를 끕니다.

• 설정 탭에서 다시 켜세요.
• 위의 배터리 관련 단계를 적용하세요. 대부분은 이것으로 막을 수 있습니다.
• Droidline 앱 업데이트를 설치한 뒤에는 설정 탭을 한 번 확인하세요.

눈에 보이는 요소를 명령이 찾지 못할 때

요소가 화면에 있는데도 NOT_FOUND가 나오는 경우입니다. 요소 찾기의 점검 목록을 차례로 확인하세요. 흔한 원인은 다음과 같습니다.

• 텍스트가 조금 다릅니다. 대소문자, 끝에 붙은 공백, 다른 언어 등입니다. 값은 droidline dump에서 복사하세요.
• 요소가 권한 대화상자 같은 시스템 창에 있습니다. all_windows=True로 dump하세요.
• 화면에 요소가 전혀 없습니다(게임, 지도, 캔버스로 그린 페이지). 좌표와 함께 tap을 쓰세요.

입력이 안 될 때

• NO_IME: Droidline 키보드가 켜져 있지 않거나 선택되어 있지 않습니다. 설정 탭에서 켜고 선택하세요.
• 텍스트는 들어가는데 앱이 반응하지 않습니다. 예를 들어 Enter를 기다리는 검색창입니다. input 다음에 sendkey("enter")를 호출하세요.
• input이 남겨 두고 싶던 텍스트를 바꿔 버렸습니다. append=True를 넘기세요.

Android 9나 10에서 스크린샷이 실패할 때

Android 11 이전에는 스크린샷을 찍으려면 안드로이드의 화면 캡처 권한이 필요합니다. 처음 screenshot을 호출하면 폰에 확인 창이 뜹니다. 지금 시작을 누르세요. 누군가 허용하기 전까지 screenshot은 NO_PERMISSION으로 실패하고, droidline devices의 MISSING에 capture가 나옵니다.

kill, clear_data, 네트워크 전환이 실패할 때

이 명령들은 안드로이드 설정 앱의 버튼을 대신 누릅니다. 설정 앱은 제조사와 Android 버전마다 다릅니다. MACRO_FAILED는 어느 단계를 찾지 못했는지 알려 줍니다.

• 화면이 켜져 있고 잠금이 풀려 있는지 확인하세요. 먼저 wake()를 호출하세요.
• 다시 시도하세요. 이 에러는 재시도할 만한 에러로 표시되어 있고, 느린 폰이 단순히 늦었을 수도 있습니다.
• 특정 폰 모델에서 매번 실패한다면 폰 모델, Android 버전, 언어를 적어 제보해 주세요. 이런 제보가 있어야 이 바로가기가 새 폰을 익힐 수 있습니다.

여러 폰이 온라인이고 명령이 실패할 때

DEVICE_AMBIGUOUS는 온라인인 폰이 둘 이상인데 명령이 어느 폰인지 지정하지 않았다는 뜻입니다. connect("shelf-01"), --device shelf-01, /devices/shelf-01/...로 폰을 지정하거나 DROIDLINE_DEVICE를 설정하세요.

명령이 AGENT_RESTARTED로 실패할 때

명령을 처리하는 도중에 폰의 Droidline 앱이 재시작돼서, 명령이 실행됐는지 Droidline이 알 수 없는 상태입니다. 화면을 확인한 다음, 다시 실행해도 안전한지 판단하세요. 재시작이 잦다면 대개 위의 배터리 설정이 원인입니다.

그래도 해결되지 않으면

GitHub에 이슈를 열어 주세요. droidline doctor 출력, 폰 모델과 Android 버전, 문제를 재현하는 가장 짧은 스크립트를 함께 적어 주세요. 토큰, 비밀번호, 개인 정보는 빼세요.