Clash 실행 로그 읽는 법: 로그 레벨, 주요 오류 의미와 원인 파악 방법

로그 레벨과 확인 순서

mihomo 코어 기반 클라이언트는 시작과 실행 중에 지속적으로 로그를 출력하며, 로그 레벨은 일반적으로 silent, error, warning, info, debug 다섯 단계로 나뉘고 설정 파일의 log-level 필드로 제어합니다. 각 레벨은 포함 관계에 있습니다. info를 선택하면 info, warning, error 세 가지를 함께 출력하고, debug를 선택하면 모든 정보를 포함해 데이터량이 가장 많고 가장 자세합니다.

문제를 진단할 때 처음부터 debug 로그를 뒤지는 것은 권장하지 않습니다. 정보량이 너무 많으면 오히려 원인 파악이 느려집니다. 합리적인 순서는 다음과 같습니다. 먼저 시작 단계에 error 레벨의 오류가 있는지 확인해 코어가 정상적으로 구동되는지 확인하고, 다음으로 연결 요청 시의 warning을 살펴 네트워크 계층 문제인지 규칙 계층 문제인지 판단합니다. 앞의 두 단계에서 실마리를 찾지 못했다면 그때 debug 레벨로 전환해 특정 요청을 재현하고, 도메인 해석과 노드 선택, 규칙 매칭 순서가 예상대로인지 한 줄씩 대조합니다.

주요 오류 항목별 해설

다음 몇 가지 오류는 로그에서 가장 자주 나타나며, 문구를 외우기보다 발생 조건을 이해하는 편이 훨씬 유용합니다.

DNS 해석 실패

로그에 "resolve host failed"나 "dns resolve error"와 비슷한 내용이 나오면 보통 설정의 nameserver가 정상적으로 응답하지 않거나, 대상 도메인 자체가 해석 범위에 없다는 의미입니다. 이런 문제는 세 가지 상황에서 흔히 발생합니다. 사용자 지정 DNS 서버에 접근할 수 없는 경우, DNS over HTTPS 주소를 잘못 입력한 경우, 그리고 규칙에서 특정 도메인에 no-resolve를 지정했지만 여전히 외부 해석이 필요한 경우입니다. 확인 방법은 먼저 시스템 기본 네트워크 도구로 nameserver 목록의 주소가 사용 가능한지 개별적으로 테스트한 다음, 규칙 세트에 포함된 도메인의 매칭 타입이 올바른지 확인하는 것입니다.

핸드셰이크 타임아웃

"handshake timeout"이나 "dial tcp timeout" 같은 오류는 클라이언트와 프록시 노드 간 연결 수립 단계에서 시간이 초과되어 실제 데이터 전송에 아직 들어가지 못했다는 뜻입니다. 흔한 원인으로는 노드 서버가 이미 종료된 경우, 구독 링크의 포트 정보가 만료된 경우, 로컬 네트워크가 특정 포트를 제한하는 경우, 노드가 위치한 지역의 네트워크 회선 자체가 불안정한 경우 등이 있습니다. 이런 오류가 발생하면 먼저 구독 내 다른 노드로 전환해 테스트해보고, 여러 노드에서 모두 타임아웃이 발생한다면 문제는 대부분 구독 자체가 아니라 로컬 네트워크 환경에 있을 가능성이 큽니다.

규칙 미매칭과 최종 처리 전략

로그에서 특정 도메인이 계속 MATCH나 FINAL 규칙에 대응하는 정책 그룹으로 떨어진다면, 앞의 모든 규칙에 매칭되지 않았다는 의미입니다. 이것이 반드시 오류는 아니지만, 만약 이 도메인이 원래 특정 규칙을 타야 했다면 규칙 순서나 매칭 타입이 잘못 작성되었다는 뜻입니다. mihomo의 규칙 매칭은 위에서 아래로 순차적으로 이루어지며, 한 규칙이 매칭되면 더 이상 아래로 비교하지 않습니다. 따라서 범위가 넓은 규칙은 범위가 좁은 규칙보다 뒤에 두어야 하며, 그렇지 않으면 좁은 규칙이 결코 적용될 기회를 얻지 못합니다.

연결 거부와 포트 점유

"connection refused"는 대부분 대상 포트에서 대기 중인 서비스가 없거나, 로컬 프록시 포트가 다른 프로그램과 충돌하는 경우입니다. 시작 단계에서 로그에 포트가 이미 사용 중이라고 표시되면 먼저 클라이언트 인스턴스가 여러 개 동시에 실행 중인지, 또는 시스템의 다른 도구가 동일한 혼합 포트를 점유하고 있는지 확인합니다.

로그로 설정 문제를 역추적하는 방법

로그 오류 자체는 표면적인 현상일 뿐, 진짜 필요한 작업은 그 현상을 설정 파일의 구체적인 필드와 연결하는 것입니다. 실행 가능한 진단 경로는 다음과 같습니다.

1. 오류가 발생한 단계를 확인합니다. 코어 시작 시에 발생한 오류인지, 특정 연결 요청 시에 발생한 오류인지에 따라 확인 범위가 완전히 달라집니다.
2. 오류와 관련된 도메인이나 IP를 기록하고, 설정 파일로 돌아가 이 도메인이 매칭될 수 있는 규칙 항목을 검색해 매칭 타입이 예상과 맞는지 확인합니다.
3. 노드 문제로 의심되면 정책 그룹에서 단일 노드만 선택해 개별적으로 테스트하여, 정책 그룹 내 다중 노드 순환으로 인한 간섭을 배제합니다.
4. 로그가 DNS 계층 오류를 나타낸다면 dns 설정 블록의 nameserver, fallback 필드를 개별적으로 확인하고, 필요하면 임시로 공용 DNS 주소로 바꿔 비교 테스트합니다.
5. 문제를 찾은 뒤에는 한 번에 하나의 설정만 변경한 다음 재시작해 검증합니다. 여러 곳을 동시에 변경하면 어떤 수정이 실제로 문제를 해결했는지 판단할 수 없습니다.

로그 가독성을 높이는 설정 권장 사항

평상시에는 log-level을 info로 유지하는 것을 권장합니다. 이 레벨은 핵심 연결 상태를 확인할 수 있으면서도 방대한 디버그 정보에 파묻히지 않습니다. 클라이언트가 화면 안에서 실행 로그를 바로 볼 수 있게 지원한다면, 시간 순서대로 스크롤되는 화면 내 실시간 로그 패널을 사용하는 것이 로그 파일을 직접 여는 것보다 훨씬 직관적입니다. 간헐적인 문제가 발생하면 먼저 재현 절차를 고정하고, 재현 전후의 타임스탬프를 기록한 뒤 로그에서 해당 시간대만 걸러보면 뒤지는 범위를 크게 줄일 수 있습니다.

또한 규칙 세트와 구독 내용을 업데이트한 뒤에는 로그를 한 번 더 살펴 새 규칙이 예상 순서대로 적용되는지 확인하는 것을 권장합니다. 실제 사용 중에 우연히 분기 결과가 이상하다는 것을 발견하고 나서 되돌아가 원인을 찾는 방식보다 훨씬 낫습니다. 로그 확인을 설정 변경 후 고정 단계로 삼으면 규칙 순서나 필드 오타로 인한 문제 대부분을 미리 발견할 수 있습니다.