Clash 구독 링크 만료 또는 설정 파싱 실패: 원인 진단과 자가 점검

FAILURE LAYERS

다운로드 실패, 변환 실패, 설정 로드 실패를 먼저 구분하기

“구독 실패”는 하나의 문제를 뜻하지 않습니다. 클라이언트가 구독 주소에서 설정을 가져와 적용하려면 네트워크 요청, 서버 응답, 콘텐츠 인식, YAML 파싱, 필드 검증, 코어 로드 등 여러 단계를 거칩니다. 단계마다 표시되는 메시지는 비슷할 수 있지만 해결 방법은 완전히 다릅니다. 업데이트를 반복해서 누르는 것만으로는 대개 같은 오류가 반복될 뿐입니다.

첫 번째는 다운로드 실패입니다. 클라이언트가 유효한 응답을 받지 못한 상태로, 요청 시간 초과, 연결 재설정, 도메인 이름 확인 실패, HTTP 401, 403, 404, 429 또는 5xx 등이 대표적입니다. 아직 YAML 파싱 단계에 도달하지 않았으므로 로컬 설정의 들여쓰기를 수정해도 해결되지 않습니다.

두 번째는 예상과 다른 응답 콘텐츠입니다. 요청 자체는 성공했지만 본문이 로그인 페이지, 접근 확인 페이지, 요금제 만료 안내, JSON 오류 객체 또는 노드 URI만 담은 텍스트일 수 있습니다. 브라우저에서 주소가 열린다는 것은 브라우저가 응답을 받았다는 뜻일 뿐, 해당 응답이 현재 클라이언트에서 로드할 수 있는 Clash 설정이라는 의미는 아닙니다.

세 번째는 구문 또는 필드 파싱 실패입니다. 서버가 YAML을 반환했지만 들여쓰기, 콜론, 따옴표, 목록 계층 또는 문자 인코딩에 문제가 있을 수 있습니다. 현재 코어가 인식하지 못하는 필드를 사용한 경우도 있습니다. 이때 로그에는 대개 YAML, unmarshal, decode, field, proxy 또는 rule 같은 키워드가 나타납니다.

네 번째는 로드 후 사용 불가입니다. 구독이 설정 목록에 들어가 노드 이름도 보이지만 설정을 활성화할 때 실패하거나, 활성화 후 연결되지 않는 경우입니다. 이는 누락된 프록시 그룹, 잘못된 규칙 참조, 불완전한 프록시 프로토콜 매개변수, DNS 설정 충돌 또는 코어 버전 차이와 관련된 경우가 많습니다. 계속해서 “링크가 열리지 않는다”는 방향으로 접근해서는 안 됩니다.

URL STATUS

구독 링크 상태와 요청 조건 확인하기

구독 주소에는 계정이나 인증 범위를 식별하는 쿼리 매개변수가 포함되는 경우가 많습니다. 복사할 때 물음표 뒤의 매개변수를 빠뜨리거나, 연결 문자열을 잘라내거나, 줄바꿈이 섞이면 서버가 잘못된 결과를 반환할 수 있습니다. 점검할 때는 서비스 제공업체의 구독 관리 페이지에서 완전한 주소를 다시 복사하세요. 직접 조합하거나 채팅 기록에서 일부만 선택해 계속 사용하지 않는 것이 좋습니다.

주소가 잘리거나 이스케이프되지 않았는지 확인하기

주소가 http:// 또는 https://로 시작하는지, 도메인과 경로가 완전한지 확인하세요.
쿼리 매개변수가 그대로 남아 있는지 확인하세요. 특히 물음표, 등호, 연결 기호와 매개변수 값의 마지막 문자를 살펴보세요.
QR 코드 인식이나 기기 간 복사 후에는 주소 중간에 공백, 한국어 문장 부호 또는 줄바꿈이 삽입되지 않았는지 확인하세요.
주소를 YAML 문자열에 넣는 경우 특수 문자가 포함되어 있다면 따옴표로 감싸 주석이나 구문 기호로 잘못 인식되지 않게 하세요.

HTTP 상태 코드로 점검 방향 정하기

401 / 403: 인증 매개변수가 만료되었거나 요청 조건을 충족하지 못했거나 서버가 접근을 거부한 경우입니다. 구독 주소를 새로 발급받고 계정 상태와 서버 측 제한을 확인하세요.
404 / 410: 경로가 존재하지 않거나 리소스가 이미 폐기된 경우입니다. 서버에서 기존 주소를 변경했을 수 있으므로 로컬 캐시를 계속 새로 고쳐도 복구되지 않습니다.
429: 짧은 시간에 업데이트를 너무 많이 시도한 경우입니다. 연속 새로 고침을 멈추고 제한 시간이 끝난 뒤 한 번 테스트하세요.
5xx: 서버가 일시적으로 요청을 처리하지 못하는 상태입니다. 오류 발생 시간과 상태 코드를 기록한 뒤 잠시 후 다시 시도하거나 구독 제공업체에 문의하세요.

시간 초과나 도메인 이름 확인 실패라면 현재 기본 네트워크도 점검해야 합니다. 테스트할 때는 시스템 프록시와 TUN을 잠시 끄고 구독 도메인에 접속해 보세요. 구독 업데이트가 아직 시작되지 않은 프록시에 잘못 의존하고 있는지 확인할 수 있습니다. 일부 클라이언트는 설정 업데이트에 DIRECT 또는 프록시 정책을 지정할 수 있습니다. 현재 네트워크에서 구독 도메인에 직접 연결할 수 없다면 업데이트 트래픽의 경로를 명확히 지정해야 합니다. “설정을 로드해야 구독에 접근할 수 있지만, 구독에 접근해야 설정을 로드할 수 있는” 순환을 피하기 위해서입니다.

RESPONSE BODY

응답 본문이 실제 Clash 설정인지 확인하기

HTTP 200은 서버가 요청을 처리했다는 뜻일 뿐 본문 형식이 올바르다는 의미는 아닙니다. 가장 흔한 사례는 구독 주소가 로그인 페이지나 접근 확인 페이지로 이동해 클라이언트가 HTML을 받은 경우입니다. 그러면 파서는 첫 줄의 <!doctype html>, <html> 또는 다른 태그 부근에서 오류를 낼 수 있습니다.

완전한 Clash 설정은 일반적으로 YAML 텍스트이며, 흔히 사용하는 최상위 필드로 proxies, proxy-groups, rules, dns, proxy-providers, rule-providers 등이 있습니다. 필드 조합은 설정 용도에 따라 달라지므로 모든 파일에 모든 필드가 있어야 하는 것은 아닙니다. 다만 본문이 웹페이지, 오류 안내 또는 계정 정보 페이지여서는 안 됩니다.

proxies:
  - name: "Example Node"
    type: ss
    server: example.invalid
    port: 443
    cipher: aes-128-gcm
    password: "example-password"

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "Example Node"
      - DIRECT

rules:
  - MATCH,노드 선택

또 다른 흔한 응답은 Base64로 인코딩된 노드 URI 모음입니다. 디코딩하면 ss://, trojan://, vmess:// 등의 항목으로 구성될 수 있습니다. 이런 콘텐츠는 완전한 Clash YAML이 아닙니다. 일부 그래픽 클라이언트는 가져올 때 변환 과정을 호출하지만, 다른 클라이언트는 완전한 설정만 허용합니다. 따라서 같은 링크라도 소프트웨어에 따라 결과가 달라질 수 있습니다. 서버의 구독 페이지에서 Clash, Mihomo 또는 호환 형식으로 명확히 표시된 출력을 선택하고, 임의의 범용 구독을 YAML 파일로 직접 로드하지 마세요.

리디렉션도 확인해야 합니다. 구독 주소가 먼저 301 또는 302를 반환한 뒤 실제 다운로드 주소로 이동할 수 있습니다. 클라이언트가 도메인 간 리디렉션을 차단하거나, 대상 도메인의 인증서에 문제가 있거나, 이동 후 인증 매개변수가 사라지면 브라우저와 클라이언트의 결과가 달라질 수 있습니다. 로그에 redirect, certificate, TLS 또는 hostname이 함께 나타난다면 프록시 노드 필드를 수정하기보다 리디렉션 대상과 시스템 시간을 먼저 확인하세요.

응답 문자 인코딩은 일반적으로 UTF-8이어야 합니다. 파일 시작 부분에 비정상적인 보이지 않는 문자가 있거나 본문을 다른 인코딩으로 잘못 읽으면 첫 줄의 필드를 인식하지 못할 수 있습니다. 신뢰할 수 있는 로컬 텍스트 편집기로 인코딩을 확인하고 UTF-8로 다시 저장한 뒤 로컬 설정으로 테스트해 보세요. 로컬 파일은 로드되지만 원격 구독은 로드되지 않는다면 문제는 대개 서버 응답 헤더, 본문 인코딩 또는 다운로드 경로에 있습니다.

YAML PARSING

YAML 들여쓰기, 따옴표, 목록 구조를 차례로 확인하기

YAML은 들여쓰기로 계층을 표현하므로 공백 수와 필드 위치가 데이터 구조를 직접 바꿉니다. Clash 설정은 보통 한 단계에 공백 두 칸을 사용합니다. YAML 규격상 일관된 다른 공백 폭도 허용되지만, 실제 점검에서는 두 칸으로 통일하는 편이 읽기 쉽고 조각을 복사할 때 계층 오류도 줄일 수 있습니다. 들여쓰기에는 탭을 사용하지 마세요.

가장 흔한 구문 오류

목록 기호의 계층 오류: - name은 해당 목록 필드 아래에 있어야 합니다. proxies:와 같은 열에 놓으면 파서는 이를 새로운 최상위 구조로 인식해 오류를 냅니다.
콜론 뒤 공백 누락: 필드는 보통 port: 443처럼 작성하며 port:443로 쓰지 않습니다. 후자는 일반 문자열로 인식될 수 있습니다.
특수 문자가 포함된 이름에 따옴표 누락: 노드 이름이나 프록시 그룹 이름에 콜론, 샵, 대괄호, 중괄호 또는 앞쪽 별표가 포함되어 있다면 큰따옴표로 감싸는 것이 좋습니다.
주석으로 인한 값 잘림: 따옴표로 감싸지 않은 샵은 주석의 시작으로 인식됩니다. 비밀번호나 이름에 샵이 포함되어 있으면 그 뒤의 내용이 무시될 수 있습니다.
중복 키 또는 잘못된 형식: 같은 계층에 rules를 중복 선언하거나 목록이어야 하는 필드를 단일 문자열로 작성하면 파싱 또는 필드 검증 단계에서 실패할 수 있습니다.

다음 조각은 proxies 안의 항목에 들여쓰기 한 단계가 빠져 있고, 프록시 그룹이 참조하는 이름도 실제 노드 이름과 일치하지 않습니다:

proxies:
- name: "홍콩 노드"
  type: ss

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "홍콩 노드 01"

들여쓰기를 바로잡는 것은 첫 단계일 뿐입니다. 프록시 그룹의 노드 이름, 규칙의 정책 이름, provider 참조 이름은 정의된 위치와 공백, 대소문자, 전각 문자를 포함해 한 글자까지 일치해야 합니다. YAML 파싱에 성공했다고 해서 이러한 참조가 유효한 것은 아닙니다. 참조 오류는 대개 코어가 설정을 로드할 때 나타납니다.

로그에 행 번호와 열 번호가 표시된다면 먼저 오류가 난 줄을 확인한 뒤, 위쪽으로 올라가 가장 가까운 상위 필드를 점검하세요. 파서가 가리키는 위치는 때때로 “더 이상 파싱할 수 없는” 지점일 뿐이며, 실제 오류는 앞 줄에 있을 수 있습니다. 예를 들어 따옴표가 닫히지 않았거나 배열 괄호가 빠졌거나, 이전 계층의 들여쓰기가 너무 일찍 끝난 경우입니다. 오류가 난 줄만 삭제하면 구문은 맞지만 기능이 손상된 파일이 될 수 있으므로 주의하세요.

CORE COMPATIBILITY

Clash와 Mihomo의 필드 호환성 확인하기

설정 구문이 올바른데도 코어의 기능 차이로 로드에 실패할 수 있습니다. 기존 Clash, Clash Meta의 후속 구현인 Mihomo, 그리고 그래픽 클라이언트마다 내장된 코어 버전은 동일한 프로토콜 매개변수와 확장 필드를 모두 지원한다고 보장할 수 없습니다. 구독 제공업체가 최신 Mihomo 형식으로 설정을 생성했는데 클라이언트가 오래된 코어를 사용한다면 알 수 없는 필드, 지원되지 않는 프록시 유형 또는 역직렬화할 수 없는 매개변수 오류가 발생할 수 있습니다.

점검할 때는 먼저 클라이언트의 “정보”, “코어” 메뉴 또는 로그 시작 부분에서 실제 실행 중인 코어 이름과 버전을 확인하세요. 그래픽 클라이언트 이름만으로 판단해서는 안 됩니다. 일부 클라이언트는 코어를 전환할 수 있지만 설정 업데이트 후에도 이전 코어가 계속 실행될 수 있습니다. 클라이언트 본체는 업데이트되었어도 코어 파일은 함께 업데이트되지 않는 경우가 있습니다.

버전 차이가 자주 발생하는 영역

프록시 프로토콜 필드: 새로운 프로토콜 유형, 전송 계층 매개변수, 지문 매개변수, UDP 관련 옵션은 최신 Mihomo 버전이 필요할 수 있습니다.
TUN 설정: 버전에 따라 네트워크 스택, 자동 라우팅, 인터페이스 탐색, DNS 하이재킹 필드의 값 요구 사항이 다를 수 있습니다. 필드가 존재한다고 해서 현재 플랫폼에 해당 권한이 있다는 뜻은 아닙니다.
DNS 강화 모드: fake-ip, redir-host, nameserver policy 및 fallback 관련 구조는 계층과 형식이 올바르게 유지되어야 합니다. 오래된 설정 예제가 현재 코어에 그대로 적용되지 않을 수 있습니다.
규칙 집합과 provider: rule-providers, proxy-providers의 원격 주소, 업데이트 간격, 파일 경로, behavior는 코어가 지원하는 형식에 맞아야 합니다.
스니핑과 지리 데이터: sniffer, GEOSITE, GEOIP 및 geodata 관련 동작은 코어 구현과 데이터 파일 상태에 따라 달라질 수 있습니다.

로그에 field not found, unsupported proxy type, invalid value 또는 유사한 메시지가 나타나면 해당 필드를 중심으로 현재 코어 문서를 확인하세요. 알 수 없는 필드를 임시로 삭제하면 원인을 확인하는 데 도움이 될 수 있지만, 기능에 미치는 영향을 모른 채 계속 사용하는 것은 좋지 않습니다. 예를 들어 TUN의 라우팅 필드를 삭제하면 설정은 로드되더라도 시스템 트래픽이 코어로 들어가지 않을 수 있습니다. DNS 부분을 삭제하면 도메인 확인 경로도 바뀔 수 있습니다.

구독 서비스가 Clash와 Mihomo 형식을 모두 제공한다면 Mihomo 코어를 사용하는 클라이언트는 일반적으로 Mihomo용으로 명확히 표시된 설정을 선택해야 합니다. 반대로 구버전 Clash 코어는 인식할 수 있는 기본 필드를 사용해야 합니다. 파일 확장자를 반복해서 바꾸는 것으로 호환성 문제를 해결하려 하지 마세요. 확장자는 설정 구조를 변환하지 않습니다.

CACHE AND UPDATE

실패한 캐시를 정리하고 설정 업데이트 완료 여부 확인하기

많은 그래픽 클라이언트는 원격 구독을 먼저 로컬 파일로 다운로드한 다음 로컬 캐시에서 로드합니다. 업데이트에 실패하면 클라이언트가 마지막으로 성공한 버전을 계속 사용할 수 있고, 오류 페이지 내용만 담긴 임시 파일을 저장할 수도 있습니다. 따라서 “노드 목록이 여전히 존재한다”는 사실만으로 방금 업데이트가 성공했다고 볼 수 없으며, “업데이트 시간이 바뀌었다”는 사실만으로 새 설정이 코어에 적용되었다고 단정할 수도 없습니다.

먼저 현재 정상적으로 작동하는 설정의 이름과 업데이트 시간을 기록하고 필요한 로컬 오버라이드 내용을 내보내세요. 그런 다음 클라이언트 로그에서 업데이트 작업이 “요청 완료, 파일 쓰기, 설정 검증, 코어 재로드” 단계를 모두 포함하는지 확인하세요. 다운로드 완료만 보이고 reload 또는 설정 전환 성공이 없다면 검증 단계에서 멈췄을 가능성이 있습니다.

안전한 캐시 처리 순서

자동 업데이트를 중지해 점검 중 파일이 계속 덮어써지거나 요청 빈도 제한이 발생하지 않게 하세요.
기본 네트워크를 복구할 수 있도록 최근에 정상 작동한 로컬 설정 사본을 보관하세요.
클라이언트에서 해당 실패 구독 기록을 삭제한 뒤, 다시 복사한 전체 주소로 추가하세요.
클라이언트를 완전히 종료하고 다시 시작하세요. 백그라운드 코어 프로세스도 종료되었는지 확인하세요.
수동 업데이트를 한 번 실행하고 즉시 로그에서 HTTP 상태, 파일 경로, 첫 번째 오류를 확인하세요.
업데이트가 성공한 뒤 자동 업데이트를 다시 활성화하고 적절한 간격을 설정하세요.

클라이언트가 오버라이드, 병합 또는 전처리를 지원한다면 이 기능도 잠시 끄세요. 원본 구독은 파싱되지만 병합 후 실패한다면 문제는 로컬 오버라이드 파일에 있습니다. 흔한 문제로는 오버라이드 후 중복 프록시 그룹 생성, 삭제된 그룹을 가리키는 규칙, 목록을 객체로 바꾸는 설정, 오래된 코어에 새로운 필드를 기록하는 경우가 있습니다.

설정 저장 경로도 오판의 원인이 될 수 있습니다. 시스템 권한 부족, 처리할 수 없는 문자가 포함된 경로, 디스크 공간 부족 또는 보안 프로그램의 쓰기 차단으로 클라이언트가 다운로드에는 성공했지만 기존 파일을 교체하지 못할 수 있습니다. 이러한 로그에는 보통 write, permission, rename, file in use 등의 정보가 포함됩니다. 원격 구독을 계속 수정하기보다 파일 쓰기 조건을 해결하세요.

DIAGNOSTIC ORDER

정해진 순서로 구독 가져오기 자가 점검하기

효율적인 문제 해결의 핵심은 한 번에 한 단계만 검증하고 각 단계의 결과를 남기는 것입니다. 다음 순서는 “구독 링크 오류”, “설정 파싱 실패”, “업데이트 후 활성화 불가”와 같은 인접한 문제에 적용할 수 있으며, 네트워크 문제와 형식 문제, 클라이언트 문제가 서로 영향을 주는 것도 줄여 줍니다.

기본 네트워크 확인: 시스템 프록시 또는 TUN을 일시 중지하고 일반 네트워크와 DNS가 정상인지 확인한 뒤 구독 도메인에 연결할 수 있는지 테스트하세요.
주소 다시 가져오기: 구독 관리 페이지에서 전체 링크를 복사해 잘림, 만료, 수동 수정 가능성을 배제하세요.
요청 결과 기록: HTTP 상태, 리디렉션, TLS 메시지, 응답 유형을 확인하고 브라우저에서 “열린다”는 사실만으로 판단하지 마세요.
본문 형식 확인: 반환된 콘텐츠가 완전한 Clash YAML인지, provider 파일인지, URI 모음인지 확인한 뒤 알맞은 가져오기 방식을 선택하세요.
YAML 점검: 오류가 난 줄을 기준으로 들여쓰기, 따옴표, 콜론, 목록, 참조 이름을 확인하고 먼저 로드 가능한 최소 설정을 만드세요.
코어 버전 확인: 클라이언트가 실제로 Clash와 Mihomo 중 무엇을 사용하는지 확인하고 오류가 난 필드가 현재 버전에서 지원되는지 점검하세요.
로컬 오버라이드 비활성화: 원본 구독으로 테스트한 다음 규칙 병합, 스크립트, DNS, TUN 수정 사항을 하나씩 복원하세요.
캐시 처리: 정상 작동하는 사본을 보관한 뒤 구독을 다시 추가하고 다운로드, 검증, 쓰기, 코어 재로드가 모두 완료되었는지 확인하세요.
실행 결과 확인: 프록시 그룹이 완전한지, 규칙이 적용되는지, DNS가 예상한 결과를 반환하는지 확인한 뒤 실제 연결을 테스트하세요.

구독 제공업체에 문의할 때는 발생 시간, 클라이언트 이름, 실제 코어와 버전, HTTP 상태, 오류 로그 앞뒤 몇 줄, 인증 정보를 가린 응답 시작 부분을 함께 전달하는 것이 좋습니다. “가져오기가 안 된다”는 스크린샷만 보내지 마세요. 명확한 증거가 있으면 구독 생성, 서버 접근 제어, 형식 변환, 클라이언트 호환성 중 어디에 문제가 있는지 빠르게 판단할 수 있습니다.

같은 로컬 YAML이 현재 코어에서는 로드되지만 원격 주소 가져오기에 실패한다면 다운로드 요청, 리디렉션, 응답 인코딩, 캐시 쓰기를 중점적으로 확인하세요. 여러 클라이언트가 본문 다운로드에는 성공하지만 같은 필드에서 모두 오류가 난다면 서버가 생성한 설정의 구문 또는 호환성 문제일 가능성이 높습니다. 한 대의 기기에서만 실패한다면 해당 기기의 시스템 시간, 네트워크, 인증서, 파일 권한, 클라이언트 코어 버전을 다시 점검하세요.

문제를 해결한 뒤 최근에 정상 작동한 설정 사본을 보관하고 구독 형식과 호환 코어를 기록하세요. 이후 업데이트 이상이 발생했을 때 “원격 구독이 변경된 것인지”와 “로컬 실행 환경이 변경된 것인지”를 빠르게 구분할 수 있어 네트워크가 끊긴 상황에서도 점검 조건을 모두 잃지 않을 수 있습니다.