Clash 구독 링크가 작동하지 않을 때: 파싱 실패 및 업데이트 오류 해결 방법

먼저 문제가 발생한 단계를 확인하세요

Clash 클라이언트가 구독을 업데이트할 때는 실제로 여러 단계를 연속해서 처리합니다. 구독 주소에 접속하고, 리디렉션을 따라가며, 응답 내용을 다운로드한 뒤 설정 형식을 인식하고 YAML을 파싱합니다. 마지막으로 프록시 노드와 정책 그룹을 로컬 설정에 기록합니다. 화면에 표시되는 짧은 ‘업데이트 실패’ 메시지는 이 과정 중 어느 단계에서든 발생할 수 있습니다. 반복해서 업데이트 버튼을 누르기보다 먼저 문제의 단계를 좁히는 편이 훨씬 효과적입니다.

문제를 확인하기 전에 오류가 발생한 정확한 시간, 클라이언트에 표시된 전체 오류 메시지, 현재 네트워크 환경을 기록하세요. 가능하다면 가정용 인터넷 대신 모바일 핫스팟으로 바꾸는 등 네트워크도 한 번 변경해 보세요. 처음부터 DNS, 시스템 프록시, TUN, 구독 주소를 동시에 수정하면 복구되더라도 무엇이 원인이었는지 알기 어렵습니다.

자주 나타나는 현상과 확인할 방향

화면에 표시되는 현상	우선 확인할 항목	일반적인 원인
HTTP 401 또는 403	구독 권한, 요청 헤더	토큰 만료, 서버 요구 사항과 다른 User-Agent
HTTP 404 또는 410	구독 주소	링크가 취소되었거나 요금제 재설정 후 기존 주소가 폐기됨
HTTP 429	업데이트 빈도	짧은 시간에 요청이 몰려 서버의 속도 제한이 발동됨
연결 시간 초과	네트워크, DNS, 프록시 루프	도메인에 연결할 수 없거나 업데이트 요청이 작동하지 않는 프록시를 통해 전송됨
YAML 파싱 실패	응답 본문, 형식	웹 페이지, JSON 오류 메시지 또는 들여쓰기가 잘못된 설정을 다운로드함
업데이트는 성공했지만 노드가 0개	구독 내용, 필터 조건	빈 설정 반환, 호환되지 않는 형식, 클라이언트 필터가 모든 노드를 제거함

구독 주소, 상태 코드, 응답 내용 확인하기

구독 링크에는 대개 액세스 토큰이 포함되어 있습니다. 토큰은 구독 재설정, 계정 변경, 서비스 만료 또는 관리자의 보안 정책에 따라 바뀔 수 있습니다. 링크를 복사할 때 공백이나 줄바꿈, 메신저가 덧붙인 문장 부호가 함께 들어가는 경우도 있습니다. 서비스 제공업체의 관리 화면에서 전체 주소를 다시 복사한 뒤 일반 텍스트 편집기에 붙여 넣어 확인하세요.

브라우저에서 열린다고 해서 클라이언트에서도 반드시 업데이트되는 것은 아닙니다

브라우저는 Cookie, 로그인 상태, 일부 리디렉션을 자동으로 처리하지만 Clash 클라이언트는 일반적인 HTTP 요청 헤더만 보내는 경우가 많습니다. 링크를 열었을 때 로그인 페이지, CAPTCHA 페이지, 요금제 안내 또는 HTML이 보인다면 클라이언트가 프록시 설정이 아닌 해당 페이지를 받은 것일 수 있습니다. 정상적인 응답은 대개 YAML 텍스트, Base64 인코딩 텍스트 또는 해당 클라이언트가 지원하는 구독 형식입니다.

macOS, Linux 또는 curl이 설치된 Windows 환경에서는 먼저 응답 헤더를 확인할 수 있습니다. 아래에는 예시 도메인을 사용했으므로 실제 구독 토큰을 공개 채팅이나 스크린샷에 올리지 마세요.

curl -I -L --max-redirs 5 "https://sub.example.net/api/client/abc123"

-I는 응답 헤더만 요청하고, -L은 리디렉션을 따라가며, --max-redirs 5는 리디렉션 횟수를 5회로 제한합니다. 최종 상태 코드, content-type, 리디렉션 루프 발생 여부를 중점적으로 확인하세요. 구독 서비스에서 정상적으로 자주 반환되는 상태 코드는 200입니다. 301, 302, 307, 308은 주소 이전 과정에서 정상일 수 있지만 최종 응답은 200이어야 합니다.

상태 코드별 대응 방법

401 Unauthorized: 토큰이 유효하지 않거나 링크에 추가 인증 정보가 필요합니다. 구독 주소를 새로 생성하고 기존 링크를 반복해서 시도하지 마세요.
403 Forbidden: 서버가 현재 요청을 거부했습니다. 클라이언트 유형, 접속 지역 또는 요청 빈도가 제한되었을 수 있으므로 User-Agent와 계정 상태를 확인하세요.
404 Not Found: 경로가 존재하지 않습니다. 주소가 완전히 복사되지 않았거나, 링크가 잘렸거나, 관리 화면에서 API 경로가 변경된 경우가 흔합니다.
410 Gone: 리소스가 명시적으로 폐기되었습니다. 일반적으로 링크를 새로 생성해야 합니다.
429 Too Many Requests: 요청이 너무 잦습니다. 10~30분 정도 기다린 뒤 한 번만 수동 업데이트하고, 1분 단위의 자동 새로고침은 설정하지 마세요.
500, 502, 503, 504: 서버 또는 상위 게이트웨이에 문제가 있습니다. 네트워크를 바꾸는 것은 원인 확인에만 도움이 되며, 대부분은 서비스가 복구될 때까지 기다려야 합니다.

응답 본문 일부를 확인해야 한다면 다운로드 크기를 제한해 터미널 기록에 전체 노드 정보가 남지 않도록 하세요. 더 안전한 방법은 본인만 접근할 수 있는 임시 파일에 저장한 다음 파일의 앞부분을 확인하는 것입니다.

curl -L --max-time 20 \
  -A "Clash.Meta" \
  "https://sub.example.net/api/client/abc123" \
  -o subscription-check.txt

head -n 12 subscription-check.txt

처음에 <!doctype html>, <html>, CAPTCHA 문구 또는 JSON 오류 객체가 나타난다면 Clash 설정이 아닌 다른 내용을 다운로드한 것입니다. 본문이 영문자, 숫자, 더하기 기호, 슬래시, 등호로 이루어진 매우 긴 한 줄뿐이라면 Base64 구독일 수 있으며, 호환되는 클라이언트나 변환 과정이 필요합니다.

User-Agent 및 형식 호환성 확인

일부 구독 API는 User-Agent에 따라 서로 다른 형식을 반환합니다. 같은 주소라도 브라우저에는 웹 페이지를, Clash에는 YAML을, 다른 클라이언트에는 또 다른 인코딩을 반환할 수 있습니다. 클라이언트를 업그레이드하거나 mihomo 코어로 이전하거나 그래픽 인터페이스를 바꾸면 요청 헤더가 달라질 수 있어 ‘기존 클라이언트에서는 업데이트되지만 새 클라이언트에서는 오류가 발생하는’ 상황이 생깁니다.

먼저 서비스 제공업체가 안내한 클라이언트 유형을 사용하세요

구독 관리 화면에 Clash, Clash Meta, Mihomo 등의 내보내기 옵션이 있다면 해당 유형에 맞는 링크를 새로 생성하는 것이 우선입니다. 내보내기 항목에 따라 User-Agent뿐 아니라 정책 그룹, 노드 필드, 규칙 구조까지 달라질 수 있습니다. 클라이언트에서 이름만 수동으로 바꾸는 것은 구독 형식을 다시 선택하는 것과 같지 않을 수 있습니다.

일부 클라이언트는 구독 편집 화면에서 User-Agent를 설정할 수 있습니다. 메뉴 이름은 소프트웨어마다 다르지만, 일반적인 경로는 「구독」→「편집」→「고급 설정」→「User-Agent」 또는 「설정」→「매개변수 설정」→「구독 요청 헤더」입니다. 서비스 제공업체가 명확히 지원하는 값을 다음과 같이 하나씩 시도해 보세요.

Clash
Clash.Meta
mihomo

한 번에 여러 값을 입력하거나 근거 없이 브라우저 Cookie를 추가하지 마세요. 변경한 뒤 저장하고 수동으로 한 번 업데이트하세요. 서버가 403을 반환하다가 서비스 제공업체가 지정한 User-Agent로 바꾼 후 200으로 회복된다면 요청 헤더 인식 문제가 원인일 가능성이 높습니다.

Clash 설정에는 완전한 구조가 필요합니다

일반적인 완전한 설정에는 프록시, 정책 그룹, 규칙 등의 항목이 포함됩니다. 최소 구조는 다음과 비슷할 수 있습니다.

mixed-port: 7890
mode: rule

proxies:
  - name: Example
    type: socks5
    server: 192.0.2.10
    port: 1080

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Example
      - DIRECT

rules:
  - MATCH,PROXY

다운로드한 내용이 ss://, vmess:// 또는 다른 공유 링크 몇 개뿐이라면 범용 노드 구독입니다. Clash YAML만 허용하는 가져오기 메뉴에서 바로 읽히지 않을 수 있습니다. 반대로 proxy-providers가 포함된 완전한 설정은 단일 provider 파일로 단순히 사용할 수 없습니다. 가져오기 전에 해당 메뉴가 ‘완전한 설정’, ‘노드 구독’, ‘프록시 모음’ 중 무엇을 요구하는지 확인하세요.

YAML 파싱 오류를 일으키는 세부 사항

YAML 들여쓰기는 공백을 사용해야 하며 Tab 문자는 파싱 실패를 일으킬 수 있습니다.
콜론 뒤에는 보통 공백이 필요합니다. 예: mode: rule
노드 이름에 콜론, 샵 또는 특수 문자가 포함되어 있다면 서버에서 올바르게 따옴표로 감싸야 합니다.
proxy-groups에서 참조하는 노드 이름은 proxies에 지정된 이름과 일치해야 합니다.
구버전 Clash가 인식하지 못하는 mihomo 확장 필드는 필드 검증 오류를 일으킬 수 있습니다. 클라이언트를 업그레이드하거나 호환되는 내보내기 형식을 선택하는 편이 좋습니다.

네트워크 차단, DNS 및 프록시 루프 확인

상태가 연결 시간 초과, TLS 핸드셰이크 실패 또는 도메인 확인 실패로 표시된다면 문제는 대개 설정을 다운로드하기 전에 발생한 것입니다. 이때 YAML을 계속 수정해도 의미가 없습니다. 먼저 구독 도메인이 정상적으로 확인되고 HTTPS 연결이 수립되는지 확인하세요.

두 네트워크에서 교차 테스트하기

현재 Wi-Fi에서 Clash의 시스템 프록시와 TUN을 끄고 한 번 직접 업데이트하세요.
모바일 핫스팟으로 전환한 뒤 다시 업데이트하세요.
핫스팟에서는 정상이고 기존 네트워크에서만 실패한다면 기존 네트워크의 DNS, 게이트웨이 필터, IPv6 경로를 중점적으로 확인하세요.
두 네트워크에서 모두 같은 403 또는 404가 반환된다면 문제는 로컬 네트워크보다 링크나 서버에 있을 가능성이 큽니다.

도메인 확인에는 운영체제에 기본 포함된 도구를 사용할 수 있습니다. 일반 도메인은 확인되는데 구독 도메인만 실패한다면, 현재 네트워크 환경에서 안정적으로 작동하는 DNS 서버로 임시 변경한 뒤 다시 시도해 보세요. 변경하기 전에 기존 값을 기록하고 테스트가 끝난 후 유지할지 결정하세요.

nslookup sub.example.net

curl -v --connect-timeout 10 \
  "https://sub.example.net/api/client/abc123" \
  -o subscription-check.txt

curl -v는 확인된 IP, TCP 연결, TLS 과정을 보여주지만 요청 경로도 출력할 수 있으므로 로그를 공개적으로 전달하지 마세요. 도메인 확인 단계에서 멈추면 DNS를, 연결 단계에서 멈추면 네트워크 경로를 확인하세요. TLS에서 인증서 도메인이 일치하지 않거나 만료되었다고 나오면 업데이트를 중지하고 서버가 수정할 때까지 기다려야 합니다. 클라이언트에서 인증서 검증을 장기간 끄면 안 됩니다.

구독 업데이트가 작동하지 않는 프록시를 거치지 않도록 하세요

일부 클라이언트는 구독 다운로드에 ‘프록시 사용’을 적용할 수 있습니다. 현재 노드가 이미 작동하지 않는데 업데이트 요청까지 해당 노드로 강제 전송되면, 노드를 업데이트하려는 요청이 기존 노드에 의존하는 악순환이 생깁니다. 구독 설정에서 ‘프록시를 통한 업데이트’를 끄거나, 시스템 프록시를 잠시 종료한 뒤 직접 연결로 업데이트하세요.

로컬에서 자주 사용되는 수신 포트로는 HTTP 포트 7890, SOCKS 포트 7891, 혼합 포트 7890, 외부 컨트롤 포트 9090 등이 있지만 사용자가 변경할 수 있습니다. 터미널 환경에 HTTP_PROXY, HTTPS_PROXY 또는 ALL_PROXY가 설정되어 있으면 클라이언트 화면에서 시스템 프록시를 꺼도 curl이 계속 로컬 포트를 사용할 수 있습니다.

env | grep -i proxy

curl --noproxy "*" -I -L \
  "https://sub.example.net/api/client/abc123"

일반 curl은 실패하지만 --noproxy "*"를 추가하면 성공한다면 문제는 구독 링크 자체가 아니라 프록시 경로에 있습니다. Windows PowerShell 사용자는 현재 세션의 프록시 환경 변수와 「설정」→「네트워크 및 인터넷」→「프록시」에 수동 프록시가 남아 있는지도 확인해야 합니다.

로컬 캐시를 정리하고 구독 기록 다시 만들기

링크와 네트워크가 정상인데도 클라이언트에 이전 노드, 빈 목록 또는 특정 시각에 반복되는 오류가 표시된다면 로컬 캐시가 제대로 교체되지 않았을 수 있습니다. 설정 파일이 사용 중이거나 디스크 권한에 문제가 있거나, 클라이언트 충돌 후 일부만 기록된 파일이 남았거나, 구독 기록에 이전 요청 헤더가 저장된 경우가 흔합니다.

되돌릴 수 있는 순서로 처리하세요

현재 사용할 수 있는 설정을 내보내고 사용자 지정 규칙, 오버라이드 설정, 정책 그룹 선택을 기록하세요.
클라이언트를 완전히 종료하고 메뉴 막대, 시스템 트레이, 백그라운드 프로세스까지 모두 끝났는지 확인하세요.
클라이언트를 다시 시작한 뒤 일반적인 방식으로 수동 업데이트를 한 번 실행하세요.
계속 실패한다면 기존 기록을 덮어쓰지 말고 새 구독 기록을 만든 다음 새로 생성한 주소를 붙여 넣으세요.
새 기록의 업데이트가 성공한 후 사용자 지정 오버라이드를 옮기고 기존 기록을 삭제하세요.

앱 데이터 디렉터리 전체를 바로 삭제하는 것은 권장하지 않습니다. 많은 그래픽 클라이언트가 같은 위치에 구독 캐시, 실행 설정, 로그, 오버라이드 스크립트, 인터페이스 설정을 함께 저장하므로 한 번에 비우면 복구 비용이 커집니다. 클라이언트에 「설정」→「구독」→「캐시 삭제」 또는 「설정 재생성」 기능이 있다면 이를 사용하세요. 해당 옵션이 없다면 클라이언트 문서에 따라 특정 구독 캐시 파일만 찾아 처리하는 편이 안전합니다.

업데이트는 성공했지만 노드가 여전히 없습니다

먼저 화면에 표시된 업데이트 시간이 실제로 변경되었는지 확인한 다음, 구독 본문에 노드가 포함되어 있는지 확인하세요. 원본 응답에는 노드가 있는데 클라이언트에 0개로 표시된다면 다음 설정을 계속 확인하세요.

노드 이름 필터의 포함 조건이 지나치게 좁게 설정되어 있지 않은지 확인하세요.
제외 정규식이 모든 노드와 잘못 일치하고 있지 않은지 확인하세요. 예를 들어 .*처럼 지나치게 포괄적인 패턴이 해당합니다.
구독 오버라이드가 proxies를 삭제했거나 정책 그룹을 교체하지 않았는지 확인하세요.
클라이언트가 provider만 불러오고 기본 설정에서는 해당 provider를 참조하지 않는지 확인하세요.
설정 전환이 방금 업데이트한 새 설정이 아니라 기존 파일에 계속 머물러 있지 않은지 확인하세요.

mihomo의 provider 설정도 정책 그룹에서 참조해야 합니다. proxy-providers를 정의했더라도 어떤 정책 그룹에도 해당 provider의 use가 지정되어 있지 않으면 노드가 그 정책 그룹에 표시되지 않습니다.

proxy-providers:
  airport:
    type: http
    url: "https://sub.example.net/provider.yaml"
    interval: 3600
    path: ./providers/airport.yaml

proxy-groups:
  - name: PROXY
    type: select
    use:
      - airport
    proxies:
      - DIRECT

interval: 3600은 3600초마다 한 번씩 확인한다는 뜻입니다. 실제 업데이트 간격은 서버 제한을 고려해 설정해야 하며, 보통 몇 분마다 새로 고칠 필요는 없습니다. 지나치게 잦은 업데이트는 노드를 더 빨리 활성화하지 않으며 429 속도 제한에 걸릴 가능성만 높입니다.

순서대로 전체 점검을 한 번 진행하세요

오류 메시지가 명확하지 않다면 아래의 고정 절차를 따라 보세요. 각 단계에서는 한 번에 하나의 변수만 변경하고 결과를 기록하세요. 이렇게 하면 마지막에 서비스 제공업체에 문의하더라도 충분히 명확한 근거를 전달할 수 있습니다.

기존 설정 저장: 정상적으로 작동하는 설정과 사용자 지정 규칙을 내보내세요.
주소 다시 복사: 계정 관리 화면에서 Clash 또는 mihomo에 맞는 구독을 생성하세요.
HTTP 상태 확인: 최종 응답이 로그인 페이지, 오류 페이지 또는 리디렉션 루프가 아닌 200인지 확인하세요.
응답 형식 확인: 완전한 YAML, provider 파일, Base64 텍스트, 웹 페이지를 구분하세요.
User-Agent 조정: 서비스 제공업체가 명확히 지원하는 Clash, Clash.Meta 또는 mihomo 식별자를 사용하세요.
기존 프록시 우회: ‘프록시를 통한 업데이트’를 끄고 7890, 7891 등의 로컬 포트와 환경 변수를 확인하세요.
네트워크 변경 테스트: 모바일 핫스팟으로 로컬 네트워크 문제와 서버 문제를 구분하세요.
새 구독 기록 생성: 기존 캐시, 요청 헤더, 오버라이드가 결과에 계속 영향을 주지 않도록 하세요.
필터 및 참조 확인: 정규식이 노드를 걸러내지 않았고 provider가 정책 그룹에서 참조되는지 확인하세요.
업데이트 빈도 조절: 429가 발생하면 요청을 중지하고, 자동 업데이트는 한 시간 간격으로 설정하는 것이 좋습니다.

서비스 제공업체에 문의할 때는 발생 시간, 최종 HTTP 상태 코드, 클라이언트 이름과 버전, 사용한 User-Agent, 다른 네트워크에서도 재현되는지 여부를 함께 전달하세요. 구독 주소는 도메인과 API 유형만 남기고 토큰 부분은 가리세요. 명확한 정보가 있으면 ‘Clash가 업데이트되지 않아요’라는 한마디보다 훨씬 효과적인 도움을 받을 수 있습니다.