Clash 구독 업데이트 실패 및 설정 파싱 오류 해결 가이드

1. 다운로드 실패, 파싱 실패, 적용 실패를 구분하세요

구독 업데이트는 최소 세 단계를 거칩니다. 클라이언트가 구독 주소에 요청을 보내고, 응답 내용을 읽어 파싱한 다음, 설정을 코어에 전달해 불러옵니다. ‘업데이트 실패’는 어느 단계에서든 발생할 수 있으며, 노드 연결 실패는 설정이 정상적으로 적용된 뒤 생기는 별개의 문제일 수 있습니다. 먼저 실패한 단계를 확인한 뒤 네트워크, 파일 또는 코어를 점검하세요. DNS, 포트, 규칙을 한꺼번에 바꾸지 않는 것이 좋습니다.

현재 사용 중인 설정을 보존하세요: ‘설정’ 페이지에서 선택된 설정을 확인하고 로컬 설정과 오버라이드 파일을 먼저 백업하세요. 테스트를 위해 유일하게 사용 가능한 구독을 삭제하지 마세요.
수동 업데이트는 한 번만 하세요: 업데이트를 누른 시간을 기록한 다음 ‘로그’를 열어 해당 시각 전후의 첫 오류를 찾으세요. 마지막에 표시되는 ‘업데이트 실패’는 대개 결과일 뿐입니다.
실행 환경을 기록하세요: ‘설정’ → ‘정보’ 또는 클라이언트 버전 정보 페이지에서 클라이언트 이름, 버전, 코어 버전을 확인하세요. 메뉴 구성은 클라이언트마다 다르며 그래픽 클라이언트 버전과 mihomo 코어 버전은 서로 다릅니다.
실패 범위를 확인하세요: 구독 하나만 실패하는지, 모든 구독이 실패하는지, 아니면 특정 proxy-providers만 업데이트되지 않는지에 따라 점검 방법이 달라집니다.

로그 단서	우선 확인할 항목	당장은 피할 작업
`no such host`	구독 도메인 조회, 네트워크 DNS	YAML 들여쓰기 변경
`timeout`、`connection refused`	요청 경로, 프록시 진입점, 서버 연결 가능 여부	반복해서 삭제하고 다시 가져오기
HTTP 401、403、429	인증 상태, 접근 제한, 업데이트 빈도	업데이트 버튼 연속 클릭
`yaml`、`unmarshal`	응답 본문, 필드 형식, 행 번호	노드가 작동하지 않는다고 단정하기
`unsupported`、`not found`	프로토콜 지원 여부, 정책 이름, 참조 관계	파일이 열리기만 하면 유효하다고 판단하기

2. 구독 링크와 HTTP 응답 내용 확인

서비스 관리 페이지에서 전용 구독 주소를 다시 복사하세요

서비스 관리 페이지에 로그인한 뒤 구독 메뉴에서 Clash 또는 Mihomo 형식을 선택하고 전체 링크를 다시 복사하세요. 브라우저 주소창의 계정 페이지 주소나 QR 코드 이미지 주소를 구독 주소로 사용하면 안 됩니다. 링크의 ? 뒤에 있는 쿼리 매개변수에는 인증 정보가 들어가는 경우가 많습니다. 일부가 빠지면 로그인 페이지나 권한 오류가 반환될 수 있습니다.

관리 페이지에서 ‘구독 링크 초기화’ 또는 ‘토큰 초기화’를 했다면 기존 주소가 즉시 만료될 수 있습니다. 이전 주소로 계속 요청하지 말고 기존 설정의 구독 주소를 새 링크로 바꾸세요. 계정이 만료된 경우 안내 페이지가 반환될 수도 있으니 관리 페이지의 표시와 HTTP 응답을 함께 확인하세요. 모든 403 응답을 만료로 단정해서는 안 됩니다.

401: 대개 인증 문제입니다. 토큰과 서버가 요구하는 인증 방식을 확인하세요.
403: 권한, 접근 출처 제한 또는 보안 정책에 의해 거부됐을 수 있습니다. 응답 본문도 함께 확인하세요.
404: 경로가 올바른지, 링크가 변경되지 않았는지 확인하세요. 일부 서비스는 유효하지 않은 주소를 숨기기 위해 이 상태 코드를 사용하기도 합니다.
429: 요청이 너무 잦다는 뜻입니다. 업데이트를 반복하지 말고 서버 안내 또는 Retry-After에 따라 기다리세요.
5xx: 서버나 중간 게이트웨이 오류일 가능성이 큽니다. 현재 설정을 보존하고 잠시 후 다시 시도하세요.

HTTP 200이어도 사용할 수 있는 설정이 반환된 것은 아닙니다

성공 상태 코드는 서버가 응답을 반환했다는 뜻일 뿐입니다. 본문이 <!DOCTYPE html> 또는 <html>로 시작한다면 웹페이지, 로그인 페이지 또는 인증 페이지일 가능성이 큽니다. ss://, vmess:// 같은 공유 링크만 있거나 Base64 텍스트만 길게 반환된다면 현재 클라이언트가 가져오는 데 필요한 전체 YAML 설정이 아닐 수 있습니다.

브라우저에서는 다운로드되지만 클라이언트에서 실패한다면 요청 방식의 차이도 고려해야 합니다. 브라우저는 로그인 쿠키를 포함하거나 다른 프록시 경로를 사용할 수 있으며, 서버가 User-Agent에 따라 응답 형식을 다르게 반환할 수도 있습니다. 먼저 서비스 관리 페이지에서 해당 클라이언트용으로 제공하는 메뉴를 이용하세요. 요청 헤더를 임의로 위장하는 것은 피하세요.

3. DNS, 프록시 경로, TLS 오류 점검

구독 요청은 그래픽 클라이언트나 코어에서 전송될 수 있습니다. 설정 파일의 DNS 항목이 그래픽 클라이언트의 자체 업데이트 요청까지 제어한다고 볼 수 없으며, 시스템 프록시를 켜도 업데이트 도구가 반드시 해당 프록시를 사용하는 것은 아닙니다. 구독 설정 메뉴에서 업데이트 방식을 확인하고 ‘직접 업데이트’와 ‘프록시를 통해 업데이트’ 옵션이 있다면 각각 한 번씩 비교 테스트하세요.

사용 가능한 연결 경로부터 확인해 업데이트가 작동하지 않는 설정에 의존하지 않도록 하세요

업데이트에 프록시가 필요한데 현재 설정을 사용할 수 없다면 순환 의존이 발생합니다. 먼저 보존해 둔 사용 가능한 설정으로 전환한 뒤 프록시 업데이트를 시도하세요. 또는 구독 도메인에 직접 연결할 수 있는 네트워크에서 직접 업데이트를 테스트할 수 있습니다. TUN 모드는 트래픽 처리 경로를 바꾸므로 원래 상태를 기록한 뒤 잠시 끄고, 확인된 시스템 프록시나 명시적 프록시를 이용해 한 번에 한 가지씩 테스트하세요.

다음 PowerShell 명령은 주소를 대화형으로 입력해 직접 연결과 로컬 HTTP 프록시를 각각 테스트합니다. 예시 프록시 주소는 127.0.0.1:7890입니다. 클라이언트 설정에 표시된 HTTP 또는 혼합 포트가 실제로 7890일 때만 그대로 사용하세요. SOCKS만 지원하는 포트를 HTTP 프록시처럼 사용하면 안 됩니다.

$subscription = Read-Host "구독 주소를 붙여넣으세요. 로컬에서만 확인하세요"
curl.exe --noproxy "*" --location --connect-timeout 10 --max-time 30 --output NUL --write-out "HTTP %{http_code}\n" "$subscription"
curl.exe --proxy http://127.0.0.1:7890 --noproxy "" --location --connect-timeout 10 --max-time 30 --output NUL --write-out "HTTP %{http_code}\n" "$subscription"
Remove-Variable subscription

여기서 연결 시간 제한은 10초, 전체 요청 시간 제한은 30초이며 속도 측정값이 아닙니다. 명령은 최종 HTTP 상태만 표시하고 응답 본문은 출력하지 않습니다. 000은 서버 상태 코드가 아니므로 curl 오류 메시지도 함께 확인하세요. 대화형 입력을 사용하면 실제 링크가 명령 기록에 직접 남지 않지만, 로컬 프로세스 검사에서 실행 중인 매개변수가 보일 수 있으므로 공유 기기에서는 실행하지 않는 것이 좋습니다.

직접 연결 실패, 프록시 연결 성공: 구독 업데이트가 예상한 프록시 경로를 사용하는지 확인하세요.
직접 연결 성공, 프록시 연결 실패: 로컬 수신 포트, 현재 연결 경로, 업데이트 프록시 설정을 확인하세요.
두 방식 모두 도메인 조회 실패: 먼저 시스템 DNS와 구독 도메인의 유효성을 확인하세요. 설정에 DNS 서버를 임의로 추가하는 것만으로 해결하려 하지 마세요.
x509 또는 인증서 유효기간 오류: 시스템 날짜와 시간대, 인증서 체인, HTTPS 검사 소프트웨어를 확인하세요. 기업 네트워크라면 관리자에게 신뢰 체인 확인을 요청할 수 있습니다.

4. 행 번호를 기준으로 YAML 문법과 필드 형식 수정

로그에 yaml: line 12 같은 오류가 표시된다면 일부 내용을 가져왔지만, 그것이 실제 설정인지는 아직 확인되지 않은 상태입니다. 먼저 HTML 오류 페이지가 아닌지 확인한 다음 로컬 텍스트 편집기에서 오류가 난 행과 앞뒤 3~5행을 살펴보세요. 파서가 표시한 행은 더 이상 읽을 수 없게 된 위치일 수 있습니다. 실제로 빠진 콜론이나 따옴표는 바로 앞 행에 있을 수 있습니다.

자주 발생하는 형식 오류 네 가지를 먼저 확인하세요

들여쓰기 방식 혼용: YAML 들여쓰기에는 공백을 사용하고 Tab은 사용하지 마세요. 같은 단계의 들여쓰기는 일관되게 유지해야 합니다. 목록 항목의 -와 하위 필드의 위치도 맞추세요.
문장 부호 오류: 필드 이름 뒤의 전각 콜론은 반각 :으로 바꾸고, 쉼표와 따옴표가 입력기 때문에 다른 문자로 바뀌지 않았는지 확인하세요.
값 형식 불일치: allow-lan은 불리언 값이어야 하고 mixed-port는 포트 번호여야 합니다. 객체, 목록, 문자열을 서로 바꿔 사용하지 마세요.
특수 문자를 올바르게 인용하지 않음: ‘콜론 뒤에 공백’ 또는 ‘공백 뒤에 샵’이 포함된 문자열은 특히 주의해야 합니다. 주소와 이름은 짝이 맞는 따옴표로 감싸세요.

아래는 구조를 설명하기 위한 최소 설정입니다. 로컬 혼합 프록시 진입점만 제공하고 트래픽은 DIRECT로 보냅니다. 원격 프록시 노드가 없으므로 구독을 대신해 사용하면서 기존 연결 경로를 유지할 수는 없습니다. 활성화해 테스트하면 트래픽은 직접 연결됩니다.

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

proxies: []

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

rules:
  - "MATCH,수동 선택"

로컬 파일은 불러올 수 있지만 구독 파일은 불러오지 못한다면 구독 내용, 병합 스크립트 또는 오버라이드 설정을 계속 확인하세요. 원격 구독을 직접 수정해도 다음 업데이트 때 덮어쓰일 수 있습니다. 먼저 복사본에서 수정 사항을 검증한 뒤 클라이언트의 영구 오버라이드 기능을 사용하거나 구독 제공자에게 원본 파일 수정을 요청하세요.

5. 코어 호환성과 설정 참조 확인

YAML 문법이 올바르다는 것은 내용을 읽을 수 있다는 뜻일 뿐, 코어에서 실행할 수 있다는 의미는 아닙니다. Clash, Clash Meta(현재 mihomo)와 버전별로 지원하는 프로토콜 및 필드가 다릅니다. 오래된 코어에서 지원하지 않는 프록시 유형을 만나면 unsupported proxy type 오류가 발생할 수 있습니다. 일부 알 수 없는 필드는 무시될 수도 있으므로 파싱 오류가 없다고 해서 해당 기능이 적용된 것은 아닙니다.

구체적인 오류에 따라 참조 관계를 확인하세요

지원되지 않는 프록시 유형: 구독을 내보낼 때 선택한 대상과 실제 실행 중인 코어를 확인하세요. 코어와 호환되는 설정을 사용하거나 클라이언트에서 지원하는 방법으로 코어를 업데이트하세요.
정책 또는 프록시가 없음: proxy-groups에서 참조하는 노드와 그룹 이름, 규칙 끝에 지정된 정책 이름을 확인하세요. 이름은 대소문자와 끝 공백까지 일치해야 합니다.
규칙 세트가 없음: 규칙에서 사용하는 RULE-SET 이름에 대응하는 항목이 rule-providers에 정의되어 있는지 확인하세요. 참조만 복사하고 정의를 빠뜨리면 안 됩니다.
시작 시 포트 사용 중 오류: address already in use는 설정을 불러오거나 포트를 수신하는 과정의 문제입니다. 클라이언트 두 개가 동시에 실행 중인지 확인하세요. 구독 토큰을 계속 수정할 필요는 없습니다.

전체 설정과 프로바이더 파일도 구분해야 합니다. 전체 설정에는 proxies, proxy-groups, rules 등이 포함될 수 있습니다. 프록시 프로바이더 파일에는 보통 proxies 목록이 들어 있으며 기본 설정의 proxy-providers에서 참조합니다. 규칙 프로바이더는 선언된 형식에 따라 규칙 내용을 제공하고, YAML 형식에서는 흔히 payload를 사용합니다. 용도가 서로 다르므로 확장자가 모두 .yaml이라는 이유만으로 같은 가져오기 메뉴에 넣으면 안 됩니다.

특정 프로바이더만 오류가 난다면 해당 항목의 URL, 형식, 업데이트 로그부터 확인하세요. 기본 구독 업데이트가 성공해도 모든 프로바이더가 갱신됐다는 뜻은 아닙니다. 클라이언트의 오버라이드, 병합, 스크립트가 최종 설정을 변경할 수도 있습니다. 복사본에서 관련 처리를 잠시 비활성화하고 원본 설정과 최종 실행 설정을 비교하면 어느 단계에서 오류가 생겼는지 파악하는 데 도움이 됩니다.

6. 업데이트 성공 후 새 설정이 실제로 적용됐는지 확인

‘다운로드 완료’와 ‘현재 적용 중’은 서로 다른 상태입니다. ‘설정’ 페이지로 돌아가 현재 선택된 카드, 업데이트 시간, 노드 수를 확인한 다음 ‘프록시’ 페이지에서 정책 그룹 내용이 달라졌는지 살펴보세요. 다운로드에 성공해도 코어 검증에 실패하면 클라이언트가 이전 설정을 계속 사용할 수 있습니다. 업데이트 안내만 보지 말고 로드 로그를 기준으로 판단하세요.

목록에서 이름이 같은 다른 항목이 아니라 현재 사용 중인 구독을 업데이트했는지 확인하세요.
업데이트 후 로드 로그를 살펴보고 이전 설정으로 되돌아갔거나, 포트가 사용 중이거나, 참조가 누락되지 않았는지 확인하세요.
‘프록시’ 페이지에서 사용할 수 있는 정책 그룹을 선택하고 필요하면 노드 하나씩 테스트하세요. 모든 노드의 속도 측정을 구독 다운로드 테스트로 혼동하지 마세요.
브라우저 연결도 되지 않는다면 시스템 프록시, TUN, 규칙 적용 여부를 확인하세요. 이 문제는 더 이상 구독 파싱이 아니라 트래픽 처리 경로나 아웃바운드 연결 문제입니다.

결과를 확인하려고 계속 재시작하거나 자동 업데이트 간격을 지나치게 짧게 설정하지 마세요. 짧은 시간에 요청을 반복하면 429 오류가 발생해 원래 문제를 가릴 수 있습니다. 여러 번 업데이트를 누르기보다 ‘요청 성공 → 검증 성공 → 로드 성공’이 한 번에 완료됐는지 확인하는 편이 정확합니다.

7. 문의 전 준비할 최소 정보

로컬에서 점검해도 해결되지 않으면 구독 제공자나 클라이언트 유지관리자에게 문의하세요. ‘가져오기에 실패합니다’라는 설명만으로는 재현하기 어렵습니다. 아래 정보를 제공하면 상대방이 서버 응답, 클라이언트 요청, 코어 검증 중 어디에서 문제가 생겼는지 구분하는 데 도움이 됩니다.

환경: 운영체제, 클라이언트 전체 버전, 실제 사용 중인 코어 이름과 버전.
시간과 작업: 오류가 발생한 날짜와 시간대, 최초 가져오기·수동 업데이트·자동 업데이트 중 어떤 작업에서 발생했는지.
오류: 관련된 첫 로그, HTTP 상태 코드, 파싱 행 번호와 민감 정보를 가린 오류 주변 내용.
비교 결과: 직접 업데이트와 프록시 업데이트 결과, 다른 구독의 정상 작동 여부.
설정 처리: 오버라이드, 병합 스크립트, 프록시 프로바이더 또는 규칙 프로바이더 사용 여부.