Clash 실행 로그 확인 방법: 주요 오류 의미와 진단 순서

먼저 로그 출처와 시간 범위를 확인하기

Clash 클라이언트의 ‘로그’는 서로 다른 두 계층에서 생성될 수 있습니다. 그래픽 클라이언트는 구독 다운로드, 설정 전환, 커널 시작, 시스템 프록시 설정을 담당하고, Clash Meta（mihomo） 같은 커널은 DNS, 규칙 매칭, 연결 수립, 정책 그룹 선택, TUN 데이터 처리를 담당합니다. 두 종류의 로그가 한 창에 섞여 있다면 먼저 오류가 어느 계층에서 발생했는지 확인해야 합니다.

예를 들어 구독 요청에서 403 응답이 반환되었다면 보통 클라이언트의 설정 업데이트 과정에 해당합니다. 반면 어떤 도메인이 규칙에 매칭된 뒤 연결 시간이 초과되었다면 커널 실행 단계의 문제입니다. 마지막 한 줄만 잘라 보면 결과를 원인으로 오해하기 쉽습니다. 장애가 발생한 시점부터 과거로 거슬러 올라가 첫 번째 이상 로그와 그 직전의 마지막 정상 기록을 찾는 것이 올바른 방법입니다.

로그 행에는 보통 어떤 정보가 포함되나요

• 시간: 구독 업데이트 클릭, 노드 전환, TUN 활성화 등 사용자의 작업과 로그를 정확한 시점으로 연결하는 데 사용됩니다.
• 레벨: debug는 상세한 처리 과정을, info는 정상 상태를 기록합니다. warn은 주의가 필요하지만 반드시 중단되는 것은 아님을 뜻하고, error는 현재 단계가 실패했음을 의미합니다.
• 모듈: 설정 로드, DNS, 인바운드 리스너, 프록시 다이얼링, 규칙 매칭, TUN 등이 일반적인 모듈입니다.
• 대상: 도메인, IP, 포트, 네트워크 인터페이스, 설정 파일 경로 또는 정책 그룹 이름일 수 있습니다.
• 오류 체인: 하나의 오류는 여러 구문이 연결된 형태로 나타날 수 있으며, 대개 왼쪽에서 오른쪽으로 실행 과정을 설명합니다. 가장 끝에는 운영 체제나 네트워크 라이브러리가 반환한 직접적인 원인이 표시됩니다.

진단하기 전에 가장 작은 단위로 장애를 한 번 재현하세요. 현재 로그 위치를 지우거나 기억한 뒤 한 가지 동작만 수행하고 해당 구간의 로그를 저장합니다. 웹페이지가 열리지 않는 문제라면 구독 업데이트, 모드 전환, DNS 수정, 노드 변경을 동시에 하지 마세요. 여러 조건을 한 번에 바꾸면 로그에서 원인과 결과의 관계를 판단하기 어려워집니다.

시작 및 설정 해석 오류: 먼저 파일을 확인하고 포트는 그다음에 확인하기

커널이 시작되지 않으면 이후의 DNS, 규칙, 노드 테스트는 의미가 없습니다. 이 단계에서는 먼저 설정 파일을 읽고 해석할 수 있는지 확인한 다음 리스닝 포트, 제어 포트, 파일 권한, 리소스 파일을 점검해야 합니다. 그래픽 인터페이스의 ‘시작 실패’는 요약 상태일 뿐이며, 실제 원인은 보통 그 앞의 몇 줄에 있습니다.

설정 문법 및 필드 오류

일반적으로 yaml, unmarshal, invalid config, field not found 또는 특정 행과 열을 가리키는 메시지가 표시됩니다. YAML은 들여쓰기에 민감하므로 Tab, 잘못된 계층, 닫히지 않은 따옴표, 목록 형식 오류가 모두 로드를 막을 수 있습니다. 다음 규칙은 목록 계층 안에 있어야 합니다:

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

로그에 알 수 없는 필드가 표시되면 설정이 대상으로 하는 커널 유형과 버전도 확인해야 합니다. Clash Meta（mihomo）가 지원하는 일부 필드는 구버전 Clash 설정 기능에 포함되지 않을 수 있으며, 반대의 경우도 발생할 수 있습니다. 파일 확장자가 .yaml이라는 이유만으로 호환된다고 판단하지 마세요. 필드 이름, 프록시 프로토콜, 규칙 집합 작성 방식, DNS 설정 구조를 확인해야 합니다.

포트가 이미 사용 중임

address already in use는 지정한 리스닝 주소와 포트를 다른 프로세스가 이미 사용 중이라는 뜻입니다. 흔한 대상은 mixed-port, port, socks-port, external-controller입니다. 이전 커널이 종료되지 않았거나 다른 프록시 도구가 실행 중일 때, 또는 두 설정이 같은 포트를 동시에 수신할 때 주로 발생합니다.

처리 순서는 다음과 같습니다. 먼저 중복 실행된 Clash 또는 mihomo 프로세스가 있는지 확인하고, 그다음 다른 프록시 소프트웨어를 점검한 후, 마지막으로 포트 변경을 고려하세요. 포트를 바꾼 뒤에는 브라우저, 터미널 환경 변수, 로컬 네트워크 장치에 입력된 프록시 포트도 함께 업데이트해야 합니다. 그렇지 않으면 커널은 시작되어도 애플리케이션이 이전 포트에 계속 연결합니다.

권한 및 파일 경로 문제

permission denied는 대상 경로와 함께 판단해야 합니다. 설정 디렉터리 접근에 실패했다면 보통 디렉터리 권한이나 파일 사용 중 상태가 원인입니다. TUN 인터페이스 생성에 실패했다면 관리자 권한, 시스템 확장 기능, 네트워크 서비스 권한과 관련될 수 있습니다. no such file or directory는 설정에서 참조한 규칙 집합, GeoIP 데이터베이스, 인증서 파일이 없다는 뜻인 경우가 많습니다. 이때는 로그에 표시된 전체 경로를 확인하고, 현재 열려 있는 기본 설정 파일만 점검하지 마세요.

구독 업데이트 오류: 다운로드 실패와 해석 실패 구분하기

구독 업데이트는 ‘요청 전송, 응답 수신, 콘텐츠 식별, 설정 생성, 설정 로드’ 단계로 이루어집니다. 최종 화면에는 모두 업데이트 실패로 표시될 수 있지만 단계마다 해결 방법은 다릅니다. 먼저 HTTP 상태 코드, 응답 유형, 해석 정보를 기록한 뒤 네트워크, 구독 권한, 형식 호환성 중 무엇을 확인할지 결정하세요.

브라우저에서 구독 주소가 열린다고 해서 클라이언트에서도 반드시 업데이트되는 것은 아닙니다. 브라우저와 클라이언트는 서로 다른 네트워크 경로, User-Agent, DNS 결과, 프록시 설정을 사용할 수 있습니다. 진단할 때는 브라우저 화면이 아니라 클라이언트에 실제로 기록된 상태 코드와 응답을 확인해야 합니다.

‘구독 콘텐츠가 비어 있음’과 ‘설정에 사용 가능한 노드가 없음’도 구분해야 합니다. 일부 구독은 proxies, proxy-groups, rules를 포함한 완전한 Clash 설정을 반환하고, 일부는 클라이언트의 변환이 필요한 일반 노드 목록만 제공합니다. 변환기가 프로토콜 필드를 인식하지 못하면 일부 노드만 생성되거나 정책 그룹을 아예 만들지 못할 수 있습니다. 이때는 원본 응답 유형에 대한 판단 정보를 보존하고, 구독이 Clash 또는 Mihomo 형식을 명시적으로 제공하는지 확인하세요.

DNS 오류: 해석 실패와 연결 실패 구분하기

DNS 로그는 연결 오류보다 먼저 나타나는 경우가 많지만 도메인에 접근할 수 없다고 해서 반드시 DNS 문제인 것은 아닙니다. 먼저 로그에서 대상 IP를 얻었는지 확인하세요. 명확한 해석 시간 초과, 상위 DNS 서버 접근 불가, 빈 응답이 나타나면 문제는 DNS 단계에 있습니다. IP를 얻은 뒤 다이얼링 시간 초과나 TLS 오류가 발생했다면 프록시 경로를 계속 점검해야 합니다.

일반적인 DNS 로그의 의미

• no such host: 시스템 해석기 또는 지정한 상위 DNS 서버가 사용 가능한 주소를 반환하지 않았거나, 도메인 자체의 철자가 잘못되었을 수 있습니다.
• i/o timeout: DNS 상위 서버에 질의를 보낸 뒤 정해진 시간 안에 응답을 받지 못했다는 뜻입니다. 상위 서버 주소, 네트워크 경로, 방화벽을 확인해야 합니다.
• connection refused: 대상 DNS 서비스 주소에는 도달했지만 해당 포트가 연결을 받지 않거나, 로컬 전달 서비스가 실행 중이 아니라는 뜻입니다.
• server misbehaving: 상위 서버의 응답이 비정상이라는 뜻으로, 프로토콜 비호환, 응답 형식 문제, 중간 네트워크 간섭이 관련될 수 있습니다.
• fake-ip 관련 기록: 도메인이 Fake-IP 매핑 절차에 들어갔다는 뜻입니다. 그 자체로 오류는 아니므로 이후 규칙 매칭과 실제 연결 결과를 계속 확인해야 합니다.

Fake-IP 모드에서는 애플리케이션이 먼저 예약된 주소 범위의 매핑 IP를 받고, 커널이 매핑을 통해 도메인을 복원한 뒤 규칙을 적용합니다. 대상 주소가 Fake-IP 범위에 속한다고 해서 곧바로 원격 서버 주소로 보면 안 됩니다. 일부 로컬 네트워크 서비스, 시간 동기화, 게임, 특수 프로토콜이 비정상적으로 작동한다면 fake-ip-filter에서 해당 도메인을 제외해야 하는지 확인할 수 있지만, 많은 도메인을 무조건 필터 목록에 넣는 것은 권장하지 않습니다.

TUN을 활성화하면 DNS가 가로채기와 리디렉션을 거칠 수도 있습니다. 따라서 시스템 설정에 표시된 DNS 서버가 최종적으로 사용되는 상위 서버와 다를 수 있습니다. 진단할 때는 Clash의 dns.enable, 리스닝 주소, nameserver, fallback 또는 정책 기반 DNS 설정과 TUN의 DNS 가로채기 설정을 함께 확인해야 합니다. 포트 53을 로컬 해석 서비스가 이미 사용 중이라면 로그에는 웹페이지에 접근할 때가 아니라 시작 단계에서 리스닝 실패가 표시되는 경우가 많습니다.

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

위 예시는 필드 간 관계를 보여 주기 위한 것입니다. 실제 설정에서는 현재 네트워크 환경과 커널 문서에 따라 상위 DNS 서버를 선택하세요. DNS를 수정할 때는 한 번에 한 항목만 바꾸고 같은 도메인으로 반복 테스트해야 합니다. 강화 모드, 상위 서버 프로토콜, TUN 가로채기를 동시에 전환하면 로그 변화의 원인을 파악하기 어려워집니다.

연결·핸드셰이크·시간 초과 오류: 프록시 경로를 구간별로 확인하기

규칙이 정책과 노드를 선택하면 커널은 프록시 서버에 연결하고, 프록시 서버가 대상에 접속합니다. 로그의 시간 초과는 로컬에서 노드로 가는 구간, 노드에서 대상까지의 구간, 프록시 프로토콜 핸드셰이크, TLS 핸드셰이크 중 어느 단계에서든 발생할 수 있습니다. 오류 직전에 기록된 아웃바운드 이름, 대상 주소, 네트워크 유형을 찾는 것이 핵심입니다.

connection refused

연결 거부는 대상 호스트가 포트를 사용할 수 없다고 명확히 응답했다는 뜻입니다. 대상이 프록시 노드 주소라면 노드 포트, 서비스 상태, 프로토콜 설정을 확인하고, 대상이 로컬 제어 포트라면 클라이언트가 연결하는 제어 주소가 올바른지 점검하세요. 시간 초과와는 다릅니다. 시간 초과는 대개 제때 응답하지 않았다는 뜻이고, 연결 거부는 네트워크가 특정 호스트까지 도달했지만 해당 포트가 연결을 받지 않았다는 뜻입니다.

i/o timeout 및 context deadline exceeded

이런 메시지는 작업이 시간 제한을 초과했다는 뜻입니다. 먼저 정상 작동이 확인된 노드로 전환한 뒤 같은 대상에 테스트하세요. 여러 노드에서 동시에 시간 초과가 발생하면 로컬 네트워크, DNS, 시스템 방화벽, 프록시 모드를 확인해야 합니다. 한 노드에서만 시간 초과가 발생한다면 해당 노드의 회선을 우선 점검하세요. 일반 웹사이트는 열리지만 특정 사이트만 시간 초과된다면 해당 도메인이 부적절한 정책으로 배정되었는지 규칙을 확인하세요.

EOF, 연결 재설정 및 TLS 핸드셰이크 실패

EOF는 예상한 데이터가 모두 전송되기 전에 연결이 닫혔다는 뜻이며, 이 한 줄만으로는 원인을 확정하기 어렵습니다. 원격 서버의 능동적인 연결 종료, 프록시 프로토콜 매개변수 불일치, 전송 계층 설정 차이, 중간 네트워크의 연결 재설정이 원인일 수 있습니다. connection reset by peer는 상대방 또는 경로상의 장비가 연결을 재설정했다는 의미가 더 분명합니다.

TLS 오류에서는 시스템 시간, 인증서 도메인, SNI, 노드 전송 설정, 대상 사이트를 확인해야 합니다. 인증서 이름이 일치하지 않는다는 로그가 표시되면 인증서 검증을 장기간 비활성화해 문제를 가리지 말고 서버 이름과 노드 매개변수를 확인하세요. 시스템 시간 오차도 인증서가 아직 유효하지 않거나 이미 만료되었다는 판단을 잘못 일으킬 수 있습니다.

UDP와 TCP의 동작 차이

노드로 웹페이지를 열 수 있다는 것은 주요 TCP 경로가 작동한다는 뜻일 뿐입니다. 음성 통화, 게임, QUIC, 일부 DNS 요청은 UDP에 의존합니다. UDP 연결에서 오류가 발생하면 노드 프로토콜과 서버가 UDP를 지원하는지, 정책 그룹이 해당 노드를 선택했는지, 시스템 방화벽이 관련 트래픽을 허용하는지 확인하세요. 진단 중에는 애플리케이션을 TCP로 임시 전환해 문제가 UDP 경로에만 있는지 확인할 수 있지만, 최종적으로는 실제 설정을 수정해야 합니다.

규칙 매칭, 프록시 모드 및 TUN: 로그가 정상이어도 경로가 잘못될 수 있음

일부 장애에는 뚜렷한 error가 나타나지 않습니다. 연결은 성공했지만 잘못된 노드를 사용하거나 예상치 않게 직접 연결된다면 규칙, 모드, 트래픽 가로채기 범위의 문제일 가능성이 큽니다. 이때 로그 레벨을 잠시 debug로 높이고 도메인, 프로세스, 규칙 유형, 정책 그룹, 최종 아웃바운드 사이의 관계를 관찰하세요. 테스트가 끝나면 평소 사용하는 레벨로 되돌려 로그가 계속 증가하지 않도록 합니다.

현재 프록시 모드 먼저 확인하기

• 규칙 모드: 규칙을 위에서부터 순서대로 매칭하고, 일치하면 지정된 정책을 사용합니다. 대부분의 세밀한 분기 문제는 이 모드에서 진단해야 합니다.
• 글로벌 모드: 모든 트래픽을 글로벌 정책으로 전달하므로 일반적인 분기에서는 규칙 목록이 보통 사용되지 않습니다. 노드 연결성을 테스트할 때는 유용하지만 규칙이 올바른지는 검증할 수 없습니다.
• 직접 연결 모드: 트래픽이 대상에 직접 연결됩니다. 규칙 모드로 되돌리는 것을 잊으면 노드 상태가 정상이어도 예상한 프록시 연결이 발생하지 않습니다.

규칙 모드에서는 규칙의 개수보다 순서가 중요합니다. 예를 들어 포괄적인 DOMAIN-SUFFIX 규칙이 정확한 규칙보다 앞에 있으면 대상을 먼저 가로챌 수 있습니다. GEOIP, GEOSITE, 규칙 집합, 최종 MATCH의 위치도 결과를 바꿉니다. 로그에 예상치 못한 규칙이 매칭되었다면 최종 정책 그룹만 수정하지 말고 설정에서 해당 규칙을 찾아 앞쪽 규칙의 적용 범위를 확인하세요.

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

위 순서에서는 api.example.com이 먼저 직접 연결되고, 그 외 example.com 하위 도메인은 프록시로 전달됩니다. 두 규칙의 순서를 바꾸면 정확한 규칙이 매칭될 기회를 잃습니다.

TUN은 켜졌지만 애플리케이션이 로그에 나타나지 않음

애플리케이션이 요청을 보냈는데 해당 연결이 로그에 전혀 나타나지 않는다면 문제는 대개 트래픽이 커널에 들어오기 전 단계에 있습니다. TUN 인터페이스가 정상적으로 생성되었는지, 기본 경로가 설치되었는지, 자동 경로 설정이 적용되었는지, 다른 VPN·가상 네트워크 카드·보안 소프트웨어가 라우팅 우선순위를 바꾸지 않았는지 확인하세요. 일부 애플리케이션은 별도의 프록시 설정을 사용하기도 합니다. 이 설정이 이전 포트를 가리키면 현재 TUN 경로를 우회할 수 있습니다.

로그에 operation not permitted, 인터페이스 생성 실패, 경로 추가 실패가 나타나면 실행 권한과 시스템 네트워크 기능을 확인해야 합니다. Linux에서는 TUN 장치, 네트워크 관리자, 라우팅 테이블, 서비스 계정 권한도 확인하세요. Windows와 macOS에서는 가상 네트워크 카드, 시스템 확장 기능, 관리자 승인 상태를 점검해야 합니다. 클라이언트마다 구현 방식이 다르므로 로그에 실제로 실패한 시스템 작업을 기준으로 판단하세요.

재사용 가능한 진단 순서: 첫 번째 이상 로그에서 설정 항목까지

안정적인 진단 과정은 하위 계층의 상태에서 시작해 구체적인 요청으로 단계적으로 나아가야 합니다. 시작 상태를 건너뛰고 바로 노드를 바꾸거나 DNS라는 단어만 보고 전체 DNS 설정을 다시 작성하면 변수가 늘어나는 경우가 많습니다. 다음 순서는 ‘시작할 수 없음, 구독 업데이트 실패, 웹페이지가 열리지 않음, 특정 애플리케이션만 이상함’과 같은 일반적인 상황에 적용할 수 있습니다.

1. 장애 범위를 기록합니다. 모든 웹사이트인지, 특정 도메인인지, 특정 애플리케이션인지, TCP인지 UDP인지, 아니면 TUN을 켠 뒤에만 발생하는지 명확히 하세요.
2. 커널이 실행 중인지 확인합니다. 설정이 정상적으로 로드되었는지, 프록시 포트와 제어 포트가 리스닝 중인지, 권한 또는 파일 누락 오류가 없는지 점검하세요.
3. 설정 출처를 확인합니다. 방금 구독을 업데이트했다면 다운로드 성공 여부, 응답 형식의 정확성, 새 설정의 해석 가능 여부를 먼저 확인하세요.
4. 요청이 커널에 들어오는지 확인합니다. 한 번 재현 가능한 테스트를 실행하고 해당 시각에 연결 기록이 나타나는지 확인하세요. 기록이 없다면 시스템 프록시, 애플리케이션 프록시, TUN 경로를 점검합니다.
5. DNS 결과를 확인합니다. 도메인 해석이 완료되었는지, Fake-IP 매핑이 현재 모드에 맞는지, DNS 상위 서버가 시간 초과되지 않는지 확인하세요.
6. 규칙과 정책을 확인합니다. 현재 모드, 매칭된 규칙, 정책 그룹, 실제 노드를 대조해 잘못된 트래픽 분기를 노드 장애로 오해하지 않도록 하세요.
7. 연결 단계를 확인합니다. 로컬에서 노드로 가는 구간, 프로토콜 핸드셰이크, TLS, 노드에서 대상까지의 구간, UDP 경로를 구분하고 한 번에 하나의 조건만 바꿔 테스트하세요.
8. 최근 변경 사항을 되돌립니다. 마지막으로 정상 작동한 설정을 복원한 뒤 DNS, TUN, 규칙, 노드 변경을 하나씩 적용해 장애를 일으킨 최소 차이를 찾으세요.

유효한 진단 기록에는 최소한 클라이언트와 커널 이름, 운영 체제, 장애 시각, 현재 모드, TUN 활성화 여부, 재현 동작, 첫 번째 이상 로그, 매칭된 정책, 이미 테스트한 단일 변수가 포함되어야 합니다. 버전도 중요합니다. 필드 지원 범위, 기본 동작, 오류 문구가 커널과 클라이언트 업데이트에 따라 달라질 수 있기 때문입니다.

로그 판단의 핵심은 가능한 많은 오류 행을 수집하는 것이 아니라 실행 순서를 세우는 데 있습니다. 설정이 먼저 읽히고, 포트가 이어서 리스닝하며, 구독이 설정을 만들고, DNS가 대상을 제공하고, 규칙이 정책을 선택하고, 노드가 연결을 수립하며, TUN이 더 많은 애플리케이션 트래픽을 커널로 보낼지 결정합니다. 각 로그를 이 흐름에 다시 배치하면 막연한 ‘Clash가 작동하지 않음’이 구체적인 필드, 포트, 상위 서버, 네트워크 인터페이스 문제로 좁혀집니다.