Clash 구독 오류·파싱 실패 원인과 해결 방법

먼저 구분하기: 다운로드 실패인가, 설정 파싱 실패인가

구독 업데이트가 실패했다고 해서 반드시 링크가 만료된 것은 아닙니다. 오류가 어느 단계에서 발생했는지 먼저 확인하세요. 앱이 응답을 받았는지, 응답이 Clash 설정 파일인지, 현재 코어가 설정의 필드를 지원하는지 순서대로 살펴보면 재설치보다 원인을 찾기 쉽습니다.

현재 정상 작동하는 설정은 그대로 보존하고 테스트용 설정을 새로 만드세요. 문제를 찾겠다고 모든 노드를 삭제하거나 DNS, TUN, 프록시 모드를 한꺼번에 바꾸지 마세요. 한 번에 한 항목만 조정하고 업데이트 시각과 오류 원문을 기록하세요.

표시된 메시지	우선 확인할 항목	다음 단계
401、403、404	인증, 링크 상태, 서버 제한	제공업체 계정 페이지에 로그인해 구독 주소를 다시 복사
timeout、no such host	네트워크 연결, 도메인 이름 확인	Wi-Fi와 모바일 데이터로 각각 확인
yaml、unmarshal、line	응답 내용과 YAML 구조	웹페이지가 반환되지 않았는지 확인한 뒤 오류가 난 줄을 살펴보기
unsupported、unknown proxy type	프로토콜 및 코어 호환성	노드 유형과 클라이언트 코어 확인
업데이트는 성공했지만 노드를 사용할 수 없음	노드, 프록시 그룹, 라우팅 규칙, DNS	연결 문제 확인으로 넘어가고 구독 주소만 점검하지 않기

첫 번째 원인: 링크 만료, 토큰 무효화 또는 복사 누락

채팅 기록을 이어 붙이지 말고 제공업체 계정 페이지에서 다시 복사하세요

구독 제공업체 계정 페이지를 열어 요금제 상태, 만료일, 남은 데이터 용량을 확인한 뒤 구독 메뉴를 찾으세요. 일부 서비스는 구독을 재설정하면 기존 주소를 즉시 무효화합니다. 계정에 로그인할 수 있어도 기존 토큰이 유효하다는 뜻은 아닙니다.

계정 페이지에서 Clash 또는 현재 mihomo 클라이언트에 맞는 구독 형식을 선택하고 복사 버튼으로 전체 주소를 복사하세요.
클라이언트의 설정 편집 화면을 열고 URL이 https://로 시작하는지, 끝에 불필요한 공백·줄바꿈·마침표가 붙지 않았는지 확인하세요.
원래 쿼리 매개변수는 그대로 유지하세요. 물음표 뒤의 내용을 삭제하거나 & 뒤의 매개변수를 임의로 잘라내지 마세요.
새 설정으로 저장한 뒤 직접 업데이트하세요. 상태가 실패에서 성공으로 바뀌는지, 업데이트 시각이 달라지는지 확인하세요.

복사한 주소에 문자 그대로 &가 들어 있다면 웹페이지에서 이스케이프된 소스 코드를 복사했을 수 있습니다. 매개변수를 하나씩 추측해 고치지 말고 제공업체의 복사 메뉴에서 다시 가져오세요. QR 코드로 가져온 경우에도 스캔 성공만으로 구독이 유효하다고 판단하지 말고 설정이 실제로 생성되었는지 확인하세요.

HTTP 상태 코드 확인 방법

401은 보통 인증 실패를 의미합니다. 403은 권한 제한이나 보안 시스템 차단일 수 있고, 404는 주소 변경, 경로 오류 또는 서버가 유효하지 않은 리소스를 숨긴 경우일 수 있습니다. 상태 코드만으로 요금제 만료를 단정할 수는 없습니다. 429가 표시되면 연속 새로고침을 멈추고 서버 안내에 따라 기다리세요. 5xx는 제공업체의 서비스 상태를 확인하는 편이 좋습니다.

두 번째 원인: Clash 설정 파일이 아닌 내용이 반환됨

구독 URL이 브라우저에서 열린다는 것은 요청에 응답이 왔다는 뜻일 뿐입니다. 로그인 페이지, 캡차 페이지, 오류 메시지 또는 다른 클라이언트용 노드 목록이 반환될 수 있습니다. 상태 코드가 200이어도 Clash에서 파싱할 수 있다는 의미는 아닙니다.

브라우저에서 실제 응답 내용 확인하기

사용 중인 기기에서 방금 복사한 구독 주소를 여세요. 공개 웹 프록시를 통해 대신 접속하지 마세요.
파일이 다운로드되면 로컬 텍스트 편집기로 열어 확인하세요. 텍스트가 바로 표시되면 첫 부분과 주요 필드를 살펴보세요.
로그인 창, 캡차, <html> 또는 <!DOCTYPE html>이 보인다면 설정 파일이 아니라 웹페이지를 받은 것입니다.
ss://, vmess:// 같은 링크가 여러 개 있거나 인코딩된 문자열이 통째로 나온다면 계정 페이지에서 Clash 형식을 선택하세요. 확장자만 .yaml로 바꾸지 마세요.

일반적인 전체 Clash 설정에는 proxies 또는 proxy-providers와 함께 proxy-groups, rules 등의 필드가 들어갑니다. 다만 proxies가 있는지만으로 유효성을 판단할 수는 없습니다. 원격 프록시 목록을 사용하는 설정은 노드가 파일에 직접 포함되지 않을 수 있습니다.

‘전체 설정 구독’과 ‘프록시 목록 파일’도 구분해야 합니다. 프록시 목록은 보통 proxies:로 시작하며 기본 설정의 proxy-providers에서 참조합니다. 일상적인 사용에 필요한 프록시 그룹과 규칙이 포함되어 있지 않을 수 있습니다. 가져오기 위치가 잘못되면 가져온 뒤 프록시 그룹이 없거나 예상과 다르게 작동할 수 있습니다.

세 번째 원인: 네트워크, DNS 또는 TLS가 업데이트 요청을 차단함

연결 시간 초과, 도메인 이름 확인 실패, 인증서 오류가 발생하면 먼저 요청 경로를 점검하고 YAML은 바로 수정하지 마세요. 이때는 설정 파일을 아직 받지 못했을 수 있으므로 라우팅 규칙을 바꿔도 현재 다운로드 문제는 해결되지 않는 경우가 많습니다.

두 네트워크에서 한 번에 한 조건씩 비교하기

오류 전문을 기록하고 URL은 그대로 둔 채 Wi-Fi에서 먼저 한 번 업데이트하세요.
모바일 데이터로 전환해 다시 업데이트하세요. 한 네트워크에서만 실패한다면 해당 네트워크의 DNS, 인증 포털 또는 접근 제한을 확인하세요.
사용 가능한 설정이 있다면 서비스를 중지했을 때와 실행했을 때의 업데이트 결과를 비교하세요. 클라이언트 버전에 따라 구독 요청이 프록시를 거치는지, 어떤 경로로 나가는지도 달라질 수 있습니다.
시스템의 ‘설정’ → ‘시스템’ → ‘날짜 및 시간’에서 자동 설정을 켜세요. 메뉴 이름은 휴대전화 제조업체에 따라 다를 수 있습니다. 시스템 날짜가 크게 틀리면 인증서 유효기간 확인에 문제가 생길 수 있습니다.

no such host는 도메인 이름 확인 문제, connection refused는 연결 거부, i/o timeout은 요청 시간 초과를 가리킵니다. x509 관련 메시지가 있다면 인증서와 시스템 시간을 확인하세요. 이런 정보가 막연한 ‘업데이트 실패’ 메시지보다 원인을 찾는 데 도움이 됩니다.

업데이트에 프록시가 필요한데 유일한 설정이 이미 작동하지 않는다면 ‘인터넷에 연결해야 업데이트할 수 있지만, 연결하려면 업데이트가 필요하다’는 악순환이 생길 수 있습니다. 신뢰할 수 있는 다른 네트워크에서 설정을 가져오거나 제공업체 안내에 따라 로컬 파일을 임시로 가져오세요. 인증서 오류를 우회하려고 검증을 계속 끄거나 HTTPS 주소를 임의로 HTTP로 바꾸지 마세요.

설정 다운로드는 성공했지만 로그에 proxy-provider 또는 rule-provider 가져오기 실패가 표시된다면 후속 리소스 요청에 문제가 있는 것입니다. 해당 리소스 유형과 도메인을 기록하고 각각 연결할 수 있는지 확인하세요. 기본 구독 업데이트에 성공해도 모든 원격 리소스가 업데이트된 것은 아닙니다.

네 번째 원인: YAML 문법 또는 코어 호환성 오류

줄 번호가 표시되면 해당 줄과 상위 단계의 들여쓰기부터 확인하세요

YAML은 공백으로 계층을 표현합니다. Tab, 전각 콜론, 따옴표 누락, 목록 들여쓰기 오류 때문에 파싱에 실패할 수 있습니다. 오류 줄은 파서가 문제를 발견한 위치일 뿐 실제 원인은 바로 앞 줄에 있을 수 있으므로 주변 내용도 함께 확인하세요.

같은 계층의 필드는 들여쓰기를 동일하게 유지하세요. 아래 예시는 모두 공백 두 칸을 사용하며 Tab은 섞지 않습니다.
필드를 구분할 때는 영문 콜론을 사용하고, YAML 문법에 맞게 콜론 뒤에 공백을 두세요.
노드 이름에 : 또는 # 같은 특수 조합이 있으면 문자열 전체를 따옴표로 감싸세요.
프록시 그룹에서 참조하는 노드 이름과 그룹 이름은 대소문자와 공백까지 정확히 일치해야 합니다.
같은 계층에 rules 등의 키를 중복 정의하지 마세요. 파서에 따라 중복 키 처리 방식이 다를 수 있습니다.

아래 예시는 목록과 문자열 작성 방법을 확인하기 위한 것으로, 그대로 구독을 대체할 수 있는 전체 프록시 설정이 아닙니다.

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - DIRECT

rules:
  - "DOMAIN-SUFFIX,example.com,DIRECT"
  - "MATCH,수동 선택"

로컬에서 편집한 뒤 오류가 발생하기 시작했다면 편집 전 사본으로 먼저 되돌리세요. 원격 구독 자체에 문제가 있다면 제공업체에 수정을 요청하는 것이 우선입니다. 로컬 캐시만 수정하면 다음 업데이트 때 변경 내용이 덮어써질 수 있습니다.

YAML 문법이 올바르더라도 현재 코어에서 지원되지 않을 수 있습니다

오리지널 Clash와 Clash Meta(현재 mihomo)는 지원하는 설정 기능이 완전히 같지 않습니다. 예를 들어 type: hysteria2 노드를 사용하려면 해당 프로토콜을 지원하는 코어가 필요합니다. 오래된 오리지널 Clash 코어는 파일이 YAML 형식이어도 이런 노드를 인식하지 못합니다.

클라이언트의 ‘정보’ 또는 코어 정보 화면에서 클라이언트 이름, 앱 버전, 코어 버전을 확인한 뒤 구독 제공업체가 안내한 요구 사항과 비교하세요. 앱 화면이 비슷해도 코어가 같다는 뜻은 아닙니다. 구독만 업데이트해도 오래된 코어에 새 프로토콜 지원이 추가되지는 않습니다. 클라이언트를 바꿔야 한다면 먼저 클라이언트 비교 가이드를 확인한 뒤 새 클라이언트에 맞는 형식을 선택하세요.

Android 클라이언트에서 전체 점검하기

클래식 Clash for Android 화면을 기준으로 설명하면 ‘구성’ → 오른쪽 위 ‘＋’ → ‘URL’로 이동해 이름과 구독 주소를 입력한 뒤 저장합니다. 기존 설정은 해당 항목의 메뉴에서 편집하거나 업데이트할 수 있습니다. 파생 버전에 따라 버튼 이름이 다를 수 있으니 실제 화면을 기준으로 확인하고, 노드 가져오기 메뉴를 전체 설정 가져오기 메뉴로 착각하지 마세요.

먼저 업데이트: 요청이 끝날 때까지 기다린 뒤 성공 시각이나 오류 전문을 기록하세요. 업데이트 버튼을 계속 눌러도 형식 오류는 해결되지 않으며 요청 제한에 걸릴 수 있습니다.
그다음 선택: 목록의 기존 설정이 아니라 방금 업데이트한 테스트 설정이 활성화되어 있는지 확인하세요.
그다음 시작: 홈으로 돌아가 서비스를 시작하세요. 처음 실행할 때 Android VPN 권한을 확인하고 설정을 불러오는 중 오류가 표시되는지 살펴보세요.
프록시 그룹 확인: 프록시 화면을 열어 그룹에 예상한 노드가 있는지 확인하고 노드 하나를 선택해 연결을 테스트하세요.
실제 접속 확인: 대상 웹페이지를 열어 보세요. 지연 시간 테스트에 성공해도 당시 테스트 대상에 연결되었다는 뜻일 뿐, 모든 웹사이트와 규칙이 정상이라는 의미는 아닙니다.

업데이트에 성공하고 서비스도 시작되지만 웹페이지가 열리지 않는다면 구독 파싱은 대체로 통과한 것입니다. 다음으로 프록시 모드, 노드 상태, DNS, 앱별 접근 제어를 확인하세요. 이때 TUN을 전환하거나 mixed-port를 바꾸는 것은 구독 문법을 고치는 데 필요한 단계가 아닙니다. 실제 연결 문제에 맞춰 각각 점검하세요.

해결되지 않으면 민감 정보를 가린 뒤 다음 내용을 전달하세요

제공업체나 클라이언트 유지관리자에게 문의할 때는 ‘구독이 안 돼요’라고만 하기보다 재현 조건을 구체적으로 적는 것이 좋습니다. 다음 다섯 가지를 정리해 보세요.

클라이언트 이름, 앱 버전, 코어 이름과 버전, Android 시스템 버전
실패한 시각, Wi-Fi 또는 모바일 데이터 사용 여부, 당시 서비스 실행 여부
오류 전문과 줄 번호. 로그의 토큰, 비밀번호, 개인 도메인은 필요에 따라 가리기
브라우저에서 설정 텍스트, 다운로드 파일, 로그인 페이지 또는 오류 페이지 중 무엇이 반환되었는지
같은 링크를 다른 네트워크에서 사용했을 때의 결과와 마지막으로 업데이트에 성공한 시각

‘링크 상태 → 응답 형식 → 네트워크 요청 → 문법 및 코어’ 순서로 확인하면 대개 문제 범위를 좁힐 수 있습니다. 정상 작동하는 사본을 보관하고 한 번에 한 항목만 변경한 뒤 오류 원문과 업데이트 결과로 검증하면 불필요한 재시도를 줄일 수 있습니다.