Clash 클라이언트 실행 시 강제 종료 및 크래시 해결: 설정 잔재, 커널 권한, 의존성 누락 3가지 원인

먼저 크래시가 발생한 단계를 파악하기

"강제 종료"는 뭉뚱그린 표현이며, 실제로 해결하려면 크래시가 정확히 어느 단계에서 발생했는지 먼저 구분해야 합니다. 단계마다 관련 구성 요소가 완전히 다르기 때문입니다. Clash 계열 클라이언트(Clash Verge, Clash Meta 계열 GUI든, mihomo 커널을 사용하는 다른 구현체든)는 보통 세 부분으로 구성됩니다. 창 렌더링과 설정 관리를 담당하는 UI 프로세스, 실제 프록시 포워딩을 담당하는 커널 프로세스(mihomo 또는 예전 clash 바이너리), 그리고 로컬 설정 파일입니다. 어느 한 층에서 문제가 생기면 겉으로는 모두 "실행이 안 됨" 또는 "열리자마자 꺼짐"으로 보이지만 점검 방향은 완전히 다릅니다.

실행 즉시 종료: 아이콘 클릭 후 프로세스가 아주 짧게 존재하다가 사라지고 작업 표시줄에 순간적으로만 나타나는 경우로, 보통 UI 프로세스가 설정 파일을 읽는 단계에서 처리되지 않은 예외를 던진 것입니다.
커널 구동 실패: 창은 열리지만 프록시 스위치를 켜는 순간 오류가 뜨거나 그대로 멈추는 경우로, TUN 모드를 켜는 순간에 흔히 발생합니다.
화면 흰색 또는 렌더링 이상: 창 자체는 뜨고 제목 표시줄도 정상이지만 콘텐츠 영역이 비어 있거나 일부 요소만 표시되는 경우로, 대부분 시스템 그래픽 의존성 누락과 관련이 있습니다.

아래에서 이 세 가지를 각각 다루며, 유형별로 로그 확인 방법과 해결 명령을 제시합니다. 전체를 다 읽기보다는 먼저 자신이 어느 유형에 해당하는지 확인한 뒤 해당 부분만 보는 것을 권장합니다.

첫 번째 유형: 실행 즉시 종료, 설정 파일 잔재 또는 손상

가장 흔한 크래시 유형으로, 특히 클라이언트 버전을 업그레이드한 직후에 자주 나타납니다. 새 버전의 설정 파일 필드가 이전 버전과 완전히 호환되지 않을 수 있는데, 파싱할 수 없는 필드를 읽으면 UI 프로세스가 오류 메시지를 띄우지 않고 그대로 크래시로 종료됩니다. 이것이 "아무 반응도 없어 보이는" 이유입니다.

파일을 지우기 전에 먼저 로그부터 확인하기

대부분의 GUI 클라이언트는 실행 로그와 크래시 로그를 설정 디렉터리 아래의 logs 하위 디렉터리에 기록하며, 일반적인 경로는 ~/.config/<클라이언트 디렉터리명>/logs/입니다. 바탕화면 아이콘 대신 터미널에서 클라이언트를 실행하면 크래시 정보가 터미널에 바로 출력되므로 로그 파일을 따로 뒤질 필요가 없습니다.

# 실제 설치된 바이너리명으로 교체(일반적으로 clash-verge 또는 해당 AppImage명)
clash-verge 2>&1 | tee ~/clash-crash.log

터미널 출력에 yaml: unmarshal errors, panic: runtime error 또는 failed to initialize config와 비슷한 문구가 보이면 권한이나 의존성 문제가 아니라 설정 파일 파싱 단계에서 크래시가 발생한 것으로 거의 확정할 수 있습니다.

문제가 되는 설정 파일 찾아 정리하기

설정 디렉터리에는 보통 "클라이언트 자체 설정"과 "구독으로 생성된 규칙 설정" 두 종류의 파일이 함께 존재하는데, 전자는 손상되는 경우가 드물고 후자가 문제의 주범인 경우가 많습니다. 다음 순서로 처리하세요.

먼저 설정 디렉터리 전체를 백업해 과도한 정리로 커스텀 규칙을 잃지 않도록 합니다: cp -r ~/.config/<클라이언트 디렉터리명> ~/clash-config-backup
현재 적용 중인 구독 설정 파일을 디렉터리 밖으로 옮겨 다음 실행 시 클라이언트가 기존 설정을 찾지 못하고 내장 기본값을 쓰도록 만듭니다: mv ~/.config/<클라이언트 디렉터리명>/profiles/*.yaml /tmp/
클라이언트를 다시 실행해 정상적으로 열리는지 확인합니다. 정상적으로 열린다면 특정 구독 설정 파일이 원인임을 알 수 있으므로 /tmp/에 있는 파일을 하나씩 되돌려 넣으며 어느 파일이 크래시를 유발하는지 정확히 찾아냅니다.
yamllint나 클라이언트에 내장된 "설정 검증" 기능으로 해당 파일의 문법을 확인합니다. 흔한 문제는 들여쓰기 오류, 전각 콜론 혼입, 규칙 항목에 필수 필드가 빠진 경우입니다.

주의

"초기화"를 위해 ~/.config 아래 클라이언트 디렉터리 전체를 바로 삭제하지 마세요. 창 위치, 언어 설정, 구독 목록 등 유지해도 되는 항목까지 함께 사라집니다. 의심되는 파일 하나씩 옮겨 영향 범위를 최소화하는 방식을 우선하세요.

두 번째 유형: 커널 구동 실패, 대부분 TUN 권한 부족

창은 정상적으로 열리지만 시스템 프록시나 TUN 모드를 켜는 순간 멈추거나 오류가 나거나 클라이언트 전체가 함께 종료된다면, 문제는 UI 자체가 아니라 커널 프로세스(mihomo)와 운영체제 간의 권한 처리에 있는 경우가 대부분입니다.

TUN 모드에 왜 추가 권한이 필요한가

TUN 모드는 시스템에 가상 네트워크 카드를 만들어 모든 트래픽을 먼저 이 가상 카드로 가로챈 뒤 커널 프로세스에 넘기는 방식으로 동작하는데, 이 과정에는 네트워크 디바이스를 생성하는 권한이 필요하며 일반 사용자 권한에는 기본적으로 이 권한이 없습니다. 대부분의 클라이언트는 두 가지 방식으로 이를 해결합니다. 하나는 mihomo 바이너리에 CAP_NET_ADMIN 권한을 설정하는 방식, 다른 하나는 루트 권한을 가진 보조 프로세스를 통해 작업을 대리 수행하는 방식입니다. 두 방식 모두 작동하지 않으면 커널 프로세스가 TUN 디바이스 생성을 시도할 때 바로 오류를 내며 종료되고, 이로 인해 UI 프로세스도 커널 이상을 감지해 함께 크래시됩니다.

점검 절차

# 1. 커널 바이너리에 권한 비트가 설정되어 있는지 확인
getcap /usr/lib/clash-verge/mihomo
# 예상 출력 예시:
# /usr/lib/clash-verge/mihomo = cap_net_admin,cap_net_bind_service+ep

# 2. 출력이 비어 있다면 권한 비트를 수동으로 추가(경로는 실제 설치 위치로 교체)
sudo setcap cap_net_admin,cap_net_bind_service=+ep /usr/lib/clash-verge/mihomo

# 3. 시스템 로그에 커널 프로세스의 디바이스 생성 거부 기록이 있는지 확인
journalctl --user -u clash-verge -n 100 --no-pager
dmesg | grep -i tun

또 다른 흔한 경우는 시스템에 tun 커널 모듈이 없는 경우로, 경량화된 서버 배포판이나 일부 커스텀 커널에서 특히 자주 발생합니다.

# 모듈이 로드되어 있는지 확인
lsmod | grep tun

# 로드되어 있지 않다면 수동으로 로드하고 부팅 시 자동 로드로 설정
sudo modprobe tun
echo "tun" | sudo tee -a /etc/modules-load.d/modules.conf

권한 비트를 추가하고 tun 모듈 존재를 확인한 뒤 TUN 모드를 다시 켜면 커널 프로세스가 정상적으로 구동되어야 합니다. 여전히 실패한다면 커널 프로세스 자체의 로그(보통 설정 디렉터리 아래 core.log 또는 비슷한 이름으로 따로 저장됨)를 확인해 포트 충돌이나 DNS 하이재킹 설정 오류 같은 부차적인 원인이 있는지 확인하세요.

세 번째 유형: 화면 흰색, 시스템 그래픽 의존성 누락

이 유형의 특징은 창 자체는 뜨고 제목 표시줄과 테두리도 정상적으로 렌더링되지만 콘텐츠 영역이 완전히 비어 있거나 일부 요소만 로드되다가 멈추는 것입니다. 대부분의 GUI 클라이언트는 WebView나 유사한 임베디드 브라우저 렌더링 컴포넌트로 화면을 구성하는데, 이런 컴포넌트는 시스템이 제공하는 그래픽 라이브러리에 의존하므로 라이브러리가 없거나 버전이 맞지 않으면 뚜렷한 오류 메시지 없이 렌더링 단계가 조용히 실패합니다.

흔히 누락되는 의존성

webkit2gtk 또는 libwebkit2gtk: GTK 기반 GUI 클라이언트가 화면을 렌더링하는 데 필수이며, 배포판 업데이트 중 실수로 삭제되거나 버전이 롤백되는 경우가 있습니다.
libayatana-appindicator 또는 예전 버전인 libappindicator: 시스템 트레이 아이콘 표시를 담당하며, 없으면 일부 클라이언트가 트레이 초기화 단계에서 바로 멈춥니다.
그래픽 드라이버 관련 OpenGL/Mesa 라이브러리: 가상 머신이나 일부 경량 데스크톱 환경에서 빠지기 쉬우며, 이 경우 GPU 가속 렌더링이 실패합니다.

명령줄로 누락된 항목 확인하기

먼저 터미널에서 클라이언트를 실행해 동적 링크 라이브러리 오류가 있는지 확인하면 무엇이 빠졌는지 바로 알 수 있습니다.

ldd $(which clash-verge) | grep "not found"

출력에 libwebkit2gtk-4.1.so.0 => not found와 비슷한 줄이 보이면 해당 라이브러리가 실제로 없는 것이므로 배포판에 맞는 패키지를 설치하면 됩니다.

# Debian / Ubuntu
sudo apt install libwebkit2gtk-4.1-0 libayatana-appindicator3-1

# Fedora
sudo dnf install webkit2gtk4.1 libappindicator-gtk3

# Arch / Manjaro
sudo pacman -S webkit2gtk-4.1 libappindicator-gtk3

설치가 끝난 뒤 클라이언트를 다시 실행하면 대부분의 경우 화면 흰색 문제가 바로 해결됩니다. 의존성이 모두 갖춰졌는데도 여전히 화면이 비어 있다면 일시적으로 GPU 가속을 끄고 실행해 그래픽 드라이버 호환성 문제를 배제해볼 수 있습니다.

WEBKIT_DISABLE_COMPOSITING_MODE=1 clash-verge

세 가지 유형별 로그 위치 요약표

점검할 때 가장 시간을 낭비하기 쉬운 부분이 어느 로그를 봐야 할지 모르는 것입니다. 아래 표는 세 가지 크래시 유형에 대응하는 점검 진입점을 정리한 것으로, 문제가 발생했을 때 앞선 내용을 다시 읽지 않고 바로 참고할 수 있습니다.

크래시 유형	전형적인 증상	우선 확인할 위치
실행 즉시 종료	아이콘 클릭 후 순간적으로 사라지고 창이 뜨지 않음	터미널에서 직접 실행해 출력 확인; `~/.config/<클라이언트>/logs/`
커널 구동 실패	창은 정상, 프록시/TUN 켤 때 멈추거나 오류	`journalctl --user`; `dmesg`; 커널 프로세스 전용 로그 파일
화면 흰색	창 테두리는 정상, 콘텐츠 영역이 비어 있음	`ldd`로 동적 라이브러리 확인; 터미널 실행 시 단계별 오류 확인

해결 후 재발 방지 방법

크래시를 해결한 뒤에는 다음에 업그레이드하거나 기기를 바꿀 때 같은 문제를 다시 겪지 않도록 두 가지를 함께 해두는 것을 권장합니다. 먼저 현재 정상 작동 중인 설정 파일을 설정 디렉터리 밖에 따로 백업해두고, 클라이언트를 업그레이드하기 전에 매번 백업을 갱신하면 업그레이드 후 필드 비호환 문제가 생겨도 빠르게 되돌릴 수 있습니다. 다음으로 현재 시스템에서 수동으로 추가한 권한 비트와 수동으로 설치한 의존성 패키지를 간단한 셸 스크립트로 정리해두면 기기를 바꾸거나 재설치할 때 스크립트만 실행해서 다시 하나씩 점검하는 시간을 아낄 수 있습니다.

#!/bin/bash
# 기기 교체 후 Clash 클라이언트 실행에 필요한 시스템 조건을 한 번에 갖추기
sudo apt install -y libwebkit2gtk-4.1-0 libayatana-appindicator3-1
sudo modprobe tun
echo "tun" | sudo tee -a /etc/modules-load.d/modules.conf
sudo setcap cap_net_admin,cap_net_bind_service=+ep /usr/lib/clash-verge/mihomo

마지막으로 한 가지 짚어두면, 위 세 가지 유형을 모두 점검했는데도 해결되지 않는다면 클라이언트 버전과 현재 시스템 커널 또는 그래픽 스택 사이에 더 근본적인 호환성 문제가 있을 가능성이 높습니다. 이런 경우 같은 커널을 쓰는 다른 GUI 버전의 클라이언트로 바꿔보는 것이 같은 버전을 반복해서 재설치하는 것보다 효과적인 경우가 많습니다.