이 글이 맞는 검색 의도
Clash rule-providers를 검색하는 개발자와 네트워크 엔지니어는 대개 하나의 거대한 YAML 파일을 계속 수정하고 싶지 않아서 GitHub에 라우팅 규칙을 분리해 관리하는 방법을 찾습니다. 특정 SaaS 도메인은 프록시로 보내고, 사내 시스템과 국내 서비스는 DIRECT로 남기며, 변경된 규칙을 일정한 주기로 자동 반영하고 싶은 상황입니다. 규칙이 몇 줄일 때는 프로필 안에 직접 작성해도 되지만, 팀 단위 운영이나 여러 장치에서 같은 정책을 공유하려면 파일을 분리하는 편이 훨씬 안전합니다.
이 글에서는 Clash Verge Rev와 Mihomo 계열 코어에서 사용할 수 있는 일반적인 구조를 기준으로 설명합니다. GitHub 저장소를 공개 또는 비공개로 운영하는 방법, rule-provider의 YAML 형식, 프록시 그룹 연결, 규칙 매칭 순서, 자동 갱신과 캐시 문제, 마지막으로 로그를 이용한 장애 분석까지 한 흐름으로 다룹니다. 클라이언트의 메뉴 이름과 지원 옵션은 버전에 따라 조금 다를 수 있으므로, 최종적으로는 현재 사용 중인 코어의 설정 검증 결과와 공식 문서를 함께 확인하세요.
중요한 전제는 rule-provider가 프록시 노드나 비밀 키를 저장하는 기능이 아니라는 점입니다. 이 기능은 주로 도메인·IP·클래스 규칙을 외부 파일로 가져오는 역할을 합니다. GitHub에 올리는 파일에는 토큰, 사내 호스트 목록, 개인용 구독 URL처럼 공개되면 안 되는 정보가 들어가지 않도록 먼저 범위를 정해야 합니다.
rule-providers와 GitHub 저장소의 기본 구조
Clash 설정은 보통 무엇을 매칭할지를 정의하는 규칙과, 매칭된 트래픽을 어느 정책 그룹으로 보낼지를 정의하는 부분으로 나뉩니다. rule-provider는 첫 번째 부분을 외부 파일로 떼어내는 장치입니다. 메인 프로필에는 공급자 이름과 갱신 주기, 다운로드 주소를 적고, 실제 도메인 목록은 GitHub의 Raw URL에서 가져옵니다.
예를 들어 저장소를 다음처럼 작게 나누면 변경 이력을 읽기 쉽습니다.
- ai.yaml: AI API와 개발용 모델 서비스 도메인
- work.yaml: 회사 SaaS, 사내 인증과 협업 도구
- direct.yaml: 프록시를 사용하지 않을 국내 서비스와 내부 도메인
- reject.yaml: 광고·추적·원치 않는 연결을 차단하는 목록
파일 하나에 모든 목적을 넣을 수도 있지만, 업무·개인·테스트 정책을 분리하면 변경 검토와 롤백이 쉬워집니다. 특히 팀원이 GitHub에서 Pull Request를 열어 특정 도메인을 추가하도록 하면, 누가 언제 어떤 이유로 규칙을 바꿨는지 남길 수 있습니다. 다만 공개 저장소에서는 고객사 도메인이나 내부 서비스 이름이 조직 정보를 노출할 수 있으므로, 민감한 목록은 비공개 저장소나 사내 Git 서버에서 관리하는 것이 적절합니다.
rule-providers:
ai-services:
type: http
behavior: domain
url: https://raw.githubusercontent.com/example-org/clash-rules/main/ai.yaml
path: ./ruleset/ai-services.yaml
interval: 86400
proxy: RULE-SET-UPDATE
work-services:
type: http
behavior: classical
url: https://raw.githubusercontent.com/example-org/clash-rules/main/work.yaml
path: ./ruleset/work-services.yaml
interval: 43200
rules:
- RULE-SET,ai-services,AI
- RULE-SET,work-services,WORK
- MATCH,FINALtype은 공급자 파일을 어떻게 가져올지, behavior는 파일 안의 규칙이 도메인 목록인지 클래식 규칙 형식인지 구분합니다. 단순한 도메인 목록에는 domain이 관리하기 편하고, DOMAIN-SUFFIX와 DOMAIN-KEYWORD를 직접 조합하거나 IP 규칙을 넣어야 한다면 코어가 요구하는 classical 형식을 선택해야 합니다. path는 다운로드된 파일을 로컬에 저장할 위치이며, 앱이나 코어가 해당 디렉터리에 쓸 수 있어야 합니다.
YAML 작성과 매칭 순서 제어
규칙이 예상과 다르게 동작하는 가장 흔한 원인은 YAML 문법보다 매칭 순서입니다. Clash는 일반적으로 위에서 아래로 규칙을 평가하고, 먼저 일치한 항목의 정책을 적용합니다. 따라서 넓은 GEOSITE나 DOMAIN-SUFFIX를 위에 배치하면, 그 아래에 적은 예외 규칙까지 도달하지 못할 수 있습니다.
예를 들어 전체 example.com을 DIRECT로 보내면서 api.example.com만 프록시로 보내고 싶다면, 더 구체적인 예외를 먼저 작성해야 합니다. 반대로 예외 파일과 일반 파일을 각각 rule-provider로 운영할 때도 동일한 원칙이 적용됩니다. 구체적인 호스트 → 서비스 그룹 → 지역·대역 규칙 → 최종 MATCH 순서로 좁혀 가면 의도하지 않은 우회가 줄어듭니다.
- 정확한 도메인: 로그인·API처럼 영향 범위가 작아야 하는 엔드포인트에 사용합니다.
- 도메인 접미사: 동일 서비스의 여러 하위 도메인을 묶을 때 편리하지만, 해당 접미사를 공유하는 다른 서비스까지 포함될 수 있습니다.
- 키워드: 빠르게 테스트할 때는 유용하지만 이름이 비슷한 전혀 다른 호스트를 잡을 수 있어 운영 규칙에는 신중해야 합니다.
- IP-CIDR: 고정 IP 서비스나 내부 네트워크에 필요하지만, CDN과 클라우드 환경에서는 주소가 자주 바뀔 수 있습니다.
- FINAL 또는 MATCH: 모든 앞선 규칙에 걸리지 않은 트래픽의 기본 정책입니다. 이 항목은 보통 마지막에 둡니다.
공급자 파일을 수정할 때는 들여쓰기를 공백으로 통일하고, 탭 문자를 사용하지 않는 편이 좋습니다. 도메인 앞에 불필요한 공백이나 따옴표를 섞으면 일부 코어에서 파싱 결과가 달라질 수 있습니다. GitHub Actions나 로컬 CI에서 YAML 파서와 Clash 설정 검증을 함께 실행하면, 잘못된 커밋이 모든 장치에 배포되는 상황을 예방할 수 있습니다. 파일명과 공급자 이름도 일관되게 유지하세요. ai-services라는 이름을 어느 날 ai로 바꾸면, 메인 프로필의 RULE-SET 참조를 함께 수정해야 합니다.
정책 그룹 이름 역시 공급자 파일 안에 넣지 말고 메인 프로필에서 관리하는 것이 좋습니다. 같은 규칙을 테스트 그룹, 업무 그룹, 자동 선택 그룹에 번갈아 연결할 수 있기 때문입니다. 운영 중에는 먼저 테스트용 그룹으로 연결한 다음, 연결 로그와 실제 응답을 확인하고 기본 그룹으로 승격하는 단계적 배포가 안전합니다.
GitHub 자동 갱신과 배포 전략
interval은 rule-provider가 외부 파일을 다시 확인하는 주기입니다. 하루 한 번 바뀌는 목록에 짧은 주기를 지정하면 GitHub 요청과 로컬 파싱이 불필요하게 늘어납니다. 반대로 장애 대응용 차단 목록을 일주일 주기로 두면 변경이 늦게 반영될 수 있습니다. 서비스 성격에 따라 30분, 6시간, 24시간처럼 주기를 나누고, 저장소의 실제 변경 빈도와 맞추세요.
GitHub Raw 주소는 CDN 캐시나 네트워크 상태의 영향을 받을 수 있습니다. 커밋 직후 모든 클라이언트가 즉시 새 파일을 받는다고 가정하지 말고, 변경 후 충분한 시간이 지난 뒤 앱의 공급자 상태에서 마지막 갱신 시각·HTTP 응답·파일 크기를 확인하세요. 갱신 실패 시 기존에 캐시된 파일을 계속 사용하는 코어도 있고, 공급자를 비활성화하는 코어도 있으므로 장애 시 기본 동작을 미리 알아 두어야 합니다.
운영 저장소에는 다음과 같은 규칙을 두면 관리 품질이 좋아집니다.
- 변경 이유와 영향 범위를 커밋 메시지에 적습니다.
- 도메인을 추가하기 전에 기존 목록과 중복 여부를 확인합니다.
- 일반 규칙과 예외 규칙을 별도 파일로 구분합니다.
- 병합 전 YAML 문법, 중복, 잘못된 도메인 형식을 검사합니다.
- 문제가 생겼을 때 되돌릴 수 있도록 태그나 이전 커밋을 보존합니다.
비공개 GitHub 저장소를 사용할 때는 인증 방식이 특히 중요합니다. 클라이언트가 개인 액세스 토큰을 URL에 직접 넣는 방식은 기록·로그·공유 화면에 토큰이 노출될 위험이 큽니다. 가능하면 인증을 지원하는 배포 계층이나 사내 프록시를 사용하고, 꼭 토큰이 필요하다면 읽기 전용 권한과 만료일을 제한하세요. 공개 저장소에 실수로 비밀 값이 커밋됐다면 파일만 삭제하는 것으로 끝나지 않습니다. Git 기록에 남아 있을 수 있으므로 즉시 키를 폐기하고 새 자격 증명을 발급해야 합니다.
여러 사용자가 서로 다른 프록시 그룹을 써야 한다면 저장소는 공통 규칙만 제공하고, 각자의 프로필에서 정책 그룹을 연결하세요. 그러면 규칙 파일을 업데이트해도 노드 선택이나 개인별 네트워크 정책이 덮어써지지 않습니다. 사내 환경에서는 변경 전 테스트 프로필을 운영하고, 일정 시간 동안 오류율과 응답 지연을 관찰한 뒤 기본 프로필에 반영하는 방식이 현실적입니다.
갱신 실패와 잘못된 라우팅을 분석하는 순서
규칙이 작동하지 않을 때 메인 프로필 전체를 무작정 수정하지 말고, 먼저 문제가 파일 다운로드인지 YAML 파싱인지 규칙 매칭인지 분리해야 합니다. 브라우저나 명령줄에서 Raw URL을 열어 실제 파일이 반환되는지 확인하고, HTML 오류 페이지가 저장된 것은 아닌지 살펴보세요. GitHub 저장소를 비공개로 바꾼 뒤 인증이 끊겼거나, 브랜치 이름을 main에서 바꾼 뒤 URL이 낡은 경우도 자주 있습니다.
파일이 정상적으로 내려왔는데 공급자 상태가 오류라면 behavior와 파일 문법을 확인합니다. 도메인 목록을 클래식 규칙으로 선언하거나, 클래식 규칙을 도메인 전용 공급자로 읽게 하면 파싱은 되더라도 기대한 매칭이 나오지 않을 수 있습니다. 파일 안의 첫 줄과 마지막 줄, 줄바꿈 형식, 인코딩을 확인하고 코어 로그에서 오류 위치를 찾으세요.
공급자는 정상인데 연결이 잘못된 그룹으로 간다면 로그에서 다음 정보를 같은 시각에 비교합니다.
- 실제 요청의 호스트 이름과 포트
- 적용된 규칙 또는 RULE-SET 이름
- 선택된策略 그룹과 최종 노드
- DNS 응답 결과와 연결 주소
- 요청이
DIRECT, 프록시,REJECT중 어디로 갔는지
특히 앱이 접속하는 주소가 문서에 적힌 대표 도메인과 다를 수 있습니다. 로그인은 한 도메인을 사용하지만 API, 이미지, 스트리밍, 업데이트 검사는 별도의 호스트를 사용할 수 있습니다. 대표 도메인 하나만 GitHub 목록에 넣고 모든 트래픽이 해결되기를 기대하면, 브라우저 화면은 열리는데 CLI나 백그라운드 동기화만 실패하는 현상이 남습니다. 먼저 로그에서 실제 호스트를 수집하고, 필요한 범위만 규칙에 추가하세요.
규칙을 수정한 뒤에는 앱을 재시작하기 전에 공급자만 수동 업데이트할 수 있는지 확인하면 원인 파악이 빠릅니다. 수동 갱신 후에도 이전 결과가 유지된다면 로컬 캐시 경로와 파일 수정 시각을 확인하고, 코어를 재시작한 뒤 다시 검증합니다. 반대로 모든 규칙이 갑자기 사라졌다면 원격 파일의 빈 커밋, 잘못된 브랜치, GitHub rate limit을 의심해야 합니다. 최종 MATCH를 너무 공격적으로 REJECT에 연결하지 말고, 테스트 단계에서는 별도 로그 그룹이나 DIRECT를 사용해 누락된 호스트를 발견하는 편이 안전합니다.
단순한 GUI 규칙 편집기는 빠른 테스트에는 편하지만, 규칙 수가 늘어나면 변경 이력·검토·자동 검증을 관리하기 어렵고 앱마다 지원 문법도 달라질 수 있습니다. 반대로 GitHub 기반 rule-provider는 저장소 권한과 YAML 문법을 직접 관리해야 한다는 부담이 있지만, 버전 관리, 롤백, 팀 리뷰, 일정한 자동 갱신을 한 흐름으로 묶을 수 있습니다. 특히 Clash는 공급자와 정책 그룹을 분리하고 실제 로그에서 매칭 결과를 확인할 수 있어, 여러 서비스를 목적별로 나누어 운영하려는 경우 설정 변경의 근거가 분명합니다. 비슷한 도구에서 흔한 수동 파일 복사와 불투명한 업데이트 문제를 줄이면서 맞춤 라우팅을 관리하고 싶다면, 이 구조를 적용할 수 있는 Clash 클라이언트부터 준비해 보세요.