규칙을 GitHub에서 관리하면 좋은 경우

여러 기기에서 같은 도메인 분기 정책을 쓰거나, 자주 바뀌는 사용자 정의 규칙을 구독 YAML과 따로 관리하고 싶다면 Clash의 rule-providers를 활용할 수 있습니다. 규칙을 프로필 본문에 매번 직접 붙여 넣는 대신 별도 YAML 파일로 분리하고, GitHub에 공개한 파일을 Clash가 일정 간격으로 다시 가져오도록 구성하는 방식입니다. 규칙 변경 이력이 GitHub에 남으므로 어떤 항목을 언제 추가했는지 확인하기 쉽고, 다른 기기에서도 같은 주소를 참조하면 정책을 일관되게 유지할 수 있습니다.

다만 GitHub에 파일을 올렸다고 모든 Clash 클라이언트에서 자동으로 적용되는 것은 아닙니다. 실제 지원 여부와 설정 키는 사용하는 코어에 따라 달라집니다. 특히 Mihomo 기반 클라이언트와 오래된 Clash 코어는 지원하는 provider 옵션이 다를 수 있으므로, 프로필을 적용하기 전에 코어 종류와 버전을 확인하세요. 이 글에서는 GitHub의 공개 raw 파일을 Mihomo 프로필에 연결하는 흐름을 기준으로 설명합니다. 구독 제공자가 내려주는 기본 프로필을 직접 수정할 수 없다면, 앱의 오버라이드 기능이나 로컬 프로필을 이용해야 할 수도 있습니다.

처음부터 큰 규칙 묶음을 만들기보다는 작은 목록으로 동작을 확인하는 것이 안전합니다. 예를 들어 자주 사용하는 몇 개 도메인만 별도 파일에 넣고, 해당 provider가 올바른 프록시 그룹으로 연결되는지 확인한 다음 목록을 늘려 가세요. provider 파일이 내려받아져도 규칙이 기존 규칙보다 뒤에 있거나 다른 규칙에 먼저 매칭되면 기대한 분기가 일어나지 않을 수 있습니다. 다운로드 성공과 트래픽 매칭은 서로 다른 단계입니다.

GitHub에 규칙 YAML을 올리고 raw 주소 확인하기

먼저 GitHub 저장소에 규칙 전용 파일을 만듭니다. 저장소의 기본 브랜치에 예를 들어 rules/streaming.yaml을 두고, 파일에는 provider가 해석할 수 있는 규칙 항목만 넣습니다. classical 형식은 DOMAIN, DOMAIN-SUFFIX, IP-CIDR처럼 Clash 규칙 문법을 한 줄씩 적을 때 적합합니다. 도메인 목록을 관리하려는 목적이라면 처음에는 구체적인 도메인이나 필요한 하위 도메인 범위만 넣고, 무관한 서비스까지 포함할 수 있는 넓은 패턴은 피하는 편이 좋습니다.

payload:
  - DOMAIN,media.example.com
  - DOMAIN-SUFFIX,video.example
  - DOMAIN-SUFFIX,cdn.example

파일을 저장한 뒤 GitHub 저장소 화면의 일반 파일 주소가 아니라 Raw 보기에서 제공되는 주소를 사용해야 합니다. 일반 주소는 HTML 페이지를 반환하므로 Clash가 YAML 규칙 파일로 읽지 못합니다. raw 주소의 저장소 소유자, 저장소 이름, 브랜치, 파일 경로가 정확한지 확인하고, 브라우저에서 열었을 때 위 예시처럼 원문 YAML이 표시되는지 점검하세요. 브랜치 이름이나 파일 경로를 바꾸면 기존 프로필의 URL도 함께 갱신해야 합니다.

저장소 공개 범위도 확인해야 합니다. 공개 저장소의 raw 파일은 주소를 아는 누구나 내려받을 수 있으므로, 규칙 목록에 개인 도메인, 조직 내부 서비스, 사용자 식별 정보가 들어가서는 안 됩니다. 규칙 파일에는 접근 토큰이나 구독 URL, 계정 정보도 넣지 마세요. 비공개 저장소를 사용하는 경우 인증이 필요한 raw 주소를 클라이언트가 그대로 가져오지 못할 수 있으며, 토큰을 프로필 YAML에 넣으면 기기 백업이나 로그를 통해 노출될 위험이 있습니다. 민감한 정책은 공개 저장소 대신 접근 통제와 배포 방식을 별도로 설계해야 합니다.

rule-providers와 RULE-SET 연결하기

프로필의 rule-providers 아래에 provider 이름과 원격 파일 정보를 지정합니다. 아래는 공개 raw 파일을 주기적으로 가져오는 기본 형태입니다. path는 기기 안에 저장할 캐시 파일 위치, url은 원격 YAML 주소, interval은 갱신 간격(초)을 나타냅니다. behavior 값은 파일 안의 규칙 유형과 맞아야 합니다. 앞 절처럼 일반 Clash 규칙 문법을 목록으로 관리한다면 classical을 사용합니다.

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

rules:
  - RULE-SET,custom-streaming,Streaming
  - MATCH,FINAL

OWNER와 REPOSITORY는 실제 저장소 정보로 바꾸고, 브랜치와 파일 경로도 확인하세요. Streaming은 프로필에 이미 정의되어 있는 프록시 그룹 이름이어야 합니다. 같은 이름의 그룹이 없다면 자신의 그룹 이름으로 바꾸거나, 먼저 유효한 그룹을 구성해야 합니다. 마지막의 MATCH는 앞 규칙에 해당하지 않는 트래픽에 적용되는 포괄 규칙이므로, 사용자 규칙보다 앞에 두면 provider 규칙이 검사되기 전에 모든 요청이 종료될 수 있습니다.

interval을 지나치게 짧게 설정할 필요는 없습니다. 매번 GitHub에 요청하는 빈도가 높아져도 규칙 변경이 더 빨리 반영된다고 보장되지 않으며, 기기 절전이나 네트워크 단절 중에는 갱신 시점이 밀릴 수 있습니다. 하루 한 번 갱신하는 설정은 자주 바뀌지 않는 목록의 시작점으로 무난합니다. 즉시 반영이 필요할 때는 클라이언트에서 프로필 또는 provider를 수동 갱신하고, 실제로 저장소의 새 파일을 받아왔는지 확인하세요.

팁: 클라이언트의 프로필 편집 화면에서 만든 설정이 구독 갱신 때 덮어써지는지 먼저 확인하세요. 구독 원본을 직접 편집할 수 없다면 오버라이드 기능을 사용하거나 별도의 로컬 프로필을 유지하고, 업데이트 전후에 provider와 규칙 순서가 보존되는지 비교하는 편이 안전합니다.

갱신과 규칙 매칭을 확인하는 방법

설정을 저장한 뒤에는 YAML 파싱 결과와 실제 연결 로그를 나누어 확인합니다. 먼저 코어 로그에 provider 초기화 또는 다운로드 오류가 있는지 살펴보세요. 다음으로 파일을 갱신한 뒤 캐시 경로에 규칙이 생성되었는지, 클라이언트가 provider를 정상 상태로 표시하는지 확인합니다. 마지막으로 테스트할 도메인에 연결해 연결 로그에서 해당 요청이 의도한 프록시 그룹을 선택했는지 봅니다. 로그에 원하는 도메인이 나타나지 않는다면, provider 다운로드 문제가 아니라 DNS 처리 방식이나 클라이언트가 연결을 기록하는 방식의 차이일 수도 있습니다.

  • 다운로드 또는 HTTP 오류: raw 주소가 맞는지, 저장소와 파일이 공개 상태인지, 브랜치와 경로의 대소문자가 일치하는지 확인합니다. GitHub 주소를 일반 저장소 페이지 주소로 입력하지 않았는지도 점검하세요.
  • YAML 파싱 오류: 들여쓰기에 탭을 쓰지 않았는지, 목록 앞의 하이픈과 콜론이 올바른지 확인합니다. behavior와 파일 내용 형식이 서로 맞는지도 봅니다.
  • 규칙이 적용되지 않음: RULE-SET 이름이 provider 키와 정확히 같은지, 대상 그룹이 실제로 존재하는지 확인합니다. 더 넓은 도메인 규칙이나 MATCH가 provider 규칙보다 먼저 있는지도 확인해야 합니다.
  • 갱신했는데 이전 결과가 보임: 클라이언트의 수동 업데이트를 실행하고, 원격 파일 자체가 최신 내용으로 바뀌었는지 브라우저에서 확인합니다. 기기별 캐시 경로가 다르면 각 프로필이 별도로 갱신될 수 있습니다.

규칙 충돌을 줄이려면 우선순위를 의도적으로 정리하세요. 특정 도메인을 한 그룹으로 보내는 예외 규칙은 넓은 도메인 묶음보다 앞에 두고, 여러 provider가 같은 도메인을 포함하면 어떤 provider가 먼저 검사되는지 기록해 두는 것이 좋습니다. 예를 들어 전체 서비스 도메인을 한 그룹으로 보내면서 특정 하위 도메인만 직접 연결하려면, 구체적인 예외가 일반 규칙보다 먼저 평가되도록 배치해야 합니다. 결과가 예상과 다를 때는 규칙 파일을 한꺼번에 크게 바꾸기보다 한두 줄씩 변경하고 연결 로그를 비교하면 원인을 찾기 쉽습니다.

팀에서 함께 관리한다면 파일 수정 권한을 제한하고, 변경 목적을 커밋 메시지나 코드 리뷰에 남기세요. 기기마다 같은 URL을 사용하더라도 클라이언트 코어 버전, 프로필 오버라이드, 프록시 그룹 이름이 다르면 결과가 달라질 수 있습니다. 따라서 규칙 파일뿐 아니라 호환 코어, 갱신 주기, 필요한 그룹 이름, 검증한 테스트 도메인을 함께 문서화하는 편이 좋습니다. 규칙 변경 뒤에는 먼저 한 대에서 테스트하고, 문제가 없을 때 나머지 기기에서 갱신하면 여러 기기의 연결 정책이 동시에 잘못 바뀌는 상황을 줄일 수 있습니다.

GUI에서 규칙을 직접 편집하는 방식은 처음 시작하기 쉽지만, 기기가 늘어나면 변경 이력을 추적하기 어렵고 각 기기의 목록이 서로 달라지기 쉽습니다. 반대로 원격 목록만 두고 규칙 순서나 그룹 이름을 점검하지 않으면 다운로드는 성공해도 트래픽이 엉뚱한 경로로 갈 수 있습니다. GitHub의 변경 이력과 Clash의 provider 갱신을 함께 사용하면 목록 관리와 실제 연결 확인을 분리해 점검할 수 있습니다. 여러 기기의 설정을 같은 기준으로 관리하려는 경우, 지원 코어와 보안 범위를 확인한 뒤 Clash 클라이언트를 선택해 적용해 보세요.

다운로드 →