Clash rule-providers 커스텀 규칙 GitHub YAML 관리 가이드

rule-providers란 무엇인가요?

rule-providers는 Clash 설정 파일에 들어가는 도메인, IP-CIDR, 도메인 키워드 등의 규칙을 별도의 YAML 파일로 분리해 관리하는 기능입니다. 모든 규칙을 하나의 프로파일에 직접 작성하면 설정 파일이 빠르게 커지고, 서비스별 예외를 찾거나 수정하기도 어려워집니다. 반면 rule-providers를 사용하면 광고 차단, 스트리밍 서비스, 업무 도메인, 국내 직접 연결 목록을 각각 독립된 파일로 나눌 수 있습니다.

분리된 규칙 파일은 로컬 경로에 둘 수도 있고, GitHub Raw URL 같은 원격 주소에서 가져올 수도 있습니다. GitHub를 사용하면 변경 이력을 확인하고, 잘못 수정했을 때 이전 버전으로 되돌리며, 여러 장치에서 동일한 규칙을 재사용하기 쉽습니다. 다만 원격 파일이 항상 정상적으로 다운로드된다는 보장은 없으므로 URL, 파일 형식, 업데이트 주기, 마지막 MATCH 규칙까지 함께 점검해야 합니다.

이 기능은 단순히 YAML 파일을 여러 개 만드는 방법이 아닙니다. 프로바이더의 이름을 정의하고, 규칙 형식을 지정하고, 실제 rules 목록에서 해당 프로바이더를 호출하는 세 단계가 정확히 연결되어야 합니다. 어느 한 부분이라도 이름이나 들여쓰기가 맞지 않으면 Clash가 설정을 거부하거나 해당 규칙을 조용히 사용하지 않을 수 있습니다.

GitHub에 규칙 YAML 만들기

먼저 GitHub 저장소에 규칙 파일을 저장할 디렉터리를 만듭니다. 예를 들어 rules/streaming.yaml, rules/work.yaml, rules/blocklist.yaml처럼 목적이 분명한 이름을 사용하면 관리가 편합니다. 파일명에는 공백이나 한글보다 영문 소문자와 하이픈을 사용하는 편이 좋고, 하나의 파일에는 가능한 한 같은 성격의 규칙만 넣어야 합니다.

GitHub 일반 파일 페이지 주소와 Raw 주소는 서로 다릅니다. github.com/user/repository/blob/main/rules/work.yaml 형태의 페이지 주소를 그대로 넣으면 Clash가 HTML 문서를 YAML로 해석하려고 하므로 실패합니다. 실제 등록에는 보통 raw.githubusercontent.com으로 시작하는 주소를 사용해야 합니다. 저장소가 비공개라면 인증이 필요한데, 클라이언트가 해당 인증 방식을 지원하는지 먼저 확인하는 것이 안전합니다.

규칙 파일의 기본 형태는 사용하는 규칙 타입에 따라 달라집니다. 도메인 전체를 매칭할 때는 DOMAIN-SUFFIX, 특정 호스트만 지정할 때는 DOMAIN, 문자열이 포함된 도메인을 찾을 때는 DOMAIN-KEYWORD, IP 주소 대역을 처리할 때는 IP-CIDR 또는 IP-CIDR6을 사용합니다.

payload:
  - DOMAIN-SUFFIX,example.com
  - DOMAIN,api.example.net
  - DOMAIN-KEYWORD,stream
  - IP-CIDR,203.0.113.0/24,no-resolve

Clash 설정에 rule-providers 선언하기

다음으로 기본 Clash 프로파일의 rule-providers 영역에 GitHub 파일을 선언합니다. 각 프로바이더에는 식별자로 사용할 이름, 원격 주소인 url, 자동 갱신 주기인 interval, 데이터 형식인 behavior, 그리고 캐시 저장 위치인 path를 지정합니다. 여기서 프로바이더 이름은 나중에 RULE-SET에서 그대로 사용하므로 철자와 대소문자를 일관되게 유지해야 합니다.

rule-providers:
  streaming:
    type: http
    behavior: domain
    url: "https://raw.githubusercontent.com/example-user/clash-rules/main/rules/streaming.yaml"
    path: ./ruleset/streaming.yaml
    interval: 86400

  work:
    type: http
    behavior: domain
    url: "https://raw.githubusercontent.com/example-user/clash-rules/main/rules/work.yaml"
    path: ./ruleset/work.yaml
    interval: 43200

behavior는 원격 파일에 담긴 데이터의 종류와 맞아야 합니다. 도메인 목록이면 domain, IP-CIDR 목록이면 ipcidr, 클래식 규칙 전체 형식이면 classical을 사용합니다. 예를 들어 DOMAIN-SUFFIX,example.com처럼 규칙 유형이 함께 들어 있는 파일을 domain으로 선언하면 파싱 결과가 예상과 달라질 수 있습니다.

path는 다운로드된 파일을 클라이언트가 저장할 로컬 경로입니다. 여러 프로바이더가 같은 경로를 사용하면 업데이트 과정에서 파일이 덮어써질 수 있으므로 반드시 서로 다른 파일명을 지정하세요. interval은 초 단위입니다. GitHub 파일을 자주 수정하지 않는다면 하루에 한 번인 86400 정도로 충분하며, 너무 짧은 주기는 불필요한 요청과 업데이트 실패를 늘릴 수 있습니다.

RULE-SET으로 규칙 연결하기

프로바이더를 선언한 것만으로는 트래픽에 적용되지 않습니다. 실제 rules 목록에서 RULE-SET 구문으로 호출하고, 일치했을 때 사용할 프록시 그룹 또는 DIRECT를 지정해야 합니다. 일반적인 형식은 RULE-SET,프로바이더이름,정책그룹입니다.

rules:
  - RULE-SET,streaming,Proxy
  - RULE-SET,work,DIRECT
  - GEOIP,PRIVATE,DIRECT
  - MATCH,Proxy

Clash 규칙은 위에서 아래 방향으로 평가되며, 먼저 일치한 규칙이 적용됩니다. 따라서 특정 업무 도메인을 직접 연결하고 싶은데 그보다 위에 모든 해외 도메인을 프록시로 보내는 규칙이 있다면, 업무 프로바이더는 실행되지 않습니다. 좁은 범위의 예외를 먼저 배치하고, 넓은 범위의 일반 규칙을 뒤에 두는 것이 기본 원칙입니다.

도메인 규칙과 IP 규칙을 함께 사용할 때도 순서를 고려해야 합니다. 애플리케이션이 도메인을 기준으로 연결하는지, DNS 해석 후 IP만 남기는지에 따라 도메인 규칙이 먼저 필요한 경우가 있습니다. fake-ip, 스니퍼, DNS 정책을 사용하는 환경에서는 표시되는 호스트명이 예상과 다를 수 있으므로, 규칙 화면과 연결 로그를 함께 확인하는 것이 좋습니다.

정책 그룹 이름도 실제 설정에 존재해야 합니다. Proxy라는 이름을 썼지만 실제 그룹이 🚀 프록시라면 규칙은 정상적으로 읽혀도 목적지를 찾지 못합니다. 이모지나 특수문자가 포함된 그룹명은 오타가 생기기 쉬우므로, 처음 구성할 때는 Proxy, Direct처럼 단순한 이름을 사용하고 안정화한 뒤 변경하는 방법이 편합니다.

업데이트 오류와 충돌 점검

GitHub 기반 rule-providers가 작동하지 않을 때는 먼저 Clash 로그나 프로파일 검증 결과에서 HTTP 상태 코드와 파일 파싱 오류를 확인합니다. 404는 저장소 경로 또는 브랜치명이 잘못된 경우가 많고, 403은 요청 제한이나 비공개 저장소 접근 문제일 수 있습니다. YAML parse error가 표시된다면 파일의 들여쓰기, 콜론, 따옴표, 탭 문자를 점검해야 합니다.

• 404 Not Found: 파일명, 사용자명, 저장소명, 브랜치, 디렉터리 경로를 다시 확인합니다.
• HTML을 YAML로 읽는 오류: 일반 GitHub 페이지 URL 대신 Raw URL을 사용했는지 확인합니다.
• Provider is empty: 빈 파일이 반환되었거나 behavior와 실제 내용이 맞지 않는지 살펴봅니다.
• 업데이트는 성공하지만 적용되지 않음: RULE-SET 이름과 정책 그룹, 규칙 우선순위를 확인합니다.
• 간헐적인 다운로드 실패: 업데이트 주기를 늘리고, 네트워크에서 GitHub Raw 도메인에 접근 가능한지 테스트합니다.

변경 사항이 바로 반영되지 않는 것도 흔한 문제입니다. 클라이언트는 path에 기존 파일을 캐시하며, 지정한 interval이 지나야 자동 업데이트할 수 있습니다. GitHub에서 파일을 수정한 뒤 즉시 확인해야 한다면 클라이언트의 프로바이더 메뉴에서 수동 업데이트를 실행하고, 필요할 때는 해당 캐시 파일을 삭제한 뒤 다시 받아 보세요. 단, 실행 중인 프로파일을 직접 수정하기보다는 원본 설정과 백업을 먼저 보관하는 것이 안전합니다.

규칙 충돌을 줄이려면 파일마다 관리 책임과 목적을 명확히 하세요. 광고 차단 목록과 업무 예외 목록을 한 파일에서 함께 수정하면 변경 영향 범위를 예측하기 어렵습니다. GitHub 커밋 메시지에는 단순히 “수정”이라고 쓰기보다 “스트리밍 도메인 추가”, “오래된 CDN 주소 제거”처럼 이유를 남기면 나중에 문제를 되돌리기 쉽습니다. 여러 사람이 저장소를 관리한다면 Pull Request 검토와 기본 YAML 검사를 추가하는 것도 좋은 방법입니다.

안전한 운영과 유지 관리 방법

rule-providers는 한 번 설정하고 끝나는 기능이 아니라 계속 관리해야 하는 구성 요소입니다. 서비스 도메인은 변경될 수 있고, 더 이상 사용하지 않는 목록이 남으면 규칙 파일이 불필요하게 커집니다. 한 달에 한 번 정도 실제 로그와 규칙 목록을 비교해 사용되지 않는 항목을 정리하고, 직접 연결해야 할 도메인이 프록시로 들어가는지 반대로 확인하세요.

가장 중요한 원칙은 최소 권한과 작은 변경입니다. 모든 트래픽을 하나의 거대한 블록리스트로 처리하기보다 목적별로 나누고, 변경 전후에 테스트할 도메인을 정해 두는 편이 안정적입니다. 또한 GitHub의 기본 브랜치에 바로 덮어쓰기보다는 별도 브랜치에서 수정한 뒤 검토하고 병합하면 잘못된 YAML이 모든 장치에 배포되는 상황을 줄일 수 있습니다.

다른 클라이언트에서 사용하는 경우에도 지원 범위를 확인해야 합니다. Clash Verge Rev와 Mihomo 계열은 최신 rule-providers 옵션을 비교적 폭넓게 제공하지만, 오래된 Clash for Windows나 모바일 클라이언트는 일부 필드나 동작이 다를 수 있습니다. 같은 설정을 여러 플랫폼에서 공유한다면 공통적으로 지원되는 문법을 우선 사용하고, 플랫폼별로 필요한 예외는 별도 프로파일에서 관리하는 것이 좋습니다.

일부 경쟁 프록시 도구는 서비스별 규칙을 화면에서만 편집하도록 만들어 여러 장치에 동일한 정책을 배포하기 어렵거나, 변경 이력과 되돌리기 기능이 제한적일 수 있습니다. Clash는 rule-providers와 GitHub를 결합해 규칙을 파일 단위로 분리하고, 버전 관리·검토·롤백을 한 흐름으로 처리할 수 있으며, 도메인과 IP-CIDR 매칭 순서도 직접 통제할 수 있습니다. 여러 기기에서 일관된 라우팅 정책을 유지하고 싶다면 Clash 무료 다운로드 후 이 가이드의 예제로 작은 프로바이더부터 구성해 보세요.