Clash 규칙을 GitHub에서 관리하는 rule-providers YAML 구성법

서론: 규칙을 별도 파일로 관리해야 하는 이유

Clash 설정을 오래 사용하다 보면 rules 항목이 길어지고, 서비스별 도메인이나 차단 목록을 수정할 때마다 전체 프로필을 편집해야 하는 번거로움이 생깁니다. 특히 여러 기기에서 같은 규칙을 사용하거나 팀원과 변경 사항을 공유한다면, 큰 설정 파일 하나에 모든 규칙을 넣는 방식은 검토와 복구가 어려워질 수 있습니다.

rule-providers는 규칙을 외부 파일로 분리하고, Clash가 해당 파일을 가져와 RULE-SET 규칙으로 적용하도록 하는 기능입니다. 규칙 데이터는 GitHub 저장소에서 관리하고, 실제 프록시 그룹과 전체 연결 정책은 로컬 프로필에 두면 역할을 나눠 깔끔하게 관리할 수 있습니다. 이 글에서는 Mihomo 기반 클라이언트를 기준으로 YAML 구성, GitHub 배포, 우선순위 점검, 오류 해결 방법을 살펴봅니다.

1rule-providers의 구성 요소 이해하기

rule-provider는 규칙 목록을 저장하는 원격 또는 로컬 데이터 소스입니다. 프로필의 rule-providers 아래에 이름과 가져오기 방법을 정의하고, rules 아래에서 그 이름을 RULE-SET으로 호출합니다. 제공자 설정만 작성하고 참조 규칙을 빼먹으면 목록이 내려받아져도 트래픽 분기에는 사용되지 않습니다.

• name: 프로필 내부에서 provider를 부르는 식별자입니다. rules의 RULE-SET 이름과 철자 및 대소문자를 일치시킵니다.
• type: 일반적으로 원격 파일은 http, 기기 안의 파일은 file을 사용합니다.
• behavior: 데이터가 도메인 목록인지, IP 대역인지, 전체 규칙인지 지정합니다. 대표 값은 domain, ipcidr, classical입니다.
• format: 파일 형식입니다. YAML 구조의 목록은 yaml, 일반 텍스트 목록은 text로 지정합니다.
• path, url, interval: 캐시 파일 위치, 내려받을 주소, 원격 목록을 다시 확인하는 간격(초)을 설정합니다.

규칙 데이터 파일과 프로필 YAML은 용도가 다릅니다. 프로필은 노드, 그룹, DNS와 전체 규칙 정책을 정의하고, provider 파일은 반복해서 관리할 규칙 목록만 담도록 구성하는 편이 좋습니다. 파일 형식과 behavior가 서로 맞지 않으면 파싱 오류가 발생하거나 규칙이 예상과 다르게 해석될 수 있습니다.

2Mihomo용 YAML 구성 예시

아래 예시는 GitHub의 공개 저장소에서 도메인 규칙 목록을 가져오는 구성입니다. url의 계정 이름, 저장소, 브랜치, 파일 경로는 실제 저장소에 맞게 바꾸세요. path는 Clash가 내려받은 파일을 로컬에 저장할 위치입니다. 프로필 관리 방식에 따라 쓰기 가능한 경로를 선택하고, 다른 provider와 파일명이 겹치지 않도록 이름을 구분합니다.

이 예시의 Work와 Proxy는 실제 프로필에 정의된 프록시 그룹 이름이어야 합니다. rules는 위에서 아래 순서로 평가되므로, 일반적인 최종 규칙인 MATCH보다 provider 참조를 앞에 둡니다. MATCH를 먼저 쓰면 그 아래에 있는 세부 규칙이 도달되지 않습니다.

도메인 provider 파일은 다음처럼 payload 목록을 가진 YAML로 만들 수 있습니다.

behavior: domain은 도메인 기반 항목에 사용합니다. 반대로 behavior: classical을 선택했다면 provider 파일에는 DOMAIN-SUFFIX,example.com처럼 대상 정책까지 포함한 전체 규칙 형식을 넣어야 합니다. 두 방식을 섞어 쓰지 말고, 관리하려는 목록이 도메인 목록인지 완성된 규칙 집합인지 먼저 결정하세요. IP 대역 목록을 구성할 때는 ipcidr 동작과 코어가 요구하는 파일 형식을 확인하고, 필요하다면 규칙의 no-resolve 옵션도 코어 문서에 맞춰 검토합니다.

3GitHub에 규칙 파일 배포하기

GitHub 저장소에는 provider 파일과 변경 이력을 함께 보관합니다. 저장소를 만들고 규칙 파일을 커밋한 뒤, 브라우저에서 파일이 정상적으로 보이는지 확인하세요. YAML 원본 파일을 내려받는 주소는 저장소의 HTML 페이지 주소가 아니라 raw.githubusercontent.com 형식의 원본 파일 주소여야 합니다. 저장소 웹페이지 URL을 provider의 url에 그대로 넣으면 HTML이 내려와 파싱 오류가 날 수 있습니다.

1. 파일 구조를 정합니다. 예를 들어 저장소에 work-sites.yaml을 추가하고, 여러 목록을 쓴다면 목적별로 파일을 나눕니다.
2. 작은 규칙부터 커밋합니다. YAML 구문과 실제 분기 결과를 먼저 확인한 뒤 항목을 늘리면 오류 원인을 찾기 쉽습니다.
3. 원본 파일 주소를 확인합니다. 공개 저장소에서 Raw 보기 또는 원본 파일 링크를 열어 주소가 파일의 내용을 직접 반환하는지 검사합니다.
4. 프로필을 갱신합니다. provider가 참조되는 활성 프로필을 다시 불러오거나, 클라이언트의 규칙 제공자 갱신 기능을 사용합니다.

커밋 메시지에는 변경 목적을 짧게 남기고, 목록 전체를 교체하기 전에는 이전 버전을 확인할 수 있도록 Git 이력을 유지하세요. 오타나 잘못된 도메인이 추가되면 문제가 시작된 커밋을 찾아 되돌릴 수 있습니다. 다른 사용자에게 배포할 경우에는 저장소를 공개하기 전에 규칙에 개인 도메인, 내부 IP, 계정 정보 등 공개하면 안 되는 데이터가 포함되지 않았는지 점검해야 합니다.

공개 저장소의 파일은 누구나 읽을 수 있고, 원격 주소나 브랜치가 바뀌면 Clash가 새 파일을 받지 못할 수 있습니다. 장기간 유지할 주소를 선택하고 파일을 이동하거나 이름을 바꿀 때는 프로필의 url도 함께 수정하세요. 저장소 접근이 자주 실패한다면 원격 목록을 필수 연결 경로로 삼기보다, 마지막으로 정상 동작한 규칙 파일을 보관하고 장애 시 복구할 계획을 마련하는 것이 안전합니다.

4규칙 우선순위와 갱신 오류 점검

provider 규칙도 일반 규칙과 같은 순서 원칙을 따릅니다. 구체적인 예외 규칙을 위쪽에 두고, 넓은 범위를 대상으로 하는 규칙은 그 뒤에 배치하세요. 예를 들어 특정 도메인을 직접 연결해야 한다면 해당 예외가 provider의 광범위한 도메인 항목보다 먼저 평가되어야 하는지 확인합니다. 정책이 겹칠 때 어느 항목이 먼저 일치하는지 판단하기 어려우면 provider 목록을 더 잘게 나누고 규칙의 책임을 명확히 구분하는 편이 좋습니다.

• 규칙이 적용되지 않음: 활성 프로필에 provider가 포함되어 있는지, RULE-SET 이름이 정확히 일치하는지, 해당 참조가 MATCH보다 앞에 있는지 확인합니다.
• 가져오기 실패: Raw URL을 브라우저에서 열어 보고, 브랜치와 경로의 대소문자, 공개 여부, 네트워크 연결 상태를 점검합니다.
• 파싱 오류: provider의 behavior와 파일 내용이 서로 맞는지, YAML 들여쓰기 및 쉼표가 올바른지 확인합니다.
• 변경이 반영되지 않음: 캐시된 로컬 파일이나 갱신 주기를 확인하고, 클라이언트에서 수동 업데이트를 실행한 뒤 프로필 로그를 살펴봅니다.

interval은 초 단위로 설정합니다. 예시의 86400은 하루를 의미합니다. 너무 짧은 간격은 불필요한 요청을 늘리고, 지나치게 긴 간격은 수정 사항이 적용되는 시간을 늦출 수 있습니다. 규칙이 매일 바뀌는지, 한 달에 한 번 바뀌는지에 맞춰 간격을 정하고, 실제 업데이트 시각은 클라이언트의 갱신 동작과 코어 로그에서 확인하세요. 기기가 오프라인인 동안 갱신이 지연될 수도 있으므로 간격만으로 즉시 적용을 보장한다고 생각해서는 안 됩니다.

오류가 나면 먼저 전체 YAML 파싱 오류와 provider 개별 다운로드 오류를 구분합니다. 프로필 자체가 로드되지 않는다면 들여쓰기나 키 이름을, 프로필은 로드되지만 규칙이 바뀌지 않는다면 URL, 캐시, provider 갱신 로그를 확인하세요. GUI 클라이언트에서는 로그 또는 연결 화면에서 요청 도메인과 실제로 선택된 규칙을 확인할 수 있습니다. 수정 후에는 브라우저 한 곳만으로 판단하지 말고, provider에 넣은 도메인과 provider에 없는 도메인을 각각 시험해 분기 결과를 비교합니다.

5자주 묻는 질문

provider 파일을 수정하면 즉시 반영되나요?

항상 즉시 반영되는 것은 아닙니다. interval에 따른 갱신 시점까지 기다리거나 클라이언트에서 수동 업데이트를 실행해야 할 수 있습니다. 갱신 뒤에도 결과가 같다면 활성 프로필, 캐시, 규칙 순서를 차례로 확인하세요.

GitHub 저장소를 비공개로 설정해도 되나요?

인증이 필요한 비공개 파일은 일반적인 공개 Raw URL 방식으로 바로 가져올 수 없을 수 있습니다. 클라이언트와 코어의 인증 지원을 확인하지 않은 상태에서 토큰을 URL에 넣어 배포하지 마세요. URL에 포함한 자격 증명은 로그나 설정 공유 과정에서 노출될 위험이 있습니다.

도메인 목록에는 어떤 behavior를 선택해야 하나요?

도메인 기반 항목을 묶을 때는 보통 domain을 사용하고, 파일 안에 완성된 Clash 규칙 문장을 넣을 때는 classical을 검토합니다. 규칙 형식과 provider 선언을 같은 방식에 맞추고, 사용하는 코어가 지원하는 항목을 확인하세요.

규칙을 모두 GitHub에 옮겨도 괜찮나요?

가능하더라도 노드 선택 정책, 로컬 네트워크 예외, 마지막 일치 규칙처럼 프로필의 나머지 구성과 밀접한 부분은 로컬 프로필에 남기는 편이 관리하기 쉽습니다. 자주 변경되거나 여러 기기에서 공유할 규칙만 분리하면 원격 파일 장애의 영향을 줄이고 문제를 더 쉽게 추적할 수 있습니다.

규칙 파일을 작게 시작해 형식과 분기 결과를 검증한 다음, Git 이력과 갱신 주기를 정리하면 유지 관리가 훨씬 편해집니다. 다양한 플랫폼용 클라이언트가 필요하다면 다운로드 페이지에서 지원 정보를 확인하세요.

다운로드하기 →