구독 가져오기 오류, 먼저 실패가 어느 단계에서 발생했는지 파악하세요
Clash Verge 구독 가져오기 오류는 발생 단계에 따라 다운로드 실패, 파싱 실패, YAML 검증 실패, 코어 로드 실패 네 가지로 나눌 수 있습니다. 네 가지 원인의 진단 방향이 완전히 다르므로, 먼저 단계를 파악한 후 진단을 시작하면 많은 시간을 절약할 수 있습니다.
| 오류 단계 | 대표적인 오류 메시지 | 가장 흔한 원인 |
|---|---|---|
| 다운로드 단계 | 「다운로드 실패」「구독 콘텐츠 가져오기 실패」 | 링크 만료, 네트워크 차단, 인증 실패 |
| 파싱 단계 | 「파싱 실패」「유효한 YAML이 아님」 | HTML 페이지 반환, Base64 디코딩 이상 |
| 검증 단계 | 「YAML 파싱 오류: line 12」 | 들여쓰기 오류, 닫히지 않은 따옴표, 중국어 문장 부호 |
| 로드 단계 | 「필드 비호환」「설정 로드 실패」 | mihomo와 구버전 Clash의 필드 차이 |
진단 방법: Clash Verge의 「구독」 페이지를 열고 「업데이트」를 한 번 클릭한 뒤 오류가 발생하는 시점을 관찰하세요. 진행 표시줄이 끝나기 전에 실패하면 다운로드 문제이고, 다운로드 완료 직후 오류가 발생하면 파싱 또는 검증 문제이며, 설정은 로드되지만 코어 시작에 실패하면 필드 호환성 문제입니다. 아래 네 절에서 순서대로 설명합니다.
링크 접근성: 만료, 인증 및 네트워크 차단
첫 번째 단계로, 구독 링크 전체를 브라우저 주소창에 복사해 직접 접속해 보세요. 이것이 가장 빠른 판단 방법입니다:
proxies:로 시작하는 텍스트가 반환됨: 링크는 정상이며 문제는 클라이언트에 있음- 404 또는 「링크가 존재하지 않음」 반환: 구독이 이미 만료되었으니 공급자 패널에서 다시 생성하세요
- 로그인 페이지 또는 요금제 만료 안내 반환: 계정 상태가 비정상이므로 먼저 갱신하거나 구독을 재설정하세요
- 계속 로딩되거나 시간 초과: 로컬 네트워크에서 구독 서버까지의 경로가 막혀 있음
브라우저에서는 열리는데 클라이언트에서 다운로드가 실패하면 명령줄로 확인하세요. Windows는 PowerShell을, macOS는 터미널을 열고 다음을 실행합니다:
curl -v -L "구독 링크" -o sub.yaml -w "%{http_code}\n"두 가지 출력에 주목하세요: HTTP 상태 코드와 응답 본문입니다.
| 상태 코드 | 의미 | 조치 |
|---|---|---|
| 200 | 서버가 정상적으로 응답함 | 클라이언트 구독 설정 확인 |
| 401 / 403 | 인증 실패 또는 UA 차단 | 링크를 다시 복사하고 User-Agent를 직접 지정 |
| 404 | 구독이 삭제되었거나 만료됨 | 공급자 패널에서 다시 생성 |
| 429 | 요청이 너무 잦음 | 몇 분 기다린 후 재시도 |
| 000 / 시간 초과 | 연결이 재설정됨 | DNS, 방화벽, 프록시 경로 확인 |
일부 공급자는 User-Agent를 검사하는데, 클라이언트 기본 UA가 비정상 트래픽으로 인식될 수 있습니다. Clash Verge의 구독 편집 패널에서 User-Agent를 직접 지정할 수 있으므로, 흔히 쓰는 브라우저 UA 문자열을 입력하면 우회할 수 있습니다.
DNS 오염도 구독 업데이트 실패의 원인이 됩니다. 구독 도메인이 잘못된 주소로 해석되면 브라우저는 시스템 프록시를 사용해 정상적으로 열리지만, 클라이언트는 직접 연결하다가 시간 초과가 발생할 수 있습니다. 구독 도메인을 「설정」 → 「환경 설정」 → 「시스템 프록시」의 직접 연결 규칙에 추가하거나, 일시적으로 사용 가능한 노드로 전환한 뒤 구독을 업데이트하세요.
구독을 업데이트하기 전에 현재 사용 가능한 노드가 하나 이상 있는지 확인하세요. 구독 업데이트 요청은 기본적으로 프록시 경로를 통해 전송되므로, 모든 노드가 사용 불가능한 상태면 요청이 ISP에 직접 연결되어 실패율이 크게 높아집니다.
응답 콘텐츠 형식: HTML, Base64 및 변환기 JSON
링크는 접근 가능한데 클라이언트가 여전히 「파싱 실패」를 보고한다면, 대부분 반환 콘텐츠가 표준 YAML 구독이 아니기 때문입니다. 브라우저로 링크를 열어 반환 콘텐츠의 시작 부분을 확인하세요:
- HTML 페이지: 공지 페이지, Cloudflare 인증 페이지 또는 404 페이지라면 링크가 웹페이지를 가리키는 것
- Base64 문자열: 일부 공급자는 구독을 Base64로 인코딩하며 이는 정상적인 현상
- JSON 구조: 공급자가 구독 변환기를 사용 중이며 반환된 것은 변환 결과
- 빈 파일: 서버가 빈 콘텐츠를 반환하므로 공급자에게 문의
Clash Verge는 Base64 구독을 직접 가져올 수 있으며 클라이언트가 자동으로 디코딩합니다. 하지만 일부 공급자의 Base64 콘텐츠에 줄바꿈 문자나 BOM 헤더가 섞여 있으면 디코딩이 실패할 수 있습니다. 링크 내용을 아무 Base64 디코더에 붙여넣어 디코딩 결과가 proxies:로 시작하는지 확인하면 이런 문제를 배제할 수 있습니다.
공급자가 구독 변환기 링크(예: Subconverter 형식)를 제공한다면, 링크 뒤에 보통 변환 매개변수가 붙어 있습니다:
?target=clash&url=원본 구독 링크변환기마다 매개변수 이름이 다르므로, 공급자 패널에서 제공하는 「Clash 구독」 전용 링크를 사용하고 매개변수를 직접 조합하지 않는 것이 좋습니다.
또 다른 숨은 문제: 공급자가 구독 콘텐츠를 HTTP 응답 헤더에 넣거나, gzip 압축을 사용하면서 Content-Encoding을 선언하지 않은 경우입니다. 이런 비정상적인 응답은 클라이언트가 자동으로 처리할 수 없으므로 공급자 고객센터에 문의해 수리해야 합니다.
YAML 문법 오류: 들여쓰기, 따옴표 및 중국어 문장 부호
구독 콘텐츠 다운로드는 성공했고 형식도 YAML로 인식되지만 파서가 읽지 못한다면 YAML 문법 문제입니다. 공급자가 생성한 설정에 가끔 오류가 있으며, 설정 파일을 직접 편집한 사용자라면 더 자주 발생합니다. 흔한 오류:
- 들여쓰기에 공백과 Tab 혼용: YAML은 공백만 허용하며 Tab은 즉시 오류 발생
- 콜론 뒤 공백 누락:
name: 노드 이름은 유효하지만name:노드 이름은 파싱 실패 - 따옴표가 닫히지 않음: 노드 이름에 특수 문자가 포함되면 따옴표로 감싸야 함
- 중국어 문장 부호: 전각 콜론 「:」, 전각 쉼표 「,」가 템플릿에 섞이면 파서가 인식하지 못함
- URL의
#가 이스케이프되지 않음: YAML에서#는 주석 시작 문자이므로 값 안의#는 따옴표로 감싸야 함
mihomo의 오류 메시지에는 줄 번호가 포함됩니다. 예:
yaml: line 12: mapping values are not allowed in this context진단 방법: Clash Verge의 「설정」 → 「환경 설정」 → 「설정 디렉터리」를 열면 profiles 폴더에 구독에 해당하는 yaml 파일이 있습니다. 텍스트 편집기로 오류 줄로 이동해 들여쓰기, 콜론, 따옴표를 확인하세요.
그래픽 인터페이스가 없다면 명령줄로 검증하세요:
python -c "import yaml; yaml.safe_load(open('sub.yaml', encoding='utf-8'))"None이 출력되면 문법이 올바른 것입니다. 오류가 발생하면 구체적인 줄 번호와 원인이 표시됩니다. 수동 수정은 일시적인 해결책일 뿐입니다. 공급자 구독은 다음 업데이트 때 파일 전체를 덮어쓰기 때문입니다. 올바른 방법은 공급자에게 피드백을 보내거나, 구독 변환기로 깨끗한 설정을 다시 생성하는 것입니다.
구독 파일을 수동으로 수정하기 전에 먼저 복사본을 백업하세요. 구독을 업데이트하면 profiles 디렉터리의 해당 파일을 덮어쓰므로, 백업이 없으면 처음부터 다시 진단해야 합니다.
코어 필드 호환성: mihomo와 구버전 Clash의 차이
구독이 파싱되고 로드되지만 코어 시작 오류가 발생하거나 일부 노드를 사용할 수 없다면 필드 호환성 문제입니다. Clash 코어가 Clash Premium에서 mihomo로 이전되면서 두 세대 코어의 필드는 완전히 호환되지 않습니다.
기존 구독에서 흔히 볼 수 있는 구식 작성 방식:
| 기존 필드 | mihomo에서의 상태 | 대체 방법 |
|---|---|---|
dns.enable |
사용 중단됨 | dns 섹션은 기본 활성화되므로 바로 삭제 |
tun.enable |
구버전 방식 | 전체 tun 섹션으로 설정 |
experimental.udp-fallback |
제거됨 | sniffer 사용 |
proxy-groups에 url 누락 |
새 버전에서는 필수 | 테스트 주소 추가 |
mihomo에서 새로 추가된 필드는 구버전 코어도 인식하지 못합니다. 예를 들어 sniffer, profile.store-selected, dns.fake-ip-filter가 있습니다.
판별 방법: 코어 로그를 확인하세요. Clash Verge의 「설정」 → 「환경 설정」 → 「로그」에서 코어 출력을 볼 수 있으며, unknown field 또는 unsupported 문구가 나타나면 필드 호환성 문제입니다. 처리 우선순위:
- 공급자에게 mihomo 전용 구독 링크 요청 — 대부분의 공급자는 Clash와 mihomo 두 링크를 함께 제공
- 구독 변환기로 기존 형식을 mihomo 형식으로 변환
- 구독 편집 패널에서 호환되지 않는 필드를 수동으로 삭제
필드를 삭제할 때 proxies 섹션의 핵심 필드는 건드리지 마세요. type, server, port, uuid, alterId는 노드 연결의 기본이므로 잘못 삭제하면 모든 노드를 사용할 수 없게 됩니다.
전체 자가 진단 순서와 복구 권장 사항
위 네 가지 원인을 하나의 경로로 연결해 순서대로 실행하면 대부분의 문제를 5분 안에 진단할 수 있습니다:
- 브라우저로 구독 링크를 열어 반환 콘텐츠가 YAML 또는 Base64인지 확인
- curl로 HTTP 상태 코드 확인, 403 또는 404면 링크 다시 생성
- 로컬 yaml로 저장한 뒤 Python 또는 온라인 도구로 문법 검증
- 코어 로그를 확인해
unknown field경고가 없는지 확인 - Clash Verge에서 기존 구독을 삭제하고 새 링크를 다시 가져오기
- 코어를 시작하고 프록시가 필요한 사이트에 접속해 연결 확인
모든 검사를 통과했는데도 사용할 수 없다면 구독 파일과 코어 로그를 함께 공급자 고객센터에 보내고 mihomo 버전 번호를 첨부하면 진단 효율이 훨씬 높아집니다.
마지막으로 복구 권장 사항: 구독을 성공적으로 가져올 때마다 「구독」 페이지에서 설정 파일 복사본을 백업하세요. 설정에 문제가 생겨 롤백이 필요할 때 백업 내용을 바로 붙여넣으면 처음부터 진단하는 것보다 훨씬 빠릅니다.