Clash 구독 업데이트 실패 원인과 자동 업데이트 간격 설정

먼저 어느 단계에서 실패했는지 확인하기

클라이언트에서 ‘구독 업데이트’는 하나의 동작이 아닙니다. 도메인 확인, 연결 설정, HTTP 요청 전송, 응답 수신, 설정 파싱, 로컬 파일 저장, 코어 재로드까지 여러 단계로 이루어집니다. 화면에 ‘업데이트 실패’만 표시된다면 로그나 응답 내용을 통해 실제 실패 단계를 먼저 확인해야 합니다. 같은 버튼을 반복해서 눌러도 결과가 달라지지 않는 경우가 많고, 구독 서비스의 요청 빈도 제한이 걸릴 수도 있습니다.

일반적인 데스크톱 클라이언트에서는 ‘설정’, ‘구독’ 또는 ‘Profiles’ 페이지에서 구독을 관리합니다. mihomo 코어를 사용하는 클라이언트라면 먼저 「설정」→「구독」으로 이동해 대상 설정을 수동 업데이트한 다음, 「로그」 페이지에서 같은 시각에 기록된 내용을 확인하세요. 로그 수준을 선택할 수 있다면 문제를 확인하는 동안에는 Info를 사용하고, 오류 정보가 부족할 때만 일시적으로 Debug로 전환하는 것이 좋습니다.

로그 또는 증상	일반적으로 해당하는 단계	우선 확인할 항목
`no such host`, 도메인 확인 실패	DNS 확인	DNS 설정, 네트워크 연결, 구독 도메인의 유효성
`timeout`, 연결 시간 초과	연결 설정 또는 응답 대기	직접 연결과 프록시 경로, 방화벽, 서버 상태
`401` 또는 `403`	서버 인증	토큰, 링크 유효 기간, User-Agent 및 접근 제한
`404` 또는 `410`	구독 주소 만료	전체 구독 링크를 다시 발급받기
YAML, Base64 또는 필드 파싱 오류	설정 파싱	응답 형식, 변환 유형, 클라이언트 호환성
다운로드는 성공했지만 설정이 변경되지 않음	저장 또는 재로드	로컬 캐시, 현재 활성화된 설정, 파일 쓰기 권한

구독 다운로드와 노드 연결 상태 구분하기

구독 업데이트에 성공했다는 것은 클라이언트가 설정을 받아 파싱했다는 뜻일 뿐, 그 안의 프록시 노드가 반드시 연결된다는 의미는 아닙니다. 반대로 현재 노드를 사용할 수 있다고 해서 구독 주소가 여전히 유효한 것도 아닙니다. 로컬 설정이 며칠 전 저장된 캐시일 수 있어 노드는 작동하지만, 원래 구독 토큰은 이미 만료되었을 수 있습니다.

업데이트는 실패했지만 기존 노드를 사용할 수 있음: 구독 주소, 인증 및 업데이트 경로를 중점적으로 확인하세요.
업데이트는 성공했지만 모든 노드가 시간 초과됨: 노드 매개변수, 네트워크 제한 및 시스템 시간을 확인하세요.
노드 수가 0개가 됨: HTTP 상태 코드만 보지 말고 서버의 실제 응답 내용을 먼저 확인하세요.
설정을 다운로드했지만 활성화할 수 없음: YAML 문법, 필드 호환성 및 코어 버전을 확인하세요.

구독 링크 만료, 잘림 및 인증 실패

구독 주소에는 보통 접근 토큰이 포함됩니다. 토큰이 재설정되었거나 요금제 상태가 바뀌었거나 링크에 유효 기간이 설정되어 있거나, 서버에서 경로를 이전한 경우 기존 주소가 401, 403, 404 또는 410을 반환할 수 있습니다. 일부 서비스는 상태 코드가 200이어도 본문에 로그인 페이지나 JSON 오류 메시지를 반환합니다. 따라서 ‘다운로드 완료’로 표시되어도 파싱 단계에서 실패할 수 있습니다.

전체 링크를 복사했는지 확인하기

긴 링크는 메신저, QR 코드 인식 또는 수동 줄바꿈 과정에서 끝부분 문자가 빠지기 쉽습니다. 쿼리 매개변수의 &도 확인하세요. 웹페이지에서 복사할 때는 HTML에 표시된 이스케이프 문자열을 그대로 클라이언트에 입력하지 말고, 브라우저 주소 표시줄의 실제 링크를 가져와야 합니다. 링크 앞뒤에 공백, 큰따옴표 또는 줄바꿈이 포함되어서도 안 됩니다.

구독 서비스의 관리 페이지로 돌아가 Clash 또는 mihomo에 해당하는 구독 주소를 다시 복사하세요.
클라이언트에서 임시 구독을 새로 만들고 기존 설정은 서둘러 삭제하지 마세요.
수동 업데이트를 실행한 뒤 노드 수, 프록시 그룹 이름 및 업데이트 시간을 비교하세요.
새 설정이 정상적으로 로드되는 것을 확인한 다음, 만료된 기존 구독을 비활성화하세요.

구독 링크는 접근 자격 증명과 같으므로 공개 로그, 스크린샷 또는 온라인 YAML 검사 사이트에 올려서는 안 됩니다. 오류 정보를 공유해야 한다면 도메인과 상태 코드는 남겨도 되지만, 경로의 토큰과 쿼리 매개변수는 가려야 합니다.

명령줄에서 상태 코드와 응답 유형 확인하기

브라우저는 로그인 페이지로 자동 이동할 수 있고, Clash와 다른 요청 헤더를 사용할 수도 있습니다. 명령줄에서 테스트하면 상태 코드와 응답 헤더를 더 쉽게 확인할 수 있습니다. Windows에서는 PowerShell에서 curl.exe를 호출하고, macOS와 Linux에서는 curl을 바로 사용할 수 있습니다. 아래 예시는 실제 구독 자격 증명을 포함하지 않은 예약 도메인을 사용합니다.

curl -I -L --max-time 15 "https://sub.example.com/clash/demo-token"
curl -L --max-time 15 -o subscription.yaml "https://sub.example.com/clash/demo-token"

-I는 응답 헤더만 요청하지만 일부 구독 서버는 HEAD 요청을 허용하지 않습니다. 첫 번째 명령에서 405가 반환되면 두 번째 실제 GET 요청의 결과를 기준으로 판단하세요. 다운로드가 끝나면 파일의 시작 부분을 먼저 확인합니다. HTML은 보통 <!doctype html> 또는 <html로 시작하고, JSON 오류는 중괄호로 시작하는 경우가 많습니다. Clash YAML에서는 일반적으로 proxies:, proxy-groups:, rules: 같은 필드를 확인할 수 있습니다.

User-Agent 인증 및 형식 호환성 문제

일부 구독 서비스는 User-Agent에 따라 서로 다른 형식을 반환하거나 특정 클라이언트 식별자만 허용합니다. 브라우저에서는 정상적으로 열리지만 클라이언트 업데이트에서는 403이 반환되거나, 같은 주소에서 클라이언트마다 다른 내용이 내려온다면 UA를 확인해야 합니다. 흔히 clash, Clash.Meta 및 클라이언트 자체 이름이 사용되지만, 어떤 값을 허용할지는 서버 설정에 따라 다릅니다. 무작위로 계속 바꿔 가며 확인해서는 안 됩니다.

먼저 구독 서비스 안내에서 권장 UA를 확인하세요. 클라이언트에 설정 항목이 있다면 「설정」→「매개변수 설정」 또는 구독 편집 창에서 ‘User-Agent’, ‘구독 요청 헤더’와 같은 옵션을 찾을 수 있습니다. 메뉴 이름은 클라이언트 버전에 따라 달라집니다. 해당 옵션이 없다면 추측으로 코어 설정을 직접 수정하지 마세요. 기본 설정의 프록시 규칙은 구독 관리자가 보내는 HTTP 요청 헤더와 다릅니다.

curl -L --max-time 15 \
  -A "Clash.Meta" \
  -o subscription.yaml \
  "https://sub.example.com/clash/demo-token"

기본 요청에서 403이 반환되지만 서비스 제공자가 명시한 UA를 사용했을 때 200과 유효한 YAML을 받는다면, 문제를 요청 헤더 인증으로 좁힐 수 있습니다. 두 요청 모두 같은 오류를 반환한다면 토큰, 발신 IP, 요청 빈도 및 서비스 상태를 계속 확인하세요.

Base64 노드 목록과 Clash YAML은 서로 다른 형식

범용 구독은 여러 줄의 URI가 들어 있는 Base64 텍스트일 수 있고, Clash 설정은 일반적으로 구조화된 YAML입니다. 클라이언트가 Clash YAML만 지원한다면 범용 구독을 가져올 때 ‘proxies 누락’, ‘설정을 파싱할 수 없음’ 또는 노드 수 0과 같은 문제가 발생할 수 있습니다. 이 경우 파일 확장자를 수동으로 바꾸지 말고 서버에서 Clash, Clash Meta 또는 mihomo 출력 유형을 선택하세요.

mihomo는 Clash 설정과 폭넓은 호환성을 유지하지만 확장 필드가 구버전 Clash 코어에서 항상 인식되는 것은 아닙니다. 예를 들어 일부 새 프로토콜 매개변수, 규칙 제공자 옵션 및 DNS 필드는 구형 코어에서 알 수 없는 필드 오류나 로드 실패를 일으킬 수 있습니다. 이 경우 먼저 클라이언트의 코어 버전을 확인한 뒤 호환되는 구독 템플릿을 선택하세요. 그래픽 클라이언트를 업데이트해도 코어가 자동으로 전환되지는 않습니다. 코어 버전은 「설정」→「코어」 또는 ‘정보’ 페이지에서 별도로 확인해야 합니다.

YAML이 열려도 로드되지 않을 수 있음

같은 레벨의 들여쓰기는 일관되어야 하며 Tab과 공백을 섞어 사용할 수 없습니다.
프록시 그룹에서 참조하는 노드 또는 제공자 이름이 실제로 존재해야 합니다.
rules에서 사용하는 대상 프록시 그룹이 이미 정의되어 있어야 합니다.
포트는 유효한 정수여야 하며 따옴표, 한글 기호 또는 주석으로 인해 값이 손상되어서는 안 됩니다.
서버가 빈 파일을 반환하면 클라이언트가 기존 설정을 유지할 수도 있고, 파싱이 끝났지만 노드가 없다고 표시할 수도 있습니다.

구독 자체가 서버에서 생성되는 경우 다운로드한 파일을 장기간 직접 수정하는 것은 일반적으로 권장되지 않습니다. 다음 자동 업데이트에서 변경 사항이 덮어써지기 때문입니다. 로컬 DNS, TUN 또는 규칙 설정을 유지해야 한다면 클라이언트가 제공하는 오버라이드, 병합 설정 또는 스크립트 기능을 우선 사용하고, 클라이언트를 업데이트할 때마다 병합 결과를 확인하세요.

업데이트 시 직접 연결과 프록시 중 무엇을 사용할지

구독 요청이 어떤 경로를 사용하는지는 가장 쉽게 놓치는 변수입니다. 구독 도메인에 직접 접속할 수 있다면 기존 노드에 의존하지 않는 직접 연결이 가장 간단합니다. 구독 도메인에 프록시로만 접속할 수 있다면 클라이언트의 ‘프록시를 통해 업데이트’ 옵션을 활성화하거나 업데이트 프로그램이 현재 프록시를 사용하도록 해야 합니다. 이 옵션의 구현은 클라이언트마다 다릅니다. 시스템 프록시를 사용하는 경우도 있고, 현재 코어 포트를 직접 호출하는 경우도 있습니다.

시작 가능한 업데이트 경로를 우선 선택하기

구독 업데이트가 구독 안에 포함된 노드에 의존하면 시작 의존성이 생깁니다. 로컬에 사용할 수 있는 기존 노드가 없으면 구독 서버에 연결할 수 없고, 구독을 업데이트할 수 없으면 새 노드도 가져올 수 없습니다. 가장 안정적인 방법은 최근에 정상 작동한 설정을 보존하고 업데이트 실패 시 로컬 파일을 비우지 않는 것입니다.

네트워크 조건	권장 업데이트 경로	이유
구독 도메인에 직접 접속 가능	직접 연결	현재 노드와 프록시 포트에 대한 의존성 감소
직접 연결 시간 초과, 현재 프록시로는 접속 가능	프록시를 통해 업데이트	로컬 네트워크에서 구독 사이트로 연결하는 문제 우회
프록시를 켠 뒤 오히려 업데이트 실패	일시적으로 직접 연결로 전환해 테스트	노드 장애, 잘못된 규칙 분류 및 프록시 인증 문제 배제
새 기기에 사용할 수 있는 설정이 없음	서비스 제공자가 직접 접속을 허용한 진입점 사용	아직 설정되지 않은 프록시 연결에 대한 의존성 방지

구독 관리 요청이 반드시 Clash 규칙을 거치는 것은 아닙니다. 일부 클라이언트는 자체 프로세스에서 구독을 직접 다운로드하고, 다른 클라이언트는 요청을 로컬 mixed-port로 전달합니다. 규칙에 구독 도메인을 DIRECT로 지정했더라도 클라이언트 업데이트 프로그램이 반드시 해당 규칙을 사용하는 것은 아닙니다. 클라이언트 문서, 업데이트 설정 및 로그에 기록된 실제 연결 경로를 기준으로 판단하세요.

로컬 포트와 시스템 프록시 확인하기

일반적인 설정에서는 mixed-port를 7890, 외부 컨트롤 포트를 9090으로 지정하지만 이는 흔한 값일 뿐 필수값은 아닙니다. 7890을 다른 프로세스가 사용하면 시스템 프록시가 여전히 이전 포트를 가리켜 브라우저와 구독 업데이트 프로그램의 연결이 실패할 수 있습니다. 먼저 클라이언트의 ‘일반’ 또는 ‘네트워크’ 페이지에서 현재 HTTP, SOCKS 및 mixed 포트를 확인한 뒤 운영체제의 프록시 주소가 일치하는지 점검하세요.

TUN 모드는 일반적으로 시스템 프록시보다 더 넓은 범위를 처리하지만, TUN을 켠다고 만료된 링크, 잘못된 UA 또는 YAML 형식 문제가 해결되지는 않습니다. TUN이 켜져 있을 때만 업데이트가 실패한다면 TUN을 일시적으로 끄고 시스템 프록시는 유지한 채 한 번 테스트하세요. 그런 다음 DNS 가로채기, 라우팅 제외 항목 및 구독 도메인이 잘못된 프록시 그룹으로 전달되고 있지 않은지 확인하세요.

자동 업데이트 간격 설정 방법

자동 업데이트는 자주 할수록 좋은 것이 아닙니다. 노드와 정책 변경이 많지 않은 구독은 보통 6시간마다 한 번이면 충분하며, 초 단위로는 21600입니다. 변경이 잦고 서버가 높은 빈도의 요청을 허용하는 구독은 1시간, 즉 3600초로 설정할 수 있습니다. 하루에 한 번 업데이트하려면 86400초입니다. 15분보다 짧은 주기는 불필요한 요청을 늘리고 429 요청 제한을 유발할 수 있습니다.

사용 상황	권장 간격	초 단위
일반적인 개인 사용, 노드 변경이 적음	6시간	`21600`
노드가 자주 변경되고 서버가 잦은 새로고침을 허용함	1시간	`3600`
설정이 장기간 안정적이며 정기 동기화만 필요함	24시간	`86400`
일시적으로 문제를 확인하는 동안	자동 업데이트를 끄고 수동 업데이트 사용	오류 요청의 반복 발생 방지

그래픽 클라이언트에서는 보통 구독 편집 창에서 업데이트 간격을 설정하며, 단위는 시간, 분 또는 초일 수 있습니다. 변경하기 전에 필드 설명을 확인하고, ‘시간’ 단위 입력란에 3600을 입력하지 않도록 주의하세요. 일부 클라이언트는 프로그램이 실행 중일 때만 시간을 계산하므로, 기기가 절전 모드에서 깨어난 뒤 다음 업데이트가 즉시 실행될 수 있습니다.

mihomo proxy-provider 업데이트 예시

설정에서 proxy-providers를 사용하는 경우 각 제공자에 독립적인 interval을 지정할 수 있습니다. 단위는 초입니다. 아래 예시는 6시간마다 제공자 파일을 가져오고 10분마다 상태 확인을 실행합니다. 상태 확인과 구독 업데이트는 서로 다른 타이머로 동작하므로 대신 사용할 수 없습니다.

proxy-providers:
  service-a:
    type: http
    url: "https://sub.example.com/provider/demo-token"
    path: ./providers/service-a.yaml
    interval: 21600
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 600

interval: 21600은 원격 제공자 파일의 새로고침 주기를 제어하고, health-check.interval: 600은 노드 연결 가능성 검사만 제어합니다. 상태 확인을 600초로 설정해도 구독이 10분마다 다시 다운로드되지는 않습니다. 반대로 구독 업데이트에 성공했다고 해서 모든 노드가 상태 확인을 통과했다는 뜻도 아닙니다.

순서대로 전체 문제 해결하기

구독 문제는 외부에서 내부로 확인하는 것이 좋습니다. 먼저 링크와 서버 응답을 확인하고, 다음으로 요청 헤더와 네트워크 경로를 점검한 뒤 마지막으로 형식과 로컬 로드를 처리하세요. 이렇게 하면 링크가 이미 만료된 상태에서 DNS, TUN 및 규칙을 반복해서 수정하는 일을 피할 수 있습니다.

오류 시간을 기록하세요.수동 업데이트를 한 번 실행하고 로그에서 상태 코드, 도메인, 시간 초과 또는 파싱 오류를 즉시 확인합니다.
링크가 완전한지 확인하세요.서버에서 Clash 또는 mihomo 유형의 링크를 다시 복사하고 클라이언트에서 임시 구독을 새로 만듭니다.
직접 연결 응답을 테스트하세요.‘프록시를 통해 업데이트’를 끈 뒤 한 번 시도하고 결과를 기록합니다.
프록시 응답을 테스트하세요.정상 작동이 확인된 노드를 다시 활성화하고 ‘프록시를 통해 업데이트’를 켠 뒤 한 번 더 시도합니다.
User-Agent를 확인하세요.서버에서 명시적으로 지원하는 식별자만 사용하고 403, 200 및 응답 본문을 비교합니다.
콘텐츠 형식을 확인하세요.응답이 HTML, 오류 JSON, 빈 파일 또는 호환되지 않는 Base64 목록이 아닌지 확인합니다.
코어와 필드를 확인하세요.mihomo 또는 Clash 코어 버전을 확인하고 알 수 없는 필드, 프록시 그룹 참조 및 YAML 들여쓰기 문제를 찾습니다.
설정을 다시 로드하세요.새 파일이 정상적으로 저장되었는지 확인하고 설정 페이지에서 업데이트된 항목을 명시적으로 선택합니다.
적절한 간격으로 되돌리세요.일반적인 환경에서는 6시간, 변경이 잦은 환경에서는 1시간으로 설정하고 429가 발생하는지 확인합니다.

업데이트 성공 후 확인

업데이트가 완료된 뒤 녹색 알림만 확인하지 마세요. 먼저 전체 노드 수와 프록시 그룹 이름을 기록한 다음 노드 하나를 선택해 지연 시간을 테스트하세요. 이어서 외부 IP 주소를 확인하기 적합한 페이지에 접속하고, Clash 연결 기록에서 요청이 예상한 정책에 적용되었는지 확인합니다. 클라이언트에는 업데이트 성공으로 표시되지만 노드 목록과 파일 수정 시간이 모두 바뀌지 않았다면, 활성화되지 않은 구독 항목이 업데이트된 것은 아닌지 확인하세요.

자동 업데이트는 가끔 실패하지만 수동 업데이트는 바로 성공한다면, 기기가 절전 모드에서 막 깨어났거나 네트워크가 아직 준비되지 않았거나 프록시 코어가 구독 작업보다 늦게 시작되었거나 서버에서 잠시 요청을 제한하는 것이 흔한 원인입니다. 업데이트 간격을 적절히 늘리고 실패 로그를 보관하세요. 특정 네트워크 환경에서 매번 실패한다면 새로고침 주기를 계속 줄이기보다 직접 연결, 시스템 프록시 및 TUN 세 경로를 비교하는 데 집중해야 합니다.

최종적으로 안정적인 상태는 다음 네 가지를 충족해야 합니다. 구독 링크가 유효하고, 업데이트 요청 경로가 명확하며, 반환된 콘텐츠가 현재 코어와 호환되고, 자동 새로고침 빈도가 서버 제한에 맞아야 합니다. 이 네 항목을 각각 확인하면 구독 업데이트 실패가 어느 단계에서 발생했는지 대개 찾을 수 있으며, 클라이언트를 다시 설치하거나 전체 설정을 삭제할 필요가 없습니다.