Clash 로그 보는 법: 주요 오류 원인과 해결 순서 정리

클라이언트가 연결되지 않을 때 시스템 프록시를 껐다 켰다 하거나 노드를 무작정 하나씩 눌러보는 것이 가장 흔한 반응입니다. 사실 내부 로그에는 실패 원인이 꽤 구체적으로 남아 있지만, 형식이 압축적이고 영어 오류 메시지가 많아 그냥 지나치는 경우가 많습니다. 이 글에서는 오류 키워드를 기준으로 자주 나오는 로그 항목을 다섯 가지로 나누어, 각각 어느 단계에서 발생하는지, 보통 원인이 무엇인지, 다음에 무엇을 확인해야 하는지 하나씩 설명합니다.

로그 한 줄의 구조부터 이해하기

Clash 코어(Clash Meta, mihomo 포함)의 연결 로그 형식은 대체로 고정되어 있습니다. 전형적인 TCP 로그 한 줄을 예로 들면 다음과 같습니다.

[TCP] 127.0.0.1:52310 --> www.google.com:443 match DomainSuffix(google.com) using 노드 선택[홍콩 01]

다섯 개 항목으로 나눠서 보면 다음과 같습니다.

• [TCP] / [UDP]: 이 연결이 사용하는 전송 프로토콜입니다. 일반적인 웹 브라우징은 대부분 TCP이며, QUIC와 일부 게임·음성 통화는 UDP를 사용합니다.
• 127.0.0.1:52310: 로컬에서 어느 지점에서 연결을 시작했는지를 나타냅니다. 시스템 프록시 모드에서는 대개 127.0.0.1로 표시되고, TUN 모드에서는 좀 더 구체적인 내부 네트워크 주소가 보입니다.
• --> www.google.com:443: 목적지 주소와 포트입니다. 여기에 도메인이 아닌 IP가 표시되면 프로그램이 IP로 직접 연결을 시도하고 있다는 뜻이며, 이 경우 규칙의 도메인 매칭은 적용되지 않습니다.
• match DomainSuffix(google.com): 매칭된 규칙입니다. match Match()로 표시되면 앞의 규칙 세트에 하나도 걸리지 않고 마지막 기본 규칙까지 내려갔다는 의미입니다.
• using 노드 선택[홍콩 01]: 실제로 사용된 출구입니다. DIRECT로 표시되면 이 트래픽이 프록시를 거치지 않았다는 뜻이므로, 프록시를 타야 할 대상이 DIRECT로 나온다면 노드가 아니라 규칙 쪽 문제입니다.

로그의 상세 수준은 설정 파일의 log-level로 결정됩니다. silent, error, warning, info, debug 중 선택할 수 있으며 대부분의 클라이언트는 기본값으로 info를 사용합니다. 문제를 진단할 때는 먼저 debug로 전환하세요. 그러면 DNS 조회, 규칙 매칭 세부 내용, 핸드셰이크 과정까지 확인할 수 있습니다.

log-level: debug

GUI 클라이언트(Clash Verge Rev, Clash for Windows 등)는 로그 페이지에서 레벨을 바로 전환할 수 있습니다. 코어만 단독으로 실행하는 경우 로그는 표준 출력으로 나오며, external-controller를 설정하면 컨트롤러의 /logs API로 실시간 로그를 받아볼 수도 있습니다.

노드 연결 단계 오류

로그에 dial이라는 단어가 보이면 Clash가 노드 서버에 연결을 시도하고 있다는 뜻이며, 문제는 로컬 기기와 노드 사이 구간에서 발생한 것입니다.

[TCP] dial 홍콩 01 --> www.google.com:443 error: dial tcp 198.51.100.7:443: connect: connection refused

• connect: connection refused: 서버가 연결을 거부했으며, 해당 노드 포트에서 서비스가 대기 중이지 않은 상태입니다. 노드가 다운되거나 포트가 바뀌거나 구독 정보가 만료된 경우 자주 발생합니다. 같은 구독의 다른 노드로 먼저 바꿔보고, 전부 실패한다면 구독을 갱신하세요.
• i/o timeout / context deadline exceeded: 연결 시간 초과로, 요청을 보냈지만 아무 응답도 오지 않은 상태입니다. refused보다는 경로가 막혔거나 서버가 다운된 상황에 가깝습니다. Wi-Fi에서 모바일 핫스팟으로 바꿔 다시 테스트하면 통신사 문제인지 노드 문제인지 빠르게 구분할 수 있습니다.
• connection reset by peer: 연결이 성립된 후 상대방에 의해 중간에 끊긴 상태입니다. 한 번 정도라면 무시해도 되지만 반복되면 노드 부하가 높거나 전송 과정에서 간섭이 있다는 신호입니다.

이 단계는 로컬 프록시 설정과는 무관합니다. 로그에 dial 노드 기록이 이미 나온다면 트래픽은 이미 Clash까지 정상적으로 들어온 상태이므로, 시스템 프록시 스위치를 다시 만질 필요는 없습니다.

TLS 및 프로토콜 핸드셰이크 단계 오류

서버 연결은 됐지만 핸드셰이크에서 실패하는 경우 오류 키워드는 tls, x509, EOF 계열로 바뀝니다.

• x509: certificate has expired or is not yet valid: 인증서 시간 검증 실패입니다. 먼저 로컬 기기의 시스템 시간이 정확한지 확인하세요. 시간이 크게 틀어져 있으면 대부분의 TLS 계열 프로토콜이 실패합니다. 시스템 시간이 정상이라면 그다음 노드 측 인증서 설정을 의심해보세요.
• tls: first record does not look like a TLS handshake: 상대 포트에서 실행 중인 서비스가 TLS가 아닙니다. 보통 구독의 포트나 프로토콜 유형이 잘못 설정된 경우로, 예를 들어 Trojan 노드가 TLS를 사용하지 않는 포트를 가리키고 있는 경우입니다.
• EOF / tls: handshake failure: 핸드셰이크가 진행되다가 중간에 연결이 끊긴 상태입니다. SNI나 ALPN이 서버와 일치하지 않을 때 자주 발생하므로, 노드 설정의 servername / sni 값이 바뀌지 않았는지 확인하세요.
• Shadowsocks에서 cipher: message authentication failed 오류가 나오면 AEAD 검증 실패로, 비밀번호나 암호화 방식이 서버와 맞지 않는 경우입니다. 구독 출처로 돌아가 이 두 값을 다시 확인하세요.
• VMess 노드 설정이 맞는 것 같은데도 인증에 실패한다면 시스템 시간을 확인하세요. VMess는 타임스탬프로 검증을 수행하며, 로컬 시간과 서버 시간의 차이가 허용 범위를 넘으면 거부됩니다.
• WebSocket 계열 노드에서 websocket: bad handshake 오류가 나오면 경로(path)나 Host가 서버와 일치하지 않는 경우입니다. CDN 오리진 설정이 바뀐 뒤 특히 자주 발생합니다.

핸드셰이크 단계의 오류는 대체로 로컬 네트워크 품질과는 무관하며, 노드 파라미터 변경 여부와 구독 정보 만료 여부 두 가지에 집중해서 확인하면 됩니다.

설정 및 구독 로딩 단계 오류

이 유형의 오류는 코어를 실행하거나 구독을 갱신할 때 나타나며, 로그에 yaml, unmarshal, proxy provider 같은 단어가 함께 표시됩니다.

• yaml: line X: ... / unmarshal errors: 설정 파일 X번째 줄 근처의 문법 오류입니다. YAML은 들여쓰기에 Tab을 쓸 수 없고, 콜론 뒤에는 반드시 공백이 있어야 하며, 특수문자가 포함된 값은 인용부호로 감싸야 합니다. 표시된 줄 번호를 따라 확인하면 됩니다.
• proxy [xxx] not found: 정책 그룹이 존재하지 않는 노드를 참조하고 있습니다. 노드 이름을 바꾸거나 삭제한 뒤 정책 그룹을 함께 수정하지 않은 경우로, 참조 이름을 맞춰주면 해결됩니다.
• rules[X] ... error: X번째 규칙 파싱에 실패했습니다. 규칙 유형을 잘못 썼거나 파라미터 개수가 맞지 않는 경우가 흔한데, 예를 들어 마지막 목적지 정책을 빠뜨린 경우입니다.
• proxy provider ... error나 구독 갱신 시 404 또는 시간 초과가 뜬다면 구독 링크가 만료되었거나 구독 주소 자체가 현재 네트워크에서 접근되지 않는 경우입니다. 대부분의 클라이언트에는 "프록시를 통해 구독 갱신" 옵션이 있으니, 구독 주소가 프록시를 거쳐야만 접근 가능하다면 이 옵션을 켠 뒤 다시 갱신하세요.

설정 로딩에 실패하면 코어가 곧바로 종료되거나 시작을 거부하는 경우가 많아, 이 유형의 오류는 사실 가장 진단하기 쉬운 편입니다. 오류 메시지에 줄 번호와 필드명이 구체적으로 나오므로 그대로 고치면 됩니다.

DNS, 포트 충돌, TUN 관련 오류

• dns resolve failed나 DNS 조회 시간 초과: Clash 내장 DNS 설정이 잘못되었거나 상위 서버에 접근할 수 없는 상태입니다. 설정에서 dns.enable: true인지, nameserver 목록에 접근 가능한 상위 서버가 있는지 확인하세요. fake-ip 모드에서 문제가 발생하면 redir-host로 잠시 전환해 fake-ip 캐시 문제인지 먼저 확인해보세요.

dns:
  enable: true
  nameserver:
    - 223.5.5.5
    - 119.29.29.29

• bind: address already in use나 7890 포트 리스닝 실패: 혼합 포트가 이미 사용 중인 경우입니다. 대부분 다른 코어 프로세스나 같은 종류의 소프트웨어가 실행 중이기 때문이며, 기존 프로세스를 종료하면 해결됩니다. mixed-port 값을 바꿔 포트를 변경할 수도 있지만, 이 경우 시스템 프록시 설정의 포트도 함께 바꿔야 합니다.
• TUN 모드 시작 실패(permission denied, utun / wintun 장치를 찾을 수 없음): TUN에는 관리자 권한이 필요하며, Windows에서는 wintun 드라이버도 함께 필요합니다. 클라이언트를 관리자 권한으로 실행하세요. 여전히 오류가 발생하면 tun.stack을 system과 gVisor 사이에서 전환해보세요. 특정 스택이 특정 시스템 버전과 호환되지 않는 경우가 있습니다.
• 시스템 프록시 설정 실패: macOS에서는 네트워크 설정을 변경하려면 별도의 권한 승인이 필요합니다. Windows에서는 보안 소프트웨어가 프록시 스위치 쓰기 작업을 차단하고 있는지 확인하세요.

고정된 순서로 진단하기

1. 로그 레벨을 debug로 전환한 뒤 문제 상황을 한 번 그대로 재현해, 오류가 로그 끝부분에 신선하게 남도록 합니다.
2. 아래에서 위로 올라가며 첫 번째 error 또는 warning을 찾으세요. 마지막 줄만 보면 안 됩니다. 그 뒤로 쏟아지는 내용은 대부분 첫 번째 오류에서 파생된 연쇄 반응일 뿐입니다.
3. 첫 번째 오류를 키워드로 다섯 단계 중 하나로 분류하세요. 설정 로딩, 구독 갱신, DNS 해석, 노드 연결, 프로토콜 핸드셰이크 중 어디에 해당하는지 판단한 뒤 앞서 설명한 내용을 참고해 처리하면 됩니다.
4. 교차 검증도 필요합니다. 시스템 프록시를 거치지 않고 Clash 포트로 직접 테스트해보세요.

curl -x http://127.0.0.1:7890 https://www.google.com -I

1. 이 요청이 성공하면 코어와 노드는 정상이며 문제는 시스템 프록시나 브라우저 쪽에 있습니다. 실패하면 문제는 코어와 노드 사이에 있습니다. 한 번에 한 가지만 바꿔서 테스트하세요. 세 가지를 동시에 바꾸면 어느 것이 원인이었는지 영영 알 수 없습니다.

오류 키워드 빠른 참조표

로그는 Clash가 남기는 가장 확실한 증거입니다. 먼저 로그를 읽고 나서 손을 대는 습관을 들이면, 진단 순서가 고정된 뒤로는 대부분의 접속 문제를 몇 분 안에 구체적인 단계까지 좁혀낼 수 있습니다.