2026-08-29 문제 해결 예상 읽기 시간 12분

Clash 구독 업데이트 실패·파싱 오류 해결: URL 형식, User-Agent, YAML 점검 가이드

구독을 가져오지 못하거나 가져온 뒤 노드가 비어 있고 파싱 오류가 표시된다면 URL, 요청 헤더, 응답 형식, YAML 들여쓰기를 차례로 확인하세요.

1. 오류 단계 구분: 실패한 지점부터 기록하기

현재 작동하는 설정은 그대로 보관한 뒤 구독을 한 번 직접 업데이트하고, 업데이트 시간과 전체 오류 내용을 기록하세요. 구독 업데이트는 도메인 확인, HTTPS 연결, HTTP 응답, 콘텐츠 파싱, 설정 로드 순으로 진행됩니다. 앞 단계에서 실패했다면 뒤 단계의 규칙을 수정해도 대개 해결되지 않습니다.

데스크톱 클라이언트에서는 구독 또는 설정 목록을 열어 업데이트 대상 항목을 확인한 다음 앱 로그나 코어 로그를 살펴보세요. 화면에 표시되는 항목 이름은 클라이언트마다 다를 수 있습니다. ‘설정 파일 업데이트 성공’과 ‘노드 제공자 업데이트 성공’을 같은 의미로 보면 안 됩니다. 두 항목은 서로 다른 주소와 별도 캐시를 사용할 수 있습니다.

오류 또는 증상	우선 확인할 항목	다음 조치
`no such host`	구독 도메인 확인	시스템 DNS와 현재 네트워크 확인
`connection refused`	대상 포트 또는 로컬 프록시 포트	오류에 표시된 호스트와 포트 확인
`401`、`403`	권한, 접근 정책, 요청 헤더	구독 URL을 다시 발급받고 응답 본문 확인
`429`	요청 빈도 제한	연속 재시도를 멈추고 서버가 안내하는 재시도 시간 준수
`yaml:` 또는 `unmarshal`	응답 형식, 필드 유형, 들여쓰기	원본 응답을 저장해 로컬에서 확인
업데이트는 성공했지만 노드가 비어 있음	설정 유형, 제공자, 필터 조건	전체 설정과 노드 목록 구분

2. URL 형식: 원본 구독 URL을 복사하고 로그인 페이지는 사용하지 않기

서비스 제공자 페이지에서 다시 복사

서비스 제공자 계정에 로그인한 뒤 Clash 또는 현재 코어와 호환된다고 명시된 구독 형식을 선택하세요.
링크 복사 기능을 사용하세요. 메신저에서 잘려 보이는 미리보기 주소를 이어 붙이지 마세요.
URL이 https://로 시작하는지, 끝에 공백이나 줄바꿈, 한국어 마침표, 닫는 괄호가 붙지 않았는지 확인하세요.
쿼리 매개변수를 모두 유지하세요. ? 뒤의 내용을 임의로 지우거나 &로 구분된 매개변수를 잘라내지 마세요.

웹페이지 소스의 &는 HTML 엔티티 표기이며, 실제 URL에서 매개변수를 구분하는 문자는 &입니다. 복사한 주소에 문자 그대로 &가 들어 있다면 뒤쪽 매개변수 이름이 잘못 처리될 수 있습니다. 직접 바꾸기보다 서비스 제공자 페이지의 복사 버튼으로 URL을 다시 가져오는 편이 안전합니다.

clash:// 같은 주소는 앱에서 가져오기 기능을 실행하는 명령일 수 있으며, 바로 다운로드할 수 있는 HTTPS 구독 URL은 아닙니다. 브라우저 주소창의 계정 페이지, 주문 내역, 구독 안내 페이지도 설정 URL로 사용할 수 없습니다. 페이지가 브라우저에서 열린다는 사실만으로 YAML이 응답된다고 볼 수는 없습니다.

로그인 상태와 리디렉션 확인

브라우저에는 로그인 쿠키가 있어 다운로드가 되더라도, 해당 쿠키가 없는 클라이언트는 로그인 페이지나 접근 거부 응답을 받을 수 있습니다. 정상적인 구독 API는 보통 URL 토큰 등 API 인증 방식을 사용합니다. 출처가 불분명한 스크립트에 브라우저 쿠키를 붙여 넣지 말고, 서비스 제공자 안내에 따라 클라이언트에서 사용할 URL을 새로 발급받으세요.

301, 302, 307 응답이 있다면 최종 URL이 예상한 서비스에 속하는지 확인하세요. 로그인 페이지나 인증 페이지, 더 이상 사용되지 않는 도메인으로 리디렉션된다면 YAML 들여쓰기가 아니라 API 접근 문제부터 해결해야 합니다.

3. HTTP 응답: 상태 코드, 응답 헤더, 원본 본문 저장

Linux와 macOS에서는 로컬 터미널에서 curl을 사용할 수 있습니다. Windows PowerShell에서는 예전 환경의 동명 별칭을 피하도록 curl.exe를 명시해 실행하세요. 아래 명령은 URL을 입력받아 전체 구독 주소가 명령 기록에 남지 않도록 합니다. 입력 중 화면에 주소가 표시될 수 있으니 주변도 확인하세요.

# Linux / macOS: 개인 디렉터리에 접근 제한이 적용된 점검 폴더 만들기
mkdir -m 700 subscription-check
cd subscription-check
umask 077
read -r -s -p '구독 HTTPS 주소를 붙여 넣으세요: ' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --dump-header response-headers.txt \
  --output response-body.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

10초는 연결 시간 제한이고 30초는 요청 전체의 제한 시간입니다. 이번 진단에 사용하는 값일 뿐 성능을 보장하지 않습니다. 명령에 --fail을 지정하지 않았으므로 서버가 오류를 반환해도 본문이 저장되어 인증 안내와 설정 데이터를 구분할 수 있습니다. 명령에서 네트워크 오류가 나면 먼저 해당 오류를 해결하세요. HTTP 000은 서버가 000 상태 코드를 보냈다는 뜻이 아닙니다.

200: 응답 본문을 확인하세요. 로그인 페이지, 인증 페이지, 오류 JSON도 200으로 반환될 수 있습니다.
401 / 403: 토큰, 구독 상태, 접근 제한, 응답 안내를 확인하세요. 403만으로 User-Agent 문제라고 단정할 수는 없습니다.
404 / 410: 경로가 만료됐는지, 도메인이 이전됐는지 확인하고 서비스 제공자 페이지에서 URL을 다시 가져오세요.
429: Retry-After가 있다면 안내된 시간만큼 기다리세요. 업데이트 버튼을 반복해서 누르지 마세요.
500 / 502 / 503: 시간과 상태 코드를 기록하고 잠시 후 다시 시도하세요. 클라이언트를 재설치해도 보통 서버 오류는 해결되지 않습니다.

로컬 텍스트 편집기에서 response-body.txt를 여세요. <!DOCTYPE html> 또는 <html로 시작한다면 대개 웹페이지입니다. JSON 오류 객체로 시작하면 먼저 오류 필드를 확인하세요. Content-Type은 참고할 수 있지만, 일부 API는 YAML을 일반 텍스트로 표시하므로 응답 헤더만으로 내용의 유효성을 판단하면 안 됩니다.

4. User-Agent: 근거를 바탕으로 요청 비교하기

일부 구독 API는 User-Agent에 따라 출력 형식을 선택하고, 다른 API는 형식 매개변수를 명시해야 합니다. 브라우저에서는 노드 공유 링크가 반환되고 클라이언트에서는 YAML이 반환된다면 같은 API가 요청에 따라 다른 형식을 제공하는 것일 수 있습니다. 먼저 서비스 제공자가 안내하는 클라이언트 정보를 확인하고 브라우저 식별자를 무작위로 시도하지 마세요.

앞서 시작한 터미널 세션에서 구독 URL을 다시 입력한 다음 아래 명령으로 응답을 비교할 수 있습니다. mihomo는 테스트용 식별자일 뿐 특정 GUI 클라이언트가 실제로 보내는 요청 헤더와 같다고 보장되지 않으며, 모든 API가 이를 인식하는 것도 아닙니다.

read -r -s -p '구독 HTTPS 주소를 붙여 넣으세요: ' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --user-agent 'mihomo' \
  --dump-header response-headers-ua.txt \
  --output response-body-ua.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

두 응답 본문의 최상위 필드와 상태 코드를 비교하세요. 특정 요청 헤더를 지정했을 때만 호환되는 설정이 반환된다면 클라이언트에 ‘구독 요청 User-Agent’ 설정이 있는지 확인하세요. 전체 구독 가져오기와 proxy-providers 다운로드는 서로 다른 경로이므로 한쪽을 수정해도 다른 쪽에 영향을 주지 않을 수 있습니다. 현재 코어 문서에서 지원한다고 명시한 경우에만 해당 제공자 설정에 요청 헤더를 추가하세요.

5. 콘텐츠 형식: 전체 설정, 제공자 파일, 공유 링크를 구분하기

Clash 설정은 모든 종류의 노드 텍스트를 통틀어 부르는 말이 아닙니다. 응답은 보통 세 가지 유형으로 나뉘며, 각 유형에 맞는 위치로 가져와야 합니다. 파일 확장자가 .yaml이라고 해서 내부 구조까지 코어 요구사항에 맞는 것은 아닙니다.

콘텐츠 유형	일반적인 구조	올바른 처리 방법
전체 Clash 설정	`proxies`, `proxy-groups`, `rules` 등의 필드	설정 파일로 가져온 뒤 참조 관계 확인
노드 제공자 파일	일반적으로 최상위 노드 목록이 `proxies:`로 시작	기본 설정의 `proxy-providers`에서 참조
공유 링크 또는 인코딩된 텍스트	`ss://`, `vmess://` 등 또는 Base64로 인코딩된 전체 텍스트	서비스 제공자가 제공하는 Clash 형식을 선택하거나 해당 형식을 명시적으로 지원하는 로컬 가져오기 기능을 사용

전체 설정에서도 proxy-providers를 통해 노드를 가져올 수 있으므로 proxies 목록이 설정에 없을 수도 있습니다. 따라서 내장 목록이 비어 있다고 구독에 노드가 없다고 단정하지 마세요. 제공자 다운로드가 성공했는지, 정책 그룹의 use가 올바른 이름을 참조하는지 확인하세요.

서비스 제공자가 인코딩된 공유 링크만 반환한다면 디코딩한 결과가 Clash 설정이라는 보장은 없습니다. 디코딩한 텍스트의 파일명만 config.yaml로 바꾸지 마세요. 서비스 제공자가 지원하는 형식을 우선 사용하고, 낯선 변환 API에 구독 인증 정보를 넘기지 마세요.

6. YAML 파싱: 첫 번째 오류부터 수정하고 필드 호환성 확인

들여쓰기, 따옴표, 필드 유형

YAML 들여쓰기에는 탭이 아닌 공백을 사용하세요. 같은 깊이의 항목은 들여쓰기를 통일합니다. 예를 들어 한 단계마다 공백 두 개를 사용하세요. ‘18번째 줄 근처에서 파싱 실패’가 표시되면 17번째 줄도 함께 확인하세요. 따옴표나 콜론 누락, 잘못된 들여쓰기는 다음 줄에서야 파서에 감지되는 경우가 많습니다.

콜론: 키와 값 사이에는 반각 :을 사용하고, 뒤에는 보통 공백 하나를 둡니다.
목록: 항목 앞에 반각 -와 공백을 사용하고, 목록을 포함하는 필드에 맞게 들여쓰기하세요.
문자열: 이름에 ‘콜론 뒤 공백’이 들어가면 따옴표로 감싸 매핑 구조로 잘못 인식되지 않도록 하세요.
유형: 포트 등 숫자 필드는 코어 요구사항에 따라 정수로 입력하세요. 불리언 값은 true 또는 false를 사용하고 한국어로 입력하지 마세요.
중복 키: 최상위 rules나 proxy-groups를 두 번 정의하지 마세요. 파서에 따라 오류가 발생하거나 앞서 입력한 값이 덮어써질 수 있습니다.

아래 예시는 정책 그룹과 규칙의 구조만 보여 줍니다. 원격 노드는 포함하지 않으며 구독을 대체할 수 있는 완전한 설정도 아닙니다. 점검할 때 현재 사용 중인 파일을 덮어쓰지 마세요.

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - DIRECT

rules:
  - "DOMAIN-SUFFIX,example.com,수동 선택"
  - "MATCH,수동 선택"

규칙 끝의 정책 이름은 정의된 정책 그룹이나 내장 정책과 일치해야 합니다. 그룹 이름을 ‘수동 선택’에서 다른 이름으로 바꾸면 규칙에서 참조하는 이름도 함께 수정하세요. YAML 문법 검사를 통과했다는 것은 텍스트를 파싱할 수 있다는 뜻일 뿐, 프록시 프로토콜과 필드 조합, 이름 참조까지 유효하다는 뜻은 아닙니다.

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

mihomo는 로컬에서 설정 파일을 테스트할 수 있습니다. 먼저 mihomo -v로 버전을 기록한 뒤 아래 명령을 실행하세요. 파일명은 현재 디렉터리에 저장된 테스트 대상 설정에 맞춰야 합니다.

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

가능하면 GUI 클라이언트가 실제로 사용하는 코어 버전으로 테스트하세요. 별도로 받은 최신 코어로 테스트해 설정을 받아들였더라도 그 결과만으로 앱 내장 코어와의 호환성이 입증되지는 않습니다. 제공자, 규칙 세트, 지리 데이터베이스 같은 외부 의존 항목은 시작 로그도 함께 확인해야 합니다.

특정 프록시 유형이나 필드가 지원되지 않는다는 오류가 표시되면 먼저 구독의 출력 대상을 확인하세요. Clash, Clash Meta(mihomo), 각 파생 버전은 지원하는 설정 기능이 모두 같지 않습니다. 오류를 없애려고 프로토콜에 필요한 필드를 삭제하지 마세요. 호환되는 출력 형식을 사용하거나 클라이언트가 지원하는지 확인한 뒤 코어를 업데이트하세요.

7. 노드가 비어 있거나 네트워크 오류가 날 때: 다운로드와 로드를 따로 확인

업데이트는 성공했는데 목록이 비어 있는 이유는 무엇인가요?

활성 설정 확인: 설정 A를 업데이트했지만 현재 실행 중인 설정은 B일 수 있습니다. 업데이트 후 현재 설정 이름과 로드 로그를 확인하세요.
제공자 확인: 기본 설정 다운로드가 성공해도 DNS, 인증, 네트워크 문제로 노드 제공자 다운로드는 실패할 수 있습니다.
필터 확인: filter, exclude-filter, 화면 검색 조건으로 모든 노드가 제외됐을 수 있습니다. 사본에서 필터를 제거하고 결과를 확인하세요.
정책 그룹 참조 확인: 제공자 이름은 정책 그룹의 use와 일치해야 합니다. 제공자를 선언했다고 해서 모든 정책 그룹에 해당 노드가 표시되는 것은 아닙니다.
목록이 비어 있는 경우와 연결 테스트 시간 초과 구분: 노드는 표시되지만 지연 시간 테스트에 실패했다면 연결 또는 테스트 경로 문제입니다. ‘구독에서 노드를 가져오지 못한’ 상황과는 다릅니다.

시스템 프록시, TUN, 로컬 포트

구독 요청이 프록시를 통과하는지는 클라이언트의 업데이트 설정과 실행 환경에 따라 달라집니다. 시스템 프록시를 켜도 백그라운드 업데이트 프로그램이 이를 사용한다고 보장할 수 없습니다. TUN을 켜도 만료된 토큰이나 잘못된 YAML은 해결되지 않습니다. 요청이 직접 연결되는지 기존 프록시를 사용하는지 먼저 확인하고 설정은 한 번에 하나씩만 변경하세요.

오류에 127.0.0.1:7890이 표시되면 실제 수신 포트가 7890인지, 코어가 실행 중인지 확인하세요. 7890은 흔히 쓰이는 예시일 뿐 모든 클라이언트의 고정 포트는 아닙니다. 코어가 시작되지 않았는데 업데이트 프로그램이 이 로컬 프록시를 계속 사용하면 ‘설정은 로드되지 않고 구독도 가져오지 못하는’ 상황이 반복될 수 있습니다. 클라이언트에서 지원한다면 일시적으로 직접 연결해 업데이트하고, 복구할 수 있도록 기존 설정은 보관하세요.

x509, 인증서 만료 또는 인증서 유효 기간 시작 전 오류가 나면 먼저 시스템 날짜와 시간, 시간대를 동기화하세요. 그런 다음 웹 로그인이 필요한 공용 네트워크인지 확인합니다. 인증서 검증을 끄는 방법을 장기 해결책으로 삼지 마세요. DNS 오류가 나면 시스템 DNS 확인과 구독 도메인 확인부터 진행하세요. DNS, TUN, 규칙, 노드 프로토콜을 한꺼번에 크게 바꾸면 어떤 변경이 효과가 있었는지 파악하기 어렵습니다.

8. 복구 확인: 두 번 연속 검증한 뒤 자동 업데이트 재개

구독을 한 번 직접 업데이트하고 응답 본문이 예상한 설정인지, 로그인 페이지나 API 오류가 아닌지 확인하세요.
설정을 로드한 뒤 파싱 오류가 없는지, 제공자 다운로드가 완료되는지, 정책 그룹에 예상한 노드가 표시되는지 로그에서 확인하세요.
노드를 하나 선택해 정상적으로 연결되는지 확인하세요. 노드 사용 가능 여부와 구독 업데이트 결과를 각각 기록하고, 하나의 ‘성공’ 상태로 모든 검증을 대신하지 마세요.
적당한 시간을 두고 다시 업데이트해 오래된 캐시 덕분에 일시적으로 성공한 것이 아닌지 확인한 뒤 기존 자동 업데이트 주기를 복구하세요.

문제가 계속되면 서비스 제공자에게 클라이언트 이름, 실제 코어 버전, 운영체제, 오류 발생 시간, HTTP 상태 코드, 민감 정보를 가린 오류 행을 전달하세요. 전체 토큰, 노드 비밀번호, 원본 설정 전체를 보내지 마세요. 로컬 점검 파일을 삭제하기 전에 인증 정보가 포함되지 않은 결론만 보관하세요. 응답 헤더에도 쿠키나 토큰이 포함된 리디렉션 URL이 들어갈 수 있으므로 민감 정보로 취급해야 합니다.

클라이언트를 다시 선택하려면 클라이언트 비교를 확인하세요. 규칙, 정책 그룹, 제공자의 차이가 궁금하다면 개념 빠른 참조를 살펴보세요. 복구 순서는 그대로 유지하세요. URL 확인, 응답 확인, 형식 호환성 확인, 설정 로드 확인, 마지막으로 연결 테스트입니다.