고급 설정 예상 읽기 시간 13분

Clash YAML 설정 파일 필드별 해설

port, mode, dns부터 proxies, proxy-groups, rules까지 설정 파일 순서에 따라 각 필드의 의미와 허용값, 잘못 수정했을 때 나타나는 대표 오류를 설명합니다.

Clash 설정 파일은 일반적으로 YAML로 작성합니다. 하나의 문서에 수신 포트, 실행 모드, DNS, 프록시 노드, 정책 그룹과 분기 규칙을 함께 넣습니다. 필드 순서는 보통 코어의 읽기에 영향을 주지 않지만, ‘기본 매개변수 → DNS → 노드 → 정책 그룹 → 규칙’ 순서로 작성하면 참조 관계와 들여쓰기 오류를 쉽게 찾을 수 있습니다.

이 글은 Clash for Windows 0.20.39에서 흔히 사용하는 설정 구조와 mihomo v1.19 계열의 설정 의미를 기준으로 합니다. 코어마다 지원하는 프로토콜, TUN 매개변수와 DNS 확장 필드는 완전히 같지 않습니다. 구독으로 생성된 설정을 수정하기 전에는 다음 구독 업데이트에서 수동 변경 사항이 덮어써지지 않도록 로컬 사본을 별도로 저장하는 것이 좋습니다.

YAML 문법과 최상위 구조

들여쓰기, 목록과 키-값

YAML은 공백으로 계층을 표현하며 Tab을 들여쓰기로 사용할 수 없습니다. 일반적으로 각 계층에 공백 2칸을 사용합니다. 콜론 뒤에는 공백 하나를 넣고, 목록 항목은 하이픈으로 시작합니다. 노드, 정책 그룹과 규칙은 서로 다른 최상위 키 아래에 있으며, 계층이 한 칸만 어긋나도 파일 전체를 불러오지 못할 수 있습니다.

port: 7890
mode: rule

proxies:
  - name: "예시 노드"
    type: ss
    server: 203.0.113.10
    port: 443

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

rules:
  - MATCH,노드 선택

port: 7890은 키-값이고, proxies: 뒤에는 목록이 옵니다. - name:으로 시작하는 각 항목은 하나의 노드 객체입니다. 콜론, 샵, 별표가 포함되거나 불리언으로 인식될 수 있는 이름은 따옴표로 감싸는 것이 좋습니다. 예를 들어 노드 이름을 "HK: 01"로 작성하면 콜론이 매핑 구분자로 해석되는 것을 막을 수 있습니다.

자주 발생하는 파싱 오류

포트, LAN과 실행 모드 필드

파일 앞부분에는 보통 인바운드 수신 포트와 기본 실행 매개변수가 들어갑니다. 다음 예시는 HTTP, SOCKS5와 혼합 프록시에 각각 포트를 설정합니다. 실제 사용에서는 세 포트를 모두 켤 필요가 없으며, 데스크톱 클라이언트에서는 mixed-port를 가장 많이 사용합니다.

port: 7890
socks-port: 7891
mixed-port: 7892
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "change-this-controller-secret"

세 프록시 포트의 차이

동일한 IP와 포트는 두 프로그램이 동시에 수신할 수 없습니다. 로그에 address already in use 또는 bind: Only one usage of each socket address가 표시되면 먼저 이전 Clash 프로세스, 다른 프록시 도구 또는 로컬 개발 서버가 포트를 사용 중인지 확인하세요. Windows에서는 터미널에서 netstat -ano | findstr :7890을 실행해 해당 PID를 찾을 수 있습니다.

allow-lan과 bind-address

allow-lan: false는 LAN 기기에 프록시 진입점을 제공하지 않는다는 뜻입니다. true로 바꾸면 휴대폰이나 다른 컴퓨터에서 현재 컴퓨터의 LAN 주소를 프록시 서버로 입력할 수 있습니다. 예: 192.168.1.20:7890. 이때 해당 포트가 Windows 방화벽을 통과하도록 허용해야 합니다.

bind-address는 수신 주소를 결정합니다. 로컬에서만 사용할 때는 127.0.0.1에 바인딩하는 것이 명확합니다. LAN에서 접근해야 한다면 코어 지원 여부에 따라 * 또는 특정 네트워크 인터페이스 주소를 사용할 수 있습니다. allow-lan만 수정한다고 해서 다른 기기의 연결이 보장되는 것은 아닙니다. 방화벽, 게스트 네트워크 격리와 라우터의 AP 격리도 접근을 차단할 수 있습니다.

mode, log-level과 제어 포트

DNS 섹션: 수신, 리졸버와 향상 모드

DNS 섹션은 도메인을 해석하는 방식을 결정합니다. 규칙 매칭뿐 아니라 TUN 모드에서 도메인 요청을 가로채는 방식에도 영향을 줍니다. 일반적인 기본 구조는 다음과 같습니다.

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"
    - "localhost.ptlogin2.qq.com"
    - "+.msftconnecttest.com"
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - tls://1.1.1.1:853
  fallback:
    - https://dns.google/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

enable, listen과 default-nameserver

enable은 내장 DNS 모듈을 제어합니다. listen은 DNS 서비스의 수신 주소이며, 예시에서는 로컬 UDP/TCP 포트 1053을 사용합니다. 다른 로컬 DNS 프로그램이 해당 포트를 이미 사용 중이면 로그에 수신 실패가 표시됩니다.

default-nameserver는 주로 DoH, DoT 등 업스트림 서버 자체의 도메인을 해석하는 데 사용되며, 부트스트랩 DNS라고도 합니다. 순환 의존을 피하려면 여기에는 먼저 해석해야 하는 도메인이 아니라 직접 접근할 수 있는 IP 주소를 입력하는 것이 일반적입니다.

nameserver, fallback과 정책 기반 해석

nameserver는 주 리졸버로, 일반 DNS 주소뿐 아니라 DoH 또는 DoT 주소도 사용할 수 있습니다. fallback과 fallback-filter는 기존 Clash 설정에서 흔히 사용하는 보조 해석 구조입니다. mihomo는 nameserver-policy, proxy-server-nameserver, direct-nameserver 등 세분화된 필드도 지원하므로 도메인 규칙이나 프록시 노드 해석 목적에 따라 서로 다른 업스트림을 선택할 수 있습니다.

“DNS를 여러 개 적었다”고 해서 모든 요청이 항상 모든 응답을 동시에 사용하는 것은 아닙니다. 코어는 필드의 의미, 필터 조건과 응답 결과에 따라 해석 경로를 선택합니다. 도메인은 해석되지만 웹사이트가 열리지 않는다면 DNS 로그, 규칙 매칭과 노드 연결을 함께 확인해야 하며 브라우저 오류만으로 판단해서는 안 됩니다.

fake-ip과 redir-host

proxies: 개별 프록시 노드 필드

proxies에는 직접 정의한 노드를 저장합니다. 구독에서는 보통 이 섹션이 자동으로 생성됩니다. 프로토콜마다 필드는 다르지만, 각 노드에는 최소한 고유 이름, 프로토콜 유형, 서버 주소와 포트가 필요합니다.

proxies:
  - name: "SS-HK-01"
    type: ss
    server: hk.example.net
    port: 443
    cipher: aes-128-gcm
    password: "example-password"
    udp: true

  - name: "VMess-JP-01"
    type: vmess
    server: jp.example.net
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    alterId: 0
    cipher: auto
    tls: true
    servername: jp.example.net
    network: ws
    ws-opts:
      path: /gateway
      headers:
        Host: jp.example.net

공통 필드와 프로토콜별 필드

노드가 목록에 표시된다는 것은 YAML이 파싱되었다는 뜻일 뿐, 연결 매개변수가 올바르다는 의미는 아닙니다. 인증 정보 오류는 핸드셰이크 실패로 나타나는 경우가 많고, 서버 주소를 해석할 수 없으면 DNS 오류가 표시됩니다. WebSocket 경로 또는 Host가 일치하지 않으면 대개 연결 직후 끊깁니다. 진단할 때는 클라이언트에서 ‘로그’를 열고 수준을 일시적으로 debug로 바꾼 다음, 특정 노드 하나를 대상으로 지연 시간을 테스트하세요.

proxy-providers와 proxy-groups

노드 제공자 proxy-providers

proxy-providers를 사용하면 로컬 파일이나 원격 주소에서 노드 묶음을 불러올 수 있습니다. 모든 노드를 proxies에 직접 작성하는 것보다 노드 출처와 정책 그룹 구조를 분리해 관리하기에 적합합니다.

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

interval: 3600은 3600초마다 한 번 업데이트를 확인한다는 뜻입니다. 상태 검사에서 interval: 600은 10분마다 테스트를 실행합니다. 제공자 다운로드에 실패하면 구독 주소의 접근 가능 여부, 시스템 시간, 프록시 시작 단계의 순환 의존 여부와 저장 경로의 쓰기 권한을 확인하세요.

정책 그룹 유형과 참조

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

tolerance: 80은 지연 시간 차이가 80밀리초 이내라면 자동 선택 그룹이 자주 전환하지 않도록 합니다. 값이 너무 작으면 가벼운 네트워크 변동에도 노드가 반복해서 바뀔 수 있고, 너무 크면 눈에 띄게 느려진 노드를 계속 유지할 수 있습니다. 가정용 광대역에서는 50~100밀리초부터 조정해 보세요.

rules와 rule-providers: 트래픽 분기의 매칭 순서

rules는 연결을 어느 정책 그룹으로 보낼지 결정합니다. 규칙은 위에서 아래로 매칭되며 첫 번째 규칙이 일치하면 검사를 멈춥니다. 따라서 구체적인 규칙일수록 앞에 두고, 최종 대체 규칙은 마지막에 배치하는 것이 일반적입니다.

rules:
  - DOMAIN,api.example.com,노드 선택
  - DOMAIN-SUFFIX,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
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

자주 사용하는 규칙 유형

no-resolve는 일부 IP 규칙이 매칭을 위해 추가 도메인 해석을 수행하지 않도록 합니다. 모든 규칙에 필요한 공통 접미사는 아닙니다. MATCH를 첫 줄에 두면 뒤의 규칙은 절대 매칭될 수 없습니다. 존재하지 않는 정책 그룹을 규칙에서 참조하면 로드 시 즉시 오류가 나거나, 연결 처리 중 정책을 찾을 수 없다는 메시지가 표시될 수 있습니다.

규칙 제공자 rule-providers

rule-providers:
  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    url: "https://example.com/rules/private-network.yaml"
    path: ./ruleset/private-network.yaml
    interval: 86400

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,노드 선택

behavior는 규칙 세트의 내용과 일치해야 하며, 일반적인 값으로 domain, ipcidr, classical이 있습니다. 도메인 규칙 세트를 ipcidr로 선언하면 내용을 올바르게 파싱할 수 없습니다. mihomo의 규칙 세트에는 format도 관련되므로 원격 파일이 YAML, 텍스트 또는 바이너리 형식일 때 해당 값을 반드시 지정해야 합니다.

TUN 섹션과 투명 프록시 매개변수

TUN 모드는 가상 네트워크 인터페이스를 만들어 별도의 프록시 설정이 없는 애플리케이션의 트래픽을 가로챕니다. 시스템 프록시와는 다른 진입점입니다. mihomo에서 흔히 사용하는 설정은 다음과 같습니다.

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

TUN을 켠 뒤 ‘브라우저는 열리지만 게임이 인터넷에 연결되지 않음’ 또는 ‘LAN 기기에 접근할 수 없음’ 문제가 발생하면 실행 권한, 라우팅 테이블, DNS 가로채기, LAN 대역의 직접 연결 규칙과 다른 VPN을 차례로 확인하세요. 기본 라우트를 만드는 네트워크 도구를 여러 개 동시에 켜지 마세요. Windows에서는 route print를 실행해 기본 라우트와 인터페이스 우선순위도 확인할 수 있습니다.

읽기 쉬운 최소 설정과 문제 해결 절차

다음 구조는 실제 인증 정보는 생략했지만 진입점부터 규칙까지의 전체 참조 흐름은 유지합니다. 설정을 확인할 때는 마지막 줄의 정책 그룹에서 역으로 추적할 수 있습니다. 규칙은 ‘노드 선택’을 참조하고, ‘노드 선택’은 ‘예시 노드’를 참조하며, ‘예시 노드’에는 서버 매개변수가 들어 있습니다.

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

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

proxies:
  - name: "예시 노드"
    type: ss
    server: 203.0.113.10
    port: 443
    cipher: aes-128-gcm
    password: "replace-with-valid-password"
    udp: true

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

rules:
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

오류 유형별 단계적 점검

  1. 파일을 불러올 수 없음: 먼저 Tab, 들여쓰기, 콜론, 따옴표와 중복 키를 확인하세요. 이 단계에서는 코어가 설정을 아직 읽지 못했으므로 노드 테스트를 먼저 해서는 안 됩니다.
  2. 설정은 로드되지만 정책 그룹이 비어 있음: proxies에 노드가 있는지, use의 제공자 이름이 올바른지, provider 파일이 정상적으로 다운로드되었는지 확인하세요.
  3. 노드 테스트 실패: server, port, 인증 필드, TLS 이름과 전송 매개변수를 확인한 뒤 서버 도메인을 해석할 수 있는지도 점검하세요.
  4. 일부 웹사이트만 열리지 않음: 연결 로그에서 매칭된 규칙, 대상 도메인, 정책 그룹과 실제 노드를 확인하고, 규칙 순서 때문에 트래픽이 너무 일찍 DIRECT 또는 REJECT로 전달되지 않았는지 점검하세요.
  5. 시스템 프록시는 작동하지만 다른 프로그램이 프록시를 사용하지 않음: 해당 프로그램이 시스템 프록시를 따르는지 확인하세요. 따르지 않는 경우에만 TUN을 검토하고, 넓은 범위의 규칙을 반복해서 추가해 진입점 문제를 가리지 마세요.
  6. 구독 업데이트 후 변경 사항이 사라짐: 로컬 DNS, TUN 또는 규칙 변경을 클라이언트가 지원하는 오버라이드나 병합 설정으로 옮기세요.

필드 호환성과 유지 관리 권장 사항

Clash for Windows 0.20.39에서 사용하는 Clash 코어 설정은 계속 업데이트되는 mihomo 설정과 완전히 동일하지 않습니다. 최신 구독에는 이전 코어가 인식하지 못하는 프로토콜, 규칙 세트 형식 또는 DNS 필드가 포함될 수 있습니다. field not found, unsupported proxy type와 같은 오류가 발생하면 화면에 표시된 이름만 보지 말고 클라이언트가 실제로 호출하는 코어와 버전을 먼저 확인하세요.

일상적인 유지 관리에서는 설정을 세 종류로 나누는 것이 좋습니다. 구독은 노드를, 규칙 제공자는 업데이트 가능한 규칙 세트를, 로컬 오버라이드는 포트, DNS와 TUN을 담당하도록 구성합니다. 이렇게 하면 수동 병합을 줄이고 문제를 명확한 영역에 한정할 수 있습니다. 수정할 때마다 한 가지 주제만 변경하세요. 예를 들어 먼저 DNS를 수정하고 다시 로드한 뒤 해석이 정상인지 확인하고 TUN을 활성화합니다.

설정 파일의 핵심 관계는 복잡하지 않습니다. 인바운드 포트가 트래픽을 받고, DNS가 도메인 정보를 제공하며, 규칙이 정책 그룹을 결정하고, 정책 그룹이 노드를 선택하고, 노드가 원격 연결을 수립합니다. 이 흐름을 따라 점검하는 편이 노드를 계속 바꾸거나 YAML 전체를 한 번에 교체하는 것보다 특정 필드를 찾기 쉽습니다.

클라이언트 다운로드 보기