먼저 로그가 인터페이스, 커널 또는 운영체제에서 생성됐는지 확인하기
Clash 클라이언트에서 “연결 실패”가 발생하면 인터페이스 알림에는 보통 결과만 표시되고, 실제 원인 분석에는 커널 실행 로그가 필요합니다. Clash Meta(현재 명칭 Mihomo)는 DNS, 규칙 매칭, 노드 연결, TUN 데이터 전달을 담당하며, 데스크톱 클라이언트는 커널을 시작하고 시스템 프록시를 변경하며 로그를 표시합니다. 두 구성 요소에서 각각 오류가 발생할 수 있으므로, 첫 단계는 특정 영어 로그를 검색하는 것이 아니라 오류가 어느 계층에서 발생했는지 확인하는 것입니다.
| 로그 출처 | 일반적인 내용 | 우선 확인할 대상 |
|---|---|---|
| 클라이언트 인터페이스 로그 | 커널 시작 실패, 설정 저장 실패, 서비스 모드 설치 결과 | 클라이언트 권한, 커널 경로, 설정 파일 |
| Mihomo 커널 실행 로그 | DNS 조회, 규칙 매칭, 프록시 연결, 연결 시간 초과 | 구독 설정, 노드, DNS 및 네트워크 출구 |
| 운영체제 로그 | TUN 네트워크 인터페이스 생성 실패, 포트 사용 중, 권한 거부 | 관리자 권한, 방화벽, 실행 중인 프로세스 |
대부분의 데스크톱 클라이언트에서는 사이드바의 「로그」 페이지에서 커널 출력을 바로 확인할 수 있습니다. 일반적인 Mihomo 데스크톱 클라이언트라면 「설정」→「Clash 설정」→「로그 레벨」로 이동해 레벨을 info에서 잠시 debug로 변경한 다음 「로그」 페이지로 돌아와 문제를 재현하세요. 클라이언트마다 메뉴 이름은 조금씩 다르지만, 설정 파일에서 사용하는 표준 필드는 대개 log-level입니다.
log-level: debug문제를 재현할 때 전체 타임라인을 남기기
마지막 빨간색 오류 한 줄만 캡처하지 마세요. 하나의 연결은 보통 도메인 확인, 규칙 매칭, 정책 그룹 선택, 노드 연결, TLS 핸드셰이크를 차례로 거치며, 마지막 줄은 과정이 멈춘 위치만 나타냅니다. 현재 로그를 먼저 지우고 시스템 시간을 기록한 뒤 실패 동작을 한 번 실행하세요. 오류 전후 최소 10초 분량의 로그를 보관하는 것이 좋습니다.
- 계속 네트워크를 사용하는 동영상 재생, 동기화 및 다운로드 프로그램을 종료해 관련 없는 로그를 줄이세요.
- 클라이언트 로그를 지우고 현재 설정이 정상적으로 로드됐는지 확인하세요.
- 테스트용 주소 하나만 방문하세요. 예:
https://example.com. - 접속 시간, 선택한 정책 그룹 및 노드 이름을 기록하세요.
- DNS 조회 시작부터 연결 종료까지의 전체 구간을 내보내거나 복사하세요.
Clash 로그 한 줄은 어떤 필드로 나눠 봐야 할까
Mihomo의 버전과 클라이언트에서 가공하는 방식에 따라 표시 형식은 달라질 수 있지만 핵심 정보는 대체로 같습니다. 시간, 레벨, 네트워크 유형, 출발지 주소, 대상 주소, 매칭된 규칙, 최종 사용 아웃바운드 정책입니다. 다음은 일반적인 TCP 연결 기록입니다.
time="2026-07-27T14:32:18.412+08:00" level=info msg="[TCP] 127.0.0.1:53124 --> example.com:443 match DomainSuffix(example.com) using PROXY[HK-01]"[TCP]는 해당 세션이 TCP를 사용한다는 뜻입니다. DNS, QUIC 및 일부 게임 트래픽에는 UDP가 표시될 수도 있습니다.127.0.0.1:53124는 Clash로 들어온 로컬 출발지 연결이며, 끝의 포트는 보통 시스템이 임시로 할당합니다.example.com:443은 대상 도메인과 포트이며, 443은 일반적으로 HTTPS에 사용됩니다.match DomainSuffix(example.com)은 도메인 접미사 규칙이 매칭됐다는 뜻이며, 최종 규칙으로 바로 연결된 것은 아닙니다.using PROXY[HK-01]은 먼저 PROXY라는 정책 그룹에 들어간 뒤 실제 노드 HK-01이 선택됐다는 뜻입니다.
로그에 using DIRECT가 표시되면 해당 연결이 규칙에 따라 직접 연결로 판단된 것입니다. using REJECT가 표시되면 설정이 요청을 능동적으로 거부한 것입니다. 이 경우 노드를 바꿔도 결과가 달라지지 않는 경우가 많으므로 규칙 순서, 규칙 세트 내용 및 현재 실행 모드를 먼저 확인하세요. 규칙은 위에서 아래로 매칭되며, 앞에서 이미 매칭된 연결은 뒤의 규칙까지 계속 검사하지 않습니다.
info, warning, error와 debug는 어떻게 구분할까
| 레벨 | 용도 | 반드시 장애를 의미하는가 |
|---|---|---|
| info | 설정 로드, 연결 수립, 규칙 매칭 | 아니요. 주로 처리 흐름을 확인하는 데 사용합니다. |
| warning | 재시도, 호환성 폴백, 규칙 세트 업데이트 이상 | 항상 그런 것은 아닙니다. 기능에 영향을 주는지 확인해야 합니다. |
| error | 연결 실패, 확인 실패, 설정 로드 불가 | 대체로 조치가 필요합니다. |
| debug | 더 자세한 DNS, 연결 및 프로토콜 상태 | 아니요. 정보량이 많다는 뜻입니다. |
DNS 오류: 상위 DNS 실패와 로컬 리스너 실패를 먼저 구분하기
dns resolve failed, lookup failed 또는 exchange failed는 모두 도메인 확인 경로에서 정상적인 응답을 받지 못했다는 뜻이지만 원인은 서로 다를 수 있습니다. 일반적인 흐름은 애플리케이션이 시스템 또는 Mihomo에 조회를 전달하고, Mihomo가 설정된 nameserver에 접속한 뒤 결과를 받아 fake-ip 또는 redir-host 모드로 처리하는 방식입니다. 어느 한 구간이라도 끊기면 인터페이스에는 단순히 “DNS 실패”로 표시될 수 있습니다.
timeout이 보이면 상위 DNS 확인하기
level=error msg="dns resolve failed: lookup example.com: i/o timeout"
level=warning msg="[DNS] exchange failed: context deadline exceeded"i/o timeout 또는 context deadline exceeded는 제한 시간 안에 유효한 응답을 받지 못했다는 뜻입니다. 먼저 설정에 지정된 DNS 주소에 현재 네트워크에서 접근할 수 있는지 확인하세요. DoH를 사용한다면 해당 도메인 자체를 default-nameserver로 확인할 수 있는지도 확인해야 합니다. 사용 가능한 확인기가 바로 그 DoH 서버인 상황에서는 순환 의존이 발생할 수 있습니다.
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: fake-ip
default-nameserver:
- 223.5.5.5
- 1.1.1.1
nameserver:
- https://dns.alidns.com/dns-query
- https://1.1.1.1/dns-query이 예시는 로컬 DNS 리스너를 127.0.0.1:1053에 열고 DoH 도메인을 확인할 기본 DNS를 준비합니다. 실제로는 현재 네트워크에 맞춰 상위 주소를 조정해야 합니다. 다른 네트워크에서 접속 가능한 상위 DNS라고 해서 현재 Wi-Fi, 회사 네트워크 또는 모바일 핫스팟에서도 안정적으로 접속된다는 뜻은 아닙니다.
로컬 DNS 포트가 실제로 수신 대기 중인지 확인하기
로그에 bind: address already in use가 표시되면 설정에서 요구한 리스너 포트를 다른 프로세스가 사용 중이라는 뜻입니다. 포트 53은 시스템 DNS 서비스가 자주 사용하며, 일부 시스템에서는 일반 사용자 프로세스가 낮은 번호의 포트에 바인딩할 권한이 없습니다. 데스크톱 환경에서는 1053으로 변경한 뒤 클라이언트 또는 TUN의 DNS 하이재킹 기능으로 조회를 넘길 수 있습니다.
dig @127.0.0.1 -p 1053 example.com
nslookup example.com 127.0.0.1dig 명령은 1053 포트를 명시적으로 지정하며, 해당 도구가 설치된 macOS 또는 Linux에서 사용할 수 있습니다. Windows 기본 제공 nslookup은 53이 아닌 포트를 직접 지정하기 불편하므로 먼저 기본 리스너를 확인하는 편이 좋습니다. 설정이 1053을 사용한다면 클라이언트 로그에서 리스너가 정상적으로 시작됐는지 확인하거나 포트 검사 도구로 검증하세요.
dial tcp timeout: 노드, 네트워크 또는 대상 사이트 문제일까
dial tcp timeout은 제한 시간 안에 TCP 연결 단계가 완료되지 않았다는 뜻입니다. 핵심은 어디로 연결을 시도하는지 확인하는 것입니다. 대상이 프록시 서버의 IP와 포트라면 로컬 장치와 노드 사이에 문제가 있을 가능성이 큽니다. 이미 프록시를 거쳐 대상 사이트에 연결하는 단계라면 노드의 출구, 대상 사이트 또는 규칙 선택이 원인일 수 있습니다.
level=error msg="dial tcp 203.0.113.20:443: i/o timeout"
level=error msg="connect failed: dial tcp: lookup node.example.net: i/o timeout"
level=error msg="dial tcp 127.0.0.1:7890: connect: connection refused"- 첫 번째 줄에서 이미 노드 IP를 확인했지만 TCP 연결이 시간 초과됐다면 노드 포트, 현재 네트워크 출구 및 방화벽을 확인하세요.
- 두 번째 줄에서 노드 도메인조차 확인되지 않았다면 DNS 경로로 돌아가 처리해야 하며, 노드 속도 측정을 반복해서는 안 됩니다.
- 세 번째 줄에서 로컬 7890 포트가 연결을 거부했다면 보통 커널이 시작되지 않았거나 포트 설정이 다르거나 프로세스가 방금 종료된 것입니다.
로컬 프록시 포트로 반복 가능한 테스트 수행하기
설정의 mixed-port가 7890이라고 가정하면 먼저 포트를 확인한 뒤 명령줄 요청이 Clash를 명확히 통과하도록 할 수 있습니다. 다음 요청은 연결 시간 초과를 5초, 전체 제한 시간을 15초로 설정해 “즉시 거부”와 “기다린 후 시간 초과”를 구분하기 쉽게 합니다.
curl --proxy http://127.0.0.1:7890 \
--connect-timeout 5 \
--max-time 15 \
-I https://example.com명령이 1초도 지나지 않아 Connection refused를 반환하면 커널 프로세스와 로컬 포트를 먼저 확인하세요. 약 5초 후 연결 시간 초과가 발생한다면 로컬 포트는 대개 요청을 받은 상태이므로 노드 연결 단계에서 문제가 발생했을 가능성이 큽니다. HTTP/2 200 또는 HTTP/1.1 200 OK가 반환되면 테스트 주소에 현재 프록시를 통해 연결할 수 있다는 뜻입니다. 원래 애플리케이션의 문제는 프록시 설정 재정의, QUIC, 인증서 또는 별도 DNS에서 비롯됐을 수 있습니다.
Windows PowerShell에서는 다음 명령을 먼저 실행해 로컬 포트에 연결할 수 있는지 확인하세요.
Test-NetConnection 127.0.0.1 -Port 7890TcpTestSucceeded : True는 로컬 장치가 Clash의 리스너 포트에 연결할 수 있다는 뜻일 뿐, 원격 노드를 사용할 수 있다는 의미는 아닙니다. 이후에도 커널 로그의 정책 그룹, 노드 이름 및 원격 오류를 함께 확인해야 합니다.
connection refused와 network unreachable의 차이
| 오류 | 직접적인 의미 | 우선 조치 |
|---|---|---|
| connection refused | 대상 호스트가 연결을 명확히 거부했거나 로컬에서 수신 대기 중인 프로세스가 없음 | IP, 포트, 커널 프로세스 및 노드 서비스 상태 확인 |
| i/o timeout | 제한 시간 안에 읽기 또는 쓰기가 완료되지 않음 | 네트워크 출구를 테스트하고 노드를 바꿔 소요 시간 비교 |
| network is unreachable | 시스템에 대상 네트워크로 연결할 수 있는 경로가 없음 | 네트워크 인터페이스, IPv4/IPv6 라우팅 및 TUN 상태 확인 |
| TLS handshake timeout | TCP 이후 TLS 핸드셰이크가 제시간에 완료되지 않음 | 연결 품질, 시간, 프로토콜 매개변수 및 중간 네트워크 확인 |
| EOF | 상대방이 연결을 먼저 종료함 | 반복 발생 여부를 확인하고 다른 노드와 비교 |
TUN 모드 관련 로그 판단법
시스템 프록시는 프록시 설정을 능동적으로 읽는 애플리케이션에만 영향을 주지만, TUN 모드는 가상 네트워크 인터페이스를 통해 더 넓은 범위의 트래픽을 인계합니다. 브라우저는 정상인데 게임이나 터미널이 실패한다면 해당 프로세스의 연결 기록이 로그에 나타나는지 확인하는 것이 중요합니다. 기록이 전혀 없다면 트래픽이 아직 Mihomo에 들어오지 않은 경우가 많고, 규칙 매칭 후 연결에 실패했다면 프록시 경로 내부의 문제입니다.
TUN 시작 단계에서 자주 발생하는 오류로는 operation not permitted, failed to create tun device 및 라우팅 쓰기 실패가 있습니다. 이는 대개 권한, 서비스 모드 또는 가상 네트워크 인터페이스 상태와 관련됩니다. Windows 클라이언트에서는 「설정」→「서비스 모드」가 정상인지 확인한 뒤 TUN을 다시 활성화하세요. macOS와 Linux에서는 클라이언트 또는 커널에 가상 인터페이스 생성 및 라우팅 변경 권한이 있는지 확인해야 합니다.
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53auto-detect-interface는 Mihomo가 현재 기본 출구 인터페이스를 인식하도록 합니다. Wi-Fi, 유선 네트워크, VPN 또는 모바일 핫스팟을 자주 전환한 뒤에도 로그에 이전 인터페이스가 표시된다면 TUN을 끄고 시스템 라우팅이 안정될 때까지 기다린 후 다시 켜세요. 두 네트워크 도구가 동시에 기본 라우팅과 DNS 하이재킹 규칙을 작성하지 않도록 하세요. 그렇지 않으면 인터페이스 연결 불가와 DNS 시간 초과가 번갈아 나타날 수 있습니다.
로그에 대상 연결이 없을 때 의미하는 것
- 애플리케이션 자체 프록시 설정이 활성화되어 다른 포트를 가리키고 있습니다.
- 터미널에
HTTP_PROXY,HTTPS_PROXY또는ALL_PROXY가 설정되지 않았고 TUN도 활성화되지 않았습니다. - 브라우저가 QUIC을 사용하지만 현재 인계 방식이 해당 UDP 트래픽을 제대로 처리하지 못하고 있습니다.
- LAN 장치가 로컬 프록시에 접근하지만
allow-lan, 리스너 주소 또는 방화벽이 연결을 허용하지 않습니다. - TUN 가상 네트워크 인터페이스는 생성됐지만 기본 라우팅이 추가되지 않았거나 다른 네트워크 도구가 덮어썼습니다.
설정 및 구독 오류는 시작 단계에서 처리하기
커널이 설정 로드를 완료하지 못했다면 이후의 DNS 및 노드 테스트는 의미가 없습니다. YAML은 들여쓰기에 민감하므로 목록 항목, 콜론 및 문자열 형식 오류로 시작이 실패할 수 있습니다. 로그의 parse config error, yaml: line 42 또는 mapping values are not allowed는 대개 오류에 가까운 위치를 알려주지만 실제 문제는 바로 이전 줄에 있을 수도 있습니다.
proxy-groups:
- name: PROXY
type: select
proxies:
- Auto
- DIRECT같은 레벨에서는 들여쓰기 간격을 일관되게 유지하고 탭을 섞어 쓰지 마세요. 이름에 콜론, 해시 또는 다른 YAML 특수 문자가 포함되면 따옴표로 감싸세요. 구독 업데이트 후 provider not found, 존재하지 않는 정책 그룹 참조 또는 규칙 세트 로드 실패가 발생하면 참조 이름이 proxy-providers 및 rule-providers의 키와 대소문자와 공백까지 완전히 일치하는지 확인하세요.
HTTP 상태 코드로 구독 업데이트 문제 범위 좁히기
401또는403: 링크 인증이 유효하지 않거나 접근이 거부됐거나 구독 인증 정보가 변경됐습니다.404: 구독 또는 규칙 세트 경로가 존재하지 않습니다.429: 짧은 시간에 요청이 너무 많습니다. 반복 새로 고침을 중지하고 잠시 후 다시 시도하세요.500,502,503: 원격 서비스에 일시적인 문제가 있습니다. 잠시 후 다시 요청하세요.200을 반환했지만 파싱에 실패함: 응답이 유효한 YAML이 아닐 수 있으므로 콘텐츠 유형, 리디렉션 및 실제 응답 본문을 확인해야 합니다.
현상에서 결론까지 이어지는 문제 해결 순서
로그의 가치는 모든 오류를 나열하는 데 있지 않고 정상 흐름에서 처음 벗어난 지점을 찾는 데 있습니다. 한 번의 실패로 DNS 시간 초과, 노드 속도 측정 실패 및 규칙 세트 업데이트 실패가 동시에 발생할 수 있습니다. 로컬 네트워크가 이미 끊긴 상태라면 이 세 오류는 하나의 원인이 다르게 나타난 것일 뿐입니다. 정해진 순서대로 확인하면 관련 없는 설정 사이를 오가는 일을 줄일 수 있습니다.
- 기본 네트워크 확인: 시스템 프록시와 TUN을 끈 뒤 현재 네트워크에서 직접 연결이 허용된 사이트에 접속할 수 있는지 테스트하세요.
- 설정 로드 확인: 시작 단계에 YAML 파싱, 포트 사용 중 또는 provider 참조 오류가 나타나는지 확인하세요.
- 로컬 리스너 확인:
mixed-port: 7890과 같은 실제 포트를 확인하고 로컬 장치에서 연결할 수 있는지 테스트하세요. - DNS 확인: 노드 도메인과 대상 도메인이 확인되는지 관찰하고 로컬 리스너 실패와 상위 DNS 시간 초과를 구분하세요.
- 규칙 매칭 확인: 대상이 DIRECT, REJECT 또는 예상한 정책 그룹 중 어디로 연결되는지 확인하세요.
- 노드 연결 확인: 서로 다른 지역의 노드 두 개에서 오류와 소요 시간을 비교해 특정 노드만의 문제인지 판단하세요.
- 애플리케이션 인계 확인: 로그에 대상 기록이 없으면 시스템 프록시, 환경 변수, TUN 라우팅 및 애플리케이션 내부 프록시 설정을 다시 확인하세요.
- 일반 설정 복원: 테스트가 끝나면 로그 레벨을
info로 되돌리고 임시 프록시 환경 변수를 정리하세요.
예를 들어 브라우저에 연결할 수 없다는 메시지가 표시되고 로그에 먼저 lookup node.example.net: i/o timeout이 나타난 뒤 여러 노드의 속도 측정이 모두 실패했다면, 공통 장애 지점은 노드 도메인 확인입니다. 이때 노드 프로토콜을 하나씩 수정할 필요는 없습니다. 다른 예로 로그에 match MATCH using PROXY[US-02]가 명확히 표시된 뒤 US-02에서만 connection refused가 발생하고 HK-01로 전환하자 즉시 성공했다면 문제 범위는 단일 노드 또는 해당 포트로 좁혀집니다.
최종 기록에는 최소한 클라이언트 버전, Mihomo 커널 버전, 운영체제, 네트워크 유형, 현재 모드, 로그 레벨, 재현 시간 및 전체 오류 구간이 포함되어야 합니다. 버전 정보는 설정 필드의 지원 여부를 판단하는 데 도움이 되며, 네트워크 유형은 IPv6, 회사 네트워크 제한 또는 핫스팟 전환 문제를 파악하는 데 유용합니다. “트래픽이 Clash에 들어왔는가, DNS 확인이 완료됐는가, 어떤 규칙이 매칭됐는가, 어느 출구로 연결됐는가”라는 네 가지 질문에 답할 수 있다면 대부분의 실행 장애를 막연한 “프록시가 작동하지 않음”에서 검증 가능한 한 단계로 좁힐 수 있습니다.