Mihomo rule-providers 설정법: GitHub로 커스텀 규칙 배포·자동 업데이트

Mihomo rule-providers란?

rule-providers는 도메인이나 IP 규칙을 메인 Clash 설정 파일과 분리해 별도의 파일로 관리하는 Mihomo 기능입니다. 규칙을 몇 개만 직접 추가할 때는 rules에 한 줄씩 적어도 괜찮지만, 여러 기기에서 같은 사용자 규칙을 쓰거나 자주 수정한다면 별도 파일로 관리하는 편이 안전합니다. GitHub에 YAML 파일을 공개하고 Mihomo가 정해진 간격으로 가져오도록 설정하면, 프로필을 매번 직접 편집하지 않아도 규칙을 배포하고 갱신할 수 있습니다.

여기서 중요한 점은 rule-provider가 트래픽을 직접 전달하는 기능은 아니라는 것입니다. provider는 규칙 목록을 가져와 보관하고, 실제 트래픽 처리는 메인 설정의 rules에 작성한 RULE-SET 항목과 프록시 그룹이 담당합니다. 따라서 파일 다운로드에 성공했더라도 provider 이름이 틀렸거나 관련 규칙이 다른 규칙보다 아래에 있으면 원하는 동작이 나타나지 않을 수 있습니다.

기본 구성은 네 부분으로 나뉩니다. GitHub에 게시할 규칙 파일, 메인 설정의 rule-providers 선언, provider를 호출하는 RULE-SET 규칙, 그리고 해당 규칙이 가리킬 프록시 그룹입니다. 이 이름과 경로가 정확히 연결되어야 자동 업데이트와 트래픽 분기가 함께 작동합니다.

1GitHub에 규칙 파일 게시하기

먼저 GitHub 저장소를 만들고, 관리할 규칙을 YAML 파일로 저장합니다. 예를 들어 저장소에 rules/custom-services.yaml 파일을 만들고 다음과 같이 작성할 수 있습니다.

이 예시는 도메인 계열 규칙을 모아 둔 파일입니다. DOMAIN-SUFFIX는 지정한 도메인과 그 하위 도메인에 적용되고, DOMAIN-KEYWORD는 도메인 이름에 특정 문자열이 포함될 때 일치합니다. 서비스가 사용하는 실제 도메인을 확인한 뒤 필요한 항목만 추가하세요. 광범위한 키워드를 넣으면 무관한 사이트까지 같은 그룹으로 연결될 수 있으므로, 가능하면 정확한 도메인 suffix를 우선 사용합니다.

파일을 저장소에 올린 다음 GitHub의 파일 화면에서 Raw를 눌러 원본 주소를 확인합니다. 웹 페이지 주소가 아니라 원본 파일 주소를 provider의 url에 넣어야 합니다. 공개 저장소라면 일반적으로 raw.githubusercontent.com으로 시작하는 URL을 사용할 수 있습니다. 저장소를 비공개로 설정하면 Mihomo가 인증 없이 원본 파일을 가져오지 못하므로, 개인 토큰을 설정 파일에 평문으로 노출하는 방식은 피하세요.

• 파일 형식: 들여쓰기를 공백으로 통일하고, 탭 문자나 YAML 목록 구조 오류가 없는지 확인합니다.
• 주소 안정성: 브랜치 이름과 파일 경로를 확인합니다. 저장소를 이동하거나 파일명을 바꾸면 원본 URL도 함께 수정해야 합니다.
• 변경 범위: 규칙을 수정할 때는 한 번에 많은 항목을 바꾸기보다 작은 단위로 업데이트하고, 잘못된 규칙을 되돌릴 수 있도록 Git 기록을 유지합니다.

2Mihomo 설정에서 provider 연결하기

이제 메인 설정 파일에 provider를 선언합니다. 아래의 custom-services는 임의로 정한 provider 이름이며, 뒤에서 사용하는 RULE-SET 이름과 대소문자까지 동일해야 합니다. URL은 앞 단계에서 확인한 GitHub 원본 파일 주소로 교체하세요.

type: http는 HTTP 주소에서 규칙 파일을 가져온다는 의미이며, behavior: domain은 도메인 규칙을 제공한다는 뜻입니다. 도메인뿐 아니라 IP 대역을 관리할 때는 규칙 내용과 동작 방식에 맞춰 ipcidr를 사용하고, 서로 다른 유형을 한 provider에 섞지 않는 것이 좋습니다. 목록 전체를 고전적인 규칙 문법으로 관리하려는 경우에는 Mihomo가 지원하는 classical 동작과 파일 형식을 사용하도록 구성할 수 있습니다. 파일 내용의 형식과 behavior가 일치하지 않으면 업데이트 과정에서 파싱 오류가 발생할 수 있습니다.

• path: 가져온 파일을 로컬에 저장할 위치입니다. 사용하는 클라이언트와 프로필 관리 방식에 따라 상대 경로가 해석되는 기준이 다를 수 있으므로, 프로필 디렉터리의 권한과 코어 로그를 확인하세요.
• url: GitHub 저장소의 Raw 파일 주소입니다. 저장소 이름, 브랜치, 디렉터리와 파일명이 실제 경로와 일치해야 합니다.
• interval: 자동 갱신 간격을 초 단위로 지정합니다. 예시의 86400은 하루이며, 매분처럼 지나치게 짧은 간격을 설정할 필요는 없습니다.

예시의 Proxy는 실제 설정 파일에 존재하는 프록시 그룹 이름으로 바꾸세요. 예를 들어 그룹이 🌏 Global이라면 그 이름을 정확히 지정해야 합니다. 그룹이 정의되어 있지 않거나 이름이 일치하지 않으면 설정 검증에서 오류가 나거나 트래픽이 기대한 그룹으로 연결되지 않습니다. 직접 연결을 원한다면 대상에 DIRECT를 지정할 수 있습니다.

rules는 위에서부터 순서대로 검사됩니다. provider 규칙은 이를 덮어쓸 수 있는 더 넓은 일반 규칙이나 최종 MATCH보다 앞에 두세요. 그렇지 않으면 앞선 규칙에서 이미 트래픽이 일치해 provider까지 도달하지 않습니다. 여러 provider를 쓸 때도 구체적인 규칙을 먼저 배치하고, 마지막에는 일반 트래픽을 처리할 기본 규칙을 둡니다.

3업데이트와 적용 여부 검증하기

설정을 저장한 뒤에는 곧바로 사이트에 접속하기보다 먼저 설정 문법과 provider 다운로드를 확인합니다. Clash Verge Rev 등 GUI를 사용한다면 현재 프로필이 수정한 설정을 실제로 불러왔는지 확인하고, Mihomo 코어 로그에서 설정 로드 오류와 rule-provider 갱신 결과를 살펴보세요. 설정 변경을 저장했더라도 다른 프로필이 활성화되어 있으면 새 규칙은 적용되지 않습니다.

1. 설정 검증: YAML의 들여쓰기, 콜론, 따옴표와 목록 구조를 확인합니다. 특히 rule-providers와 rules는 최상위 키로 배치되어야 합니다.
2. 원본 주소 확인: Raw URL을 브라우저에서 열어 실제 YAML 내용이 표시되는지 확인합니다. 404 응답, GitHub 로그인 화면, HTML 페이지가 나오면 URL이나 저장소 접근 설정이 잘못된 것입니다.
3. 프로필 다시 불러오기: 설정을 저장하고 사용 중인 프로필을 업데이트하거나 코어를 다시 시작합니다. GUI의 규칙 또는 provider 화면에서 해당 이름과 갱신 상태가 표시되는지도 확인합니다.
4. 실제 요청 추적: 대상 도메인에 접속한 뒤 연결 기록에서 매칭된 규칙이 RULE-SET인지, 선택된 그룹이 의도한 그룹인지 확인합니다.

규칙이 적용되지 않을 때는 문제를 단계별로 분리하면 원인을 빠르게 찾을 수 있습니다. provider 목록이 비어 있거나 다운로드 오류가 보이면 네트워크 연결, Raw URL, 파일 경로와 코어 로그부터 확인합니다. provider는 정상인데 대상 도메인이 다른 그룹을 사용한다면 규칙 순서, 도메인 오타, 그룹 이름을 점검합니다. 연결 기록에서 도메인 대신 IP만 보이는 환경이라면 DNS 처리 방식이나 해당 규칙 유형이 실제 요청과 맞는지도 살펴보세요.

• 갱신이 되지 않음: interval이 아직 지나지 않았을 수 있습니다. 테스트를 위해 간격을 계속 짧게 두기보다, 설정을 다시 불러오거나 클라이언트가 제공하는 provider 갱신 기능을 사용하고 로그에서 결과를 확인하세요.
• YAML 파싱 오류: 목록 앞의 하이픈, 공백 들여쓰기, 따옴표를 검사합니다. GitHub 화면의 보기용 문서가 아니라 Raw 파일을 기준으로 확인하세요.
• 규칙에 매칭되지 않음: 파일의 도메인 항목과 접속 기록에 표시되는 실제 호스트 이름이 맞는지 비교합니다. 리디렉션이나 별도 CDN 도메인이 사용되면 필요한 항목을 추가해야 할 수 있습니다.
• 잘못된 프록시 그룹: RULE-SET의 마지막 인수가 현재 프로필의 그룹 이름과 일치하는지 확인합니다. 철자와 공백도 구분됩니다.

규칙을 자주 바꾸는 경우에는 먼저 소수의 테스트 도메인으로 검증한 뒤 목록을 확장하세요. GitHub에서 파일을 수정한 직후에는 캐시와 갱신 주기 때문에 모든 클라이언트에 즉시 반영되지 않을 수 있습니다. 변경 사항이 도착했는지는 파일의 최신 내용만 보는 것이 아니라 Mihomo 로그와 실제 연결 기록을 함께 확인하는 것이 가장 확실합니다. 여러 기기에서 같은 provider를 사용한다면 각 기기의 코어 버전, 활성 프로필, 갱신 상태도 비교하세요.

정리하면 rule-providers는 사용자 규칙을 메인 설정에서 분리해 재사용하고 업데이트하기 좋은 방법입니다. GitHub 파일의 형식과 원본 주소를 정확히 관리하고, provider의 동작 방식과 규칙 유형을 맞춘 다음, 실제 RULE-SET 매칭과 프록시 그룹까지 검증하면 문제를 크게 줄일 수 있습니다. 설정을 공유하거나 배포할 때는 파일을 공개해도 되는지 확인하고, 변경 기록을 남겨 문제가 생겼을 때 이전 버전으로 되돌릴 수 있도록 관리하세요.

Clash 다운로드 →