Clash 설정 파일 YAML 구조 완벽 정리: 기본 항목부터 proxy-groups와 rules까지

YAML 파일, 구독, 코어 설정의 차이부터 알아보기

config.yaml은 설정 파일에 흔히 사용하는 이름이며, 확장자는 .yml이어도 됩니다. YAML은 키와 값, 목록, 계층 구조를 표현하고 Clash 또는 mihomo가 해당 필드의 의미를 해석합니다. YAML 파서로 파일을 읽을 수 있다고 해서 노드 프로토콜, DNS 매개변수, 규칙 유형까지 현재 코어에서 지원된다는 뜻은 아닙니다.

Clash Meta는 이후 mihomo라는 이름으로 개발·유지되고 있습니다. 클라이언트마다 포함된 코어와 설정 메뉴가 다를 수 있습니다. 이 글은 mihomo 설정 구조를 기준으로 설명하며, 인라인 규칙 집합 등의 기능을 구형 Clash 코어에 그대로 적용해서는 안 됩니다. 호환성을 확인할 때는 클라이언트 이름만 보지 말고 정보 또는 코어 정보 화면에서 실제 실행 중인 코어를 확인하세요.

전체 설정 구독: 포트, DNS, 노드, 정책 그룹, 규칙이 함께 포함될 수 있으며, 구독을 업데이트하면 이 설정도 바뀔 수 있습니다.
노드 제공자: proxy-providers로 노드를 제공하고 로컬 정책 그룹에서 이를 참조합니다. 전체 설정 파일과는 다릅니다.
클라이언트 오버라이드: 구독 내용에 필드를 추가하거나 기존 값을 바꿉니다. 병합 순서는 클라이언트에 따라 다릅니다.

구조 검증에 사용할 수 있는 전체 config.yaml 예제

아래 설정은 로컬 혼합 포트와 직접 연결 정책만 제공하며 프록시 서버는 포함하지 않습니다. 필드 계층, 정책 참조, 규칙 순서를 확인하기 위한 예제이며, 불러오기에 성공해도 프록시를 통한 외부 연결이 가능한 것은 아닙니다. 예제의 인라인 규칙 집합을 사용하려면 type: inline을 지원하는 mihomo 코어가 필요합니다.

# 기본 진입점
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

# DNS 모듈; 별도 DNS 수신 포트는 설정하지 않음
dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '*.lan'
    - 'localhost'
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

# 원격 프록시 노드는 포함하지 않음
proxies: []

# 정책 그룹 이름은 rules에서 참조
proxy-groups:
  - name: 출구 선택
    type: select
    proxies:
      - DIRECT

# 인라인 규칙 집합; 별도 규칙 파일 불필요
rule-providers:
  예시 도메인:
    type: inline
    behavior: domain
    payload:
      - '+.example.com'

# 위에서부터 순서대로 매칭하고 마지막 규칙은 기본 처리
rules:
  - DOMAIN,localhost,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - RULE-SET,예시 도메인,출구 선택
  - MATCH,출구 선택

이 파일은 시스템 프록시와 TUN을 활성화하지 않습니다. 애플리케이션의 HTTP 프록시를 127.0.0.1:7890으로 직접 설정해야 해당 앱의 요청이 혼합 포트로 전달됩니다. 연결이 코어에 들어오면 규칙에 따라 ‘출구 선택’ 정책이 적용됩니다. 현재 이 그룹에는 DIRECT만 있으므로 목적지에 직접 연결됩니다.

작성 순서와 실행 순서는 다릅니다

최상위 항목에서 dns를 proxies보다 먼저 쓰든 나중에 쓰든 일반적으로 설정 의미는 달라지지 않습니다. ‘진입점 → DNS → 노드 → 정책 그룹 → 규칙 집합 → 규칙’ 순서로 정리하면 의존 관계를 확인하기 쉽습니다. 실제 매칭 결과를 바꾸는 것은 rules 목록의 순서입니다. 정책 그룹 안의 후보 순서는 화면 표시에도 영향을 주므로 모든 목록을 순서를 바꿔도 되는 사전처럼 취급해서는 안 됩니다.

기본 설정: 포트, 작동 모드, 로그

필드	예시 값	기능
`mixed-port`	`7890`	하나의 포트에서 HTTP와 SOCKS 프록시 연결을 모두 받습니다.
`allow-lan`	`false`	같은 LAN의 다른 기기에서 이 기기의 프록시 진입점을 사용할 수 없게 합니다.
`mode`	`rule`	규칙 목록에 따라 연결에 적용할 정책을 결정합니다.
`log-level`	`info`	일반 실행 정보를 출력합니다. 문제를 진단할 때는 일시적으로 debug로 바꿀 수 있습니다.
`ipv6`	`false`	코어의 IPv6 지원을 끕니다. 운영체제의 네트워크 설정을 변경하는 것은 아닙니다.

mixed-port: 7890을 설정해도 시스템의 모든 트래픽이 Clash로 전달되는 것은 아닙니다. 시스템 프록시는 해당 설정을 따르는 앱에만 적용되며, 자체적으로 네트워크에 연결하는 프로그램은 이를 우회할 수 있습니다. TUN은 가상 네트워크 인터페이스와 라우팅을 통해 연결을 처리하므로 시스템 프록시와는 다른 트래픽 진입 방식입니다.

external-controller는 관리 API가 연결을 받는 주소이며, 브라우저에 입력하는 프록시 주소가 아닙니다. 예를 들어 로컬 관리 포트는 127.0.0.1:9090으로 설정할 수 있지만, 혼합 포트와 같은 주소의 7890을 동시에 사용할 수는 없습니다. 클라이언트가 제어 인터페이스를 직접 관리할 수도 있으므로 수동으로 덮어쓰기 전에 클라이언트 요구 사항을 확인하세요.

dns: 해석 모드, 업스트림, Fake-IP의 관계

dns는 최상위 맵입니다. 내부의 enable, nameserver 등의 필드는 dns:보다 한 단계 더 들여써야 합니다. 예제의 nameserver에는 업스트림 DNS 주소 두 개가 지정되어 있습니다. 주소를 두 개 썼다고 반드시 첫 번째 주소부터 차례대로 재시도한다는 뜻은 아닙니다. 실제 조회 방식은 코어 구현과 다른 DNS 매개변수에 따라 달라집니다.

Fake-IP는 프록시 노드 주소가 아닙니다

enhanced-mode: fake-ip를 설정하면 코어가 해당 도메인의 조회에 가상 주소를 할당하고, 이후 연결을 매핑 정보와 연결합니다. 예제의 주소 범위 198.18.0.1/16은 원격 서버 주소가 아니므로 노드의 server 필드에 넣어서는 안 됩니다. 실제 조회 결과가 필요한 일부 LAN 앱은 필요에 따라 fake-ip-filter에 추가할 수 있습니다.

dns.enable: true는 코어의 DNS 모듈을 켜지만, 운영체제의 모든 DNS 요청이 코어로 전달된다는 뜻은 아닙니다.
dns.listen은 별도의 DNS 수신 포트를 여는 설정입니다. 예제에서는 포트를 추가로 사용하지 않도록 설정하지 않았습니다.
dns.ipv6: false는 코어 DNS가 AAAA 조회를 처리하는 방식을 제어합니다. 이 설정만으로 시스템이 IPv6 연결을 전혀 시도하지 않는다고 볼 수는 없습니다.
암호화 DNS는 해당 DNS 조회 경로를 보호할 뿐, 프록시 규칙을 대신하거나 모든 DNS 요청이 프록시를 거친다고 보장하지 않습니다.

‘도메인으로는 접속할 수 없지만 IP 주소로는 접속되는’ 문제가 발생하면 먼저 DNS 조회가 코어에 전달되는지, 업스트림에 연결할 수 있는지 확인한 다음 Fake-IP 매핑과 라우팅을 살펴보세요. 이때 노드를 계속 바꿔도 실제 문제 원인을 해결하지 못할 수 있습니다.

proxies와 proxy-groups: 노드와 선택 로직 분리하기

proxies는 노드 목록입니다. 각 노드에는 보통 name, type, server, port와 해당 프로토콜에서 요구하는 인증 및 전송 매개변수가 들어갑니다. 프로토콜마다 필드가 다르므로 서로 바꿔 쓸 수 없습니다. 예를 들어 비밀번호 필드는 다른 프로토콜에서 요구하는 UUID를 대신할 수 없습니다. 실제 값은 서비스 제공자나 직접 구축한 서버의 설정에서 확인하세요.

proxy-groups는 원격 서버를 정의하는 대신 출구를 선택하는 방식을 정합니다. 그룹 안의 proxies는 최상위 필드와 이름은 같지만, 여기서는 후보 이름 목록입니다. 이름은 정의된 노드나 다른 참조 가능한 정책 그룹, 또는 DIRECT 같은 내장 정책과 일치해야 합니다.

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

select: 클라이언트에서 후보를 직접 선택합니다. 특정 노드나 직접 연결을 지정할 때 적합합니다.
url-test: 지정한 테스트 주소의 응답을 바탕으로 후보를 자동 선택합니다. 측정된 지연 시간이 모든 웹사이트의 실제 로딩 속도와 같지는 않습니다.
fallback: 후보 순서와 상태 확인 결과에 따라 사용 가능한 항목을 선택합니다. 주 연결과 예비 연결을 전환할 때 적합합니다.
load-balance: 설정한 분배 방식에 따라 연결을 처리합니다. 다운로드 한 건을 여러 노드에 나눠 대역폭을 합산한다는 뜻은 아닙니다.

예제에서는 select를 사용하므로 테스트 URL이 필요하지 않습니다. 자동 테스트 방식의 정책 그룹으로 바꾼다면 현재 네트워크에 적합한 테스트 주소와 확인 간격도 지정해야 합니다. 예를 들어 interval: 300은 300초를 의미합니다. type만 바꾸고 해당 유형에 필요한 매개변수를 빠뜨리지 않도록 주의하세요.

구독 노드를 proxy-providers에 넣어 참조하는 방법

노드 제공자를 사용하면 정책 그룹에서는 구독 URL을 그룹의 proxies 목록에 넣는 대신 use로 제공자 이름을 참조하는 것이 일반적입니다. 제공자가 반환하는 내용도 해당 형식에 맞아야 하며, 일반적인 전체 설정 구독을 노드 제공자로 바로 사용할 수 있는 것은 아닙니다. 규칙은 정책 그룹을 가리키고, 정책 그룹은 노드를 선택하도록 참조 관계를 명확히 유지하세요.

rule-providers와 rules: 규칙 집합과 매칭 진입점

rule-providers에는 재사용할 규칙 집합을 정의하고, rules에서는 해당 집합을 언제 참조할지와 매칭 후 적용할 정책을 지정합니다. ‘예시 도메인’이라는 규칙 집합만 정의하고 RULE-SET,예시 도메인,출구 선택을 작성하지 않으면 자동으로 트래픽 분리에 사용되지 않습니다.

behavior에 따라 payload 작성법이 달라집니다

behavior	콘텐츠 예시	주의 사항
`domain`	`+.example.com`	도메인 규칙 집합 형식을 사용하며 각 행에 대상 정책 그룹을 추가하지 않습니다.
`ipcidr`	`192.168.0.0/16`	콘텐츠는 IP 대역이어야 하며 도메인을 섞어 넣으면 안 됩니다.
`classical`	`DOMAIN-SUFFIX,example.com`	규칙 표현식을 사용하며 대상 정책은 참조하는 위치에서 지정합니다.

예제에서는 type: inline을 사용하므로 규칙 집합 내용이 payload 아래에 직접 들어갑니다. 원격 HTTP 규칙 제공자는 다운로드 주소, 캐시 경로, 업데이트 간격, 형식도 설정해야 합니다. 원격 파일의 본문을 URL 필드에 그대로 복사해서는 안 됩니다. 구형 코어가 인라인 제공자를 지원하지 않는다면 규칙 의미가 같은지 확인한 뒤 일반 규칙으로 바꾸세요.

위에서부터 확인하고 처음 매칭된 규칙 적용

예를 들어 예시 도메인에는 ‘출구 선택’을 적용하고 나머지 연결은 직접 연결하려면 다음과 같이 작성합니다.

rules:
  - DOMAIN-SUFFIX,example.com,출구 선택
  - MATCH,DIRECT

DOMAIN은 도메인 전체와 일치하고, DOMAIN-SUFFIX는 해당 도메인과 하위 도메인에 일치합니다. MATCH는 기본 규칙이므로 일반적으로 마지막에 둡니다. 이를 첫 줄로 옮기면 뒤에 있는 도메인 규칙은 매칭될 기회가 없습니다. 규칙을 추가할 때는 기존 목록을 수정하세요. 파일 끝에 두 번째 rules:를 추가하면 안 됩니다.

IP 규칙 끝의 no-resolve는 해당 IP 규칙과 매칭하려고 도메인을 IP로 능동적으로 조회하지 않는다는 뜻입니다. DNS를 전역적으로 끈다는 의미는 아닙니다. 연결에 대상 IP가 이미 지정되어 있다면 해당 네트워크 대역 규칙과 매칭될 수 있습니다. 예제에는 일부 로컬 주소 범위만 나와 있으므로 이 세 규칙을 전체 사설망 규칙 집합으로 간주해서는 안 됩니다.

TUN 설정 위치와 스위치 하나만 켜서는 안 되는 이유

tun은 dns, rules와 마찬가지로 최상위 필드이며 정책 그룹 안에 들여써서는 안 됩니다. 데스크톱에서 흔히 사용하는 설정 예시는 다음과 같습니다. 실제 지원 여부는 코어, 운영체제, 클라이언트의 트래픽 처리 방식에 따라 달라집니다.

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

auto-route는 관련 라우트를 자동으로 설정하고, auto-detect-interface는 출구 인터페이스를 자동으로 감지합니다. TUN을 활성화하려면 보통 관리자 권한이나 클라이언트의 서비스 모드가 필요합니다. Android 클라이언트는 시스템의 VpnService로 VPN 인터페이스를 만드는 경우가 많으므로 데스크톱의 권한 설정 절차를 그대로 적용하지 마세요.

dns-hijack의 any:53은 대상이 되는 기존 DNS 트래픽을 가로채는 설정이며, 브라우저가 HTTPS로 보내는 모든 암호화 DNS 요청까지 처리하지는 않습니다. 회사 VPN, 다른 가상 네트워크 인터페이스, 수동 라우팅이 자동 라우팅과 충돌할 수도 있습니다. 진단 기준을 잃지 않도록 먼저 시스템 프록시 진입점에서 설정이 정상인지 확인한 다음 TUN을 활성화하세요. 진입 방식, DNS, 규칙을 한꺼번에 바꾸지 않는 것이 좋습니다.

불러오기 전 확인: 들여쓰기, 참조, 클라이언트 오버라이드

YAML에서 자주 발생하는 오류

Tab으로 들여쓰기: 공백 두 칸으로 통일하세요. 같은 계층의 항목은 들여쓰기를 맞춰야 합니다.
목록 기호 누락: rules, nameserver, 그룹 내 후보 항목은 모두 목록입니다.
최상위 필드 중복: dns:를 두 번 쓴다고 자동 병합되지 않습니다. 파서에서 오류가 나거나 한쪽만 남을 수 있습니다.
특수 문자에 따옴표 누락: 비밀번호, 특수 기호가 포함된 이름, 다른 자료형으로 잘못 해석될 수 있는 값은 따옴표로 묶는 것이 좋습니다.
대소문자 또는 이름 불일치: 출구 선택과 출구 선택 은 같은 참조로 안전하게 처리되지 않습니다. 복사할 때 뒤에 공백이 붙지 않았는지 확인하세요.

코어로 검사한 뒤 실제 적용 결과 확인하기

mihomo 명령줄 프로그램이 설치되어 있다면 설정 파일이 있는 디렉터리에서 다음 명령을 실행하세요.

mihomo -t -f ./config.yaml

Windows에서는 현재 디렉터리에 프로그램이 있을 때 .\mihomo.exe -t -f .\config.yaml을 사용할 수 있습니다. 검사가 통과했다는 것은 해당 코어에서 설정을 검사할 수 있다는 뜻일 뿐, 노드 인증이 올바르거나 네트워크에 연결할 수 있거나 시스템 트래픽이 프록시로 전달된다는 의미는 아닙니다.

먼저 설정 테스트를 실행하고 로그에 표시된 줄 번호, 알 수 없는 필드, 정책 참조 오류부터 해결하세요.
클라이언트에서 설정을 불러온 뒤 혼합 포트가 실제로 7890인지, 포트 사용 오류가 없는지 확인하세요.
프록시가 설정된 앱에서 요청을 보내고 연결 목록에서 일치한 규칙과 최종 정책을 확인하세요.
파일에 mode: rule을 설정했는데 화면에 다른 모드가 표시된다면 클라이언트의 전역 설정이나 런타임 API가 파일 값을 덮어쓰는지 확인하세요.
마지막으로 구독을 한 번 업데이트해 사용자 지정 규칙이 그대로 남아 있는지 확인하고, 유지해야 할 변경 내용이 오버라이드 계층에 저장되어 있는지 점검하세요.