서론: 규칙셋을 분리해야 하는 이유
Clash 설정을 오래 운영하다 보면 rules 항목이 수백 줄로 늘어나기 쉽습니다. 도메인 목록을 직접 관리하는 방식은 처음에는 단순하지만, 규칙을 추가하거나 여러 기기에서 같은 목록을 사용하려 할 때 수정 누락과 설정 충돌이 생기기 쉽습니다. rule-providers는 규칙 목록을 별도의 파일로 분리하고, 메인 설정에서는 그 목록을 참조하도록 해 주는 기능입니다.
규칙셋을 분리하면 메인 YAML을 간결하게 유지하면서도 도메인 목록을 독립적으로 업데이트할 수 있습니다. 예를 들어 개인적으로 관리하는 서비스 목록은 GitHub 저장소에 올리고, Clash 설정에서는 해당 파일의 주소와 업데이트 주기를 지정할 수 있습니다. 이후에는 RULE-SET 규칙을 통해 목록에 해당하는 트래픽을 원하는 정책 그룹으로 보냅니다.
적용 전 확인
rule-providers 설정은 사용 중인 코어의 지원 여부와 문법에 영향을 받습니다. 이 가이드는 Mihomo를 기준으로 설명하며, 구형 코어에서는 일부 필드나 동작이 다를 수 있으므로 코어 버전과 클라이언트 로그를 함께 확인하세요.
1rule-providers 필드와 YAML 구성
rule-providers에는 규칙셋의 이름과 가져오는 방식, 규칙의 종류, 저장 위치, 원격 주소, 갱신 간격을 선언합니다. 아래 예시는 GitHub의 공개 저장소에서 규칙 파일을 가져오는 기본적인 구성입니다. url은 브라우저에서 파일 내용만 표시되는 Raw 주소를 사용해야 합니다.
- 이름:
custom-domains는 메인 설정의RULE-SET에서 참조할 식별자입니다. 공백 없이 명확한 이름을 사용하고, 참조하는 쪽의 이름과 철자 및 대소문자를 일치시키세요. - type:
http는 원격 주소에서 파일을 내려받는 방식을 뜻합니다. 로컬 파일을 읽는 구성이 필요하다면 사용 중인 Mihomo 문서에서 지원하는 타입과 경로 규칙을 확인해야 합니다. - behavior:
domain,ipcidr,classical중 규칙 데이터의 성격에 맞는 유형을 선택합니다. 도메인만 모은 목록에는domain, IP 대역에는ipcidr, 여러 종류의 Clash 규칙을 담은 목록에는classical이 적합합니다. - format:
yaml은 파일이 YAML 형식임을 나타냅니다. 원격 파일의 실제 형식과 설정값을 맞춰야 하며, 확장자만 YAML로 바꾼다고 데이터 형식이 변하지는 않습니다. - path: 내려받은 파일을 저장할 위치입니다. 상대 경로가 어느 설정 디렉터리를 기준으로 해석되는지는 실행 환경에 따라 확인하고, 폴더 생성 및 파일 쓰기 권한도 점검하세요.
- interval: 업데이트 확인 간격을 초 단위로 지정합니다. 예시의
86400은 하루입니다. 자주 바뀌지 않는 목록은 불필요하게 짧은 간격으로 설정하지 않는 편이 GitHub 요청과 로그를 관리하기 쉽습니다.
behavior와 파일 내부 구조는 함께 맞춰야 합니다. 특히 classical 규칙셋은 일반 rules에서 쓰는 규칙 형식의 항목들을 담을 수 있지만, domain 규칙셋에 DOMAIN-SUFFIX 같은 규칙 전체를 넣는 방식은 기대한 대로 처리되지 않을 수 있습니다. 규칙 목록의 의미와 형식을 먼저 정한 뒤 provider 유형을 선택하세요.
2GitHub에 규칙 파일 배포하기
GitHub 저장소에는 Clash 메인 설정 전체를 올리기보다, 재사용할 규칙셋 파일만 별도로 두는 방식이 관리에 유리합니다. 저장소를 공개로 설정하고 규칙 파일을 커밋한 다음, 해당 파일의 Raw 주소를 provider의 url에 입력합니다. 예시 주소의 example-user와 저장소 이름은 실제 값으로 바꾸어야 합니다.
behavior: domain으로 도메인 전용 목록을 만들 경우에는 다음처럼 payload에 도메인 항목을 기록할 수 있습니다. 루트에 payload가 있는 YAML 구조를 사용하고, 들여쓰기를 일관되게 유지하세요.
도메인 규칙은 일치 범위를 고려해 작성해야 합니다. 하위 도메인을 포함하려는 항목과 특정 호스트만 대상으로 하는 항목은 의미가 다를 수 있으므로, 목록에 넣은 패턴이 의도한 범위인지 검토하세요. 규칙을 너무 넓게 작성하면 관계없는 서비스까지 같은 프록시 정책에 묶일 수 있습니다.
- Raw 주소 확인: 링크를 열었을 때 GitHub의 파일 편집 화면이 아니라 파일 본문이 표시되는지 확인합니다. 로그인 요구, 404 응답, 저장소 접근 제한이 있으면 Clash도 파일을 가져오지 못할 수 있습니다.
- 커밋 단위로 변경: 규칙을 수정할 때 변경 내용을 커밋하면 어떤 항목을 언제 바꿨는지 추적하기 쉽습니다. 여러 사람이 관리한다면 변경 목적과 영향을 간단히 기록하세요.
- 민감 정보 제외: 공개 저장소에는 구독 주소, 인증 토큰, 개인 IP 등 비공개 정보가 포함된 설정을 올리지 마세요. 규칙셋은 공개해도 안전한 데이터만 분리해 관리하는 것이 좋습니다.
- 업데이트 가능한 주소 사용: 브랜치 경로는 해당 브랜치의 최신 파일을 가리킵니다. 변경을 고정해 검증하려는 운영 환경에서는 별도 버전 경로나 관리 절차를 고려하고, 주소가 실제로 유지되는지 주기적으로 점검하세요.
배포 전 주의사항
GitHub Raw 주소가 브라우저에서 열린다는 사실만으로 모든 네트워크 환경에서 다운로드가 보장되지는 않습니다. 사용 중인 네트워크에서 GitHub 접근이 제한되거나 일시적인 응답 오류가 발생하면 provider 업데이트가 실패할 수 있습니다.
3RULE-SET으로 트래픽에 적용하기
provider를 선언하는 것만으로는 트래픽 경로가 바뀌지 않습니다. 메인 설정의 rules에서 provider 이름을 RULE-SET으로 참조하고, 뒤에 적용할 정책 그룹을 지정해야 합니다. 다음 예시에서는 목록에 등록된 도메인을 PROXY 그룹으로 보냅니다.
custom-domains는 앞에서 선언한 provider 이름과 정확히 같아야 하며, PROXY는 실제 설정의 프록시 그룹 이름이어야 합니다. 그룹 이름이 존재하지 않거나 철자가 다르면 설정 검사에서 오류가 나거나 예상과 다른 결과가 생길 수 있습니다. 사용하는 구성에 맞춰 정책 이름을 바꾸고, 먼저 작은 규칙셋으로 동작을 확인하세요.
규칙은 위에서 아래로 평가되므로, 이미 더 넓은 범위의 규칙이 앞에 있으면 provider의 규칙까지 도달하지 않을 수 있습니다. 예를 들어 provider보다 앞에 광범위한 도메인 규칙이나 일치 범위가 넓은 규칙이 있다면, 대상 트래픽이 먼저 그 규칙에 매칭될 수 있습니다. 예외 규칙과 세부 규칙을 먼저 배치하고, 일반 규칙과 MATCH는 그 뒤에 두는 구성이 보통 확인하기 쉽습니다.
- 메인 YAML에서
rule-providers이름과RULE-SET참조 이름이 일치하는지 비교합니다. - provider가 가리키는 Raw 주소와 파일 형식,
behavior값을 확인합니다. rules에서 provider 규칙이 일반 규칙이나 최종MATCH보다 먼저 평가되는 위치인지 살펴봅니다.- Clash Verge, Clash Verge Rev 또는 사용 중인 클라이언트에서 프로필을 다시 적용하고, 규칙 검사와 연결 기록에서 실제 매칭 항목을 확인합니다.
GUI 클라이언트마다 규칙 목록과 업데이트 버튼의 위치는 다르지만 확인 원칙은 같습니다. 연결 로그에서 대상 도메인에 어떤 규칙이 매칭되었는지 보고, 해당 연결이 의도한 프록시 그룹이나 DIRECT로 전달되는지 점검하세요. 이름이 비슷한 규칙셋이 여러 개라면 로그에서 식별하기 쉽도록 provider 이름을 구체적으로 정하는 것도 도움이 됩니다.
4업데이트 오류와 장기 운영 점검
규칙셋이 예상대로 적용되지 않을 때는 정책 그룹부터 바꾸기보다 다운로드, 파일 형식, 매칭 순서를 차례로 확인하는 것이 효율적입니다. provider 업데이트 실패와 규칙 미일치는 서로 다른 문제이므로, 클라이언트의 코어 로그와 연결 로그를 구분해 살펴보세요.
- 다운로드 실패: Raw URL의 오탈자, 저장소 공개 여부, 파일 이동 또는 이름 변경, 네트워크에서 GitHub에 접근 가능한지를 확인합니다. 응답이 404이거나 HTML 오류 페이지라면 규칙 YAML로 처리할 수 없습니다.
- YAML 파싱 오류: 들여쓰기, 콜론, 따옴표와 리스트 구조를 점검합니다. 탭 대신 공백을 사용하고, 파일을 직접 편집한 뒤에는 GitHub에 커밋된 내용이 로컬에서 검토한 내용과 같은지도 확인하세요.
- 지원되지 않는 필드: 코어 버전이
format이나 사용한 provider 동작을 지원하는지 확인합니다. GUI 이름이 같아도 실제 코어 종류와 버전이 다를 수 있으므로, 클라이언트의 코어 정보와 Mihomo 호환성을 확인하는 것이 중요합니다. - 파일을 받았지만 규칙이 안 맞음:
behavior와 payload 형식이 일치하는지, 대상 도메인이 목록에 있는지, 같은 트래픽에 앞서 매칭되는 규칙이 있는지 확인합니다. - 변경이 바로 보이지 않음: 업데이트 간격이 지나지 않았거나, 프로필을 다시 불러오지 않았거나, 기존 provider 파일이 사용되고 있을 수 있습니다. 클라이언트가 제공하는 provider 업데이트 또는 프로필 갱신 동작을 실행하고 로그를 확인하세요.
운영 환경에서는 규칙 목록을 무조건 자주 갱신하기보다, 변경 빈도와 장애 영향에 맞춰 주기를 정하는 편이 안전합니다. 업데이트 직후 문제가 생겼을 때 되돌릴 수 있도록 GitHub의 이전 커밋을 보존하고, 규칙 변경 전후에 연결 테스트를 수행하세요. 여러 장치에서 동일한 provider를 쓰는 경우에도 각 장치의 코어 버전, 설정 경로, 갱신 상태가 같은지 확인해야 합니다.
안정적인 운영 팁
규칙셋은 목적별로 작게 나누고, provider 이름과 저장소 파일명을 일관되게 관리하세요. 변경 기록과 롤백 경로를 남겨 두면 업데이트 오류가 발생했을 때 원인을 찾고 정상 상태로 복구하기 쉽습니다.
정리하면 rule-providers는 긴 규칙 목록을 외부 파일로 분리해 관리하기 위한 기능입니다. provider의 필드와 규칙 파일 구조를 맞추고, 메인 설정에서 RULE-SET으로 참조한 뒤, 규칙 우선순위와 업데이트 로그까지 확인해야 안정적으로 사용할 수 있습니다. 처음부터 거대한 목록을 옮기기보다 작은 규칙셋 하나를 만들어 다운로드와 매칭을 검증한 다음 범위를 넓혀 보세요.