Clash 설정 파일
필드 레퍼런스

01 · DOCUMENT MODEL

YAML 구조와 설정 로드 순서

최상위 필드는 실행 단계가 아닙니다

Clash 설정 파일은 보통 config.yaml이라는 이름을 사용하며, 여러 최상위 키로 구성됩니다. 대표적인 최상위 항목은 포트, 실행 모드, DNS, 프록시 노드, 프록시 그룹, 규칙 및 외부 Provider입니다. 파일에서의 순서는 주로 가독성을 위한 것이며, 커널이 작성 순서대로 한 줄씩 실행한다는 뜻은 아닙니다. 파서는 먼저 전체 YAML을 읽어 설정 객체를 만든 다음 프록시 그룹 참조, 규칙 대상, Provider 정의를 검증합니다. 따라서 rules를 proxies보다 앞에 작성해도 반드시 오류가 발생하는 것은 아니지만, 사람이 점검하기는 훨씬 어려워집니다. “기본 실행 매개변수 → DNS → 노드 → 프록시 그룹 → Provider → 규칙” 순서로 구성하는 것이 좋습니다.

YAML은 들여쓰기로 부모와 자식 계층을 표현하며, 공백 대신 탭을 사용할 수 없습니다. 같은 계층은 동일한 들여쓰기 폭을 유지해야 하며 일반적으로 공백 두 칸을 사용합니다. 목록 항목은 하이픈으로 시작하고, 하이픈 뒤의 객체도 들여쓰기 규칙을 따라야 합니다. 문자열은 대부분 따옴표 없이 쓸 수 있지만 값에 콜론, 샵, 중괄호, 앞뒤 공백이 포함되거나 불리언으로 인식될 수 있는 단어가 들어가면 따옴표를 사용하는 편이 안전합니다. 예를 들어 노드 이름을 "HK: Premium"으로 작성하면 콜론이 키와 값의 구분자로 해석되는 것을 막을 수 있습니다. 비밀번호에 #이 포함된 경우에도 따옴표를 사용해야 합니다. 그렇지 않으면 샵 뒤의 내용이 주석으로 처리될 수 있습니다.

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

dns:
  enable: true
  enhanced-mode: fake-ip

proxies:
  - name: "Example-SS"
    type: ss
    server: 203.0.113.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "Example-SS"
      - DIRECT

rules:
  - MATCH,노드 선택

스칼라, 목록, 매핑의 차이

mode: rule은 스칼라이고, rules 아래의 여러 줄 항목은 목록이며, dns 아래의 여러 키-값 쌍은 매핑입니다. 설정 오류는 이 세 구조를 혼동해서 발생하는 경우가 많습니다. 예를 들어 nameserver는 목록을 요구하므로 하이픈 없는 단일 문자열로 작성하면 일부 커널이 로드를 거부할 수 있습니다. proxy-groups는 객체 목록이며 각 프록시 그룹에 자체 name과 type이 필요합니다. “필드 유형이 올바르지 않음” 오류가 발생하면 필드 철자뿐 아니라 해당 값이 문자열, 숫자, 불리언, 목록, 객체 중 무엇이어야 하는지도 확인하세요.

YAML의 true와 false에는 따옴표를 붙이지 않아야 합니다. 불리언과 문자열은 의미가 다르기 때문입니다. 포트는 보통 숫자로 작성합니다. 도메인, 노드 이름, 정규식, 비밀번호는 문자열로 처리하는 것이 적합합니다. 빈 값도 주의해야 합니다. 키만 있고 값이 없는 상태는 빈 목록과 같지 않습니다. 특정 항목을 명시적으로 비우려면 오버라이드 시스템에서 대상 필드 유형에 따라 [] 또는 {}를 요구할 수 있습니다.

참조 관계와 최종 설정

프록시 그룹은 이름으로 노드나 다른 프록시 그룹을 참조하고, 규칙 끝에서는 다시 프록시 그룹 이름을 참조합니다. 이름은 정확히 일치해야 하며 공백, 대소문자, 전각 기호도 이름의 일부입니다. 규칙이 DOMAIN-SUFFIX,example.com,해외 노드로 작성되어 있는데 실제 프록시 그룹 이름이 “외부 노드”라면 커널은 두 이름이 같다고 추론하지 못합니다. 구독 업데이트로 노드 이름이 바뀌면 직접 작성한 프록시 그룹의 참조 대상이 사라질 수도 있습니다.

그래픽 클라이언트에 표시되는 설정이 커널이 최종적으로 읽는 내용과 항상 같은 것은 아닙니다. 구독 원문은 클라이언트의 전역 오버라이드, 스크립트 처리, 프록시 그룹 생성, 필드 호환 변환을 거쳐 실행 시점의 설정으로 만들어질 수 있습니다. 문제를 조사할 때는 구독 편집기만 보지 말고 “최종 설정 보기”, “실행 설정” 또는 로그의 로드 경로를 우선 확인하세요. 클라이언트에 설정 문법 검사가 있다면 먼저 파싱 오류를 해결한 뒤 규칙과 네트워크 동작을 관찰해야 합니다. 들여쓰기 하나가 잘못되면 파일 전체가 로드되지 않으므로 이후 네트워크 테스트는 참고할 가치가 없습니다.

02 · RUNTIME

포트, 모드 및 공통 필드

인바운드 포트의 역할 구분

port는 HTTP 프록시 포트이고, socks-port는 SOCKS5 프록시 포트입니다. mixed-port는 하나의 포트에서 HTTP와 SOCKS5 요청을 모두 받을 수 있습니다. 데스크톱 클라이언트는 보통 혼합 포트 하나만 활성화하면 시스템 프록시와 명령줄 도구가 같은 진입점을 공유할 수 있습니다. 여러 필드에 같은 포트를 지정하거나 다른 프록시 프로그램, 개발 서버, 이미 실행 중인 Clash 인스턴스와 포트를 겹치게 하지 마세요. 포트 충돌이 발생하면 클라이언트에는 설정이 가져와진 것으로 표시될 수 있지만, 로그에는 리스닝 실패가 나타나고 시스템 프록시는 정상 작동하지 않는 진입점을 가리키게 됩니다.

redir-port, tproxy-port와 TUN 인바운드는 투명 프록시 환경을 위한 것으로, 주로 라우터, Linux 게이트웨이 또는 클라이언트가 자동으로 관리합니다. 일반적인 macOS 및 Windows 사용자는 “더 폭넓게 적용”하기 위해 모든 포트를 수동으로 동시에 활성화할 필요가 없습니다. 시스템 프록시 모드는 시스템 프록시 설정을 따르는 앱의 트래픽을 처리하고, TUN 모드는 가상 네트워크 인터페이스를 통해 더 넓은 범위의 트래픽을 인계받습니다. 플랫폼 기능에 따라 클라이언트에서 두 모드를 설정할 수 있지만 포트 필드만으로 TUN 드라이버와 라우팅 설정을 대신할 수는 없습니다.

allow-lan과 리스닝 범위

allow-lan: true는 로컬 네트워크 접근을 허용한다는 뜻이지만, 다른 기기에서 실제로 연결할 수 있는지는 bind-address, 운영체제 방화벽, 네트워크 인터페이스, 라우터의 클라이언트 격리 정책에 따라 달라집니다. 로컬 기기에서만 사용할 때는 끄는 편이 노출 범위를 관리하기 쉽습니다. 공유가 필요하다면 현재 네트워크를 신뢰할 수 있는지 확인하고 외부 제어 인터페이스에 인증을 설정하세요. 프록시 인바운드와 제어 인터페이스는 서로 다른 서비스입니다. 프록시 포트를 연다고 해서 제어 API까지 로컬 네트워크에 공개해야 하는 것은 아닙니다.

external-controller는 127.0.0.1:9090과 같은 외부 제어 인터페이스를 정의합니다. 그래픽 패널은 이를 통해 연결 정보를 읽고, 프록시 그룹을 전환하며, 설정을 새로 고칩니다. 루프백 주소에 바인딩하면 로컬 기기에서만 접근할 수 있습니다. 모든 인터페이스에 바인딩하기 전에는 secret의 인증 역할을 이해하고 방화벽을 점검해야 합니다. 화면은 열리지만 노드와 연결이 표시되지 않는다면 제어 주소의 사용 여부, 클라이언트에 입력한 제어 포트의 일치 여부, 인증 값의 일치 여부를 먼저 확인하세요.

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "your-controller-secret"

실행 모드, 로그 및 IPv6

mode의 대표적인 값은 rule, global, direct입니다. 규칙 모드는 rules를 위에서 아래로 매칭하고, 전역 모드는 트래픽을 전역 정책에 전달하며, 직접 연결 모드는 프록시를 건너뜁니다. 일상적인 사용에서는 규칙 모드를 기본으로 하고, 전역 모드는 “규칙 문제인지 노드 문제인지”를 임시로 확인할 때 활용할 수 있습니다. 직접 연결 모드는 앱 자체의 네트워크가 정상인지 확인하는 데 유용합니다. 전역 모드를 장기 설정으로 사용하면 세밀한 분기를 우회하고 규칙 작성 오류를 가릴 수 있습니다.

log-level은 로그의 상세 수준을 조절합니다. 정상적인 실행에는 info가 적절하고, 규칙 매칭, DNS 또는 핸드셰이크 문제를 조사할 때는 일시적으로 debug로 올릴 수 있습니다. 상세 로그는 빠르게 커질 수 있으며 접속 도메인과 노드 이름이 포함될 수도 있으므로 문제를 해결한 뒤에는 일반 수준으로 되돌려야 합니다. ipv6는 커널이 관련 조회와 연결 기능을 사용할지 결정하지만, 단독으로 네트워크를 복구하는 스위치는 아닙니다. 로컬 네트워크, DNS 응답, 프록시 노드와 규칙이 모두 지원해야 합니다. IPv6 경로가 불안정하다면 먼저 끄고 비교 테스트를 진행한 뒤 장기적으로 변경할지 결정하세요.

설정을 수정한 뒤에는 “저장 성공”, “다시 로드 성공”, “트래픽이 새 설정을 통과함”을 구분해야 합니다. 일부 클라이언트는 텍스트만 저장하고 즉시 다시 로드하지 않으며, 일부는 문법 오류가 발생해도 이전에 실행되던 설정을 유지합니다. 가장 확실한 확인 방법은 다시 로드한 로그를 보고 현재 모드와 포트를 확인한 다음, 규칙 매칭을 식별할 수 있는 요청을 한 번 발생시키는 것입니다. 포트 설정이 여전히 불분명하다면 문제 해결의 시스템 프록시 및 포트 항목을 참고해 하나씩 점검하세요.

03 · NAME RESOLUTION

Clash DNS, Fake-IP 및 DNS 해석 경로

DNS 모듈의 위치

Clash DNS를 활성화하면 도메인 해석은 운영체제가 특정 서버에 질의 하나를 보내는 단순한 과정이 아닙니다. 커널은 규칙에 따라 상위 DNS를 선택하고 결과를 캐시하며, Fake-IP 모드에서는 도메인과 예약 주소 사이의 매핑을 유지할 수 있습니다. 이를 이해하면 세 가지 문제를 구분하는 데 도움이 됩니다. 상위 DNS에 접근할 수 없는 경우, 도메인이 적절하지 않은 주소로 해석되는 경우, 앱이 Clash를 우회해 암호화 DNS를 직접 요청하는 경우입니다. 프록시 연결은 정상인데 웹페이지가 열리지 않는다면 모든 문제를 노드 탓으로 돌리지 말고 DNS 리스너, 시스템 DNS 지정, 규칙 경로를 함께 확인해야 합니다.

dns.enable은 모듈 활성화 여부를 제어하고, listen은 리스닝 주소와 포트를 지정합니다. 데스크톱 그래픽 클라이언트가 시스템 DNS를 자동으로 인계받는 경우 수동으로 리스닝 포트를 바꾸면 클라이언트 관리 방식과 충돌할 수 있습니다. 라우터나 로컬 네트워크 서비스 환경에서 리스닝 주소를 명시적으로 설정할 필요가 더 큽니다. 로컬 네트워크 인터페이스에 바인딩한다면 시스템 DNS 서비스가 해당 포트를 사용하고 있지 않은지 확인하고 접근 범위도 제한하세요.

Fake-IP와 Redir-Host

enhanced-mode: fake-ip는 먼저 앱에 예약 주소를 반환한 뒤 Clash가 매핑을 통해 원래 도메인을 복원하고 규칙을 적용합니다. 도메인 정보를 온전히 보존하고 규칙 판단이 빠르며, 실제 주소를 해석할 때까지 기다렸다가 전달하는 과정을 줄일 수 있다는 장점이 있습니다. 반면 실제 주소, 로컬 네트워크 검색 또는 특수 프로토콜에 의존하는 일부 앱은 호환되지 않을 수 있어 fake-ip-filter로 제외해야 합니다. redir-host는 기존의 실제 주소 해석 경로에 더 가깝고 호환 방식도 다르지만, 도메인 식별과 연결 경로가 시스템 캐시 및 해석 시점의 영향을 받습니다.

fake-ip-range는 예약 주소 범위를 지정합니다. 일반적으로 클라이언트나 커널의 기본값을 그대로 사용하는 것이 좋으며, 로컬 실제 네트워크 대역, VPN 주소 풀 또는 기업 네트워크 라우팅과 겹치지 않아야 합니다. 로컬 네트워크 도메인에 접속했을 때 예약 주소가 반환된다면 전체 주소 대역을 임의로 바꾸기보다 해당 도메인을 필터 목록에 추가하세요. 필터 규칙은 가능한 한 정확하게 작성해야 합니다. 단일 호스트는 전체 도메인으로 쓰고, 하위 도메인까지 포함해야 할 때는 지원되는 와일드카드 형식을 사용한 뒤 앱과 시스템 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"
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://cloudflare-dns.com/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query

세 가지 상위 DNS 필드의 조합

default-nameserver는 주로 암호화 DNS 상위 서버 자체의 도메인을 해석하는 데 사용되므로 직접 접근 가능한 IP 주소를 입력하는 경우가 많습니다. 모든 항목을 도메인으로 작성하면 “DNS 서버 도메인을 먼저 해석해야 하지만 현재 사용할 해석기가 없음”이라는 순환이 발생할 수 있습니다. nameserver는 주요 질의 상위 서버이며 일반 UDP, DoT 또는 DoH 주소를 사용할 수 있습니다. proxy-server-nameserver는 프록시 노드 서버의 도메인을 해석해 노드 도메인 해석과 프록시 경로가 서로 의존하지 않도록 합니다. 노드 서버가 이미 IP 주소라면 영향이 작지만, 도메인이라면 매우 중요합니다.

nameserver-policy를 사용하면 도메인별로 서로 다른 상위 DNS를 지정할 수 있어 기업 내부 도메인, 지역별 해석 또는 별도 처리가 필요한 서비스에 적합합니다. 이는 “질의를 어디에 보낼지”를 정하는 기능이며 최종 연결이 어떤 프록시 그룹을 통과할지는 직접 결정하지 않습니다. 연결 분기는 여전히 규칙이 담당합니다. DNS policy와 프록시 rule을 같은 문법으로 혼동하지 말고, 해석 결과만으로 프록시가 적용되었다고 판단하지도 마세요.

dns:
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
    "internal.example":
      - 192.0.2.53
  fallback:
    - tls://1.1.1.1
  fallback-filter:
    geoip: true
    geoip-code: CN

DNS 문제는 경로에 따라 점검해야 합니다

첫째 Clash DNS가 실제로 리스닝 중인지 확인하고, 둘째 시스템 또는 TUN 트래픽이 해당 리스너로 전달되는지 확인하며, 셋째 어떤 상위 DNS를 사용했는지 관찰한 뒤 마지막으로 연결 규칙을 점검하세요. 브라우저 캐시만 지우거나 노드를 계속 바꾸는 것으로는 DNS 계층의 문제를 찾을 수 없습니다. 로그에 상위 DNS 타임아웃이 표시되면 현재 네트워크에서 해당 서버에 직접 연결할 수 있는지 테스트해야 합니다. 도메인은 해석되지만 연결이 실패한다면 규칙 매칭, IPv4·IPv6 선택, 노드 사용 가능성을 계속 확인하세요. 특정 앱에서만 문제가 발생한다면 앱 내장 DoH, QUIC 또는 캐시 방식도 고려해야 합니다.

04 · OUTBOUND

프록시 노드 필드와 프로토콜 매개변수

모든 노드에 공통으로 필요한 식별 필드

proxies는 프록시 노드 객체 목록입니다. 각 객체에는 최소한 고유한 name, 프로토콜 type, 서버 server, 포트 port가 포함되며 나머지 필드는 프로토콜에 따라 달라집니다. 노드 이름은 화면에 표시되는 레이블이 아니라 설정 내부에서 참조하는 키입니다. 두 노드가 같은 이름을 사용하면 프록시 그룹 참조가 모호해지고, 구독 노드와 로컬 노드의 이름이 겹치면 병합 과정에서 덮어써질 수도 있습니다. 이름에는 지역, 회선 또는 용도를 함께 나타내되 자주 바뀌는 상태 정보는 넣지 않는 것이 좋습니다.

server에는 IP 주소나 도메인을 사용할 수 있습니다. 도메인을 사용한다면 앞 장에서 설명한 노드 도메인 해석 경로가 작동해야 합니다. 포트는 원격 서비스의 포트이며 로컬 mixed-port가 아닙니다. 둘을 혼동하는 것은 수동 입력에서 흔한 오류입니다. 프로토콜 필드는 서버 설정과 일치해야 하며 암호화 방식이나 전송 유형을 바꿔 가며 “자동 탐색”할 수는 없습니다. 인증 실패, TLS 핸드셰이크 실패, 네트워크 타임아웃은 서로 다른 단계의 문제이므로 로그를 함께 확인하세요.

Shadowsocks와 VMess 예시

Shadowsocks 노드는 암호화 방식과 비밀번호를 중점적으로 확인합니다. cipher는 커널이 지원하면서 서버와 동일한 값이어야 합니다. 비밀번호에는 특수 문자가 YAML에서 해석되지 않도록 항상 따옴표를 붙이는 것이 좋습니다. 서버에서 플러그인을 사용한다면 플러그인 이름과 옵션도 함께 입력해야 하며 서버, 포트, 비밀번호만 복사해서는 안 됩니다. 플러그인 매개변수는 보통 매핑 객체이므로 계층이 잘못되면 플러그인이 로드되지 않거나 노드를 사용할 수 없습니다.

proxies:
  - name: "SS-Example"
    type: ss
    server: 203.0.113.20
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "VMess-Example"
    type: vmess
    server: edge.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    servername: edge.example.com
    network: ws
    ws-opts:
      path: /proxy
      headers:
        Host: edge.example.com

VMess에는 ID 필드 외에도 TLS, WebSocket, HTTP 또는 gRPC 전송 설정이 포함될 수 있습니다. servername은 TLS SNI에 사용되고 WebSocket의 Host는 HTTP 요청 헤더에 해당합니다. 둘은 같을 수 있지만 의미는 다릅니다. 경로는 앞의 슬래시를 유지하고 서버 진입점과 일치시켜야 합니다. 오래된 설정에는 호환성을 위한 과거 필드가 남아 있을 수 있으므로 새 커널에 가져오기 전에는 다른 프로토콜 템플릿을 조합하지 말고 서비스 제공자가 현재 제공하는 매개변수를 기준으로 하세요.

Trojan, VLESS 및 TLS 관련 필드

Trojan은 보통 비밀번호 인증과 TLS를 사용하고, VLESS는 UUID를 사용하며 다양한 전송 방식과 흐름 제어를 조합할 수 있습니다. TLS 노드에서 가장 흔한 문제는 서버 주소, 인증서 이름, SNI가 서로 일치하지 않는 것입니다. skip-cert-verify는 인증서 검증 방식을 바꾸므로 장기적인 해결책으로 사용해서는 안 됩니다. 인증서 검증에 실패하면 먼저 기기 시간, 서버 인증서, 도메인 및 servername을 확인하세요. 테스트 환경에서 어떤 인증서를 사용하는지 명확히 알고 있을 때만 일시적으로 변경하고 그 이유를 기록해야 합니다.

  - name: "Trojan-Example"
    type: trojan
    server: gateway.example.com
    port: 443
    password: "your-password"
    sni: gateway.example.com
    udp: true
    skip-cert-verify: false

  - name: "VLESS-Example"
    type: vless
    server: vless.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000001
    tls: true
    servername: vless.example.com
    network: grpc
    grpc-opts:
      grpc-service-name: proxy

UDP, 인터페이스 및 다이얼 동작

udp: true는 노드가 UDP 전달을 허용한다는 뜻이지만 서버, 프로토콜, 클라이언트 모드와 로컬 네트워크도 함께 지원해야 합니다. 이 필드만 추가한다고 UDP를 지원하지 않는 회선이 UDP 기능을 얻는 것은 아닙니다. 게임, 음성 또는 DNS와 관련된 경우 로그에서 트래픽이 UDP로 전달되는지 확인하고 프록시 그룹에서 선택한 노드가 이를 지원하는지도 점검하세요. 일부 설정에는 interface-name, routing-mark 또는 다이얼 관련 필드도 있지만 이는 다중 네트워크 카드와 게이트웨이 환경에 더 적합합니다. 데스크톱 사용자는 인터페이스 이름을 정확히 모른 채 그대로 복사하지 않는 것이 좋습니다.

노드가 지연 시간 테스트를 통과했다는 것은 특정 테스트 URL에 당시 요청을 설정할 수 있었다는 뜻일 뿐, 모든 프로토콜과 사이트가 정상이라는 의미는 아닙니다. 테스트 주소, TLS 경로, 패킷 손실과 대역폭이 결과에 영향을 줍니다. Clash 지연 시간 테스트 수치 해석법을 이어서 읽고 실제 접속과 로그를 함께 확인하세요. 클라이언트를 바꿔 비교해야 한다면 이 사이트의 다운로드 목록에서는 모든 플랫폼의 우선 추천으로 Clash Plus를 안내하며 Clash Verge Rev, FlClash, Clash Nyanpasu, ClashX Meta 등도 선택할 수 있습니다.

05 · POLICY

프록시 그룹 필드와 선택 로직

select: 직접 선택하는 수동 방식

프록시 그룹은 노드, 내장 동작, 다른 프록시 그룹을 규칙에서 참조할 수 있는 출구로 묶습니다. select는 가장 직접적인 유형으로, 사용자가 클라이언트 화면에서 항목을 수동 선택하며 선택 결과는 보통 클라이언트에 저장됩니다. 전체 진입점, 지역 선택, 고정 회선이 필요한 서비스에 적합합니다. 그룹 안의 proxies는 기존 노드나 프록시 그룹을 이름으로 참조하며 DIRECT, REJECT 같은 내장 동작도 포함할 수 있습니다. 참조 대상은 최종 설정 안에 이미 존재해야 합니다.

프록시 그룹은 중첩할 수 있습니다. 예를 들어 “노드 선택”이 “홍콩 자동”, “일본 자동”, “수동 선택”을 참조하도록 구성할 수 있습니다. 중첩하면 규칙 중복을 줄일 수 있지만 계층이 깊어질수록 문제 해결이 어려워집니다. 특정 연결의 최종 경로를 확인하려면 규칙 대상부터 시작해 각 프록시 그룹을 차례로 펼쳐 구체적인 노드나 내장 동작까지 따라가야 합니다. 이름은 기능을 반영해야 하며 여러 그룹을 모두 “자동 선택”이라고 지정해 테스트 범위를 구분하지 못하게 만들지 마세요.

url-test, fallback 및 load-balance

url-test는 지정한 URL에 주기적으로 요청을 보내 측정 결과에 따라 조건에 맞는 노드를 선택합니다. interval은 테스트 주기이고 tolerance는 지연 시간이 비슷할 때 잦은 전환을 줄이는 값입니다. 테스트가 너무 잦으면 요청과 배터리 소모가 늘고, 간격이 너무 길면 회선 변화를 제때 반영하지 못합니다. 테스트 URL은 안정적이고 응답 본문이 작으며 실제 외부 연결성을 대표해야 합니다. 로그인 필요, 복잡한 리디렉션, 지역 제한이 뚜렷한 페이지는 사용하지 마세요.

fallback은 현재 노드를 사용할 수 없을 때 다음 사용 가능한 항목으로 전환하는 가용성 순서를 중시합니다. load-balance는 정책에 따라 여러 노드에 연결을 분산하므로 세션 일관성 요구 사항을 명확히 이해한 환경에 적합합니다. 고정된 출발지 주소가 필요한 로그인, 결제 또는 장시간 연결 서비스에는 부하 분산을 임의로 사용하지 않는 것이 좋습니다. 자동 그룹의 테스트 결과도 실제 브라우징 속도 순위로 해석해서는 안 됩니다. 결과는 테스트 주소와 해당 시점의 네트워크 조건에만 해당합니다.

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "홍콩 자동"
      - "수동 선택"
      - DIRECT

  - name: "수동 선택"
    type: select
    proxies:
      - "SS-Example"
      - "Trojan-Example"
      - "VLESS-Example"

  - name: "홍콩 자동"
    type: url-test
    proxies:
      - "SS-Example"
      - "Trojan-Example"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

Provider로 노드 동적으로 가져오기

노드가 구독 Provider에서 제공될 때 프록시 그룹은 use로 Provider 이름을 참조할 수 있으므로 모든 노드를 proxies에 직접 작성할 필요가 없습니다. 일부 커널은 filter와 exclude-filter로 이름을 필터링하는 기능도 지원합니다. 필터에는 보통 정규식이 사용되므로 문자 범위와 괄호를 올바르게 이스케이프해야 합니다. 구독의 이름 규칙이 통일되어 있지 않다면 “홍콩”이나 “HK”만으로는 노드를 놓치거나 같은 문자가 포함된 설명 항목을 잘못 선택할 수 있습니다. 먼저 실제 노드 이름을 확인한 뒤 필터 표현식을 작성하세요.

proxy-groups:
  - name: "홍콩 노드"
    type: select
    use:
      - provider-main
    filter: "(?i)홍콩|홍|HK|Hong Kong"
    exclude-filter: "(?i)게임|잔여|만료"

  - name: "장애 조치"
    type: fallback
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 600

상태 확인과 연결 유지

Provider의 상태 확인과 프록시 그룹 자체의 URL 테스트가 동시에 작동할 수 있습니다. 전자는 노드 사용 가능 상태를 관리하고 후자는 그룹 내부에서 노드를 선택합니다. 중복되고 빈번한 테스트는 불필요한 요청을 발생시키므로 어느 계층이 확인을 담당할지 정하고 주기를 적절히 설정해야 합니다. 프록시 그룹을 전환해도 기존 연결이 즉시 이동하는 것은 아닙니다. 브라우저 연결 풀, QUIC, 장시간 연결은 이전 출구를 계속 사용할 수 있습니다. 전환 결과를 확인할 때는 화면의 선택 항목만 보지 말고 기존 연결을 닫은 뒤 새 요청을 만들고 필요하면 앱의 연결 풀을 정리하세요.

규칙에서 참조하는 프록시 그룹은 장기간 유지되어야 합니다. 구독 업데이트로 노드 목록은 바뀔 수 있지만 규칙 대상 그룹 이름까지 임의로 바뀌어서는 안 됩니다. 안정적인 구조에는 보통 전체 진입점, 자동 그룹, 수동 그룹, 직접 연결 및 거부 처리가 포함되고 필요에 따라 스트리밍, 메신저 또는 개발 서비스 그룹을 추가합니다. 그룹이 많다고 분기가 정확해지는 것은 아닙니다. 실제 규칙에서 참조되고 용도가 분명한 그룹만 유지할 가치가 있습니다.

06 · ROUTING

Clash 규칙 분기 문법과 우선순위

규칙은 위에서 아래로 검사하며 최초로 일치한 항목을 사용합니다

rules는 순서가 있는 목록입니다. 연결 정보가 특정 규칙과 일치하면 커널은 해당 규칙이 지정한 정책을 사용하고 뒤의 일반 규칙은 더 확인하지 않습니다. 따라서 구체적인 규칙은 포괄적인 규칙보다 앞에 두고, 최종 대체 규칙인 MATCH는 반드시 마지막에 배치해야 합니다. 예를 들어 DOMAIN-SUFFIX,example.com,DIRECT를 먼저 쓰고 MATCH,노드 선택을 뒤에 쓰면 해당 도메인은 직접 연결됩니다. 순서를 반대로 하면 앞의 MATCH가 모든 트래픽을 처리하므로 뒤의 규칙은 실행될 기회를 잃습니다.

일반적인 규칙은 “규칙 유형, 매칭 내용, 정책 대상”으로 구성되며 일부 유형에는 추가 매개변수가 붙을 수 있습니다. 쉼표는 필드 구분자이고 프록시 그룹 이름은 설정과 완전히 일치해야 합니다. 규칙 목록의 각 줄은 YAML 문자열 항목으로 작성해야 합니다. 도메인 규칙에는 프로토콜 헤더, 경로 또는 포트를 포함하지 않아야 합니다. https://sub.example.com/path를 매칭하려면 호스트 이름을 추출한 뒤 전체 도메인, 접미사 또는 키워드 규칙 중 적절한 유형을 선택하세요.

도메인, 주소 및 프로세스 규칙

DOMAIN은 전체 도메인을 정확히 매칭하고, DOMAIN-SUFFIX는 지정한 도메인과 하위 도메인을 매칭하며, DOMAIN-KEYWORD는 도메인에 포함된 키워드로 매칭합니다. 일반적으로 접미사 규칙이 키워드 규칙보다 제어하기 쉽습니다. 키워드가 지나치게 짧으면 범위가 넓어져 무관한 도메인까지 잘못 매칭될 수 있습니다. 특정 서비스를 포함하려면 먼저 실제 요청 도메인을 수집한 뒤 정확한 규칙과 접미사 규칙을 조합하세요.

IP-CIDR과 IP-CIDR6은 주소 대역으로 매칭합니다. 도메인 연결이 주소 규칙에 들어갈지는 해석 과정과 no-resolve 매개변수에 따라 달라집니다. 불필요한 추가 DNS 해석을 피하려면 지원되는 문법에서 no-resolve를 사용할 수 있습니다. GEOIP는 주소 소재지 데이터베이스에 따라 분류하므로 결과는 데이터베이스 출처와 업데이트 상태의 영향을 받으며 업무상 지역을 절대적으로 판단하는 기준은 아닙니다. PROCESS-NAME, PROCESS-PATH 같은 프로세스 규칙은 운영체제와 클라이언트 권한에 의존하므로 모바일, 샌드박스 환경 또는 TUN 구현에 따라 지원 수준이 다를 수 있습니다.

rules:
  - DOMAIN,api.example.com,노드 선택
  - DOMAIN-SUFFIX,example.net,노드 선택
  - DOMAIN-KEYWORD,cdn-example,노드 선택
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

규칙 집합과 논리 조합

대규모 규칙을 모두 기본 설정에 작성하는 대신 RULE-SET으로 규칙 Provider를 참조할 수 있습니다. 규칙 집합에는 매칭 조건만 저장하고 기본 설정에서 정책 대상을 지정하면 같은 집합을 여러 기기에서 서로 다른 출구로 사용할 수 있습니다. 사용할 때는 Provider의 behavior와 파일 내용이 일치하는지 확인하세요. domain은 도메인 항목에, ipcidr은 주소 대역에, classical은 완전한 클래식 규칙에 적합합니다. 유형이 맞지 않으면 파일은 정상적으로 다운로드되어도 예상대로 파싱되지 않을 수 있습니다.

일부 커널은 AND, OR, NOT 같은 논리 규칙을 지원합니다. “특정 프로세스가 특정 도메인에 접근할 때”와 같은 복합 조건을 표현하는 데 적합하지만 기본 규칙보다 가독성과 클라이언트 간 호환성이 낮습니다. 기본 유형으로 요구 사항을 정확히 표현할 수 없을 때만 도입하고 옆에 용도를 기록하세요. 규칙이 복잡해질수록 눈으로 추측하기보다 로그의 매칭 정보가 더 신뢰할 만합니다.

rules:
  - RULE-SET,private,DIRECT
  - RULE-SET,applications,DIRECT
  - RULE-SET,streaming,미디어 서비스
  - RULE-SET,global,노드 선택
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

규칙이 매칭되지 않을 때의 확인 방법

먼저 연결 로그에서 실제 도메인, 대상 주소, 프로세스, 매칭된 규칙을 확인한 뒤 설정으로 돌아가 점검하세요. 브라우저 주소창의 주 도메인이 페이지가 접근하는 유일한 항목이라는 뜻은 아닙니다. 스크립트, 이미지, 인증, API가 여러 도메인에 분산될 수 있습니다. 로그에 IP만 표시된다면 DNS를 Clash가 인계받았는지 또는 앱이 주소로 직접 연결하는지 확인해야 합니다. 예상한 규칙이 MATCH 뒤에 있다면 순서를 옮기는 것만으로 문제가 설명됩니다. 규칙 대상 그룹이 존재하지 않는다면 참조를 수정해야 합니다.

규칙 분기의 목표는 가능한 한 많은 규칙이 아니라 안정성과 설명 가능성입니다. 로컬 네트워크와 예약 주소는 보통 직접 연결을 우선하고, 명확한 업무 규칙은 중간에 배치하며, 지역 주소 규칙은 뒤에 두고 MATCH가 최종 대체를 담당하게 합니다. 새 규칙을 추가할 때는 정방향 매칭과 역효과를 모두 확인하세요. 대상 서비스가 예상한 그룹을 통과하는지, 무관한 서비스가 지나치게 넓은 조건에 끌려가지 않는지 점검해야 합니다. 프록시 연결은 되지만 웹페이지에 접근할 수 없는 복합 문제가 발생하면 항목별 점검 목록에 따라 시스템 프록시, 포트, 노드, DNS와 규칙을 확인하세요.

07 · EXTERNAL SOURCES

Proxy Provider와 규칙 집합

Provider는 어떤 문제를 해결하나요?

proxy-providers는 외부 노드 소스를 기본 설정과 분리합니다. 기본 설정에는 프록시 그룹과 규칙 구조를 유지하고 Provider가 노드 목록을 주기적으로 업데이트합니다. 이를 통해 구독이 바뀌어도 프록시 그룹 이름을 안정적으로 유지할 수 있고 여러 자동 그룹이 같은 노드 소스를 참조할 수도 있습니다. Provider 이름은 내부 참조 키이므로 안정적으로 유지해야 합니다. 구독 주소를 바꿀 때 모든 프록시 그룹을 함께 수정할 필요 없이 해당 Provider 정의만 업데이트하면 됩니다.

일반적인 type에는 http와 file이 있습니다. HTTP 유형은 URL에서 가져오고 file 유형은 로컬 경로를 읽습니다. path는 캐시 또는 로컬 파일 위치를 지정하며 여러 Provider가 같은 경로에 쓰지 않도록 해야 합니다. interval은 원격 업데이트 주기를 제어합니다. 너무 짧으면 요청이 잦아지고 너무 길면 상위 소스의 변경을 제때 받지 못합니다. 클라이언트에 자체 구독 업데이트 일정이 있다면 해당 설정이 커널 필드를 덮어쓰는지도 확인하세요.

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

proxy-groups:
  - name: "구독 노드"
    type: select
    use:
      - provider-main

Provider 파일 형식과 상태 확인

프록시 Provider의 응답은 커널 요구 사항을 따라야 하며, 일반적으로 전체 기본 설정이 아니라 proxies를 키로 하는 노드 목록을 포함합니다. 일반 구독 링크, Base64 노드 목록 또는 완전한 설정을 그대로 Provider 파일로 사용한다고 해서 현재 커널이 반드시 인식하는 것은 아닙니다. 형식 변환은 신뢰할 수 있고 통제 가능한 단계에서 수행하고, 변환 과정에서 노드 필드가 누락되지 않았는지 확인하세요. 구독 형식의 차이는 Clash 구독과 다른 링크 형식 간 변환 방법에서 이어서 확인할 수 있습니다.

health-check는 Provider 내부 노드를 주기적으로 확인합니다. 테스트 URL과 주기 선택 원칙은 자동 프록시 그룹과 같습니다. 상태 확인 실패가 반드시 구독 다운로드 실패를 의미하지는 않습니다. 전자는 노드 테스트이고 후자는 Provider 파일 가져오기입니다. 로그에서 HTTP 업데이트 상태, 파일 파싱 상태, 노드 테스트 결과를 구분해야 합니다. 업데이트 후 노드 수가 0이 되었다면 먼저 캐시 파일이 실제로 저장되었는지 확인한 뒤 형식과 필터 표현식을 점검하세요.

rule-providers의 동작 유형

규칙 Provider는 behavior로 콘텐츠 유형을 선언합니다. domain 파일은 보통 도메인 또는 도메인 집합을 저장하고, ipcidr은 IPv4 및 IPv6 주소 대역을 저장하며, classical은 유형이 포함된 완전한 규칙을 저장합니다. format은 YAML, 텍스트 또는 커널이 지원하는 바이너리 형식을 구분하는 데 사용할 수 있습니다. 참조할 때 기본 규칙에서 Provider 이름과 프록시 그룹을 지정합니다. 예를 들면 RULE-SET,private,DIRECT와 같습니다. 정책이 Provider 파일에 고정되지 않는다는 점이 외부 규칙을 재사용할 수 있는 이유입니다.

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

  local-network:
    type: file
    behavior: ipcidr
    format: yaml
    path: ./rules/local-network.yaml

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

업데이트 실패, 캐시 및 대체 동작

Provider 업데이트에 실패하면 커널은 보통 기존 캐시를 계속 사용하려고 하지만 구체적인 동작은 클라이언트와 캐시의 완전성에 따라 달라집니다. 최초 로드 시 캐시가 없고 원격 주소에 접근할 수 없다면 해당 노드나 규칙이 바로 누락됩니다. 이전에 정상 실행된 기기에서는 오래된 파일을 계속 사용할 수도 있습니다. 문제를 조사할 때는 “한 번도 다운로드에 성공하지 못했는지”와 “이전에는 작동했지만 현재 업데이트에 실패했는지”를 기록하세요. 두 경우의 해결 경로가 다릅니다.

원격 규칙과 노드 소스는 안정적인 HTTPS 주소를 사용해야 합니다. URL의 쿼리 매개변수에는 구독 식별 정보가 포함될 수 있으므로 공개 로그, 스크린샷 또는 공유 설정에 남기지 않는 것이 좋습니다. 설정 구조를 공유해야 한다면 주소와 인증 정보는 바꾸되 필드 계층은 유지하세요. 경로는 클라이언트 작업 디렉터리도 고려해야 합니다. 상대 경로는 커널 실행 디렉터리를 기준으로 해석되며 사용자가 보는 구독 파일의 위치를 기준으로 하지 않을 수 있습니다. 파일을 찾지 못할 때는 ./를 반복해서 수정하기보다 로그에 표시된 절대 경로를 확인하는 편이 효과적입니다.

여러 Provider를 병합한 뒤에도 노드 이름이 겹칠 수 있습니다. 프록시 그룹 필터는 최종 이름만 보고 어느 소스에서 왔는지 구분하지 못합니다. 클라이언트 오버라이드로 Provider별 접두사를 추가하거나 구독 관리 단계에서 이름을 통일할 수 있습니다. 보다 체계적인 다중 설정 관리 방법은 Profile 구조 입문과 다중 설정 관리를 참고하세요.

08 · MAINTENANCE

설정 오버라이드, 병합 및 시스템 문제 해결

오버라이드 계층이 필요한 이유

구독 설정은 업데이트될 때 상위 소스의 내용으로 교체되므로 구독 본문을 직접 편집하면 로컬 수정 사항이 사라지기 쉽습니다. 오버라이드 계층은 포트, DNS, 프록시 그룹 추가, 규칙 우선 배치처럼 안정적인 로컬 설정과 원격 설정을 분리합니다. 클라이언트에 따라 Override, Mixin, Merge, 확장 스크립트 또는 설정 강화 등 이름이 다를 수 있고 병합 의미도 완전히 같지 않습니다. 사용하기 전에 객체 재귀 병합, 배열 교체, 배열 추가, 스크립트 처리 중 어떤 방식을 사용하는지 확인해야 합니다.

매핑 필드는 키 단위로 덮어쓸 수 있어 dns.enable만 수정하고 다른 DNS 하위 항목은 유지할 수 있습니다. 반면 배열 필드는 차이가 발생하기 쉽습니다. rules를 통째로 교체하면 기존 구독 규칙이 사라지고, 추가 방식이라면 로컬 규칙이 MATCH 뒤에 배치되어 영원히 매칭되지 않을 수 있습니다. 프록시 그룹과 노드 역시 목록이므로 이름 기준 병합인지 위치 기준 병합인지에 따라 결과가 크게 달라집니다. 따라서 오버라이드 후에는 텍스트의 문법만 확인하지 말고 반드시 최종 설정을 확인해야 합니다.

# 예시: 개념적인 오버라이드 내용, 실제 병합 방식은 클라이언트에 따라 다름
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip

rules:
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - DOMAIN-SUFFIX,example.net,노드 선택
  - MATCH,노드 선택

규칙 앞에 추가하기, 덧붙이기 및 삭제

로컬 규칙은 보통 구독 규칙보다 앞에 배치해야 하며, 특히 포괄적인 규칙을 덮어써야 할 때 중요합니다. prepend와 append를 지원하는 클라이언트라면 정확한 예외 규칙은 prepend에, 실제로 추가할 대체 규칙은 append에 배치하세요. 클라이언트가 배열 전체 교체만 지원한다면 이후 규칙을 직접 유지 관리해야 합니다. 원격 규칙 하나를 삭제하려고 반대 규칙을 추가하는 방식은 일반적으로 통하지 않습니다. 해당 규칙보다 앞에 더 정확한 규칙을 추가하거나 클라이언트가 제공하는 필터 스크립트를 사용해야 합니다.

필드를 비울 때는 올바른 유형을 사용해야 합니다. 목록을 비울 때는 보통 [], 매핑을 비울 때는 {}를 사용하며 키 삭제 방식은 오버라이드 구현에 따라 달라집니다. 필드를 null로 작성하면 삭제를 의미할 수도 있고, 빈 값을 커널에 전달해 유형 오류를 일으킬 수도 있습니다. 익숙하지 않은 병합기를 사용할 때는 먼저 영향이 적은 작은 필드로 테스트하고 병합 전후 결과를 비교한 다음 전체 규칙과 프록시 그룹을 처리하세요.

문법에서 네트워크까지 이어지는 4단계 점검

첫 번째 단계는 YAML 파싱입니다. 들여쓰기, 콜론, 목록 기호, 따옴표, 필드 유형을 확인하세요. 이 단계에서 실패하면 클라이언트는 보통 줄 번호를 알려주지만 실제 원인은 따옴표가 닫히지 않은 것처럼 이전 줄에 있을 수도 있습니다. 두 번째 단계는 설정 참조입니다. 프록시 그룹이 존재하는 노드나 Provider를 참조하는지, 규칙 대상이 존재하는지, Provider 경로가 충돌하지 않는지 확인하세요. 세 번째 단계는 런타임 리스닝입니다. 프록시 포트, 제어 포트, DNS 포트와 TUN이 정상적으로 시작되었는지 확인합니다. 네 번째 단계에서야 노드 핸드셰이크, DNS 상위 서버, 규칙 매칭, 앱의 시스템 프록시 사용 여부 등 네트워크 동작을 확인합니다.

최소 설정으로 위치 찾기

복잡한 설정에서 문제가 발생하면 로컬 테스트용 사본을 만들고, 정상 작동이 확인된 노드 하나, select 프록시 그룹 하나, MATCH 규칙 하나, 필수 포트 필드만 남기세요. 먼저 프록시 경로를 확인한 뒤 DNS, Provider, 규칙 집합을 단계적으로 추가합니다. 각 부분을 추가할 때마다 다시 로드하고 테스트하면 장애가 처음 나타난 지점이 주요 조사 범위가 됩니다. 여러 노드, DNS, 실행 모드를 동시에 바꾸는 것보다 조금 느리지만 결과를 재현할 수 있고 우연히 복구된 뒤 원인을 설명하지 못하는 상황도 피할 수 있습니다.

mixed-port: 7890
mode: rule
log-level: debug

proxies:
  - name: "Test-Node"
    type: ss
    server: 203.0.113.30
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "TEST"
    type: select
    proxies:
      - "Test-Node"
      - DIRECT

rules:
  - MATCH,TEST

테스트가 끝나면 로그 수준을 일반 설정으로 되돌리고 검증된 변경 사항을 안정적인 오버라이드 계층에 반영하세요. 문제가 특정 플랫폼에서만 발생한다면 시스템 프록시 구현, 권한, TUN 드라이버와 앱 네트워크 스택의 차이도 고려해야 합니다. Windows 전체 설치와 시스템 프록시 문제는 Windows Clash 설치 전체 과정을 참고하세요. 일반적인 문제는 문제 해결에서 기본 개념, 설치 및 설정, 사용 팁, 문제 해결 항목별로 계속 확인할 수 있습니다.

장기간 업데이트할 수 있는 설정 관리

안정적인 설정은 상위 데이터와 로컬 의도를 분리해야 합니다. 구독 또는 Provider는 노드를 관리하고, 기본 설정은 프록시 그룹과 규칙을 관리하며, 오버라이드 계층은 기기별 차이를 저장합니다. 프록시 그룹에는 안정적인 이름을 사용하고 사용자 지정 규칙에는 이유를 기록하며 포트와 DNS를 중복 정의하지 마세요. 구독 업데이트 후에는 최종 설정의 노드 수, 프록시 그룹 참조, MATCH 위치를 확인하고, 클라이언트 업데이트 후에는 필드 호환성과 오버라이드 병합 결과를 중점적으로 점검하세요.

기기를 이전할 때 YAML 파일 하나만 복사하지 마세요. Provider 캐시를 다시 다운로드할 수 있는지, 클라이언트가 프록시 그룹 선택 상태를 저장하는지, 시스템 프록시와 TUN 권한을 어떻게 설정해야 하는지도 기록해야 합니다. 설정 파일에는 커널 동작이 담기지만 운영체제 권한과 클라이언트 화면 상태가 모두 포함되는 것은 아닙니다. 이 경계를 기준으로 관리해야 문제가 발생했을 때 YAML, 클라이언트 설정, 시스템 네트워크 중 어디를 수정해야 할지 판단할 수 있습니다.