Clash 구독 링크 만료·파싱 실패 진단법: 응답 내용부터 형식 호환성까지 단계별 점검

구독 가져오기 오류나 업데이트 후 노드 소실은 대부분 클라이언트 문제가 아닙니다. 반환 내용, 링크 유효기간, 형식, 변환 단계를 순서대로 점검하고 브라우저와 curl로 원본 응답을 확인하는 방법을 정리합니다.

두 가지 문제를 먼저 구분하기: 링크 만료와 파싱 실패

"구독 문제"에는 서로 다른 두 가지 현상이 섞여 있으며 대처 방법도 완전히 다릅니다. 첫 번째는 링크 만료로, 클라이언트가 타임아웃·연결 불가·404를 표시하거나 아예 아무 내용도 받아오지 못하는 경우입니다. 이런 문제의 원인은 대개 서버 측이나 네트워크 경로에 있으며 클라이언트 설정과는 무관합니다. 두 번째는 파싱 실패로, 구독은 정상적으로 다운로드되고 클라이언트도 실제로 데이터를 받았지만 가져오기 후 형식 오류, YAML 파싱 오류, 또는 노드 목록이 비어 있거나 일부 노드가 사라지는 경우입니다. 이런 문제의 원인은 대부분 구독 내용 자체의 형식에 있으며, 링크에 접근 가능한지 여부와는 별개입니다.

이 두 문제를 혼동하는 것이 진단이 헛돌게 되는 주요 원인입니다. 많은 사람이 클라이언트 오류 메시지를 보면 바로 클라이언트를 재설치하거나 코어를 바꾸는데, 실제로는 먼저 2분만 투자해 구독의 원본 응답 내용을 확인하는 것만으로 절반 이상의 진단 방향을 배제할 수 있습니다.

1단계: 브라우저와 curl로 구독의 원본 응답 내용 직접 확인하기

클라이언트는 구독 내용을 소비하는 쪽일 뿐, 서버가 실제로 무엇을 반환했는지 알려주지 않습니다. 문제가 어느 단계에 있는지 판단하려면 항상 클라이언트를 건너뛰고 구독 링크 자체가 무엇을 반환하는지 먼저 확인해야 합니다.

가장 간단한 방법은 구독 링크를 브라우저 주소창에 붙여넣어 직접 접속하는 것입니다. 브라우저가 다운로드 창을 띄우거나 텍스트를 표시하면 내용을 열어 확인해 보세요.

• proxies:, proxy-groups:로 시작하는 텍스트가 보인다면 표준 Clash YAML 설정이며 형식 자체에는 문제가 없습니다.
• vmess://, ss://, trojan://로 시작하는 긴 문자열이 줄바꿈이나 Base64로 이어져 있다면 범용 구독 형식(흔히 Base64 구독이라 부름)으로, 클라이언트나 변환 서비스가 추가로 처리해야 Clash 설정으로 바뀝니다.
• HTML 페이지나 오류 메시지, 또는 "로그인이 만료되었습니다", "트래픽이 모두 소진되었습니다" 같은 문구가 보인다면 문제는 서버 측에 있으며 클라이언트 설정과는 전혀 관련이 없습니다.
• 브라우저가 접속 불가나 연결 시간 초과를 표시한다면 링크 자체가 이미 만료되었거나 네트워크 연결 문제가 있는 것입니다.

브라우저 방식은 주소창이 일부 문자 인코딩을 다르게 처리할 수 있다는 한계가 있습니다. 더 확실한 방법은 curl 명령으로 직접 가져오는 것입니다. 명령줄 결과는 브라우저 캐시나 확장 프로그램의 영향을 받지 않으므로 구독이 정상인지 판단하는 가장 신뢰할 수 있는 수단입니다.

curl -v -o subscription.txt "구독 링크"

-v 옵션을 추가하면 DNS 조회, TLS 핸드셰이크, HTTP 상태 코드를 포함한 전체 요청 과정을 확인할 수 있습니다. 특히 반환된 상태 코드에 주목하세요.

• 200: 요청 성공. 내용이 subscription.txt에 저장되었으니 텍스트 편집기로 열어 확인하세요.
• 401 / 403: 인증 실패 또는 권한 부족으로, 링크의 토큰 파라미터가 만료된 경우에 흔히 발생합니다.
• 404: 링크가 가리키는 리소스가 존재하지 않으며, 보통 구독 주소가 삭제되었거나 경로가 잘못 입력된 경우입니다.
• 429: 요청이 너무 잦아 속도 제한이 걸린 상태입니다. 몇 분 기다린 뒤 다시 시도하고, 짧은 시간 안에 구독을 반복해서 수동으로 새로고침하지 마세요.
• 5xx: 서버 자체의 오류로, 클라이언트나 로컬 네트워크와는 무관하며 서버가 복구될 때까지 기다리는 수밖에 없습니다.

curl 요청에 클라이언트 전용 User-Agent를 붙여야 전체 노드를 받을 수 있는 경우도 있습니다(일부 서비스는 User-Agent에 따라 다른 내용을 반환하며, 예를 들어 Clash 클라이언트로 인식될 때만 노드 정보를 주고 그 외에는 안내 문구만 반환합니다). 이때는 명시적으로 지정할 수 있습니다.

curl -v -A "clash-verge/v2" -o subscription.txt "구독 링크"

User-Agent를 실제 사용 중인 클라이언트 식별자로 바꿔 응답 내용을 다시 비교해 보세요. 이번에는 전체 노드를 받았는데 기본 User-Agent로는 받지 못했다면, 구독 서비스에 UA 화이트리스트 메커니즘이 있는 것이며 이는 정상 동작이지 오류가 아닙니다.

2단계: 링크 유효기간과 트래픽·기기 수 제한 확인하기

구독 응답 내용이 실제로 이상하다는 것을 확인했다면, 다음으로 유효기간과 한도 문제를 점검합니다. 이런 제한은 대개 응답 내용에 직접 표시되어 있지만 쉽게 간과됩니다.

1. 만료 시각: 대부분의 서비스는 HTTP 응답 헤더에 Subscription-Userinfo 필드를 담아 보내며, 여기에는 expire(만료 타임스탬프), total(총 트래픽), upload/download(사용한 트래픽)가 포함됩니다. curl -v를 사용하면 이 응답 헤더가 출력에 표시되어 만료 시각과 남은 트래픽을 바로 확인할 수 있습니다.
2. 트래픽 소진: upload+download가 total에 가깝거나 이를 초과하면, 링크 자체는 접근 가능하더라도 서버가 의도적으로 빈 노드 목록이나 안내 문구를 반환할 수 있습니다. 이때 클라이언트가 "노드 0개"로 파싱하는 것은 정상적인 현상이며 파싱 오류가 아닙니다.
3. 기기 수 제한: 일부 서비스는 같은 계정에 연결할 수 있는 기기 수나 동시 접속 수를 제한하며, 초과 시 새 기기의 구독 요청이 거부되거나 축소된 노드 목록이 반환될 수 있습니다. 최근 기기를 추가했거나 클라이언트를 바꿨다면 다른 기기에서 먼저 구독을 비활성화한 뒤 다시 시도해 보세요.
4. IP 또는 지역 제한: 일부 구독 서비스는 요청 발신 IP에 화이트리스트나 지역 제한을 두고 있어, 네트워크 환경을 바꾼 뒤(예: 회사 네트워크에서 가정 네트워크로) 구독이 갑자기 업데이트되지 않는다면 이런 제한을 의심해 볼 만합니다.

3단계: 구독 형식 종류와 클라이언트 호환성 확인하기

서버 응답 이상과 계정 제한을 배제한 뒤에도 구독 내용 자체는 정상적으로 다운로드되는데 클라이언트에서 가져오기 오류가 난다면, 대부분 형식 호환성 문제입니다. 흔히 쓰이는 구독 형식은 한 가지가 아닙니다.

• 표준 Clash / Clash Meta(mihomo) YAML: proxies, proxy-groups, rules를 주요 필드로 하는 완전한 설정 파일로, 클라이언트에서 바로 사용할 수 있습니다. 필드 간 들여쓰기와 콜론 뒤 공백 규칙이 엄격해서 수동으로 편집할 때 이 부분에서 실수가 가장 잦습니다.
• Base64로 인코딩된 범용 구독: 여러 프로토콜 링크(vmess://, ss://, trojan://, hysteria2:// 등)를 Base64로 인코딩해 이어붙인 내용으로, Clash 설정으로 바로 사용할 수 없으며 먼저 디코딩한 뒤 YAML 구조로 변환해야 합니다. Clash Meta 코어를 지원하는 대부분의 클라이언트는 이 변환 로직을 이미 내장하고 있지만, 클라이언트 버전이 오래되면 hysteria2, tuic 같은 최신 프로토콜을 인식하지 못해 가져오기 시 "알 수 없는 프로토콜 유형" 오류가 나거나 해당 노드를 건너뛸 수 있습니다.
• 특정 패널의 커스텀 형식: 일부 구독 패널은 표준 필드 외에 커스텀 파라미터를 추가하는데, 오래된 버전의 클라이언트가 인식하지 못하는 필드를 만나면 무시하고 넘어가는 경우도 있고 엄격 모드에서 오류로 중단되는 경우도 있습니다.

프로토콜 호환성 문제인지 판단하려면 오류 메시지에 구체적인 필드명이나 프로토콜명이 언급되는지 확인하세요. 예를 들어 unsupported type이라거나 특정 필드를 인식할 수 없다는 표시가 그렇습니다. 이런 경우 먼저 클라이언트가 사용하는 코어 버전을 확인하고, 구독에 쓰인 프로토콜이 해당 버전의 지원 목록에 있는지 확인하세요. 대부분 클라이언트를 최신 버전으로 업그레이드하면 해결되는데, 새로운 프로토콜 지원은 계속 추가되고 있기 때문입니다.

4단계: 변환 단계에서 발생하는 파싱 오류 점검하기

많은 구독 링크는 사실 뒤에서 "구독 변환" 서비스를 거칩니다. 원본 노드 정보를 변환 서비스가 먼저 읽어들인 뒤 Clash 형식으로 다시 생성해 클라이언트에 반환하는 방식입니다. 이 변환 과정 자체에서도 오류가 발생할 수 있으며, 흔한 경우는 다음과 같습니다.

• 변환 서비스가 일시적으로 오류를 일으켜 반환된 YAML 내용이 불완전하거나 잘려서, 클라이언트가 파일 끝의 닫힘 구조가 없다는 이유로 오류를 표시합니다.
• 변환 규칙 템플릿 자체가 잘못 작성된 경우, 예를 들어 정책 그룹이 존재하지 않는 노드 이름을 참조하면 YAML 문법상으로는 문제가 없지만 클라이언트가 정책 그룹을 로드할 때 해당 노드를 찾지 못해 오류가 나거나 정책 그룹이 비어 있게 됩니다.
• 변환 서비스가 특수 문자를 제대로 처리하지 못해, 노드 이름에 포함된 이모지·세로줄·콜론 같은 기호가 변환 후 YAML 구조의 완전성을 깨뜨리는 경우입니다.

이런 문제를 진단하려면 curl로 받은 원본 내용을 처음부터 끝까지 살펴보는 것이 가장 직접적인 방법입니다. 파일 끝이 완전한지, 들여쓰기가 일관되는지, 명백한 깨짐이나 잘림이 있는지를 중점적으로 확인하세요. 내용이 실제로 불완전하다면 변환 서비스나 원본 서버 측 문제일 가능성이 높으며 로컬 클라이언트 설정과는 무관합니다. 이 경우 구독 제공자에게 문의하거나 수정을 기다리는 수밖에 없으며, 로컬에서는 지난번 정상적으로 로드된 이전 설정을 임시로 사용하는 것 정도만 할 수 있습니다.

클라이언트가 이전 구독 캐시를 보관하는 기능을 지원한다면(대부분의 주요 클라이언트가 이 메커니즘을 갖추고 있습니다), 업데이트가 실패해도 마지막으로 성공적으로 로드된 설정으로 자동 되돌아가므로 프록시가 바로 사용 불가능해지지는 않습니다. 그래서 "구독 업데이트" 오류가 기존 프록시의 즉시 실패를 의미하지는 않으니, 당황해서 업데이트를 반복 재시도할 필요는 없습니다.

자주 발생하는 오류 메시지 빠른 대조표

클라이언트에서 흔히 나타나는 구독 오류 메시지와 그에 맞는 진단 방향을 정리했습니다. 메시지 속 키워드로 문제 범위를 빠르게 좁힐 수 있습니다.

• timeout / 연결 시간 초과: 먼저 curl로 링크 접근 가능 여부를 단독으로 테스트하세요. 대부분 네트워크 경로나 서버 문제이며 형식 문제가 아닙니다.
• yaml: line X: mapping values are not allowed: 전형적인 들여쓰기 오류나 콜론 뒤 공백 누락 문제로, 설정을 직접 편집했거나 변환 서비스 템플릿이 잘못된 경우에 많이 나타납니다.
• proxy group xxx not found: 정책 그룹이 존재하지 않는 노드나 그룹 이름을 참조하는 경우로, 대개 변환 템플릿 설정 오류이니 구독 제공자에게 문의하세요.
• unsupported proxy type: 클라이언트 코어가 구독 안의 프로토콜 유형을 인식하지 못하는 경우로, 클라이언트를 업그레이드하거나 프로토콜 표기가 올바른지 확인하세요.
• empty proxies list / 노드 수 0개: 먼저 트래픽이 소진되었거나 계정 상태가 이상한지 확인한 뒤, 구독 링크가 제한으로 빈 목록을 반환하고 있는지 확인하세요.

이 대조표를 curl 점검과 함께 사용하면 구독 관련 문제의 대부분을 다룰 수 있습니다. 핵심 원칙은 항상 동일합니다. 먼저 서버가 무엇을 반환했는지 확인하고, 그다음 내용 문제인지 클라이언트 호환성 문제인지 판단하며, 마지막에야 로컬 설정 조정이 필요한지 고민합니다. 이 순서로 진단하면 클라이언트 설정에서 의미 없는 시도를 하는 것을 피할 수 있습니다.