Clash 설정 필드

CHAPTER 01 / INPUT

YAML 구조 개요와 로드 관계

Clash 설정 파일은 YAML 문서입니다. 줄 단위로 실행되는 스크립트가 아니라, 파싱된 키와 값, 목록, 객체를 커널에 전달하는 구조입니다. 최상위 필드는 수신 포트, 실행 모드, DNS 동작 및 제어 인터페이스를 결정합니다. 프록시 노드는 proxies에 배치하거나 proxy-providers로 불러옵니다. 정책 그룹은 이름으로 노드와 다른 정책 그룹을 참조하며, 규칙 목록은 도메인, IP, 프로세스 또는 네트워크 유형을 지정된 정책으로 전달합니다. 설정을 읽을 때는 먼저 객체가 존재하는지 확인하고, 참조 이름이 완전히 일치하는지 확인한 다음 규칙 순서를 점검해야 합니다. 특정 규칙 하나만 보면 참조된 정책 그룹 자체가 로드되지 않았다는 사실을 놓치기 쉽습니다.

YAML은 들여쓰기로 계층을 표현합니다. 두 칸 들여쓰기를 일관되게 사용하고 탭은 사용하지 않는 것이 좋습니다. 목록 항목은 앞에 하이픈을 붙이며, 하이픈 뒤에는 공백 하나를 둡니다. 콜론은 키와 값을 구분하고, 콜론 뒤에도 보통 공백을 둡니다. 콜론, 샵, 대괄호 또는 특수한 불리언 표현이 포함된 이름은 따옴표로 감싸는 편이 안전합니다. 주석은 #으로 시작하며 설명에만 사용되고 커널에는 전달되지 않습니다. 들여쓰기가 올바르더라도 필드가 잘못된 계층에 있으면 파서가 예상한 위치에서 읽지 못할 수 있으므로, “파일이 열린다”는 사실만으로 필드가 적용되었다고 볼 수 없습니다.

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

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query

proxies:
  - name: "예시 노드"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

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

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

위의 최소 구조는 완전한 참조 흐름을 보여줍니다. rules의 “노드 선택”은 proxy-groups의 이름과 글자 그대로 같아야 하며, 정책 그룹의 “예시 노드”는 proxies의 노드 이름과 일치해야 합니다. 이름은 문자, 공백, 전각·반각 기호까지 구분합니다. 설정 일부를 복사할 때 규칙만 복사하고 정책 그룹을 빠뜨리거나, 정책 그룹만 복사하고 노드를 빠뜨리면 결국 끊어진 참조가 생깁니다. 일부 클라이언트는 가져오기 단계에서 안내하지만, 다른 클라이언트는 커널 시작 시에만 오류를 기록하므로 클라이언트 로그 확인이 필요합니다.

최상위 필드 권장 순서

YAML 표준은 최상위 필드의 고정 순서를 요구하지 않습니다. 하지만 유지보수를 위해 “실행 진입점, DNS, 노드 출처, 노드, 정책 그룹, 규칙 출처, 규칙” 순서로 배치하는 것이 좋습니다. 이 순서는 데이터 의존 관계와 비슷합니다. 먼저 트래픽이 커널에 들어오는 방식을 정하고, 도메인 확인 방법을 결정한 뒤 사용할 출구를 준비하고, 마지막으로 매칭을 실행합니다. 구독 생성기는 다른 순서를 사용할 수 있지만 들여쓰기와 참조가 올바르다면 대체로 결과에 영향을 주지 않습니다. 직접 관리할 때 순서를 일정하게 유지하면 병합 중 잘못 삭제할 가능성을 줄이고 업데이트 전후 차이도 쉽게 비교할 수 있습니다.

구독에서 가져온 설정은 보통 클라이언트가 로컬 사본으로 저장합니다. 사본을 직접 편집하면 테스트하기는 쉽지만 다음 구독 업데이트 때 파일이 다시 생성될 수 있습니다. 장기간 유지할 로컬 규칙은 캐시 파일 수정에 의존하지 말고 클라이언트가 지원하는 오버라이드, 병합 또는 스크립트 진입점에 넣어야 합니다. 현재 목표가 첫 연결을 완료하는 것이라면 먼저 빠른 시작 절차에 따라 구독이 정상인지 확인한 뒤 이 페이지로 돌아와 구조를 조정하세요. 그러면 “구독 자체의 문제”와 “사용자 지정 필드 오류”를 분리해서 처리할 수 있습니다.

CHAPTER 02 / RUNTIME

공통 필드: 포트, 모드, LAN 및 제어 인터페이스

공통 필드는 커널이 애플리케이션 트래픽을 수신하는 방식과 관리 기능을 노출하는 방식을 결정합니다. 데스크톱 클라이언트는 보통 그래픽 인터페이스에서 이 값을 관리하지만, 최종 기준은 설정 파일입니다. 가장 흔한 진입점은 mixed-port입니다. 하나의 포트에서 HTTP와 SOCKS5 프록시 요청을 모두 받아 시스템 프록시와 프록시 주소를 직접 입력하는 애플리케이션에 적합합니다. 오래된 설정에서는 port와 socks-port를 각각 사용할 수도 있습니다. 여러 진입점을 동시에 정의한다면 포트 번호가 중복되지 않고 다른 프로그램이 사용하지 않는지 확인해야 합니다.

mixed-port: 7890
redir-port: 7892
tproxy-port: 7893

allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

redir-port와 tproxy-port는 주로 투명 프록시 환경에서 사용되며, 라우팅 규칙, 게이트웨이 스크립트 또는 특정 클라이언트가 연결을 자동으로 구성합니다. 일반 데스크톱 시스템에서 시스템 프록시만 사용한다면 필드를 채우기 위해 억지로 활성화할 필요가 없습니다. TUN 모드도 별도의 트래픽 진입점과 라우팅 과정을 사용하므로 수신 포트 하나를 추가하는 것만으로 완료되지 않습니다. 시스템 프록시와 TUN의 적용 범위를 비교하려면 TUN 모드와 시스템 프록시의 차이를 확인한 뒤 애플리케이션이 시스템 프록시를 읽는지에 따라 라우팅 방식을 결정하세요.

실행 모드와 규칙 동작

mode의 대표 값은 rule, global, direct입니다. 규칙 모드는 rules를 위에서 아래로 매칭하며 일상적인 사용에 가장 적합합니다. 전역 모드는 트래픽을 전역 정책 선택에 맡기므로 노드의 작동 여부를 임시로 테스트할 때 유용합니다. 직접 연결 모드는 프록시 출구를 우회하므로 로컬 네트워크 문제를 분리할 때 사용할 수 있습니다. 모드를 바꿔도 규칙 내용은 수정되지 않고 의사 결정 진입점만 달라집니다. 문제를 해결할 때 잠시 전역 모드로 전환해 보세요. 전역 모드에서는 접속되지만 규칙 모드에서 실패한다면 규칙 매칭과 정책 그룹을 중점적으로 확인하고, 전역 모드에서도 실패한다면 노드, 프로토콜 매개변수 및 시스템 라우팅 상태부터 점검해야 합니다.

allow-lan은 LAN 기기가 로컬 수신 포트에 접근할 수 있는지를 제어합니다. true로 설정한 뒤에는 bind-address, 운영체제 방화벽 및 LAN 주소를 함께 고려해야 합니다. 수신 포트를 개방하면 같은 네트워크의 기기가 해당 포트로 요청을 보낼 수 있으므로, 프록시 공유가 명확히 필요할 때만 활성화하고 제어 인터페이스에는 접근 제한을 설정해야 합니다. 로컬에서만 사용할 때는 false로 유지하는 편이 관리하기 쉽습니다. 클라이언트 인터페이스에 “LAN 연결 허용” 스위치가 있다면 여러 오버라이드 계층에서 같은 값을 반복 설정하지 않아야 화면 표시와 최종 설정이 어긋나지 않습니다.

제어 인터페이스와 설정 저장

external-controller: 127.0.0.1:9090
secret: "your-dashboard-password"
external-ui: dashboard
profile:
  store-selected: true
  store-fake-ip: true

external-controller는 제어 API를 제공합니다. 그래픽 클라이언트와 패널은 이를 통해 정책 그룹을 읽고 노드를 전환하거나 설정을 다시 로드할 수 있습니다. 로컬에서 관리한다면 127.0.0.1에 바인딩하면 충분합니다. 모든 네트워크 인터페이스에 바인딩할 경우 접근 제어, 방화벽 및 실제 사용 환경을 반드시 함께 검토해야 합니다. secret은 제어 인터페이스 인증에 사용하며, 예시 값은 직접 정한 로컬 값으로 바꿔야 합니다. external-ui는 패널 정적 파일 디렉터리를 가리키며, 네트워크 노드 출처도 아니고 프록시 규칙을 변경하지도 않습니다.

profile.store-selected는 정책 그룹 선택을 저장하여 커널 재시작 후 이전 선택을 복원합니다. store-fake-ip는 Fake-IP 매핑을 저장해 재시작 후 매핑 변경의 영향을 줄입니다. 클라이언트가 이 필드를 직접 관리하는지는 구현에 따라 다릅니다. 그래픽 클라이언트는 같은 YAML이 아니라 자체 데이터베이스에 상태를 저장할 수 있습니다. “수정 후 재시작하면 다시 원래대로 돌아오는” 경우에는 필드가 구독, 오버라이드 또는 클라이언트 환경설정 중 어디에서 왔는지 먼저 판단해야 하며, 같은 캐시 파일만 반복해서 편집해서는 안 됩니다.

log-level은 로그 상세도를 제어할 때 사용합니다. 평소에는 info를 사용할 수 있으며, 규칙 매칭, DNS 요청 또는 연결 수립 과정을 확인할 때만 일시적으로 상세도를 높였다가 완료 후 되돌리는 것이 좋습니다. 그렇지 않으면 많은 기록이 핵심 오류를 가릴 수 있습니다. ipv6은 커널 관련 기능이 IPv6를 처리할지 결정하지만, 이 값을 켠다고 로컬 네트워크에 사용 가능한 IPv6 라우팅이 생기는 것은 아닙니다. 활성화 후 연결이 지연되면 로컬 네트워크, DNS 응답 및 규칙 적용 범위를 각각 확인해야 하며 모든 문제를 단일 스위치 탓으로 돌려서는 안 됩니다.

CHAPTER 03 / RESOLUTION

DNS 필드: 업스트림 확인, Fake-IP 및 폴백 규칙

Clash의 DNS 모듈은 도메인 요청과 규칙 매칭 사이에 위치합니다. 로컬 또는 TUN으로 라우팅된 DNS 질의를 받아 설정에 따라 업스트림 서버를 선택할 수 있습니다. DNS 설정의 목적은 주소를 무작정 늘리는 것이 아니라 세 가지를 명확히 하는 것입니다. 질의가 어디에서 들어오는지, 어떤 업스트림을 사용하는지, 확인 결과가 규칙과 어떻게 연동되는지입니다. 시스템 프록시 모드에서는 일부 애플리케이션이 여전히 시스템 DNS를 직접 사용할 수 있습니다. TUN 모드에서 DNS 가로채기를 함께 사용하면 적용 범위가 대체로 더 넓습니다. 브라우저는 작동하지만 다른 애플리케이션의 확인이 실패한다면 해당 애플리케이션의 DNS 트래픽이 커널로 들어오는지 먼저 확인하세요.

dns:
  enable: true
  listen: 0.0.0.0: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://1.1.1.1/dns-query
  proxy-server-nameserver:
    - https://1.1.1.1/dns-query

enable은 내장 DNS의 활성화 여부를 제어하고, listen은 수신 주소를 지정합니다. 0.0.0.0에서 수신하면 LAN 접근 범위가 관련되므로 실제 네트워크 환경에 맞게 처리해야 합니다. 로컬에서만 사용할 경우 로컬 루프백 주소를 사용하거나 클라이언트의 자동 설정에 맡길 수 있습니다. default-nameserver는 보통 직접 접근 가능한 IP 주소를 사용하며, DoH 업스트림 자체의 도메인 확인 같은 기본 작업에 쓰입니다. 모든 질의의 주요 출구는 아닙니다. 일반 도메인 확인은 주로 nameserver에 맡기고, 프록시 서버 도메인은 proxy-server-nameserver로 별도 확인하여 프록시 연결 전 순환 의존성을 피할 수 있습니다.

Fake-IP와 Redir-Host의 처리 차이

enhanced-mode: fake-ip은 예약 주소 대역의 매핑 주소를 도메인에 반환합니다. 이후 애플리케이션이 해당 주소에 연결하면 커널이 매핑을 통해 원래 도메인을 복원한 뒤 도메인 규칙과 프록시 결정을 수행합니다. 이 과정은 도메인 정보를 유지하고 TUN 환경에서 일관되게 처리하는 데 유리합니다. fake-ip-range에는 전용 예약 대역을 사용해야 하며 LAN에서 실제 사용하는 주소 범위로 바꾸면 안 됩니다. 매핑 주소는 원격 서버의 실제 주소가 아니므로 패킷 캡처 도구에서 예약 주소가 보이는 것은 정상입니다.

일부 LAN 기기 검색, 시간 동기화, 게임 또는 실제 주소 반환에 의존하는 애플리케이션은 Fake-IP와 맞지 않습니다. 이 경우 관련 도메인을 fake-ip-filter에 추가하여 실제 확인 결과를 사용하게 할 수 있습니다. 필터 항목은 최대한 구체적으로 지정하고, 이상이 확인된 도메인부터 추가하세요. 너무 넓은 최상위 매칭을 바로 넣으면 도메인 규칙의 가시성이 떨어질 수 있습니다. 매핑 과정과 제외 사례는 Clash Fake-IP 모드 원리에서 더 확인할 수 있습니다.

redir-host는 전통적인 확인 흐름에 더 가깝고, 커널이 실제 IP를 얻은 뒤 연결을 처리합니다. 실제 주소에 의존하는 프로그램에는 직관적이지만, 이후 IP 연결 단계에서 도메인 정보가 사라질 수 있어 규칙 매칭이 확인 캐시나 스니핑에 더 의존할 수 있습니다. 두 모드 중 모든 네트워크에 통하는 정답은 없습니다. 일반 웹 접속, TUN 전체 라우팅 및 많은 도메인 규칙은 우선 Fake-IP로 테스트하는 것이 좋습니다. LAN 서비스, 특정 게임 또는 기업 내부 도메인이 있다면 DNS 구조 전체를 즉시 바꾸기보다 항목별로 필터를 보완하세요.

폴백, 정책 및 분할 확인

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    domain:
      - "+.example.net"
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
    "geosite:geolocation-!cn":
      - https://1.1.1.1/dns-query

fallback과 fallback-filter은 조건에 따라 대체 결과를 선택하는 데 사용됩니다. 설정할 때는 클라이언트가 사용하는 커널의 동시 질의, 결과 필터링 및 Geo 데이터 처리 방식을 이해해야 하며, “대체 주소를 입력하면 모든 실패가 고정 순서로 자동 재시도된다”고 생각해서는 안 됩니다. nameserver-policy는 도메인 또는 규칙 집합별로 확인 서버를 지정할 수 있어 중국 본토·한국 국내 네트워크, 가정용 도메인 및 업무용 도메인에 서로 다른 확인 경로가 필요할 때 유용합니다. 정책 키에서 geosite를 참조한다면 로컬 Geo 데이터에 접근할 수 있어야 하며, 그렇지 않으면 해당 매칭이 예상대로 작동하지 않습니다.

일반적인 장애는 현상에 따라 나누어 처리할 수 있습니다. 모든 도메인이 실패하지만 IP 직접 접속은 정상이라면 수신과 업스트림을 우선 확인하세요. 프록시 노드 도메인만 실패한다면 proxy-server-nameserver와 기본 확인을 점검합니다. LAN 이름이 실패하면 검색 도메인, hosts 및 Fake-IP 제외를 확인하세요. 규칙 매칭이 예상과 다르면 도메인 정보가 유지되는지와 Geo 데이터가 로드되었는지 점검합니다. 수정 후에는 설정을 다시 로드하고 로그를 확인해야 하며, 향상 모드, 업스트림 주소 및 TUN 가로채기를 동시에 바꾸면 어떤 항목이 실제로 적용되었는지 판단하기 어렵습니다.

CHAPTER 04 / ENDPOINTS

프록시 노드 필드: 이름, 프로토콜 매개변수 및 전송 계층

proxies는 프록시 노드 객체 목록입니다. 각 객체에는 최소한 이름, 프로토콜 유형, 서버 주소, 포트와 해당 프로토콜의 인증 매개변수가 필요합니다. 노드 이름은 표시용일 뿐 아니라 정책 그룹에서 참조하므로 고유해야 합니다. 서버는 도메인 또는 IP일 수 있으며, 도메인을 사용하면 연결 전에 DNS 확인이 필요합니다. 포트는 서버가 실제로 수신하는 포트여야 하고 로컬 프록시 진입점 포트와 혼동해서는 안 됩니다. 구독에서 생성된 노드 매개변수는 보통 한 세트로 제공되므로 특정 필드 하나만 임의로 수정하면 서버와 클라이언트의 협상이 깨질 수 있습니다.

proxies:
  - name: "SS 예시"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

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

Shadowsocks 노드는 cipher와 password를 사용합니다. 암호화 방식은 서버와 일치해야 하며 필드 철자와 대소문자도 커널이 지원하는 범위에 맞아야 합니다. Trojan 노드는 보통 TLS로 연결하고 sni는 핸드셰이크에서 사용할 서버 이름을 지정합니다. skip-cert-verify를 false로 설정하면 인증서 검증을 수행하므로 정상적인 공개 인증서 환경에서는 검증을 유지해야 합니다. 인증서 이름과 연결 도메인이 다르면 검증 비활성화를 장기 해결책으로 삼지 말고 서버 설정과 구독 내용을 먼저 확인하세요.

VMess, WebSocket 및 TLS

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

VMess의 uuid, alterId, 전송 네트워크 및 TLS 매개변수는 서버와 일치해야 합니다. WebSocket 설정은 ws-opts 아래에 배치하며 경로와 Host 헤더는 전송 계층 협상에 사용됩니다. 필드 들여쓰기가 노드 객체 바깥으로 벗어나면 YAML은 파싱되더라도 커널이 이를 해당 노드의 WebSocket 매개변수로 처리하지 않습니다. gRPC, HTTP 또는 다른 전송을 사용할 때는 해당 옵션으로 바꿔야 하며 관련 없는 ws-opts를 남겨 자동 변환을 기대해서는 안 됩니다.

TLS 관련 필드는 프로토콜 객체에 따라 sni 또는 servername을 사용할 수 있습니다. 일부를 복사하기 전 현재 커널이 지원하는 필드를 대조하고 이름이 비슷하다는 이유만으로 바꾸지 마세요. 서버 주소, TLS 서버 이름 및 HTTP Host는 같을 수도 있지만 역할이 다를 수 있습니다. 서버 주소는 연결 대상을 정하고, SNI는 TLS 핸드셰이크에 참여하며, Host 헤더는 애플리케이션 계층 전송에 사용됩니다. 핸드셰이크 실패를 조사할 때는 도메인 확인 여부만 보지 말고 세 계층을 각각 점검해야 합니다.

UDP, 인터페이스 및 체인형 출구

udp: true는 노드가 UDP 처리를 허용한다는 뜻이지만 실제 사용 가능 여부는 프로토콜, 서버 및 로컬 라우팅 방식에 따라 달라집니다. 애플리케이션이 UDP 요청을 보낸다고 시스템 프록시가 자동으로 이를 라우팅하는 것은 아닙니다. 많은 시스템 프록시 설정은 주로 TCP를 대상으로 합니다. TUN 또는 투명 프록시 환경에서는 UDP를 통합 처리하기 쉽지만 올바른 라우팅과 DNS 설정이 필요합니다. 게임, 음성 또는 QUIC 연결에 문제가 생기면 먼저 트래픽이 커널로 들어오는지 확인한 뒤 노드 지원 여부를 판단해야 하며, 노드 객체의 불리언 값만으로 결론을 내려서는 안 됩니다.

interface-name, routing-mark 등의 필드는 출구 인터페이스를 제한하거나 시스템 라우팅과 연동할 때 사용하며, 주로 다중 NIC, 서버 및 라우터 환경에 등장합니다. 잘못 설정하면 프록시 연결이 다시 프록시 진입점으로 들어가 순환이 발생할 수 있습니다. 체인형 프록시는 dialer-proxy 등의 메커니즘으로 다이얼링 출구를 지정할 수 있지만 참조되는 노드나 정책 그룹이 먼저 존재해야 하고 상호 참조도 피해야 합니다. 명확한 체인 요구가 없는 일반 클라이언트 설정에는 이러한 필드를 추가하지 않는 것이 좋습니다.

구독을 가져온 뒤 추측으로 프로토콜 매개변수를 수정하지 마세요. 먼저 클라이언트에서 제공하는 설정 업데이트를 실행한 다음 노드 이름이 정책 그룹에 들어갔는지 확인합니다. 노드 목록이 비어 있다면 문제는 대개 구독 가져오기, 형식 변환 또는 제공자 로드 단계에서 발생합니다. 노드는 있지만 연결이 실패한다면 프로토콜 매개변수, DNS 및 시스템 시간을 확인하세요. 클라이언트 다운로드와 플랫폼별 차이는 클라이언트 다운로드 페이지에서 확인하고, 지원이 중단된 클라이언트의 이전은 설정 이전 단계를 참고하세요.

CHAPTER 05 / POLICY

정책 그룹 필드: 수동 선택, 자동 테스트 및 장애 조치

proxy-groups는 노드, 내장 출구 및 다른 정책 그룹을 규칙에서 참조할 수 있는 의사 결정 객체로 구성합니다. 규칙에는 보통 특정 노드 이름을 직접 쓰지 않고 정책 그룹 이름을 작성하므로 구독이 갱신되거나 노드가 바뀌어도 모든 규칙을 다시 작성할 필요가 없습니다. 대표적인 내장 출구는 DIRECT와 REJECT입니다. 전자는 대상에 직접 연결하고 후자는 매칭된 트래픽을 종료합니다. 정책 그룹 이름도 고유해야 합니다. 노드와 이름이 중복되면 읽고 관리하기 어려워지므로 “노드 선택”, “자동 선택”, “장애 조치”처럼 용도를 나타내는 이름을 권장합니다.

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "자동 선택"
      - "장애 조치"
      - "SS 예시"
      - DIRECT

  - name: "자동 선택"
    type: url-test
    proxies:
      - "SS 예시"
      - "Trojan 예시"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: "장애 조치"
    type: fallback
    proxies:
      - "SS 예시"
      - "Trojan 예시"
    url: https://www.gstatic.com/generate_204
    interval: 300

Select, URL-Test 및 Fallback

select는 수동 선택에 사용합니다. 자동 그룹, 장애 조치 그룹, 개별 노드와 직접 연결 사이에서 사용자가 명확히 전환할 수 있는 최상위 진입점으로 적합합니다. url-test는 테스트 주소로 후보를 확인하고 결과에 따라 선택합니다. 테스트 결과는 지정한 URL에 대한 연결 성능만 반영하며 모든 웹사이트, 프로토콜 및 시간대의 체감 품질과 같지 않습니다. tolerance는 결과가 비슷한 후보 사이에서 잦은 전환을 줄이는 데 사용하며 단위와 구체적인 처리는 커널 구현에 따라 달라집니다.

fallback은 목록 순서에 따라 사용 가능한 항목을 선택하고 현재 항목을 사용할 수 없을 때 다음 항목으로 전환하므로 출구 우선순위가 명확한 환경에 적합합니다. load-balance는 여러 후보에 연결을 분배하지만 세션 일관성을 고려해야 합니다. 로그인, 결제 또는 고정 출구가 필요한 서비스는 연결마다 출구가 바뀌는 방식과 맞지 않을 수 있습니다. 자동 테스트와 부하 분산 모두 “노드가 많을수록 좋다”는 뜻은 아닙니다. 후보가 지나치게 많으면 검사 요청과 관리 비용이 늘어납니다. 먼저 지역, 용도 또는 프로토콜로 필터링한 뒤 규모를 통제할 수 있는 정책 그룹을 구성하세요.

프록시 제공자로 정책 그룹 채우기

proxy-providers:
  airport:
    type: http
    url: "https://example.com/api/v1/client/subscribe?token=xxxx"
    path: ./providers/airport.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "제공자 노드"
    type: select
    use:
      - airport

proxy-providers는 원격 노드 모음을 로컬 제공자 파일로 저장합니다. type: http는 주소를 통해 업데이트한다는 뜻이고, path는 로컬 캐시 위치를 지정하며, interval은 주기적인 업데이트 간격을 지정합니다. 예시 구독 주소에는 명확한 테스트 값이 사용되므로 실제 주소는 구독 서비스에서 복사해야 하며 공개 문서나 스크린샷에 노출하지 않아야 합니다. health-check는 제공자 단위의 가용성 검사에 사용합니다. 정책 그룹 자체의 테스트와 함께 사용할 수도 있지만 두 간격이 너무 짧으면 중복 검사가 발생합니다.

정책 그룹은 use로 제공자를 참조하고 proxies로 정적 노드 또는 다른 그룹을 참조합니다. 두 출처를 커널 지원 방식에 따라 조합할 수 있지만 관리할 때는 노드의 출처를 명확히 해야 합니다. 구독 업데이트 후 노드 이름이 바뀌면 proxies에 직접 작성한 이전 이름이 작동하지 않을 수 있습니다. 동적 모음에는 제공자 참조가 더 적합합니다. 추가 필터링이 필요하다면 지원되는 커널에서 filter 또는 제외 표현식을 사용해 노드 이름을 기준으로 지역 그룹을 만들 수 있습니다. 표현식은 먼저 소수의 이름으로 테스트하여 명명 규칙 변화로 빈 그룹이 생기지 않는지 확인하세요.

정책 그룹의 의존 방향

정책 그룹은 다른 정책 그룹을 참조할 수 있지만 의존성은 단방향이어야 합니다. 예를 들어 “노드 선택”이 “자동 선택”을 참조하는 것은 합리적이지만, “자동 선택”이 다시 “노드 선택”을 참조하면 순환이 발생합니다. 정책 계층은 아래에서 위로 설계할 수 있습니다. 하위 계층에는 정적 노드와 제공자를 두고, 중간 계층에는 지역 필터링과 자동 테스트를 배치하며, 최상위에는 규칙에서 참조할 용도 그룹을 둡니다. 미디어, 업무, 다운로드 같은 용도 그룹은 최상위 출구를 참조하고 하위 속도 테스트 그룹이 업무 그룹을 참조하게 만들지는 마세요.

interval이 초 단위 주기 설정이라면 실제 필요에 따라 지정하고 지나치게 높은 빈도를 추구하지 마세요. 노드 구독 업데이트, 상태 검사 및 정책 테스트는 서로 다른 작업입니다. 구독 업데이트는 후보 모음을 바꾸고, 상태 검사는 노드 연결 가능 여부를 판단하며, 정책 테스트는 후보 중 하나를 선택합니다. 문제를 해결할 때는 각각 수동으로 실행하고 어느 단계에서 실패하는지 관찰하세요. 클라이언트 인터페이스에 자동 업데이트 주기가 별도로 있다면 전체 설정을 업데이트하는지 제공자만 업데이트하는지 확인하여 여러 타이머가 중복 요청을 보내지 않도록 해야 합니다.

CHAPTER 06 / MATCHING

규칙 문법, 매칭 순서 및 규칙 집합

rules는 순서가 있는 목록입니다. 연결은 첫 번째 규칙부터 아래로 확인하며, 매칭되면 해당 규칙의 정책을 즉시 사용하고 이후 규칙은 같은 연결에 적용하지 않습니다. 따라서 규칙의 핵심은 내용뿐 아니라 위치에도 있습니다. 구체적인 도메인, 프로세스 또는 네트워크 대역은 앞에 두고 범위가 넓은 Geo 규칙은 뒤에 배치하며 마지막에는 MATCH로 대체 처리합니다. 너무 포괄적인 규칙을 앞에 두면 아래의 정밀한 규칙은 영원히 매칭되지 않습니다.

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

DOMAIN은 전체 도메인을 정확히 매칭하고, DOMAIN-SUFFIX는 지정 도메인과 하위 도메인을 매칭하며, DOMAIN-KEYWORD는 키워드로 매칭하므로 범위가 더 넓고 같은 문자열을 포함한 다른 도메인까지 잘못 매칭할 수 있습니다. 정확한 도메인이나 접미사를 사용할 수 있다면 키워드 매칭을 우선해서는 안 됩니다. 도메인 규칙은 연결 과정에서 도메인 정보를 얻을 수 있어야 작동합니다. 애플리케이션이 IP에 직접 연결하거나 DNS 처리에서 도메인 정보가 보존되지 않으면 IP 유형 규칙으로 넘어갈 수 있습니다.

IP, 포트, 프로세스 및 네트워크 유형

IP-CIDR은 IPv4 네트워크 대역에 사용하며 IPv6에는 해당 IPv6 규칙 유형을 사용합니다. LAN 예약 주소는 보통 GeoIP보다 앞에서 직접 연결해야 합니다. no-resolve는 해당 IP 규칙을 매칭할 때 IP를 얻기 위해 도메인 확인을 능동적으로 실행하지 않는다는 뜻입니다. 추가 질의와 규칙 단계의 순환을 피할 수 있지만 적합성은 규칙 유형과 실제 트래픽에 따라 판단해야 합니다. CIDR을 사용할 때는 프리픽스 길이를 확인하세요. 너무 넓은 대역은 의도하지 않은 주소까지 포함할 수 있습니다.

rules:
  - PROCESS-NAME,example-app.exe,DIRECT
  - DST-PORT,22,노드 선택
  - NETWORK,udp,자동 선택
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,노드 선택

프로세스 규칙은 운영체제 권한과 클라이언트 커널 기능에 의존하므로 플랫폼마다 프로세스 이름을 얻는 방식이 완전히 같지 않습니다. Windows에서는 실행 파일 이름을 흔히 사용하고, macOS와 Linux에서는 프로세스 이름 또는 경로로 제공할 수 있습니다. 모바일 플랫폼에서는 데스크톱 방식으로 모든 애플리케이션을 식별하기 어렵습니다. 포트 규칙은 대상 포트만 나타낼 뿐 트래픽 용도를 증명하지 않습니다. 많은 서비스가 공유 포트를 사용하므로 포트만으로 분기하면 범위가 지나치게 넓어질 수 있습니다. NETWORK는 TCP와 UDP를 구분하지만 특정 요구를 보완하는 용도로 적합하며 도메인 및 IP 규칙을 대신해서는 안 됩니다.

Rule Provider와 동작 유형

rule-providers:
  direct-domains:
    type: http
    behavior: domain
    format: yaml
    path: ./ruleset/direct-domains.yaml
    url: https://example.com/rules/direct-domains.yaml
    interval: 86400

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

rules:
  - RULE-SET,direct-domains,DIRECT
  - RULE-SET,private-networks,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

rule-providers는 대규모 규칙을 별도 파일로 분리합니다. behavior: domain은 내용을 도메인 유형 데이터로 해석한다는 뜻이고, ipcidr은 네트워크 대역에 사용합니다. 일부 커널은 더 일반적인 규칙 집합 유형도 지원합니다. 동작 유형은 원격 파일의 내용과 일치해야 합니다. 도메인 목록을 IP 대역 유형으로 지정할 수 없고, 일반 규칙 텍스트를 순수 도메인 데이터로 바로 사용할 수도 없습니다. format은 파일 형식을 설명하며 업데이트에 실패하면 네트워크 접근, 파일 형식, 저장 경로 및 파싱 로그를 함께 확인해야 합니다.

규칙 집합 업데이트 주기와 구독 업데이트는 서로 독립적입니다. 노드 구독을 업데이트해도 외부 규칙 집합이 자동으로 새로 고쳐지는 것은 아니며, 규칙 집합을 갱신해도 노드가 바뀌지는 않습니다. GeoIP, GeoSite 및 외부 규칙 집합은 서로 다른 데이터 출처입니다. 지역 규칙이 오래되었다면 구독만 업데이트하지 말고 클라이언트가 사용하는 데이터 파일 위치와 업데이트 기능을 확인하세요. Geo 데이터 로드 문제는 도움말 센터에서 오류 현상에 따라 더 찾아볼 수 있습니다.

설명 가능한 규칙 순서 만들기

“로컬 및 LAN, 수동 정밀 규칙, 업무 규칙 집합, 지역 규칙, 최종 대체 처리” 순서를 권장합니다. 각 구간 앞에 주석을 작성하여 규칙 출처와 용도를 설명할 수 있습니다. 수동 규칙이 적다면 주 설정에 직접 작성하는 편이 확인하기 쉽고, 많으며 독립적인 업데이트가 필요할 때 규칙 제공자를 사용하세요. 여러 출처의 규칙을 기계적으로 합쳐 바로 사용하지 말고 중복 항목, 상반된 정책 및 지나치게 넓은 키워드가 있는지 확인해야 합니다.

규칙을 테스트할 때는 한 번에 하나의 구간만 수정하세요. 먼저 정확한 도메인 규칙 하나를 목록 앞부분에 추가하고 설정을 다시 로드한 뒤 해당 도메인에 접속하여 로그에서 매칭을 확인할 수 있습니다. 문법과 정책 그룹이 유효한 것을 확인한 다음 접미사나 규칙 집합으로 범위를 넓히세요. 전역 모드로 전환하는 것은 노드 연결만 검증할 뿐 규칙이 올바르다는 증거가 아닙니다. 테스트가 끝나면 규칙 모드로 돌아가 최종 MATCH 대상이 예상과 일치하는지 확인해야 합니다.

CHAPTER 07 / MAINTENANCE

오버라이드, 병합, 자동 업데이트 및 설정 문제 해결

구독 설정은 원격 내용에 따라 업데이트되므로 로컬 수정은 안정적인 사용자 지정 계층에 넣어야 합니다. 일반적인 클라이언트는 오버라이드, 병합, 확장 스크립트 또는 설정 조각 기능을 제공하지만 배열과 객체를 처리하는 방식은 서로 다를 수 있습니다. 객체 필드는 보통 키 단위로 덮어쓸 수 있습니다. 예를 들어 mode를 rule로 바꾸거나 dns에 하위 필드를 추가할 수 있습니다. 배열 필드는 전체 교체, 앞뒤 추가 또는 클라이언트가 정의한 문법으로 처리될 수 있습니다. rules, proxies, proxy-groups는 모두 배열이므로 잘못해서 전체를 덮어쓰면 구독에 있던 내용이 사라집니다.

설정을 관리할 때는 먼저 네 가지 출처를 구분해야 합니다. 원격 구독 원문, 클라이언트가 생성한 실행 설정, 로컬 오버라이드 조각, 클라이언트 자체 환경설정입니다. 인터페이스에 보이는 최종 상태는 네 가지가 병합된 결과일 수 있습니다. 문제를 해결할 때는 다운로드한 구독 파일만 열지 말고 클라이언트가 제공하는 “실행 설정 보기” 또는 로그 출력을 찾아야 합니다. 구독 업데이트 후 사용자 지정 규칙이 사라진다면 수정 내용이 원격 사본이나 캐시 계층에 들어간 것입니다. 인터페이스를 바꿔도 YAML이 변하지 않는다면 해당 항목이 클라이언트 설정에 저장되었을 가능성이 있습니다.

객체 오버라이드와 배열 추가

# 공통 오버라이드 예시, 실제 진입점은 클라이언트 지원 방식에 따름
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*.lan"
    - "*.local"

위 객체 구조는 최종 목표를 표현하는 데 적합하지만 특정 클라이언트가 배열을 어떻게 병합하는지는 설명하지 않습니다. 예를 들어 fake-ip-filter가 교체 방식이면 두 항목을 작성하는 순간 구독의 기존 목록을 덮어쓰고, 추가 방식이면 기존 목록을 유지한 채 두 항목을 더합니다. 사용하기 전에 클라이언트 문서나 실행 설정에서 동작을 확인해야 합니다. 규칙 배열에서는 삽입 위치를 특히 주의하세요. 우선 매칭해야 하는 로컬 규칙은 원격 규칙보다 앞에 들어가야 하며, MATCH 뒤에 추가하면 트래픽이 대체 규칙에서 이미 끝났기 때문에 적용되지 않습니다.

정책 그룹에도 같은 문제가 있습니다. “노드 선택”에 로컬 그룹 하나를 추가하려고 원격 정책 그룹 목록 전체를 복사해 장기간 관리하면 구독 업데이트 후 새 그룹이 사본에 자동으로 들어오지 않습니다. 더 안정적인 방법은 클라이언트가 제공하는 그룹 단위 오버라이드, 스크립트 처리 또는 제공자 참조를 사용하여 최종 설정에서 대상 그룹만 변경하는 것입니다. 클라이언트가 세밀한 병합을 지원하지 않는다면 사용자 지정 범위를 줄이거나 장기 규칙을 독립 규칙 제공자에 넣으세요.

자동 업데이트의 세 가지 계층

자동 업데이트에는 최소한 전체 구독, 프록시 제공자 및 규칙 제공자의 세 계층이 포함됩니다. 전체 구독 업데이트는 보통 클라이언트가 예약 실행하며 완료 후 전체 설정을 다시 생성합니다. proxy-providers.interval은 노드 집합을 업데이트하고, rule-providers.interval은 규칙 집합을 업데이트합니다. 이 셋을 하나의 스위치로 생각해서는 안 됩니다. 구독 주소가 바뀌었을 때 규칙 제공자만 새로 고쳐도 새 노드는 얻을 수 없으며, 규칙 집합이 오래되었을 때 노드 구독만 새로 고쳐도 규칙 데이터는 바뀌지 않습니다.

주기를 설정할 때는 내용 변화 빈도와 클라이언트 실행 방식을 고려해야 합니다. 데스크톱 클라이언트를 장시간 종료해 두면 타이머가 백그라운드에서 실행되지 않으므로 다시 시작한 뒤 업데이트 시간을 직접 확인해야 합니다. 업데이트 성공이 실행 설정 재로드를 의미하지도 않습니다. 일부 클라이언트는 자동 적용하지만 일부는 수동 전환이나 재로드가 필요합니다. 안정적인 순서는 업데이트 실행, 출처 상태 확인, 최종 설정 재로드, 정책 그룹 선택 유지 여부 확인, 접속 테스트입니다.

확인 오류부터 연결 오류까지의 점검 흐름

첫 번째 계층은 YAML 파싱입니다. 흔한 메시지로는 들여쓰기 오류, 콜론 뒤 공백 누락, 닫히지 않은 따옴표, 잘못된 목록 계층 및 중복 키가 있습니다. 처리할 때는 오류가 표시된 줄의 위아래 여러 줄을 함께 확인하세요. 실제 구조 오류가 표시된 줄보다 앞에 있을 수 있습니다. 특수 문자가 포함된 값은 먼저 따옴표로 감싸고, 웹에서 복사한 굽은 따옴표와 전각 문장 부호는 일반 YAML 문자로 바꿔야 합니다. 파싱을 통과한 뒤에는 필드 검증으로 넘어가 유형이 올바른지 확인하세요. 예를 들어 포트는 숫자이고 불리언 값은 true 또는 false여야 합니다.

두 번째 계층은 참조 검증입니다. 규칙 대상이 정책 그룹이나 내장 출구에 존재하는지, 정책 그룹 구성원이 노드·제공자·다른 그룹에 존재하는지, 규칙 제공자 이름이 RULE-SET 참조와 일치하는지 하나씩 확인하세요. 이름 사이의 공백은 눈으로 확인하기 어려우므로 임시로 이름을 복사해 검색하면 됩니다. 세 번째 계층은 리소스 로드입니다. 구독, 프록시 제공자, 규칙 제공자 및 Geo 데이터를 읽을 수 있는지 확인하세요. 네트워크 업데이트가 실패해도 이전 캐시가 남아 있으면 커널이 계속 시작될 수 있으므로 업데이트 시간과 로그를 함께 봐야 합니다.

네 번째 계층은 연결 수립입니다. 노드 시간 초과가 발생하면 서버 확인, 대상 포트, 로컬 네트워크 및 프로토콜 매개변수를 먼저 점검하세요. TLS 핸드셰이크 실패는 시스템 시간, 서버 이름 및 인증서를 확인하고, UDP만 이상하면 라우팅 방식과 노드 기능을 확인합니다. 특정 도메인만 이상하다면 DNS와 규칙 매칭으로 돌아가세요. 다섯 번째 계층은 시스템 트래픽 진입점입니다. 브라우저 설정, 시스템 프록시, TUN 라우팅 및 애플리케이션 자체 프록시가 현재 구성과 일치해야 합니다. 설정 파일이 완전히 올바르더라도 시스템 트래픽이 커널로 들어오지 않으면 접속 결과는 바뀌지 않습니다.

수정을 완료한 뒤 반복 가능한 검증 절차를 남겨 두세요. 설정을 다시 로드하여 커널이 시작되는지 확인하고, 제공자를 업데이트하여 노드와 규칙 집합을 읽을 수 있는지 확인한 다음 정책 그룹 선택을 점검합니다. 이어서 직접 연결되어야 하는 도메인 하나와 프록시를 사용해야 하는 도메인 하나에 접속하고, 마지막으로 로그의 매칭 결과를 확인하세요. 문제가 여전히 분류되지 않는다면 도움말 센터에서 설치 및 설정, 사용 팁, 문제 해결 항목별로 다시 확인할 수 있습니다. 전체 YAML의 로드 순서를 다시 이해하려면 설정 파일 YAML 구조 분석을 참고하세요. 기본 가져오기를 다시 진행해야 한다면 입문 가이드로 돌아가 구독이 검증되기 전에 오버라이드를 더 추가하지 마세요.