Clash 구독 형식 완벽 정리: YAML, Base64, 구독 변환 제대로 쓰는 법

구독 링크란 정확히 무엇인가

구독 링크는 클라이언트가 주기적으로 요청을 보내는 HTTP/HTTPS 주소입니다. 이 요청에 대한 응답에는 다수의 노드 정보가 담겨 있고, 경우에 따라 분기 규칙도 함께 포함됩니다. 클라이언트는 이 내용을 받아 약속된 형식대로 노드 목록을 파싱하고, 로컬 설정 파일에 기록해 프록시 엔진이 사용할 수 있게 만듭니다. 구독을 제대로 이해하려면 두 가지 층위를 구분해야 합니다. 하나는 '노드 정보를 어떻게 표현하는가', 다른 하나는 '설정 파일 전체를 어떻게 구성하는가'입니다. 전자는 한 줄짜리 노드 링크의 작성 방식을 결정하고, 후자는 구독 파일 전체의 구조를 결정합니다. 많은 사용자가 구독 문제를 진단할 때 링크 자체에만 집중하고 클라이언트가 실제로 어떤 구조를 기대하는지는 놓치는데, 이는 형식 관련 오류에서 가장 흔한 착각입니다.

Clash 계열 클라이언트(Mihomo 코어 기반 파생 클라이언트 포함)는 기본적으로 YAML 구조화 설정 파일을 인식하지만, 서버(일명 '기장/airport') 운영자나 구축자가 처음 생성하는 것은 대개 범용 노드 공유 링크입니다. 따라서 둘을 연결하려면 변환 과정이 필요합니다. 이 변환이 얼마나 매끄럽게 이뤄지느냐에 따라 구독 업데이트의 안정성, 규칙의 완전성, 노드 누락 여부가 결정됩니다.

3가지 주요 형식 분석

Clash YAML 기본 설정

이는 Clash 클라이언트가 가장 직접적으로 인식하는 형식으로, 완전한 파일에는 보통 proxies(노드 목록), proxy-groups(정책 그룹), rules(분기 규칙), 그리고 선택적으로 dns, tun 등의 필드가 포함됩니다. 각 노드는 딕셔너리 형태로 작성되며 필드명이 고정되어 있습니다. 예를 들면:

proxies:
  - name: "HK-01"
    type: ss
    server: example.com
    port: 443
    cipher: aes-256-gcm
    password: "your-password"

YAML은 들여쓰기에 극도로 민감해서 스페이스 한 칸만 어긋나도 설정 파일 전체가 파싱에 실패할 수 있습니다. 클라이언트는 대개 '설정이 유효하지 않음'이라고만 표시하고 구체적으로 어느 줄이 문제인지는 알려주지 않는데, 이 부분이 구독 변환 과정에서 가장 오류가 잦은 지점입니다.

범용 Base64 노드 링크

서버 측에서 널리 쓰는 공유 형식으로, 보통 ss://, vmess://, trojan://로 시작하는 한 줄짜리 텍스트 형태입니다. 프로토콜 헤더 뒤에 Base64로 인코딩된 파라미터 묶음이 붙어 있으며, 디코딩하면 서버 주소, 포트, 암호화 방식 등의 필드를 확인할 수 있습니다. 구독 링크가 반환하는 내용은 대개 이런 텍스트 여러 줄을 이어 붙인 뒤 전체를 다시 한 번 Base64로 인코딩한 형태이므로, 클라이언트나 변환 도구는 먼저 바깥쪽 디코딩을 수행한 다음 각 줄의 노드 링크를 개별적으로 파싱해야 합니다. 이 형식의 장점은 클라이언트 간 호환성이 뛰어나서 대부분의 주요 도구가 인식한다는 점이고, 단점은 정책 그룹이나 규칙 정보를 포함하지 않고 노드 정보만 담을 수 있다는 점입니다.

클라이언트 전용 형식

일부 클라이언트는 YAML을 기반으로 자체 필드를 확장합니다. 예를 들어 그룹의 표시 스타일, 아이콘 주소, 특정 DNS 작성 방식 등이 있습니다. 이런 확장 필드는 표준 Clash 코어 입장에서는 무해한 여분의 정보에 불과하지만, A 클라이언트에서 내보낸 설정을 그대로 B 클라이언트에 가져다 쓰면 B 클라이언트가 특정 전용 필드를 인식하지 못해 오류를 내거나, 아예 무시해버려 일부 기능이 빠지는 경우가 생깁니다. 이것이 '같은 구독인데 클라이언트만 바꾸면 문제가 생기는' 현상의 원인 중 하나입니다.

구독 변환 서비스의 동작 원리

구독 변환 서비스는 본질적으로 형식 번역 계층입니다. 먼저 원본 구독 주소에 요청을 보내 Base64나 그 외 형식의 노드 목록을 받아온 뒤, 서버 주소, 포트, 프로토콜, 암호화 파라미터 등의 정보를 한 줄씩 디코딩합니다. 그런 다음 목표 클라이언트가 인식하는 템플릿에 맞춰 YAML 설정 파일로 다시 조립하며, 필요에 따라 미리 정의된 규칙 세트에 맞춰 proxy-groups와 rules를 삽입할 수 있습니다. 전체 과정은 원본 콘텐츠 가져오기, 노드 필드 파싱, 템플릿 기반 재구성이라는 세 단계로 요약할 수 있습니다.

변환 서비스를 사용할 때 실제로 클라이언트에 입력하는 구독 주소는 서버에서 제공한 원본 링크가 아니라 변환 서비스가 생성한 새 주소입니다. 형식은 대략 '변환 서비스 도메인 + 파라미터(원본 구독 주소, 목표 형식, 규칙 템플릿 포함)'입니다. 클라이언트가 구독을 새로고침할 때마다 이 변환 주소로 요청을 보내고, 변환 서비스는 그때마다 실시간으로 서버의 원본 구독을 요청해 변환한 뒤 결과를 클라이언트에 돌려줍니다. 즉 변환 서비스가 전체 연결 고리의 중간 단계로 끼어드는 셈이라, 이 서비스에 문제가 생기면 구독 새로고침도 함께 실패합니다. 문제를 진단할 때 이 점이 자주 간과됩니다.

규칙 템플릿을 선택할 때는 버전 호환성에 주의해야 합니다. 일부 템플릿은 구버전 Clash용으로 작성되어 있어서, 포함된 필드가 신버전 코어에서는 이미 폐기되었거나 이름이 바뀐 경우가 있습니다. 이런 템플릿을 불러오면 정책 그룹이 이상하게 표시되지만 오류 메시지는 뜨지 않아서, 구독 자체의 문제로 오해하기 쉽습니다.

변환 실패의 흔한 원인 진단

구독 변환 실패는 대체로 4가지 원인으로 나뉘며, 발생 빈도가 높은 순서로 정리하면 다음과 같습니다.

1. 원본 구독 주소 자체에 접근할 수 없는 경우.변환 서비스는 먼저 원본 콘텐츠를 가져와야 변환을 진행할 수 있습니다. 서버 링크가 만료되었거나 트래픽 제한이 걸렸거나 특정 지역 네트워크에서만 접근 가능한 경우, 변환 단계에서 곧바로 실패하며 오류 메시지는 형식 문제가 아니라 '구독을 가져올 수 없음'으로 표시되는 경우가 많습니다.
2. 변환 서비스가 지원하지 않는 노드 프로토콜인 경우.비교적 새로운 프로토콜을 변환 서비스의 템플릿 라이브러리가 아직 지원하지 않으면, 파싱 시 해당 노드를 건너뛰어 버려서 변환 후 노드 수가 원본 구독보다 눈에 띄게 줄어듭니다.
3. 규칙 템플릿과 목표 코어 버전이 맞지 않는 경우.템플릿에 신버전 코어에서만 존재하는 필드가 포함되어 있으면, 구버전 클라이언트는 불러올 때 오류를 내거나 해당 필드를 무시하며, 정책 그룹이나 분기 규칙이 비정상적으로 동작합니다.
4. 특수 문자 이스케이프 처리 문제.노드 별칭에 콜론, 인용부호 등 YAML 특수 문자가 포함되어 있는데 변환 과정에서 이스케이프 처리가 제대로 되지 않으면, 생성된 파일의 문법 구조가 깨져서 이후 모든 필드 파싱이 통째로 실패합니다.

진단할 때는 다음 순서를 권장합니다. 먼저 원본 구독 주소를 직접 열어 정상적으로 접근되는지 확인하고, 그다음 변환 후 노드 수가 서버 관리 페이지에 표시된 노드 수와 일치하는지 비교하며, 마지막으로 생성된 YAML에 들여쓰기 오류나 이스케이프 처리되지 않은 특수 문자가 있는지 확인합니다. 대부분의 문제는 이 세 단계 안에서 구체적인 원인을 찾을 수 있습니다.

다른 클라이언트로 구독 이전하는 절차

Clash 클라이언트를 교체할 때 같은 구독 주소를 그대로 재사용하는 것은 대체로 가능합니다. 주요 클라이언트들이 표준 YAML 구조를 호환하기 때문입니다. 다만 전용 필드나 기본 정책 그룹 명명 방식의 차이는 유의해야 합니다. 다음 순서를 권장합니다.

• 새 클라이언트에 구독을 별도로 먼저 추가하고, 기존 클라이언트의 설정은 바로 삭제하지 말고 되돌릴 수 있는 대조군으로 남겨두세요.
• 추가가 끝나면 수동으로 구독 업데이트를 한 번 실행해, 노드 수가 기존 클라이언트와 일치하는지 확인하세요.
• 정책 그룹 화면을 열어 그룹과 규칙 세트가 정상적으로 로드되는지 확인하고, 특히 자동 속도 테스트 그룹이 정상적으로 노드를 선택하는지 살펴보세요.
• 일부 사용자 정의 규칙이 사라졌다면, 대개 기존 클라이언트에서 로컬 규칙을 수동으로 추가했던 경우입니다. 이런 내용은 구독과 함께 동기화되지 않으므로 새 클라이언트에서 다시 추가해야 합니다.
• 이상이 없음을 확인한 뒤에 기존 클라이언트의 시스템 프록시나 TUN 모드를 종료하세요. 두 클라이언트가 동시에 네트워크 출구를 점유해 충돌이 생기는 것을 막기 위함입니다.

구독이 변환 서비스를 통해 생성된 것이라면, 이전할 때는 이전 클라이언트가 생성한 변환 결과를 그대로 복사해 쓰기보다 원본 서버 구독 주소를 다시 변환 과정에 넣어 새 주소를 만드는 방식을 권장합니다. 이렇게 하면 새 클라이언트가 자신의 버전에 맞게 조정된 규칙 템플릿을 확실히 받아볼 수 있습니다.

정리

구독 형식 문제는 복잡해 보이지만 뜯어보면 세 가지 단계뿐입니다. 노드 정보 자체를 어떻게 인코딩하는지, 설정 파일 전체를 어떻게 구성하는지, 그리고 중간에 변환 서비스를 거쳤는지 여부입니다. 구독을 불러올 수 없거나 클라이언트를 옮긴 뒤 기능이 이상해질 때는 먼저 어느 단계에서 문제가 생겼는지 파악하고, 이 글에서 안내한 순서대로 하나씩 확인해보세요. 대부분의 형식 관련 오류는 몇 분 안에 원인을 찾아 해결할 수 있습니다.