Clash rule-providers 고급 설정: GitHub에서 규칙셋 직접 관리하기

NT-06.1rule-providers란 무엇이며, 왜 규칙을 외부 파일로 분리하는가

Clash와 mihomo 설정에서 rules는 트래픽을 어떤 정책 그룹으로 보낼지 결정하는 핵심 항목입니다. 하지만 서비스가 늘어나면 규칙 목록도 빠르게 길어집니다. 스트리밍, 업무 도구, 메신저, 광고 차단, 로컬 네트워크처럼 용도별 규칙을 하나의 YAML 파일에 모두 직접 작성하면 수정 범위를 파악하기 어렵고, 작은 오타 하나가 전체 설정 검증 실패로 이어질 수 있습니다.

rule-providers는 이런 규칙을 별도의 파일로 관리하는 기능입니다. 메인 Profile에는 외부 규칙셋의 이름과 위치, 갱신 주기만 선언하고, 실제 DOMAIN, DOMAIN-SUFFIX, IP-CIDR 같은 항목은 별도 YAML 또는 텍스트 파일에 저장합니다. 이후 rules에서 RULE-SET 문법으로 해당 규칙셋을 호출합니다. 결과적으로 메인 설정은 짧아지고, 서비스별 규칙은 독립적으로 검토하고 교체할 수 있습니다.

동작 순서는 세 단계로 이해하면 됩니다. 먼저 mihomo가 Profile에 선언된 provider의 URL 또는 로컬 경로에서 규칙 파일을 가져옵니다. 다음으로 파일의 형식과 behavior 값을 기준으로 규칙을 읽고 메모리에 캐시합니다. 마지막으로 실제 요청이 들어오면 rules에 적힌 RULE-SET,provider-name,정책 항목을 위에서부터 평가해 일치하는 정책 그룹으로 전달합니다. 따라서 provider를 선언했다고 자동으로 적용되는 것은 아니며, 반드시 rules에서 호출해야 합니다.

이 기능은 GitHub 같은 Git 기반 저장소에서 규칙 파일을 관리할 때 특히 유용합니다. 규칙을 수정할 때 변경 내역을 확인할 수 있고, 여러 기기에서 동일한 파일을 사용하며, 검토가 끝난 버전만 배포하는 운영 방식도 만들 수 있습니다. 다만 공개 저장소에 개인용 도메인 목록, 내부 호스트명, 접속 정보가 섞이지 않도록 파일 내용을 먼저 점검해야 합니다.

NT-06.2YAML 필드와 provider 유형을 정확하게 작성하기

가장 일반적인 원격 provider는 type: http입니다. 클라이언트가 지정된 주소에서 파일을 내려받아 로컬 캐시에 저장하고, interval에 설정한 초 단위 주기가 지나면 다시 갱신합니다. 로컬에 직접 둔 파일을 참조할 때는 type: file을 사용합니다. 두 방식은 이름은 같아도 갱신 경로가 다르므로, 원격 저장소에서 배포할 파일에는 http, 수동으로 관리하는 기기별 파일에는 file을 선택하면 됩니다.

rule-providers:
  streaming-services:
    type: http
    behavior: classical
    format: yaml
    url: "https://example.invalid/rules/streaming.yaml"
    path: ./rules/streaming-services.yaml
    interval: 86400
    proxy: DIRECT

  private-network:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/private-network.yaml

streaming-services와 private-network는 provider의 식별자입니다. 영문 소문자와 하이픈을 사용해 용도를 분명하게 정하는 것이 좋습니다. 이 이름은 아래 RULE-SET에서 그대로 참조하므로, 이름을 바꾸면 호출부도 함께 수정해야 합니다. path는 다운로드한 파일을 저장할 로컬 캐시 경로이며, 클라이언트와 코어가 쓰기 가능한 위치인지 확인해야 합니다.

behavior는 특히 중요합니다. 도메인만 한 줄씩 담은 파일이라면 domain, IP 대역만 담은 파일이라면 ipcidr, 여러 종류의 완전한 Clash 규칙 문법을 섞어 쓴 파일이라면 classical을 사용합니다. 예를 들어 classical provider의 파일은 다음처럼 작성할 수 있습니다.

payload:
  - DOMAIN-SUFFIX,video.example,STREAMING
  - DOMAIN-SUFFIX,cdn.example,STREAMING
  - DOMAIN,updates.example,DIRECT

반대로 domain provider에서는 보통 조건만 나열합니다.

payload:
  - "+.video.example"
  - "+.cdn.example"
  - "updates.example"

파일 형식과 behavior가 맞지 않으면 provider가 로드되지 않거나, 로드되더라도 예상한 규칙 매칭이 일어나지 않을 수 있습니다. 저장소에서 파일을 수정한 뒤에는 YAML 들여쓰기, 최상위 payload 키, 규칙 쉼표 개수를 함께 확인하세요.

NT-06.3GitHub에서 규칙셋을 배포하고 Clash에 연결하는 과정

GitHub를 규칙 배포 장소로 사용할 때는 저장소를 단순한 메모장처럼 다루기보다 작은 배포 프로젝트로 보는 편이 안전합니다. 먼저 rules와 같은 디렉터리를 만들고, 서비스별 파일을 기능 단위로 나눕니다. 예를 들어 streaming.yaml, work.yaml, local-network.yaml처럼 이름을 정하면 파일의 목적을 바로 알 수 있습니다. 파일 하나에 너무 많은 서비스를 넣으면 수정 영향 범위가 커지고, 반대로 파일을 지나치게 잘게 나누면 provider 선언과 갱신 관리가 복잡해집니다.

1. 저장소에 규칙 파일을 만들고 모든 항목의 형식을 통일합니다. classical을 사용할 경우 각 줄이 유효한 Clash 규칙인지 확인하고, 도메인 전용 파일은 불필요한 정책 이름을 넣지 않습니다.
2. 변경 사항을 작은 단위로 커밋합니다. 여러 서비스의 도메인을 한 번에 바꾸기보다 목적별로 나누면 특정 커밋에서 문제가 시작됐는지 추적하기 쉽습니다.
3. 클라이언트가 실제 규칙 파일 원문을 받을 수 있는 배포 주소를 사용합니다. 저장소의 HTML 화면 주소가 아니라 원문 콘텐츠를 반환하는 HTTPS 주소여야 하며, 접근 권한이 필요한 비공개 파일은 클라이언트가 인증하지 못할 수 있습니다.
4. Profile의 rule-providers에 provider를 등록하고, 로컬 캐시 path를 서로 겹치지 않게 지정합니다.
5. rules에서 provider를 호출한 뒤 Profile을 저장하고, 클라이언트의 provider 상태 또는 로그 화면에서 다운로드 성공 여부를 확인합니다.

rule-providers:
  work-sites:
    type: http
    behavior: classical
    format: yaml
    url: "https://example.invalid/clash/work.yaml"
    path: ./rules/work-sites.yaml
    interval: 43200
    proxy: DIRECT

  media-sites:
    type: http
    behavior: domain
    format: yaml
    url: "https://example.invalid/clash/media.yaml"
    path: ./rules/media-sites.yaml
    interval: 86400
    proxy: DIRECT

rules:
  - RULE-SET,work-sites,WORK
  - RULE-SET,media-sites,MEDIA
  - MATCH,PROXY

위 예시에서 work-sites는 파일 안에 완전한 규칙 행이 있는 classical provider이고, media-sites는 도메인 목록만 담는 domain provider입니다. RULE-SET 뒤의 마지막 값은 provider 이름이 아니라 트래픽을 보낼 정책 그룹 이름입니다. 따라서 Profile 안에 실제로 WORK와 MEDIA라는 proxy group이 존재해야 합니다.

GitHub 측 파일을 갱신했다고 해서 모든 클라이언트가 즉시 새 내용을 사용하는 것은 아닙니다. 클라이언트는 interval과 자체적인 업데이트 동작에 따라 캐시를 유지합니다. 긴급하게 규칙을 바꿔야 할 때는 해당 provider의 수동 업데이트 기능을 실행하고, 그래도 이전 내용이 보이면 클라이언트를 재시작하기 전에 먼저 로컬 캐시 경로와 다운로드 로그를 확인하세요. 파일을 수정할 때마다 provider 이름이나 캐시 파일명을 바꾸면 이전 캐시가 남아 문제 원인을 파악하기 어려워집니다.

NT-06.4규칙 우선순위와 운영 환경에서의 안전한 자동화

provider를 여러 개 연결할 때 가장 중요한 원칙은 rules의 위에서 아래로 평가된다는 점입니다. 먼저 일치한 규칙에서 처리가 끝나므로, 넓은 범위의 provider를 위에 배치하면 뒤에 있는 예외 규칙이 실행되지 않습니다. 예를 들어 모든 example.com 하위 도메인을 프록시로 보내는 provider 뒤에 특정 업데이트 주소를 DIRECT로 보내는 규칙을 두면 예외가 작동하지 않습니다. 예외를 먼저 두고 넓은 규칙을 뒤에 배치해야 합니다.

rules:
  - DOMAIN,updates.example,DIRECT
  - RULE-SET,work-sites,WORK
  - RULE-SET,media-sites,MEDIA
  - MATCH,PROXY

provider 내부의 규칙 순서도 무시하지 않는 것이 좋습니다. classical 파일에서 서로 충돌하는 항목이 있다면 더 구체적인 조건을 위에 배치하세요. 다만 provider를 여러 개 호출하는 구조에서는 최종 우선순위가 메인 Profile의 rules 배열에 의해 결정됩니다. 파일 안에서 정렬을 잘해도, 메인 규칙에서 다른 provider가 먼저 일치하면 해당 파일까지 도달하지 않습니다.

운영 자동화는 “변경 → 검증 → 배포 → 갱신 확인”의 순서로 구성하는 것이 안정적입니다. 먼저 저장소에서 규칙을 수정하고, YAML 문법과 규칙 유형을 검사합니다. 다음으로 테스트용 Profile에서 수동 provider 업데이트를 실행해 로드 성공 여부를 확인합니다. 문제가 없을 때만 운영 Profile에 반영하고, 클라이언트 로그에서 provider 다운로드 오류와 규칙 매칭 결과를 확인합니다. 단순히 저장소에 파일을 올리는 것만으로는 실제 사용 환경의 성공을 보장할 수 없습니다.

• 갱신 주기: 자주 바뀌지 않는 규칙은 하루 단위나 그보다 긴 주기를 사용합니다. 저장소와 클라이언트에 불필요한 요청을 반복하지 않도록 서비스 특성에 맞춥니다.
• 파일 호환성: 사용하는 클라이언트의 코어가 format과 behavior 조합을 지원하는지 확인합니다. Clash 계열 클라이언트라도 내장 코어와 버전에 따라 세부 지원 범위가 다를 수 있습니다.
• 다운로드 경로: provider를 프록시로 가져와야 하는 환경이면 proxy 정책을 점검합니다. 프록시가 아직 연결되지 않은 상태에서 provider 다운로드를 프록시에 의존하면 초기화 순환 문제가 생길 수 있습니다.
• 실패 대비: 원격 파일을 사용할 때는 마지막으로 성공한 로컬 캐시가 남아 있는지 확인합니다. 새 파일을 받지 못했다고 즉시 빈 규칙셋으로 교체하지 않도록 클라이언트의 provider 상태를 확인해야 합니다.
• 이름 관리: provider 이름과 정책 그룹 이름을 비슷하게 만들지 않습니다. media-sites는 provider, MEDIA는 정책 그룹처럼 표기 규칙을 나누면 오타를 줄일 수 있습니다.

문제가 발생했을 때는 먼저 provider가 로드되었는지, 다음으로 RULE-SET 호출이 존재하는지, 마지막으로 호출 순서와 정책 그룹 이름이 올바른지 확인하세요. provider 파일의 내용만 반복해서 수정하는 것보다 “다운로드 단계”, “파싱 단계”, “규칙 평가 단계”를 나누어 점검하는 편이 빠릅니다. 이 구조를 지키면 GitHub에서 서비스별 규칙을 관리하면서도 메인 Profile은 간결하게 유지할 수 있습니다.