Clash 구독 링크 가져오기 오류·파싱 실패? 구독 문제 해결 방법

다운로드 실패, 파싱 실패, 설정 검증 실패를 먼저 구분하세요

Clash 구독 가져오기는 한 단계로 끝나지 않습니다. 클라이언트가 먼저 구독 URL에 요청을 보내 응답 본문을 받은 다음, YAML이나 지원되는 구독 형식으로 파싱하고 마지막으로 코어가 노드, 프록시 그룹, 규칙을 검사합니다. 화면에 같은 ‘가져오기 실패’로 표시되어도 실제 문제 단계는 다를 수 있습니다. 먼저 클라이언트의 ‘로그’를 열어 오류 발생 시각과 처음 나타난 구체적인 오류를 기록한 뒤 수정하세요.

Clash Verge Rev 등 클라이언트의 메뉴 이름은 버전에 따라 달라질 수 있습니다. 일반적으로 ‘구독’ 페이지에서 원격 구독을 추가하고 URL을 입력해 가져옵니다. 기존 구독은 해당 카드의 메뉴에서 ‘업데이트’를 실행하면 됩니다. 문제를 확인할 때는 클라이언트 버전과 코어 버전을 함께 기록하세요. ‘최신 버전’이라고만 적지 마세요. 구형 Clash 코어, Clash Meta(현 mihomo), 기타 호환 구현은 지원하는 설정 항목이 서로 다를 수 있습니다.

로그 또는 증상	먼저 확인할 항목	다음 단계
`timeout`, `lookup`, TLS 오류	네트워크, DNS, 인증서	먼저 정상 응답을 받으세요. YAML은 그다음에 확인합니다.
HTTP 401、403、404	권한, URL, 서버 상태	계정 페이지와 구독 메뉴 확인
`yaml: line 12` 같은 줄 번호 안내	응답 본문과 YAML 문법	오류가 표시된 줄과 그 위 몇 줄 확인
지원되지 않는 프록시 유형, 존재하지 않는 프록시 그룹 참조	코어 호환성과 설정 구조	형식을 맞춘 뒤 코어로 검사
가져오기는 성공했지만 노드가 없음	구독 내용, 필터 조건, provider	노드 소스가 실제로 불러와졌는지 확인

1단계: 구독 URL인지 웹페이지 주소인지 확인하세요

서비스 제공업체 계정 페이지에서 Clash, Clash Meta 또는 mihomo용으로 명확히 표시된 구독 메뉴를 선택하세요. 로그인 페이지, 요금제 상세 페이지, 초대 링크는 구독 URL이 아닙니다. 브라우저에서 페이지가 열린다고 해서 코어가 설정 파일로 읽을 수 있는 것은 아닙니다.

URL 전체를 다시 복사하세요. https://로 시작하는지, 끝부분이 메신저에서 잘리지 않았는지, 앞뒤에 공백이나 줄바꿈 또는 한글 문장 부호가 섞이지 않았는지 확인하세요. 계정 페이지의 복사 버튼을 사용하는 것이 좋습니다.
쿼리 매개변수는 그대로 두세요. token, key 등의 매개변수를 임의로 삭제하거나 URL 전체를 다시 퍼센트 인코딩하지 마세요. 매개변수 이름은 서비스 제공업체가 안내한 주소를 기준으로 확인하세요.
이스케이프 문자를 확인하세요. HTML 소스에서 복사하면 매개변수 구분자가 문자 그대로 &로 바뀔 수 있습니다. 일반 URL에서 여러 쿼리 매개변수는 보통 &로 구분합니다. 원래 구독 메뉴에서 다시 복사하고 토큰 내용을 추측해 일괄 치환하지 마세요.
URL이 재설정되었는지 확인하세요. 구독 토큰을 재설정하면 기존 URL은 즉시 사용할 수 없게 될 수 있습니다. 이전 항목에서 계속 ‘업데이트’를 누르지 말고 클라이언트에 저장된 URL을 새 주소로 바꾸세요.

구독 URL에는 계정 인증 정보가 포함될 수 있습니다. 공개 온라인 YAML 검사기, 출처를 알 수 없는 구독 변환 사이트, 공개 문의 게시판에 붙여 넣지 마세요. 서비스 제공업체에 문의해야 한다면 오류 유형과 발생 시각을 먼저 설명하고, 필요한 정보만 비공개 지원 채널로 전달하세요.

2단계: HTTP 상태 코드와 실제 응답 내용을 확인하세요

구독 URL의 유효성을 판단하려면 상태 코드와 본문을 함께 확인해야 합니다. HTTP 200이어도 로그인 페이지, 보안 확인 페이지, JSON 오류 메시지가 반환될 수 있습니다. 반대로 Content-Type: text/plain 응답에 유효한 YAML이 들어 있을 수도 있습니다. 파일 확장자나 응답 헤더, ‘다운로드 성공’ 표시만으로 판단하지 마세요.

응답을 로컬에 저장하고 리디렉션은 자동으로 따라가지 마세요

터미널 사용에 익숙하다면 Bash에서 다음 명령을 실행할 수 있습니다. 입력한 구독 URL은 화면에 표시되지 않으며 응답 헤더와 본문은 현재 디렉터리에 각각 저장됩니다. 먼저 본인만 접근할 수 있는 작업 디렉터리로 이동하세요. 저장된 파일에는 민감한 정보가 포함되므로 업로드하거나 공개 저장소와 동기화하지 마세요. Windows에서는 Bash를 사용할 수 있는 환경을 이용하거나 클라이언트 로그에서 같은 정보를 확인하세요.

umask 077
read -r -s -p '구독 URL 입력: ' SUB_URL
printf '\n'
curl --connect-timeout 10 --max-time 30 \
  --dump-header subscription-headers.txt \
  --output subscription-body.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

여기서 10초는 연결 제한 시간이고 30초는 요청 전체 제한 시간입니다. 실제 성능 측정값이나 클라이언트 기본값이 아닙니다. 명령에는 리디렉션 자동 추적 옵션이 없습니다. 301, 302, 307, 308 응답을 받으면 로컬에서 Location이 서비스 제공업체가 승인한 도메인을 가리키는지 먼저 확인하세요. 리디렉션 대상에 토큰이 들어 있을 수 있으므로 응답 헤더를 그대로 공유하지 마세요. 명령줄 요청은 클라이언트와 다르게 처리될 수 있으므로 비교용으로만 사용하고, 클라이언트에서도 같은 응답이 나온다고 단정하지 마세요.

상태 코드별로 원인을 좁혀 보세요

200: 본문을 계속 확인하세요. <!DOCTYPE html> 또는 <html로 시작한다면 보통 Clash 설정이 아니라 웹페이지입니다.
204 또는 본문 크기가 0바이트: 파싱할 내용이 없습니다. URL과 서버의 구독 생성 상태를 확인하세요. YAML 항목을 덧붙여 문제를 숨기지 마세요.
401, 403: 토큰 만료, 권한 부족, 요청 출처 제한 또는 보안 차단일 수 있습니다. 상태 코드만으로 계정이 만료되었다고 단정할 수는 없습니다.
404, 410: 이전 구독 경로가 변경되거나 폐기되었는지 확인하고 계정 페이지에서 새 URL을 받으세요.
429: 연속으로 재시도하지 마세요. 응답에 Retry-After가 있다면 안내된 시간만큼 기다리세요.
500, 502, 503, 504: 구독 생성 서비스나 상위 게이트웨이 문제일 가능성이 높습니다. 발생 시각을 기록해 서비스 제공업체에 문의하세요.

본문이 vmess://, ss:// 등으로 시작하는 노드 목록이거나 긴 Base64 문자열이라면 일반 구독 형식을 선택했을 수 있습니다. 바로 가져올 수 있는지는 클라이언트에 따라 다르며, 이를 완전한 Clash YAML 설정으로 사용할 수는 없습니다. 서비스 제공업체에서 제공하는 대상 형식을 다시 선택하세요.

3단계: YAML 들여쓰기, 필드 유형, 정책 참조를 확인하세요

응답이 YAML인지 확인한 다음 문법을 검사하세요. YAML은 공백으로 계층을 표현하며 들여쓰기에 탭을 섞으면 안 됩니다. 오류 메시지의 줄 번호는 파서가 문제를 발견한 위치인 경우가 많고, 실제 원인은 바로 윗줄에 있을 수 있습니다. 예를 들어 따옴표가 닫히지 않았거나 콜론 뒤에 공백이 없거나 복사 과정에서 목록 일부가 빠졌을 수 있습니다.

먼저 문법을, 다음으로 설정 내용을 확인하세요

들여쓰기: 같은 계층에는 같은 들여쓰기를 사용하세요. 보통 한 단계에 공백 2개를 씁니다. 목록 항목 앞의 -도 올바른 계층에 있어야 합니다.
특수 문자: 이름이나 비밀번호에 ‘콜론 뒤 공백’, # 등의 문자가 있으면 올바르게 따옴표로 감싸야 합니다. 작은따옴표로 감싼 문자열에 작은따옴표가 들어 있다면 YAML 규칙에 따라 작은따옴표 두 개로 표기하세요.
필드 유형: proxies는 보통 노드 목록, proxy-groups는 프록시 그룹 목록, rules는 규칙 목록입니다. YAML 파싱에 성공해도 필드 유형이 코어의 요구사항에 맞지 않을 수 있습니다.
참조 이름: 규칙과 프록시 그룹에서 참조하는 노드 및 그룹 이름이 실제로 존재하고 서로 일치해야 합니다. 노드 이름만 바꾸고 기존 참조를 남겨 두지 마세요.

아래는 파싱 문제를 분리해 확인하기 위한 최소 직접 연결 설정입니다. 별도의 테스트 파일로 저장하고 실제 구독 설정을 덮어쓰지 마세요. 프록시 노드는 포함되어 있지 않으며 모든 트래픽은 직접 연결됩니다. 테스트를 통과해도 이 기본 설정이 받아들여졌다는 뜻일 뿐, 구독이나 프록시 회선이 복구된 것은 아닙니다.

mixed-port: 7890
mode: rule
log-level: info
proxies: []
proxy-groups:
  - name: DIRECT-TEST
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,DIRECT-TEST

여기서 7890은 예시 혼합 포트일 뿐 모든 클라이언트의 기본값은 아닙니다. 포트 충돌은 보통 코어 실행이나 리스닝에 영향을 주며 원격 응답이 HTML로 바뀌는 원인은 아닙니다. 설정만 테스트할 때는 시스템 프록시 전환, TUN 활성화, DNS 변경도 필요하지 않습니다.

실제 사용하는 코어로 테스트하세요

로컬에 mihomo 실행 파일이 있다면 다음 명령으로 저장한 설정을 검사할 수 있습니다. 클라이언트에서 실제로 사용하는 버전의 코어를 실행하세요. 다른 최신 코어에서 테스트를 통과했다고 해서 구형 코어도 호환된다는 뜻은 아닙니다.

mihomo -v
mihomo -t -f ./profile.yaml

-t는 설정 테스트, -f는 파일 지정을 위한 옵션입니다. 전체 설정에서 원격 provider를 참조하면 초기화나 검사 중에도 리소스를 읽을 수 있습니다. 신뢰할 수 있는 설정과 통제된 환경에서 실행하세요. 테스트 로그에 노드 이름이나 리소스 주소가 포함될 수도 있으므로 그대로 공개하지 않는 것이 좋습니다.

4단계: 코어 형식, provider, 클라이언트 덮어쓰기를 확인하세요

모두 YAML이어도 ‘전체 설정’과 ‘노드 provider 파일’은 다릅니다. proxy-providers에서 사용하는 파일은 보통 proxies 노드 목록만 제공하며, 완전한 실행 설정이 아닙니다. 기본 설정에서 provider를 참조해야 합니다. 반대로 프록시 그룹과 규칙이 포함된 전체 구독을 노드 목록만 받는 입력란에 넣어도 가져오기에 실패할 수 있습니다.

대상 코어를 확인하세요. 서비스 제공업체가 Clash와 Clash Meta/mihomo용 메뉴를 따로 제공한다면 실제 사용하는 코어에 맞는 형식을 선택하세요. 지원되지 않는 프록시 유형이나 필드가 나타나면 지원 여부부터 확인하고 보안 또는 프로토콜 관련 매개변수를 바로 삭제하지 마세요.
추가 다운로드도 확인하세요. 기본 설정을 가져온 뒤에도 proxy-providers와 rule-providers가 리소스를 다운로드해야 할 수 있습니다. 로그에서 실패한 URL의 유형을 확인해 기본 구독 가져오기 실패와 리소스 업데이트 실패를 구분하세요.
참조 관계를 확인하세요. provider를 사용하는 프록시 그룹은 use 등 지원되는 필드로 해당 이름을 참조해야 합니다. 필터 표현식이 모든 노드를 제외해도 그룹에 선택 가능한 노드가 없는 것처럼 보일 수 있습니다.
덮어쓰기 설정을 분리하세요. 새 테스트 항목에서는 개인 병합 설정, 스크립트, 확장 기능의 덮어쓰기를 일시적으로 적용하지 마세요. 원본 구독은 정상인데 최종 설정이 실패한다면 덮어쓰기를 하나씩 다시 적용해 어떤 필드가 문제인지 확인하세요.

5단계: 네트워크 경로와 계정 상태를 확인하세요

로그에 연결 시간 초과, DNS 조회 실패, TLS 인증서 오류가 표시되면 요청 단계부터 확인하세요. 브라우저는 확장 프로그램의 프록시, 캐시, 로그인 세션을 사용할 수 있지만 클라이언트의 구독 업데이트는 다른 네트워크 경로를 사용할 수 있습니다. 결과가 다르다고 해서 URL이 진짜인지 바로 판단할 수는 없습니다.

직접 연결과 이미 작동하는 프록시를 비교하세요. 클라이언트에 구독 다운로드 프록시 옵션이 있다면 각각 테스트하고 결과를 기록하세요. 이미 작동하지 않는 노드를 통해 구독 업데이트를 시도하지 마세요. 사용할 수 있는 회선이 없다면 휴대폰 핫스팟으로 현재 네트워크와 비교해 보세요.
시스템 시간을 확인하세요. 날짜나 시간대가 크게 틀리면 인증서 검증에 문제가 생길 수 있습니다. 먼저 시간을 동기화하고, 오류를 피하려고 TLS 인증서 검증을 끄지 마세요.
DNS와 네트워크 로그인을 확인하세요. 호텔, 학교, 공공 Wi-Fi의 인증 페이지가 요청을 가로막을 수 있습니다. 먼저 네트워크 인증을 완료한 뒤 다시 시도하세요. 응답이 HTML이라는 이유만으로 구독 형식을 바꾸지 마세요.
서비스 제공업체 계정 페이지를 확인하세요. 요금제 이용 기간, 데이터 사용량, 구독 재설정 기록, 점검 공지를 확인하세요. 데이터가 소진된 뒤 오류를 반환할지 노드 목록을 유지할지는 서비스 제공업체마다 다릅니다.

여러 네트워크에서 같은 URL이 동일한 403 또는 고정된 오류 본문을 반환하고 계정 페이지에도 권한 문제가 표시된다면, 클라이언트를 다시 설치하기보다 서비스 제공업체에 문의하는 편이 빠릅니다. 현재 기기에서만 실패한다면 시스템 시간, 프록시 설정, 클라이언트 요청 옵션, 코어 버전을 먼저 비교하세요.

복구 후 확인: 가져오기 성공이 노드 사용 가능을 뜻하지는 않습니다

수정한 뒤 수동 업데이트를 한 번 실행해 로그에 다운로드나 파싱 오류가 더 이상 없는지 확인하세요. 이어서 노드 수, 프록시 그룹 구성원, provider 업데이트 시각을 확인한 다음 노드를 선택해 실제 접속을 테스트하세요. 지연 시간 테스트가 성공해도 해당 테스트 요청만 성공한 것이므로 평소 사용하는 사이트의 연결까지 검증된 것은 아닙니다.

검증된 설정을 백업하고 복구 당시의 클라이언트 및 코어 버전을 기록하세요.
현재 활성화된 항목이 방금 수정한 구독인지 확인하세요. 이전 설정이 계속 실행 중일 수 있습니다.
짧은 시간에 반복 요청해 제한에 걸리지 않도록 기존 자동 업데이트 일정을 복원하세요.
로컬 임시 응답 파일을 삭제하세요. 전체 구독 URL이 공개된 적이 있다면 서비스 제공업체 계정 페이지에서 토큰을 재설정한 뒤 모든 기기의 URL을 업데이트하세요.

문의를 보낼 때는 ‘발생 시각, 클라이언트 버전, 코어 버전, HTTP 상태 코드, 민감 정보를 가린 첫 번째 오류, 다른 네트워크에서도 재현되는지’를 전달하면 충분합니다. 전체 구독 URL, 원본 노드 비밀번호, 응답 본문 전체를 공개 게시물에 올리지 마세요. ‘주소 → 응답 → 문법 → 코어 → 네트워크 및 계정’ 순서로 확인하면 문제가 어느 단계에 있는지 파악한 뒤 URL 업데이트, 설정 수정, 서버 복구 대기 중 적절한 조치를 선택할 수 있습니다.