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

구독을 가져올 때는 보통 링크 요청, 응답 수신, 설정 파싱, 설정 로드의 네 단계를 거칩니다. 화면에 표시되는 ‘업데이트 실패’는 이 중 어느 단계에서든 발생할 수 있습니다. 실패한 단계를 찾아야 링크를 갱신할지, 요청 방식을 바꿀지, 설정 구조를 확인할지 판단할 수 있습니다.

현재 정상 작동하는 설정을 먼저 보관한 다음, 실패한 구독을 수동으로 한 번 업데이트하세요. 클라이언트의 ‘로그’ 페이지를 열고 작업 시간, HTTP 상태 코드, 첫 번째 오류를 기록합니다. 클라이언트마다 메뉴 이름은 다르므로 연결 속도 테스트가 아니라 구독 업데이트 로그를 찾아야 합니다.

로그 단서 단계 우선 확인할 항목
no such host 도메인 확인 구독 도메인이 정확한지, 현재 DNS가 작동하는지 확인
timeout 또는 connection refused 연결 수립 또는 응답 수신 네트워크 경로, 프록시 포트, 서버 연결 가능 여부
HTTP 401、403、404、410 서버 응답 인증, 접근 제한, 링크 변경 여부
yaml: 및 줄 번호 응답 내용 파싱 응답이 설정 파일인지, 들여쓰기와 데이터 유형이 올바른지 확인
proxy not found 설정 참조 확인 프록시 그룹, 노드, 규칙 대상의 이름이 서로 일치하는지 확인

링크 만료 및 계정 상태

구독 주소 전체를 다시 복사하세요

서비스 제공업체의 계정 페이지에서 Mihomo용 구독 주소를 다시 복사하세요. 계정 로그인 페이지, 구매 페이지, 브라우저 주소창의 관리 페이지 주소를 구독 링크로 사용하면 안 됩니다. 복사한 주소에 공백, 줄바꿈, 한글 문장부호가 섞이지 않았는지 확인하고, ? 뒤의 매개변수가 메신저에서 잘리지 않았는지도 살펴보세요.

  • 401: 일반적으로 유효한 인증 정보가 없다는 뜻입니다. 링크 토큰과 계정 상태를 먼저 확인하세요.
  • 403: 접근 권한 거부일 수 있지만 요청 헤더, 지역, IP 또는 보안 정책에 따른 제한일 수도 있습니다. 상태 코드만으로 구독이 만료됐다고 단정할 수 없습니다.
  • 404 또는 410: 구독 경로가 변경됐거나 링크가 취소 또는 삭제됐을 수 있습니다. 계정 페이지에서 확인하세요.
  • 429: 요청이 너무 잦다는 뜻입니다. 응답의 Retry-After에 따라 기다리고 업데이트 버튼을 연속으로 누르지 마세요.
  • 5xx: 우선 서버 상태를 확인하고 잠시 후 다시 시도하세요. 로컬 설정을 크게 변경하는 것은 뒤로 미루세요.

트래픽 소진, 요금제 만료, 토큰 무효는 서로 다른 문제입니다. 일부 서비스는 명확한 401 대신 빈 목록이나 안내 문구를 반환하기도 합니다. 요청 성공 여부만 보지 말고 응답 본문과 계정 상태를 함께 확인하세요.

브라우저 확인의 한계

신뢰할 수 있는 기기에서 구독 링크를 직접 열면 로그인 페이지, 오류 페이지, 파일 다운로드 여부를 대략 확인할 수 있습니다. 하지만 브라우저는 로그인 Cookie를 포함하거나 클라이언트와 다른 User-Agent를 보낼 수 있습니다. 브라우저에서 다운로드된다고 클라이언트도 같은 내용을 가져온다는 보장은 없습니다. 브라우저에 글자가 깨져 보여도 설정이 손상됐다고 단정할 수 없습니다.

링크가 로그인 양식이나 CAPTCHA 페이지를 반환하면 먼저 전용 구독 주소를 복사했는지 확인하세요. 웹페이지를 .yaml 파일로 저장해 가져오지 마세요. 브라우저 테스트 기록이 남으므로 공유 기기에서는 특히 주의해야 합니다.

HTTP 응답과 실제 본문 확인

파일 확장자만으로는 내용을 판단할 수 없습니다. config.yaml이라는 이름의 응답이 HTML일 수 있고, HTTP 200이어도 ‘구독이 만료되었습니다’라는 안내가 담길 수 있습니다. 상태 코드, 리디렉션, 본문 시작 부분을 함께 확인하세요.

curl로 비교할 결과 저장하기

아래 명령은 curl이 설치된 macOS 또는 Linux의 Bash 터미널에서 사용할 수 있습니다. 주소를 입력해도 화면에 표시되지 않고 명령 기록에도 그대로 저장되지 않습니다. 다만 요청이 실행되는 동안에는 권한이 있는 로컬 프로세스가 확장된 주소를 볼 수 있습니다. 출력 파일에도 인증 정보가 포함될 수 있으므로 로컬에만 저장하세요.

read -r -s -p '구독 주소: ' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --connect-timeout 10 --max-time 30 \
  --dump-header subscription-headers.txt \
  --output subscription-response.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

연결 시간 제한은 10초, 전체 요청 제한은 30초, 리디렉션 횟수는 최대 5회로 설정합니다. 이는 문제 해결을 위한 매개변수일 뿐 서비스 성능을 측정한 결과가 아닙니다. 인증서 검증을 건너뛰는 -k를 추가하거나 인증 정보가 리디렉션 대상까지 전달되는 --location-trusted를 사용하지 마세요.

  1. 터미널에 표시된 curl 오류와 최종 HTTP 상태를 확인하세요. HTTP 응답을 받기 전에 연결이 끊기면 000이 표시될 수 있지만, 이는 서버 상태 코드가 아닙니다.
  2. subscription-headers.txt를 확인하세요. 리디렉션을 거쳤다면 파일에 응답 헤더 묶음이 여러 개 있을 수 있으므로 마지막 묶음을 살펴보세요.
  3. 로컬 텍스트 편집기에서 subscription-response.txt를 열고 첫 부분이 설정 필드, 인코딩된 노드 목록, HTML 또는 오류 안내인지 확인하세요.
  4. 리디렉션 대상이 제공업체에서 허용한 도메인인지 확인하세요. Cookie나 토큰이 포함된 주소가 들어 있을 수 있으므로 응답 헤더를 공개하지 마세요.

Content-Type은 참고 정보이지 최종 판단 기준이 아닙니다. 일부 서비스는 YAML을 text/plain으로 표시해도 정상적으로 사용할 수 있습니다. 반대로 응답 헤더에 YAML이라고 적혀 있어도 본문의 문법과 구조가 올바르다는 보장은 없습니다.

전체 설정, 노드 목록, 인코딩된 구독 구분하기

‘응답이 YAML이다’라는 확인만으로는 충분하지 않습니다. Mihomo 전체 설정, proxy-providers에서 사용하는 노드 목록, URI 또는 Base64 형식의 노드 구독은 서로 다른 입력입니다. 해당 내용을 변환하는 기능이 있는지는 클라이언트 구현에 따라 다르며, 모든 클라이언트가 자동 변환을 지원한다고 볼 수 없습니다.

내용의 특징 일반적인 용도 흔한 오용
프록시 소스, 정책 그룹, 규칙 포함 전체 설정으로 불러오기 존재하지 않는 노드나 정책 그룹 참조
proxies:가 중심인 노드 목록 proxy-providers에서 참조 모든 정책과 라우팅 규칙이 포함된 것으로 오해
여러 줄의 ss://, vmess:// 링크 또는 인코딩된 텍스트 해당 형식을 지원하는 가져오기 도구로 변환 커널 YAML 설정으로 바로 불러오기
<!DOCTYPE html> 또는 <html> 웹페이지 또는 접근 차단 응답 확장자를 YAML로 바꿔 해결하려고 시도

YAML 줄 번호와 필드 유형

로그에서 18번째 줄을 가리켜도 문제의 원인이 반드시 그 줄에 있는 것은 아닙니다. 앞줄에 콜론이 빠졌거나 따옴표가 닫히지 않으면 다음 줄에서 파서 오류가 날 수 있습니다. 오류가 표시된 줄의 앞뒤를 최소 3줄씩 확인하고, 탭 대신 공백으로 들여쓰기하세요.

# 구조 예시이며, 그대로 인터넷에 연결할 수 있는 완성 설정은 아닙니다
proxies: []
proxy-groups:
  - name: 수동 선택
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,수동 선택

이 예시는 목록과 들여쓰기 구조를 확인하기 위한 것으로 프록시 노드는 포함하지 않습니다. 실제 설정에서는 규칙 대상, 정책 그룹 이름, 노드 이름이 정확히 일치해야 합니다. 한글 문장부호, 줄 끝의 공백, 대소문자 차이로 참조 대상을 찾지 못할 수도 있습니다.

문법 통과와 커널 지원 여부 구분하기

YAML 문법이 올바르더라도 현재 커널이 해당 프로토콜, 전송 방식, 필드를 지원한다는 뜻은 아닙니다. 먼저 클라이언트의 ‘정보’ 또는 커널 정보 페이지에서 실제 커널 버전을 확인한 뒤 해당 버전의 지원 범위를 살펴보세요. 클라이언트 버전과 커널 버전은 다릅니다.

더 자세히 확인하려면 접근이 제한된 디렉터리에 전체 설정을 저장한 후 로컬 Mihomo에서 mihomo -t -f config.yaml을 실행해 설정을 검사할 수 있습니다. 이 검사는 인터넷 연결 여부를 확인하는 테스트가 아닙니다. 외부 리소스를 사용하는 설정이라면 리소스 로드 로그도 확인하세요. 검토하지 않은 설정으로 서비스를 바로 활성화하지 마세요.

User-Agent와 구독 응답 형식

일부 구독 서비스는 User-Agent에 따라 반환할 설정 형식을 결정합니다. 같은 주소가 브라우저에서는 안내 페이지를, 클라이언트에서는 YAML을 반환하거나 그 반대인 경우 이 방식과 관련이 있을 수 있습니다. 요청 헤더를 무작정 바꾸기보다 제공업체가 Mihomo용으로 안내한 구독 경로를 우선 사용하세요.

  1. 주소, 네트워크, 테스트 시간을 비슷하게 유지하고 User-Agent만 변경하세요. 여러 변수를 동시에 바꾸지 마세요.
  2. 먼저 클라이언트 로그에서 확인할 수 있는 요청 정보를 기록한 다음, 제공업체 문서에 명시된 User-Agent 값을 확인하세요.
  3. curl의 --user-agent로 비교 테스트를 하고 각 결과를 따로 저장해 상태 코드와 본문 구조를 비교하세요.
  4. 결과를 확인한 다음 클라이언트에서 구독 요청에만 해당 헤더를 설정할 수 있는지 살펴보세요. 브라우저 설정만 바꾸지 마세요.

예를 들어 제공업체가 해당 식별자를 지원한다고 명시한 경우 --user-agent 'clash.meta'로 테스트할 수 있습니다. 모든 구독 서비스에 통하는 해결책은 아니며 현재 커널과 호환되는 설정이 반환된다는 보장도 없습니다. 응답이 여전히 로그인 페이지나 403이라면 식별자를 계속 바꾸지 말고 인증과 네트워크 제한을 확인하세요.

네트워크, DNS, 프록시를 통한 업데이트 경로

브라우저는 접속되는데 클라이언트는 시간 초과되는 경우

먼저 요청이 같은 네트워크 경로를 사용하는지 확인하세요. 브라우저는 시스템 프록시를 사용할 수 있지만 구독 업데이트 기능은 직접 연결, 내장 프록시 또는 별도로 설정된 다운로드 경로를 사용할 수 있습니다. 시스템 프록시를 켰다고 모든 프로세스가 자동으로 이를 사용하는 것은 아닙니다.

클라이언트에 ‘프록시를 통해 구독 업데이트’와 같은 옵션이 있다면 현재 프록시가 작동하는지 먼저 확인하세요. 구독이 만료되고 노드에도 연결할 수 없다면 기존 노드를 통해 업데이트하려다 의존성 문제가 생길 수 있습니다. 사용 가능한 설정을 보관한 뒤 제공업체가 지원하는 방식으로 다른 네트워크 경로를 시도하세요.

  • DNS: no such host가 표시되면 도메인 철자와 시스템 DNS 조회를 먼저 확인하세요. 변경될 수 있는 서비스 IP를 임의로 고정하지 마세요.
  • 프록시 포트: 로컬 HTTP 프록시를 127.0.0.1:7890으로 설정했다면 클라이언트가 실제로 해당 포트를 수신 중인지 확인하세요. 7890은 예시일 뿐 모든 클라이언트의 기본값은 아닙니다.
  • TUN: TUN은 프로세스의 트래픽 경로를 바꿀 수 있지만 잘못된 YAML을 고치지는 못합니다. 전환하기 전에 현재 설정을 기록하고 테스트 후 원래대로 되돌려 두 문제를 혼동하지 않도록 하세요.
  • TLS: 인증서 오류가 발생하면 시스템 날짜와 시간대, 구독 도메인, 네트워크 인증 페이지를 확인하세요. 인증서 검증을 바로 끄지 마세요.

별도 네트워크에서 비교 테스트하기

가능하다면 휴대전화 핫스폿과 기존 네트워크에서 각각 요청해 보세요. 링크와 User-Agent는 그대로 유지합니다. 한쪽 네트워크에서만 HTML 차단 페이지가 반환되거나 연결 시간이 초과되면 네트워크 경로를 집중적으로 확인하세요. 양쪽에서 같은 형식 오류가 일관되게 발생하면 구독 내용과 클라이언트 호환성을 다시 살펴보세요.

curl의 --noproxy '*'는 curl에 명시적으로 설정된 프록시 사용을 제외할 수 있지만 시스템 TUN, 라우팅 규칙, 네트워크 출구 장비를 우회하지는 않습니다. 따라서 이 옵션을 사용해도 실패한다는 이유만으로 직접 연결 경로가 문제라고 단정할 수 없습니다.

가져오기 복구와 최소한의 오류 제보

변경한 뒤 수동 업데이트를 한 번 실행해 설정 파싱이 완료되는지 확인한 다음 새 설정으로 연결을 테스트하세요. 구독 업데이트 성공은 내용이 수신되고 처리됐다는 뜻일 뿐, 모든 노드가 작동하거나 DNS, 시스템 프록시, 라우팅 규칙이 모두 설정됐다는 뜻은 아닙니다.

  1. 구독 업데이트 시각, 노드 수, 예상한 정책 그룹이 있는지 확인하세요.
  2. 로드 로그에서 지원되지 않는 노드 유형, 프로바이더 다운로드 실패, 누락된 규칙 대상 등의 오류가 없는지 확인하세요.
  3. 접속 가능한 것으로 알려진 테스트 대상에 연결하고 연결 로그에서 적용된 규칙, 정책 그룹, 출구를 확인하세요.
  4. 이전 설정을 복구할 수 있도록 보관하고 새 설정이 안정적으로 작동하는지 확인한 뒤 임시 응답 파일을 정리하세요.

계속 실패할 때 함께 전달할 정보

클라이언트 유지관리자나 구독 제공업체에 문의할 때 운영체제, 클라이언트 버전, 커널 버전, 실패 시각, HTTP 상태 코드, 민감 정보를 가린 첫 번째 오류, 직접 연결과 프록시 업데이트 비교 결과를 첨부하세요. 형식 문제라면 들여쓰기를 유지한 최소한의 코드 조각을 제공하고, 전체 구독 링크와 노드 인증 정보는 보내지 마세요.

점검 순서는 링크와 인증 확인, 응답 본문 확인, 형식과 커널 지원 확인, 요청 헤더와 네트워크 경로 비교로 정리할 수 있습니다. 한 번에 변수 하나만 바꾸면 ‘가끔 성공’하는 상황을 잘못 판단할 가능성이 줄고, 다음 구독 업데이트에서도 같은 문제를 재현하고 해결하기 쉽습니다.