Clash 실행 로그 확인 방법: 자주 발생하는 오류 원인과 해결 절차

1. 로그 열기: 세 가지 경로

먼저 방법부터. 어떤 클라이언트를 쓰든 로그는 결국 같은 곳에서 나옵니다—바로 커널입니다. 그래픽 인터페이스는 커널이 출력하는 내용을 그대로 받아 보여줄 뿐이므로, 각 클라이언트에서 보이는 오류 문구는 사실상 동일합니다. 이 텍스트를 읽는 법을 익히면 어떤 클라이언트든 다 통합니다. 로그를 확인하는 방법은 사용 방식에 따라 세 가지로 나뉩니다.

1. GUI 클라이언트의 로그 페이지. Clash Verge Rev는 왼쪽 메뉴에 "로그" 항목이 있어 클릭하면 커널 로그가 실시간으로 흐르며, 상단에서 레벨별 필터링도 가능합니다. Clash for Windows는 "Logs" 탭이 이에 해당하며 마찬가지로 레벨 필터링을 지원합니다.
2. 커널 설정의 log-level. mihomo 커널을 직접 실행하면 로그가 터미널에 출력되며, 상세 수준은 설정 파일의 log-level 항목으로 조절합니다. silent, error, warning, info, debug 다섯 단계 중 선택할 수 있고 기본값은 info입니다.
3. 외부 컨트롤러 API. 커널에서 external-controller(일반적으로 127.0.0.1:9090)를 활성화하면 /logs?level=info 엔드포인트가 실시간 로그 스트림을 계속 전송합니다. GUI 클라이언트의 로그 페이지도 이 경로를 사용합니다.

2. 로그 한 줄의 구성: 시간, 레벨, 연결 정보

먼저 전형적인 info 레벨 실행 로그 한 줄을 보겠습니다(클라이언트마다 표시 형식은 조금씩 다르지만 구성 요소는 동일합니다):

2026-06-19 21:03:11 INFO [TCP] 127.0.0.1:52341 --> www.example.com:443 match DomainSuffix(example.com) using 홍콩 노드

네 부분으로 나눠 보겠습니다:

• 시간 2026-06-19 21:03:11: 문제를 확인할 때는 먼저 이 시각을 자신이 조작한 시점과 맞춰봐야 합니다. 그 이전의 로그는 이번 문제와 무관합니다.
• 레벨 INFO: 낮은 순부터 debug, info, warning, error 순이며, 레벨이 높을수록 주의 깊게 봐야 합니다.
• 연결 [TCP] 127.0.0.1:52341 --> www.example.com:443: 왼쪽은 로컬 출발지 주소와 임시 포트, 오른쪽은 접속 대상 주소와 포트입니다.
• 결과 match DomainSuffix(example.com) using 홍콩 노드: 이 연결이 어떤 규칙에 매칭되어 어떤 출구로 전달됐는지를 나타냅니다—출구는 노드일 수도 있고 DIRECT(직접 연결) 또는 REJECT(차단)일 수도 있습니다.

왜 이런 형태인지도 짚어보겠습니다. Clash의 동작 원리는 "연결이 들어오면 규칙표를 조회하고 하나의 출구로 넘긴다"는 것이므로, 실행 중 로그는 거의 이 한 문장 패턴을 반복합니다. 로그를 읽는다는 것은 결국 세 가지를 대조하는 일입니다: 대상이 맞는지, 규칙 매칭이 맞는지, 출구가 맞는지. 이 세 가지가 모두 맞는데도 접속이 안 된다면 그제야 노드와 회선 문제를 살펴봐야 합니다.

3. 자주 발생하는 오류 다섯 가지

1. 연결 시간 초과: i/o timeout

2026-06-19 21:04:02 WARN [TCP] dial 홍콩 노드 127.0.0.1:52341 --> www.google.com:443 error: dial tcp 203.0.113.8:443: i/o timeout

의미: 커널이 노드 서버로 연결을 시도했지만 시간이 다 되도록 응답이 없었습니다. context deadline exceeded도 같은 의미의 다른 표현입니다. "노드 → 회선 → 로컬" 순서로 확인하세요:

1. 노드 목록에서 지연 시간 테스트를 실행합니다: 전체가 시간 초과라면 대부분 구독 만료나 로컬 네트워크 단절이고, 특정 노드만 시간 초과라면 그 노드 자체의 문제입니다.
2. 같은 대상에 다른 노드로 접속해서 정상 접속되면 원래 노드가 문제였음을 확인할 수 있습니다.
3. 모든 노드에서 접속이 안 될 때는 같은 대상을 DIRECT로 바꿔서 한 번 시도해보세요. 직접 연결도 안 되면 로컬 네트워크 자체의 문제입니다.

원인: timeout은 단지 "응답을 받지 못했다"는 뜻일 뿐, 노드 다운, 회선 차단, 로컬 네트워크 단절 중 무엇인지는 구분해주지 않습니다. 따라서 반드시 단계별로 원인을 좁혀가야 하며, 시간 초과가 보인다고 바로 클라이언트를 바꿀 필요는 없습니다.

2. 구독 및 설정 파싱 실패

2026-06-19 21:05:40 ERROR configuration file error: yaml: unmarshal errors: line 86: cannot unmarshal !!str into map[string]interface {}

의미: 설정 파일 86행 근처의 YAML 구조에 문제가 있어 커널이 시작을 거부합니다. 흔한 원인은 세 가지입니다: 수동 편집 후 들여쓰기가 어긋난 경우, 구독 링크가 YAML이 아니라 오류 안내 웹페이지를 반환한 경우, 현재 커널이 인식하지 못하는 필드가 설정에 섞여 있는 경우입니다. 또 다른 흔한 형태는 다음과 같습니다:

2026-06-19 21:05:41 ERROR proxy 3: unsupport proxy type: hysteria

의미: 네 번째 노드(0부터 시작하는 순번)가 커널이 지원하지 않는 프로토콜을 사용하고 있습니다. 오리지널 Clash 커널은 hysteria, tuic 같은 신규 프로토콜을 인식하지 못하므로 mihomo(Clash Meta) 커널을 사용하는 클라이언트로 교체해야 합니다. 클라이언트 비교 페이지에서 각 클라이언트의 커널 정보를 확인할 수 있습니다.

확인 순서: 오류에 줄 번호가 표시되면 해당 줄을 확인하고, 노드 순번이 표시되면 그 순번의 노드를 찾습니다. 구독 가져오기가 실패하면 구독 링크를 브라우저에 직접 붙여넣어 열어보세요—깨진 문자나 오류 페이지가 나오면 구독 자체의 문제이고, 정상적인 긴 텍스트가 나오면 클라이언트의 파싱 단계에 문제가 있는 것입니다.

3. 포트 점유: bind error

2026-06-19 21:06:15 ERROR start mixed(http+socks) proxy error: listen tcp 127.0.0.1:7890: bind: address already in use

의미: 커널이 사용하려는 7890 포트를 다른 프로세스가 이미 점유하고 있어 프록시 서비스가 시작되지 않습니다. Windows에서는 같은 오류가 "Only one usage of each socket address is normally permitted"로 표시됩니다. 확인 순서:

1. 가장 흔한 원인은 이전 Clash 인스턴스가 완전히 종료되지 않은 경우입니다. 작업 관리자를 열어 남아 있는 clash, mihomo, clash-verge 프로세스를 찾아 종료한 뒤 다시 실행하세요.
2. 포트가 관련 없는 다른 프로그램에 점유된 경우라면 클라이언트 설정에서 혼합 포트를 변경(예: 7890 → 7897)하고 저장한 뒤 커널을 재시작하세요.

원인: 대기 포트는 독점 자원이라 한 시점에 하나의 프로세스만 사용할 수 있습니다. 이런 오류의 해법은 항상 두 단계입니다—먼저 점유하고 있는 프로세스를 찾고, 그것을 종료할지 아니면 포트를 바꿀지 결정하는 것입니다.

4. DNS 해석 실패

2026-06-19 21:07:33 WARN [TCP] dial DIRECT 127.0.0.1:52410 --> api.example.com:443 error: dns resolve failed: couldn't find ip

의미: 커널이 대상 도메인의 IP를 해석하지 못해 연결이 주소 조회 단계에서 멈춥니다. 먼저 클라이언트의 DNS 설정이 잘못 바뀌지 않았는지 확인하고 기본값으로 되돌려 다시 시도해보세요. 그다음 시스템 자체가 정상적으로 도메인을 해석하는지도 확인합니다(프록시를 끈 상태에서 브라우저 접속이 되는지). fake-ip 모드를 사용할 때는 이런 오류가 상대적으로 적게 발생합니다. 자주 발생한다면 DNS 설정에 223.5.5.5, 119.29.29.29 같은 공용 DNS를 기본 리졸버로 추가해보세요.

5. TUN 모드 실행 실패

2026-06-19 21:08:20 ERROR start TUN listening error: create tun: permission denied

의미: TUN 모드는 가상 네트워크 어댑터를 생성해야 하며, 이 과정에는 관리자 권한이 필요합니다. Windows에서는 "관리자 권한으로 실행"으로 클라이언트를 실행하고, macOS와 Linux는 클라이언트 안내에 따라 권한을 승인하세요. 권한을 부여한 뒤에도 실패한다면 다른 VPN이나 가속기류 프로그램과 충돌하는지 확인하세요—두 개의 가상 네트워크 어댑터가 동시에 라우팅을 가로채면 서로 충돌합니다. 다른 하나를 먼저 종료한 뒤 다시 시도하세요. TUN 모드의 전체 설정 절차는 사용 가이드에 별도 항목으로 정리돼 있으며, 관련 용어는 용어 설명에서 확인할 수 있습니다.

4. 문제 해결의 표준 순서

앞의 내용을 하나의 절차로 정리하면, 어떤 이상 상황이든 다음 다섯 단계로 접근하세요:

1. 문제를 재현하면서 로그를 확인필터 레벨을 warning 이상으로 설정해 error 항목이 있는지 먼저 확인합니다.
2. 단계 구분하기시작 단계 오류(설정 파싱, 포트 점유, TUN 생성)는 클라이언트를 여는 순간 나타나고, 실행 단계 오류(시간 초과, DNS, 핸드셰이크 실패)는 웹페이지에 접속할 때 나타납니다.
3. 시작 단계는 텍스트 그대로 대응오류가 가리키는 줄을 그대로 확인하고, 짐작으로 판단하지 마세요.
4. 실행 단계는 노드와 로컬을 먼저 구분지연 시간 테스트로 노드 문제와 로컬 네트워크 문제를 구분하고, match ... using ...로 규칙 매칭이 예상과 맞는지 대조합니다—중국 본토 사이트가 노드로 전달되고 있다면 대부분 규칙이나 GeoIP 데이터의 문제이며 노드와는 무관합니다.
5. 정보가 부족하면 debug로 전환현재 레벨로는 원인이 보이지 않을 때 임시로 debug로 바꿔 문제를 재현한 뒤, 세부 정보를 확보하면 다시 info로 돌려놓습니다.

원인: 로그는 시간순으로 기록되지만 오류는 명확한 단계 속성을 가집니다. 먼저 단계를 특정하고 그다음 텍스트를 확인하는 방식이, 수천 줄의 로그에서 키워드를 뒤지는 것보다 훨씬 빠릅니다.

5. debug 레벨 사용법과 주의할 점

방법: 로그 페이지에서 레벨을 debug로 전환하거나, 설정 파일에 log-level: debug를 추가한 뒤 커널을 재시작하고, 문제를 처음부터 다시 재현해 조작 시작부터 오류가 나타나기까지의 구간을 캡처합니다. 주의할 점은 세 가지입니다:

• debug는 모든 연결의 매칭 세부 정보를 출력하며 매우 빠르게 스크롤됩니다. 장시간 켜두면 인터페이스가 느려지고 로그 파일이 커집니다.
• 로그에는 접속했던 도메인 정보가 포함되므로, 도움을 요청하기 위해 스크린샷을 커뮤니티나 채팅방에 올리기 전에 민감한 도메인을 가려두세요.
• 문제가 해결되면 다시 info로 돌려서, 평소에는 조용하고 문제가 생겼을 때만 기록을 남기는 상태로 유지하세요. 그래야 다음 문제 확인 시에도 로그를 읽기 편합니다.

여기까지가 로그 읽는 법의 전부입니다: 경로 세 가지, 로그 문장 패턴 한 가지, 자주 발생하는 오류 다섯 가지, 확인 절차 다섯 단계. 다음에 클라이언트가 계속 로딩만 하거나 웹페이지가 안 열릴 때, 바로 재설치하지 말고 먼저 로그를 열어 가장 최근의 error 줄부터 확인해보세요.