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

다운로드 실패, 파싱 실패, 노드 연결 불가를 먼저 구분하세요

현재 사용할 수 있는 설정은 먼저 보존하고 업데이트 로그를 확인하세요. 구독 업데이트는 응답 다운로드, 설정 파싱, 코어 로드의 세 단계로 진행됩니다. 노드 연결 테스트는 그다음 단계입니다. 이 문제들을 한꺼번에 다루면 링크가 이미 만료됐는데 규칙만 계속 수정하거나, YAML 형식 오류가 있는데 노드만 계속 바꾸게 될 수 있습니다.

ClashX와 mihomo 코어를 사용하는 클라이언트는 메뉴 이름이나 오류 메시지가 다를 수 있습니다. 창 제목만 기록하지 말고 클라이언트 이름과 버전, 코어 이름과 버전을 함께 확인하세요. 클라이언트 외피를 최신 버전으로 업데이트해도 실제 실행 중인 코어까지 바뀌는 것은 아닙니다.

증상 또는 로그 내용	먼저 확인할 항목	지금은 하지 않아도 되는 작업
`timeout`、`no such host`	다운로드 경로, 도메인 조회, 네트워크 연결	YAML 들여쓰기 수정
HTTP 401、403、404	링크 권한, 토큰, 서버 응답 내용	노드 프로토콜 일괄 변경
`yaml: line 12`	응답이 설정 파일인지, 오류 행 주변의 문법	시스템 프록시 포트 변경
`proxy ... not found`	그룹에서 참조하는 이름, 노드 제공자	인증서 검증 끄기
업데이트는 성공했지만 모든 노드가 시간 초과됨	노드 연결, 테스트 주소, 외부 네트워크	구독 파싱 실패라고 바로 단정하기

1단계: 복사한 주소가 유효한 구독 링크인지 확인

접속 경로, 토큰, 요금제 상태 확인

서비스 계정 페이지에서 ‘구독’ 또는 ‘가져오기’ 메뉴를 열고 Clash 또는 mihomo용이라고 명시된 설정 형식을 선택하세요. 계정 로그인 페이지, 결제 페이지, 노드 안내 페이지는 구독 주소가 아닙니다.
주소를 다시 복사한 뒤 앞부분이 https://인지, 끝에 공백이나 줄바꿈 또는 한국어 문장 부호가 붙지 않았는지 확인하세요. 쿼리 문자열은 삭제하지 마세요. 계정 식별이나 출력 형식을 결정하는 매개변수일 수 있습니다.
요금제가 만료되지 않았고 데이터 사용량이 남아 있으며 구독 토큰이 재설정되지 않았는지 확인하세요. 토큰을 재설정했다면 클라이언트에 저장된 기존 주소도 새 주소로 바꿔야 합니다.
QR 코드나 원클릭 가져오기 링크를 받았다면 클라이언트가 해당 가져오기 프로토콜을 지원하는지 확인하세요. 앱을 실행하는 링크와 설정 파일을 직접 반환하는 HTTPS 주소는 서로 다른 방식입니다.

HTTP 401은 인증 실패, 403은 계정 권한·접근 정책·보안 확인 문제, 404는 경로 변경을 뜻하는 경우가 많습니다. 상태 코드는 원인 범위를 좁히는 단서일 뿐, 403만으로 요금제 만료를 단정할 수는 없습니다. 응답 본문과 서비스 계정 상태를 함께 확인하세요.

브라우저에서 열려도 클라이언트에서 업데이트된다는 뜻은 아닙니다

브라우저에는 로그인 쿠키가 있거나 구독 다운로드와 다른 네트워크 경로가 적용될 수 있습니다. 링크를 열었을 때 로그인 양식, 인증 문자 입력 화면, ‘JavaScript를 사용 설정하세요’라는 안내가 나타난다면 클라이언트는 이를 설정 파일로 파싱하지 못할 가능성이 큽니다. 웹페이지 소스를 복사하지 말고 클라이언트가 직접 읽을 수 있는 구독 주소를 찾으세요.

2단계: 구독 다운로드의 네트워크 경로 확인

오류가 도메인 조회, TCP 연결, TLS 핸드셰이크 중 어느 단계에서 발생했는지 먼저 확인하세요. no such host는 도메인 조회 오류, connection refused는 연결 거부를 가리킵니다. certificate has expired나 호스트 이름 불일치는 인증서 문제이며, context deadline exceeded는 앞뒤 로그를 함께 확인해 시간 초과가 발생한 위치를 파악해야 합니다.

도메인 조회 실패: 먼저 시스템이 구독 도메인을 조회할 수 있는지 확인한 다음, 클라이언트가 별도의 DNS를 사용하는지 살펴보세요. 브라우저에서 보안 DNS를 사용한다면 조회 결과가 시스템 DNS 상태를 그대로 반영하지 않을 수 있습니다.
직접 연결 시간 초과: 현재 사용할 수 있는 노드가 있다면 클라이언트에서 지원하는 경우 해당 노드를 통해 구독을 업데이트해 보세요. 업데이트 경로가 끊기지 않도록 기존 설정은 삭제하지 마세요.
프록시를 통한 업데이트 시간 초과: 현재 프록시 노드가 작동하는지 확인하세요. 사용할 수 없는 노드가 업데이트에 필요한 상황이라면 ‘연결하려면 먼저 업데이트해야 하지만 업데이트하려면 먼저 연결해야 하는’ 악순환이 생길 수 있습니다.
TLS 오류: 시스템 날짜와 시간, 시간대를 확인하고 구독 도메인의 인증서가 유효한지 확인하세요. 인증서 검증을 건너뛰는 방법을 장기적인 해결책으로 삼지 마세요.

시스템 프록시, TUN 모드, 구독 다운로드가 반드시 같은 경로를 사용하는 것은 아닙니다. 일부 클라이언트는 앱에서 구독을 다운로드하고, 일부는 코어가 제공자 업데이트를 처리합니다. TUN을 켠 뒤 문제가 사라졌다면 경로가 바뀌었다는 뜻일 뿐, YAML이 올바르다는 증거는 아닙니다. 이를 근거로 모든 사용자에게 TUN을 켜라고 할 수도 없습니다.

로컬 프록시로 재현 가능한 테스트하기

아래 명령은 macOS 또는 Linux의 Bash에서 사용할 수 있습니다. 주소를 대화형으로 입력하면 명령 기록에 직접 남지 않지만, 실행 중에는 로컬 프로세스 인수에 표시될 수 있으므로 신뢰할 수 있는 기기에서만 실행하세요. 응답 파일에도 민감한 정보가 포함되므로 업로드하지 마세요. 먼저 직접 연결로 테스트한 뒤, 사용 가능 여부를 확인한 로컬 혼합 포트와 비교하세요.

umask 077
read -r -s -p '구독 주소 입력: ' SUB_URL
printf '\n'
curl --noproxy '*' --location --connect-timeout 10 --max-time 30 \
  --output subscription-direct.yaml \
  --write-out 'HTTP %{http_code}\n' "$SUB_URL"

curl --noproxy '' --proxy http://127.0.0.1:7890 \
  --location --connect-timeout 10 --max-time 30 \
  --output subscription-proxy.yaml \
  --write-out 'HTTP %{http_code}\n' "$SUB_URL"
unset SUB_URL

7890은 흔히 쓰이는 혼합 포트일 뿐이므로 클라이언트가 실제로 수신 대기 중인 포트로 바꿔야 합니다. 클라이언트가 해당 포트에서 수신 대기하지 않으면 두 번째 명령에서 연결이 거부되어도 구독 서버 문제라고 볼 수 없습니다. 여기서는 --fail을 사용하지 않으므로 HTTP 403 응답도 본문이 파일로 저장될 수 있습니다. HTTP 상태 코드와 파일 내용을 모두 확인하세요.

3단계: 서버가 어떤 형식의 응답을 반환하는지 확인

HTTP 200은 요청이 성공 응답을 받았다는 뜻일 뿐, 응답이 Clash 설정이라는 뜻은 아닙니다. 방금 저장한 파일을 로컬 텍스트 편집기로 열어 처음 몇 줄과 최상위 필드를 확인하세요. 파일 내용에 있는 항목을 직접 실행하지 마세요.

콘텐츠 특징	일반적인 의미	대응 방법
`<!DOCTYPE html>`, 로그인 양식	웹페이지, 인증 페이지 또는 오류 페이지	클라이언트가 직접 읽을 수 있는 구독 주소 다시 발급
`{"error":` 형태의 JSON	API 오류 메시지	오류 원인을 확인하고 권한과 사용량 점검
`ss://`, `vmess://` 등 줄마다 링크가 있는 형식	일반 노드 링크 목록	클라이언트가 지원하는 가져오기 방식이나 올바른 출력 형식 선택
길게 이어진 인코딩 문자열	인코딩된 노드 목록일 수 있음	서비스 제공자에게 형식을 확인하고 YAML로 억지로 가져오지 않기
`proxies:`、`proxy-groups:`	전체 설정 파일 또는 설정 일부일 수 있음	구조와 참조 관계를 계속 확인

전체 설정과 노드 제공자 파일을 혼용하지 마세요

전체 설정에는 보통 프록시, 정책 그룹, 규칙이 포함되며 proxy-providers로 외부 노드를 참조할 수도 있습니다. 노드 제공자 파일은 보통 proxies:로 시작하며 노드만 제공합니다. 노드만 있는 파일을 기본 설정으로 가져오면 노드는 표시되지만 필요한 정책 그룹이 없을 수 있습니다. 반대로 전체 설정을 제공자 파일로 읽으면 형식 오류가 발생할 수 있습니다.

제공자를 사용하는 경우 기본 설정 로드 결과와 제공자 다운로드 로그를 각각 확인하세요. 기본 설정 문법에 문제가 없더라도 원격 제공자가 업데이트에 성공했다는 뜻은 아닙니다. 특정 정책 그룹만 비어 있다면 전체 설정을 바로 초기화하지 말고 해당 그룹의 use, 제공자 상태, 필터 표현식을 먼저 확인하세요.

4단계: 오류 행 번호를 기준으로 YAML과 참조 이름 확인

YAML은 들여쓰기에 민감합니다. 탭 대신 공백을 사용하고 같은 단계의 들여쓰기를 일관되게 유지하세요. 보통 한 단계에 공백 2개를 사용합니다. mapping values are not allowed 또는 did not find expected key 오류가 나오면 오류 행 위쪽 3~5줄을 확인하세요. 실제 원인은 앞줄의 닫히지 않은 따옴표나 잘못된 목록 들여쓰기일 수 있습니다.

최소 설정으로 로드 과정부터 확인

아래는 원격 노드가 없는 최소 설정으로, ‘클라이언트가 어떤 설정도 불러오지 못하는 문제’와 ‘구독 내용 자체의 문제’를 구분하는 데 사용합니다. 직접 연결만 선택할 수 있으며 원격 프록시 연결은 설정하지 않습니다. 별도의 테스트 파일로 저장하고 기존 구독 파일을 덮어쓰지 마세요.

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

proxies: []

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

rules:
  - MATCH,수동 선택

테스트 파일에서 포트 사용 중 오류가 나면 다른 프록시 프로세스를 종료하거나 사용 중이지 않은 포트로 바꾸고 테스트 명령도 함께 수정하세요. 포트 수신 대기 실패는 실행 문제이지 YAML 문법 오류가 아닙니다. 테스트 설정이 정상적으로 로드되면 원래 구독으로 돌아가 차이를 확인하세요.

중점적으로 확인할 구조 문제 4가지

필드 뒤에 공백 누락: mixed-port: 7890처럼 작성하세요. mixed-port:7890도 같은 키-값 구조로 처리될 것이라고 기대하지 마세요.
이름에 따옴표 누락: 노드 이름에 : 또는 # 같은 조합이 들어 있다면 이름 전체를 따옴표로 감싸세요. 문자열 안에 포함된 따옴표도 올바르게 처리해야 합니다.
참조 이름 불일치: 정책 그룹의 노드 이름은 대소문자, 공백, 기호까지 정의된 이름과 정확히 일치해야 합니다. 노드 이름을 바꿨다면 참조하는 곳도 함께 수정하세요.
최상위 필드 중복: 두 설정을 그대로 이어 붙여 proxies:나 rules:가 두 번 나오게 하지 마세요. 파서에 따라 중복 키를 거부하거나 처리 방식이 달라질 수 있으므로 기존 값이 덮어써질 것이라고 기대하면 안 됩니다.

파일 확장자만으로 형식을 판단하지 마세요. config.yaml이라는 이름의 HTML 오류 페이지도 설정 파일이 아닙니다. 이해하지 못하는 필드를 일괄 삭제하는 것도 피하세요. 인증 정보, 전송 계층 매개변수, TLS 설정을 삭제하면 문법 검사는 통과해도 노드가 연결되지 않을 수 있습니다.

5단계: 실제 코어와 프로토콜 호환성 확인

Clash 설정에는 서로 관련은 있지만 완전히 같지는 않은 형식이 여러 가지 있습니다. mihomo 코어가 지원하는 일부 프로토콜과 필드는 구버전 Clash 코어에서 지원되지 않을 수 있습니다. 예를 들어 구독에 type: hysteria2가 있다면 노드 유형 이름을 다른 프로토콜로 바꾸지 말고 현재 실행 중인 코어가 해당 유형을 지원하는지 확인하세요.

클라이언트의 ‘정보’ 화면이나 시작 로그에서 버전을 확인하세요. 화면에 코어 정보가 표시되지 않는다면 로그에서 코어 이름과 버전이 나오는 부분을 찾으세요.
다운로드한 패키지가 운영체제와 아키텍처에 맞는지 확인하고, 다른 설치 경로에 있는 사본이 아니라 현재 실행 중인 클라이언트를 업데이트했는지 확인하세요.
로그에 알 수 없는 프록시 유형이나 지원되지 않는 필드가 명시되어 있다면 서비스 제공자가 지원하는 호환 형식을 선택하거나 해당 기능을 지원하는 클라이언트와 코어를 사용하세요.
오류를 없애려고 reality-opts, tls 등의 연결 매개변수를 삭제하지 마세요. 설정이 받아들여지는 것과 노드가 올바르게 핸드셰이크하는 것은 별개의 문제입니다.

mihomo 내장 검사 명령 사용하기

로컬에 명령줄 버전 mihomo가 설치되어 있다면 터미널에서 저장한 설정을 검사할 수 있습니다. 아래 명령은 실행 파일이 PATH에 있고 테스트 파일이 현재 디렉터리에 있다고 가정합니다. 먼저 버전을 확인한 뒤 설정을 테스트하세요.

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

테스트 결과는 해당 파일과 해당 코어에만 적용됩니다. 그래픽 클라이언트는 덮어쓰기, 설정 병합, 스크립트 처리를 추가로 수행할 수 있으므로 터미널 테스트가 통과해도 클라이언트가 실제로 생성한 실행 설정을 확인해야 합니다. 외부 리소스를 사용하는 설정은 테스트나 이후 로드 과정에서 네트워크 연결이 필요할 수 있습니다. 테스트 통과를 모든 노드가 온라인이라는 뜻으로 해석하지 마세요.

업데이트 성공 후 노드가 비어 있다면 필터와 설정 활성화 상태를 확인하세요

먼저 방금 업데이트한 설정이 현재 선택되어 있는지 확인하세요. 일부 클라이언트에서는 구독 카드를 업데이트하는 작업과 활성 설정을 전환하는 작업이 별도로 진행됩니다. 노드 목록에 변화가 없다면 업데이트 시각, 활성 설정 표시, 로드 로그를 확인하고 요청 빈도 제한에 걸리지 않도록 업데이트 버튼을 연속으로 누르지 마세요.

원본에 노드가 없음: 로컬 파일이 proxies: []이고 다른 유효한 노드 소스도 없다면 서비스 제공자에게 계정 상태와 출력 조건을 문의하세요.
원본에는 노드가 있지만 화면에 표시되지 않음: 이름 검색, 지역 필터, 정규식 필터, 제외 조건이 적용되어 있는지 확인하세요. 먼저 필터를 모두 해제한 뒤 비교하세요.
제공자 그룹만 비어 있음: 정책 그룹의 use가 올바른 제공자 이름을 참조하는지 확인하고 해당 제공자의 마지막 다운로드가 성공했는지 살펴보세요.
가져온 뒤에만 오류가 발생함: 백업을 보존한 상태에서 사용자 지정 덮어쓰기나 병합 규칙을 잠시 끄고 비교하세요. 기본 구독과 추가 설정은 각각 올바르더라도 병합 과정에서 이름이 충돌할 수 있습니다.

노드가 목록에 표시되지만 지연 시간 테스트에서 시간 초과가 난다면 연결 문제를 확인하세요. 테스트 대상에 접근할 수 없거나 노드의 외부 연결에 문제가 있거나 로컬 네트워크에서 차단되어도 시간 초과가 발생할 수 있습니다. 이런 증상만으로 구독 파싱 오류라고 판단할 수는 없습니다. 이 단계에서 YAML 들여쓰기를 계속 바꿔도 대개 도움이 되지 않습니다.

수정 후 검증과 문제 제보에 필요한 기록

한 번에 한 항목만 수정한 뒤 다시 업데이트하고 같은 로그를 확인하세요. DNS, 코어, 구독 주소, 규칙을 한꺼번에 바꾸면 원인을 판단하기 어렵습니다. 수정 후에는 다음 순서대로 점검해 오류 창만 사라진 것은 아닌지 확인하세요.

구독을 한 번 수동 업데이트해 HTTP 요청이 성공하고 업데이트 시각이 바뀌는지 확인하세요.
설정 파싱과 코어 로드가 성공했는지, 노드·정책 그룹·제공자 누락 오류가 없는지 확인하세요.
노드를 하나 선택해 실제 프록시 경로로 HTTPS 페이지에 접속한 뒤 필요한 앱에서도 테스트하세요. 브라우저가 정상이라고 모든 앱이 프록시를 사용한다고 볼 수는 없습니다.
클라이언트를 다시 시작한 뒤에도 올바른 설정이 활성 상태인지 확인하세요. 예약 업데이트를 사용한다면 예약 작업도 한 번 더 실행해 성공 여부를 확인하세요.
문제 해결 과정에서 만든 민감한 응답 파일을 삭제하고 더 이상 필요하지 않은 임시 설정도 정리하세요.

문제 해결 순서는 그대로 따르세요. 먼저 링크가 유효한지 확인하고, 네트워크에서 응답을 가져올 수 있는지 확인한 다음, 응답 형식과 YAML 구조, 코어 호환성을 점검하세요. 포트와 규칙 기초는 사용 설명서에서, 계정 링크와 자동 업데이트 문제는 구독 FAQ에서 더 확인할 수 있습니다.