Clash 구독 만료 및 파싱 실패 자가 점검 목록: 링크 접근성부터 필드 호환성까지

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

클라이언트에 “업데이트 실패”가 표시될 때 문제는 서로 다른 세 단계에서 발생할 수 있습니다. 첫 번째는 HTTPS 요청으로 구독 내용을 가져오는 단계입니다. 두 번째는 응답 내용을 YAML, Base64 노드 목록 또는 다른 형식으로 인식하는 단계입니다. 세 번째는 파싱된 설정을 Clash Meta(mihomo) 커널에 전달해 로드하는 단계입니다. 세 단계의 안내 문구는 비슷한 경우가 많지만, 점검 방향은 완전히 다릅니다.

오류 단계	주요 증상	우선 점검 항목
링크 요청	시간 초과, 403, 404, 연결 재설정	상태 코드, DNS, 시스템 프록시, 구독 만료 여부
콘텐츠 파싱	unexpected token, invalid YAML, 설정이 비어 있음	응답 본문, 들여쓰기, 인코딩, 구독 형식
커널 로드	설정은 다운로드됐지만 전환 시 실패	필드 호환성, 포트 사용 여부, 규칙 세트 및 커널 버전

먼저 전체 오류 문구, 발생 시간, 현재 클라이언트 버전을 기록하세요. 그런 다음 클라이언트 로그를 열고 로그 수준을 일시적으로 “정보” 또는 “디버그”로 설정합니다. Clash Verge Rev 2.x를 예로 들면 「설정」→「로그」에서 이동할 수 있습니다. 클라이언트에 따라 명칭이 다르거나 「설정」→「진단」에 있을 수도 있습니다. 점검이 끝나면 기록이 계속 쌓이지 않도록 일반 로그 수준으로 되돌리세요.

1단계: 구독 링크에서 콘텐츠를 가져올 수 있는지 확인

HTTP 상태 코드와 리디렉션 결과 확인

브라우저의 시크릿 창에서 구독 링크를 여는 방법은 초기 점검에만 활용하세요. 브라우저는 Cookie를 자동으로 전송하거나 리디렉션을 따라가고 다운로드 파일을 표시할 수 있지만, 클라이언트는 별도의 네트워크 요청을 사용합니다. 최종 상태 코드와 응답 헤더를 확인하는 방법이 더 정확합니다. Windows 11에서는 PowerShell에서 아래 명령을 실행할 수 있으며, macOS와 Linux에서는 시스템에 기본 제공되거나 로컬에 설치된 curl을 사용할 수 있습니다.

curl -L --max-redirs 5 --connect-timeout 10 \
  --max-time 30 -D headers.txt \
  -o subscription.txt \
  "https://example.com/api/subscription?token=REDACTED"

-L은 301, 302, 307, 308 리디렉션을 따르게 하고, --max-redirs 5는 리디렉션 횟수를 제한합니다. 연결 시간 초과는 10초, 전체 요청 시간 제한은 30초로 설정됩니다. 명령은 응답 헤더를 headers.txt에, 본문을 subscription.txt에 저장합니다. 테스트할 때는 예시 주소를 로컬에서 바꾸고, 실제 토큰을 공유 스크립트에 입력하지 마세요.

200: 서버가 콘텐츠를 반환했으므로, 본문이 실제 구독 설정인지 계속 확인하세요.
301, 302, 307, 308: 리디렉션이 있습니다. 최종 응답도 리디렉션이면 순환이 발생했을 수 있고, 로그인 페이지로 이동한다면 클라이언트가 대화형 로그인을 완료할 수 없습니다.
401, 403: 토큰 만료, 권한 부족, 출처 제한 또는 요청 정책에 의한 차단입니다.
404, 410: 구독 경로가 폐기됐거나 요금제 이전 후 기존 주소가 중단됐거나, URL이 복사 과정에서 잘렸을 수 있습니다.
429: 요청 빈도가 너무 높습니다. 자동 새로고침을 중지하고 서버 측 제한 시간이 끝난 뒤 다시 시도하세요.
500, 502, 503, 504: 서버 또는 상위 서버에 일시적인 문제가 발생한 상태입니다. 서비스 상태와 잠시 후 재시도한 결과를 함께 확인하세요.

복사 과정에서 URL이 변경되지 않았는지 확인

구독 주소에는 ?, &, =, % 같은 문자가 자주 포함됩니다. 메신저의 줄바꿈, 서식 있는 텍스트 편집기의 이스케이프 처리, 끝부분 문자 수동 삭제로 인해 토큰이 무효화될 수 있습니다. 주소 앞뒤에 따옴표, 전각 공백, 줄바꿈이 없어야 합니다. 서비스 제공업체 콘솔에 “구독 복사” 버튼이 있다면 전체 주소를 다시 복사한 뒤 클라이언트에서 새 설정을 만들고, 기존 항목을 계속 수정하지 마세요.

시스템 시간도 확인해야 합니다. HTTPS 인증서 검증은 로컬 컴퓨터의 시계에 의존하므로 날짜가 며칠만 어긋나도 인증서가 아직 유효하지 않거나 이미 만료됐다는 로그가 남을 수 있습니다. Windows에서는 「설정」→「시간 및 언어」→「날짜 및 시간」에서 자동 시간 설정을 켜고 즉시 동기화하세요. Android에서는 보통 「설정」→「시스템」→「날짜 및 시간」에 있습니다.

시스템 프록시 루프와 현재 노드 문제 배제

구독 요청은 직접 연결로 전송될 수도 있고 시스템 프록시를 사용할 수도 있습니다. 일반적인 로컬 혼합 포트는 7890이며, 일부 클라이언트는 기본값으로 7897을 사용합니다. 정확한 값은 「설정」→「포트 설정」의 Mixed Port를 기준으로 확인하세요. 클라이언트 커널이 이미 중지됐는데 시스템 프록시가 여전히 127.0.0.1:7890을 가리키면 구독 요청은 수신 대기 중인 프로세스가 없는 로컬 포트에 연결하게 됩니다.

클라이언트에서 “시스템 프록시”를 끈 다음 구독을 업데이트해 보세요.
직접 연결로 구독 도메인에 접근할 수 없다면 커널을 다시 시작하고, 사용 가능한 것으로 확인된 노드를 선택한 뒤 업데이트하세요.
TUN 모드를 사용 중이라면 먼저 「설정」→「네트워크 설정」에서 TUN을 끄고 일반 요청을 한 번 실행해 비교하세요.
로그에 connection refused 127.0.0.1, i/o timeout 또는 로컬 포트로 반복 전달되는 기록이 있는지 확인하세요.

TUN 모드 자체는 YAML 문법 파싱에 관여하지 않지만 구독 요청의 라우팅 경로를 바꿉니다. TUN을 끈 뒤에만 업데이트가 성공한다면 라우팅 제외 항목, 시스템 프록시 상태, 현재 노드의 사용 가능 여부를 계속 확인해야 하며 구독 본문을 바로 수정해서는 안 됩니다.

2단계: 반환된 콘텐츠가 실제로 사용 가능한 구독인지 확인

파일 확장자가 아니라 본문 첫 부분을 확인

구독 URL 끝에 .yaml이 없는 경우는 흔하므로 응답 콘텐츠를 기준으로 판단해야 합니다. 앞서 저장한 subscription.txt를 텍스트 편집기로 열고 처음 20줄을 확인하세요. Clash 또는 mihomo용 완전한 YAML 설정에는 보통 proxies, proxy-groups, rules, proxy-providers 같은 최상위 필드가 포함됩니다.

mixed-port: 7890
mode: rule

proxies:
  - name: "Example Node"
    type: ss
    server: 203.0.113.10
    port: 443

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "Example Node"

rules:
  - MATCH,PROXY

본문이 <!doctype html>, <html> 또는 로그인 양식으로 시작한다면 실제로 가져온 것은 웹페이지입니다. {"code":403,"message":"expired"} 같은 JSON 오류 객체도 Clash 설정이 아닙니다. 이 경우 권한 또는 서버 문제를 해결해야 하며 YAML 파일을 수정해도 소용없습니다.

Base64 노드 목록과 공유 링크 식별

문자, 숫자, 더하기 기호, 슬래시, 등호만 포함된 긴 문자열은 Base64로 인코딩된 범용 구독일 수 있습니다. 디코딩하면 보통 줄마다 ss://, trojan://, vmess:// 또는 hysteria2:// 공유 링크가 표시됩니다. 일부 클라이언트는 이러한 링크를 가져올 수 있지만, 이를 완전한 Clash YAML로 로드하면 최상위 타입 오류가 발생하거나 proxies를 찾지 못할 수 있습니다.

먼저 구독 제공업체 콘솔로 돌아가 Clash, Clash Meta 또는 mihomo로 표시된 출력 형식을 선택하세요. 형식 변환에는 노드 인증 정보가 포함될 수 있으므로 직접 관리하는 로컬 도구나 신뢰할 수 있는 서버 API를 사용해야 합니다. 변환 후에도 프록시 그룹, 규칙, DNS 설정을 확인하세요. 노드 목록은 연결 매개변수만 설명할 뿐 완전한 트래픽 분할 설정과 같지 않습니다.

문자 인코딩과 파일 시작 부분 확인

YAML 파일은 UTF-8로 저장하는 것이 좋습니다. 텍스트 편집기에 깨진 문자가 많이 표시되거나 로그에 제어 문자 관련 오류가 나타나면 UTF-8로 다시 내보내세요. 파일 시작 부분의 UTF-8 BOM은 일반적으로 최신 파서에서 처리되지만, 일부 구형 클라이언트나 외부 변환 스크립트는 이를 필드의 일부로 인식할 수 있습니다. 점검할 때는 파일을 “UTF-8”로 다른 이름으로 저장하고, 비교용 원본 사본은 보관하세요.

3단계: YAML 문법 및 구조 오류를 줄 단위로 확인

먼저 로그에 표시된 행 번호와 열 번호 확인

대표적인 오류로는 did not find expected key, mapping values are not allowed, cannot unmarshal, duplicate key가 있습니다. 로그의 행 번호는 보통 파서가 구조를 잃은 지점을 가리키며, 실제 오류는 그보다 한두 줄에서 세 줄 앞에 있을 수 있습니다. 오류가 난 줄, 이전 항목의 들여쓰기, 따옴표의 짝이 맞는지 함께 확인하세요.

공백으로 들여쓰고 Tab과 공백을 섞어 쓰지 마세요.
같은 단계에서는 들여쓰기를 일관되게 유지하세요. 각 단계마다 공백 두 칸을 사용하는 방식이 일반적입니다.
목록 항목의 하이픈 뒤에는 공백을 넣어야 합니다. 예: - name: node-a
이름에 콜론, 샵, 중괄호 또는 앞뒤 공백이 포함되면 따옴표로 감싸세요.
포트는 port: 443처럼 정수로 작성하고, 불필요한 문자가 포함된 값으로 작성하지 마세요.

# 오류: proxy-groups가 proxies 항목 내부로 들여쓰기됨
proxies:
  - name: node-a
    type: ss
  proxy-groups:
    - name: PROXY

# 올바름: 두 필드가 모두 최상위에 위치함
proxies:
  - name: node-a
    type: ss

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - node-a

문법이 올바른지와 필드 타입이 올바른지 구분

YAML 문법 검사를 통과했다고 해서 커널이 모든 필드를 허용하는 것은 아닙니다. 예를 들어 port: "443"은 YAML에서 문자열이며, 프로토콜 설정에는 보통 정수가 필요합니다. udp: "true"도 문자열이고, 올바른 값은 불리언 true입니다. 로그에 cannot unmarshal string into Go value가 표시되면 값의 타입을 중점적으로 확인하세요.

필드	일반적으로 올바른 타입	자주 잘못 작성하는 형태
`port`	정수	`"443 tcp"`
`udp`	불리언	`"true"`
`proxies`	목록	쉼표로 구분한 단일 문자열
`nameserver`	목록	들여쓰기가 잘못된 매핑 객체
`interval`	초 단위 정수	`24h`

프록시 그룹 참조와 규칙 대상 확인

문법 파싱이 끝나면 커널은 참조 관계도 검사합니다. 규칙 끝의 정책 이름은 기존 프록시 그룹, 프록시 이름 또는 내장 동작과 일치해야 합니다. 예를 들어 규칙이 DOMAIN-SUFFIX,example.com,Proxy인데 설정에는 PROXY라는 그룹만 있다면 대소문자 차이로 대상을 찾지 못합니다. 프록시 그룹의 노드 이름도 proxies 또는 use의 참조와 일치해야 합니다.

RULE-SET을 사용할 때는 해당 이름이 rule-providers에 정의되어 있는지도 확인하세요. provider의 behavior는 콘텐츠와 일치해야 합니다. 도메인 모음은 보통 domain, IP 대역 모음은 ipcidr, 완전한 규칙 문장을 포함한 모음은 classical을 사용합니다. 원격 규칙 세트 다운로드가 실패해도 기본 구독 자체는 이미 파싱됐을 수 있으며, 로그에는 provider의 URL, 상태 코드 또는 시간 초과 정보가 별도로 표시됩니다.

4단계: Clash Meta 커널 버전과 필드 호환성 확인

클라이언트 UI 버전과 커널 버전은 별도로 확인해야 합니다

데스크톱 클라이언트, 모바일 클라이언트, mihomo 커널은 각각 독립적인 버전을 가집니다. UI를 업그레이드해도 커널이 함께 전환된다는 보장은 없습니다. 같은 구독이 두 기기에서 다르게 작동하는 원인도 커널 버전 차이인 경우가 많습니다. 「설정」→「정보」 또는 「설정」→「커널」에서 전체 버전 정보를 기록하세요. 점검 기록에는 최소한 클라이언트 이름, 클라이언트 버전, 커널 종류, 커널 버전을 적어야 합니다. 예: “Clash Verge Rev 2.x, mihomo 1.19.x”.

최신 프로토콜과 전송 필드는 해당 커널의 지원 여부에 따라 달라집니다. 설정에 type: hysteria2, type: tuic, VLESS Reality, WireGuard 또는 새로운 DNS 필드가 포함되면 구버전 Clash 커널에서 알 수 없는 타입이나 필드 오류가 발생할 수 있습니다. 해결 방법은 구독에 필요한 mihomo 커널로 전환하거나 현재 커널과 호환되는 형식으로 구독 서비스가 출력하도록 하는 것입니다. 인증, TLS, 전송 매개변수를 무작정 삭제해서는 안 됩니다.

최소 설정으로 문제가 노드에 있는지 전역 설정에 있는지 확인

원본 파일을 복사해 둔 뒤 최소 테스트 설정을 만들 수 있습니다. 정상 작동이 확인된 노드 하나, 프록시 그룹 하나, MATCH 규칙 하나만 남겨 보세요. 최소 설정이 로드되면 DNS, TUN, rule-providers, 고급 프로토콜 설정을 단계별로 추가해 문제 구간을 찾을 수 있습니다. 단일 노드에서도 계속 오류가 발생한다면 해당 노드의 type, 주소, 포트, 인증 필드, TLS 매개변수를 중점적으로 확인하세요.

mixed-port: 7890
mode: rule
log-level: info

proxies:
  - name: test-node
    type: socks5
    server: 127.0.0.1
    port: 1080

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - test-node
      - DIRECT

rules:
  - MATCH,PROXY

이 예시는 구조를 로드할 수 있는지 확인하기 위한 용도입니다. 연결을 만들려면 127.0.0.1:1080에서 실제 SOCKS5 서비스가 실행 중이어야 합니다. 구조 테스트는 통과했지만 네트워크 테스트가 실패한다면 YAML 구조는 커널이 허용한 것이므로, 이후에는 노드 접근성과 인증 매개변수를 확인하세요.

포트 사용 여부와 남아 있는 커널 프로세스 확인

설정 파싱이 성공한 뒤 로그에 address already in use가 표시된다면 문제 지점은 구독 형식이 아니라 수신 포트입니다. 흔한 충돌로는 기존 커널이 7890을 계속 사용 중인 경우, 다른 인스턴스가 컨트롤러 포트 9090을 사용하는 경우, 여러 클라이언트에서 동시에 시스템 프록시를 켠 경우가 있습니다. 다른 프록시 클라이언트와 남아 있는 커널을 완전히 종료한 뒤 설정을 다시 로드하세요. 비교를 위해 Mixed Port를 7897로 임시 변경할 수도 있습니다.

Windows에서는 netstat -ano | findstr :7890을 실행해 포트를 사용하는 프로세스 번호를 확인할 수 있고, macOS와 Linux에서는 lsof -iTCP:7890 -sTCP:LISTEN을 실행할 수 있습니다. 프로세스의 정체를 확인한 후 종료하고, 포트 번호만 보고 시스템 서비스를 처리하지 마세요.

5단계: 결과에 따라 해결 방법 적용

링크 만료 또는 인증 실패

서비스 콘솔에서 구독 주소를 새로 생성하고 요금제 상태와 기기 제한을 확인하세요.
클라이언트에서 실패한 항목을 삭제하고 새 구독을 만드세요. 캐시된 URL을 계속 사용하지 않도록 합니다.
자동 업데이트 간격을 1440분처럼 적절한 값으로 설정하세요. 짧은 시간에 반복해서 새로고침하면 429가 발생할 수 있습니다.
새 링크에서도 401 또는 403이 반환되면 상태 코드, 시간, 토큰을 가린 로그를 보관해 서비스 제공업체에 문의하세요.

웹페이지, JSON 오류 또는 범용 노드 목록이 반환됨

사용자 센터 페이지 주소가 아니라 구독 API를 복사했는지 확인하세요.
Clash Meta 또는 mihomo 형식을 선택해 설정을 다시 다운로드하세요.
공유 링크 목록만 가져올 수 있다면 로컬 변환 과정으로 YAML을 생성하고 프록시 그룹과 규칙을 직접 추가하세요.
변환 후에는 기존 설정을 덮어쓰지 말고 새 설정으로 먼저 가져오세요.

YAML 필드 또는 커널 호환성 문제

로그의 행 번호를 기준으로 들여쓰기, 따옴표, 필드 타입을 확인하세요.
현재 mihomo 버전에서 지원하는 설정 구조를 대조하고 프로토콜 타입과 DNS 필드를 확인하세요.
최소 설정을 단계별로 복원해 특정 노드, 규칙 세트 또는 DNS 구간을 찾으세요.
커널을 업데이트한 뒤 클라이언트를 다시 시작하고 새 연결을 만든 다음 테스트하세요. 기존 연결의 결과를 그대로 사용하지 마세요.

수정 완료 후 검증 기록

전체 검증에서는 네 가지 결과를 확인해야 합니다. 구독 요청이 200을 반환하는지, 본문이 예상 형식인지, mihomo 커널이 설정을 로드했는지, 실제 연결이 규칙에 따라 해당 프록시 그룹으로 들어가는지입니다. 노드 수가 늘어난 것만으로는 규칙 세트, DNS 또는 TUN이 정상 작동한다고 볼 수 없습니다.

수동으로 한 번 새로고침하고 소요 시간을 기록하세요. 예를 들어 같은 네트워크에서 세 번 연속 1.2초, 1.4초, 1.3초가 걸렸다면 결과가 비교적 안정적이라고 볼 수 있습니다.
로그를 열고 직접 연결 도메인 하나와 프록시 도메인 하나에 접속해 규칙 적용 대상이 예상과 일치하는지 확인하세요.
프록시 그룹을 전환한 뒤 새 연결을 만드세요. 기존 TCP 연결은 이전 출구를 계속 사용할 수 있습니다.
클라이언트를 다시 시작한 뒤 설정을 한 번 더 로드해 메모리에만 남아 있는 임시 상태를 배제하세요.
적절한 자동 업데이트 간격을 복원하고 시스템 프록시와 TUN 상태가 일상적인 사용 방식에 맞는지 확인하세요.

점검 순서는 고정하는 것이 좋습니다. 먼저 HTTP 상태와 응답 본문을 확인하고, 다음으로 YAML 문법과 참조 관계를 점검한 뒤, 마지막으로 커널 버전·포트·실행 상태를 처리하세요. 이렇게 하면 이미 만료된 링크의 설정을 반복해서 편집하는 일을 막고, 포트 충돌을 구독 파싱 오류로 잘못 판단하는 일도 피할 수 있습니다.