Clash 클라이언트 실행 시 튕김(크래시) 해결법 - Windows·macOS 시작 오류 진단

먼저 어느 단계에서 문제가 발생했는지 파악하기

시작 오류는 크게 두 단계로 나뉘며, 대응 방법이 완전히 다릅니다. 우선 1분만 투자해 문제 단계를 파악한 뒤 조치를 시작하세요.

• GUI 단계 오류: 아이콘을 클릭해도 반응이 없거나, 프로세스가 잠깐 뜨자마자 종료되거나, 창이 흰 화면으로만 뜨는 경우입니다. 대부분 실행 환경 누락, 설치 파일과 시스템 아키텍처 불일치, 권한 부족이 원인입니다.
• 코어 단계 오류: 화면은 정상적으로 열리지만 "코어 실행 실패", "Clash core exited" 메시지가 뜨거나, 시스템 프록시를 켜는 순간 오류가 발생하는 경우입니다. 대부분 설정 파일 손상, 포트 충돌, 이전 코어 프로세스의 잔여 실행이 원인입니다.

판단 방법: 클라이언트의 로그 화면을 열거나, 데이터 폴더 내 logs 폴더를 직접 확인하세요. 로그가 화면 초기화 단계에서 멈춰 있다면 GUI 단계 문제이고, 로그에 mihomo 또는 clash 코어의 오류 라인이 보인다면 코어 단계 문제입니다. 코어 단계 문제는 설정 파일부터, GUI 단계 문제는 실행 환경부터 확인하세요.

공통 점검: 설정 파일과 구독 링크

설정 파일 손상은 코어 단계 오류의 가장 큰 원인입니다. Clash 설정은 YAML 형식으로 들여쓰기와 특수 문자에 민감해서, 형식이 한 곳만 틀려도 코어가 파싱 단계에서 바로 종료됩니다.

설정 파일이 손상되는 대표적인 경우는 세 가지입니다.

• 설정을 직접 수정할 때 Tab 들여쓰기가 섞여 들어간 경우. YAML은 공백 들여쓰기만 허용하므로 Tab 하나만 있어도 파싱이 실패합니다.
• 구독 링크가 YAML이 아니라 오류 페이지, 로그인 페이지, 빈 내용을 반환한 경우. 클라이언트가 이를 그대로 저장하면 파싱할 수 없습니다.
• 설정 파일을 쓰는 도중 클라이언트가 비정상 종료되어 파일이 중간에 잘려 불완전한 YAML 문서만 남은 경우.

해결 방법은 파일을 한 줄씩 고치는 것이 아니라 클라이언트가 설정을 새로 만들도록 하는 것입니다.

1. 클라이언트를 완전히 종료한 뒤 설정 폴더(아래 표 참고)를 찾습니다.
2. 전체 폴더 이름을 바꿔 백업합니다. 예를 들어 원래 이름 뒤에 .bak을 붙입니다.
3. 클라이언트를 다시 실행하면 기본 설정이 자동으로 새로 생성됩니다.
4. 구독을 다시 불러와 정상 실행되는지 확인한 뒤, 백업본에서 필요한 사용자 규칙만 골라 복원합니다.

자주 손상되는 또 다른 파일은 캐시 파일 cache.db입니다. Fake-IP 매핑 등 실행 상태를 기록하는 파일로, 비정상 종료 후 손상되면 코어가 시작하자마자 튕길 수 있습니다. 이 파일은 그냥 삭제하면 클라이언트가 새로 생성하며, 설정에는 영향이 없습니다.

Windows 진단 절차

WebView2 런타임 복구

Clash Verge Rev, Clash Nyanpasu 등 Tauri 프레임워크 기반 클라이언트는 화면 렌더링에 시스템의 WebView2 구성 요소를 사용합니다. WebView2가 없거나 손상되면 창이 흰 화면으로 뜨거나 실행 후 바로 종료되는 증상이 나타납니다.

"설정 → 앱 → 설치된 앱"에서 WebView2를 검색합니다. 있다면 "수정 → 복구"를 선택하고, 없다면 Microsoft 공식 사이트에서 Microsoft Edge WebView2 Runtime을 내려받아 설치한 뒤 클라이언트를 다시 실행합니다. Electron 기반 클라이언트(예: Clash for Windows)는 자체 렌더링 엔진을 내장하고 있어 WebView2에 의존하지 않으므로 이 항목은 건너뛰어도 됩니다.

포트 충돌 확인

기본 혼합 포트 7890이 다른 프로그램에 의해 사용 중이면 코어 실행이 곧바로 실패합니다. 명령 프롬프트에서 다음을 실행하세요.

netstat -ano | findstr :7890

출력 결과가 있으면 해당 포트가 사용 중이라는 뜻이며, 맨 마지막 열이 점유 중인 프로세스의 PID입니다. 작업 관리자의 "세부 정보" 탭에서 해당 PID를 찾으세요. 대개 이전에 완전히 종료되지 않은 Clash 코어가 원인이므로 그대로 종료하면 됩니다. 점유 중인 프로세스를 건드리고 싶지 않다면, 클라이언트 설정에서 혼합 포트를 7897 등 사용하지 않는 포트로 바꿔도 됩니다.

잔여 프로세스 정리

클라이언트가 비정상 종료된 뒤에도 코어 프로세스가 백그라운드에 남아 있을 수 있고, 이 상태에서 다시 실행하면 포트와 파일 잠금 충돌이 발생합니다. 관리자 권한 명령 프롬프트에서 다음을 실행하세요.

taskkill /F /IM verge-mihomo.exe
taskkill /F /IM clash-meta.exe
taskkill /F /IM mihomo.exe

실제 사용 중인 클라이언트의 코어 프로세스명으로 실행하면 됩니다. "해당 프로세스를 찾을 수 없습니다"라는 메시지가 나오면 잔여 프로세스가 없다는 뜻이므로 무시해도 됩니다.

권한 및 보안 소프트웨어

• TUN 모드와 서비스 모드는 관리자 권한이 필요합니다. 클라이언트 아이콘을 마우스 오른쪽 버튼으로 클릭해 "관리자 권한으로 실행"을 선택하면 권한 문제인지 확인할 수 있습니다.
• 일부 보안 소프트웨어는 코어의 네트워크 접속을 차단하거나 코어 실행 파일을 오탐하여 격리시킵니다. 보안 소프트웨어의 격리 항목을 확인해 격리된 파일을 복원하고, 클라이언트 설치 폴더를 신뢰 목록에 추가하세요.
• 설치 경로에는 한글이나 공백 외의 특수 문자를 넣지 않는 것이 좋습니다. 일부 구버전은 ASCII가 아닌 경로 처리가 불완전합니다.

macOS 진단 절차

"손상되어 열 수 없음" 오류와 격리 속성

브라우저에서 내려받은 공증(notarization)되지 않은 앱은 Gatekeeper에 의해 격리 속성이 붙어, 실행 시 "손상됨" 메시지와 함께 바로 종료됩니다. 파일 자체는 대부분 정상이며, 격리 속성만 제거하면 됩니다. "응용 프로그램 → 유틸리티 → 터미널"을 열고 다음을 실행하세요.

sudo xattr -rd com.apple.quarantine /Applications/Clash\ Verge.app

경로는 실제 앱 이름으로 바꾸고, 로그인 비밀번호를 입력한 뒤 엔터를 누르면 됩니다. 이후 정상적으로 실행할 수 있습니다.

칩 아키텍처 확인

Apple 실리콘(M 시리즈)은 arm64 설치 파일을, Intel은 x64 설치 파일을 사용해야 합니다. 잘못된 아키텍처를 설치하면 Dock 아이콘이 한 번 튀었다가 바로 종료되는 증상이 나타나며, 터미널에서 실행 파일을 직접 실행하면 Bad CPU type in executable 오류가 표시됩니다. 화면 왼쪽 상단 애플 메뉴 → "이 Mac에 관하여"에서 칩 종류를 확인한 뒤, 다운로드 페이지에서 맞는 아키텍처 버전을 다시 설치하세요.

포트 및 잔여 프로세스

Windows와 마찬가지로 먼저 기본 포트를 확인합니다.

lsof -i :7890

결과가 있으면 두 번째 열의 PID로 해당 프로세스를 종료합니다.

kill -9 <PID>

프로세스명으로 잔여 코어를 바로 정리할 수도 있습니다: pkill -f mihomo.

권한 복구

처음 실행할 때 시스템 프록시 설정을 적용하기 위한 권한 요청 창이 뜨는데, 여기서 "취소"를 누르면 이후 실행 과정이 정상적으로 진행되지 않습니다. 또한 이전에 sudo로 클라이언트를 직접 실행한 적이 있다면 설정 폴더의 소유자가 root로 바뀌어, 이후 일반 권한으로 실행할 때 읽기/쓰기가 실패할 수 있습니다. 소유자를 복구하려면 다음을 실행하세요.

sudo chown -R $(whoami) ~/Library/Application\ Support/io.github.clash-verge-rev.clash-verge-rev

경로는 위 표를 참고해 실제 클라이언트의 폴더로 바꿔서 사용하세요.

완전히 정리 후 재설치

개별 조치로 해결되지 않을 때는 아래 순서대로 깨끗하게 재설치하세요. 재설치는 "로컬 데이터 폴더 손상"류의 문제를 해결하는 방법으로, 구독 링크 자체가 만료되었거나 서버(기점) 측 장애인 경우는 해당하지 않습니다. 그런 경우는 클라이언트를 아무리 깨끗하게 설치해도 연결되지 않습니다.

1. 클라이언트를 종료하고, 앞서 안내한 방법으로 코어 프로세스가 모두 종료되었는지 확인합니다.
2. 데이터 폴더 이름을 바꿔 백업합니다. .bak 접미사를 붙이면 됩니다.
3. 원래 데이터 폴더를 삭제하고 기존 버전을 제거합니다.
4. 최신 버전 클라이언트를 설치하고, 실행 후 구독을 다시 불러옵니다.
5. 먼저 TUN 모드는 켜지 않고, 시스템 프록시 모드에서 정상적으로 연결되는지 확인합니다.
6. 사용자 설정을 하나씩 복원하면서 매번 재시작해, 어떤 설정 항목이 오류를 일으키는지 정확히 찾아냅니다.

그래도 계속 튕긴다면: 로그를 수집해 다시 진단하기

위 방법이 모두 효과가 없다면, 클라이언트의 로그 레벨을 debug로 올리고 오류를 한 번 재현한 뒤 다음 정보를 수집하세요.

• 운영체제 버전, 예를 들어 Windows 11 23H2, macOS 15.5 등.
• 클라이언트 이름과 버전, 그리고 코어 종류(mihomo 또는 Clash Premium).
• 전체 재현 과정: 아이콘 클릭부터 오류가 발생하기까지의 모든 단계.
• 오류 발생 전후 로그의 오류 구간. 보통 마지막 30줄 정도면 충분합니다.

이 정보를 가지고 해당 클라이언트 프로젝트의 GitHub Issues 페이지에서 검색해보세요. 대부분의 시작 오류는 이미 원인과 해결 버전이 정리되어 있습니다. 검색 결과가 없을 때만 새 이슈를 등록하고, 위 목록을 함께 첨부하면 답변을 받기까지 걸리는 시간을 크게 줄일 수 있습니다.