Clash 구독 업데이트 실패 해결법: 파싱 오류·만료된 링크·User-Agent 점검 가이드

먼저 요청 실패인지 설정 파싱 실패인지 구분하기

Clash 구독 업데이트는 보통 세 단계로 진행됩니다. 클라이언트가 구독 주소에 요청을 보내고, 응답 내용을 읽은 뒤, 설정 처리 과정과 코어에서 확인합니다. 어느 단계에서든 실패하면 화면에 ‘업데이트 실패’가 표시될 수 있습니다. 따라서 먼저 재설치하기보다 클라이언트의 구독 상세 정보와 로그를 열어 전체 오류 메시지, 발생 시각, 현재 사용 중인 코어를 기록하세요.

같은 구독 주소라도 브라우저, 클라이언트, 명령줄에서 서로 다른 내용이 반환될 수 있습니다. 브라우저에서 열린다는 것은 해당 요청에 응답이 있었다는 뜻일 뿐, Clash에서 사용할 수 있는 설정이 반환됐다는 의미는 아닙니다. 이미 가져온 노드로 계속 연결된다고 해도 기존 설정이 작동한다는 뜻이지, 구독 API가 정상이라는 뜻은 아닙니다.

로그 또는 응답	일반적인 의미	우선 점검 항목
`timeout`、`connection refused`	요청이 정상적으로 완료되지 않음	네트워크 경로, 프록시 포트, 서비스 상태
`401`、`403`	인증 또는 접근 정책에 의해 거부됨	구독 토큰, 계정 상태, 요청 헤더
`404`、`410`	주소가 없거나 리소스가 취소됨	현재 구독 경로와 링크가 재설정됐는지
`429`	요청 빈도 제한	자동 업데이트 주기와 재시도 횟수
`yaml: line …`	본문을 예상한 형식으로 파싱할 수 없음	응답 형식, 들여쓰기, 특수 문자
`unsupported proxy type`	코어에서 특정 노드 유형을 지원하지 않음	코어 버전과 구독 출력 대상

링크 만료·계정 문제·HTTP 상태 코드

현재 구독 주소를 다시 복사하기

구독 서비스 계정 페이지에서 요금제 상태, 유효 기간, 남은 트래픽을 확인한 뒤 현재 구독 메뉴에서 Clash 또는 mihomo용 주소를 복사하세요. 요금제 만료, 토큰 재설정, API 이전, 트래픽 소진은 응답에 영향을 줄 수 있습니다. 구체적인 동작은 서비스 제공업체에 따라 다르므로 상태 코드 하나만으로 계정 만료를 단정할 수 없습니다.

복사한 주소의 앞뒤를 확인해 줄바꿈, 공백, 따옴표, 메신저가 덧붙인 문장 부호가 들어가지 않도록 하세요.
쿼리 매개변수를 모두 보존하세요. ‘링크를 간단하게 만든다’며 물음표 뒤의 내용을 삭제하지 마세요.
웹페이지 소스에서 주소를 복사했다면 &는 HTML 표기입니다. 실제 링크에서 매개변수를 구분하는 문자는 &입니다.
계정에서 구독 토큰을 재설정했다면 기존 주소가 바로 만료될 수 있습니다. 기존 구독 항목의 주소를 수정하고 같은 이름의 설정이 여러 개 생기지 않도록 하세요.

업데이트 버튼을 연속으로 누르지 말고 상태 코드에 맞게 대응하기

401은 인증 정보가 없거나 만료된 경우가 많습니다. 403은 접근 제한, 이상 요청 탐지, 요청 헤더 정책으로 발생할 수도 있고, 404는 API 경로가 변경된 경우일 수 있습니다. 429가 표시되면 서버의 Retry-After 안내에 따라 기다리세요. 안내가 없다면 자동 업데이트를 잠시 중지한 뒤 제공업체에 문의하세요. 계속 재시도해도 요청만 늘어날 뿐 토큰 문제는 해결되지 않습니다.

500, 502, 503은 서버나 게이트웨이 상태를 우선 확인해야 합니다. 오류가 발생한 시각을 기록하고 잠시 기다렸다가 다시 시도하세요. 304는 캐시 협상의 정상 결과일 수 있으므로 무조건 실패로 볼 수 없습니다. 클라이언트가 기존 내용을 올바르게 유지하는지 함께 확인하세요.

요청 시간 초과: 구독 다운로드의 네트워크 경로 확인

시스템 프록시, TUN, 구독 다운로드는 서로 연관되어 있지만 같은 기능은 아닙니다. 클라이언트가 설정을 직접 다운로드하는 경우도 있고, ‘프록시를 통해 업데이트’ 옵션을 제공하는 경우도 있습니다. 코어의 프록시 제공자는 별도 업데이트 설정을 사용할 수도 있습니다. 화면에 업데이트 실패가 표시돼도 브라우저와 같은 경로를 사용한다고 단정하지 마세요.

같은 네트워크에서 실패 로그를 한 번 기록하고 DNS 조회 실패, TCP 연결 실패, TLS 오류, 응답 읽기 시간 초과를 구분하세요.
클라이언트에서 실제로 수신 중인 로컬 프록시 포트를 확인하세요. 오래된 안내를 그대로 따라 하지 마세요. 아래 명령은 127.0.0.1:7890이 실제 HTTP 또는 혼합 프록시 포트인 경우에만 사용할 수 있습니다.
사용 가능한 기존 설정은 보존하고, 직접 연결과 기존 설정을 통한 요청을 각각 테스트하세요. 한 번에 한 가지 조건만 바꾸세요.
네트워크를 바꾼 뒤 문제가 해결됐다면 노드 비밀번호를 바꾸지 말고 기존 네트워크의 DNS, 게이트웨이 제한, 보안 소프트웨어를 확인하세요.

curl로 응답 비교하기

아래 명령은 Linux 또는 macOS의 Bash에서 사용합니다. 주소는 숨김 입력으로 받아 셸 기록에 남지 않도록 했지만, 입력하는 기기의 보안 환경에도 유의하세요. 연결 대기는 10초, 전체 요청 제한은 30초이며 응답 헤더와 본문은 로컬 파일에 각각 저장됩니다. Windows에서는 curl.exe를 사용할 수 있지만, 변수 입력 문법은 사용하는 터미널에 맞게 조정해야 합니다.

read -r -s -p '구독 주소: ' SUB_URL
printf '\n'

curl --noproxy '*' --connect-timeout 10 --max-time 30 \
  -D subscription.headers -o subscription.body "$SUB_URL"

curl --noproxy '' --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 30 \
  -D subscription-proxy.headers -o subscription-proxy.body "$SUB_URL"

unset SUB_URL

여기서 ‘직접 연결’은 curl에 명시적인 프록시를 사용하지 않는다는 뜻입니다. 시스템에서 TUN을 활성화했다면 연결이 여전히 TUN을 통과할 수 있습니다. 비교 테스트가 필요하면 다른 작업에 영향이 없는지 확인한 뒤 TUN을 잠시 끄고 다시 시도하세요. 301 또는 302가 반환되면 먼저 Location이 가리키는 도메인을 확인하세요. 신뢰할 수 있는 주소임을 확인한 뒤에만 -L로 리디렉션을 따라가세요.

User-Agent: 같은 주소에서 서로 다른 형식이 반환되는 이유

User-Agent는 요청 프로그램을 나타내는 HTTP 요청 헤더입니다. 일부 구독 서비스는 이 값을 기준으로 응답 형식을 선택합니다. 예를 들어 브라우저에는 안내 페이지를, 특정 클라이언트에는 YAML을 반환하거나 인식할 수 없는 요청을 거부할 수 있습니다. 반대로 이 값과 관계없이 전용 주소나 쿼리 매개변수를 사용하는 서비스도 있습니다.

서비스 요구 사항을 먼저 확인한 다음 요청 헤더를 변경하기

구독 서비스의 형식 안내를 확인해 해당 주소가 Clash, Clash Meta(mihomo), 다른 클라이언트 중 무엇을 대상으로 하는지 확인하세요.
클라이언트 이름과 버전, 코어 버전을 각각 기록하세요. 클라이언트 버전과 코어 버전은 별개의 정보이며, 화면에서 클라이언트를 업데이트해도 코어가 함께 업데이트되지 않을 수 있습니다.
클라이언트 로그와 명령줄 응답을 비교하세요. 브라우저에 표시된 로그인 페이지를 구독 본문으로 착각하지 마세요.
제공업체가 특정 User-Agent를 명시적으로 요구할 때만 클라이언트의 구독 요청 설정에 해당 값을 입력하세요. 메뉴 이름은 클라이언트마다 다릅니다.

예를 들어 제공업체가 clash.meta를 명시적으로 요구한다면, 앞서 사용한 curl 요청에 -A 'clash.meta'를 추가해 비교할 수 있습니다. 이 문자열은 일부 서비스에서 사용할 수 있는 값일 뿐, 모든 mihomo 클라이언트의 고정 요청 헤더도 아니고 일반적인 해결 방법도 아닙니다. 요청 헤더를 위장해도 실제 계정 만료나 권한 제한은 우회할 수 없습니다.

User-Agent를 설정 최상위에 임의로 추가해도 클라이언트의 구독 요청이 바뀌지는 않습니다. 클라이언트가 설정 전체를 다운로드하는 과정과 코어가 proxy-providers를 업데이트하는 과정은 서로 다릅니다. 각 구성 요소가 지원하는 설정만 적용됩니다. 요청 헤더를 바꿔 YAML을 받았는데도 클라이언트에서 실패한다면 형식과 코어 호환성을 확인하세요.

HTTP 200인데도 파싱 실패: 응답 본문 확인

200 OK는 HTTP 요청이 성공했다는 뜻이지, 내용이 Clash에서 사용 가능하다는 뜻은 아닙니다. 응답 본문은 로그인 페이지, CAPTCHA 화면, JSON 오류 객체, Base64로 인코딩된 노드 목록, 다른 코어용 설정일 수 있습니다. 먼저 응답 헤더의 Content-Type을 확인하고 로컬에서 본문 앞부분을 살펴보세요. 응답 헤더의 표시가 부정확할 수도 있으므로 최종 판단은 실제 내용에 따라야 합니다.

본문 특징	대응 방법
`<!DOCTYPE html>` 또는 `<html`로 시작	로그인 페이지, 차단 페이지인지 또는 잘못된 메뉴에서 복사했는지 확인
JSON에 오류 코드 또는 오류 메시지가 포함됨	먼저 API 오류를 해결하세요. YAML 설정으로 가져오면 안 됩니다.
`ss://`, `vmess://` 등의 URI가 여러 줄로 나열됨	클라이언트가 변환을 지원하는지 확인하거나 Clash 형식으로 다시 내보내세요.
`proxies:`, `proxy-groups:` 등의 구조가 포함됨	YAML 문법과 필드 호환성을 계속 확인하세요.
`proxies:`와 노드 목록만 있음	노드 제공자 파일일 수 있으므로 올바른 가져오기 메뉴인지 확인하세요.

전체 설정과 노드 제공자 파일은 서로 바꿔 쓸 수 없습니다.

전체 설정에는 보통 프록시 그룹, 규칙, 실행 매개변수가 정의되어 있습니다. proxy-providers의 원격 파일은 주로 노드 목록을 제공합니다. 전체 설정을 노드 목록만 받는 제공자 주소에 입력하거나 노드 목록을 전체 설정처럼 사용하면 파싱 오류가 나거나 정책이 누락될 수 있습니다. rule-providers는 규칙 집합을 가져오는 기능이며 노드 구독 주소가 아닙니다.

Clash Meta는 이후 mihomo로 이름이 바뀌었으며, 원본 Clash와 프로토콜 및 설정 기능이 완전히 같지는 않습니다. 예를 들어 Hysteria2, VLESS 노드는 해당 코어의 지원이 필요합니다. 로그에 지원하지 않는 유형이나 필드가 표시되면 실제로 실행 중인 코어를 확인한 뒤 제공업체 안내에 따라 출력 형식을 선택하세요. type 이름만 바꾼다고 한 프로토콜이 다른 프로토콜로 변환되지는 않습니다.

YAML 들여쓰기 및 설정 참조 오류

yaml: line 12, did not find expected key, cannot unmarshal 오류가 표시되면 지정된 줄과 그 앞뒤 몇 줄을 확인하세요. 파서는 문제를 발견한 위치를 가리키는 경우가 많지만 실제 원인은 바로 윗줄에 있을 수 있습니다. 따옴표 누락, 목록 들여쓰기 불일치, 목록이어야 하는 필드에 문자열을 입력한 경우를 확인하세요.

공백·목록·특수 문자

들여쓰기는 Tab이 아닌 공백을 사용하세요. 같은 단계의 키는 줄을 맞춰야 합니다. 두 칸 들여쓰기는 흔한 규칙일 뿐, 유일하게 허용되는 폭은 아닙니다.
rules는 목록이어야 하며 각 규칙 앞에 -를 붙입니다. 한글·중문에서 쓰는 전각 콜론은 YAML의 영문 콜론을 대신할 수 없습니다.
콜론 뒤 공백이나 샵 기호 등 특수 문자가 포함된 이름은 따옴표로 묶는 것이 좋습니다. 참조하는 이름과 실제 이름도 정확히 일치해야 합니다.
중복 키와 의도치 않게 합쳐진 구간을 확인하세요. 노드를 직접 붙여 넣거나 규칙을 덮어쓰거나 여러 구독을 합친 경우 특히 주의해야 합니다.

아래는 목록과 들여쓰기 구조를 이해하기 위한 직접 연결 설정 예시입니다. 원격 구독은 포함하지 않으며 노드를 복구하는 대안도 아닙니다. 규칙은 이미 정의된 프록시 그룹을 참조하므로 오류가 있는 구조와 일부를 비교해 볼 수 있습니다.

mixed-port: 7890
allow-lan: false
mode: rule

proxy-groups:
  - name: "기본 정책"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,기본 정책

YAML 유효성만 보지 말고 현재 사용 중인 코어로 검사하기

일반 YAML 파서는 문법만 검사할 수 있으며, 코어가 필드와 프로토콜, 정책 참조를 받아들이는지는 확인하지 못합니다. 로컬에서 실제 실행 중인 mihomo 바이너리를 사용해 먼저 버전을 확인한 다음 임시 설정을 테스트하세요:

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

여기서 subscription.yaml은 로컬에 저장된 설정 파일이어야 합니다. 클라이언트 내장 코어가 명령 검색 경로에 없다면 해당 바이너리의 실제 경로를 사용하세요. 외부 제공자 설정을 테스트할 때는 경로와 네트워크 의존성도 고려해야 합니다. proxy not found와 같은 오류가 나면 프록시 그룹에서 참조하는 노드가 존재하는지, 이름이 일치하는지, 노드 제공자가 정상적으로 로드됐는지 확인하세요.

최종 점검 목록: 순서대로 업데이트 복구하기

현재 상태 보존: 사용 가능한 기존 설정을 저장하고 오류 원문, 발생 시각, 클라이언트 버전과 코어 버전을 기록하세요.
계정 확인: 유효 기간, 트래픽, 토큰 상태를 확인한 뒤 계정 페이지에서 올바른 구독 주소를 다시 복사하세요.
요청 확인: HTTP 상태, 리디렉션, 응답 본문을 확인하고 직접 연결과 프록시 요청을 각각 비교하세요.
형식 확인: HTML, JSON, URI 목록, 전체 YAML, 노드 제공자 파일을 구분하세요.
요청 헤더 확인: 제공업체 안내에 따라 User-Agent를 확인하고 추측으로 계속 바꾸지 마세요.
설정 확인: YAML 들여쓰기, 필드 유형, 노드 프로토콜, 프록시 그룹 참조를 점검하세요.
자동 업데이트 복구: 수동 업데이트에 한 번 성공한 뒤 적절한 주기로 자동 업데이트를 다시 켜세요. 같은 구독을 여러 개 만들어 동시에 재시도하지 마세요.

새 구독 항목은 업데이트되는데 기존 항목만 계속 실패한다면 기존 항목에 저장된 주소, 요청 옵션, 덮어쓰기 스크립트, 로컬 캐시를 먼저 확인하세요. 전체 설정을 바로 초기화하지 말고 백업한 다음 클라이언트 문서에 따라 해당 구독 항목만 처리하세요. 여러 기기에서 같은 서버 오류가 발생하면 ‘업데이트할 수 없음’이라고만 문의하기보다 개인정보를 가린 상태 코드, 시각, 본문 오류 정보를 제공업체에 전달하는 편이 원인을 찾는 데 도움이 됩니다.

업데이트 성공 여부는 구독 내용을 가져왔는지, 설정 검사를 통과했는지, 프록시 그룹이 정상적으로 로드됐는지를 모두 확인해야 합니다. 노드 연결은 다음 단계에서 테스트하세요. 구독은 가져왔지만 노드에 연결할 수 없다면 회선, 노드 매개변수, 로컬 프록시 설정을 확인해야 합니다. 관련 개념은 용어집에서 확인하고, 이후 연결 문제는 문제 해결 페이지에서 계속 점검하세요.