Clash 구독 가져오기 파싱 오류: 링크 형식·YAML 들여쓰기·요청 헤더 점검 목록

다운로드 오류, 파싱 오류, 노드 없음부터 구분하기

Clash 구독을 가져올 때는 몇 단계가 진행됩니다. 클라이언트가 구독 주소로 요청을 보내고, 응답 본문을 받은 뒤, 내용을 설정으로 변환하거나 파싱해 커널에 전달합니다. 화면에 표시되는 ‘업데이트 실패’는 이 여러 단계를 한꺼번에 나타낼 수 있습니다. 먼저 클라이언트 로그를 열어 실패 시각과 원래 오류 메시지를 기록한 다음, 링크와 설정 중 무엇을 점검할지 판단하세요.

Windows 클라이언트마다 메뉴 이름은 다를 수 있습니다. 구독 메뉴가 ‘구독’ 또는 ‘프로필’로 표시될 수 있고, 로그는 보통 ‘로그’ 페이지에서 확인할 수 있습니다. 오류가 발생한 구독을 한 번 업데이트한 직후, 같은 시각의 로그를 확인하세요. 노드 지연 시간 측정 실패를 가져오기 오류로 오인하지 않도록 주의해야 합니다.

로그 또는 증상	먼저 확인할 항목	지금은 하지 말아야 할 작업
`timeout`、`Could not resolve host`	네트워크 연결, 도메인 이름 확인, 구독 업데이트에 사용되는 프록시 경로	먼저 YAML 들여쓰기를 수정하지 마세요
HTTP 401、403、404	구독 토큰, 접근 제한, 주소의 유효 여부	클라이언트를 반복해서 재설치하지 마세요
`yaml: line ...`、`unmarshal`	응답 본문, 필드 형식, 오류가 표시된 줄 주변의 구조	파일 확장자만으로 형식을 판단하지 마세요
가져오기는 완료됐지만 선택할 노드가 없음	`proxies`, `proxy-providers` 및 프록시 그룹 참조	`DIRECT`를 추가해 노드를 복구하려고 하지 마세요
`unsupported proxy type`	커널 이름, 버전 및 노드 프로토콜	프로토콜 이름을 임의로 다른 프로토콜로 바꾸지 마세요

1단계: 구독 링크와 HTTP 응답 확인

계정 페이지 주소가 아닌 구독 주소 복사하기

서비스 제공자의 구독 페이지로 돌아가 Clash 또는 Clash Meta/mihomo용으로 명확히 표시된 구독 메뉴를 선택하세요.
전체 링크를 다시 복사하고, 주소가 https:// 또는 서비스에서 명시적으로 제공한 http://로 시작하는지 확인하세요. 끝에 줄바꿈, 한글 문장부호 또는 불필요한 공백이 없어야 합니다.
쿼리 매개변수가 모두 있는지 확인하세요. &가 포함된 주소가 잘리면 첫 번째 매개변수만 남을 수 있습니다. 웹페이지 소스에서 복사할 때는 문자 그대로의 &가 잘못 포함되지 않았는지도 살펴보세요.
최근 구독 토큰을 재설정했다면 클라이언트의 주소를 새 주소로 바꾸세요. 업데이트 버튼을 다시 눌러도 이전 링크는 복구되지 않습니다.

주소에 .yaml 확장자가 없어도 형식 오류라는 뜻은 아닙니다. 반대로 .yaml로 끝나는 주소가 로그인 페이지나 오류 메시지를 반환할 수도 있습니다. 실제로 확인해야 할 것은 서버가 반환한 상태 코드와 본문입니다.

Windows에서 실제 응답 내용을 저장하기

아래 명령은 Windows PowerShell에서 실행합니다. 일부 PowerShell 버전의 명령 별칭과 혼동하지 않도록 시스템의 curl.exe를 사용합니다. 먼저 본인만 사용하는 임시 폴더로 이동한 다음 실행하세요. 토큰이 포함된 주소를 명령 기록에 직접 남기지 않도록 입력 프롬프트에서 링크를 받습니다.

$url = Read-Host '구독 주소를 붙여넣으세요'
curl.exe --location --max-time 30 --dump-header response-headers.txt --output subscription-response.txt -- "$url"
Get-Content .\response-headers.txt
Get-Content .\subscription-response.txt -TotalCount 12
Remove-Variable url

--location은 리디렉션을 따라가며, --max-time 30은 전체 요청 시간을 30초로 제한합니다. 응답 헤더가 여러 묶음으로 표시되면 마지막 상태를 확인하세요. 명령이 파일 저장에 성공했다는 사실만으로 유효한 구독이라고 단정할 수는 없습니다. 응답 헤더에 민감한 리디렉션 주소가 포함될 수도 있으니, 확인이 끝나면 이 파일들을 삭제하세요.

200: 본문을 계속 확인하세요. 로그인 페이지나 서비스 오류도 200을 반환할 수 있습니다.
301, 302: 최종적으로 로그인 또는 인증 페이지가 아닌 구독 내용으로 이동하는지 확인하세요.
401, 403: 토큰과 접근 정책을 확인하세요. 서버 측 보안 기능이 요청을 거부했을 수도 있습니다.
404, 410: 구독 경로가 변경됐는지 확인하고, 링크 상태는 제공자에게 문의하세요.
429: 연속 업데이트를 중단하고 서버 안내에 따라 기다리세요. 추가로 요청 제한에 걸리지 않도록 주의하세요.

브라우저에서 열린다고 해서 클라이언트에서도 다운로드할 수 있는 것은 아닙니다. 브라우저에는 로그인 쿠키가 있을 수 있고, 다른 프록시 경로를 사용하거나 웹 인증을 이미 통과했을 수도 있습니다. 브라우저에 ‘정상’으로 표시되는 계정 페이지를 구독 유효성의 근거로 삼지 마세요.

2단계: 응답이 YAML, 노드 목록, 웹페이지 중 무엇인지 확인

응답 파일의 앞부분을 보면 대개 원인을 좁힐 수 있습니다. Content-Type은 참고할 수 있지만, 일부 서비스는 YAML을 일반 텍스트로 표시하므로 응답 헤더만으로 단정하면 안 됩니다.

내용 특징	가능한 형식	처리 방법
`proxies:`、`proxy-groups:`、`rules:`	Clash 설정 또는 설정 일부	구조와 필드, 커널 호환성을 계속 확인하세요
`<!DOCTYPE html>`、`<html`	로그인 페이지, 인증 페이지 또는 오류 페이지	구독 경로를 바로잡거나 제공자에게 문의하세요. YAML로 수정하지 마세요
`ss://`, `vmess://` 등의 줄별 링크	노드 공유 링크 목록	클라이언트에서 명시적으로 지원하는 가져오기 방법을 선택하거나 Clash 형식을 받으세요
길게 이어지는 인코딩 문자열	Base64 노드 목록일 수도 있고 다른 내용일 수도 있음	제공자 안내를 확인하세요. 겉모양만 보고 설정으로 가져오지 마세요
JSON 오류 메시지, 만료 안내 또는 빈 본문	API 오류 또는 사용할 수 없는 구독	먼저 서버 응답 문제를 해결한 다음 로컬 설정을 확인하세요

‘노드 제공자 파일’과 ‘전체 설정’은 서로 다릅니다. 전자는 proxies 목록만 포함하는 경우가 많으며, 기본 설정에서 proxy-providers로 참조해야 합니다. 프록시 그룹과 규칙이 들어 있지 않을 수 있으므로, 전체 설정으로 가져온다고 모든 라우팅 옵션이 자동으로 만들어지지는 않습니다.

형식을 변환해야 한다면 클라이언트에 내장되어 있고 작동 방식이 명확히 안내된 변환 기능이나 제공자 자체의 형식 메뉴를 우선 사용하세요. 토큰이 포함된 구독 링크를 출처 불명의 온라인 변환 사이트에 제출하지 마세요. 변환 서비스에서 링크와 응답에 포함된 노드 인증 정보를 확인할 수 있습니다.

3단계: YAML 들여쓰기, 따옴표 및 필드 형식 확인

오류가 표시된 줄과 그 상위 구조를 함께 확인하세요

오류 메시지에 표시된 줄 번호는 파서가 문제를 발견한 위치이며, 실제 오류가 시작된 위치와 다를 수 있습니다. 예를 들어 이전 줄의 따옴표가 닫히지 않았거나 들여쓰기 단계가 잘못됐으면 다음 줄에서 오류가 표시될 수 있습니다. 로컬 텍스트 편집기에서 파일을 열고 줄 번호와 공백 표시를 켠 뒤, 오류 줄과 앞뒤 5줄을 확인하세요.

계층 구조를 들여쓸 때는 탭 대신 공백을 사용하세요. 계층마다 공백 2개를 쓰면 읽기 편하지만, 무엇보다 같은 계층의 항목을 맞추는 것이 중요합니다.
필드 이름 뒤에는 반각 콜론 :을 쓰고, 매핑 값 앞에는 보통 공백을 둡니다. 예: mode: rule.
목록 항목은 반각 하이픈과 공백으로 시작합니다. 예: - DIRECT. 전각 대시는 하이픈을 대신할 수 없습니다.
문자열에 콜론과 공백, 특수 기호 또는 혼동하기 쉬운 내용이 있으면 여는 따옴표와 닫는 따옴표를 함께 사용하세요. 예: name: "홍콩: 01".
같은 매핑 계층에서 dns, rules 등의 키를 중복해서 쓰지 마세요. 파서마다 중복 키를 처리하는 방식이 다를 수 있습니다.

아래는 계층 구조를 이해하기 위한 직접 연결 테스트 설정입니다. 원격 노드가 없으므로 구독 복구 여부나 프록시 연결 상태를 확인할 수 없습니다. 로컬 테스트 사본에서만 사용하고, 정상 구독을 덮어쓰지 마세요.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxy-groups:
  - name: "로컬 테스트"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,로컬 테스트

proxy-groups는 목록이며, 각 프록시 그룹은 매핑입니다. 그룹 안의 proxies도 목록입니다. rules와 proxy-groups는 같은 최상위 계층에 있어야 하며, 특정 프록시 그룹 안에 들여쓰면 안 됩니다. 7890은 예시 수신 포트일 뿐이므로 실제 포트는 클라이언트에 표시된 값을 사용하세요.

구문 분석에 성공해도 필드 형식이 올바르다는 뜻은 아닙니다

목록을 문자열로 잘못 작성해도 YAML 문법 자체는 유효할 수 있지만 커널이 요구하는 형식과는 맞지 않습니다. 예를 들어 proxies: "DIRECT"는 위의 목록 형식과 데이터 유형이 다릅니다. cannot unmarshal 오류가 표시되면 공백만 조정하지 말고 필드가 문자열, 숫자, 불리언, 목록, 매핑 중 무엇을 요구하는지 함께 확인하세요.

원본 구독은 정상적으로 로드되지만 오버라이드를 추가한 뒤 오류가 발생한다면, 먼저 해당 구독에 연결된 오버라이드, 병합 또는 스크립트 처리를 중지한 다음 하나씩 다시 적용하세요. 클라이언트에 저장된 원본 구독과 커널에 전달되는 최종 설정은 다를 수 있으므로, 실제 적용된 최종 설정도 확인해야 합니다. 각 필드에 대한 자세한 내용은 규칙 구문 안내서와 DNS 설정 참고서를 확인하세요.

4단계: User-Agent와 mihomo 커널 지원 여부 확인

같은 링크도 요청에 따라 다른 형식을 반환할 수 있습니다

일부 구독 API는 요청 헤더의 User-Agent를 보고 클라이언트 종류를 판별합니다. 브라우저, 명령줄 도구, 클라이언트가 서로 다른 내용을 받을 수 있으므로 앞서 명령줄에서 확인한 결과가 클라이언트의 실제 응답과 완전히 같다고 볼 수는 없습니다.

클라이언트에 ‘구독 요청 헤더’ 또는 ‘User-Agent’ 설정이 있으면 기존 값을 먼저 기록한 뒤 제공자 문서를 확인하세요. 아래 명령은 응답 비교를 위해 요청 헤더를 mihomo로 설정합니다. 모든 구독 서비스에 통하는 해결책은 아니며, 구형 클라이언트가 mihomo 커널로 바뀌는 것도 아닙니다.

$url = Read-Host '구독 주소를 붙여넣으세요'
curl.exe --location --max-time 30 --user-agent "mihomo" --output response-mihomo.txt -- "$url"
Get-Content .\response-mihomo.txt -TotalCount 12
Remove-Variable url

기본 요청은 노드 링크 목록을 반환하지만 요청 헤더를 지정하면 YAML을 반환한다면, 서버가 요청 형식에 따라 응답을 분기하는 것입니다. 제공자가 명시적으로 지원하는 경로나 요청 헤더를 사용하고, 여러 식별 문자열을 연속해서 시험하지 마세요. 두 요청 모두 인증 페이지를 반환한다면 YAML을 수정하거나 요청 헤더를 바꿔도 서버 접근 제한은 해결되지 않는 경우가 많습니다.

클라이언트 버전과 커널 버전을 따로 기록하세요

Clash, Clash Premium, Clash Meta(현재 명칭 mihomo)는 지원하는 기능 범위가 서로 다릅니다. 설정에 type: hysteria2, type: vless 같은 노드 유형이 있으면 현재 커널이 해당 프로토콜과 관련 매개변수를 지원하는지 확인해야 합니다. 클라이언트 UI만 업데이트해도 실행 중인 커널까지 바뀌는 것은 아닙니다.

클라이언트의 ‘정보’ 또는 버전 정보 페이지에서 클라이언트 버전을 기록하세요.
커널 정보 또는 시작 로그에서 커널 이름과 전체 버전 번호를 기록하세요.
해당 버전의 설정 문서를 참고해 오류가 발생한 필드를 확인하세요. 특히 프로토콜 유형과 전송 매개변수를 살펴보세요.
커널에 맞는 구독 형식을 선택하거나 클라이언트에서 공식 제공하는 업데이트 경로로 커널을 업데이트하세요.

type을 삭제하거나 프로토콜 이름을 바꿔 오류를 우회하지 마세요. 프로토콜 유형은 연결 방식을 결정하므로 임의로 바꾸면 구조 검사에는 통과하더라도 실제 연결이 되지 않는 경우가 대부분입니다.

5단계: 가져오기는 성공했지만 노드가 없을 때 참조 관계 확인

노드 목록이 비어 있으면 먼저 구독 원문에 실제 노드가 있는지 확인한 다음, 클라이언트의 최종 설정에도 해당 노드가 남아 있는지 살펴보세요. ‘노드를 다운로드하지 못한 경우’와 ‘노드는 있지만 현재 프록시 그룹에서 참조하지 않는 경우’도 구분해야 합니다.

직접 노드: proxies가 빈 목록인지 확인하세요. 응답 자체가 proxies: []라면 계정 사용 가능 상태와 구독 필터 조건부터 확인해야 합니다.
원격 노드 제공자: proxy-providers의 다운로드 로그를 확인하세요. 기본 설정 다운로드에 성공해도 모든 제공자가 업데이트된 것은 아닙니다.
프록시 그룹 참조: use로 제공자를 참조한다면 이름이 proxy-providers의 키와 일치해야 합니다. proxies로 노드를 참조하는 경우에도 노드 이름이 일치해야 합니다.
필터 조건: 직접 추가한 이름 필터 규칙을 잠시 사용 중지하세요. 정규식, 대소문자 또는 지역 이름이 바뀌면 결과가 노드 0개가 될 수 있습니다.
병합 순서: 오버라이드가 원본 구독의 노드나 프록시 그룹을 빈 목록으로 바꾸지 않았는지 확인하세요. 클라이언트마다 병합 방식이 다르므로 목록이 항상 자동으로 추가된다고 가정하면 안 됩니다.

예를 들어 프록시 그룹에서 use: [공항 노드]를 지정했지만 제공자 이름이 구독 노드라면 두 이름은 자동으로 일치하지 않습니다. 참조 관계를 바로잡은 뒤 해당 제공자를 업데이트하고 로그를 확인하세요. 기본 구독 업데이트 버튼만 연달아 누르지 마세요.

재테스트 순서와 문제 제보 항목

한 번에 조건 하나만 바꿔야 어떤 조정이 효과가 있었는지 알 수 있습니다. 먼저 구독 응답이 정상인지 확인하고, 다음으로 YAML과 커널의 호환성을 확인한 뒤, 마지막으로 오버라이드와 네트워크 트래픽 가로채기 기능을 복구하세요. 아래 순서로 다시 테스트하면 DNS, 포트, TUN을 한꺼번에 바꾸는 것보다 문제를 찾기 쉽습니다.

테스트용 구독에 원본 링크를 가져오고 개인 오버라이드를 사용 중지한 다음 한 번 업데이트하세요.
로그에 다운로드 또는 파싱 오류가 없는지 확인하고 노드 수와 프록시 그룹 내용을 살펴보세요.
실제로 사용할 노드를 하나 선택한 다음 지연 시간을 테스트하세요. 테스트 실패는 이후 연결 문제에 해당하며 구독 파싱 실패와는 다릅니다.
필요에 따라 시스템 프록시를 다시 켜고 브라우저 접속을 확인하세요. TUN이 필요하다면 별도로 활성화한 다음 대상 앱에서 확인하세요.
사용자 지정 규칙, 오버라이드, 필터 설정을 하나씩 복구하세요. 변경 내용을 저장할 때마다 커널이 정상적으로 설정을 불러오는지 확인해야 합니다.

서비스 제공자나 클라이언트 프로젝트에 문의할 때는 Windows 버전, 클라이언트 버전, 커널 이름과 버전, 실패 시각, HTTP 상태 코드, 전체 오류 유형, ‘원본 구독만으로 로드되는지 여부’를 함께 전달하세요. YAML 문제라면 계층 구조를 유지한 비식별화 조각과 원본 줄 번호를 제공할 수 있습니다.

구독 토큰, 서버 비밀번호, UUID, 전체 노드 주소 또는 전체 응답 파일을 공개하지 마세요. 링크가 이미 유출됐다면 제공자 사이트에서 먼저 토큰을 재설정한 뒤 클라이언트의 구독 주소를 바꾸세요. 가져오기에 성공한 뒤 확인할 사항은 구독 가져오기 안내와 연결 확인 안내에서 이어서 확인할 수 있습니다.