Clash YAML 설정 파일이란?

Clash(및 Mihomo 코어)의 모든 동작은 하나의 YAML 설정 파일로 정의됩니다. 구독 링크를 가져오면 사실상 이 YAML이 자동으로 다운로드되는 것이며, 「노드가 몇 개 있는지」「어떤 사이트가 프록시를 거치는지」「느린 노드는 어떻게 교체되는지」가 모두 파일 안의 필드로 표현됩니다.

수백 개의 설정 키가 있지만, 실무에서 가장 자주 다루는 핵심은 세 가지입니다. ① proxies — 실제 서버에 연결하는 프록시 노드 목록, ② proxy-groups — 노드를 묶어 선택·자동 테스트·폴백 전략을 적용하는 정책 그룹, ③ rule-providers — 수천 개의 도메인·IP를 외부 파일로 관리하는 규칙 세트입니다. 이 세 모듈이 rules 목록과 맞물려 트래픽 라우팅의 전체 그림을 완성합니다.

전제 조건: Clash 클라이언트 설치와 구독 가져오기가 완료되어 있어야 합니다. 아직이라면 먼저 Clash Verge Rev 설치 및 설정 튜토리얼을 참고하세요. 규칙 매칭 원리는 규칙 기반 라우팅 심층 분석에서 별도로 다룹니다.

전역 설정: 파일의 뼈대 이해하기

본격적으로 세 모듈을 살펴보기 전, YAML 상단의 전역 필드를 짚고 넘어갑니다. 이 값들은 모든 노드와 규칙이 공유하는 「실행 환경」을 정의합니다. 

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5
    - 8.8.8.8
  • mixed-port: HTTP/SOCKS 혼합 프록시 포트. 클라이언트가 「시스템 프록시」를 켤 때 이 포트를 사용합니다.
  • mode: rule(규칙 분기, 일상 권장), global(전역 프록시), direct(전역 직접 연결) 중 하나.
  • dns: 도메인 해석 방식. fake-ip 모드는 규칙 매칭 속도를 높이지만 일부 앱과 충돌할 수 있어, 문제 발생 시 redir-host로 전환합니다.
  • external-controller: REST API 주소. 대시보드·스크립트 연동 시 필요합니다.

YAML은 들여쓰기(스페이스 2칸)로 계층을 표현합니다. 탭 문자는 사용하지 마세요. 문법 오류가 있으면 설정 전체가 로드되지 않으므로, 수정 후에는 클라이언트의 「설정 미리보기」나 외부 YAML 린터로 검증하는 습관이 중요합니다.

프록시 노드 (proxies): 아웃바운드 완전 해설

proxies 배열의 각 항목이 하나의 프록시 노드입니다. Clash는 이 노드에 TCP/UDP 연결을 맺어 사용자 트래픽을 중계합니다. Mihomo는 Shadowsocks, VMess, VLESS, Trojan, Hysteria2, TUIC, WireGuard 등 다수의 프로토콜을 지원합니다.

Shadowsocks 노드 예제

proxies:
  - name: "KR-Seoul-01"
    type: ss
    server: example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

VMess 노드 예제

  - name: "US-LA-Vmess"
    type: vmess
    server: 1.2.3.4
    port: 443
    uuid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /path
      headers:
        Host: example.com

Trojan 노드 예제

  - name: "JP-Tokyo-Trojan"
    type: trojan
    server: trojan.example.com
    port: 443
    password: "trojan-password"
    sni: trojan.example.com
    skip-cert-verify: false

각 노드의 name은 클라이언트 UI에 표시되는 이름이자, proxy-groups에서 참조하는 식별자입니다. 이름은 파일 내에서 유일해야 하며, 공백·특수문자가 많으면 규칙 작성 시 불편하므로 영문·숫자·하이픈 조합을 권장합니다.

공통 필드 설명
name 노드 표시 이름. proxy-groups·rules에서 참조
type 프로토콜 종류: ss, vmess, trojan, vless, hysteria2, tuic 등
server / port 서버 주소와 포트
udp UDP 릴레이 지원 여부. 게임·영상 통화 시 true 권장
보안 참고: YAML 파일에는 서버 비밀번호·UUID 등 민감 정보가 포함됩니다. GitHub 등 공개 저장소에 업로드하지 마세요. 공유 시 반드시 자격 증명을 마스킹합니다.

proxy-providers: 노드 목록 외부화

노드가 수십~수백 개일 때 proxies 배열에 직접 나열하면 파일이 비대해집니다. Mihomo의 proxy-providers는 구독 URL에서 노드를 주기적으로 가져와 use 필드로 정책 그룹에 주입할 수 있게 합니다. 대부분의 프로바이더 구독이 이 방식을 사용하며, 사용자가 직접 작성하는 경우는 드뭅니다. 

proxy-providers:
  airport:
    type: http
    url: "https://example.com/sub?flag=clash"
    interval: 3600
    path: ./providers/airport.yaml
    health-check:
      enable: true
      url: http://www.gstatic.com/generate_204
      interval: 300

정책 그룹 (proxy-groups): 노드 운영 전략

proxy-groups는 노드를 어떻게 선택·교체할지를 정의합니다. rules 목록은 보통 개별 노드가 아닌 정책 그룹 이름을 참조합니다. 「자동 선택」「Netflix」「수동 선택」 등 클라이언트 UI에 보이는 항목 대부분이 여기서 옵니다.

select — 수동 선택

사용자가 UI에서 직접 노드를 고릅니다. 「지역별 노드」「스트리밍 전용」 등 카테고리 분류에 적합합니다. 

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - "KR-Seoul-01"
      - "US-LA-Vmess"
      - "JP-Tokyo-Trojan"
      - DIRECT

url-test — 지연 시간 기반 자동 선택

주기적으로 각 노드에 테스트 URL을 요청해 가장 빠른 노드를 자동 선택합니다. 「자동 선택」「Auto」 그룹의 정체입니다. 

  - name: "자동 선택"
    type: url-test
    proxies:
      - "KR-Seoul-01"
      - "US-LA-Vmess"
      - "JP-Tokyo-Trojan"
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

tolerance는 현재 노드와 새 최적 노드의 지연 차이가 이 값(ms) 미만이면 교체하지 않아 빈번한 전환을 방지합니다. 경쟁 게임·화상 회의처럼 안정적인 노드가 필요하면 select로 고정하는 편이 낫습니다.

fallback — 순차 폴백

목록 순서대로 테스트해 첫 번째로 응답하는 노드를 사용합니다. url-test와 달리 「항상 1순위 우선, 실패 시 2순위」 패턴에 적합합니다. 

  - name: "폴백 그룹"
    type: fallback
    proxies:
      - "JP-Tokyo-Trojan"
      - "US-LA-Vmess"
      - DIRECT
    url: http://www.gstatic.com/generate_204
    interval: 300

load-balance — 부하 분산

여러 노드에 트래픽을 분산합니다. strategy를 consistent-hashing으로 두면 동일 대상에 같은 노드가 매핑되어 세션 안정성이 높아집니다. 다운로드·크롤링 등 대역폭 분산에 활용됩니다.

relay — 다중 홉 체인

트래픽을 A 노드 → B 노드 순으로 연속 중계합니다. 특수한 우회·내부망 구조에 쓰이지만 지연 증가가 크므로 일반 사용자에게는 권장하지 않습니다.

proxy-providers와 결합

  - name: "공항 자동"
    type: url-test
    use:
      - airport
    url: http://www.gstatic.com/generate_204
    interval: 300

use에 proxy-providers 이름을 지정하면 해당 구독의 전체 노드가 그룹에 자동 편입됩니다. 구독 갱신 시 노드가 추가·삭제되어도 그룹이 따라 갱신되므로, 프로바이더 구독을 쓸 때 가장 흔한 패턴입니다.

규칙 세트 (rule-providers): 대규모 규칙 관리

DOMAIN-SUFFIX,google.com,PROXY처럼 규칙을 한 줄씩 나열하면 수천 개의 도메인을 수동 관리하기 어렵습니다. rule-providers는 GitHub 등에 호스팅된 규칙 파일을 가져와 RULE-SET 규칙 유형으로 참조합니다. 커뮤니티에서 유지보수하는 gfwlist, cn, reject 등의 목록을 그대로 활용할 수 있습니다. 

rule-providers:
  reject:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/reject.txt"
    path: ./ruleset/reject.yaml
    interval: 86400

  gfw:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/gfw.txt"
    path: ./ruleset/gfw.yaml
    interval: 86400

  cn:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/cn.txt"
    path: ./ruleset/cn.yaml
    interval: 86400
필드 설명
type http(원격 URL), file(로컬 파일)
behavior domain, ipcidr, classical — 규칙 세트 내용 형식
path 로컬 캐시 경로. 최초 로드 후 오프라인에서도 사용 가능
interval 갱신 주기(초). 86400 = 24시간

rules에서 아래처럼 참조합니다. 이름은 rule-providers에 선언한 키와 일치해야 합니다. 

rules:
  - RULE-SET,reject,REJECT
  - RULE-SET,gfw,PROXY
  - RULE-SET,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

behavior: classical이면 세트 안에 DOMAIN-SUFFIX,xxx,DIRECT 형태의 완전한 규칙 줄이 들어갑니다. domain·ipcidr는 순수 목록만 담고 Clash가 내부적으로 변환합니다. 프로바이더·커뮤니티 템플릿이 어떤 형식을 쓰는지 확인한 뒤 맞춰야 합니다.

규칙 세트 URL에 접속할 수 없으면 해당 RULE-SET이 비어 있어 분기가 실패합니다. 미러 URL로 바꾸거나 type: file로 로컬 복사본을 사용하세요. 자세한 라우팅 순서와 GEOIP 활용은 규칙 기반 라우팅 가이드를 참고하세요.

세 모듈이 함께 동작하는 방식

트래픽이 Clash를 통과할 때의 흐름을 정리하면 다음과 같습니다.

  1. 애플리케이션이 도메인(예: youtube.com)으로 연결을 시도합니다.
  2. Clash가 rules 목록을 위에서부터 순차 매칭합니다.
  3. RULE-SET,gfw,PROXY에 매칭되면 동작 대상은 정책 그룹 PROXY입니다.
  4. PROXY 그룹이 url-test라면 등록된 proxies 노드 중 지연이 가장 낮은 노드를 선택합니다.
  5. 선택된 노드(예: US-LA-Vmess)로 실제 암호화 연결이 수립되고 트래픽이 중계됩니다.

즉 rule-providers → rules → proxy-groups → proxies 순으로 참조가 이어집니다. 어느 한 고리의 이름이 불일치하면 「규칙은 맞는데 노드를 찾을 수 없음」 오류가 발생합니다. 설정을 수정할 때는 항상 이 참조 체인을 따라가며 확인하세요.

실전 통합 예제

아래는 세 모듈을 모두 포함한 축소 예제입니다. 실제 프로바이더 구독은 노드·규칙이 훨씬 많지만, 구조는 동일합니다. 

mixed-port: 7890
mode: rule

proxies:
  - { name: "Node-A", type: ss, server: a.example.com, port: 443, cipher: aes-256-gcm, password: "pass" }
  - { name: "Node-B", type: trojan, server: b.example.com, port: 443, password: "pass", sni: b.example.com }

proxy-groups:
  - name: PROXY
    type: url-test
    proxies: [Node-A, Node-B]
    url: http://www.gstatic.com/generate_204
    interval: 300
  - name: "수동 선택"
    type: select
    proxies: [PROXY, Node-A, Node-B, DIRECT]

rule-providers:
  gfw:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/gfw.txt"
    path: ./ruleset/gfw.yaml
    interval: 86400

rules:
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - RULE-SET,gfw,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

구독 위에 덮어쓰기로 커스터마이징

프로바이더가 제공하는 원격 YAML은 갱신 시 덮어쓰이므로 직접 편집하면 안 됩니다. Clash Verge Rev의 Merge/Override 기능을 사용하면 로컬 YAML 조각만 추가할 수 있습니다. 예를 들어 개인 NAS 도메인을 직접 연결하도록 규칙을 덧붙이려면: 

rules:
  - DOMAIN-SUFFIX,nas.home,DIRECT

덮어쓰기 파일에는 보통 변경하려는 필드만 작성합니다. rules는 기존 목록 앞에 병합되므로, 우선순위가 높은 규칙을 넣을 때 유용합니다. 문법 오류 시 전체 설정이 로드되지 않으니, 수정 후 반드시 프록시 동작을 확인하세요.

자주 하는 실수와 해결법

  • 이름 불일치: proxy-groups의 proxies에 적은 이름이 proxies 배열의 name과 정확히 같아야 합니다. 대소문자·따옴표까지 일치해야 합니다.
  • PROXY 미정의: rules에서 PROXY를 참조하지만 해당 이름의 proxy-groups가 없으면 연결 실패합니다. 구독마다 그룹 이름이 다를 수 있으니 실제 파일을 확인하세요.
  • RULE-SET 순서: cn 규칙 세트가 gfw보다 위에 있으면 해외 CDN 도메인이 국내 직접 연결로 빠질 수 있습니다. 커뮤니티 권장 순서를 따르세요.
  • YAML 들여쓰기: 스페이스와 탭을 혼용하거나 들여쓰기 깊이가 어긋나면 파싱 오류가 납니다.
  • interval 0: rule-providers·proxy-providers의 interval이 너무 짧으면 불필요한 네트워크 요청이 발생합니다. 3600~86400초가 일반적입니다.

자주 묻는 질문

proxies와 proxy-groups의 차이는 무엇인가요?

proxies는 실제 서버 연결 단위(아웃바운드)이고, proxy-groups는 여러 노드를 묶어 운영 전략을 적용하는 컨테이너입니다. 규칙에서는 대부분 그룹 이름을 참조하며, 그룹이 내부적으로 어떤 노드를 쓸지 결정합니다.

rule-providers 없이 rules만 써도 되나요?

가능합니다. 소수의 도메인만 다룰 때는 DOMAIN-SUFFIX 규칙만으로 충분합니다. 다만 도메인이 수백 개 이상이면 rule-providers + RULE-SET 조합이 유지보수·정확도 면에서 훨씬 유리합니다.

구독 YAML을 메모장으로 직접 수정해도 되나요?

프로바이더 구독은 동기화 시 변경 사항이 사라집니다. 영구적인 수정이 필요하면 Override 덮어쓰기를 사용하거나, 노드만 따로 뽑아 자체 YAML을 구성하세요.

Mihomo 전용 문법이 있나요?

rule-providers, proxy-providers, Hysteria2·TUIC 노드 타입, geodata-mode 등은 Mihomo(Clash Meta) 확장입니다. 구 Clash Premium 코어와 100% 호환되지 않으므로, 사용 중인 클라이언트가 Mihomo 기반인지 확인하세요. Clash Verge Rev는 Mihomo를 사용합니다.

많은 상용 VPN 앱은 내부 라우팅 로직을 사용자에게 공개하지 않아, 「왜 이 사이트만 느린지」를 알기 어렵습니다. 반면 Clash + Mihomo는 YAML 한 파일에 노드·정책·규칙이 모두 명시되어 있어, 구독을 바꾸거나 덮어쓰기로 미세 조정할 때도 투명하게 제어할 수 있습니다. proxies·proxy-groups·rule-providers 세 모듈만 이해하면 대부분의 커스터마이징 시나리오를 스스로 해결할 수 있으며, 커뮤니티 규칙 세트를 그대로 가져다 쓸 수 있다는 점도 큰 장점입니다. YAML 문서를 매번 찾아 헤매고 싶지 않다면, 본 사이트의 Clash 클라이언트는 구독 가져오기와 검증된 라우팅 템플릿이 통합되어 있어 설정 부담을 크게 줄여 줍니다.

지금 바로 Clash를 무료로 다운로드하고 YAML 기반 스마트 프록시를 시작해 보세요 →