Clash rule-providers 만들기: GitHub 호스팅과 YAML 검증 실전 가이드

1. rule-providers가 하는 일: 규칙 목록을 설정 본문과 분리하기

rule-providers는 자주 바꾸거나 여러 설정에서 재사용할 규칙 목록을 별도 파일로 관리하는 기능입니다. 메인 설정에는 규칙 파일을 가져오는 방법과 갱신 간격을 선언하고, rules에는 제공자 이름과 적용할 정책을 연결합니다. 규칙이 많아져도 전체 구독 YAML을 매번 직접 편집할 필요가 줄고, 목록 파일만 교체해 변경 사항을 관리할 수 있습니다.

다만 모든 Clash 계열 코어가 같은 규칙 제공자 기능을 지원하는 것은 아닙니다. 아래 예시는 mihomo(구 Clash.Meta)의 HTTP 규칙 제공자를 기준으로 합니다. 사용 중인 GUI 클라이언트의 이름만으로 호환성을 판단하지 말고, 실제 선택된 코어와 버전을 확인하세요. 일반 Clash 코어나 오래된 코어에서 rule-providers 또는 특정 behavior를 지원하지 않으면 설정 파싱 단계에서 오류가 날 수 있습니다.

항목	역할	확인할 점
`type`	규칙 파일을 가져오는 방식 지정	원격 파일은 일반적으로 `http`
`behavior`	파일 안의 규칙 데이터 형식 지정	`domain`, `ipcidr`, `classical` 중 파일 내용과 맞추기
`url`	원격 규칙 파일의 주소	브라우저에서 열었을 때 YAML 원문이 반환되는지 확인
`path`	코어가 파일을 저장할 로컬 경로	쓰기 가능한 위치인지, 다른 제공자와 파일명이 겹치지 않는지 확인
`interval`	원격 파일을 다시 확인하는 간격	단위는 초이며, 클라이언트가 실행 중이고 네트워크에 연결되어야 갱신 가능

2. 사용자 YAML 만들기: behavior와 payload 형식 맞추기

먼저 한 가지 목적의 작은 규칙 파일을 만드세요. 아래 예시는 도메인 규칙만 담은 파일입니다. domain 동작 방식은 도메인 항목을 제공하며, 접미사 범위는 +. 접두사로 나타낼 수 있습니다. 파일 이름은 예를 들어 custom-domains.yaml처럼 용도를 알아보기 쉽게 정하고, 저장소에서 메인 설정과 분리된 경로에 둡니다.

payload:
  - '+.example.com'
  - 'service.example.net'
  - '+.updates.example.org'

여기서 example.com은 설명용 도메인입니다. 실제로 운영할 때는 직접 관리하거나 사용할 권한이 있는 도메인으로 바꾸세요. 최상위 payload는 YAML 목록을 담는 키이며, 목록 항목은 따옴표로 감싸 두면 특수 문자나 YAML 파서의 해석 차이로 생기는 문제를 줄일 수 있습니다. URL 전체, https://, 포트 번호, 경로를 도메인 항목에 넣지 마세요.

IP 대역을 관리한다면 behavior: ipcidr와 CIDR 목록을 사용합니다. 반면 기존 Clash 규칙 문법처럼 규칙 종류, 조건, 정책을 한 줄에 쓰려면 classical을 사용해야 합니다. 예를 들어 DOMAIN-SUFFIX,example.com,DIRECT는 도메인 데이터 한 개가 아니라 정책까지 포함한 규칙입니다. 이런 행을 domain 제공자에 넣으면 데이터 형식과 동작 방식이 맞지 않습니다.

payload:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - DOMAIN,api.example.net,해외 프록시

위 형식은 classical 제공자 파일의 예입니다. 정책 이름은 사용 중인 메인 설정의 proxy-groups에 있는 이름과 정확히 같아야 합니다. 실제 운영에서는 목록 파일에 정책까지 넣기보다, 파일은 매칭 조건만 관리하고 최종 정책은 메인 설정의 RULE-SET에서 지정하는 편이 단순합니다. 어느 방식을 선택하든 제공자의 behavior와 파일의 데이터 형식을 일치시키세요.

3. GitHub에 배포하고 메인 설정에 연결하기

공개 저장소를 사용하는 경우 규칙 파일을 저장소에 올리고, 코어가 인증 없이 가져올 수 있는 원문(raw) 파일 주소를 url에 지정합니다. 저장소의 코드 보기 화면 주소와 원문 파일 주소는 다릅니다. 주소를 브라우저에서 열었을 때 HTML 페이지가 아니라 payload:로 시작하는 파일 내용이 보여야 합니다. 비공개 저장소는 인증 정보나 별도 접근 설정이 필요할 수 있으므로, 민감한 토큰을 메인 설정이나 공개 규칙 파일에 넣지 마세요.

다음은 도메인 목록을 하루 간격으로 가져오는 mihomo 설정 조각입니다. 저장소 사용자명, 저장소명, 브랜치, 파일 경로는 실제로 배포한 위치에 맞춰 바꾸세요. path는 다운로드한 파일을 코어가 저장할 위치이며, 저장소 안의 경로와 같은 값일 필요는 없습니다.

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

rules:
  - RULE-SET,custom-domains,DIRECT
  - MATCH,해외 프록시

예시의 OWNER와 REPOSITORY는 자리표시자이므로 그대로 사용하면 가져오기에 실패합니다. custom-domains는 제공자 식별자이며, RULE-SET 첫 번째 인자와 글자까지 정확히 일치해야 합니다. interval: 86400은 24시간을 초 단위로 표현한 값입니다. 이 값은 매초 원격 저장소를 검사하라는 뜻이 아니며, 네트워크가 끊겨 있거나 코어가 실행되지 않는 동안 갱신이 보장되는 것도 아닙니다.

규칙 제공자 연결 자체가 맞는지 먼저 확인하려면 메인 설정의 rules에 제공자 참조를 한 줄 추가하고, 일반적인 최종 규칙은 그 뒤에 둡니다. 이미 MATCH가 있다면 이를 중복으로 추가하지 말고 기존 규칙 목록에 알맞게 삽입하세요. 로컬 path에 파일을 쓸 수 있는지, 시작 로그에서 제공자 초기화와 다운로드가 성공했는지도 확인합니다.

4. 규칙 순서와 갱신: 먼저 일치한 규칙이 출구를 정합니다

RULE-SET은 일반 규칙 목록의 한 항목처럼 위에서 아래로 평가됩니다. 앞쪽 규칙이 이미 연결과 일치하면 뒤에 있는 규칙 제공자는 그 연결을 처리하지 않습니다. 따라서 특정 호스트를 별도 정책으로 보내는 예외는 포괄적인 제공자 규칙보다 앞에 두고, 기본 처리용 MATCH는 보통 마지막에 둡니다.

rules:
  - DOMAIN,login.example.com,해외 프록시
  - RULE-SET,custom-domains,DIRECT
  - MATCH,해외 프록시

위 예시는 login.example.com을 먼저 지정한 정책으로 보내고, 그 밖에 제공자 목록과 일치하는 도메인은 직접 연결하도록 구성합니다. 규칙 파일에 같은 도메인이 여러 번 있거나, 메인 규칙에서 더 넓은 조건이 먼저 적용되면 기대와 다른 정책이 선택될 수 있습니다. 규칙을 바꾼 뒤에는 단순히 페이지를 새로고침하는 데 그치지 말고, 클라이언트의 연결 기록이나 규칙 조회 화면에서 실제로 일치한 항목과 정책을 확인하세요.

원격 파일은 메인 설정과 별도로 갱신됩니다. 새 규칙을 저장소에 올렸는데 즉시 적용되지 않으면 원문 파일의 내용이 변경됐는지, 클라이언트가 해당 제공자를 다시 가져왔는지, 로컬 캐시 파일의 수정 시간이 바뀌었는지 차례로 확인하세요. 클라이언트에서 제공자 새로고침 기능을 지원하면 이를 사용하고, 해당 기능이 없다면 코어 재시작 후 로그를 확인합니다. 규칙이 갱신됐더라도 현재 연결은 이전 정책으로 유지될 수 있으므로 테스트할 때 새 연결을 만드세요.

5. YAML과 동작 검증: 파싱, 원격 응답, 매칭을 나눠 확인

문제가 생기면 한 번에 여러 항목을 바꾸지 말고 세 단계로 나누어 검사합니다. 첫째, YAML의 들여쓰기와 구조가 유효한지 확인합니다. 둘째, 원격 주소가 올바른 파일을 반환하고 로컬 저장 경로에 기록되는지 확인합니다. 셋째, 실제 연결이 의도한 제공자 규칙과 일치하고 올바른 정책으로 나가는지 확인합니다. 파싱 오류와 연결 실패는 원인이 다르므로 같은 방식으로 해결할 수 없습니다.

코어에서 설정 검사

명령줄에서 mihomo를 사용할 수 있다면 해당 실행 파일로 설정 테스트를 진행할 수 있습니다. 옵션은 실행 파일과 배포 버전에 따라 달라질 수 있으므로, 현재 설치본의 도움말도 함께 확인하세요.

mihomo -t -f ./config.yaml

테스트에 실패하면 표시된 줄 번호 주변을 살펴보세요. YAML은 일반적으로 들여쓰기에 공백을 사용하며 탭과 공백을 섞지 않는 편이 안전합니다. 콜론 뒤의 공백 누락, 목록 앞의 하이픈 위치, 따옴표 짝, 키 중복도 확인합니다. 테스트 통과는 기본 설정 구조가 해석된다는 뜻이지, 원격 서버 연결과 규칙 매칭까지 검증됐다는 뜻은 아닙니다.

원격 응답과 로그 확인

브라우저에서 원문 주소를 열어 파일이 공개 상태인지 확인하고, 로그인 페이지나 저장소 오류 화면, 404 응답이 대신 내려오지 않는지 확인합니다. 내용이 맞는데 코어가 파일을 받지 못한다면 주소의 브랜치와 경로, 네트워크 접근, DNS, 로컬 디렉터리 쓰기 권한을 점검하세요. 로그에 제공자 이름이 표시된다면 해당 시각의 요청 오류와 갱신 성공 여부를 비교합니다. 인증 토큰이나 구독 주소가 로그와 화면 공유에 노출되지 않도록 주의하세요.

설정 파싱 오류: type, behavior, url, path의 들여쓰기와 값의 철자를 확인하고, 사용 중인 코어가 규칙 제공자를 지원하는지 확인합니다.
다운로드 실패: 원문 파일 주소, 저장소 공개 범위, 네트워크 연결, 코어 로그를 차례로 확인합니다. 웹페이지의 보기 주소를 원문 주소로 착각하지 마세요.
규칙은 읽혔지만 정책이 다름: 제공자 식별자와 RULE-SET 이름, behavior와 파일 형식, 위쪽에 먼저 일치하는 규칙이 있는지 확인합니다.
갱신했는데 즉시 바뀌지 않음: 마지막 갱신 시각과 로컬 캐시 파일을 확인한 다음, 제공자를 다시 새로고침하고 새로운 테스트 연결로 결과를 비교합니다.

처음부터 수백 개 도메인을 넣기보다 테스트용 항목 몇 개로 시작하면 원인을 찾기 쉽습니다. 기본 연결이 확인된 뒤 목록을 늘리고, 수정 전후의 파일과 설정을 각각 보관하세요. 이렇게 하면 GitHub에 올린 규칙 파일, mihomo가 읽은 제공자, 최종 라우팅 규칙 가운데 어느 단계에서 문제가 생겼는지 비교할 수 있습니다.