왜 rule-providers로 규칙을 분리해야 하나

Clash 설정 파일이 커지면 rules 아래에 모든 도메인과 IP 규칙을 직접 넣고 관리하는 방식은 빠르게 한계에 도달합니다. 광고 차단, 스트리밍 서비스, 업무용 도메인, 국내 직접 연결, 해외 프록시 연결처럼 목적이 다른 규칙이 하나의 YAML에 섞이면 수정 범위를 파악하기 어렵고, 작은 오타 하나가 전체 프로필 로드 실패로 이어질 수 있습니다. 여러 기기나 프로필에서 같은 규칙을 재사용하기도 어렵습니다.

rule-providers는 규칙 목록을 별도의 원격 파일로 분리하고, 메인 Clash 설정에서는 그 파일의 주소와 형식만 선언하는 기능입니다. 메인 YAML은 프록시 그룹과 기본 라우팅 정책에 집중하고, GitHub 저장소에는 서비스별 규칙 파일을 보관하는 식으로 역할을 나눌 수 있습니다. 이렇게 구성하면 규칙 변경 이력을 확인할 수 있고, 이전 버전으로 되돌리거나 여러 프로필에 같은 규칙을 적용하기도 쉬워집니다.

이 글에서는 Mihomo 계열 코어를 기준으로 GitHub에 YAML 규칙 파일을 만들고, Clash Verge Rev·Mihomo 기반 클라이언트에서 이를 rule-providers로 불러오는 과정을 설명합니다. 클라이언트와 코어의 버전에 따라 일부 옵션 이름이나 지원 형식이 다를 수 있으므로, 적용 전 현재 사용 중인 코어가 원격 rule provider를 지원하는지 먼저 확인하세요.

시작 전 준비사항과 저장소 설계

아래 항목을 먼저 준비하면 설정 과정에서 시행착오를 줄일 수 있습니다.

Clash Verge Rev 또는 Mihomo 기반 클라이언트: rule provider와 최신 YAML 필드를 처리할 수 있는 버전을 권장합니다.
GitHub 계정과 비공개 또는 공개 저장소: 공개 규칙은 누구나 읽을 수 있으므로 민감한 도메인 목록을 올릴 때 주의하세요.
규칙 파일의 목적: 광고, 스트리밍, 업무 서비스처럼 한 파일이 한 가지 역할을 갖도록 정합니다.
안정적인 Raw URL: GitHub 파일 화면 주소가 아니라 실제 원문을 반환하는 raw.githubusercontent.com 주소를 사용해야 합니다.

저장소 구조는 지나치게 복잡하게 만들 필요가 없습니다. 예를 들어 다음처럼 규칙 종류를 파일 이름으로 구분하면 나중에 찾기 쉽습니다.

clash-rules/
├── rules/
│   ├── streaming.yaml
│   ├── ads.yaml
│   ├── work.yaml
│   └── direct-cn.yaml
└── README.md

파일 이름에는 공백이나 한글보다 영문 소문자와 하이픈을 사용하는 편이 안전합니다. GitHub의 브랜치를 기본 main으로 유지하고, 테스트가 필요한 변경은 별도 브랜치에서 검증한 뒤 병합하면 운영 중인 Clash 프로필에 갑작스러운 오류가 전파되는 일을 줄일 수 있습니다.

주의

구독 URL, 개인 토큰, 내부망 주소, 인증 헤더, 사용자의 실제 계정 정보는 규칙 파일이나 README에 넣지 마세요. GitHub 저장소를 비공개로 설정하더라도 커밋 기록이나 잘못된 권한 설정을 통해 정보가 노출될 수 있습니다.

1단계: GitHub에 올릴 YAML 규칙 파일 작성

rule provider 파일은 일반적인 Clash 규칙 배열을 담은 YAML입니다. 가장 단순한 형식은 payload 아래에 규칙을 나열하는 방식입니다. 규칙의 종류는 DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD, IP-CIDR 등으로 나뉩니다. 서비스 전체를 묶을 때는 특정 호스트 하나만 적는 DOMAIN보다 하위 도메인까지 포함하는 DOMAIN-SUFFIX가 실용적인 경우가 많습니다.

payload:
  - DOMAIN-SUFFIX,netflix.com
  - DOMAIN-SUFFIX,nflxvideo.net
  - DOMAIN-SUFFIX,nflximg.net
  - DOMAIN,api-global.netflix.com

광고 규칙처럼 도메인 접미사만으로 충분하지 않은 경우에는 키워드 규칙을 사용할 수 있지만, DOMAIN-KEYWORD,ads처럼 너무 짧은 키워드는 정상 서비스까지 차단할 위험이 있습니다. 가능한 경우에는 정확한 도메인이나 검증된 도메인 접미사를 우선하세요. IP 대역을 사용할 때는 네트워크 범위가 정확한지 확인하고, IPv6 주소나 예외가 필요한지 함께 검토해야 합니다.

형식과 인코딩 확인

파일은 UTF-8로 저장하고, YAML 들여쓰기는 스페이스를 사용하세요. 탭 문자가 섞이면 Clash가 파일을 읽지 못할 수 있습니다. 주석은 유지보수에 도움이 되지만 규칙 자체와 혼동되지 않도록 간단하게 작성하는 것이 좋습니다.

# Streaming services routed through the media group
payload:
  - DOMAIN-SUFFIX,example-stream.com
  - DOMAIN-SUFFIX,example-cdn.com

# Keep the service API on the same policy
  - DOMAIN,api.example-stream.com

GitHub에서 파일을 저장한 뒤 Raw 버튼을 눌러 브라우저에 YAML 원문이 표시되는지 확인하세요. HTML로 렌더링된 GitHub 파일 페이지를 provider URL로 사용하면 Clash가 규칙 대신 웹 문서를 내려받게 됩니다. 주소는 대체로 다음과 같은 형태입니다.

https://raw.githubusercontent.com/사용자명/저장소명/main/rules/streaming.yaml

브라우저에서 해당 URL을 열었을 때 payload:가 첫 줄에 보이면 기본적인 URL 검증은 끝난 것입니다. 404, 403, 로그인 화면이 표시되거나 빈 응답이 나오면 저장소 공개 범위, 브랜치 이름, 파일 경로를 다시 확인하세요.

2단계: 메인 Clash YAML에 rule-providers 등록

이제 메인 프로필의 최상위 영역에 rule-providers를 추가합니다. 각 provider에는 클라이언트 설정에서 식별할 이름을 주고, 원격 주소는 url에 넣습니다. type: http는 원격 HTTP 또는 HTTPS 파일을 주기적으로 가져온다는 뜻이며, interval은 업데이트 주기를 초 단위로 지정합니다. 규칙 파일이 일반 YAML이면 behavior: classical을 사용하는 구성이 이해하기 쉽습니다.

rule-providers:
  streaming:
    type: http
    behavior: classical
    url: https://raw.githubusercontent.com/사용자명/clash-rules/main/rules/streaming.yaml
    path: ./rule-providers/streaming.yaml
    interval: 86400
    format: yaml

  ads:
    type: http
    behavior: classical
    url: https://raw.githubusercontent.com/사용자명/clash-rules/main/rules/ads.yaml
    path: ./rule-providers/ads.yaml
    interval: 43200
    format: yaml

path는 클라이언트가 내려받은 파일을 저장할 로컬 경로입니다. 상대 경로를 사용하면 프로필 데이터 디렉터리 아래에 저장되는 경우가 많지만, 클라이언트별 동작이 다를 수 있습니다. 경로를 임의의 운영체제 절대 경로로 지정하기보다 기존 프로필에서 사용하는 형식을 따르는 것이 안전합니다.

format: yaml은 원격 파일이 YAML이라는 것을 명시합니다. 일부 구성에서는 format을 생략해도 동작하지만, 파일 형식을 명시하면 코어가 해석하는 방법이 분명해지고 문제를 진단하기 쉽습니다. provider 이름은 영문과 숫자를 사용해 짧게 정하고, 아래 rules에서 동일한 이름을 그대로 참조해야 합니다.

핵심 확인

rule-providers는 rules와 같은 최상위 레벨에 있어야 합니다. proxy-groups 안에 넣거나 rules 아래에 중첩하면 YAML 문법은 맞더라도 Clash 설정 구조로는 인식되지 않습니다.

3단계: rules에서 provider 호출 순서 지정

provider를 선언하는 것만으로는 트래픽이 자동으로 해당 규칙을 사용하지 않습니다. 메인 설정의 rules 목록에서 RULE-SET 문법으로 provider와 정책 그룹을 연결해야 합니다. 예를 들어 streaming 규칙에 매칭된 요청을 Media 그룹으로 보내려면 다음과 같이 작성합니다.

rules:
  - RULE-SET,ads,REJECT
  - RULE-SET,streaming,Media
  - RULE-SET,work,Work
  - GEOIP,LAN,DIRECT
  - MATCH,Proxy

규칙은 위에서 아래로 평가되며, 먼저 매칭된 항목이 적용됩니다. 따라서 광고 차단을 스트리밍 규칙보다 먼저 두면 광고 도메인은 REJECT로 끝나고, 그 이후에 있는 Media 정책으로 넘어가지 않습니다. 반대로 너무 넓은 DOMAIN-KEYWORD 규칙을 위에 배치하면 의도하지 않은 서비스가 차단될 수 있습니다.

MATCH는 앞선 규칙에 해당하지 않는 모든 요청을 처리하는 마지막 안전망입니다. 개발 단계에서는 마지막 정책을 Proxy로 두어 누락된 도메인을 확인하기 쉽도록 하고, 실제 운영에서는 지역 서비스와 보안 요구사항에 맞춰 DIRECT 또는 별도 그룹으로 조정할 수 있습니다.

적용 순서 체크리스트

GitHub Raw URL을 브라우저에서 열어 정상적인 YAML이 반환되는지 확인합니다.
메인 YAML의 rule-providers 이름과 RULE-SET의 이름이 정확히 같은지 비교합니다.
광고 차단, 업무, 스트리밍처럼 우선순위가 다른 provider의 순서를 정합니다.
항상 마지막에 의도한 정책의 MATCH를 배치합니다.
프로필을 저장하고 Clash를 재로드한 뒤 Rules 화면과 로그에서 매칭 결과를 확인합니다.

4단계: 여러 프로필에서 재사용하고 장애를 점검하는 방법

GitHub 기반 provider의 가장 큰 장점은 여러 프로필이 같은 규칙 파일을 공유할 수 있다는 점입니다. 집에서 사용하는 프로필과 이동 중 사용하는 프로필의 프록시 그룹은 달라도, 광고 차단이나 업무 도메인 목록은 같은 URL을 참조할 수 있습니다. 규칙을 수정할 때 각 프로필을 따로 편집하지 않아도 되므로 설정의 일관성이 높아집니다.

다만 원격 파일은 메인 프로필보다 별도의 장애 지점을 추가합니다. GitHub 저장소가 일시적으로 접근되지 않거나 Raw URL이 변경되면 provider 업데이트가 실패할 수 있습니다. Clash 로그에서 download failed, parsing error, unexpected status code 같은 메시지가 보이면 다음 순서로 확인하세요.

HTTP 상태 코드: 404라면 파일 경로·브랜치·파일 이름을, 403이라면 저장소 권한과 요청 제한을 확인합니다.
응답 내용: YAML 대신 GitHub 오류 HTML이 저장되면 URL이 Raw 주소인지 다시 확인합니다.
YAML 문법: 콜론, 쉼표, 들여쓰기, 따옴표가 손상되지 않았는지 검사합니다.
캐시 파일: 업데이트 실패 시 기존 로컬 provider가 남아 있을 수 있으므로, 오래된 규칙을 계속 사용하고 있는지 확인합니다.
정책 그룹 이름: Media나 Work가 실제 proxy-groups에 존재하는지 확인합니다.

운영 저장소에는 변경 규칙을 기록하는 커밋 메시지를 남기고, 무작정 대량의 도메인을 추가하지 않는 것이 좋습니다. 한 번에 수천 개의 항목을 넣으면 업데이트 시간과 메모리 사용량이 증가하고, 특정 서비스가 느려졌을 때 원인을 찾기 어려워집니다. 변경 전후에 주요 사이트를 직접 연결, 프록시, 차단 세 가지 상태로 시험하면 문제 범위를 빠르게 좁힐 수 있습니다.

5단계: 보안과 버전 관리 기준 정하기

GitHub를 규칙 배포 서버처럼 사용할 때는 편리함과 변경 통제를 함께 고려해야 합니다. 공개 저장소의 장점은 별도 인증 없이 대부분의 Clash 클라이언트가 파일을 읽을 수 있다는 것이지만, 누구나 저장소 내용을 볼 수 있습니다. 조직 내부 도메인이나 고객사 주소처럼 노출되면 곤란한 정보는 공개 provider로 만들지 말고, 접근 제어가 가능한 별도 서버나 비공개 배포 방식을 검토하세요.

규칙 파일을 수정할 때는 먼저 별도 브랜치에서 테스트하고, 문제가 없을 때 운영 브랜치에 병합하세요. 변경량이 큰 경우에는 파일을 기능별로 나누고 커밋도 작게 유지하는 편이 좋습니다. 문제가 발생하면 GitHub의 이전 커밋으로 되돌릴 수 있지만, 클라이언트가 이미 새 파일을 캐시했을 수 있으므로 Clash에서 provider 업데이트를 수동 실행하거나 앱을 다시 로드해야 할 수 있습니다.

업데이트 주기는 파일 성격에 맞춰 결정합니다. 광고 목록처럼 자주 바뀌는 파일은 6시간 또는 12시간 단위가 적절할 수 있고, 업무 도메인처럼 거의 변하지 않는 목록은 하루나 일주일 단위로도 충분합니다. 너무 짧은 주기를 설정하면 GitHub 요청이 불필요하게 늘어나고, 너무 길면 이미 제거한 규칙이 계속 남습니다.

rule-providers:
  work:
    type: http
    behavior: classical
    url: https://raw.githubusercontent.com/사용자명/clash-rules/main/rules/work.yaml
    path: ./rule-providers/work.yaml
    interval: 604800
    format: yaml

보안상 피해야 할 구성

규칙 파일 URL에 개인 액세스 토큰을 평문으로 포함하기
검증하지 않은 제3자 저장소의 규칙을 무조건 실행하기
모든 도메인을 하나의 광범위한 키워드 규칙으로 차단하기
변경 기록 없이 운영 브랜치에 대량 수정 내용을 바로 반영하기

특히 provider 파일은 규칙을 통해 트래픽의 정책 그룹을 바꿀 수 있으므로, URL이 탈취되거나 저장소가 변조되면 사용자의 연결 경로가 예기치 않게 변경될 수 있습니다. HTTPS를 사용하고, 저장소 권한을 최소화하며, 정기적으로 Raw URL과 커밋 이력을 확인하세요. 가능하다면 배포 전 YAML 린터와 실제 테스트 프로필을 별도로 운영하는 것이 안전합니다.

일부 클라이언트는 rule provider 상태를 화면에 표시하지만, 모든 오류를 친절하게 설명하지는 않습니다. 따라서 규칙을 추가할 때는 먼저 작은 파일 하나로 시작하고, 특정 도메인이 어느 정책 그룹으로 갔는지 Connections·Logs 화면에서 확인한 뒤 범위를 넓히는 방식이 가장 안정적입니다. 이 과정을 반복하면 메인 프로필은 짧고 읽기 쉬운 상태로 유지하면서도 GitHub에서 세밀한 규칙을 독립적으로 관리할 수 있습니다.

다른 프록시 클라이언트는 서비스별 규칙을 매번 전체 프로필에 복사해야 하거나, 원격 목록의 변경 이력을 확인하기 어렵고, 여러 기기에서 설정이 쉽게 달라지는 불편이 있습니다. Clash는 rule-providers와 RULE-SET을 통해 규칙을 모듈처럼 분리하고, GitHub의 버전 관리와 결합해 재사용·롤백·검증을 한 흐름으로 처리할 수 있습니다. 여러 프로필의 라우팅을 일관되게 운영하고 싶다면 이 방식으로 시작해 보세요. Clash 다운로드 후 작은 테스트 provider부터 적용하면 부담 없이 구성을 확인할 수 있습니다.

Clash rule-providers를 GitHub에서 관리하는 고급 YAML 설정법