설정 2026년 10월 17일

Mihomo rule-providers 설정: GitHub 규칙셋 관리와 자동 갱신 실전 가이드

사용자 정의 규칙을 별도 YAML로 관리하고 Mihomo에서 GitHub를 통해 자동으로 갱신하는 방법을 살펴봅니다. 주요 설정 필드와 규칙 적용 순서, Git 버전 관리, provider 로딩 오류 점검법을 실전 중심으로 정리했습니다.

공항 선택 Clash 구독 보안 가이드

rule-providers가 필요한 상황

Mihomo의 rule-providers는 여러 규칙을 메인 프로필의 rules에 직접 늘어놓지 않고, 별도 파일이나 원격 주소에서 관리하도록 해 주는 기능입니다. GitHub에 도메인·IP 규칙을 저장해 두면 프로필은 그 목록을 참조하고, Mihomo가 설정한 간격에 따라 원격 파일의 변경 사항을 가져옵니다. 개인 기기 여러 대에서 동일한 예외 규칙을 써야 하거나, 규칙이 자주 바뀌어 구독 설정을 매번 편집하기 번거로운 경우에 특히 유용합니다.

다만 rule-provider는 규칙의 목적지를 정하는 프록시 그룹이 아닙니다. provider가 규칙 데이터를 제공하고, 메인 프로필의 rules 줄이 해당 규칙과 일치하는 연결을 어느 그룹으로 보낼지 결정합니다. 예를 들어 특정 도메인을 provider에 넣어도 그 이름을 참조하는 RULE-SET 줄이 없거나, 그 줄보다 앞에 일치하는 규칙이 있으면 기대한 경로로 처리되지 않습니다. 관리 파일, 참조 줄, 규칙 순서를 하나의 구성으로 확인해야 합니다.

또한 자동 갱신은 GitHub 저장소가 바뀌는 즉시 모든 연결이 바뀐다는 뜻이 아닙니다. Mihomo가 provider를 처음 불러오고, 이후 설정된 interval이 지나 원격 파일을 다시 확인해야 합니다. 클라이언트 UI에서 편집 중인 설정이 활성 프로필인지도 확인하세요. Clash Verge Rev 같은 그래픽 클라이언트는 프로필 관리 화면과 Mihomo 코어를 함께 제공하지만, 실제 규칙 처리와 갱신은 코어가 수행합니다.

provider 유형과 핵심 필드 선택

원격 GitHub 파일을 정기적으로 가져오려면 보통 type: http를 사용합니다. type: file은 로컬 파일을 읽는 방식이므로, 별도의 동기화 절차를 마련하지 않는 한 GitHub에서 자동으로 내용을 가져오지는 않습니다. 규칙 데이터의 형식과 내용에 맞춰 behavior와 format도 지정해야 합니다. behavior는 규칙이 도메인 중심인지, 여러 규칙 유형을 섞은 목록인지, IP 대역 중심인지 구분하는 값이며, format은 원격 파일이 YAML인지 일반 텍스트인지 알려 줍니다.

다음은 YAML 형식의 도메인 규칙을 GitHub에서 가져오는 개념 예시입니다. 저장소 이름, 브랜치, 파일 경로, 그룹 이름은 실제 구성에 맞게 바꿔야 합니다. 여기의 URL은 형식 설명용 자리표시자이며 그대로 사용하지 마세요.

rule-providers:
  WORK-TOOLS:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/OWNER/REPO/main/rules/work-tools.yaml"
    path: ./ruleset/work-tools.yaml
    interval: 86400

rules:
  - RULE-SET,WORK-TOOLS,PROXY
  - MATCH,DIRECT

provider 이름인 WORK-TOOLS는 rules의 RULE-SET 항목과 정확히 일치해야 합니다. 대소문자나 하이픈이 다른 이름을 참조하면 규칙을 찾지 못할 수 있습니다. 설정에 proxy, 인증 헤더 등 추가 옵션을 쓰려면 사용 중인 Mihomo 버전에서 해당 필드가 지원되는지 확인하고, 꼭 필요한 경우에만 추가하는 편이 좋습니다.

GitHub 저장소와 자동 갱신 구성

GitHub에서는 규칙 파일을 일반 소스 코드와 분리해 두면 검토하기 편합니다. 예를 들어 저장소에 rules/work-tools.yaml을 만들고, 도메인 동작만 담는다면 다음처럼 작성할 수 있습니다. payload 아래 각 항목은 사용 중인 규칙 유형에 맞아야 하며, 도메인 목록에 임의의 DOMAIN-SUFFIX 접두어를 섞지 않도록 형식과 behavior를 맞춥니다.

payload:
  - '+.example.com'
  - 'api.example.net'
  - 'DOMAIN-SUFFIX,tools.example.org'

위 예시는 형식 선택의 차이를 보여 주기 위한 것입니다. behavior: domain을 쓰면 도메인 규칙 형식에 맞는 항목만 두고, DOMAIN-SUFFIX,... 같은 명시적 규칙 유형을 포함하려면 해당 파일 구조에 맞게 behavior: classical과 지원되는 포맷을 선택해야 합니다. 문서에 있는 샘플을 복사할 때도 파일 내용과 provider 설정이 서로 호환되는지 먼저 확인하세요. 잘못된 형식은 다운로드에 성공해도 파싱 단계에서 실패할 수 있습니다.

GitHub의 브랜치 이름과 파일 경로는 URL에 그대로 반영됩니다. 기본 브랜치가 main이 아니라면 주소를 고쳐야 하며, Raw 주소로 파일을 직접 열어 YAML 내용이 반환되는지도 브라우저에서 시험할 수 있습니다. 저장소를 비공개로 두면 인증 없이 접근하는 Mihomo가 파일을 가져오지 못합니다. 토큰을 설정 파일이나 공개 저장소에 그대로 넣는 방법은 피하고, 비공개 저장소가 필요하다면 코어가 지원하는 인증 방식과 토큰의 노출 위험을 별도로 검토하세요.

interval: 86400은 하루 단위로 확인하는 예시입니다. 규칙 변경이 즉시 반영되어야 하는 운영 환경이라도 지나치게 촘촘한 주기부터 설정하기보다, 변경 빈도와 GitHub 접근 정책에 맞춰 간격을 정하세요. 앱을 재시작하거나 설정을 다시 불러온다고 해서 원격 파일이 항상 즉시 재요청되는 것은 아닙니다. 테스트 중 빠른 반영이 필요하면 provider 갱신 기능이 클라이언트에 표시되는지 확인하고, 갱신 결과를 로그에서 검증합니다.

규칙 적용 순서와 안전한 분리

Mihomo는 rules를 위에서부터 확인해 처음 일치한 규칙의 정책을 적용합니다. 그러므로 provider가 정상적으로 갱신되더라도 더 넓은 규칙이 위에서 먼저 매칭되면 provider 규칙은 실행되지 않을 수 있습니다. 예를 들어 모든 도메인을 처리하는 와일드카드 성격의 규칙을 위쪽에 두면 그 아래의 세부 규칙은 사실상 도달할 수 없습니다. 구체적인 예외를 앞에 두고, provider의 범주 규칙을 적절한 위치에 배치한 뒤, 마지막에 최종 처리 규칙을 두는 구성이 이해하기 쉽습니다.

여러 provider를 사용할 때는 목적과 변경 주기를 기준으로 분리하는 것이 좋습니다. 업무 도메인, 광고 차단, 내부 서비스 예외를 한 파일에 모두 넣으면 변경 한 번으로 예상하지 못한 트래픽까지 영향을 받을 수 있습니다. provider를 나누면 로그에서 어떤 목록이 매칭됐는지 파악하기 쉽고, 특정 목록만 비활성화해 원인을 좁힐 수도 있습니다. 다만 작은 목록까지 지나치게 잘게 쪼개면 URL과 관리 항목이 많아지므로, 팀에서 소유권과 검토 책임을 나눌 수 있는 단위로 정합니다.

원격 규칙은 연결 경로뿐 아니라 사용자의 실제 접속 경험을 바꿉니다. 광범위한 도메인 패턴이나 IP 대역을 추가하기 전에 어떤 서비스가 영향을 받는지 검토하고, 필요하다면 테스트 그룹으로 먼저 적용하세요. 구독 프로필과 사용자가 직접 관리하는 규칙이 동시에 존재하는 환경에서는 업데이트 후 사용자 정의 규칙의 위치가 유지되는지도 확인해야 합니다. UI가 설정을 병합하거나 생성하는 방식은 버전과 프로필 구조에 따라 다를 수 있으므로, 편집 화면의 모양만 믿지 말고 활성 설정과 코어 로그를 함께 확인합니다.

Git 버전 관리와 변경 검토

GitHub를 쓰는 장점은 파일을 원격에 두는 것만이 아닙니다. 변경 이력을 남기고, 검토한 다음 적용할 수 있다는 점이 운영상 더 중요합니다. 규칙을 추가할 때는 커밋 메시지에 도메인과 이유를 기록하고, 삭제할 때도 대상과 영향 범위를 설명하세요. 예를 들어 “API 연결 실패 대응으로 특정 호스트를 추가”처럼 원인을 남기면 몇 주 뒤 문제가 재발했을 때 이전 변경을 되짚기 쉽습니다. 개인 저장소라도 한 번에 대량 수정하기보다 작은 단위로 나누면 오타나 과도한 매칭을 찾기 편합니다.

공유하는 규칙을 안정적으로 운영하려면 기본 브랜치에 바로 수정하기보다 작업 브랜치에서 검토한 뒤 병합하는 방법을 고려할 수 있습니다. 단, provider의 Raw URL이 특정 브랜치를 가리키므로 병합 대상 브랜치와 실제 배포 URL이 일치해야 합니다. 특정 커밋의 내용을 고정하는 방식은 재현성을 높일 수 있지만, 이후 변경을 자동으로 따라가지 못할 수 있습니다. 반대로 움직이는 브랜치의 URL은 업데이트가 편하지만, 검토되지 않은 커밋이 다음 갱신에 포함될 수 있습니다. 자동화와 변경 통제 중 무엇이 더 중요한지에 따라 선택하세요.

규칙 파일 변경 뒤에는 적어도 다음을 확인합니다.

검토 가능한 절차가 있다고 해서 GitHub가 규칙의 안전성을 자동으로 보장하는 것은 아닙니다. 외부 기여를 받는 공개 저장소라면 변경 내용을 확인하지 않고 자동 병합하지 말고, 규칙 목록을 작성하거나 수정할 수 있는 사람을 제한하세요. 특히 MATCH와 같이 광범위하게 동작하는 항목은 provider에 넣지 않는 편이 관리하기 쉽습니다. 최종 정책은 메인 프로필에서 눈에 보이도록 두고, provider에는 분류 데이터만 맡기는 방식이 변경 영향 분석에 유리합니다.

provider 오류를 진단하는 순서

갱신이 되지 않을 때는 노드를 먼저 바꾸기보다 실패 단계를 나눠 보세요. 첫째, URL 접근 문제인지 확인합니다. Raw URL이 잘못되었거나 브랜치·파일 경로가 바뀌면 HTTP 오류가 납니다. 둘째, 접근은 되지만 응답 본문이 규칙 파일이 아닌 경우를 살핍니다. 저장소 웹 페이지 URL이나 권한 오류 페이지가 반환되면 다운로드 자체가 성공한 것처럼 보여도 파싱은 실패할 수 있습니다. 셋째, 본문은 맞지만 문법·형식이 설정과 다른 경우를 확인합니다. 마지막으로 provider가 로드된 뒤에도 규칙 순서나 그룹 이름 때문에 트래픽이 다르게 분류되는지 점검합니다.

Clash Verge Rev 등에서 확인할 때는 현재 활성 프로필, Mihomo 코어 버전, provider 상태, 로그의 오류 문구를 함께 기록합니다. 오류 시각과 provider 이름을 적어 두면 여러 목록이 있는 구성에서도 원인을 좁힐 수 있습니다. 업데이트가 성공했다고 표시되는데 오래된 결과가 보인다면, 저장된 path의 파일이 어느 프로필에서 쓰이는지, 클라이언트가 다른 설정 파일을 활성화했는지 확인하세요. 로컬 캐시 파일을 임의로 삭제하기 전에 백업하고, UI의 갱신 또는 설정 다시 불러오기 기능을 우선 사용합니다.

규칙을 수정한 뒤에는 가능한 한 한 번에 하나의 변수를 바꾸세요. URL과 YAML 형식과 규칙 순서를 동시에 바꾸면 무엇이 문제를 해결했는지 알기 어렵습니다. 먼저 URL에서 본문이 정상적으로 열리는지 확인하고, 그다음 Mihomo가 provider를 읽는지, 마지막으로 실제 요청이 의도한 정책을 타는지 확인하면 재현 가능한 진단이 됩니다.

자주 묻는 질문

interval은 초 단위인가요?

네. 원격 provider를 다시 확인하는 간격을 초 단위로 지정합니다. 예를 들어 86400은 하루에 해당합니다. 짧은 간격이 항상 더 빠르고 안정적인 것은 아니므로 규칙 변경 빈도와 접근 환경에 맞게 설정하세요.

type: file도 GitHub에서 자동 갱신되나요?

아니요. file은 로컬 파일을 읽습니다. GitHub의 변경을 로컬 파일에 반영하는 별도 동기화 작업을 구성하지 않았다면 원격 업데이트를 자동으로 가져오지 않습니다. GitHub에서 정기적으로 가져오려면 일반적으로 type: http를 사용합니다.

Raw URL인데도 로드가 실패하는 이유는 무엇인가요?

브랜치나 파일 경로가 틀렸거나, 저장소가 비공개이거나, 응답 파일의 형식이 provider 설정과 다를 수 있습니다. 브라우저에서 해당 주소를 열어 실제 규칙 내용이 반환되는지 먼저 확인한 뒤, 코어 로그에서 HTTP 상태와 파싱 오류를 구분하세요.

갱신 후에도 트래픽이 달라지지 않으면 어떻게 하나요?

provider가 활성 프로필에 로드됐는지, rules에서 정확한 이름으로 참조하는지, 앞선 규칙이 먼저 매칭되지 않는지 확인합니다. 마지막으로 실제 요청의 코어 로그에서 매칭 규칙과 최종 프록시 그룹을 대조하세요.

직접 YAML에 모든 규칙을 적는 방식은 작은 개인 설정에는 간단하지만, 여러 기기에서 같은 목록을 유지하거나 변경 이유를 추적할 때는 수정 내용이 흩어지기 쉽습니다. 반면 GitHub rule-provider는 파일 이력과 검토 절차를 활용하면서 Mihomo가 원격 규칙을 주기적으로 확인하게 할 수 있습니다. 다만 형식 불일치와 잘못된 규칙 순서가 있으면 자동 갱신만으로는 해결되지 않으므로, 버전 관리와 로그 검증을 함께 적용하는 것이 좋습니다. 자신의 프로필에서 provider 구성을 직접 관리하려는 경우, 먼저 사용 중인 Mihomo 호환 클라이언트를 확인하고 필요한 배포 파일을 살펴보세요.

클라이언트 다운로드 →

GitHub 규칙 관리를 시작해 보세요

Mihomo 호환 클라이언트에서 프로필을 확인하고 rule-provider 설정을 점검하세요.