Clash 설정 파일 구조 해부: port부터 rules까지 YAML 한 편을 단계별로 이해하기

먼저 YAML의 계층과 파싱 규칙부터 확인하기

Clash 설정 파일은 보통 YAML을 사용합니다. 서로 독립된 스위치의 나열이 아니라 계층 구조를 가진 설정 트리입니다. 최상위 필드는 코어 동작을 제어하고, 들여쓴 필드는 상위 객체에 속하며, 하이픈으로 시작하는 항목은 목록 요소입니다. 설정을 읽을 때는 먼저 들여쓰기를 확인한 뒤 필드의 의미를 판단해야 합니다. 필드명만 보고 계층을 확인하지 않으면 유효한 매개변수를 잘못된 위치에 넣기 쉽습니다.

들여쓰기, 콜론, 목록

들여쓰기는 공백으로 통일하세요. 일반적으로 한 단계마다 공백 2개를 사용하며 Tab은 섞지 않는 것이 좋습니다.
키 이름 뒤의 콜론 다음에는 공백을 넣어야 합니다. 예: mode: rule.
dns:, profile: 같은 필드 아래에 하위 항목이 있다면 하위 항목도 계속 들여써야 합니다.
proxies:, proxy-groups:, rules:에는 보통 목록이 들어가며, 각 항목은 -로 시작합니다.
콜론, 샵, 중괄호 같은 특수 문자가 포함된 이름은 작은따옴표나 큰따옴표로 감싸는 것이 좋습니다.

mode: rule
log-level: info

profile:
  store-selected: true
  store-fake-ip: true

proxy-groups:
  - name: '노드 선택'
    type: select
    proxies:
      - '자동 선택'
      - DIRECT

위 예시에서 store-selected는 profile에 속하고, name, type, proxies는 하나의 정책 그룹 객체를 구성합니다. type과 name의 들여쓰기 단계가 어긋나면 YAML이 파싱되더라도 전혀 다른 데이터 구조가 만들어질 수 있습니다.

공통 필드: 포트, LAN, 실행 모드

설정 파일 앞부분에는 보통 수신 포트, 실행 모드, 로그 수준, 제어 포트를 배치합니다. 이 필드들은 애플리케이션이 시스템 트래픽을 받는 방식과 그래픽 클라이언트가 Clash Meta（mihomo）코어와 통신하는 방식을 결정합니다.

port: 7890
socks-port: 7891
mixed-port: 7893
redir-port: 7892
tproxy-port: 7895

allow-lan: false
bind-address: '*'
mode: rule
log-level: info
ipv6: false

external-controller: 127.0.0.1:9090
secret: 'change-this-controller-secret'

각 포트는 어떤 트래픽을 받는가

port: HTTP 프록시 수신 포트입니다. 예시에서는 보통 127.0.0.1:7890으로 지정합니다.
socks-port: SOCKS5 프록시 포트입니다. SOCKS5를 지원하는 명령줄 도구나 애플리케이션은 127.0.0.1:7891에 연결할 수 있습니다.
mixed-port: 하나의 포트에서 HTTP와 SOCKS5 요청을 함께 받습니다. 클라이언트가 로컬 프록시 진입점 하나만 노출하면 될 때 보통 이 항목만 사용하면 됩니다.
redir-port: Linux 리디렉션 환경에서 사용하며, 일반적으로 iptables 또는 호환되는 트래픽 전달 규칙과 함께 구성합니다.
tproxy-port: Linux TPROXY 투명 프록시에 사용하며, 대상 주소를 유지해야 하는 전달 트래픽을 처리할 수 있습니다.

이 포트를 모두 활성화할 필요는 없습니다. 데스크톱 클라이언트에서 시스템 프록시를 사용할 때는 mixed-port: 7890만 활성화하거나 HTTP와 SOCKS 포트를 각각 활성화하는 구성이 흔합니다. 로그에 address already in use가 표시되면 다른 프록시 프로그램, 기존 코어 프로세스 또는 개발 서버가 같은 포트를 사용 중인지 확인한 뒤 설정을 바꾸거나 충돌하는 프로세스를 종료하세요.

mode, allow-lan, 제어 인터페이스

mode: rule은 rules를 위에서 아래로 매칭하는 방식으로, 일상적인 트래픽 분기 설정에서 가장 흔히 사용됩니다.
mode: global은 연결을 전역 정책 그룹으로 전달하며 일반 규칙에 따라 개별 분기하지 않습니다.
mode: direct은 연결이 직접 접속하도록 합니다. 문제가 프록시 경로에서 발생했는지 임시로 확인할 때 유용합니다.
allow-lan: true는 LAN 장치가 수신 포트에 연결하도록 허용합니다. 활성화할 때는 시스템 방화벽, 수신 주소, 신뢰할 수 있는 네트워크 범위도 함께 확인해야 합니다.
external-controller는 REST API 제어 인터페이스입니다. 로컬 클라이언트만 사용할 경우 127.0.0.1에 바인딩하세요. 원격 패널이 필요하다면 유효한 secret을 설정하고 네트워크 접근 범위를 제한해야 합니다.

bind-address: '*'는 사용 가능한 주소에서 수신한다는 뜻이지만, 실제로 LAN에 공개되는지는 allow-lan과 방화벽 설정에 따라 달라집니다. ‘수신 주소’, ‘LAN 허용’, ‘제어 인터페이스’를 같은 설정으로 보면 안 됩니다. 각각 프록시 진입점, LAN 접근 권한, 코어 관리 인터페이스를 관리합니다.

DNS 블록: 해석 경로와 Fake-IP

DNS 설정은 도메인을 해석하는 방식을 결정하며, 연결 단계에서 도메인 규칙을 계속 매칭할 수 있는지에도 영향을 줍니다. Clash Meta（mihomo）에서 흔히 사용하는 향상 모드에는 fake-ip과 redir-host가 있습니다. 전자는 예약 주소 대역에서 매핑 주소를 반환하고 코어에 도메인과 연결의 대응 관계를 보존합니다. 후자는 실제 DNS 결과를 반환하는 흐름에 더 가깝습니다.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - 'time.*.com'
    - 'time.*.gov'
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - 'https://dns.alidns.com/dns-query'
    - 'https://doh.pub/dns-query'
  fallback:
    - 'https://1.1.1.1/dns-query'
    - 'https://dns.google/dns-query'
  fallback-filter:
    geoip: true
    geoip-code: CN

세 가지 nameserver의 역할

default-nameserver에는 보통 직접 접속할 수 있는 IP 주소를 입력합니다. DoH 또는 DoT 서버 자체의 도메인을 해석해 시작 단계에서 순환 의존이 발생하지 않도록 하는 용도입니다.
nameserver는 기본 해석기입니다. 일반 UDP DNS를 사용하거나 DoH, DoT 같은 암호화된 DNS 주소를 입력할 수 있습니다.
fallback은 보조 해석기입니다. 그 결과를 사용할지는 fallback-filter 등의 조건에 영향을 받습니다.

listen: 127.0.0.1:1053은 로컬 장치만 DNS 수신 포트에 접근하도록 합니다. 클라이언트가 시스템 DNS를 자동으로 인계받는다면 운영체제의 DNS를 이 포트로 수동 변경할 필요가 없는 경우가 많습니다. TUN 모드에서는 코어가 DNS 하이재킹을 통해 53번 포트 요청을 받을 수도 있으며, 구체적인 동작은 클라이언트가 생성한 TUN 설정에 따라 달라집니다.

fake-ip-filter에는 무엇을 넣어야 하나

LAN 도메인, 장치 검색 도메인, 일부 시간 동기화 도메인, 실제 주소 반환 결과에 의존하는 애플리케이션 도메인은 fake-ip-filter에 추가할 수 있습니다. 넓은 범위의 와일드카드를 필터 목록에 무심코 넣지 마세요. 많은 도메인이 Fake-IP 매핑을 우회하게 되어 도메인 규칙의 매칭 방식과 첫 연결 지연 시간이 달라질 수 있습니다.

proxies: 개별 노드 정의 방법

proxies는 정적 노드 목록입니다. 각 노드에는 최소한 이름, 프로토콜 유형, 서버 주소, 포트가 필요하며, 이후 프로토콜에 맞춰 인증 및 전송 매개변수를 추가합니다. 노드 필드는 실제 서버 설정과 일치해야 합니다. 프로토콜 이름이 같더라도 포트, 암호화 방식, TLS 호스트 이름, WebSocket 경로를 서로 바꿔 사용할 수 있다는 뜻은 아닙니다.

proxies:
  - name: '예시-Trojan'
    type: trojan
    server: edge.example.com
    port: 443
    password: 'example-password'
    udp: true
    sni: edge.example.com
    skip-cert-verify: false

  - name: '예시-VMess'
    type: vmess
    server: vm.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000001
    alterId: 0
    cipher: auto
    udp: true
    tls: true
    servername: vm.example.com
    network: ws
    ws-opts:
      path: /connect
      headers:
        Host: vm.example.com

노드 이름은 이후 참조에 사용하는 키입니다

name은 화면에 표시되는 문자열에 그치지 않습니다. 정책 그룹은 노드를 완전히 동일한 문자열로 참조합니다. 노드 이름이 예시-Trojan이라면 정책 그룹에 예시 Trojan이라고 쓰는 순간 존재하지 않는 참조가 됩니다. 노드 이름을 바꿀 때는 모든 proxy-groups, 규칙 대상, 체인 프록시 설정도 함께 확인하세요.

TLS와 전송 계층 필드는 서로 맞아야 합니다

server는 연결을 생성할 때 사용하는 서버 주소입니다.
sni 또는 servername은 TLS 핸드셰이크의 서버 이름으로 사용되며, 노드 제공자가 안내한 값에 맞춰 입력해야 합니다.
skip-cert-verify: false는 서버 인증서를 정상적으로 검증한다는 뜻입니다.
network: ws는 WebSocket 전송을 사용한다는 뜻이며, 관련 매개변수는 ws-opts에 있습니다.
udp: true는 해당 노드가 UDP를 처리하도록 허용합니다. 실제 통신 가능 여부는 프로토콜, 서버, 네트워크 환경에 따라 달라집니다.

구독에서 가져올 때 노드는 proxies에 직접 작성되지 않고 클라이언트가 변환해 생성하거나 proxy-providers를 통해 로드되는 경우가 많습니다. 두 방식을 함께 사용할 수도 있지만, 같은 이름의 노드가 있으면 정책 그룹 참조와 문제 해결이 더 어려워집니다.

proxy-providers와 proxy-groups: 노드에서 정책으로

proxy-providers는 로컬 파일이나 원격 주소에서 여러 노드를 불러오고, proxy-groups는 노드를 선택, 속도 측정, 장애 전환이 가능한 정책으로 구성합니다. 규칙은 보통 특정 노드가 아니라 정책 그룹을 가리킵니다.

proxy-providers:
  provider-main:
    type: http
    url: 'https://subscription.example.com/clash'
    path: ./providers/provider-main.yaml
    interval: 3600
    health-check:
      enable: true
      url: 'https://www.gstatic.com/generate_204'
      interval: 600

proxy-groups:
  - name: '노드 선택'
    type: select
    proxies:
      - '자동 선택'
      - DIRECT
    use:
      - provider-main

  - name: '자동 선택'
    type: url-test
    use:
      - provider-main
    url: 'https://www.gstatic.com/generate_204'
    interval: 300
    tolerance: 80

  - name: '장애 전환'
    type: fallback
    use:
      - provider-main
    url: 'https://www.gstatic.com/generate_204'
    interval: 300

자주 사용하는 정책 그룹 유형

select: 노드나 다른 정책 그룹을 수동으로 선택합니다. 규칙이 최종적으로 참조할 그룹에 적합합니다.
url-test: 주기적으로 테스트 주소에 요청하고 후보 노드 중 지연 시간이 낮은 노드를 선택합니다. 예시는 300초마다 확인하며, tolerance: 80은 지연 시간이 비슷할 때 잦은 전환을 줄이는 데 사용됩니다.
fallback: 사용 가능 여부에 따라 후보를 선택하며, 현재 연결 경로가 작동하지 않으면 다음으로 사용 가능한 노드로 전환합니다.
load-balance: 정책에 따라 여러 노드에 연결을 분산합니다. 하나의 다운로드 작업에 대역폭을 직접 합산하는 기능은 아닙니다.

proxies는 노드나 정책 그룹 이름을 명시적으로 나열할 때 사용하고, use는 provider를 참조할 때 사용합니다. 정책 그룹은 계속 중첩할 수 있습니다. 예를 들어 ‘노드 선택’에 ‘자동 선택’을 포함하고, ‘자동 선택’이 provider에서 노드를 가져오게 구성할 수 있습니다. 설정을 점검할 때는 참조 관계를 따라 각 이름이 존재하는지 단계별로 확인해 자기 자신을 참조하는 순환을 피하세요.

rules: 순서대로 실행되는 트래픽 분기표

rules는 설정 마지막 부분에서 가장 중요한 목록 중 하나입니다. Clash는 위에서 아래로 매칭하며, 보통 한 규칙에 매칭되면 이후 항목을 더 확인하지 않습니다. 따라서 더 구체적인 도메인, 프로세스, 네트워크 대역 규칙을 앞에 두고, 범위가 넓은 GeoIP, GeoSite, 최종 대체 규칙은 뒤에 배치해야 합니다.

rules:
  - DOMAIN-SUFFIX,example.org,노드 선택
  - DOMAIN,api.example.net,자동 선택
  - DOMAIN-KEYWORD,stream,노드 선택
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOSITE,CN,DIRECT
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,노드 선택

규칙은 매처, 값, 대상으로 구성됩니다

DOMAIN-SUFFIX,example.org,노드 선택을 예로 들면 첫 번째 항목은 규칙 유형, 두 번째 항목은 매칭할 값, 세 번째 항목은 매칭 후 사용할 정책입니다. 정책 이름은 proxy-groups의 이름과 완전히 일치해야 하며, DIRECT 또는 REJECT 같은 내장 대상도 사용할 수 있습니다.

DOMAIN은 완전한 도메인 하나를 정확히 매칭합니다.
DOMAIN-SUFFIX는 지정한 도메인과 하위 도메인을 매칭하므로 사이트 범위별 트래픽 분기에 적합합니다.
DOMAIN-KEYWORD는 도메인에 포함된 키워드로 매칭하므로 범위가 넓습니다. 너무 짧은 키워드는 피하세요.
IP-CIDR과 IP-CIDR6은 각각 IPv4와 IPv6 주소 대역을 매칭합니다.
GEOIP는 지리적 IP 데이터베이스를 바탕으로 대상 주소가 속한 지역을 판단합니다.
GEOSITE는 도메인 분류 데이터베이스를 사용합니다. 이용 가능한 카테고리는 현재 mihomo 버전과 데이터 파일에 따라 달라집니다.
MATCH는 앞선 규칙에 매칭되지 않은 트래픽을 처리하므로 규칙 목록 마지막에 배치해야 합니다.

no-resolve는 이 IP 규칙이 매칭을 위해 추가로 도메인 해석을 실행하지 않도록 합니다. LAN 대역이나 GEOIP 규칙에 자주 사용하지만, 추가 여부는 앞의 DNS 모드와 규칙 요구 사항을 함께 고려해야 합니다. 도메인 규칙에 추가하는 것은 의미가 없습니다.

규칙 순서가 잘못되었을 때 나타나는 전형적인 증상

MATCH를 중간에 배치하면 뒤의 규칙은 절대 실행될 기회를 얻지 못합니다.
범위가 넓은 DOMAIN-KEYWORD를 먼저 작성하면 뒤에 있는 정확한 도메인 규칙이 매칭되지 않습니다.
LAN 대역을 미리 직접 연결하도록 설정하지 않으면 라우터, NAS, 개발 서버에 접속할 때 프록시로 전송됩니다.
규칙 대상 이름은 변경했지만 규칙표가 여전히 이전 정책 그룹을 참조하면 로드 시 프록시 또는 정책을 찾을 수 없다는 메시지가 표시됩니다.
GEOSITE, GEOIP를 사용하면서 해당 데이터베이스를 준비하지 않으면 규칙 로드 또는 매칭에 문제가 발생합니다.

TUN과 profile: 자주 쓰는 후반부 설정

TUN 모드는 가상 네트워크 인터페이스를 통해 더 많은 시스템 트래픽을 인계받으며, 시스템 프록시 설정을 직접 읽을 수 없는 프로그램에 적합합니다. mixed-port와 충돌하지 않습니다. 전자는 네트워크 계층에서 트래픽을 인계받고, 후자는 HTTP 또는 SOCKS5를 명시적으로 지원하는 애플리케이션에서 계속 사용할 수 있습니다.

tun:
  enable: true
  stack: mixed
  dns-hijack:
    - any:53
  auto-route: true
  auto-detect-interface: true
  strict-route: false

profile:
  store-selected: true
  store-fake-ip: true

auto-route는 코어가 라우팅을 자동으로 구성하도록 하고, auto-detect-interface는 현재 출구 네트워크 카드를 식별합니다. 운영체제마다 TUN 드라이버, 관리자 권한, 라우팅 설정 요구 사항이 다릅니다. 그래픽 클라이언트는 보통 「설정」→「네트워크」 또는 「설정」→「TUN 모드」에서 이러한 매개변수를 생성하고 관리합니다. 클라이언트가 이미 TUN 설정을 관리한다면 여러 오버라이드 계층에서 같은 필드를 중복 선언하지 마세요.

store-selected: true는 정책 그룹 선택을 저장해 재시작 후에도 마지막으로 선택한 항목을 사용하도록 합니다. store-fake-ip: true는 Fake-IP 매핑을 저장해 재시작 후 매핑 변경으로 발생하는 연결 끊김을 줄이는 데 도움이 됩니다. 두 필드는 profile에 속하며 dns의 하위 항목이 아닙니다.

로드부터 매칭까지 전체 점검 순서

설정이 YAML 문법 검사를 통과했다고 해서 노드 연결이 보장되는 것은 아닙니다. 노드가 연결된다고 해서 규칙과 DNS가 예상대로 작동한다는 뜻도 아닙니다. 문제를 찾을 때는 여러 구간을 동시에 수정하기보다 정해진 순서대로 진행해야 원인을 더 쉽게 좁힐 수 있습니다.

YAML 파싱을 확인합니다.먼저 클라이언트 설정 화면이나 코어 로그에서 들여쓰기, 중복 키, 알 수 없는 필드, 유형 오류가 없는지 확인하세요.
로컬 수신을 확인합니다.7890, 7891, 7893, 9090, 1053 등의 실제 활성 포트가 다른 프로세스에 의해 사용되고 있지 않은지 확인하세요.
노드 핸드셰이크를 확인합니다.프록시 화면에서 노드 하나를 선택해 지연 시간을 테스트한 뒤 TLS, 인증, 시간 초과, 네트워크 연결 불가 관련 로그를 확인하세요.
정책 그룹 참조를 확인합니다.규칙 대상, 정책 그룹 구성원, provider 이름이 완전히 일치하는지 확인하세요.
DNS를 확인합니다.도메인 조회가 시간 초과되는지, DoH 서버 도메인이 default-nameserver를 통해 초기 해석되는지 확인하세요.
규칙 매칭을 확인합니다.연결 또는 로그 화면에서 대상 도메인이 어떤 규칙에 매칭되었는지, 최종적으로 어떤 정책 그룹과 노드가 선택되었는지 확인하세요.
마지막으로 TUN을 활성화합니다.먼저 일반 시스템 프록시가 정상적으로 작동하는지 확인한 다음 TUN을 켜야 노드 문제와 라우팅 인계 문제를 구분하기 쉽습니다.

설정 파일을 읽는 순서

익숙하지 않은 설정을 읽을 때는 최상위 포트부터 시작해 dns, proxies 또는 proxy-providers, proxy-groups, rules 순서로 확인하고 마지막에 tun과 profile을 점검하면 됩니다. 이 순서는 트래픽 처리 과정과 일치합니다. 애플리케이션이 먼저 로컬 포트나 TUN으로 들어오고, 도메인이 DNS를 통해 해석되며, 규칙이 정책 그룹을 선택하고, 정책 그룹이 구체적인 노드를 선택합니다.

설정의 유지 관리성을 결정하는 것은 필드 수가 아니라 참조 관계가 명확한지 여부입니다. 노드 이름, provider 이름, 정책 그룹 이름, 규칙 대상은 하나의 연속된 연결 고리를 이룹니다. 어느 이름이든 수정했다면 그 연결 고리를 따라 이후 참조를 확인해야 합니다. 수정이 끝나면 클라이언트의 설정 검증 기능으로 다시 로드하고 연결 로그에서 실제 매칭 결과를 확인하세요.