Clash 설정 파일 구조 완전 분석: port, dns부터 rules까지 각 블록의 역할

설정 파일 전체 구조 개요

Clash 설정 파일은 본질적으로 하나의 YAML 문서로, 위에서 아래로 크게 네 종류의 내용으로 나뉩니다: 전역 실행 파라미터, 노드 정의, 정책 그룹 정의, 분기 규칙. 이 네 종류는 서로 독립적이면서도 서로 참조합니다—노드는 정책 그룹에 참조되고, 정책 그룹은 규칙에 참조되며, 규칙이 트래픽이 최종적으로 어느 경로로 갈지 결정합니다. 이 참조 체인을 이해하는 것이 특정 필드의 값 범위를 외우는 것보다 훨씬 유용한데, 설정 오류나 분기가 작동하지 않을 때 문제 해결 순서가 바로 이 체인을 따라 거슬러 올라가는 방식이기 때문입니다.

Clash Meta(즉 mihomo)는 원조 Clash의 필드를 기반으로 확장하여 TUN 모드, DNS 스니핑, 지리 위치 데이터베이스 경로 등의 설정 항목을 추가했지만, 핵심 4단 구조는 변하지 않았습니다. 이 글은 Meta 커널의 필드 범위를 기준으로 하며, 원조 필드는 그 부분집합이므로 그대로 읽어도 이해에 어려움이 없습니다.

공통 필드: port, mode, log-level, dns

파일 맨 위쪽은 보통 독립적인 키-값 쌍들로, 클라이언트 자체의 동작 방식을 담당하며 구체적인 노드와는 무관합니다.

• port / socks-port: 각각 HTTP 프록시 포트와 SOCKS5 프록시 포트를 열며, 시스템이나 애플리케이션이 필요에 따라 둘 중 하나를 선택해 연결합니다.
• mixed-port: 단일 포트로 HTTP와 SOCKS5 요청을 동시에 받으며, 대부분의 클라이언트는 기본적으로 이 포트 하나만 노출해 설정 항목을 줄입니다.
• allow-lan: 로컬 네트워크 내 다른 기기가 본 기기의 프록시를 통해 접속할 수 있는지 여부로, bind-address와 함께 리스닝 범위를 제어합니다.
• mode: 값은 rule(규칙 기반 분기, 일반적인 사용 방식), global(모두 동일한 노드로, 문제 해결 시 사용), direct(모두 직접 연결, 프록시를 임시로 끌 때 사용)이 있습니다.
• log-level: 로그의 상세 정도를 제어합니다. 문제를 파악할 때는 debug로 임시 변경하는 경우가 많고, 일상적으로는 info나 warning을 권장해 로그 파일이 무한히 커지는 것을 방지합니다.

dns 블록은 별도의 단락으로, 도메인 해석이 어떤 경로를 거칠지 결정합니다. 이는 "분기가 적용된 것처럼 보이지만 실제로는 적용되지 않는" 문제의 원인이 되는 경우가 많습니다—DNS 해석 단계에서 이미 도메인이 잘못된 IP로 해석되면, 이후 규칙을 어떻게 작성해도 되돌릴 수 없습니다. 기본적으로 사용 가능한 dns 블록은 대략 다음과 같습니다:

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://doh.pub/dns-query
  fake-ip-range: 198.18.0.1/16
  use-hosts: true

fake-ip-range는 Meta 커널에서 흔히 사용하는 설정으로, TUN 모드와 함께 사용되어 도메인에 가짜 로컬 IP 대역을 할당하고, 커널이 트래픽 계층에서 실제 해석과 전달을 완료함으로써 시스템 DNS에 직접 의존할 때 발생하는 오염 문제를 피합니다. 이 부분을 자세히 다루면 TUN 모드의 전체 흐름까지 다뤄야 하는데, 이는 이 글의 초점이 아니므로, 여기서는 dns 블록과 rules 블록이 서로 독립적이면서도 서로 영향을 주는 두 개의 파이프라인이라는 점만 알아두면 됩니다.

proxies: 노드 정의

proxies는 목록이며, 목록의 각 항목은 구체적인 프록시 노드를 나타냅니다. 프로토콜마다 필드가 다소 다르지만 모두 같은 구조를 따릅니다: name은 이후 참조에 사용되는 고유 식별자이고, type은 프로토콜을 결정하며(ss, vmess, trojan, hysteria2 등), 나머지 필드는 해당 프로토콜 고유의 연결 파라미터입니다.

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example.com
    port: 443
    cipher: aes-256-gcm
    password: "your-password"
  - name: "SG-01"
    type: vmess
    server: sg01.example.com
    port: 443
    uuid: 0000-uuid-example
    alterId: 0
    cipher: auto

여기서 가장 놓치기 쉬운 점은, name은 단순한 문자열 식별자일 뿐이며 클라이언트는 이것이 실제 노드의 지리적 위치와 일치하는지 검사하지 않습니다. 라벨을 잘못 적어도 오류가 발생하지 않으며, 이후 정책 그룹에서 노드를 선택할 때 혼란을 초래할 뿐입니다. 서비스 제공업체가 제공하는 구독 링크는 본질적으로 완전한 proxies 목록을 생성하는 것이며, 구독 변환 서비스가 하는 일은 서로 다른 형식의 노드 정보를 이 구조로 통일해 변환하는 것입니다.

proxy-groups: 정책 그룹

proxy-groups도 목록이지만, 각 항목이 정의하는 것은 노드가 아니라 "여러 노드나 정책 그룹 중에서 어떻게 하나를 선택하는가"입니다. 정책 그룹의 proxies 필드에는 노드 이름을 적을 수도 있고, 다른 정책 그룹의 이름을 적을 수도 있는데, 이러한 중첩이 다단 분기(예: "자동 선택" 위에 "수동 선택"을 씌우는 것)를 구성하는 기초가 됩니다.

• select: 수동 선택으로, 클라이언트 화면에서 클릭해 전환할 수 있는 목록으로 표시되며, 수동으로 노드를 고르고 싶은 상황에 적합합니다.
• url-test: 지연 시간 기반 자동 선택으로, 클라이언트가 정기적으로 설정된 URL로 속도를 측정해 지연 시간이 가장 낮은 노드로 자동 전환합니다.
• fallback: 장애 대응으로, 목록 순서대로 시도하며 현재 노드를 사용할 수 없으면 자동으로 다음 노드로 전환합니다.
• load-balance: 다중 노드 부하 분산으로, 정책(예: 일관 해시)에 따라 서로 다른 연결을 여러 노드에 분산시킵니다.

proxy-groups:
  - name: "자동 선택"
    type: url-test
    proxies:
      - HK-01
      - SG-01
    url: "https://www.gstatic.com/generate_204"
    interval: 300

  - name: "노드 선택"
    type: select
    proxies:
      - 자동 선택
      - HK-01
      - SG-01
      - DIRECT

마지막 정책 그룹에 등장하는 DIRECT와 REJECT에 주의해야 합니다. 이는 내장된 두 가지 특수 식별자로, proxies에 별도로 정의할 필요가 없습니다: DIRECT는 프록시를 거치지 않고 직접 연결함을, REJECT는 연결을 즉시 거부함을 의미합니다. 이 둘은 어떤 정책 그룹의 후보 목록에도 등장할 수 있고, rules 블록에서 대상 정책으로 직접 등장할 수도 있는데, 이는 많은 사람이 쉽게 놓치는 세부사항입니다.

rules: 분기 규칙

rules 블록은 각 네트워크 요청을 최종적으로 어떤 정책 그룹에 넘길지 결정하며, 전체 설정에서 한 줄씩 순서대로 매칭되어 적용되는 부분입니다—앞에 적힌 규칙이 우선순위가 높고, 어떤 규칙이 매칭되면 이후 규칙은 더 이상 검사하지 않습니다. 규칙의 기본 형식은 "매칭 유형, 매칭 내용, 대상 정책"이며, 자주 쓰이는 매칭 유형은 다음과 같습니다:

• DOMAIN-SUFFIX: 도메인 접미사로 매칭하며, 특정 도메인과 그 모든 하위 도메인을 포괄합니다.
• DOMAIN-KEYWORD: 도메인에 지정한 키워드가 포함되면 매칭되며, 접미사 방식보다 매칭 범위가 넓어 오탐이 발생하기 쉽습니다.
• IP-CIDR / IP-CIDR6: IP 대역으로 매칭하며, 한국(또는 해당 국가) 국내 IP 대역 직접 연결에 자주 사용됩니다.
• GEOIP: IP의 지리적 위치로 매칭하며, 로컬 GeoIP 데이터베이스에 의존합니다.
• MATCH: 기본 규칙으로 맨 마지막에 두며, 앞의 규칙에 매칭되지 않은 모든 트래픽을 처리합니다.

rules:
  - DOMAIN-SUFFIX,cn,DIRECT
  - DOMAIN-KEYWORD,google,노드 선택
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

규칙의 세 번째 항목에는 정책 그룹 이름(또는 DIRECT/REJECT)을 적어야 하며, 노드 이름을 직접 적을 수는 없습니다—이는 초보자가 가장 자주 걸려드는 함정 중 하나입니다. rules에 proxies에만 존재하고 어떤 정책 그룹에도 나타나지 않는 이름을 적으면, 클라이언트가 설정을 불러올 때 바로 오류가 발생합니다. 특정 규칙이 적용되는지 빠르게 확인하려면 log-level을 임시로 debug로 바꾸면, 로그에 각 요청이 어떤 규칙에 매칭되었는지 출력됩니다.

최소 실행 예제: 네 블록을 조합하기

앞서 살펴본 네 블록을 순서대로 이어붙이면 바로 실행 가능한 최소 설정이 됩니다. 모든 상황을 다루지는 못하지만, 각 블록이 어떻게 협력하는지 충분히 설명해줍니다—dns는 도메인을 어떻게 해석할지 결정하고, proxies는 사용 가능한 노드를 제공하며, proxy-groups는 노드를 전환 가능한 정책으로 구성하고, rules는 구체적인 트래픽을 특정 정책 그룹에 배정합니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

dns:
  enable: true
  nameserver:
    - https://doh.pub/dns-query

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example.com
    port: 443
    cipher: aes-256-gcm
    password: "your-password"

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - HK-01
      - DIRECT

rules:
  - DOMAIN-SUFFIX,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

이 설정을 Clash Meta 커널을 지원하는 클라이언트에 넣고 서버 주소와 비밀번호만 바꾸면 바로 실행됩니다. 대부분의 서비스 제공업체가 제공하는 전체 설정이나 구독 링크는 펼쳐보면 본질적으로 이 네 블록의 확장판입니다—정책 그룹 수가 더 많고, 규칙 줄 수가 더 길며, 추가로 규칙 세트와 그룹별 속도 측정 URL이 붙어 있을 수 있지만, 뼈대는 바뀌지 않습니다.

일반적인 문제 해결 순서

설정 파일 오류나 분기 이상이 발생했다면 다음 순서로 확인하면 됩니다:

1. YAML 문법 차원

   들여쓰기가 일관되는지(탭과 공백을 섞어 쓰지 않았는지), 콜론 뒤에 공백을 두었는지, 특수문자가 포함된 비밀번호를 따옴표로 감쌌는지 확인합니다. 대부분의 클라이언트는 로드 실패 시 로그에 구체적인 줄 번호를 표시합니다.

2. 참조가 실제로 존재하는지

   rules에서 지정한 대상 정책 그룹 이름, proxy-groups에서 참조하는 노드 이름이 해당 블록에 실제로 존재하는지, 대소문자를 포함해 철자가 완전히 일치하는지 확인합니다.

3. 규칙 순서가 합리적인지

   범위가 넓은 규칙(예: 특정 DOMAIN-KEYWORD)을 정확한 규칙보다 앞에 두어 뒤에 있는 더 구체적인 규칙이 영원히 매칭되지 않는 일이 없는지 확인합니다.

4. DNS만 따로 테스트

   mode를 임시로 global로 전환해 분기 규칙 문제인지 DNS 해석 단계 문제인지 구분한 다음, 단계별로 범위를 좁혀 나갑니다.