Clash YAML 설정 파일 구조 해설: 포트, DNS, proxies, proxy-groups, rules

설정 구조: 참조 관계부터 확인한 뒤 항목 수정

Clash 설정 파일은 노드 목록만 담은 파일이 아닙니다. 포트는 앱이 연결을 코어에 전달하는 방식을 정하고, DNS는 도메인 이름을 조회하며, 노드는 원격 연결 정보를 정의합니다. 정책 그룹은 사용할 출구를 구성하고, 규칙은 연결을 적절한 출구로 보냅니다. FlClash에서 사용하는 Clash Meta 코어는 mihomo라고도 합니다. 이 글에서는 해당 코어 기준으로 설정을 설명하며, 구형 코어에서는 일부 항목을 지원하지 않을 수 있습니다.

가장 중요한 관계는 규칙이 정책 그룹을 참조하고, 정책 그룹이 노드 이름이나 내장 출구를 참조한다는 점입니다. 예를 들어 규칙이 요청을 “수동 선택” 그룹으로 보내면, 이 그룹에서 “예시 노드” 또는 DIRECT를 선택합니다. 이름은 정확히 일치해야 합니다. 공백 하나만 달라도 대상을 찾지 못할 수 있습니다.

proxies: 프로토콜, 서버, 포트, 인증 정보를 담는 노드 목록입니다.
proxy-groups: 선택 가능한 출구와 선택 방식을 지정하는 정책 그룹 목록입니다.
rules: 연결을 어느 출구로 보낼지 결정하는 순서가 있는 규칙 목록입니다.
dns와 tun: 각각 도메인 이름 조회와 가상 네트워크 인터페이스를 통한 트래픽 전달을 처리하며, 노드 자체를 뜻하지는 않습니다.

기본 항목: 포트, 모드, 로그

먼저 최상위 항목부터 살펴보겠습니다. 아래 예시는 HTTP 프록시와 SOCKS5를 모두 받는 로컬 혼합 포트를 설정합니다. 여기서 7890은 예시 값이며, 모든 구독이나 클라이언트가 같은 포트를 사용하는 것은 아닙니다.

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

항목	예시 값	기능
`mixed-port`	`7890`	하나의 포트에서 HTTP와 SOCKS5 프록시 연결을 모두 받습니다.
`allow-lan`	`false`	이 프록시 연결 지점을 LAN 공유용으로 사용하지 않도록 합니다.
`mode`	`rule`	모든 연결에 전역 설정을 적용하는 대신 규칙에 따라 출구를 선택합니다.
`log-level`	`info`	일반적인 실행 정보를 기록합니다. 문제를 진단할 때는 잠시 debug로 변경할 수 있습니다.
`ipv6`	`false`	코어의 IPv6 사용을 제한하며, 운영체제의 IPv6를 끄는 설정은 아닙니다.

프록시 포트와 노드 포트는 다릅니다

이 컴퓨터의 앱은 127.0.0.1:7890에 연결하지만, 원격 노드의 서비스 포트는 443이나 서버에서 지정한 다른 포트일 수 있습니다. 두 포트가 같을 필요는 없습니다. port는 HTTP 프록시만, socks-port는 SOCKS 프록시만 제공할 수 있습니다. 혼합 포트를 사용한다면 모든 수신 포트를 설정해야 하는 것은 아닙니다.

설정을 불러온 뒤 curl -I -x http://127.0.0.1:7890 https://example.com을 실행해 프록시 포트가 연결을 받는지 확인할 수 있습니다. 이 명령은 HTTP 요청 경로만 테스트하며 UDP, TUN 또는 모든 앱의 트래픽이 전달되는지는 확인하지 않습니다. 연결 거부 오류가 발생하면 실제 수신 포트와 코어 실행 상태부터 확인하세요.

DNS 항목: 조회 경로와 Fake-IP

DNS 설정은 코어가 도메인 이름을 조회하는 방식에 영향을 줍니다. 아래는 이해를 돕기 위한 최소 예시입니다. 로컬의 1053 포트에서 요청을 받고 Fake-IP 모드를 사용하며, 암호화된 상위 DNS 서버 하나를 지정합니다. 모든 네트워크에 적합한 권장 설정은 아니며, 상위 서버 주소에 현재 네트워크에서 접속할 수 있어야 합니다.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://1.1.1.1/dns-query

1053 포트 수신과 시스템 DNS는 별개입니다

listen은 코어가 DNS 서비스를 제공하도록 설정할 뿐입니다. 이 항목만 적는다고 시스템 DNS가 해당 주소로 자동 변경되지는 않습니다. 일반적인 시스템 DNS 설정에는 사용자 지정 포트를 직접 입력할 수 없는 경우가 많습니다. 시스템 DNS를 가로채는지는 TUN의 DNS 리디렉션, 시스템 네트워크 설정, 실제 라우팅에 따라 달라집니다.

Fake-IP는 실제 서버 주소가 아닙니다

198.18.0.1/16은 코어의 가상 주소 매핑에 사용됩니다. 앱이 매핑된 주소를 받으면 코어는 저장된 도메인 정보를 바탕으로 규칙을 적용하고 연결을 설정합니다. 따라서 이 주소 대역이 보인다고 바로 DNS 오류라고 판단할 필요는 없습니다. 요청이 같은 코어로 돌아오는지, 매핑 정보가 여전히 유효한지 확인하세요.

dns.ipv6: false는 이 설정에서 호출 측에 AAAA 응답을 반환하지 않도록 합니다. 최상위 ipv6 항목과는 적용 범위가 다릅니다.
nameserver는 기본 DNS 상위 서버입니다. 도메인 이름으로 된 상위 서버 주소를 사용한다면 해당 도메인 자체를 조회할 초기 DNS 경로도 고려해야 합니다.
노드의 server가 도메인 이름이라면 이 주소도 조회할 수 있어야 합니다. 복잡한 설정에서는 proxy-server-nameserver를 따로 지정해 노드 도메인을 조회할 상위 DNS 서버를 설정할 수 있습니다.
상위 DNS 서버, Fake-IP 필터, TUN 리디렉션을 한꺼번에 변경하지 마세요. 한 번에 하나씩 바꿔야 문제의 원인을 파악할 수 있습니다.

proxies: 노드 매개변수는 서버 설정과 일치해야 합니다

proxies는 목록이며 각 노드는 - name:으로 시작합니다. 프로토콜마다 필수 항목이 다릅니다. Shadowsocks의 비밀번호와 암호화 방식을 UUID나 TLS 설정이 필요한 다른 프로토콜에 그대로 적용할 수는 없습니다. 아래에서는 Shadowsocks 노드의 항목 구조만 보여줍니다.

proxies:
  - name: "예시 노드"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: chacha20-ietf-poly1305
    password: "yaml-demo-password"
    udp: true

name은 정책 그룹에서 참조하는 로컬 이름으로, 한국어를 사용할 수 있습니다. server는 원격 서버 주소입니다. udp: true는 해당 노드 설정에서 UDP 기능을 활성화하지만, 서버와 회선, 앱이 모두 UDP 전달을 지원한다는 보장은 없습니다.

서비스 제공업체가 완성된 Clash 구독을 제공한다면 노드 정보가 이미 포함되어 있는 경우가 많으므로 직접 다시 작성할 필요가 없습니다. 자주 쓰이는 다른 구조로 proxy-providers가 있습니다. 이 항목은 노드를 제공자가 관리하도록 하며, 정책 그룹에서 use로 제공자 이름을 참조합니다. 제공자 이름을 단일 노드 이름처럼 그룹의 proxies 목록에 넣지 마세요.

proxy-groups: 노드를 선택 가능한 출구로 구성하기

노드를 정의한 다음 정책 그룹을 만듭니다. select는 사용자가 그룹 안에서 출구를 직접 선택하는 방식으로, 설정 참조가 올바른지 확인하기에 적합합니다. 아래의 “수동 선택” 그룹에는 예시 노드와 직접 연결 출구가 포함되어 있습니다.

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - "예시 노드"
      - DIRECT

DIRECT는 내장된 직접 연결 출구이므로 최상위 proxies에 추가하지 않아도 됩니다. REJECT도 내장 출구이며 연결을 차단할 때 사용합니다. 사용자 지정 그룹 이름은 이러한 내장 이름과 겹치지 않게 하고, 같은 이름의 노드와 정책 그룹을 만들지 마세요.

자동 지연 측정은 다운로드 속도 테스트가 아닙니다

url-test 정책 그룹은 설정된 테스트 주소와 간격에 따라 후보 출구의 응답 지연을 비교합니다. 예를 들어 interval: 300은 300초 간격을 뜻하고, tolerance: 50은 전환 허용 오차를 밀리초 단위로 설정할 수 있습니다. 테스트 결과는 대상 사이트와 네트워크 경로에 영향을 받으므로 대용량 파일의 다운로드 속도로 환산할 수 없습니다.

처음 문제를 진단할 때는 수동 그룹 하나만 두는 것이 좋습니다. 먼저 노드 연결과 규칙 참조를 확인한 다음 자동 선택이나 장애 조치를 추가하세요. 정책 그룹끼리 참조할 수 있지만 A가 B를 참조하고 B가 다시 A를 참조하는 순환 참조는 피해야 합니다.

rules: 위에서 아래로 확인해 처음 일치하는 규칙 적용

mode: rule에서는 보통 규칙을 위에서 아래로 확인하고, 처음 일치한 규칙이 지정한 출구로 연결을 보냅니다. 구체적인 규칙은 앞에, 마지막 대체 규칙은 맨 뒤에 둡니다. 아래 도메인은 일치 범위를 설명하기 위한 예시일 뿐, 특정 사이트를 반드시 직접 연결하거나 프록시로 보내야 한다는 뜻은 아닙니다.

rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,수동 선택
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,수동 선택

DOMAIN,example.com: 이 도메인과 정확히 일치하는 경우를 찾습니다. www.example.com은 자동으로 포함되지 않습니다.
DOMAIN-SUFFIX,example.org: 해당 도메인과 하위 도메인에 일치하며, 임의의 문자열 포함 여부를 검사하는 규칙은 아닙니다.
IP-CIDR: 대상 IP 대역을 기준으로 일치 여부를 판단합니다. 예시에 나온 두 사설 IP 대역이 전체 LAN 주소 범위를 뜻하지는 않습니다.
no-resolve: 이 IP 규칙을 위해 도메인 조회를 새로 시작하지 않도록 합니다. 연결에 DNS가 전혀 필요하지 않다는 뜻은 아닙니다.
MATCH: 앞선 규칙에 일치하지 않은 연결을 처리합니다. 맨 앞에 두면 뒤에 있는 규칙이 적용될 기회가 사라집니다.

규칙이 적용되지 않으면 모드와 새 연결부터 확인하세요

클라이언트가 전역 모드라면 규칙 모드에서 기대하는 결과를 기준으로 판단할 수 없습니다. 규칙 모드로 바꾼 뒤 연결 기록에서 대상 도메인, 일치한 규칙, 실제 출구를 확인하세요. 도메인 정보 없이 IP만 확인되는 연결은 예상한 도메인 규칙과 일치한다고 보장할 수 없습니다.

규칙을 수정하거나 정책을 전환한 뒤에는 새 연결을 만들어 테스트하세요. 브라우저가 기존 TCP 또는 QUIC 연결을 재사용할 수 있으며, 설정 문구를 바꿔도 기존 연결이 새 규칙에 따라 자동으로 다시 만들어지지는 않습니다. 필요하면 해당 연결을 닫고 다시 시도하세요. 재사용 중인 세션을 계속 새로고침하는 것만으로는 충분하지 않습니다.

TUN: 트래픽 진입 경로이며 규칙과 DNS를 대체하지 않습니다

TUN 모드는 가상 네트워크 인터페이스를 통해 트래픽을 코어로 전달하므로 시스템 프록시 설정을 읽지 않는 앱에 유용합니다. mixed-port와는 서로 다른 연결 방식이지만, 전달된 연결의 출구는 여전히 정책 그룹과 규칙이 결정합니다. 아래 예시는 비활성화 상태로 두고 mihomo에서 흔히 쓰이는 항목 구조만 보여줍니다.

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

auto-route는 라우팅을 자동으로 설정하고, auto-detect-interface는 아웃바운드 인터페이스를 자동으로 찾습니다. 지원 여부와 동작은 시스템 및 코어 버전에 따라 달라집니다. dns-hijack의 any:53은 가로챈 일반 DNS 트래픽을 처리하는 설정입니다. 이것만으로 앱 자체의 DoH나 모든 암호화 DNS가 가로채진다고 볼 수는 없습니다.

TUN을 활성화하려면 대개 시스템 권한이 필요합니다. FlClash의 인터페이스 설정이 최종 설정 생성에 반영될 수도 있으므로 구독 파일의 enable 값만 보고 실제 실행 여부를 판단해서는 안 됩니다. 가상 네트워크 인터페이스, 라우팅, 클라이언트 상태, 연결 기록을 함께 확인하세요. 시스템에서 다른 VPN도 실행 중이라면 먼저 현재 상태를 기록한 뒤 하나씩 중지해 비교하세요. 여러 트래픽 전달 경로를 동시에 바꾸지 않는 것이 좋습니다.

들여쓰기 점검과 최소 로드 가능 예시

YAML은 들여쓰기로 구조를 표현합니다. 공백 두 칸을 일관되게 사용하고 Tab은 피하세요. 최상위의 dns, proxies, proxy-groups, rules는 같은 위치에 맞춰야 합니다. 같은 노드 안의 type, server, port도 서로 같은 들여쓰기 단계에 있어야 합니다.

콜론 뒤 공백을 확인하세요.mode: rule은 키와 값의 형식입니다. mode:rule은 일반 문자열로 처리될 수 있습니다.
목록의 하이픈 위치를 확인하세요. 노드, 그룹의 후보 항목, 규칙은 모두 목록이지만 각각 속한 단계는 다릅니다.
특수 문자를 확인하세요. 비밀번호나 이름에 #, 콜론 뒤 공백 등이 있으면 적절한 따옴표로 묶으세요. 큰따옴표 문자열에서는 백슬래시도 이스케이프 처리가 필요합니다.
중복 키를 확인하세요. 파일 끝에 최상위 rules를 하나 더 추가하지 마세요. 기존 목록에 규칙을 합쳐야 합니다. 키가 중복되면 오류가 발생하거나 기존 값이 덮어써질 수 있습니다.
이름 참조를 확인하세요. “수동 선택”과 “수동 선택 ”은 서로 다른 이름입니다. 노드나 정책 그룹의 이름을 바꾸면 참조하는 곳도 함께 수정해야 합니다.

먼저 직접 연결 설정을 확인한 뒤 실제 노드를 추가하세요

아래는 독립적으로 사용할 수 있는 최소 설정이며, 모든 연결을 직접 연결합니다. 원격 프록시 기능은 없지만 로컬 사본에서 포트, 정책 그룹, 규칙의 기본 구조를 확인하기에 적합합니다. 현재 사용하는 설정을 덮어쓰는 구독 대체 파일로 사용하지 마세요.

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

proxies: []

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,수동 선택

mihomo를 별도로 실행한다면 mihomo -t -f ./config.yaml을 사용해 지정한 파일을 확인할 수 있습니다. 검사를 통과했다는 것은 코어가 설정을 받아들였다는 뜻일 뿐, 노드 인증 정보가 정확하거나 상위 DNS에 연결되거나 라우팅이 적용되었다는 뜻은 아닙니다. FlClash에서 관리하는 설정은 클라이언트에서 다시 불러온 뒤 실제 오류 메시지를 확인하세요.

설정을 계속 진행하려면 고급 설정 안내에서 정책 그룹, 규칙, TUN의 관계를 확인하세요. 구독 가져오기부터 시작하려면 설정 가이드에 따라 구독을 불러오고 모드를 선택하면 됩니다. 설정 파일은 의도한 구성을 나타내지만, 실제 적용 결과는 클라이언트 실행 상태와 연결 기록을 기준으로 확인해야 합니다.