Clash 로그 읽는 법: 주요 오류 메시지 의미와 문제 진단 방법

노드를 바꾸기 전에 로그를 먼저 봐야 하는 이유

웹페이지가 열리지 않거나 연결이 끊기는 문제가 생기면 많은 사람이 먼저 구독이나 노드를 바꿔보고, 몇 번 시도해도 안 되면 클라이언트 자체를 의심합니다. 이런 방식은 효율이 낮습니다. 프록시 경로에는 로컬 설정, 노드 가용성, 국제 회선 품질, 대상 사이트 응답 등 여러 단계가 관여하기 때문에 무작정 노드를 바꿔봐서는 가능성의 일부만 배제할 수 있습니다. 더 빠른 방법은 로그 페이지를 열어 클라이언트가 이번 연결 요청을 처리하면서 실제로 무엇을 기록했는지 보는 것입니다. 오류 메시지는 대개 문제가 어느 계층에 있는지 직접 알려줍니다.

Clash 계열 클라이언트의 로그는 본질적으로 코어(Clash Meta / mihomo)가 실행되는 동안 실시간으로 출력하는 내용이며, 클라이언트 UI는 이 텍스트를 렌더링하고 색상과 필터를 입혀 보여줄 뿐입니다. 로그 구조와 자주 나오는 필드의 의미를 이해하는 것이 연결 문제를 진단하는 가장 기본적이면서도 효과적인 방법입니다.

로그 레벨과 필드 구조

클라이언트의 로그 페이지(사이드바에서 보통 Logs 또는 "로그"로 표시)를 열면 아래와 같은 형태의 기록을 볼 수 있습니다.

[Info] [TCP] 192.168.1.5:51234 --> example.com:443 match Rule(DOMAIN-SUFFIX,example.com) using Proxy-HK

이 한 줄에는 네 가지 핵심 요소가 담겨 있습니다.

• 로그 레벨: 대괄호 안의 Info, Warning, Error 등으로 기록의 심각도를 나타냅니다.
• 프로토콜과 연결 방향: TCP 또는 UDP, 그리고 로컬 포트가 어떤 대상 도메인/포트로 향하는지를 나타냅니다.
• 매칭된 규칙: 이 연결이 설정 파일의 어떤 라우팅 규칙에 매칭되었는지를 보여줍니다.
• 사용된 프록시 노드: 실제로 이 연결을 전달한 노드 또는 정책 그룹의 이름입니다.

로그 레벨은 보통 4단계로 나뉘며, 클라이언트 설정에서 표시할 최소 레벨을 조정할 수 있습니다.

1. Debug: 가장 상세한 레벨로, 규칙 매칭의 전체 과정이 포함됩니다. 평소에는 켜둘 필요 없이 복잡한 문제를 진단할 때만 켭니다.
2. Info: 기본 레벨로, 정상적인 연결 수립, 규칙 매칭, 노드 전환 등의 정보를 기록합니다.
3. Warning: 치명적이지 않은 이상 상황, 예를 들어 특정 DNS 조회가 보조 리졸버로 넘어갔거나 노드 측정이 타임아웃되었지만 다른 후보가 남아 있는 경우입니다.
4. Error: 연결 실패, 설정 로드 오류 등 주의가 필요한 문제로, 보통 구체적인 오류 텍스트가 함께 기록됩니다.

문제를 진단할 때는 먼저 레벨을 Info 또는 Debug로 조정한 뒤, 문제가 발생한 동작(예: 열리지 않는 웹페이지 접속)을 한 번 재현하고, 이후 로그에서 Error와 Warning 레벨의 기록을 살펴 문제가 발생한 정확한 요청을 찾는 것이 좋습니다.

connection refused 계열 오류

가장 흔한 오류 중 하나로, 전체 메시지는 보통 다음과 비슷합니다.

[Error] [TCP] dial tcp 203.0.113.10:443: connect: connection refused

이 오류의 의미는 로컬에서 연결 요청을 이미 보냈지만 상대편(노드 서버일 수도, 대상 사이트일 수도 있음)이 이번 TCP 연결을 명시적으로 거부했다는 것입니다. 흔한 원인은 세 가지로 나뉩니다.

• 노드 서버 사용 불가: 노드가 오프라인 상태이거나 서비스 제공자가 포트를 일시적으로 닫았거나, 노드 자체 설정에 오류(포트 번호, 암호화 방식이 서버와 불일치)가 있는 경우입니다. 이 경우 같은 구독 내 다른 노드로 바꿔보면 바로 확인할 수 있습니다.
• 로컬 방화벽 또는 보안 소프트웨어의 차단: 일부 보안 소프트웨어는 클라이언트가 생성하는 아웃바운드 연결을 차단하며, 특히 TUN 모드를 켠 경우 더 자주 발생합니다. 보안 소프트웨어의 실시간 보호 기능을 임시로 끄고 비교 테스트를 해볼 수 있습니다.
• 대상 사이트가 현재 노드 IP를 거부: 일부 사이트는 특정 IP 대역에 접속 제한을 걸어두는데, 이 경우 노드 자체가 정상이어도 해당 사이트 접속 시 계속 오류가 발생합니다. 노드를 바꾸는 것만이 해결책입니다.

이 세 가지 상황을 구분하는 간단한 방법은, 같은 노드로 여러 사이트에 접속해보는 것입니다. 모든 사이트에서 connection refused가 나온다면 노드 또는 로컬 환경 문제일 가능성이 높고, 특정 사이트에서만 오류가 나고 나머지는 정상이라면 대상 사이트가 해당 노드 IP를 제한하고 있을 가능성이 더 큽니다.

DNS 타임아웃과 해석 실패

DNS 관련 오류에는 보통 명확한 키워드가 포함됩니다. 예를 들면 다음과 같습니다.

[Warning] [DNS] resolve example.com failed: context deadline exceeded
[Error] [DNS] all DNS servers failed to resolve example.com

첫 번째는 특정 도메인 해석 요청이 타임아웃(설정된 시간을 초과)되었다는 뜻입니다. 일회성이라면 대체로 사용에 영향이 없으며, 코어가 자동으로 재시도하거나 다음 DNS 서버로 전환합니다. 두 번째는 설정 파일에 나열된 모든 DNS 서버가 해석에 실패했다는 뜻으로, 이 경우 웹페이지가 바로 열리지 않습니다.

DNS 해석 실패의 흔한 진단 방향은 다음과 같습니다.

1. 설정 파일의 DNS 섹션 확인: nameserver 목록의 주소가 실제로 사용 가능한지 확인합니다. 해외 DNS(예: 8.8.8.8, 1.1.1.1)를 사용한다면 이 주소로의 조회 요청 자체도 프록시를 거치도록 설정되어 있는지 확인해야 합니다. 그렇지 않으면 직접 연결이 불가능한 네트워크 환경에서는 마찬가지로 타임아웃이 발생합니다.
2. Fake-IP 모드 사용 여부 확인: Fake-IP는 도메인에 가상 IP를 할당하고 실제 연결 수립 시 코어가 실제 해석을 수행합니다. 이 단계 설정에 오류가 있으면(예: fake-ip-range가 로컬 네트워크 대역과 충돌) 도메인은 "해석"되지만 실제로는 연결되지 않는 형태로 나타납니다.
3. 로컬 Hosts 파일이나 다른 프록시 소프트웨어의 간섭 확인: 동시에 다른 네트워크 도구를 실행 중이거나 Hosts 파일에 오래된 도메인 매핑이 남아 있으면 DNS 계층에서 비정상 결과가 나올 수 있습니다.

구독 파싱 실패

구독을 업데이트할 때 아래와 같은 오류가 나온다면 문제는 프록시 노드 자체가 아니라 설정 파일을 가져오거나 파싱하는 단계에서 발생한 것입니다.

[Error] update subscription failed: Get "https://sub.example.com/link": context deadline exceeded
[Error] parse config failed: yaml: line 42: did not find expected key

첫 번째는 네트워크 단계의 실패입니다. 클라이언트가 타임아웃 시간 내에 구독 제공자 서버에서 내용을 받아오지 못한 경우로, 그 시점에 구독 링크에 접속할 프록시가 없었거나 구독 서버가 일시적으로 응답하지 않거나 구독 링크 자체가 만료된 경우가 흔한 원인입니다. 두 번째는 내용 단계의 실패입니다. 구독 내용은 성공적으로 다운로드되었지만 YAML 형식 파싱에서 오류가 발생한 경우로, 보통 구독 제공자가 정상적인 설정 대신 유지보수 안내 HTML 같은 오류 페이지를 반환했을 때 발생합니다.

구독 파싱 실패는 다음 순서로 확인하면 됩니다.

• 먼저 구독 링크가 브라우저에서 정상적으로 열리고 텍스트 내용이 보이는지 확인합니다. 오류 페이지나 빈 페이지가 열린다면 문제는 제공자 쪽에 있으므로 구독 제공처에 문의하거나 복구를 기다려야 합니다.
• 구독을 업데이트할 때 사용 중인 네트워크 환경을 확인합니다. 일부 클라이언트는 구독 업데이트 시 현재 활성화된 프록시가 아니라 "직접 연결"을 사용하는데, 직접 연결 환경에서 구독 도메인에 접속할 수 없으면 업데이트가 자연히 타임아웃됩니다.
• 구독 링크에 특수문자가 포함되어 있거나 일부가 잘려나가지 않았는지 확인합니다. 복사·붙여넣기 과정에서 공백이 하나 더 들어가거나 문자가 하나 빠지면 링크가 무효화됩니다.

정책 그룹 속도 측정 및 노드 전환 로그

설정 파일에서 자동 속도 측정 정책 그룹(예: url-test 또는 fallback 타입)을 사용 중이라면 로그에 아래와 같은 기록이 계속 나타납니다.

[Info] Proxy-HK check health: 156ms
[Warning] Proxy-SG check health failed: dial tcp: i/o timeout

이런 로그는 코어의 헬스 체크 메커니즘에 속하며, 일정 주기마다 정책 그룹 내 노드에 측정 요청을 보내 지연 시간을 기록하거나 사용 불가로 표시합니다. 특정 노드에서 check health failed가 계속 나온다면 그 노드에 실제로 문제가 있다는 뜻이며, 정책 그룹은 자동으로 해당 노드를 건너뛰고 지연이 낮은 대체 노드를 선택합니다. 설정을 바꾸지 않았는데도 접속 속도가 빨라지고 느려지기를 반복하는 것은 바로 정책 그룹이 노드 간에 동적으로 전환하고 있기 때문입니다.

그룹 전체 노드의 측정이 모두 실패한다면 보통 두 가지 상황을 의심할 수 있습니다. 하나는 구독 자체의 품질이 낮아 노드가 대량으로 사용 불가 상태인 경우이고, 다른 하나는 로컬 네트워크 환경 자체에 문제가 있어 모든 아웃바운드 연결이 수립되지 않는 경우입니다. 이때는 구독을 바꾸기 전에 먼저 로컬 네트워크 문제를 배제해야 합니다.

TUN 모드 관련 오류

TUN 모드(시스템 레벨 프록시, 전체 트래픽 인수)를 켰을 때 시작이 실패하면 로그에 보통 다음과 같이 비교적 직접적인 메시지가 나옵니다.

[Error] start TUN device failed: operation not permitted
[Error] start TUN device failed: address already in use

첫 번째는 거의 확실히 권한 문제입니다. TUN 모드는 가상 네트워크 어댑터를 생성해야 하며, 이 작업은 클라이언트가 관리자 권한으로 실행 중일 것을 요구합니다. 이전에 일반 권한으로 시작했다면 클라이언트를 관리자 권한으로 다시 열면 대개 해결됩니다. 두 번째는 가상 네트워크 어댑터가 사용하는 주소 대역이 현재 로컬 네트워크 설정과 충돌한다는 뜻으로, 다른 가상 네트워크 어댑터 기반 도구(일부 VPN 클라이언트 등)를 동시에 실행 중일 때 흔히 발생합니다. 충돌하는 소프트웨어를 먼저 종료하거나 설정에서 TUN이 사용하는 주소 대역을 조정해야 합니다.

오류 유형별 문제 진단 실전 절차

위의 여러 오류 유형을 하나로 정리하면 비교적 일반적으로 적용할 수 있는 진단 순서를 만들 수 있습니다.

1. 먼저 문제가 발생한 계층을 확인: 인터넷 자체가 완전히 안 되는지(TUN 또는 시스템 프록시 설정 문제일 가능성), 특정 사이트만 안 열리는지(노드 또는 규칙 문제일 가능성이 더 큼), 아니면 모든 사이트가 느린지(노드 품질 또는 국제 회선 문제일 가능성이 더 큼)를 구분합니다.
2. 로그 페이지를 열고 동작을 한 번 재현: 로그 레벨을 Info로 조정한 뒤 실패한 접속을 다시 시도하고, 이때 생성된 오류 텍스트를 기록합니다.
3. 키워드로 분류: dial tcp/connection refused는 노드 또는 대상 사이트 연결 문제, DNS 관련은 도메인 해석 계층, update subscription/parse config는 구독 가져오기 및 형식 문제, TUN 관련은 시스템 레벨 프록시 권한 또는 네트워크 장치 충돌을 가리킵니다.
4. 단계별로 배제: 먼저 로컬 환경(권한, 방화벽, 다른 프록시 소프트웨어 충돌)을 배제하고, 그다음 구독과 노드 자체를 확인하며, 마지막에 대상 사이트의 개별 제한을 고려합니다.

이 순서를 지키면 대부분의 오류는 몇 분 안에 대략적인 방향을 찾을 수 있으며, 시행착오식으로 설정이나 노드를 반복해서 바꿀 필요가 없습니다.

마무리

로그는 개발자만 보는 블랙박스 출력이 아니라 클라이언트가 "이번 연결이 어느 단계에서 막혔는지"를 알려주는 설명문입니다. 자주 나오는 오류 메시지의 키워드와 의미를 몇 분만 익혀두면, 문제가 생겼을 때 먼저 로그를 확인한 뒤 설정을 조정하는 방식이 클라이언트를 반복 재시작하거나 노드를 무작정 바꾸는 것보다 시간을 훨씬 절약하고 실제 원인을 찾는 데도 더 효과적입니다.