GitHub에서 Clash 사용자 규칙셋 관리하기: rule-providers 실전 설정

Clash rule-providers와 GitHub를 함께 쓰면 좋은 이유

Clash 규칙이 늘어나면 프로필의 rules가 길어지고, 같은 도메인 목록을 PC와 휴대폰, OpenWrt에서 따로 관리하기도 쉽습니다. 한 기기에서 규칙을 고친 뒤 다른 기기에는 반영하지 않아 서비스별 라우팅 결과가 달라지는 일도 생깁니다. Clash rule-providers는 규칙 목록을 메인 YAML에서 분리해 외부 파일로 관리하는 기능입니다. 여기에 GitHub 저장소를 호스팅 경로로 활용하면 규칙 변경 이력과 배포 파일을 한곳에서 관리할 수 있습니다.

이 방식에서 역할은 분명히 나뉩니다. GitHub 저장소에는 재사용할 규칙 파일을 보관하고, Clash 또는 Mihomo 프로필에는 해당 파일의 URL과 갱신 간격, 규칙을 연결할 정책 그룹을 적습니다. 프로필을 수정할 때마다 긴 도메인 목록을 복사하지 않아도 되고, 규칙이 언제 어떤 이유로 바뀌었는지 Git 커밋으로 추적할 수 있습니다. 여러 기기에서 동일한 규칙을 불러오거나 팀에서 검토한 규칙을 공유할 때 특히 유용합니다.

다만 rule-providers는 규칙을 자동으로 올바르게 만들어 주는 기능이 아닙니다. 잘못된 도메인 패턴이나 순서가 낮은 RULE-SET은 예상과 다른 정책을 만들 수 있으며, 공개 저장소에 개인용 호스트 목록을 올리면 의도치 않게 정보가 노출될 수 있습니다. 이 글에서는 공개 GitHub 저장소에 안전하게 규칙을 배치하고, Mihomo 계열 코어에서 불러와 검증하는 기본 흐름을 설명합니다. 클라이언트마다 메뉴 이름은 다를 수 있으므로 설정의 핵심은 UI보다 YAML과 코어 로그에서 확인하세요.

아래 설정은 Mihomo 호환 코어를 기준으로 한 예시입니다. 오래된 Clash 코어 또는 일부 클라이언트 포크는 지원하는 provider 형식과 필드가 다를 수 있으므로, 적용 전에 사용 중인 코어의 문서와 버전을 확인하세요.

GitHub 규칙 저장소를 만들고 파일 구조 정하기

먼저 GitHub에서 규칙용 저장소를 하나 만들고, 목적을 알아보기 쉬운 파일명으로 목록을 분리합니다. 예를 들어 업무용 SaaS, 개발 도구, 미디어 서비스처럼 변경 주기와 라우팅 목적이 다른 규칙은 각각 파일로 나누는 편이 좋습니다. 모든 항목을 custom.yaml 하나에 넣으면 처음에는 간단해 보이지만, 규칙 변경의 영향 범위를 살피기 어렵고 서로 다른 정책 그룹으로 보내야 할 때 다시 파일을 쪼개야 합니다.

파일은 저장소 루트나 하위 디렉터리에 둘 수 있습니다. 공개 저장소라면 GitHub의 일반 웹 페이지 주소가 아니라 파일 원문을 제공하는 raw.githubusercontent.com 주소를 사용합니다. 웹 페이지 주소를 provider의 url에 넣으면 HTML 문서를 규칙 파일로 읽으려 해 파싱 오류가 날 수 있습니다. 저장소 이름, 브랜치, 경로의 대소문자도 실제 파일과 일치해야 합니다.

my-clash-rules/
└── rules/
    ├── work-domain.yaml
    └── dev-domain.yaml

규칙 파일의 데이터 구조는 provider의 behavior와 format에 맞춰야 합니다. 도메인 목록만 담는다면 behavior: domain을 쓸 수 있고, 여러 종류의 규칙을 Clash 규칙 문법으로 묶으려면 behavior: classical을 선택합니다. IP 대역을 담는 목록은 behavior: ipcidr에 맞춰 관리합니다. 서로 다른 구조를 한 파일에 섞지 말고, 먼저 어떤 규칙을 어떤 방식으로 매칭할지 정한 다음 파일 형식을 선택하세요.

공개 저장소는 별도의 계정이나 토큰 없이 원문 URL에 접근하기 쉬워 설정이 단순합니다. 반면 비공개 저장소는 인증 정보가 필요하며, 토큰을 프로필 YAML에 그대로 넣어 공유하거나 공개하지 않도록 주의해야 합니다. 민감한 내부 도메인, 고객 정보, 사내 네트워크 주소를 공개 저장소에 커밋하지 말고, 공개가 적절하지 않다면 승인된 사내 호스팅이나 접근 통제 방식을 검토하세요.

rule-providers YAML과 RULE-SET 연결하기

메인 프로필에는 먼저 rule-providers 항목을 선언하고, 이어서 rules에서 RULE-SET으로 해당 이름을 참조합니다. 다음은 공개 저장소에 도메인 규칙 파일을 올렸다고 가정한 최소 예시입니다. YOUR-USER, YOUR-REPO, 파일 경로는 본인의 저장소 값으로 바꾸고, proxy-groups 이름도 실제 프로필에 있는 그룹명과 정확히 맞춰야 합니다.

rule-providers:
  WORK-DOMAIN:
    type: http
    behavior: domain
    format: yaml
    path: ./providers/work-domain.yaml
    url: https://raw.githubusercontent.com/YOUR-USER/YOUR-REPO/main/rules/work-domain.yaml
    interval: 86400

rules:
  - RULE-SET,WORK-DOMAIN,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

이 예시의 type: http는 원격 파일을 가져오는 provider를 뜻하고, path는 다운로드한 목록을 로컬에서 저장할 위치입니다. interval: 86400은 초 단위 갱신 간격을 나타내므로 하루에 한 번 확인하는 설정입니다. 너무 짧게 잡으면 실익 없이 원격 요청이 잦아질 수 있고, 지나치게 길면 GitHub에서 바꾼 규칙이 기기에 늦게 반영될 수 있습니다. 규칙이 자주 바뀌지 않는다면 하루 단위부터 시작해 실제 운영 주기에 맞게 조정하세요.

behavior: domain을 사용한 규칙 파일은 일반적으로 다음처럼 도메인 항목을 목록으로 작성합니다. 정확한 문법은 사용하는 코어의 문서를 기준으로 확인하고, 파일에 주석이나 빈 줄을 추가할 때도 파서가 허용하는 형식을 유지하세요.

payload:
  - '+.example.com'
  - '+.service.example'
  - 'api.example.net'

반면 behavior: classical을 쓴다면 파일 안에 DOMAIN-SUFFIX처럼 규칙 유형과 값을 함께 적는 방식이 필요합니다. provider 이름은 메인 YAML의 선언과 RULE-SET 참조에서 철자와 대소문자를 동일하게 유지하세요. 그리고 RULE-SET,WORK-DOMAIN,PROXY는 뒤에 배치된 규칙보다 먼저 검사됩니다. 더 일반적인 GEOIP, MATCH 또는 광범위한 도메인 규칙이 앞에서 트래픽을 가져가면 provider 규칙에 도달하지 못하므로, 적용 순서를 의도적으로 설계해야 합니다.

GitHub 게시와 자동 갱신을 운영하는 방법

초기 게시에서는 규칙 파일 하나만 먼저 올려 작은 범위로 시험하는 것이 좋습니다. 파일을 만들고 커밋한 뒤 GitHub에서 파일의 원문 보기가 열리는지 확인합니다. 브라우저에서 읽을 수 있다는 사실만으로 Clash가 정상 파싱한다고 단정할 수는 없으므로, 원문 주소를 복사해 provider의 url에 넣고 클라이언트에서 프로필을 다시 불러와야 합니다. 저장소를 만들 때 지정한 기본 브랜치가 main이 아니라면 URL의 브랜치 부분도 실제 이름에 맞춰 수정합니다.

이후 규칙을 바꿀 때는 파일을 직접 덮어쓰기 전에 변경 이유와 영향 범위를 간단히 기록합니다. 예를 들어 새 도메인 추가, 더 이상 사용하지 않는 항목 제거, 특정 서비스의 하위 도메인 범위 축소처럼 변경 목적을 커밋 메시지에 남기면 문제 발생 시 원인을 찾기 쉽습니다. GitHub의 변경 이력으로 이전 버전을 비교하거나 되돌릴 수 있다는 점이 단순 URL 목록이나 메신저로 파일을 주고받는 방식과 다른 장점입니다.

provider의 자동 갱신 간격은 원격 파일을 주기적으로 확인하게 하지만, 모든 클라이언트가 같은 순간에 갱신되거나 변경이 즉시 적용된다는 뜻은 아닙니다. 변경 직후 테스트할 때는 클라이언트의 provider 업데이트 기능이나 프로필 새로고침을 실행하고, 다운로드 성공 여부와 적용된 규칙 수를 확인하세요. 실제 메뉴 이름은 Clash Verge Rev, Mihomo 기반 앱, 모바일 클라이언트마다 다를 수 있습니다. 업데이트 시 기존 프로필의 로컬 수정이 덮어써지는 구조인지도 확인해 두면 운영 중 설정 손실을 줄일 수 있습니다.

공유 저장소에서는 편집 권한을 필요한 사람에게만 부여하고, 변경 전후를 비교하는 검토 절차를 두는 편이 안전합니다. 규칙 한 줄도 여러 기기의 트래픽 분류에 영향을 줄 수 있기 때문입니다. 자동화 도구로 파일을 생성하거나 갱신한다면 결과 YAML의 문법 검사와 변경 내역 검토를 배포 과정에 포함하세요. 저장소 주소나 브랜치 이름을 바꾸는 경우에는 provider의 URL도 함께 바꿔야 하며, 기존 URL을 더 이상 제공하지 않기 전에 모든 프로필에서 새 주소가 정상 동작하는지 확인해야 합니다.

처음부터 큰 규칙 모음을 옮기기보다, 테스트 가능한 도메인 몇 개로 provider를 검증한 다음 목록을 확장하세요. 문제 발생 시 Git 커밋 하나와 provider 하나만 살펴보면 되므로 원인 범위가 좁아집니다.

규칙 적용 확인과 자주 발생하는 오류 해결

설정 파일을 저장한 뒤에는 먼저 코어가 프로필을 정상적으로 읽는지 확인합니다. YAML 들여쓰기는 탭 대신 공백을 사용하고, rule-providers와 rules가 최상위 항목으로 정렬되어 있는지 살펴보세요. provider 이름이나 정책 그룹이 선언과 다르면 프로필 로드 단계에서 오류가 나거나 규칙이 기대한 그룹으로 연결되지 않습니다. 클라이언트의 코어 로그에서 provider 다운로드 실패, 형식 오류, 규칙 로드 결과를 확인하고, 문제가 있다면 URL 접속과 YAML 파싱을 분리해 점검합니다.

  • 다운로드 오류: 브라우저에서도 원문 URL이 열리는지 확인합니다. 저장소가 비공개인지, 브랜치 이름과 파일 경로의 대소문자가 맞는지, 네트워크에서 GitHub 원문 도메인에 접근 가능한지 확인하세요.
  • 형식 또는 파싱 오류: 원문 URL이 GitHub 웹 페이지가 아니라 규칙 파일을 반환하는지 점검합니다. behavior와 파일의 실제 데이터 구조가 맞는지도 확인합니다.
  • 규칙이 적용되지 않음: RULE-SET이 더 구체적인 규칙보다 아래에 있는지, provider 이름과 대상 그룹 이름이 정확한지 살펴봅니다. 로그나 연결 화면에서 해당 요청이 어떤 규칙에 매칭됐는지 확인하세요.
  • 수정한 내용이 반영되지 않음: 클라이언트에서 provider를 수동 갱신하고 프로필을 다시 확인합니다. 캐시된 파일을 사용 중일 수 있으므로, 코어 로그에서 마지막 갱신 결과와 시간을 확인하세요.

테스트는 실제로 제어할 수 있는 도메인이나 안전한 테스트 대상부터 시작합니다. 브라우저에서 해당 서비스에 접속한 뒤 Clash의 연결 목록이나 로그에서 요청 도메인, 매칭된 규칙, 선택된 정책 그룹을 확인하세요. 서비스가 여러 하위 도메인과 CDN을 함께 사용한다면 대표 페이지 하나만 열어서는 전체 동작을 검증하기 어렵습니다. 로그인, API 호출, 이미지 로드처럼 서로 다른 요청이 어떤 규칙을 타는지 살피되, 불필요하게 광범위한 DOMAIN-KEYWORD를 추가해 다른 서비스를 함께 잡지 않도록 주의합니다.

특정 요청만 예상과 다르게 분류된다면 일단 provider 전체를 교체하기보다, 로그에 나타난 실제 Host와 현재 규칙의 범위를 비교하세요. 접미사 규칙은 의도한 하위 도메인을 포함하는지, 더 앞선 규칙이 요청을 먼저 처리하는지 확인합니다. 수정 후에는 Git에서 변경된 행을 검토하고, provider를 새로 고친 다음 같은 요청을 다시 재현합니다. 이처럼 로그 확인 → 최소 수정 → 갱신 → 재검증 순서를 지키면 잘못된 와일드카드나 순서 문제를 빠르게 분리할 수 있습니다.

자주 묻는 질문

비공개 GitHub 저장소도 rule-providers에 사용할 수 있나요?

인증을 지원하는 방식과 클라이언트·코어의 기능에 따라 달라집니다. 비공개 저장소에 접근하기 위해 토큰을 URL이나 YAML에 직접 넣으면 프로필 공유, 로그 출력, 백업 과정에서 자격 증명이 노출될 수 있습니다. 인증 처리 방법을 충분히 검토하지 않았다면 공개해도 되는 규칙만 공개 저장소에 두거나, 조직에서 승인한 내부 배포 경로를 사용하세요.

interval을 짧게 설정하면 규칙이 더 안정적으로 갱신되나요?

반드시 그렇지는 않습니다. 짧은 간격은 원격 확인 횟수를 늘릴 뿐이며, GitHub 접속 장애나 잘못된 파일 형식을 해결하지 않습니다. 규칙 변경 빈도에 맞는 간격을 정하고, 중요한 변경은 클라이언트에서 수동 갱신해 로그와 실제 매칭 결과를 확인하는 편이 낫습니다.

모든 Clash 클라이언트에서 같은 YAML을 쓸 수 있나요?

클라이언트의 화면이 비슷해도 포함된 코어와 버전에 따라 rule-provider 필드나 지원 형식이 다를 수 있습니다. 프로필이 로드되지 않으면 앱 이름만으로 호환성을 추측하지 말고 코어 종류와 버전을 확인하세요. Mihomo용 기능을 오래된 코어가 지원하지 않는 경우에는 해당 코어의 문법으로 조정하거나 호환되는 코어를 선택해야 합니다.

domain과 classical 중 어떤 behavior를 선택해야 하나요?

도메인 이름 목록만 따로 관리한다면 domain이 간결하고, 도메인·IP 등 여러 규칙 유형을 하나의 규칙 파일에서 다뤄야 한다면 classical이 적합할 수 있습니다. 선택한 behavior와 파일 구조가 일치해야 하므로, 현재 코어 문서의 예시를 기준으로 작은 파일부터 검증하세요.

GitHub rule-providers로 재사용 가능한 규칙 운영하기

일부 간단한 프록시 앱이나 수동 VPN 설정은 규칙 목록의 버전 이력, 여러 기기 간 재사용, 세밀한 도메인별 라우팅을 한곳에서 관리하기 어렵습니다. 파일을 매번 복사하는 운영은 수정 누락을 만들고, 설정 전체를 자주 교체하는 방식은 어떤 규칙이 바뀌었는지 추적하기 힘듭니다. Clash의 rule-providers는 규칙 파일과 프로필을 분리하고, GitHub의 변경 이력과 Mihomo의 규칙 매칭·로그를 활용해 이 과정을 더 확인 가능하게 만듭니다. 개인 기기에서 같은 목록을 재사용할 때나 팀에서 검토된 규칙을 배포할 때도, provider별 분리와 변경 검증으로 관리 범위를 명확히 할 수 있습니다.

Clash를 아직 설치하지 않았다면 다운로드 페이지에서 사용 환경에 맞는 클라이언트를 확인하세요. 먼저 작은 규칙 파일 하나로 적용을 시험하고, 로그에서 의도한 매칭이 확인된 뒤 목록을 확장하면 안정적인 운영 흐름을 만들 수 있습니다.

→ 지금 무료로 Clash를 다운로드하고 빠른 인터넷을 경험하세요

다운로드 페이지로 이동