1. 증상을 문장으로 정의하기
먼저 「노드가 없다」가 무엇을 의미하는지 나눕니다. ① 코어가 구성 로드에 실패해 아예 기동하지 못하는 경우, ② 구성은 올라갔지만 proxies 섹션이 비어 있거나 Provider가 빈 목록을 돌려준 경우, ③ 노드는 있는데 UI의 특정 그룹에만 안 보이는 경우는 원인이 다릅니다. 첫 번째는 보통 YAML 문법 오류나 지원하지 않는 키 때문에 로그에 파싱 에러가 남습니다. 두 번째는 구독 URL이 HTML 오류 페이지·빈 파일·잘못된 인코딩을 주거나, Subscription Converter 출력 형식이 기대와 다를 때 흔합니다. 세 번째는 proxy-groups의 proxies 목록에 이름이 빠졌거나 use로 묶어야 할 Provider를 빠뜨린 경우가 많습니다.
안드로이드에서 구독 URL 자체가 안 받아지는 증상은 Clash Meta Android 구독 가져오기 글과 겹치고, 본문은 「가져오기는 됐는데 목록이 비는」 쪽에 초점을 둡니다. 전체 구성 개념은 Clash 문서·FAQ와 함께 보시면 흐름이 잡힙니다.
2. 원격 응답이 진짜 노드인지
Clash 구독 URL을 PC 브라우저나 curl로 열어 첫 수백 바이트를 확인하세요. 기대하는 것은 proxies:로 시작하는 YAML 조각, 혹은 클라이언트가 디코딩할 수 있는 Base64 묶음입니다. 대신 <html·401 Unauthorized·짧은 플레인 텍스트 한 줄만 있는 경우, 클라이언트가 「다운로드 성공」으로 표시해도 파싱 결과 proxies 개수 0이 될 수 있습니다. 토큰 만료·IP 제한·User-Agent 요구·중간 프록시가 HTML 에러를 돌려주는 경우도 같은 증상으로 이어집니다.
형식 혼동
일부 패널은 동일 링크에 대해 「Clash」「V2Ray」「Sing-box」 등 여러 포맷을 고릅니다. Clash용이 아닌 JSON·리스트만 내려오면 코어가 무시하거나 전부 건너뛸 수 있으니, 제공자 설정에서 Clash(Mihomo) 호환 출력인지 다시 확인합니다. 변환기를 사이에 두었다면 변환 규칙 업데이트 후 캐시된 중간 결과가 빈 proxies를 만들지 않는지도 봅니다.
proxy-providers 아래의 특정 name을 참조하는데 새 구독 이름이 달라져 목록이 비어 보일 수 있습니다.
3. proxy-providers와 병합
최신 템플릿은 노드를 proxies:에 직접 쓰지 않고 proxy-providers로 원격에서 끌어온 뒤, 프록시 그룹에서 use:로 묶는 패턴이 많습니다. 이때 UI가 「구독」탭과 「Provider」탭을 분리해 두었다면, 사용자는 구독만 봤다가 Provider 쪽이 비어 있다고 느낄 수 있습니다. 설정 파일에서 각 provider의 url·path·type(http 등)·health-check가 유효한지 확인하고, 코어 로그에 provider fetch failed 류 메시지가 없는지 봅니다.
# Minimal pattern (illustrative)
proxy-providers:
sub1:
type: http
url: "https://example.com/sub"
path: ./providers/sub1.yaml
interval: 3600
health-check:
enable: true
url: https://www.gstatic.com/generate_204
interval: 600
proxy-groups:
- name: PROXY
type: select
use:
- sub1use에 적은 이름은 proxy-providers의 키와 정확히 같아야 합니다. 대소문자·공백 한 칸 차이도 참조 실패로 이어질 수 있습니다.
4. YAML 파싱·이름 참조
Clash·Mihomo 구성은 YAML 파싱을 통과해야 합니다. 탭과 스페이스를 섞거나, 병합(! 앵커·별칭) 계층이 깨지면 일부 키만 사라진 것처럼 보일 수 있습니다. proxy-groups 항목이 - name: X인 노드를 참조하는데 실제 proxies 목록에 X가 없으면, 그룹은 비어 있거나 시작 시 경고를 냅니다. 패치 규칙(patches)이나 외부 스니펫을 끼워 넣는 구조라면, 적용 순서가 뒤바뀌어 proxies 블록이 통째로 덮인 경우도 있습니다.
인코딩
원격 파일이 UTF-8이 아닌 인코딩이면 한글 주석만 깨지는 수준을 넘어 파서가 중단될 수 있습니다. 로컬에서 편집할 때는 UTF-8(무 BOM)을 유지하고, 보이지 않는 BOM 문자가 맨 앞에 붙지 않았는지 확인합니다.
5. Provider 캐시·강제 갱신
proxy-providers에 path:로 로컬 파일을 지정하면, 코어는 원격을 받아 그 경로에 캐시합니다. 한번 네트워크 오류로 빈 파일·HTML이 쓰였다면, 다음 갱신까지 그 내용을 붙잡는 것처럼 보일 수 있습니다. 클라이언트에 「Provider 업데이트」「캐시 삭제」 메뉴가 있으면 해당 Provider만 다시 받게 하고, 없다면 앱을 종료한 뒤 설정에 적힌 캐시 디렉터리에서 해당 YAML을 지우고 재시작하는 방법도 있습니다. 이때 경로는 OS·클라이언트마다 다르므로 공식 문서·데이터 폴더 열기 메뉴를 따릅니다.
동시에 interval이 지나치게 길게 잡혀 있으면 사용자가 수동 새로고침을 하지 않는 한 오래된 스냅샷이 남습니다. 문제 재현 직후에는 수동 업데이트를 한 번 실행해 원격과 로컬이 일치하는지 확인하는 것이 좋습니다.
6. 프록시 그룹·USE
노드가 전역 목록에는 있는데 선택 그룹에만 없다면, 그룹 정의의 proxies: 리스트와 use: 블록을 의심합니다. url-test·fallback 그룹은 하위 후보가 비면 동작이 이상해 보일 수 있습니다. 또한 DIRECT만 남은 그룹은 규칙상 직결로만 나가므로 「프록시가 없다」고 느낄 수 있습니다. 템플릿이 rule-providers와 함께 쓰이는 경우, 규칙 파일이 아직 내려받기 전이라 기본 정책만 타는지도 함께 봅니다.
DNS·가짜 IP 설정이 꼬이면 연결은 되지만 특정 앱만 실패하는 등 다른 그림이 나올 수 있어, 그 경우 fake-ip·DNS 점검 글과 대조해 보세요. TLS 단계에서만 끊기면 TLS handshake 진단 순서가 더 맞습니다.
7. 로그로 좁히기
코어 로그에서 다음 키워드를 찾습니다. can't unmarshal·yaml·parse는 구문 문제, fetch·timeout·403는 원격 수신 문제, provider·empty는 Provider 경로·응답 본문 문제에 가깝습니다. 로그 한 줄과 타임스탬프를 남겨 두면 이후 설정 변경과 대조하기 쉽습니다. GUI가 로그를 가리면 설정 디렉터리의 로그 파일을 직접 열어도 됩니다.
Windows에서 LAN·방화벽 이슈와 겹치면 Mixed Port·방화벽 구성도 함께 점검합니다. 데스크톱과 모바일에서 동일 프로필을 쓴다면, 한쪽만 비는지 비교 실험이 빠른 분기입니다.
8. 증상 표
| 표면 증상 | 흔한 원인 | 먼저 할 일 |
|---|---|---|
| 갱신 성공인데 목록 0개 | HTML·오류 응답, 잘못된 포맷 | URL 원문 확인, UA·토큰 점검 |
| Provider 탭만 비어 있음 | proxy-providers fetch 실패 |
로그 확인, 캐시 삭제 후 재수신 |
| 시작 시 YAML 에러 | 들여쓰기·탭·이름 불일치 | UTF-8 정리, 참조 이름 통일 |
| 전역엔 있는데 그룹엔 없음 | use 누락·오타 |
그룹 정의와 provider 키 대조 |
| 가끔만 비었다가 돌아옴 | 간헐 차단·서버 부하 | 재시도, health-check URL 변경 |
한 번에 한 가지 변경만 적용하면 원인 추적이 빨라집니다. 구독 URL·로컬 패치·규칙 저장소를 동시에 바꾸면 어느 쪽이 결정타였는지 알기 어렵습니다.
10. 요약
Clash 구독이 갱신됐다고 떠도 노드 목록이 비어 있으면, (1) 브라우저나 curl로 원격 본문이 진짜 Clash용 proxies인지 확인하고, (2) proxy-providers 구조라면 use와 키 이름·fetch 로그를 맞추며, (3) YAML 파싱·인코딩·이름 참조를 정리하고, (4) Provider 캐시를 비운 뒤 수동 갱신으로 최신 스냅샷을 받습니다. 이렇게 네 단계면 「HTTP는 됐는데 파싱 결과가 0」류의 함정을 대부분 건너뛸 수 있습니다.
규칙 기반 클라이언트는 텍스트 설정과 로그가 열려 있을수록 복구가 빠릅니다. 한 번 통과한 체크리스트를 프로필 폴더에 메모해 두면 다음에 구독 URL을 바꿀 때도 같은 삽질을 줄일 수 있습니다.