Clash 클라이언트 실행 크래시 해결: 설정 파일 문법, 포트 충돌, 잔여 프로세스 정리

"실행이 안 됨"과 "실행 즉시 종료"를 구분해야 하는 이유

사용자들이 문제를 보고할 때 두 가지 현상을 뭉뚱그려 표현하는 경우가 많지만, 실제 점검 경로는 다릅니다. "실행이 안 됨"은 보통 아이콘을 클릭해도 아무 반응이 없고 프로세스 목록에서도 실행 파일을 찾을 수 없는 경우로, 대부분 시스템 권한, 런타임 라이브러리 누락, 설치 파일 자체 손상이 원인입니다. "실행 즉시 종료"는 프로세스가 실제로 실행되긴 했지만 창이 잠깐 나타나거나 스치듯 지나간 뒤 자동으로 사라지는 경우로, 흔한 원인은 설정 파일 파싱 실패, 커널 포트 충돌, 로컬 커널 잔여 프로세스가 리소스를 점유하고 있는 경우입니다. 두 현상을 구분하는 것이 문제를 빠르게 찾아내는 첫걸음입니다. 무작정 재설치로는 근본 원인을 해결하지 못하는 경우가 많으며, 특히 포트 충돌이나 잔여 프로세스 같은 문제는 몇 번을 재설치해도 그대로 남아 있습니다.

또한 Clash 계열 클라이언트(Clash Meta(mihomo) 커널 기반 구현 포함)는 구조상 두 계층으로 나뉩니다. 상위 계층은 그래픽 인터페이스(GUI)이고, 하위 계층은 실제로 트래픽을 처리하는 커널 프로세스입니다. GUI가 크래시되었다고 해서 커널에 문제가 있는 것은 아니며, 커널이 다운되어도 GUI는 멈춘 채 반응이 없는 형태로 나타날 수 있습니다. 점검할 때는 먼저 문제가 어느 계층에서 발생했는지 확인한 뒤 그에 맞게 대응하는 것이 좋습니다.

1단계: 로그를 확인하고 감으로 추측하지 않기

거의 모든 Clash 계열 클라이언트는 로컬에 실행 로그를 남기며, 로그에 담긴 오류 메시지는 여러 번 재시작하는 것보다 훨씬 많은 정보를 줍니다. 흔한 로그 위치는 다음과 같습니다:

• Windows: 클라이언트 설치 폴더 아래의 logs 폴더, 또는 사용자 디렉터리 %APPDATA% 내 해당 클라이언트의 하위 디렉터리.
• macOS: ~/Library/Logs/ 아래 해당 클라이언트 이름의 폴더, 또는 앱 내 "로그 폴더 열기" 메뉴.
• Linux: systemd 서비스로 실행되는 경우가 많으며 journalctl로 확인할 수 있습니다. 독립 실행 파일 형태라면 보통 로그가 터미널 표준 출력으로 출력됩니다.

클라이언트에 "터미널에서 실행" 또는 유사한 디버그 옵션이 있다면 먼저 이 방식으로 한 번 실행해 보세요. 그래픽 인터페이스가 크래시되면 오류 메시지를 미처 확인하기 어렵지만, 터미널 출력은 그대로 남아 한 줄씩 대조하며 확인할 수 있습니다.

원인 1: 설정 파일 문법 오류

Clash 설정 파일은 YAML 형식을 사용하며 들여쓰기와 특수 문자에 매우 민감합니다. 설정 파일을 직접 수동으로 편집했거나 구독 변환 스크립트가 생성한 내용이 규격에 맞지 않으면, 커널이 파싱 단계에서 곧바로 종료될 수 있습니다. 흔한 문법 문제는 다음과 같습니다:

1. 들여쓰기에 공백과 탭을 혼용했거나, 같은 계층 필드의 들여쓰기 폭이 일치하지 않는 경우.
2. 문자열에 이스케이프되지 않은 콜론이나 샵(#)이 포함되어 파서가 이를 새로운 키-값 쌍이나 주석 시작으로 잘못 인식하는 경우.
3. 규칙 세트(rule-providers)나 프록시 그룹(proxy-groups)에서 존재하지 않는 이름을 참조하여 커널이 검증 단계에서 오류를 내고 종료되는 경우.
4. 새 버전 커널에서 폐기된 필드명을 설정 파일에 그대로 남겨둬 필드 타입이 맞지 않는 경우.

점검 방법: 먼저 온라인 또는 로컬 YAML 검증 도구로 들여쓰기와 기본 문법이 올바른지 확인한 뒤, 클라이언트 사용 문서를 참고해 필드명이 현재 커널 버전에서 지원되는 표기법인지 대조합니다. 어느 줄에서 오류가 나는지 확실치 않다면 구간별로 주석 처리해 보는 방법이 있습니다. 먼저 포트, 모드, DNS 같은 가장 기본적인 필드만 남기고 정상 실행되는지 확인한 뒤, 프록시 노드와 규칙 세트를 하나씩 다시 추가하며 오류가 재현될 때까지 진행하면 문제가 되는 구간을 정확히 찾을 수 있습니다.

원인 2: 포트 점유

Clash 커널이 시작될 때는 로컬 포트를 바인딩해야 합니다. HTTP/SOCKS 프록시 포트, 외부 제어 포트(보통 9090 근처), TUN 모드를 켤 때 사용되는 가상 네트워크 카드 등이 포함됩니다. 이 포트들이 이미 다른 프로그램에 점유되어 있으면 커널이 바인딩에 실패하고 종료되며, GUI는 크래시되거나 커널 연결 실패 메시지를 표시합니다.

흔한 점유 원인: 완전히 종료되지 않은 다른 프록시 도구가 동시에 실행 중, 이전 실행의 커널 잔여 프로세스가 여전히 예전 포트를 감시 중, 또는 로컬 개발 도구(예: 로컬 디버그 서버)가 마침 같은 포트 범위를 사용 중인 경우 등입니다. 점검 절차:

• Windows: 명령줄에서 netstat -ano | findstr 7890을 실행합니다(포트 번호는 설정 파일에 실제로 지정한 값으로 교체). 반환된 PID를 기록한 뒤 작업 관리자나 tasklist /FI "PID eq 해당PID"로 어떤 프로그램인지 확인합니다.
• macOS / Linux: lsof -i :7890 또는 sudo lsof -i :9090을 실행해 포트를 점유한 프로세스를 확인합니다. 프로세스 이름을 보면 커널 잔여 프로세스인지 다른 프록시 소프트웨어인지 바로 알 수 있는 경우가 많습니다.

점유 원인을 확인한 뒤에는 점유 중인 프로세스를 종료하거나, 클라이언트 설정에서 혼합 포트와 외부 제어 포트를 비어 있는 값으로 바꿀 수 있습니다. 한 대의 기기에서 여러 프록시 도구를 번갈아 사용한다면, 매번 충돌을 수동으로 점검하지 않도록 각 도구에 서로 다른 포트 범위를 할당해두는 것을 권장합니다.

원인 3: 커널 잔여 프로세스

클라이언트가 비정상 종료되면(예: 프로세스 강제 종료, 시스템 절전으로 인한 중단, 업데이트 중 인터럽트) 커널 하위 프로세스가 GUI의 관리에서 벗어나 백그라운드에서 계속 실행되는 고립 프로세스가 되는 경우가 있습니다. 이런 잔여 프로세스는 이전에 설정된 포트를 계속 점유하며, 다음번에 클라이언트를 정상적으로 실행하면 새로 시작되는 커널이 같은 포트에 바인딩을 시도하다 실패해 실행 즉시 종료되는 형태로 나타납니다. 이때 로그에는 주소가 이미 사용 중이라는 메시지가 명확히 남습니다.

플랫폼별 정리 방법:

• Windows: 작업 관리자를 열어 커널에 해당하는 프로세스 이름을 찾습니다(클라이언트마다 이름이 다르며, 흔히 mihomo, clash 같은 문자열이 포함된 실행 파일입니다). 수동으로 종료한 뒤 클라이언트를 다시 실행합니다.
• macOS: 활성 상태 보기에서 같은 프로세스 이름 키워드로 검색하거나, pkill -f mihomo 명령으로 일괄 정리합니다(실행 전에 다른 동일 이름 프로그램을 잘못 종료하지 않는지 확인하세요).
• Linux: ps aux | grep mihomo로 PID를 찾고 kill -9 PID로 종료합니다. 클라이언트가 systemd로 관리되는 서비스라면 systemctl stop 후 systemctl start를 사용하는 것이 좋으며, 서비스 상태와 실제 프로세스 상태가 불일치하는 것을 피할 수 있습니다.

이런 잔여 문제가 반복적으로 발생한다면, 클라이언트 업데이트나 시스템 업데이트 과정에서 관련 프로세스가 자주 강제 종료되고 있는지 확인해 보고, 클라이언트 설정에서 "종료 시 커널 프로세스 정리"와 같은 옵션이 있는지 확인해 활성화 상태로 유지하는 것도 좋습니다.

원인 4: 런타임 라이브러리 누락

일부 클라이언트의 그래픽 인터페이스는 시스템 내장 또는 서드파티 런타임 프레임워크를 기반으로 만들어졌으며, 시스템에 해당 버전의 런타임 라이브러리가 없으면 앱이 실행 단계에서 곧바로 크래시됩니다. 이 경우 로그 파일조차 생성되지 않는 경우가 많은데, 프로그램이 로그를 기록하는 단계까지 도달하지 못한 채 종료되기 때문입니다.

흔한 사례:

• Windows: Visual C++ 런타임 또는 WebView2 컴포넌트가 없는 경우로, 특히 구형 시스템 버전이나 시스템을 방금 재설치해 자주 쓰이는 런타임을 아직 설치하지 않은 기기에서 자주 발생합니다. 시스템 구성 요소 관리에서 WebView2가 설치되어 있는지 확인하고, 없다면 공식 런타임 배포 패키지를 설치하는 것을 권장합니다.
• Linux: 배포판 내장 동적 라이브러리 버전이 오래되었거나, GTK, WebKitGTK 등 그래픽 인터페이스 종속 패키지가 없는 경우로, 패키지 관리자로 해당 종속성을 설치하면 대부분 해결됩니다.
• macOS: 시스템 버전이 클라이언트가 요구하는 최소 버전보다 낮아, 새 버전 앱이 구형 시스템에서 지원하지 않는 시스템 API를 사용하는 경우입니다. 이 경우 시스템을 업그레이드하거나 현재 시스템 버전을 지원하는 클라이언트 버전으로 교체하는 방법밖에 없습니다.

이 유형에 해당하는지 판단하는 간단한 방법: 아이콘을 더블클릭하는 대신 터미널에서 클라이언트 실행 파일을 직접 실행해 봅니다. 터미널에서는 어떤 동적 라이브러리나 컴포넌트가 누락되었는지 구체적인 이름을 출력해 주는 경우가 많아, 그래픽 인터페이스의 "크래시" 메시지보다 훨씬 많은 정보를 얻을 수 있습니다.

네 가지 원인 빠른 자가 점검표

문제 해결 후 확인 순서

문제를 해결한 뒤에는 기존의 복잡한 설정을 곧바로 복원하지 말고 다음 순서로 확인하는 것을 권장합니다:

1. 가장 단순한 기본 설정으로 클라이언트를 먼저 실행해, 커널이 정상적으로 뜨고 외부 제어 포트에 정상 접속되는지 확인합니다.
2. 기존 구독 설정으로 단계적으로 전환하며, 노드 목록이 정상적으로 파싱되고 갱신되는지 관찰합니다.
3. 시스템 프록시나 TUN 모드를 켜기 전에, 먼저 순수 프록시 모드에서 네트워크 연결이 정상인지 확인한 뒤 고급 기능을 한 단계씩 켜 나가면, 이후 다시 문제가 발생했을 때 어느 단계인지 쉽게 파악할 수 있습니다.
4. 이전 문제가 포트 충돌 때문이었다면, 시스템 프록시 설정에 입력된 포트 번호가 클라이언트가 현재 사용 중인 포트와 일치하는지도 함께 확인하세요. 포트를 변경했는데 시스템 프록시 설정이 갱신되지 않은 경우를 방지할 수 있습니다.