rule-providers로 규칙 파일을 분리하면 좋은 경우

Clash 설정의 rules 항목에 도메인 규칙을 계속 추가하다 보면, 어느 서비스가 어떤 프록시 그룹을 사용하는지 찾기 어려워지고 구독 프로필을 바꿀 때 직접 수정한 내용이 덮어써질 수도 있습니다. rule-providers를 사용하면 자주 바뀌는 분기 규칙을 별도의 YAML 파일로 분리하고, 메인 설정에서는 그 파일을 불러와 적용할 수 있습니다. 규칙 목록은 GitHub에서 관리하고 Mihomo가 지정한 간격으로 다시 받아오도록 구성할 수도 있습니다.

이 방식은 규칙을 노드나 그룹 설정과 분리하고 싶은 경우, 여러 기기에서 같은 규칙 목록을 쓰고 싶은 경우, 또는 도메인 목록을 Git 기록으로 추적하고 싶은 경우에 유용합니다. 다만 여기서 말하는 자동 갱신은 GitHub에 파일을 올리는 순간 사용 중인 클라이언트로 즉시 푸시된다는 뜻이 아닙니다. 클라이언트가 provider의 URL을 정해진 간격으로 조회하고 새 파일을 받아오는 구조이므로, 갱신 주기와 다운로드 가능 여부를 함께 확인해야 합니다.

아래 예시는 Mihomo 호환 코어를 기준으로 설명합니다. Clash라는 이름을 사용하는 모든 앱이 같은 코어와 문법을 지원하는 것은 아니므로, 설정을 적용하기 전에 클라이언트의 코어 종류와 버전을 확인하세요. 앱에 내장된 구독 관리 기능이나 원격 규칙 기능이 별도로 있다면, 해당 기능이 프로필을 다시 불러올 때 로컬 수정 사항을 보존하는지도 살펴보는 편이 안전합니다.

provider 필드와 규칙 파일의 역할

메인 설정의 rule-providers 블록은 규칙 파일의 위치, 형식, 규칙 종류, 다운로드 URL, 갱신 간격을 정의합니다. provider를 선언하는 것만으로 트래픽이 자동 분기되지는 않습니다. 실제로 적용하려면 rules 목록에서 RULE-SET 항목을 호출하고, 그 규칙이 일치했을 때 사용할 프록시 그룹이나 정책을 지정해야 합니다.

필드 역할 확인할 점
type provider를 가져오는 방식 일반적인 원격 파일은 http를 사용
behavior 파일 안에 담긴 규칙의 종류 도메인 목록은 domain, 완성된 규칙 목록은 classical
format 가져올 파일의 형식 YAML 파일이라면 코어에서 지원하는 경우 yaml로 지정
path 다운로드한 파일을 저장할 로컬 경로 provider마다 겹치지 않는 파일명을 사용
url 원격 규칙 파일의 주소 브라우저에서 실제 파일 내용이 열리는지 확인
interval 원격 파일을 다시 확인하는 간격(초) 예를 들어 86400은 24시간 간격

behavior는 파일 내용에 맞춰야 합니다. 도메인 provider는 도메인이나 도메인 접미 목록을 담고, classical provider는 DOMAIN-SUFFIX 같은 Clash 규칙 형식의 항목을 담습니다. 둘을 서로 바꿔 쓰면 YAML 자체가 파싱되더라도 규칙을 읽지 못하거나 코어가 프로필 적용을 거부할 수 있습니다.

GitHub에 규칙 YAML 파일 작성하기

먼저 GitHub 저장소에 규칙 전용 파일을 만들고, 공개 저장소라면 main처럼 안정적으로 유지할 브랜치에 커밋합니다. 아래는 도메인 목록을 제공하는 파일의 간단한 예입니다. 실제 서비스에 필요한 도메인은 연결 로그에서 확인해 추가하고, 넓은 와일드카드로 관계없는 사이트까지 포함하지 않도록 범위를 제한하세요.

payload:
  - '+.example.com'
  - 'api.example.net'
  - 'login.example.org'

이 파일은 규칙 자체만 담으므로 메인 설정의 rules: 블록 전체를 복사해 넣는 방식과 다릅니다. 파일 이름과 저장소 경로를 정한 뒤 GitHub의 원본 파일 보기에서 Raw 주소를 확인합니다. 일반 파일 페이지 URL이 아니라 실제 YAML 텍스트를 반환하는 주소여야 합니다. 저장소를 비공개로 설정하면 인증이 필요한 주소가 될 수 있는데, 클라이언트가 필요한 인증 헤더를 지원하지 않는다면 다운로드가 실패할 수 있습니다. 비밀 토큰을 URL에 넣어 공개 프로필에 저장하는 방식은 피하세요.

도메인 접미를 표현하는 문법은 코어가 지원하는 방식에 맞춰야 합니다. 예를 들어 +.example.com은 해당 도메인의 하위 도메인을 포함하려는 패턴으로 쓰일 수 있지만, 특정 코어 버전에서 지원하는지 확인해야 합니다. 의심스러운 항목은 먼저 작은 테스트 파일에 넣고, 로그에서 실제로 원하는 호스트에 매칭되는지 검증한 뒤 목록에 추가하면 원인 파악이 쉽습니다.

메인 YAML에서 provider를 선언하고 호출하기

메인 설정에는 다음과 같이 provider와 실제 분기 규칙을 함께 추가할 수 있습니다. Proxy는 예시용 정책 그룹 이름이므로, 자신의 설정에 정의된 그룹 이름으로 바꿔야 합니다. path는 코어가 읽고 쓸 수 있는 위치를 지정해야 하며, 여러 provider가 같은 경로를 사용하지 않도록 파일명을 구분하세요.

rule-providers:
  example-services:
    type: http
    behavior: domain
    format: yaml
    path: ./rules/example-services.yaml
    url: "https://raw.githubusercontent.com/OWNER/REPOSITORY/main/rules/example-services.yaml"
    interval: 86400

rules:
  - RULE-SET,example-services,Proxy
  - MATCH,DIRECT

위의 example-services는 provider의 식별자입니다. RULE-SET 뒤의 이름이 선언한 키와 정확히 같아야 하며, 마지막 인수는 일치한 요청을 보낼 대상입니다. 여기서는 Proxy 그룹으로 보냅니다. 실제 설정에서 그룹 이름이 PROXY, 자동 선택 등으로 다르다면 대소문자와 문자까지 일치하도록 수정하세요.

규칙은 일반적으로 위에서 아래로 평가되어 먼저 일치한 항목이 적용됩니다. 따라서 더 구체적인 도메인 예외 규칙을 provider 규칙보다 앞에 둘지, provider 규칙이 다른 넓은 규칙보다 먼저 실행되도록 할지 의도적으로 정해야 합니다. 예를 들어 특정 API 도메인을 직접 연결하고 싶다면 해당 예외를 provider 항목보다 위에 배치할 수 있습니다. 반대로 MATCH 같은 포괄 규칙을 앞쪽에 두면 뒤에 작성한 provider가 실행되지 않을 수 있으므로, 포괄 규칙은 보통 끝에 둡니다.

팁: provider 파일을 여러 서비스가 함께 편집한다면 파일 이름에 역할을 드러내고, 메인 YAML의 키와 GitHub 파일 경로를 간단한 문서로 기록하세요. 키 이름, 다운로드 파일명, 정책 그룹 이름은 서로 다른 값이라는 점을 구분하면 설정 오류를 빠르게 찾을 수 있습니다.

규칙 파일 전체를 provider에 넣고 싶다면 behavior: classical을 사용하고 파일 내용을 해당 코어가 지원하는 클래식 규칙 형식으로 작성합니다. 이 경우에는 도메인 전용 목록과 달리 각 항목에 규칙 종류와 대상이 포함될 수 있습니다. 규칙 파일 형식과 behavior가 맞지 않으면 다운로드는 성공해도 적용 단계에서 실패할 수 있으므로, 두 방식을 한 파일에서 섞지 말고 용도에 맞는 형식을 선택하세요.

자동 갱신과 다운로드 오류 점검

interval: 86400은 하루 간격으로 원격 provider를 다시 확인하도록 설정한 예입니다. 짧은 간격을 지정한다고 GitHub 변경 사항이 항상 즉시 반영되는 것은 아니며, 코어가 실행 중인지, 네트워크에서 Raw 호스트에 연결할 수 있는지, 클라이언트가 provider 업데이트를 실제로 수행했는지에 따라 반영 시점이 달라집니다. 규칙을 바꾼 직후 확인해야 한다면 클라이언트의 provider 업데이트 또는 프로필 새로 고침 기능을 사용하고, 코어 로그에서 요청과 적용 결과를 확인하세요.

오류가 발생하면 먼저 문제를 세 단계로 나눠 봅니다. 첫째, 브라우저에서 Raw URL을 열어 로그인 페이지나 404가 아니라 YAML 내용이 보이는지 확인합니다. 둘째, 메인 설정에서 URL의 오타, 브랜치명, 파일 경로, 따옴표를 확인합니다. 셋째, 앱 로그에서 다운로드 실패와 YAML 파싱 실패를 구분합니다. HTTP 404는 경로·브랜치 문제일 가능성이 높고, 연결 타임아웃이나 TLS 오류는 네트워크 경로 또는 DNS 문제일 수 있습니다. 파일을 내려받았는데 설정이 적용되지 않는다면 YAML 들여쓰기, behavior, provider 이름과 RULE-SET 호출을 다시 대조하세요.

  • 404 또는 파일을 찾을 수 없음: 저장소 소유자, 저장소 이름, 브랜치, 파일 경로와 대소문자를 점검합니다.
  • 시간 초과 또는 연결 오류: 클라이언트 로그에서 Raw 호스트로의 연결 실패 여부를 보고 DNS·프록시·방화벽을 확인합니다.
  • YAML 파싱 오류: 탭 대신 공백을 사용하고, 콜론·따옴표·들여쓰기와 파일 인코딩을 점검합니다.
  • 다운로드는 되지만 분기되지 않음: provider 키, RULE-SET 이름, 대상 그룹, 규칙의 위아래 순서를 확인합니다.
  • 업데이트가 늦음: 간격 설정과 마지막 갱신 시각을 확인하고, 클라이언트가 provider 갱신을 실행했는지 살펴봅니다.

공개 저장소에 규칙을 둘 때는 누구나 내용을 볼 수 있다는 점도 고려해야 합니다. 규칙 목록에 계정 정보, 구독 주소, 개인 서버 주소처럼 공개하면 안 되는 데이터를 넣지 마세요. GitHub Actions 같은 자동화로 파일을 생성한다면 검증되지 않은 입력을 그대로 커밋하지 말고, 변경 기록과 검토 절차를 유지하는 편이 안전합니다. 원격 규칙 파일을 수정할 권한이 있는 사람은 연결 정책을 바꿀 수 있으므로, 저장소 접근 권한도 필요한 사용자에게만 부여하세요.

간단한 GUI 클라이언트의 내장 규칙 편집은 처음 설정하기 쉽지만, 규칙이 커지면 변경 이력을 비교하거나 여러 프로필에 똑같이 반영하기가 번거로울 수 있습니다. 반면 Clash의 rule-providers는 규칙 파일을 버전 관리하고, 적용 위치와 갱신 주기를 분리해 점검할 수 있어 반복 운영에 유리합니다. GitHub 파일의 접근성과 코어 호환성을 먼저 확인한 뒤, 작은 규칙 세트부터 적용해 로그로 검증하면 수동 편집에서 생기는 실수를 줄일 수 있습니다.

다운로드 페이지 보기 →