미호모 rule-providers 설정법: YAML 커스텀 규칙 실전 가이드

서론: 재사용 가능한 규칙을 만드는 방법

도메인이나 IP 규칙을 여러 프로필에서 반복해서 사용하다 보면, 규칙을 복사하고 수정하는 과정에서 누락이나 오타가 생기기 쉽습니다. 서비스별 규칙이 늘어날수록 설정 파일의 rules 섹션도 길어져 관리가 번거로워집니다. Mihomo의 rule-providers를 사용하면 규칙 목록을 별도의 파일로 분리하고, 필요한 프로필에서 같은 목록을 불러와 재사용할 수 있습니다.

rule-provider는 규칙 데이터의 출처와 형식을 정의하며, RULE-SET은 불러온 목록에 어떤 정책을 적용할지 지정합니다. 예를 들어 광고 도메인 목록은 REJECT로, 업무 서비스 목록은 전용 프록시 그룹으로 보낼 수 있습니다. 규칙을 한 곳에서 관리하고 여러 설정에 연결하면 수정 이력을 추적하기도 쉬워집니다.

이 가이드는 Mihomo 코어를 사용하는 Clash Verge Rev 등의 클라이언트를 기준으로 설명합니다. 메뉴 이름이나 프로필 편집 방식은 클라이언트마다 다를 수 있지만, 아래 YAML 구조와 규칙 연결 원리는 동일합니다.

1rule-providers의 구조와 형식 이해

각 provider에는 고유한 이름과 함께 가져오는 방식, 규칙 데이터 형식, 파일 경로가 필요합니다. 원격 파일을 주기적으로 확인하려면 type: http와 interval을 설정합니다. 파일을 직접 내려받아 프로필과 함께 관리하려면 type: file을 사용할 수 있습니다. 원격 provider에서는 URL에 공개적으로 접근할 수 있어야 하며, 인증이 필요한 주소나 비공개 저장소는 클라이언트가 정상적으로 가져오지 못할 수 있습니다.

규칙 데이터 형식은 목록 안에 무엇이 들어 있는지에 따라 선택합니다. behavior: domain은 도메인 목록, behavior: ipcidr은 IP 대역 목록, behavior: classical은 DOMAIN-SUFFIX나 IP-CIDR 같은 완성된 규칙 목록에 적합합니다. provider 파일과 설정의 behavior가 맞지 않으면 업데이트가 성공한 것처럼 보여도 규칙을 읽지 못하거나 코어가 설정을 거부할 수 있습니다.

도메인 목록과 classical 목록의 차이

YAML 형식의 도메인 provider는 보통 payload 아래에 도메인 항목을 기록합니다. 도메인 목록을 사용할 때는 behavior: domain으로 선언하고, 하위 도메인까지 포함할 항목은 +.example.com 형태로 표현할 수 있습니다. 반면 classical 목록은 각 행에 규칙 종류와 대상을 함께 적습니다. 어떤 형식이 적합한지는 원본 규칙 파일의 실제 구조를 기준으로 판단해야 합니다.

위 예시는 파일 내용을 설명하기 위한 구조입니다. 도메인 provider의 항목을 classical 형식으로 작성하거나 그 반대로 지정하지 마세요. 원격 목록을 이용한다면 제공자가 안내하는 형식과 업데이트 주소를 먼저 확인하고, 파일을 직접 운영한다면 파일의 항목과 provider 선언을 함께 검토해야 합니다.

2YAML provider를 설정하고 프록시 그룹에 연결하기

다음 예시는 두 개의 원격 목록을 불러오는 구성입니다. 업무 도메인은 domain 형식으로 프록시 그룹에 전달하고, 광고 차단 목록은 classical 형식으로 거부합니다. URL은 사용자가 신뢰하는 실제 규칙 파일 주소로 바꾸고, path에는 다운로드 파일을 저장할 프로필 기준 경로를 지정하세요.

interval: 86400은 일반적으로 하루 간격으로 업데이트를 확인한다는 의미입니다. 목록이 자주 바뀌지 않는다면 불필요하게 짧은 간격을 지정할 필요가 없습니다. 반대로 URL 서버의 요청 제한이 있거나 네트워크가 불안정한 환경에서는 간격을 지나치게 짧게 설정하면 업데이트 실패가 반복될 수 있습니다. path의 위치는 클라이언트가 프로필을 저장하고 관리하는 방식에 영향을 받으므로, 상대 경로가 어느 디렉터리를 기준으로 해석되는지 실제 코어 로그에서 확인하는 편이 안전합니다.

규칙 적용 순서도 결과에 직접 영향을 줍니다. Mihomo는 규칙을 위에서부터 확인해 먼저 일치한 규칙의 정책을 사용합니다. provider 규칙을 넓은 범위의 규칙이나 MATCH보다 아래에 두면 해당 목록이 먼저 평가되지 않습니다. 일반적으로 provider 규칙을 더 포괄적인 규칙보다 위에 배치하고, 마지막에 기본 처리용 MATCH를 둡니다.

3자동 업데이트와 Git 변경 관리

원격 provider는 설정된 주소에서 규칙 파일을 받아 로컬 경로에 저장하고, 지정한 업데이트 간격에 따라 최신 파일을 확인합니다. 다만 자동 업데이트는 코어가 실행 중이고 주소에 연결할 수 있다는 전제에서 동작합니다. 기기를 오랫동안 종료했거나 프록시 연결이 끊긴 경우에는 업데이트가 늦어질 수 있으므로, 중요한 규칙 변경 직후에는 클라이언트의 provider 새로고침 기능이나 Mihomo 로그를 통해 실제 반영 여부를 확인하세요.

직접 규칙을 관리한다면 Git 저장소에 규칙 파일과 변경 이력을 함께 보관하는 방법이 유용합니다. 예를 들어 rules/business.yaml, rules/ads.yaml처럼 목록별로 파일을 나누면 수정 범위를 파악하기 쉽습니다. 변경 전후의 도메인 추가·삭제 내역이 커밋에 남아 잘못된 항목을 되돌리기도 편리합니다.

1. 작업용 복사본에서 규칙 파일을 수정하고, YAML 들여쓰기가 공백 두 칸으로 일관적인지 확인합니다.
2. provider의 behavior와 파일의 payload 구조가 일치하는지 검토합니다.
3. 변경 내용을 Git에 커밋한 뒤, 원격에서 클라이언트가 접근할 수 있는 주소로 게시합니다.
4. 테스트 프로필에서 provider를 새로고침하고, 오류가 없을 때 주 프로필에 적용합니다.

저장소의 기본 브랜치나 파일 경로를 바꾸면 기존 URL이 더 이상 유효하지 않을 수 있습니다. 배포된 규칙 파일의 주소를 변경할 때는 provider의 url도 함께 갱신하고, 이전 주소가 캐시되거나 업데이트에 실패하는지 확인하세요. 규칙 목록을 공개할 때는 내부 시스템 이름, 사내 도메인, 개인 식별 정보가 실수로 포함되지 않았는지도 살펴야 합니다. 공개 URL로 게시한 파일은 주소를 아는 사람이 열람할 수 있다고 가정하는 것이 안전합니다.

4규칙이 적용되지 않을 때 점검하기

설정을 저장했는데도 예상한 프록시 그룹이 선택되지 않는다면, 먼저 클라이언트의 코어 로그에서 설정 파싱 오류와 provider 다운로드 오류를 구분하세요. YAML 오류가 있으면 설정 전체의 적용이 실패할 수 있고, 다운로드 오류라면 기존 목록이 유지되거나 provider가 비어 있을 수 있습니다. 화면에서 보이는 프로필이 실제 활성 프로필인지도 함께 확인해야 합니다.

• YAML 문법 오류: 탭 대신 공백을 사용했는지, 콜론 뒤에 공백이 있는지, URL에 특수 문자가 있다면 따옴표로 감쌌는지 확인합니다.
• 주소 또는 파일 오류: provider URL을 브라우저나 터미널에서 열어 파일을 가져올 수 있는지 확인합니다. 파일이 비어 있거나 HTML 오류 페이지를 반환하면 규칙으로 처리할 수 없습니다.
• 형식 불일치: 도메인 목록인지 완성된 규칙 목록인지 확인하고 behavior 및 format을 파일 구조와 맞춥니다.
• 경로와 권한: path가 유효한지, 클라이언트가 해당 디렉터리에 파일을 쓸 수 있는지 확인합니다. 경로를 바꾼 뒤에는 provider를 다시 불러오세요.
• 규칙 순서와 대상: 해당 규칙이 MATCH보다 위에 있는지, RULE-SET 이름과 정책 그룹 이름이 정확히 일치하는지 점검합니다.
• 도메인 매칭 범위: 목록에 등록한 도메인과 실제 요청 도메인이 같은지 확인합니다. 서비스가 여러 하위 도메인이나 CDN 도메인을 사용한다면 필요한 항목이 목록에 빠졌을 수 있습니다.

테스트할 때는 한 번에 여러 요소를 바꾸지 마세요. 먼저 provider가 정상적으로 로드되었는지 확인하고, 다음으로 테스트 도메인이 목록과 일치하는지 살펴본 뒤, 마지막으로 선택된 정책과 프록시 그룹을 확인하면 원인을 좁히기 쉽습니다. 클라이언트의 연결 기록이나 Mihomo 로그에 규칙 매칭 정보가 표시된다면 실제 요청이 어떤 규칙에 걸렸는지 확인할 수 있습니다. 진단이 끝나면 임시로 추가한 테스트 규칙을 제거해 정상적인 규칙 순서를 복구하세요.

자주 묻는 질문

로컬 파일로도 rule-provider를 사용할 수 있나요?

가능합니다. 규칙 파일을 직접 관리할 때는 provider 유형을 file로 설정하고 로컬 파일 경로를 지정할 수 있습니다. 원격 업데이트가 필요하지 않다면 로컬 방식이 간단하며, 파일 변경 후에는 클라이언트에서 설정을 다시 불러오거나 provider를 갱신해야 합니다. 파일이 프로필과 함께 이동할 수 있도록 경로가 클라이언트에서 어떻게 해석되는지도 확인하세요.

provider와 일반 rules는 무엇이 다른가요?

일반 rules는 설정에 규칙을 직접 작성하는 방식입니다. provider는 규칙 목록을 별도 파일로 관리해 여러 프로필에서 재사용하거나 업데이트할 수 있게 합니다. 소수의 고정 규칙은 직접 작성하는 편이 간단하고, 규모가 크거나 자주 변경되는 목록은 provider로 분리하는 것이 관리에 유리합니다.

provider가 자동으로 갱신되지 않는 이유는 무엇인가요?

코어가 실행되지 않았거나, 주소에 연결할 수 없거나, 서버가 요청을 거부했을 수 있습니다. 업데이트 간격이 아직 지나지 않았을 수도 있으므로 로그의 마지막 갱신 시각과 오류 메시지를 확인하세요. 수동 새로고침 후에도 실패한다면 URL이 실제 규칙 파일을 반환하는지, 저장 경로에 쓰기 권한이 있는지 점검합니다.

규칙 순서가 provider에도 중요한가요?

그렇습니다. provider 목록 자체의 순서와 별개로, rules에 적은 RULE-SET 항목은 위에서부터 평가됩니다. 넓은 범위의 규칙이나 마지막 기본 규칙이 먼저 일치하지 않도록 provider 규칙을 적절한 위치에 두어야 원하는 정책이 적용됩니다.

Clash 다운로드하기 →