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

Clash 설정 파일 구조 해설: 포트·DNS부터 규칙 섹션까지

YAML 계층별로 자주 쓰는 필드를 분석하고, 프록시 노드·정책 그룹·규칙 간 참조 관계를 설명합니다.

먼저 Clash 설정의 처리 흐름을 이해하기

Clash, Clash Meta(현재는 보통 Mihomo라고 부름) 및 그래픽 클라이언트는 일반적으로 YAML 파일로 실행 매개변수를 정의합니다. 설정은 서로 독립된 여러 필드처럼 보이지만, 실제 실행 시에는 하나의 연속된 흐름으로 처리됩니다. 애플리케이션 트래픽이 먼저 로컬 리스닝 포트나 TUN 네트워크 인터페이스로 들어오고, 도메인 요청은 DNS 모듈에서 처리됩니다. 이후 연결은 rules를 위에서 아래로 순서대로 검사하며, 일치한 규칙이 연결을 정책 그룹에 전달하고 정책 그룹이 구체적인 프록시 노드, 직접 연결 또는 차단 동작을 선택합니다.

따라서 설정을 읽을 때 특정 노드의 연결 가능 여부만 확인해서는 안 됩니다. 완전한 설정이라면 최소한 다음 다섯 가지 질문에 답할 수 있어야 합니다. 트래픽은 어디로 들어오는가, 도메인은 어떻게 조회되는가, 사용할 수 있는 출구는 무엇인가, 출구는 어떻게 정책 그룹으로 구성되는가, 연결은 최종적으로 어떤 규칙에 의해 배정되는가. 어느 한 단계에서든 이름 참조가 잘못되면 설정 로드 실패, 빈 정책 그룹, 도메인 조회 실패 또는 잘못된 출구로의 연결처럼 나타날 수 있습니다.

YAML은 들여쓰기에 민감합니다. 일반적으로 한 단계에 공백 두 칸을 사용하며, 공백 대신 탭을 사용할 수 없습니다. 같은 계층의 키는 정렬을 유지해야 하고, 목록 항목은 하이픈으로 시작합니다. 불리언 값은 true와 false를 사용하는 것이 좋습니다. 콜론, 샵, 별표 또는 특수 기호가 포함된 이름은 파서가 YAML 문법으로 해석하지 않도록 따옴표로 감싸야 합니다.

기본 필드와 로컬 리스닝 포트

설정 파일 최상위에는 보통 포트, LAN 접근 허용, 실행 모드, 로그 수준을 먼저 배치합니다. 이 필드들은 Clash가 로컬 컴퓨터나 LAN 기기의 연결을 어떻게 수신할지 결정하지만, 연결이 어떤 프록시 노드를 사용할지는 직접 결정하지 않습니다.

mixed-port: 7890
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, socks-port 및 mixed-port

port는 HTTP 프록시 리스닝 포트를 제공하고, socks-port는 SOCKS5 프록시 리스닝 포트를 제공합니다. mixed-port는 하나의 포트에서 HTTP와 SOCKS5 요청을 모두 받을 수 있게 합니다. 데스크톱 클라이언트는 시스템 프록시 설정을 단순화하기 위해 혼합 포트를 자주 사용합니다. 여러 포트를 동시에 선언했다면 포트 번호가 다른 프로그램에서 사용 중인지 확인하고, 시스템 프록시가 실제로 어느 포트를 가리키는지 점검해야 합니다.

redir-port와 tproxy-port는 주로 투명 프록시 환경에서 사용됩니다. 운영체제 네트워크 스택, 라우팅 규칙, 권한 설정이 필요하며 모든 플랫폼이 동일한 방식으로 지원하는 것은 아닙니다. 일반적인 데스크톱 사용자가 시스템 프록시나 클라이언트의 TUN 기능으로 트래픽을 가로채는 경우에는 보통 이 두 필드를 직접 추가할 필요가 없습니다.

LAN 접근과 제어 인터페이스

allow-lan은 다른 기기가 이 컴퓨터의 리스닝 포트를 통해 프록시를 사용할 수 있는지 제어합니다. 활성화한 뒤에는 bind-address, 운영체제 방화벽, 기기 간 네트워크 연결 상태도 확인해야 합니다. 이 컴퓨터에서만 사용할 때는 비활성 상태로 두어도 됩니다. 같은 LAN의 휴대폰이나 태블릿에 프록시를 제공해야 한다면 신뢰할 수 있는 네트워크 범위를 제한하고, 리스닝 포트가 공용 인터넷에 노출되지 않도록 해야 합니다.

external-controller는 제어 인터페이스 주소입니다. 그래픽 UI나 외부 패널이 이를 통해 연결, 트래픽, 정책 그룹 상태를 조회할 수 있습니다. 127.0.0.1에서 수신하면 로컬 컴퓨터에서만 접근할 수 있습니다. LAN 주소로 변경할 경우에는 충분히 강력한 secret을 함께 설정하고 네트워크 접근 범위도 제한해야 합니다. 제어 인터페이스 포트와 프록시 포트는 용도가 다르므로 시스템 프록시를 제어 인터페이스로 지정해서는 안 됩니다.

실행 모드와 로그

mode: rule은 규칙에 따라 트래픽을 분배하는 모드로, 일상적인 설정에서 가장 널리 사용됩니다. global 모드는 모든 연결을 전역 정책으로 전달하고, direct 모드는 연결을 직접 전송합니다. 그래픽 클라이언트의 ‘규칙, 전역, 직접 연결’ 전환은 현재 실행 모드를 바꾸는 경우가 많지만, 원본 YAML 파일을 반드시 수정하는 것은 아닙니다.

log-level은 silent, error, warning, info, debug 등의 수준으로 설정할 수 있으며, 지원되는 값은 사용 중인 코어 버전에 따라 다릅니다. 규칙 매칭이나 DNS 요청을 점검할 때는 일시적으로 로그 상세도를 높이고, 문제가 확인되면 일반 수준으로 되돌리는 것이 좋습니다. 로그가 지나치게 많으면 확인이 어려워질 수 있습니다.

DNS 섹션: 조회 경로와 Fake IP

dns 섹션은 Clash가 도메인 조회를 가로챌지, 어떤 상위 DNS 서버에 질의할지, 실제 주소 또는 Fake IP를 반환할지를 결정합니다. DNS 설정은 프록시 규칙과 밀접하게 연결됩니다. 규칙은 매칭을 위해 도메인 자체가 필요할 수 있고, 프록시 노드의 서버 주소도 먼저 조회해야 할 수 있습니다. 상위 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"
    - "localhost.ptlogin2.qq.com"
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://1.1.1.1/dns-query
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query

enable, listen 및 상위 DNS 서버

enable: true는 코어의 DNS 모듈을 활성화합니다. listen은 DNS 서비스의 리스닝 주소를 지정하며, 입력이 필요한지는 클라이언트가 조회를 가로채는 방식에 따라 달라집니다. 일부 그래픽 클라이언트는 이 항목을 자동으로 생성하거나 덮어씁니다. 로컬 컴퓨터가 아닌 주소에서 수신하도록 설정하기 전에는 LAN DNS 노출로 접근 범위가 어떻게 바뀌는지 먼저 이해해야 합니다.

default-nameserver는 주로 DoH, DoT 등 암호화된 DNS 서버 자체의 도메인을 조회하는 데 사용되며, 프록시 노드 도메인의 초기 조회에도 관여할 수 있습니다. 따라서 일반적으로 직접 접근할 수 있는 IP 주소 형식의 DNS를 입력합니다. nameserver는 일반 조회에 사용하는 주요 상위 서버로, 일반 DNS 주소나 코어가 지원하는 암호화 DNS 형식을 사용할 수 있습니다. Mihomo 버전에 따라 확장 매개변수와 프로토콜 표기 지원이 다를 수 있으므로 설정을 옮길 때는 코어 문서와 시작 로그를 확인해야 합니다.

nameserver-policy를 사용하면 도메인이나 규칙 집합별로 DNS 상위 서버를 지정할 수 있습니다. 예를 들어 특정 도메인에 지정한 조회 서비스를 사용하게 만들 수 있습니다. 이는 ‘어느 DNS에 질의할지’를 정하는 기능이며, 프록시 규칙에서 ‘어느 출구로 연결할지’를 정하는 것과는 다릅니다. DNS 조회 경로와 이후 연결 경로는 별도로 설정해야 합니다.

fake-ip와 redir-host

Fake IP 모드는 먼저 애플리케이션에 예약 주소 대역의 임시 주소를 반환하고, 애플리케이션이 연결을 시작할 때 해당 주소를 원래 도메인으로 매핑합니다. 이를 통해 코어가 도메인 정보를 더 안정적으로 유지할 수 있어 DOMAIN, DOMAIN-SUFFIX, GeoSite 같은 도메인 규칙을 적용하기 쉽습니다. TUN 환경에서는 여러 애플리케이션의 DNS와 연결을 일관되게 가로채기 위해 Fake IP를 자주 사용합니다.

일부 LAN 서비스, 게임 플랫폼, 프린터 및 실제 DNS 결과에 의존하는 애플리케이션은 Fake IP와 맞지 않을 수 있습니다. 이러한 도메인은 fake-ip-filter에 추가해 실제 조회 결과를 반환하도록 할 수 있습니다. 필터 범위를 무작정 넓히면 많은 도메인이 Fake IP 매핑을 우회해 도메인 규칙의 관찰 가능성이 낮아지므로 주의해야 합니다. redir-host 모드는 실제 IP를 반환해 호환 방식이 더 단순하지만, 규칙 매칭 결과는 DNS 캐시, 연결 방식, 애플리케이션 동작의 영향을 받습니다.

프록시 노드와 프록시 제공자

proxies는 정책 그룹에서 참조할 수 있는 정적 노드 목록입니다. 각 항목에는 노드 이름, 프로토콜 유형, 서버 주소, 서버 포트, 인증 매개변수 등이 포함됩니다. 프로토콜마다 필요한 필드가 다르므로 type만 바꿔 한 종류의 노드를 다른 종류로 변환할 수는 없습니다.

proxies:
  - name: "예시 노드 A"
    type: socks5
    server: 192.0.2.10
    port: 1080
    username: "example-user"
    password: "example-password"
    udp: true

name은 설정 내부에서 노드를 참조하는 식별자입니다. 정책 그룹의 이름은 공백, 대소문자, 기호를 포함해 이 값과 완전히 일치해야 합니다. 노드 이름이 중복되면 코어나 클라이언트에 따라 로드를 거부하거나 참조 결과를 판단하기 어려워질 수 있으므로 고유하게 유지해야 합니다.

구독에는 보통 많은 노드가 포함되어 있어 이를 proxies에 직접 펼치면 관리가 어렵습니다. Mihomo는 proxy-providers를 통해 프록시 제공자를 정의할 수 있으며, 제공자가 로컬 파일이나 원격 콘텐츠를 읽은 뒤 노드 집합을 정책 그룹에 전달합니다. 제공자에는 보통 type, url, path, 업데이트 간격, 헬스 체크 등의 필드가 포함됩니다. 구독 주소는 접근 자격 증명에 해당하므로 공개 저장소, 스크린샷, 공개 로그에 기록하지 않는 것이 좋습니다.

proxy-providers:
  provider-main:
    type: http
    url: "구독 서비스가 제공하는 전체 주소"
    path: ./providers/provider-main.yaml
    interval: 86400
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

제공자의 헬스 체크는 주기적으로 노드 연결 상태를 테스트하는 기능이며, 정책 그룹이 자동으로 지연 시간이 가장 짧은 노드를 선택한다는 뜻은 아닙니다. 자동 선택 여부는 정책 그룹 유형이 결정합니다. 헬스 체크 주소 역시 대상 주소의 응답 상태만 반영합니다. 지연 시간은 대상 서버, DNS, 네트워크 혼잡, 노드 출구 위치의 영향을 받을 수 있습니다.

정책 그룹: 참조 가능한 출구로 노드 구성하기

proxy-groups는 노드와 규칙 사이에 위치합니다. 규칙은 자주 바뀌는 특정 노드에 직접 연결하지 않고 안정적인 정책 그룹 이름을 참조하는 것이 일반적입니다. 이렇게 구성하면 노드가 업데이트되거나 작동하지 않을 때 전체 규칙을 다시 작성하지 않고 클라이언트에서 그룹 내 선택지만 바꿀 수 있습니다.

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

  - name: "자동 속도 측정"
    type: url-test
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80

  - name: "기본 출구"
    type: select
    proxies:
      - "노드 선택"
      - "자동 속도 측정"
      - DIRECT

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

  • select: 사용자가 그룹 내 노드, 다른 정책 그룹 또는 내장 동작을 직접 선택합니다. 기본 진입점이나 고정 출구가 필요한 서비스에 적합합니다.
  • url-test: 지정한 테스트 주소를 주기적으로 측정하고 조건에 맞는 지연 시간이 낮은 노드를 자동으로 선택합니다. 탐지 결과를 기준으로 하므로 모든 업무 연결의 속도가 같다는 의미는 아닙니다.
  • fallback: 목록에서 사용 가능한 앞쪽 노드를 우선 사용하고, 현재 노드를 사용할 수 없으면 다음 노드로 전환합니다. 고정된 우선순위를 중시하는 환경에 적합합니다.
  • load-balance: 코어가 지원하는 방식에 따라 연결을 여러 노드에 분산합니다. 하나의 TCP 연결 대역폭을 단순히 합산하는 기능은 아니며, 출구가 자주 바뀌면 세션이나 주소 일관성에 의존하는 서비스에 영향을 줄 수 있습니다.

proxies에는 정적 노드, 다른 정책 그룹, DIRECT, REJECT 등의 내장 동작을 나열합니다. use는 proxy-providers를 참조할 때 사용합니다. 필요에 따라 두 항목을 하나의 정책 그룹에서 함께 구성할 수 있습니다. 정책 그룹이 다른 정책 그룹을 참조하는 것도 가능하지만, A가 B를 참조하고 B가 다시 A를 참조하는 순환 참조는 피해야 합니다. 이 경우 설정 검증이 실패합니다.

그룹 이름 역시 엄격하게 참조됩니다. 규칙에 기본 출구가 적혀 있다면 설정 안에 동일한 이름의 정책 그룹, 노드 또는 내장 정책이 반드시 있어야 합니다. 정책 그룹 이름을 바꾼 뒤에는 rules, 다른 정책 그룹, 오버라이드 스크립트에 남은 참조도 함께 검색해 수정해야 합니다.

규칙 섹션: 순차 매칭이 최종 출구를 결정합니다

rules는 연결 분배를 결정하는 표입니다. 코어는 일반적으로 첫 번째 규칙부터 아래로 확인하며, 일치하면 이후 매칭을 중단하고 규칙 끝에 지정된 정책으로 연결을 전달합니다. 따라서 규칙은 개수보다 순서가 중요합니다. 범위가 좁고 우선순위가 높은 규칙은 앞에, 일반 규칙과 최종 대체 규칙은 뒤에 배치해야 합니다.

rules:
  - DOMAIN,example.org,DIRECT
  - DOMAIN-SUFFIX,example.com,노드 선택
  - DOMAIN-KEYWORD,service,기본 출구
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,기본 출구

자주 사용하는 규칙 유형

DOMAIN은 전체 도메인을 정확히 매칭하고, DOMAIN-SUFFIX는 지정한 도메인과 하위 도메인을 매칭합니다. DOMAIN-KEYWORD는 도메인에 포함된 키워드로 매칭하므로 범위가 더 넓으며, 오탐을 방지해야 합니다. IP-CIDR과 IP-CIDR6은 대상 IP 대역으로 매칭하며 LAN, 고정 서비스 주소, 명확한 네트워크 범위에 적합합니다.

GEOIP는 IP 지리 데이터베이스를 기준으로 대상 주소를 매칭합니다. Mihomo는 GeoSite 또는 규칙 집합을 사용해 대량의 도메인을 처리할 수도 있으며, 구체적인 규칙 유형과 데이터베이스 형식은 코어 버전과 설정 방식에 따라 달라집니다. 지리 규칙은 로컬 데이터베이스에 의존하므로 데이터베이스가 없거나 경로가 잘못되었거나 형식이 호환되지 않으면 로드 단계 또는 실행 로그에 안내가 표시됩니다.

no-resolve는 IP 유형 규칙에서 주로 사용되며, 해당 규칙을 매칭할 때 도메인에 대한 추가 DNS 조회를 실행하지 않는다는 뜻입니다. 불필요한 조회를 줄일 수 있지만, 현재 연결에 도메인만 있고 매칭에 사용할 대상 IP가 없다면 이 IP 규칙이 적용되지 않을 수 있습니다. 추가 여부는 DNS 모드와 규칙 목적에 따라 판단해야 합니다.

MATCH는 최종 대체 규칙이므로 규칙 목록의 마지막에 배치해야 합니다. 앞선 규칙에 매칭되지 않은 연결을 처리합니다. 적절한 대체 규칙이 없으면 코어 버전이나 클라이언트 생성 방식에 따라 예측하기 어려운 결과가 발생할 수 있습니다. 직접 작성하는 설정에서는 MATCH를 명시해 기본 출구를 분명히 하는 것이 좋습니다.

규칙 제공자와 대규모 규칙 집합

규칙이 많을 때는 rule-providers를 사용해 규칙 집합을 별도 파일로 분리한 뒤 RULE-SET으로 참조할 수 있습니다. 규칙 제공자는 일반적으로 동작 유형, 출처, 저장 경로, 업데이트 간격, 형식을 선언합니다. 참조 이름은 제공자 키 이름과 일치해야 하며, 규칙 집합의 콘텐츠 형식도 behavior와 호환되어야 합니다.

rule-providers:
  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    path: ./rules/private-network.yaml
    url: "규칙 유지 관리자가 제공하는 전체 주소"
    interval: 86400

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,기본 출구

규칙 집합 업데이트가 성공했다고 해서 순서가 반드시 올바른 것은 아닙니다. RULE-SET 앞에 범위가 더 넓은 규칙을 배치했다면 연결이 먼저 매칭되어 뒤의 규칙 집합이 적용되지 않을 수 있습니다. 문제를 점검할 때는 규칙 파일이 다운로드되었는지만 확인하지 말고 연결 상세 정보에서 규칙 유형, 매칭된 내용, 최종 정책을 확인해야 합니다.

TUN 모드와 트래픽 진입점의 관계

시스템 프록시는 운영체제의 프록시 설정을 따르는 프로그램에만 영향을 줍니다. 터미널 도구, 게임, 가상 머신 또는 자체 네트워크 스택을 구현한 애플리케이션은 시스템 프록시를 무시할 수 있습니다. TUN 모드는 가상 네트워크 인터페이스를 통해 더 넓은 범위의 IP 트래픽을 가로챈 뒤 연결을 Clash의 DNS, 규칙, 정책 처리 경로로 전달합니다.

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

auto-route는 코어가 라우팅을 자동으로 설정하도록 하고, auto-detect-interface는 기본 아웃바운드 인터페이스를 식별합니다. dns-hijack은 지정한 DNS 트래픽을 코어가 처리하도록 전달합니다. stack의 선택 값과 기본 동작은 코어 및 플랫폼에 따라 달라지며, 일반적인 구현으로 system, gVisor, mixed가 있습니다. 그래픽 클라이언트는 보통 운영체제에 맞는 기본값을 제공하므로 호환성 문제를 확인하는 경우가 아니라면 자주 변경할 필요가 없습니다.

TUN 시작에 실패하면 클라이언트 권한, 가상 네트워크 인터페이스 상태, 다른 VPN 또는 네트워크 필터링 소프트웨어, 라우팅 테이블, DNS 가로채기 충돌을 차례로 확인해야 합니다. TUN이 활성화되었는데도 일부 애플리케이션이 직접 연결된다면 라우팅 제외 항목, 인터페이스 선택, 애플리케이션 자체의 독립 VPN 사용 여부도 점검해야 합니다. TUN은 트래픽을 코어로 전달할 뿐이며, 최종적으로 직접 연결할지 프록시를 사용할지는 규칙과 정책 그룹이 결정합니다.

설정 로드 실패와 규칙 미적용 점검 순서

  1. 먼저 YAML 문법을 확인합니다. 들여쓰기, 콜론 뒤 공백, 목록 하이픈, 따옴표의 닫힘 여부를 확인하세요. 파서가 표시한 줄 번호는 오류가 발견된 위치일 뿐이며, 실제 문제는 앞선 몇 줄에 있을 수도 있습니다.
  2. 다음으로 이름 참조를 확인합니다. 규칙 끝의 정책 이름, 정책 그룹의 노드 이름, use가 참조하는 프록시 제공자, RULE-SET이 참조하는 규칙 제공자를 대조하세요.
  3. 원격 리소스 상태를 확인합니다. 구독, 프록시 제공자, 규칙 제공자가 정상적으로 업데이트되었는지, 저장 디렉터리에 쓰기 권한이 있는지, 원격 콘텐츠가 코어가 요구하는 형식인지 확인하세요.
  4. 트래픽 진입점을 점검합니다. 시스템 프록시 포트는 현재 리스닝 포트와 일치해야 합니다. TUN을 사용할 때는 가상 네트워크 인터페이스와 라우팅이 생성되었는지 확인하고, LAN 기기는 리스닝 주소와 방화벽도 점검해야 합니다.
  5. DNS와 규칙 로그를 확인합니다. 먼저 도메인이 정상적으로 조회되었는지 판단한 다음, 연결이 어떤 규칙에 매칭되었는지, 어느 정책 그룹으로 들어갔는지, 최종적으로 어떤 노드가 선택되었는지 확인하세요.
  6. 설정 범위를 줄입니다. 복잡한 설정은 일시적으로 사용 가능한 노드 하나, 수동 정책 그룹 하나, 소수의 규칙만 남겨 기본 흐름을 검증한 뒤 DNS 정책, 규칙 집합, 자동 속도 측정을 단계별로 복원하는 것이 좋습니다.

유지 관리하기 쉬운 Clash 설정은 참조 관계가 명확해야 합니다. 포트와 TUN은 트래픽을 받고, DNS는 도메인을 조회하며, 노드와 프록시 제공자는 출구를 제공하고, 정책 그룹은 출구를 구성하며, 규칙은 정책을 선택합니다. 설정을 수정할 때 이 흐름을 따라 단계별로 검증하면 코어, 구독, DNS, 규칙 집합을 한꺼번에 바꾸는 것보다 문제를 쉽게 찾을 수 있습니다.

Clash 다운로드