Clash 구독 만료 및 설정 파싱 실패: 주요 원인과 복구 방법

Clash에서 구독 업데이트에 실패하면 요청 시간 초과, 비정상 상태 코드, 빈 다운로드 내용, 설정 파싱 실패, 프록시 노드 수 0, 설정 전환 직후 원상 복귀와 같은 메시지가 흔히 표시됩니다. 모두 “구독을 사용할 수 없음”처럼 보이지만 실제로는 서로 다른 장애 단계에 해당합니다. 구독 업데이트는 최소한 주소 요청, 서버 응답, 콘텐츠 변환, YAML 파싱, 설정 저장, 코어 로드의 여섯 단계를 거칩니다. 업데이트 버튼을 계속 누르는 것만으로는 대개 같은 오류가 반복될 뿐입니다.

문제를 확인할 때는 먼저 어느 단계에서 실패했는지 파악한 뒤 주소를 변경할지, 구독을 다시 생성할지, 설정을 수정할지, 클라이언트 캐시를 정리할지 결정해야 합니다. 기존 설정을 저장하지 않은 상태에서 모든 데이터를 삭제하지 마세요. 구독 주소에는 접근 자격 증명이 포함될 수 있으므로 공개 로그, 스크린샷, 포럼 글에 그대로 복사해서도 안 됩니다.

먼저 구독 업데이트가 실패한 단계를 식별하세요

첫 단계는 YAML을 수정하는 것이 아니라 클라이언트 로그에서 최초 오류를 확인하는 것입니다. 이후 오류는 연쇄적으로 발생하는 경우가 많습니다. 예를 들어 다운로드 실패 뒤에 “설정 파일이 존재하지 않음”이 표시되거나, YAML 파싱 실패 뒤에 “코어 시작 실패”가 나타날 수 있습니다. 오류 발생 시각, 구독 이름, HTTP 상태, 오류 줄 번호, 현재 사용하는 코어 유형을 기록한 뒤 다음 특징에 따라 분류하세요.

REQUEST

요청 단계

시간 초과, 도메인 이름 확인 실패, 연결 거부, TLS 연결 실패 또는 비정상 HTTP 상태로 나타납니다. 이 단계에서는 설정 내용이 아직 파서에 전달되지 않았습니다.

CONTENT

응답 단계

요청은 성공했지만 로그인 페이지, 오류 안내, 빈 내용 또는 클라이언트와 호환되지 않는 구독 형식이 반환됩니다.

PARSER

파싱 단계

로그에 YAML 줄 번호, 필드 유형 오류, 중복 이름 또는 지원되지 않는 설정 항목이 표시된다면 파일은 다운로드되었지만 설정을 구성하지 못한 것입니다.

STORAGE

로드 단계

파일은 파싱되지만 클라이언트가 계속 이전 버전을 불러오거나 설정 디렉터리에 기록하지 못합니다. 이런 문제는 대개 캐시, 디렉터리 권한 또는 설정 인덱스와 관련이 있습니다.

이전 설정을 수동으로 선택했을 때 정상적으로 연결된다면 코어와 로컬 네트워크는 여전히 작동할 가능성이 높으며, 문제는 구독 요청이나 새 설정 내용에 집중되어 있을 수 있습니다. 모든 설정이 동시에 작동하지 않는다면 시스템 시간, 네트워크 경로, DNS, 시스템 프록시 루프백, 방화벽 상태도 확인해야 합니다. 그래야 환경 문제를 구독 만료로 잘못 판단하지 않을 수 있습니다.

구독 주소, 유효 기간, 요청 조건 확인

구독 주소는 일반 공개 웹페이지 링크가 아닌 경우가 많습니다. 주소의 경로와 쿼리 매개변수에는 사용자 식별, 요금제 상태, 접근 권한 정보가 포함될 수 있습니다. 서버에서 이전 자격 증명을 비활성화했거나, 사용자가 주소를 다시 생성했거나, 요금제가 만료되었거나, 구독 경로가 이전되면 이전 주소가 열리더라도 오류 안내만 반환할 수 있습니다.

주소가 잘리지 않았는지 확인

메신저, 이메일 또는 QR 코드에서 긴 링크를 복사할 때는 보이는 부분만 복사해 끝의 매개변수가 누락되는 경우가 흔합니다. 줄바꿈, 전각 기호, 앞뒤 공백이 섞일 수도 있습니다. 클라이언트의 구독 편집 화면에 전체 주소를 다시 붙여 넣고 프로토콜, 도메인, 경로, 쿼리 문자열이 끊김 없이 포함되어 있는지 확인하세요. 불필요해 보이는 매개변수도 직접 삭제하지 마세요. 서버 인증이나 클라이언트 유형 식별에 사용될 수 있습니다.

HTTP 상태 코드로 방향 판단

401 또는 403: 일반적으로 접근 자격 증명 만료, 권한 부족 또는 서버의 요청 거부를 의미합니다. 먼저 구독 서비스 관리 페이지에서 주소를 다시 발급받으세요.
404: 이전 경로가 이전되었거나, 주소 경로가 완전히 복사되지 않았거나, 서버에서 해당 리소스를 삭제했을 가능성이 있습니다.
429: 짧은 시간에 요청이 너무 많이 발생했다는 뜻입니다. 연속 새로 고침을 중지하고 제한이 해제된 뒤 다시 테스트하세요.
5xx: 서버 또는 상위 변환 서비스에 일시적인 문제가 있다는 의미입니다. 로컬 설정을 삭제해도 보통 해결되지 않으므로 기존 설정을 보존하고 잠시 후 다시 시도하세요.
301 또는 302: 리디렉션 자체가 반드시 오류인 것은 아닙니다. 다만 로그인 페이지, 공지 페이지 또는 다른 프로토콜 주소로 이동하면 클라이언트가 최종 구독 내용을 가져오지 못할 수 있습니다.

브라우저에서 주소가 열린다고 해서 클라이언트에서도 반드시 업데이트되는 것은 아닙니다. 브라우저는 로그인 상태를 저장하거나 리디렉션을 자동으로 처리하고 서버가 생성한 안내 페이지를 표시할 수 있지만, Clash 클라이언트는 보통 네트워크 요청을 보내 응답 본문을 읽기만 합니다. 반대로 브라우저에 읽기 어려운 인코딩 텍스트가 표시된다고 해서 내용이 손상된 것도 아닙니다. 일부 구독은 원래 Base64로 인코딩된 노드 링크 모음입니다.

시스템 시간과 네트워크 경로 확인

기기의 날짜, 시간 또는 시간대가 크게 어긋나면 HTTPS 인증서 검증이 실패할 수 있습니다. 먼저 시스템 자동 시간 동기화를 활성화한 뒤 구독을 다시 요청하세요. 현재 네트워크에서 구독 도메인을 차단했다면 신뢰할 수 있는 다른 네트워크로 잠시 전환해 한 번 업데이트해 보세요. 시스템 프록시를 사용해 구독을 업데이트할 때는 클라이언트가 루프백을 형성하지 않는지도 확인해야 합니다. 클라이언트가 구독을 요청한 트래픽이 아직 시작되지 않았거나 이미 중단된 로컬 프록시 포트로 다시 전달되면 연결 거부나 시간 초과로 나타날 수 있습니다.

요청은 성공했지만 내용이 비정상일 때 확인하는 방법

HTTP 200은 서버가 내용을 반환했다는 뜻일 뿐, 그 내용이 유효한 설정이라는 의미는 아닙니다. 많은 파싱 실패는 서버가 반환한 HTML 페이지, JSON 오류 객체, 빈 응답 또는 잘못된 구독 형식에서 발생합니다. 이때 로그에는 “proxies 필드를 찾을 수 없음”, “매핑을 파싱할 수 없음”, “잘못된 문자” 또는 첫 줄 부근의 문법 오류가 표시될 수 있습니다.

일반적인 구독 콘텐츠 구분

Clash 설정은 일반적으로 YAML을 사용하며, 자주 쓰이는 최상위 필드에는 proxies, proxy-groups, rules, proxy-providers, rule-providers가 있습니다. mihomo는 일부 필드를 호환하고 확장하지만, 실제로 사용할 수 있는 항목은 코어 버전에 따라 달라집니다. 여러 프로토콜 링크로 구성된 일반 구독 텍스트는 Base64로 인코딩되기도 합니다. 이런 콘텐츠는 클라이언트나 구독 변환 서비스에서 먼저 Clash 설정으로 변환해야 하며, 완전한 YAML이라고 가정해 바로 사용할 수 없습니다.

응답 본문이 HTML 문서 표기로 시작하거나 로그인 안내, 요금제 만료 안내, 인증 코드 페이지처럼 보인다면 문제는 서버 응답에 있습니다. 이때 로컬 YAML을 계속 수정해서는 안 됩니다. JSON이 반환되었다면 먼저 오류 코드와 설명이 포함되어 있는지 확인하세요. 응답이 몇 글자뿐이거나 완전히 비어 있다면 구독 주소를 다시 발급받고 서비스 상태를 확인해야 합니다.

클라이언트와 코어의 호환성 확인

같은 설정이라도 클라이언트에 따라 결과가 다를 수 있습니다. 기존 Clash 코어, Clash Meta(현재는 보통 mihomo라는 이름으로 유지 관리됨), 여러 버전의 그래픽 클라이언트는 프로토콜, DNS 필드, 규칙 집합 동작, 설정 확장 기능을 모두 동일하게 지원하지 않습니다. 서버가 최신 mihomo에서만 지원되는 필드를 생성하는데 클라이언트가 이전 코어를 사용하면 알 수 없는 필드, 지원되지 않는 프록시 유형, 시작 검사 실패가 발생할 수 있습니다.

먼저 클라이언트의 정보 페이지에서 그래픽 인터페이스 버전과 실제 코어 버전을 확인한 뒤 구독 제공자가 요구하는 형식을 확인하세요. 클라이언트에서 코어를 전환할 수 있다면 기존 설정을 저장한 후 해당 문서에 따라 전환해야 합니다. 대상 필드를 지원하지 않는 경우 알 수 없는 필드를 임의로 삭제하지 말고 호환되는 구독 형식을 선택하세요. 일부 필드는 서로 의존하므로 한 항목을 삭제하면 정책 그룹이나 규칙 참조가 작동하지 않을 수 있습니다.

YAML 설정 파싱 실패 위치 찾기

YAML은 들여쓰기와 데이터 유형에 민감합니다. 로그에 줄 번호가 표시되면 해당 줄뿐 아니라 앞선 몇 줄도 함께 확인하세요. 실제 오류가 이전 구간의 따옴표 누락, 들여쓰기 단계 중단, 목록 기호 위치 오류일 수 있습니다. 설정을 편집하기 전에 원본 파일을 복사하고, 일반 텍스트 편집기를 사용하며, UTF-8 인코딩을 유지하세요.

들여쓰기, 탭, 콜론 확인

계층 들여쓰기에는 공백을 사용하고 탭을 섞지 마세요. 같은 수준의 목록 항목은 동일한 들여쓰기를 유지해야 합니다. 노드 이름, 정책 그룹 이름 또는 문자열 값에 특수 문자가 포함되면 따옴표로 감쌀 수 있습니다. 특히 값에 공백 뒤의 콜론, 해시 기호 또는 YAML이 해석할 수 있는 다른 기호가 포함될 때 유용합니다.

proxies:
  - name: "Tokyo: Primary"
    type: socks5
    server: 192.0.2.10
    port: 1080

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "Tokyo: Primary"
      - DIRECT

rules:
  - MATCH,PROXY

위 예시는 구조를 보여주기 위한 것입니다. proxies, proxy-groups, rules는 최상위에 위치하고, 각 목록 항목은 하이픈으로 시작합니다. 정책 그룹이 참조하는 노드 이름은 노드 정의와 완전히 일치해야 합니다. 실제 프록시 프로토콜에는 인증, 전송, 암호화 관련 매개변수도 필요하므로 예시 필드만 복사해 사용 가능한 노드로 만들 수는 없습니다.

필드 유형 확인

포트는 일반적으로 숫자여야 하고, 불리언 값은 코어가 인식할 수 있는 불리언 유형으로 작성해야 하며, 목록 필드는 일반 문자열로 작성할 수 없습니다. 흔한 오류로는 proxies를 한 줄짜리 텍스트로 작성하거나, 규칙 목록을 객체로 작성하거나, 숫자 위치에 단위를 넣거나, 따옴표가 없어 숫자나 특수 값이 잘못 해석되는 경우가 있습니다. 파서가 “expected sequence”라고 알리면 보통 목록이 필요하다는 뜻이고, “expected mapping”이라고 알리면 해당 위치가 키-값 구조여야 한다는 뜻입니다.

이름 참조와 대체 규칙 확인

설정은 이름으로 노드, 정책 그룹, 규칙을 연결합니다. 정책 그룹이 삭제되거나 이름이 바뀐 노드를 참조하거나, 규칙이 존재하지 않는 정책 그룹을 참조하면 검사 실패나 비정상 동작이 발생할 수 있습니다. 이름 비교는 일반적으로 대소문자, 공백, 기호를 포함해 텍스트가 완전히 일치해야 합니다. 규칙은 구체적인 매칭부터 대체 규칙 순서로 배치해야 하며, MATCH는 일반적으로 규칙 목록의 마지막에 둡니다. 대체 규칙이 너무 앞에 있으면 뒤의 규칙이 매칭되지 않습니다.

부분 구독을 전체 설정으로 착각하지 않기

proxy-providers가 반환하는 내용은 프록시 모음일 뿐이며, 주 설정의 provider 항목이 이를 불러오는 구조일 수 있습니다. 이 내용에는 포트, DNS, 정책 그룹, 전체 규칙이 포함되지 않을 수 있으므로 항상 독립적인 주 설정으로 가져올 수 있는 것은 아닙니다. 원격 규칙 집합도 도메인, IP 또는 규칙 동작 데이터만 제공할 뿐 실행 가능한 Clash 설정이 아닙니다. 복사한 주소가 주 구독 진입점인지, 특정 provider 또는 규칙 집합 주소인지 확인하세요.

클라이언트 캐시, 이전 설정, 기록 실패 처리

구독 응답이 정상이고 설정도 독립 검사에 통과했는데 클라이언트에 이전 노드가 계속 표시된다면 캐시와 저장 단계로 범위를 좁혀야 합니다. 그래픽 클라이언트는 보통 구독 인덱스, 다운로드한 설정 사본, 현재 활성 설정, 코어 실행 파일을 별도로 관리합니다. 화면에 표시되는 구독 이름과 디스크의 파일 이름이 다를 수도 있습니다.

자동 업데이트 중지: 진단 중 파일이 계속 덮어써지지 않도록 고빈도 예약 새로 고침을 잠시 끄세요.
현재 설정 내보내기: 사용 가능한 노드, 정책 그룹 선택, 로컬 오버라이드 내용을 저장하고 현재 설정 이름을 기록하세요.
새 구독 항목 만들기: 기존 항목을 바로 덮어쓰지 말고 새로 발급받은 주소로 새 항목을 만든 뒤 업데이트를 실행하세요.
업데이트 시간 확인: 클라이언트에 표시된 업데이트 시각, 노드 수, 로그 시간이 이번 작업과 일치하는지 확인하세요.
설정 검사 실행: 전환하기 전에 클라이언트가 제공하는 검사 기능을 사용해 새 설정을 현재 코어가 불러올 수 있는지 확인하세요.
전환 후 코어 재시작: 먼저 시스템 전체를 재부팅할 필요 없이 프록시 코어 또는 클라이언트만 재시작하세요. 새 설정이 실제 활성 설정이 되었는지 확인합니다.
안정성 확인 후 이전 항목 삭제: 규칙, DNS, 프록시 연결 검증이 모두 끝날 때까지 되돌릴 버전을 보관하세요.

업데이트 후 파일 시간이 바뀌지 않았다면 설정 디렉터리에 쓰기 권한이 있는지, 디스크 공간이 충분한지, 보안 프로그램이 클라이언트의 파일 기록을 차단하고 있지 않은지 확인하세요. 클라이언트를 시스템 보호 디렉터리에 설치하면 일반 권한으로 인접한 설정 파일을 업데이트하지 못할 수 있습니다. 정상적인 클라이언트는 보통 사용자 데이터를 사용자 설정 디렉터리에 저장하므로 실제 경로는 클라이언트 로그에서 확인해야 합니다.

백업 없이 사용자 데이터 디렉터리 전체를 바로 삭제하는 것은 권장하지 않습니다. 이 디렉터리에는 구독 주소, 오버라이드 규칙, 정책 그룹 선택, DNS 설정, 인터페이스 환경 설정이 함께 들어 있을 수 있습니다. 먼저 설정을 내보낸 다음 클라이언트 문서에 따라 특정 구독 캐시나 인덱스만 찾는 방법이 안전합니다. 클라이언트에 “설정 초기화” 기능이 있더라도 영향 범위를 이해한 뒤 사용하세요.

구독은 가져왔지만 노드 또는 규칙 집합이 비어 있음

가져오기에 성공했다고 해서 모든 원격 리소스가 로드된 것은 아닙니다. 주 설정은 계속 proxy-providers와 rule-providers를 참조할 수 있으며, 코어가 시작된 뒤 각 리소스를 별도로 요청합니다. 주 구독은 정상적으로 반환되더라도 provider 주소가 만료되면 화면에 정책 그룹이 비어 있거나, 규칙 집합 다운로드 실패 또는 일부 노드 누락이 나타날 수 있습니다.

프록시 모음 업데이트 확인

로그에서 provider 이름, 요청 주소 상태, 업데이트 시각을 확인하세요. 정책 그룹이 use로 provider를 참조한다면 provider 이름은 정의와 일치해야 합니다. 원격 콘텐츠는 코어가 요구하는 provider 형식이어야 합니다. 일반 웹페이지, 완전한 주 설정, 호환되지 않는 노드 목록은 모두 로드에 실패할 수 있습니다. 정책 그룹이 정적 proxies와 provider를 함께 사용하면 정적 항목이 계속 표시되어 원격 모음의 실패가 가려질 수 있습니다.

원격 규칙 집합 확인

규칙 집합의 behavior, 콘텐츠 형식, 규칙 유형은 서로 일치해야 합니다. 예를 들어 domain, ipcidr, classical 동작은 서로 다른 데이터 구조에 대응합니다. 주 설정이 참조하는 규칙 집합 이름, 규칙의 정책 이름, 원격 파일 형식 중 하나라도 일치하지 않으면 규칙 집합을 사용할 수 없게 됩니다. 업데이트 후 로그에 규칙 수가 표시되는지 확인하고, 최종적으로 MATCH와 같은 대체 동작이 존재하는지도 확인하세요.

직접 연결과 프록시 다운로드 경로 고려

원격 리소스는 직접 연결로 가져오도록 설정할 수도 있고 현재 프록시를 통해 다운로드할 수도 있습니다. provider가 프록시를 통해서만 접근 가능한데 코어가 provider를 로드하기 전에 사용할 노드가 없다면 시작 의존성이 발생할 수 있습니다. 반대로 서버가 특정 네트워크에서의 직접 연결만 허용한다면 프록시를 강제로 사용한 요청도 실패합니다. 클라이언트와 코어가 지원하는 설정 방식에 따라 다운로드 경로를 명확히 정하고, 최소 하나의 실행 가능한 시작 방식을 남겨 두세요.

복구 후 검증 목록

구독 업데이트 버튼에 성공이 표시된 뒤에도 설정이 실제로 적용되어 실행 중인지 확인해야 합니다. 노드 목록만 확인해서는 충분하지 않습니다. DNS, 규칙, 시스템 프록시가 여전히 이전 상태를 사용할 수 있기 때문입니다. 다음 테스트를 정해진 순서로 진행하는 것이 좋습니다.

구독 업데이트 시각, 설정 파일 수정 시각, 로그 시각이 일치하는지 확인하세요.
노드 수가 예상과 일치하고 정책 그룹에 대규모 빈 참조가 없는지 확인하세요.
노드 하나에서 지연 시간 테스트를 실행하세요. 지연 시간 결과는 테스트 주소에 도달할 수 있다는 뜻일 뿐 모든 웹사이트에 접속할 수 있다는 의미는 아닙니다.
현재 프록시 모드를 확인하고 규칙 모드, 전역 모드, 직접 연결 모드가 테스트 목적에 맞는지 확인하세요.
연결 로그를 열어 대상 요청이 예상한 규칙과 정책 그룹에 매칭되었는지 확인하세요.
DNS 로그를 확인해 도메인 확인 실패, 잘못된 매핑, 시스템 DNS 우회가 없는지 점검하세요.
시스템 프록시를 활성화했다면 로컬 수신 포트와 시스템 설정이 일치하는지 확인하세요. TUN을 사용한다면 서비스, 권한, 라우팅이 구성되었는지도 확인해야 합니다.
클라이언트를 한 번 재시작해 구독 인덱스와 활성 설정이 현재 세션에서만 적용된 것이 아니라 영구 저장되는지 확인하세요.

TUN 모드는 더 넓은 범위의 시스템 트래픽을 처리하지만 유효하지 않은 구독이나 잘못된 YAML을 고쳐 주지는 않습니다. 설정 검사를 통과하지 못한 상태에서 TUN 활성화를 복구 수단으로 사용해서는 안 됩니다. 반대로 설정은 정상인데 일부 앱만 프록시를 사용하지 않는다면 TUN 권한, 시스템 라우팅, 제외 항목, 앱 자체의 프록시 설정을 확인하는 편이 효과적입니다.

증상에 따른 복구 작업 선택

증상	우선 확인할 항목	복구 작업
401, 403 또는 요금제 안내	구독 자격 증명과 서비스 상태	서버에서 주소를 다시 발급받아 이전 구독 항목을 교체
요청 시간 초과 또는 도메인 확인 실패	로컬 네트워크, DNS, 시스템 시간, 프록시 루프백	시간 동기화, 네트워크 전환, 업데이트 트래픽 경로 확인
HTTP 200이지만 첫 줄 파싱 실패	응답이 HTML, JSON 또는 빈 내용인지 확인	서버 진입점을 수정하거나 올바른 구독 형식 선택
로그에 YAML 줄 번호가 표시됨	이전 줄의 들여쓰기, 따옴표, 목록, 필드 유형	백업 후 항목별로 수정하고 설정 검사를 반복
가져오기에 성공했지만 노드가 0개	provider 주소, 형식, 정책 그룹 참조	provider를 별도로 업데이트하고 이름과 콘텐츠 유형 확인
업데이트 후에도 이전 노드가 표시됨	활성 설정, 캐시 인덱스, 디렉터리 권한	새 구독 항목을 만들고 기록 시각을 확인한 뒤 코어 재시작

전체 복구 순서는 다음과 같이 요약할 수 있습니다. 먼저 최초 오류를 읽고 요청 상태를 확인합니다. 요청이 성공하면 응답 내용을 식별하고, 내용이 올바르면 YAML과 코어 호환성을 점검합니다. 설정 검사를 통과한 뒤 캐시와 기록 문제를 처리하고, 마지막으로 provider, 규칙, DNS, 시스템 프록시 또는 TUN을 검증합니다. 단계별로 처리하면 유효한 설정을 보존할 수 있고, 구독 서비스에 문제가 있을 때 로컬에서 사용할 수 있는 이전 버전을 잘못 삭제하는 일도 피할 수 있습니다.