Clash 실행 로그 확인법: 주요 오류 메시지 의미와 문제 진단 방법

로그가 문제 진단의 1차 자료인 이유

Clash 계열 클라이언트(오리지널 커널과 mihomo 커널 포함)는 실행 중 지속적으로 구조화된 텍스트 로그를 출력하며, 연결 수립, 규칙 매칭, DNS 조회, 프록시 선택 등 각 단계의 실행 결과를 기록합니다. "인터넷이 되는지 안 되는지"라는 모호한 현상 설명과 달리, 로그는 특정 연결, 특정 조회의 구체적인 실패 원인을 보여줍니다. 이것이 공식 문서와 커뮤니티 문제 해결 과정에서 "먼저 로그를 확인하라"고 강조하는 이유입니다.

대부분의 클라이언트(Clash Verge, Clash for Windows 계열 파생 버전, mihomo party 등)는 메인 화면에 "로그" 또는 "Logs" 탭을 제공하며, 일부는 레벨별 필터링과 키워드 검색도 지원합니다. 명령줄로 커널을 실행할 때는 로그가 터미널 표준 출력으로 바로 나오며, 설정 파일의 log-level 필드를 통해 지정한 파일로 출력하도록 제어할 수도 있습니다. 어떤 클라이언트를 쓰든 로그 형식과 자주 발생하는 오류 유형을 이해하면, 진단 시간을 "반복 재시작으로 운 시험하기"에서 "구체적인 단계 찾아내기"로 크게 줄일 수 있습니다.

로그 레벨은 어떻게 설정하고, 어느 레벨을 봐야 할까

Clash 설정 파일의 log-level 필드는 출력의 상세 정도를 결정하며, 자주 쓰이는 값은 거친 것부터 세밀한 것 순으로 다음과 같습니다:

• silent: 로그를 전혀 출력하지 않으며, 프로덕션 환경에서 완전히 조용하게 동작할 때만 사용합니다. 문제 진단 시에는 이 레벨을 쓰지 마세요.
• error: 연결 실패, 설정 파싱 오류 등 심각한 문제만 기록하며, 정보량이 가장 적어 중간 과정을 놓치기 쉽습니다.
• warning: error 기반에 잠재적 이상 알림을 추가합니다. 예를 들어 규칙 세트 로딩 지연, 인증서 만료 임박 등입니다.
• info: 기본 권장 레벨로, 프록시 선택 결과, DNS 조회 요약, 연결 수립 및 종료를 기록합니다. 정보 밀도가 적절해 일상적인 문제 해결에 충분합니다.
• debug: 가장 완전한 실행 세부 정보를 출력하며, 각 규칙의 매칭 시도 과정, 프로토콜 핸드셰이크의 구체적인 바이트 교환 요약까지 포함합니다. 어려운 문제를 진단할 때 임시로 켜고, 로그량이 많고 성능에 영향을 줄 수 있어 일상적으로 장기간 사용하는 것은 권장하지 않습니다.

설정 방법은 YAML 설정 파일에서 다음과 같이 지정합니다:

log-level: info

자주 발생하는 오류 하나씩 해설

DNS 확인 실패 유형

이런 로그는 보통 dns resolve failed, no such host 또는 유사한 문구를 포함하며, 클라이언트가 도메인을 IP 주소로 확인하려다 실패했음을 나타냅니다. 자주 나타나는 원인은 다음과 같습니다:

• 설정 파일의 DNS 서버 주소가 잘못 입력되었거나 해당 서버가 이미 무효화됨;
• fake-ip 모드를 활성화했지만 대상 도메인이 잘못 직접 연결(direct) 그룹으로 분류되어, 실제 DNS 요청이 프록시 채널을 거치지 않음;
• DoH/DoT 암호화 DNS를 사용할 때, 업스트림 암호화 DNS 서버 자체가 프록시를 거쳐야만 접근 가능해 "닭이 먼저냐 알이 먼저냐" 식의 순환 잠금이 발생함;
• 도메인 자체가 존재하지 않거나 만료된 경우로, 이는 클라이언트 문제가 아니라 도메인 문제에 해당함.

진단 방법: 먼저 설정 안의 nameserver 필드가 유효한 주소인지 확인하고, 해당 도메인에 대응하는 규칙 그룹이 예상한 노드를 매칭했는지 확인합니다. 암호화 DNS 순환 잠금 문제라면 DNS 서버 주소를 위해 별도로 직접 연결을 설정하거나 안정적으로 사용 가능한 착지 노드를 지정할 수 있습니다.

핸드셰이크 시간 초과 유형

로그에 handshake timeout, dial tcp: i/o timeout 또는 context deadline exceeded가 나타나면, 클라이언트가 프록시 노드와 연결을 시도했지만 정해진 시간 내에 TLS 핸드셰이크나 TCP 연결 수립을 완료하지 못했음을 나타냅니다. 이런 오류의 원인은 세 가지 측면으로 나눌 수 있습니다:

• 노드 측: 서버가 이미 다운되었거나 포트가 일시적으로 차단되었거나, 서버가 위치한 지역의 네트워크 품질이 좋지 않음;
• 프로토콜 매개변수 측: 클라이언트와 서버 간 암호화 방식, 전송 프로토콜(WebSocket 경로, gRPC 서비스명 등)의 설정이 일치하지 않아 핸드셰이크 요청 형식이 상대측에 받아들여지지 않음;
• 로컬 네트워크 측: 로컬 아웃바운드 네트워크 자체가 대상 포트에 속도 제한이나 간섭을 걸고 있으며, 특히 일부 통신사의 특정 포트 QoS 정책에서 흔히 발생함.

진단 방법: 먼저 같은 구독 안의 다른 노드로 테스트합니다. 모든 노드가 시간 초과되면 문제는 대개 로컬 네트워크에 있고, 특정 노드만 시간 초과되면 그 노드 자체의 상태나 프로토콜 매개변수 설정 오류를 먼저 의심합니다.

규칙 미매칭 유형

로그에 match RuleSet(...) 또는 final rule이 나타나지만 프록시 경로가 예상과 다른 경우는 오류가 아니라, 규칙 매칭 로직은 정상 작동했지만 결과가 사용자가 예상한 그룹이 아닌 경우입니다. 자주 나타나는 원인:

• 규칙 파일은 위에서 아래 순서로 매칭되며, 앞쪽의 더 광범위한 규칙이 먼저 매칭되어 뒤쪽의 정밀한 규칙이 실행되지 못함;
• 규칙 세트(rule-provider)가 제때 업데이트되지 않아 여전히 예전 버전의 도메인/IP 목록을 사용 중;
• 최종 기본 규칙(MATCH)이 예상치 않은 그룹을 가리키고 있어, 앞의 규칙에 매칭되지 않은 모든 트래픽이 이곳으로 떨어짐.

진단 방법: debug 레벨 로그를 켠 뒤 특정 도메인에 대해 연결을 시도하고, 로그에서 해당 도메인을 검색해 실제로 어느 규칙에 매칭되어 어느 프록시 그룹으로 떨어졌는지 확인한 다음, 규칙 파일과 순서를 하나씩 대조합니다.

연결 거부 및 프로토콜 오류 유형

connection refused는 대상 포트에서 서비스가 리스닝하고 있지 않음을 나타내며, 보통 서버에 설정된 포트와 클라이언트에 입력된 포트가 일치하지 않거나 서버 측 서비스가 시작되지 않은 경우입니다. invalid header, unexpected EOF 같은 프로토콜 계층 오류는 대부분 클라이언트와 서버 양쪽의 암호화 방식, 위장 매개변수(obfs 유형 등)가 일치하지 않는 것을 나타내므로, 구독의 프로토콜 필드를 하나씩 대조해야 합니다.

오류 유형별로 문제 원인을 찾는 실용적인 방법

오류 로그를 발견했다면, 가능한 모든 원인을 하나씩 시도하기보다 다음 순서로 범위를 좁혀가는 것을 권장합니다:

1. 1단계, 오류가 발생한 단계를 구분합니다. DNS 확인 단계인지, 핸드셰이크 연결 단계인지, 규칙 매칭 단계인지 확인합니다. 로그 안의 키워드(resolve / dial / handshake / rule)가 보통 이미 단계를 명시하고 있어, 먼저 단계별로 분류하면 대부분의 관련 없는 방향을 제외할 수 있습니다.
2. 2단계, 단일 노드 문제인지 판단합니다. 같은 구독의 다른 노드로 전환해 재시도합니다. 문제가 사라지면 해당 노드의 서버 측 상태나 매개변수 문제이고, 여전히 존재하면 3단계로 넘어갑니다.
3. 3단계, 로컬 네트워크 문제인지 판단합니다. 임시로 프록시를 끄고 대상 사이트에 직접 접속해 보거나, 모바일 핫스팟 등 다른 네트워크 환경에서 테스트해 로컬 통신사, 라우터 정책이 만든 간섭을 배제합니다.
4. 4단계, 설정 파일 자체를 대조합니다. DNS 설정, 규칙 순서, rule-provider 업데이트 시각, 구독이 최신 버전인지를 확인합니다. "노드 문제처럼 보이는" 많은 경우가 실제로는 설정 파일 만료나 필드 오타로 판명됩니다.
5. 5단계, 로그 레벨을 올려 문제를 재현합니다. 앞 네 단계로도 원인을 찾지 못했다면 log-level을 임시로 debug로 조정해 문제를 완전히 재현하고, 관련 로그 조각을 보관해 추가 분석이나 커뮤니티 문의에 활용합니다.

일상적으로 로그를 확인할 때 유용한 습관

• 연결에 문제가 생기면 먼저 타임스탬프를 확인해 장애 발생 시점을 특정한 다음, 전후 몇 초의 로그 맥락을 거슬러 확인해 긴 로그를 무작정 뒤지는 것을 피합니다.
• 클라이언트 로그 페이지의 키워드 필터 기능을 적극 활용해, 문제가 된 도메인이나 IP를 직접 검색하면 관련 로그 라인을 빠르게 찾을 수 있습니다.
• 규칙을 수정한 뒤에는 한 번 debug 레벨을 켜서 새 규칙이 실제로 예상대로 작동하는지 검증한 다음, 다시 info 레벨로 전환해 장기 운영하는 것을 권장합니다.
• TUN 모드에서의 문제는 대개 시스템 네트워크 스택과 커널 로그 두 부분이 함께 관련되어 있습니다. TUN 모드로 연결이 되지 않는 경우 Clash 자체 로그 외에도 클라이언트에 별도의 TUN 상태 표시가 있는지 확인하세요.
• 최근 정상 작동했을 때의 설정 파일 백업을 보관해두면, 업그레이드 후 갑자기 오류가 늘어난 경우 설정 차이를 바로 비교해 변경된 지점을 찾을 수 있습니다.