왜 클라이언트가 실행 직후 크래시되는가
Clash 계열 클라이언트(Clash Verge, Clash Meta 클라이언트, mihomo 커널 기반의 각종 그래픽 인터페이스 포함)는 구조상 두 개의 계층으로 나뉩니다. 상위 계층은 화면, 시스템 트레이, 구독 관리를 담당하는 클라이언트 프로세스이고, 하위 계층은 실제 트래픽 전달을 처리하는 커널 프로세스(보통 mihomo 또는 그 전신인 Clash Premium)입니다. 크래시는 어느 계층에서든 발생할 수 있으며 원인도 완전히 다릅니다. 클라이언트 화면 프로세스가 죽는 것은 대체로 설치 손상, 의존 라이브러리 누락, 시스템 권한 문제 때문이고, 커널 프로세스가 죽는 것은 거의 항상 설정 파일, 포트 충돌, 잔류 프로세스 중 하나로 귀결됩니다.
재설치를 시도하기 전에 먼저 "화면 자체가 안 뜨는지", "화면은 뜨지만 연결하는 순간 꺼지는지", "부팅 시 자동 실행 후 순식간에 사라지는지"를 구분해야 합니다. 이 세 가지 증상은 확인해야 할 경로가 완전히 다르며, 무작정 삭제 후 재설치해서는 근본 원인을 해결하지 못하고 다음 업데이트에서 다시 재발할 수 있습니다.
1단계: 추측하지 말고 로그를 확인하라
거의 모든 크래시 상황의 첫 번째 실마리는 로그에 있습니다. 이 단계를 건너뛰고 "안 열림" 관련 검색부터 하는 것은 시간 낭비입니다. 로그는 보통 두 가지로 나뉩니다: 클라이언트 자체 실행 로그와 커널이 출력하는 연결 로그입니다.
- Windows: 클라이언트 로그는 보통 사용자 디렉터리의
AppData\Roaming또는AppData\Local안에 있는 해당 제품명 폴더에 저장되며, 하위 디렉터리 이름에logs가 포함됩니다. 커널 로그는 설정 디렉터리의logs하위 폴더에 날짜별로 저장됩니다. - macOS: 클라이언트 로그는 대부분
~/Library/Logs/안 해당 제품명 폴더에 저장됩니다. "콘솔" 앱을 열어 프로세스 이름으로 필터링하면 크래시 시 시스템이 던진 예외 스택도 확인할 수 있습니다.
가장 최근 로그 파일을 열어 다음 세 가지 키워드를 중점적으로 찾으세요:
yaml: line또는unmarshal—— 설정 파일 문법 또는 필드 타입 오류;bind: address already in use—— 포트 충돌;panic또는fatal error—— 커널 런타임 크래시, 대개 호출 스택이 함께 출력됨.
해당 오류 원문을 복사해두면, 이후 3단계는 오류 유형에 맞춰 대응하는 것으로 충분하며 로그 전체를 다 읽을 필요는 없습니다.
time="2026-05-20T21:14:02+08:00" level=fatal msg="Parse config error: yaml: line 47: mapping values are not allowed in this context"위와 같은 오류는 설정 파일 47번째 줄 근처에 문제가 있다는 뜻으로, 보통 들여쓰기가 한 칸 틀렸거나 콜론 뒤에 콜론이 하나 더 들어간 경우입니다. 클라이언트 자체 문제라고 의심할 필요는 없습니다.
2단계: 캐시와 잔류 커널 프로세스 정리
로그에 명확한 설정 오류가 없는데도 클라이언트가 실행되다 절반쯔음에서 사라진다면, 로컬 캐시 파일 손상이나 지난번 비정상 종료로 남은 좀비 커널 프로세스가 리소스를 차지하고 있을 가능성이 큽니다. 처리 방법:
- 먼저 작업 관리자(Windows) 또는 활성 상태 보기(macOS)에서 커널 프로세스 이름(주로
mihomo,clash-meta또는clash)을 검색하세요. 이미 실행 중인 인스턴스가 있다면 먼저 수동으로 종료한 후 클라이언트를 다시 실행하세요. - 클라이언트를 종료한 후 설정 디렉터리의 캐시 파일(보통
cache.db또는 유사한 이름, 구독 설정yaml파일은 삭제하지 마세요)을 삭제하세요. 이런 캐시 파일 손상은 업그레이드 후 크래시가 발생하는 흔한 원인입니다. - 클라이언트에 "패널 캐시 초기화" 또는 "기본 설정으로 복원" 기능이 있다면, 수동으로 파일을 삭제하는 것보다 이 내장 초기화 기능을 우선 사용하는 것이 더 안전하며 구독 정보를 잘못 삭제할 위험이 없습니다.
- 클라이언트를 다시 실행해 정상적으로 작동하는지 확인하세요.
3단계: 포트 충돌 확인
Clash 계열 클라이언트는 실행 시 여러 로컬 포트를 바인딩해야 합니다: HTTP/Mixed 프록시 포트(기본값 예: 7890), 컨트롤 패널 포트(기본값 예: 9090), 그리고 TUN 모드를 켤 때 사용되는 가상 네트워크 카드 관련 포트입니다. 이 포트들이 이미 다른 프로그램에 의해 점유되어 있으면 커널 프로세스가 바로 실행에 실패하고, 클라이언트 화면이 잠깐 나타났다 사라지거나 "연결 중" 상태에서 멈추는 증상으로 나타납니다.
확인 방법:
- Windows: 명령 프롬프트를 열고
netstat -ano | findstr 7890을 실행하세요(7890은 실제 설정에서 사용하는 포트로 바꾸세요). 출력이 있다면 해당 포트가 이미 점유된 상태이며, 마지막 열의 프로세스 PID를 기록한 후 작업 관리자에서 해당 프로세스를 찾아 종료할지 결정하세요. - macOS: 터미널을 열고
lsof -i :7890을 실행하면 동일하게 해당 포트를 점유하고 있는 프로세스 이름과 PID를 확인할 수 있습니다.
흔한 포트 충돌 원인으로는 두 개의 Clash 계열 클라이언트를 동시에 설치한 경우(예: 신구 버전이 완전히 제거되지 않음), 시스템에 다른 프록시 도구가 실행 중인 경우, 또는 지난번 커널 프로세스가 정상 종료되지 않아 좀비 프로세스가 포트를 계속 점유하고 있는 경우가 있습니다. 충돌 원인을 확인한 뒤 불필요한 프로세스를 종료하거나, 설정 파일의 port, external-controller를 다른 사용 가능한 포트로 바꾼 뒤 저장하고 다시 실행하세요.
mixed-port: 7891
external-controller: 127.0.0.1:90914단계: 설정 파일 문법 검증
YAML 형식은 들여쓰기와 콜론 뒤 공백에 매우 민감해서, 수동으로 설정을 수정하거나 여러 출처의 규칙을 합칠 때 문법 오류가 쉽게 발생합니다. 로그에 표시된 줄 번호를 확인하는 것 외에도 다음과 같은 방법으로 미리 자체 점검할 수 있습니다:
- 모든 줄의 콜론 뒤에 공백이 있는지 확인하세요. YAML 규칙상
key: value사이에 공백이 반드시 필요하며,key:value로 쓰면 일반 문자열로 인식되어 파싱에 실패합니다. - 들여쓰기가 일관되게 공백으로만 이루어져 있는지 확인하세요. Tab과 공백을 혼용하지 말고, 같은 계층의 들여쓰기 공백 수는 반드시 일치해야 합니다.
proxy-groups에서 참조하는 프록시 이름이proxies목록에 실제로 존재하는지 확인하세요. 표기가 일치하지 않으면 참조 대상을 찾지 못하고, 일부 클라이언트는 오류 메시지 대신 곧바로 크래시를 일으킵니다.- 설정이 구독 링크에서 자동 생성된 것이라면, 먼저 클라이언트 내장 "설정 검증" 또는 "문법 검사" 기능을 사용해 보세요. 대부분의 그래픽 클라이언트는 설정 메뉴에서 이 기능을 제공합니다.
끝까지 확인한 결과 구독 제공자 쪽에서 전달한 설정 자체에 문제가 있는 것으로 밝혀졌다면, 우선 정상 작동이 확인된 예전 설정으로 임시 전환해 클라이언트 자체에 문제가 없음을 확인한 후 구독 제공자에게 문의하세요.
Windows와 macOS 크래시 사례 비교
| 증상 | Windows 흔한 원인 | macOS 흔한 원인 |
|---|---|---|
| 아이콘 클릭 시 반응 없음, 화면이 전혀 나타나지 않음 | 설치 디렉터리 파일이 보안 소프트웨어에 의해 삭제 또는 차단됨, 재설치 후 신뢰 목록에 추가 | 앱이 "손쉬운 사용" 또는 "네트워크 확장" 권한을 얻지 못함, 시스템 설정에서 수동으로 허용 필요 |
| 화면이 열린 후 몇 초 안에 자동으로 종료됨 | 캐시 파일 손상, 또는 이전 버전 잔류 파일과 충돌 | Gatekeeper가 서명되지 않은 구성 요소를 차단, 최초 실행 시 "개인정보 보호 및 보안"에서 허용 필요 |
| "연결" 클릭 또는 구독 불러오기 후 크래시 | 설정 파일 문법 오류 또는 포트 충돌 | 설정 파일 문법 오류 또는 포트 충돌 (시스템과 무관, 양쪽 동일) |
| TUN 모드 활성화 후 크래시 | 가상 네트워크 카드 드라이버가 제대로 설치되지 않음, 관리자 권한으로 재설치 필요 | 시스템 확장이 승인되지 않음, "개인정보 보호 및 보안"에서 수동 허용 후 재시작 필요 |
| 부팅 시 자동 실행 후 흔적 없이 사라짐 | 자동 시작 항목이 네트워크 서비스 준비보다 먼저 실행되어 커널이 포트 바인딩에 실패함 | 로그인 항목 권한이 불완전함, 기존 로그인 항목을 삭제하고 다시 추가하는 것을 권장 |
여전히 해결되지 않는다면 이 순서로 마지막 점검
위 네 단계를 모두 거쳐도 문제가 여전하다면 다음 순서로 마지막 점검을 진행하세요. 대부분의 남은 사례를 커버할 수 있습니다:
- 다운로드한 설치 파일이 시스템 아키텍처와 맞는지 확인하세요. 예를 들어 Windows ARM 기기에 x64 버전을 설치하거나, macOS Intel 칩에 Apple Silicon 전용 빌드를 설치하면 실행 오류가 발생합니다.
- 완전히 제거한 후 남아 있는 설정 디렉터리를 수동으로 삭제하세요(구독 링크는 미리 백업). 그런 다음 최신 버전을 재설치하면 버전 간 업그레이드로 남은 필드 비호환 문제를 피할 수 있습니다.
- 보안 소프트웨어나 방화벽을 임시로 끄고 대조 테스트를 해보세요. 끄면 정상적으로 실행된다면, 보안 소프트웨어의 실시간 보호가 커널 프로세스를 차단하고 있는 것이므로 클라이언트를 화이트리스트에 추가해야 합니다.
- 제3자 경로로 다운로드한 설치 파일이라면, 공식 다운로드 경로에서 다시 받는 것을 권장합니다. 설치 파일 자체가 변조되거나 손상되어 발생하는 실행 오류를 피할 수 있습니다.