rule-providers의 역할과 설계 범위
Clash의 rule-providers는 자주 바뀌는 도메인 규칙을 메인 프로필과 분리해 관리하는 기능입니다. 모든 rules를 하나의 YAML 파일에 직접 적으면 처음에는 단순해 보이지만, 서비스가 늘어날수록 파일이 길어지고 규칙의 출처와 갱신 시점을 확인하기 어려워집니다. GitHub에 규칙셋을 저장하면 변경 이력을 남기고, 여러 기기에서 같은 주소를 받아 사용할 수 있으며, 문제가 생겼을 때 이전 커밋으로 되돌리기도 쉽습니다.
예를 들어 AI 서비스, 개발 도구, 패키지 레지스트리, 업무용 SaaS를 모두 하나의 목록에 넣는 대신 목적별로 AI-RULES, DEV-RULES, WORK-RULES처럼 나누는 방식이 관리에 유리합니다. 이렇게 하면 특정 서비스만 프록시 그룹을 바꾸거나, 국내에서 빠르게 연결되는 개발 저장소만 DIRECT로 보내는 정책을 독립적으로 조정할 수 있습니다. 중요한 것은 도메인을 많이 모으는 일이 아니라, 각 규칙셋이 어떤 트래픽을 책임지는지 분명하게 정의하는 일입니다.
rule-provider를 도입하기 전에 먼저 확인할 점은 사용 중인 코어가 해당 문법을 지원하는지입니다. Clash 계열 클라이언트의 화면은 서로 달라도 Mihomo 코어를 사용한다면 대체로 비슷한 구조를 해석합니다. 다만 구형 Clash for Windows 환경이나 오래된 코어에서는 필드 이름, 리모트 프로바이더 동작, 규칙 형식 지원 범위가 다를 수 있으므로, 설정을 적용하기 전에 현재 코어 버전과 문서의 예제를 함께 확인해야 합니다.
GitHub에 YAML 규칙셋 만들기
GitHub 저장소에는 규칙 파일과 README를 함께 두는 것이 좋습니다. 파일만 올려 두면 몇 달 뒤 해당 목록이 어떤 서비스용인지, DOMAIN과 DOMAIN-SUFFIX 중 무엇을 의도했는지 다시 확인하기 어렵습니다. 저장소를 공개할 경우에는 개인 도메인, 사내 호스트, 토큰이 들어간 URL을 절대 포함하지 말고, 공개해도 되는 규칙만 별도 파일로 분리하세요.
가장 널리 쓰이는 형식은 도메인 목록을 담은 yaml 파일입니다. 다음은 AI 서비스와 개발 도구를 분리한 개념 예시입니다. 그룹 이름은 자신의 프로필에 실제로 존재하는 프록시 그룹과 일치해야 합니다.
# ai-rules.yaml
payload:
- DOMAIN-SUFFIX,openai.com
- DOMAIN-SUFFIX,anthropic.com
- DOMAIN-SUFFIX,ai.google.dev
- DOMAIN-SUFFIX,googleapis.com
# dev-rules.yaml
payload:
- DOMAIN-SUFFIX,github.com
- DOMAIN-SUFFIX,githubusercontent.com
- DOMAIN-SUFFIX,npmjs.org
- DOMAIN-SUFFIX,pypi.org
- DOMAIN-SUFFIX,docker.io
여기서 payload 아래의 문법은 메인 프로필의 일반 규칙과 같은 방식으로 해석됩니다. 단순 호스트 하나만 지정할 때는 DOMAIN, 하위 도메인을 모두 포함할 때는 DOMAIN-SUFFIX를 사용합니다. 문자열 일부를 기준으로 잡는 DOMAIN-KEYWORD는 편리하지만 오탐 가능성이 큽니다. 예를 들어 DOMAIN-KEYWORD,google은 AI API뿐 아니라 로그인, 문서, 광고, 업무용 서비스까지 넓게 잡을 수 있으므로 운영 규칙에는 신중하게 사용해야 합니다.
GitHub에서 파일의 Raw 주소를 복사할 때는 일반 저장소 페이지 주소가 아니라 raw.githubusercontent.com으로 이어지는 실제 파일 URL을 사용합니다. 브라우저에서 보기 좋은 HTML 페이지 주소를 provider의 url에 넣으면 Mihomo가 YAML을 읽지 못하거나, HTML 문서를 규칙 파일로 오인해 파싱 오류를 낼 수 있습니다.
프로필에 리모트 provider 연결하기
메인 설정의 rule-providers에는 provider 이름, URL, 다운로드 형식, 갱신 주기, 저장 경로를 정의합니다. 아래 예시는 GitHub Raw 파일을 주기적으로 가져오는 기본 패턴입니다. path는 클라이언트가 내려받은 파일을 보관할 위치이며, 여러 provider가 같은 파일명을 사용하지 않도록 이름을 구분하는 편이 안전합니다.
rule-providers:
AI-RULES:
type: http
behavior: classical
format: yaml
url: https://raw.githubusercontent.com/example-user/clash-rules/main/ai-rules.yaml
path: ./ruleset/ai-rules.yaml
interval: 86400
DEV-RULES:
type: http
behavior: classical
format: yaml
url: https://raw.githubusercontent.com/example-user/clash-rules/main/dev-rules.yaml
path: ./ruleset/dev-rules.yaml
interval: 21600
rules:
- RULE-SET,AI-RULES,AI-PROXY
- RULE-SET,DEV-RULES,DEV-PROXY
- MATCH,FINAL
interval: 86400은 24시간마다 갱신한다는 뜻이고, 개발 도구처럼 변경을 자주 확인해야 하는 목록은 더 짧은 주기를 사용할 수 있습니다. 하지만 모든 provider를 5분마다 갱신하도록 설정하면 GitHub 요청이 불필요하게 늘어나고, 기기와 네트워크에 따라 시작 시간이 늦어질 수 있습니다. 서비스의 변경 빈도와 장애 대응 필요성을 기준으로 주기를 정하세요.
behavior는 규칙 파일의 성격과 맞아야 합니다. 일반적인 클래식 규칙 한 줄 목록은 classical로 관리할 수 있고, 도메인만 모아 둔 파일은 코어 버전에 따라 적절한 형식으로 지정해야 합니다. 문법이 맞지 않으면 provider가 다운로드되더라도 규칙 적용 단계에서 실패할 수 있으므로, 처음에는 하나의 작은 provider만 연결한 뒤 로그에서 정상 로드 여부를 확인하는 순서가 좋습니다.
규칙의 순서는 특히 중요합니다. Mihomo는 위에서부터 검사해 처음 일치하는 규칙을 사용합니다. 따라서 RULE-SET,AI-RULES,AI-PROXY가 광범위한 다른 RULE-SET이나 GEOIP 규칙 아래에 있으면, GitHub에서 목록을 잘 받아와도 실제 요청에는 적용되지 않을 수 있습니다. 반대로 예외적으로 직통해야 하는 호스트가 있다면 구체적인 DOMAIN 줄을 해당 provider보다 위에 배치해야 합니다.
충돌 확인과 활성 프로필 검증
규칙을 GitHub에 올렸다는 사실만으로 Clash에 적용된 것은 아닙니다. Clash Verge Rev나 다른 Mihomo 클라이언트에서 현재 활성화된 프로필이 수정한 YAML을 바라보는지 먼저 확인해야 합니다. 편집 중인 파일과 실행 중인 프로필이 다르면 화면에는 새 provider가 보이지만 실제 연결은 이전 규칙을 계속 사용할 수 있습니다.
- 현재 실행 중인 프로필 이름과 파일 경로를 확인합니다.
rule-providers의 URL,behavior,format,path의 들여쓰기를 검사합니다.- 프로필을 저장하고 업데이트 또는 재로드를 실행합니다.
- provider 상태에서 다운로드 성공, 마지막 갱신 시각, 규칙 개수를 확인합니다.
- 테스트 도메인에 접속하면서 코어 로그의 매칭 규칙과 최종 프록시 그룹을 확인합니다.
충돌은 보통 세 가지 형태로 나타납니다. 첫째, 같은 도메인이 여러 provider에 들어 있고 위쪽 provider가 먼저 매칭하는 경우입니다. 둘째, 특정 도메인은 AI-PROXY로 보내야 하지만 뒤쪽의 넓은 규칙이 먼저 적용되는 경우입니다. 셋째, provider 파일에는 DOMAIN-SUFFIX,example.com이 있는데 실제 요청은 별도의 CDN 도메인이나 인증 도메인으로 나가 목록에 없는 경우입니다. 이때는 규칙을 무작정 늘리기보다 브라우저 개발자 도구와 Mihomo 로그에서 실제 FQDN을 수집해야 합니다.
| 증상 | 확인할 항목 | 우선 대응 |
|---|---|---|
| provider 다운로드 실패 | Raw URL, 네트워크, 파일 형식 | 브라우저에서 Raw 주소와 YAML 문법 확인 |
| 다운로드는 성공하지만 미매칭 | rules 순서, provider 이름, behavior | 테스트 규칙을 위로 옮기고 로그 비교 |
| 일부 화면만 로드되지 않음 | 로그인·CDN·API 호스트 누락 | 실제 연결 목록에서 호스트를 추가 |
| 규칙 변경이 늦게 반영됨 | interval, 캐시, 활성 프로필 | 수동 업데이트 후 코어를 재로드 |
테스트할 때는 여러 조건을 한 번에 바꾸지 않는 것이 좋습니다. 먼저 provider 하나만 활성화하고, 같은 노드와 같은 브라우저에서 성공 여부를 확인합니다. 그다음 다른 provider를 추가하면 어떤 목록이 충돌을 만들었는지 추적하기 쉽습니다. TUN 모드를 사용 중이라면 시스템 프록시와 DNS 처리까지 함께 영향을 주므로, 최초 검증은 가능한 한 단순한 규칙 모드와 혼합 포트 환경에서 진행하는 편이 원인을 좁히기 좋습니다.
자동 갱신과 GitHub 운영 전략
자동화의 핵심은 provider가 자주 바뀌는 것이 아니라, 변경이 검토 가능한 형태로 남는 것입니다. 도메인을 추가할 때 커밋 메시지에 서비스명과 이유를 적고, 삭제할 때는 더 이상 사용하지 않는 근거를 남기세요. 예를 들어 add api host for coding assistant처럼 기록하면 나중에 장애가 발생했을 때 특정 변경을 쉽게 되돌릴 수 있습니다. 여러 사람이 저장소를 관리한다면 Pull Request를 거쳐 문법 검사와 중복 검사를 수행하는 방식이 적합합니다.
GitHub Actions를 사용하면 YAML 파싱, 빈 줄, 중복 도메인, 허용되지 않은 사내 호스트를 자동으로 검사할 수 있습니다. 자동화 작업은 provider 파일을 바로 배포하기 전에 실패하도록 설계해야 합니다. 잘못된 YAML이 Raw URL에 올라가면 모든 클라이언트가 다음 갱신 시점에 같은 오류를 받기 때문입니다. 가능하면 main 브랜치에 병합하기 전에 임시 파일을 대상으로 검증하고, 안정적인 커밋에 태그를 붙여 롤백 지점을 만드는 것이 좋습니다.
갱신 주기도 운영 정책의 일부입니다. 규칙이 거의 변하지 않는 개인 목록은 하루 한 번이면 충분하지만, 개발 도구의 배포 CDN처럼 호스트가 자주 추가되는 목록은 6시간 또는 12시간 주기를 고려할 수 있습니다. 다만 provider의 갱신 주기는 GitHub 저장소의 변경을 감지하는 주기이지, 실제 서비스 장애를 자동으로 해결하는 장치가 아닙니다. 새 도메인이 목록에 들어가도 현재 연결이 이미 실패 중이라면 DNS, 노드 품질, TLS, 인증 상태를 별도로 점검해야 합니다.
보안 측면에서는 공개 저장소에 프록시 구독 URL이나 인증 토큰을 넣지 않아야 합니다. URL에 토큰이 포함된 경우 Git 기록에서 삭제해도 이미 복제되었을 가능성이 있으므로 즉시 키를 폐기하고 새로 발급해야 합니다. 또한 공개 규칙셋에 너무 넓은 DOMAIN-SUFFIX를 추가하면 의도하지 않은 트래픽까지 우회될 수 있습니다. 업무용 저장소와 개인용 AI 목록을 분리하고, README에 적용 범위와 예상 출구를 명시하면 오용 가능성을 줄일 수 있습니다.
결국 안정적인 구조는 작은 provider 여러 개, 명확한 이름, 검토 가능한 Git 커밋, 보수적인 갱신 주기의 조합입니다. 한 파일에 모든 도메인을 넣는 방식은 관리 초기에는 빠르지만, 어느 서비스의 변경이 장애를 만들었는지 알아내기 어렵습니다. 반대로 너무 잘게 쪼개면 프로필이 복잡해지므로, 트래픽의 목적과 출구 정책이 실제로 다른 단위만 provider로 분리하는 것이 균형 잡힌 선택입니다.
간단한 프록시 앱은 빠르게 켤 수 있지만, 규칙셋이 커지면 수동 편집과 플랫폼별 설정 차이 때문에 변경 이력을 추적하기 어렵고 자동 갱신 기능도 제한적인 경우가 있습니다. Clash와 Mihomo 계열은 첫 매칭 규칙, provider 단위 갱신, GitHub 기반 버전 관리를 조합해 AI 서비스와 개발 도구를 서로 다른 출구로 보내면서도 변경 과정을 확인할 수 있다는 장점이 있습니다. 설정 파일을 코드처럼 관리하고 싶은 사용자라면, 이 구조가 단순한 일회성 규칙 복사보다 재현성과 복구성이 높습니다.