Clash rule-providers 직접 만들기: GitHub YAML 관리 가이드

rule-providers의 역할과 먼저 확인할 것

구독 설정에 포함된 rules만으로는 모든 도메인을 원하는 정책으로 분기하기 어려울 수 있습니다. 특히 개발 도구, AI 서비스, 문서 사이트, 패키지 저장소처럼 자주 주소가 바뀌거나 여러 도메인을 함께 관리해야 하는 대상은 설정 본문에 하나씩 적기보다 별도의 규칙 파일로 분리하는 편이 안정적입니다. mihomo의 rule-providers는 원격 또는 로컬 규칙 파일을 내려받아 메모리에 로드하고, rules에서 하나의 규칙 세트처럼 참조하게 해 줍니다.

이 구조를 사용하면 기본 구독 YAML을 직접 크게 수정하지 않고도 개인 규칙을 추가할 수 있습니다. GitHub 저장소에 YAML 파일을 보관하면 변경 이력이 남고, 여러 기기에서 같은 규칙을 사용할 수 있으며, 문제가 생겼을 때 이전 커밋으로 되돌리기도 쉽습니다. 다만 GitHub 저장소에 구독 URL, API 키, 개인 토큰, 내부 서비스 주소를 함께 올려서는 안 됩니다. 규칙 파일에는 가능하면 공개되어도 문제가 없는 도메인과 IP 대역만 포함하세요.

항목	역할	예시
`rule-providers`	외부 규칙 파일을 정의	`dev-tools`
`behavior`	도메인, IP 또는 클래식 규칙 형식을 지정	`domain`
`rules`	로드한 규칙 세트를 정책 그룹에 연결	`RULE-SET,dev-tools,AI`
`path`	다운로드한 파일을 저장할 로컬 경로	`./rules/dev-tools.yaml`

GitHub에 호환되는 YAML 규칙 파일 작성하기

가장 단순한 도메인 규칙 파일은 YAML 목록으로 작성합니다. behavior: domain을 사용할 때는 일반적으로 각 항목이 도메인 문자열이어야 하며, 앞에 점을 붙여 하위 도메인까지 포함할 수 있습니다. 예를 들어 .openai.com은 기본 도메인과 그 하위 도메인을 함께 대상으로 삼는 방식으로 사용할 수 있습니다. 규칙 파일 내부에 DOMAIN이나 PROCESS-NAME 같은 Clash 규칙 문법을 넣으려면 behavior: classical을 사용해야 합니다.

도메인 형식 예시

payload:
  - ".openai.com"
  - ".chatgpt.com"
  - ".anthropic.com"
  - ".claude.ai"
  - ".huggingface.co"
  - ".npmjs.com"
  - ".pypi.org"
  - ".docker.com"

위 파일을 저장할 때 파일명은 예를 들어 ai-dev.yaml으로 정할 수 있습니다. 최상위 키는 보통 payload를 사용하며, 들여쓰기는 탭이 아닌 공백으로 통일해야 합니다. GitHub 웹 편집기에서 붙여넣은 뒤 파일의 Raw 주소를 열어 실제 응답이 YAML인지 확인하세요. 일반 GitHub 파일 페이지 주소인 https://github.com/사용자/저장소/blob/main/ai-dev.yaml은 HTML 페이지이므로 rule-provider의 URL로 사용하면 안 됩니다.

classical 형식이 필요한 경우

payload:
  - DOMAIN-SUFFIX,code.visualstudio.com
  - DOMAIN-SUFFIX,marketplace.visualstudio.com
  - DOMAIN-SUFFIX,registry.npmjs.org
  - DOMAIN-KEYWORD,jetbrains
  - PROCESS-NAME,code.exe

클래식 형식은 도메인뿐 아니라 키워드, IP 대역, 프로세스 이름 등을 하나의 파일에서 관리할 수 있다는 장점이 있습니다. 대신 모든 플랫폼에서 프로세스 이름이 같지는 않습니다. Windows의 code.exe와 macOS의 Code가 다를 수 있고, TUN 모드에서 프로세스 매칭이 항상 동일하게 동작한다고 보장할 수도 없습니다. 처음에는 도메인 기반 규칙으로 시작하고, 실제 로그에서 필요한 트래픽이 확인된 경우에만 프로세스 규칙을 추가하세요.

mihomo 설정에 provider 등록하기

규칙 파일을 만든 다음 기본 설정의 rule-providers 아래에 제공자를 등록합니다. 아래 예시는 GitHub의 공개 Raw 파일을 12시간마다 확인하고, 다운로드한 파일을 로컬의 rules 디렉터리에 저장하는 구성입니다. interval은 초 단위이므로 12시간은 43200입니다.

rule-providers:
  ai-dev:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/example-user/clash-rules/refs/heads/main/ai-dev.yaml"
    path: ./rules/ai-dev.yaml
    interval: 43200

rules:
  - RULE-SET,ai-dev,AI服务
  - MATCH,代理

ai-dev는 provider의 내부 이름입니다. 이 이름은 rules의 RULE-SET 뒤에 정확히 반복해야 하며, 대소문자와 하이픈을 임의로 바꾸면 안 됩니다. format: yaml은 payload: 구조의 YAML 파일을 의미합니다. 규칙 파일을 한 줄에 하나씩 적은 일반 텍스트라면 format: text를 사용하고, mihomo에서 생성한 MRS 파일이라면 해당 형식과 코어 지원 여부를 별도로 확인해야 합니다.

규칙 업데이트에 사용할 프록시 지정하기

GitHub Raw에 직접 연결할 수 없는 환경에서는 provider 다운로드가 실패할 수 있습니다. 이때 proxy 항목에 실제로 존재하는 정책 그룹 이름을 지정할 수 있습니다. 예를 들어 구독의 정책 그룹에 규칙下载이라는 그룹이 있다면 다음처럼 작성합니다. 정책 그룹 이름은 자신의 설정에 있는 이름과 한 글자까지 일치해야 합니다.

rule-providers:
  ai-dev:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/example-user/clash-rules/refs/heads/main/ai-dev.yaml"
    path: ./rules/ai-dev.yaml
    interval: 43200
    proxy: 규칙下载

여기서 중요한 점은 규칙 자체의 트래픽과 규칙 파일을 내려받는 트래픽이 서로 다를 수 있다는 것입니다. proxy는 provider 파일을 업데이트할 때 사용할 정책이며, provider에 포함된 도메인의 실제 접속 정책은 아래 rules의 AI服务가 결정합니다. 업데이트 프록시를 지정했다고 해서 모든 AI 서비스 트래픽이 같은 그룹으로 연결되는 것은 아닙니다.

필드	권장값	주의사항
`type`	`http`	원격 HTTPS 파일을 주기적으로 가져올 때 사용
`behavior`	`domain`, `classical`	파일 내부 문법과 반드시 일치해야 함
`format`	`yaml`, `text`	서버가 반환하는 실제 파일 형식과 일치시킴
`interval`	`43200` 또는 `86400`	짧게 설정하면 GitHub와 네트워크에 불필요한 요청 증가
`proxy`	필요할 때만 지정	존재하지 않는 그룹을 입력하면 업데이트 실패

RULE-SET 순서와 정책 그룹 연결

Clash 규칙은 위에서 아래로 평가되며, 먼저 일치한 항목에서 처리가 끝납니다. 따라서 직접 만든 RULE-SET을 GEOIP, GEOSITE 또는 마지막의 MATCH보다 위에 배치해야 합니다. MATCH보다 아래에 작성하면 해당 줄까지 도달하지 않으므로 아무 효과가 없습니다.

rules:
  - DOMAIN,internal.example.com,DIRECT
  - RULE-SET,ai-dev,AI服务
  - RULE-SET,package-repos,开发工具
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,代理

예를 들어 사내 도메인을 먼저 DIRECT로 보내고, 그 뒤에 AI와 개발 도구 provider를 배치하면 예외 규칙을 우선 적용할 수 있습니다. 반대로 AI 서비스가 국내 CDN이나 공용 로그인 도메인을 함께 사용한다면 모든 관련 도메인을 하나의 목록에 넣는 방식이 항상 완벽하지는 않습니다. 브라우저 개발자 도구, mihomo 연결 로그, DNS 로그를 함께 확인해 실제로 어떤 호스트명이 매칭되는지 확인하세요.

provider를 여러 개로 나누는 기준

하나의 파일에 모든 도메인을 넣으면 처음에는 편하지만, 나중에 정책을 분리하기 어려워집니다. AI 서비스와 패키지 저장소의 접속 경로가 다르다면 각각 별도의 provider로 만드는 편이 좋습니다. 예를 들어 AI 서비스는 AI服务, npm·PyPI·Docker는 开发工具, 일반 문서 사이트는 代理로 연결할 수 있습니다.

rule-providers:
  ai-services:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/example-user/clash-rules/refs/heads/main/ai-services.yaml"
    path: ./rules/ai-services.yaml
    interval: 86400

  package-tools:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/example-user/clash-rules/refs/heads/main/package-tools.yaml"
    path: ./rules/package-tools.yaml
    interval: 86400

rules:
  - RULE-SET,ai-services,AI服务
  - RULE-SET,package-tools,开发工具
  - MATCH,代理

파일을 나눌 때는 이름만 봐도 대상과 정책을 알 수 있도록 작성하세요. misc-1처럼 의미 없는 이름을 사용하면 몇 달 뒤 관리가 어려워집니다. provider 이름, 파일명, 정책 그룹 이름을 비슷하게 맞추되, 규칙의 우선순위는 반드시 rules 목록에서 명시적으로 관리하는 것이 좋습니다.

GitHub 변경 후 검증하고 안전하게 운영하기

GitHub 파일을 수정했다고 해서 실행 중인 mihomo가 즉시 새 규칙을 사용하는 것은 아닙니다. provider의 자동 업데이트 간격이 남아 있거나, 클라이언트가 캐시된 규칙을 계속 사용하고 있을 수 있습니다. FlClash의 프로필 또는 규칙 관리 화면에서 provider 업데이트를 수동 실행하고, 로그에 다운로드 성공과 규칙 로드 성공이 모두 표시되는지 확인하세요. 단순히 GitHub 웹 페이지에서 파일이 보인다는 사실만으로는 클라이언트가 정상적으로 읽었다고 판단할 수 없습니다.

Raw URL을 브라우저 또는 curl로 열어 HTTP 상태 코드가 200인지 확인합니다.
응답이 HTML 오류 페이지가 아닌지, YAML의 들여쓰기와 최상위 키가 올바른지 검사합니다.
FlClash에서 provider를 수동 업데이트하고 시작 로그의 오류를 확인합니다.
연결 로그에서 테스트 도메인이 실제 provider에 포함된 호스트명인지 확인합니다.
정책 그룹 전환 후 같은 주소를 다시 접속해 예상한 그룹으로 연결되는지 비교합니다.

curl -L --connect-timeout 10 --max-time 30 \
  -o /tmp/ai-dev.yaml \
  -w "HTTP=%{http_code} SIZE=%{size_download}\n" \
  "https://raw.githubusercontent.com/example-user/clash-rules/refs/heads/main/ai-dev.yaml"

업데이트 실패 시 기존에 캐시된 규칙이 계속 사용될 수도 있지만, 새 기기에서는 규칙이 비어 있거나 provider 자체가 로드되지 않을 수 있습니다. 따라서 GitHub 저장소의 기본 브랜치, 파일 경로, 파일명과 URL의 철자를 함께 확인해야 합니다. 저장소를 비공개로 바꾸면 인증 없는 mihomo 요청이 파일을 받을 수 없으므로 개인 저장소를 provider 원본으로 사용할 때는 별도의 인증 지원 여부를 확인해야 합니다. 인증 토큰을 URL에 직접 넣는 방식은 로그와 캐시에 남을 수 있어 권장하지 않습니다.

운영 중에는 도메인을 무작정 추가하기보다 변경 이유를 커밋 메시지에 남기고, 한 번에 한 종류의 수정만 배포하세요. 특정 서비스가 접속되지 않을 때는 해당 서비스의 로그인, API, 정적 콘텐츠, 파일 다운로드 도메인이 모두 같은 정책을 따라야 하는지 확인해야 합니다. 반대로 너무 넓은 도메인 규칙은 일반 웹사이트나 국내 CDN까지 프록시로 보낼 수 있으므로 .example.com을 추가하기 전에 실제 필요한 하위 도메인 범위를 검토하세요.