Clash 설정 파일 완벽 가이드: YAML, DNS, 정책 그룹과 규칙 문법

01 / YAML STRUCTURE

YAML 구조 개요

설정 파일은 어떤 영역으로 구성되는가

Clash 설정 파일은 하나의 YAML 매핑입니다. 최상위 키는 수신 포트, 실행 모드, DNS 동작, 프록시 노드, 정책 그룹, 규칙 및 외부 Provider를 정의합니다. 커널은 파일을 읽을 때 먼저 YAML 문법을 해석한 다음 필드 형식과 참조 관계를 확인하고, 마지막으로 프록시·정책 그룹·규칙 사이의 실행 흐름을 구성합니다. 문법이 올바르다는 것은 YAML을 읽을 수 있다는 뜻일 뿐, 모든 노드에 연결할 수 있거나 정책 그룹 참조가 완전하다는 의미는 아닙니다. 따라서 문제를 해결할 때는 ‘텍스트 문법’, ‘필드 구조’, ‘이름 참조’, ‘네트워크 연결’의 네 가지 층위로 나누어 확인해야 합니다.

일반적인 최상위 영역에는 mixed-port, allow-lan, mode, log-level, external-controller, dns, proxies, proxy-groups, rules, proxy-providers, rule-providers가 있습니다. 모든 설정 파일에 이 필드를 빠짐없이 작성할 필요는 없습니다. 클라이언트 화면에서 시스템 프록시를 관리하는 경우 포트와 컨트롤러 주소를 클라이언트가 생성할 수 있고, 구독 제공업체가 설정을 생성하는 경우 노드와 정책 그룹이 구독 갱신에 따라 함께 업데이트됩니다. 수동 설정에서는 어떤 필드가 기본 실행 매개변수이고 어떤 필드가 구독 갱신 시 교체되는지 구분하는 것이 중요합니다.

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

external-controller: 127.0.0.1:9090

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query

proxies:
  - name: Example-Trojan
    type: trojan
    server: proxy.example.com
    port: 443
    password: "your-password"
    sni: proxy.example.com

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

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

위 예제는 최소한의 관계 순환 구조를 보여 줍니다. 규칙이 요청을 ‘노드 선택’으로 전달하고, 정책 그룹이 다시 요청을 특정 노드 또는 DIRECT로 전달합니다. 규칙 끝의 대상 이름은 정책 그룹 이름과 완전히 일치해야 하며, 정책 그룹의 노드 이름도 proxies 항목과 일치해야 합니다. 이름 비교에서는 일반적으로 문자, 공백, 전각·반각 차이를 구분합니다. “노드 선택”과 “노드 선택 ”은 비슷해 보여도 실제로는 서로 다른 이름입니다. 이름을 변경할 때는 모든 참조 위치도 함께 수정해야 합니다.

들여쓰기, 시퀀스와 스칼라

YAML은 들여쓰기로 계층을 표현합니다. 두 칸 들여쓰기를 일관되게 사용하고 탭은 사용하지 않는 것이 좋습니다. 하이픈으로 시작하는 항목은 시퀀스이며, 예를 들어 proxies 아래의 각 노드와 rules 아래의 각 규칙이 이에 해당합니다. 콜론 뒤에는 반드시 공백을 넣어야 합니다. 문자열 자체에 콜론, 샵, 대괄호가 포함되거나 앞뒤 공백이 있을 때는 따옴표를 사용하면 모호함을 줄일 수 있습니다. 비밀번호, UUID, 도메인, 노드 이름은 문자열로 처리하는 것이 적절하고, 포트·간격·동시 실행 수는 보통 숫자를 사용합니다. 스위치 값은 true 또는 false를 사용합니다.

따옴표로 감싸지 않은 샵은 주석의 시작을 의미합니다. 예를 들어 password: abc#123에서는 abc만 값으로 처리될 수 있으므로 올바른 표기는 password: "abc#123"입니다. 불리언 값도 명확한 true와 false를 사용해야 하며, YAML 파서에 따라 불리언으로 해석될 수 있는 단어는 피하는 것이 좋습니다. 노드 이름에 쉼표가 있어도 노드 객체 자체가 바로 깨지지는 않지만, 해당 이름을 쉼표로 구분하는 규칙이나 일부 축약 필드에 넣으면 해석이 모호해질 수 있습니다. 따라서 노드와 정책 그룹 이름은 짧고 고유하며 제어 문자를 포함하지 않도록 정하는 것이 좋습니다.

해석 순서와 참조 확인

설정 파일의 작성 순서는 주로 가독성을 위한 것이므로 최상위 영역을 반드시 정해진 순서로 배치할 필요는 없습니다. 다만 규칙 목록 내부의 순서는 실행 결과에 영향을 줍니다. 노드를 정책 그룹보다 먼저 작성하거나 정책 그룹을 규칙보다 먼저 작성해도 되며, 커널은 전체 설정을 해석한 뒤 참조를 구성합니다. “프록시를 찾을 수 없음” 또는 “정책 그룹이 존재하지 않음” 오류가 발생하면 먼저 오류 메시지의 이름을 복사해 정의 부분과 한 글자씩 대조하고, 해당 이름이 Provider에서 동적으로 제공되는지도 확인하세요. Provider가 아직 정상적으로 로드되지 않았다면 이를 참조하는 정책 그룹이 잠시 비어 있을 수 있습니다.

설정 테스트는 일부 YAML 조각이 아니라 완성된 파일부터 시작해야 합니다. 조각이 문법 검사를 통과해도 원본 파일에 다시 넣었을 때 계층이 올바르다는 보장은 없습니다. 클라이언트에서 설정이 유효하지 않다고 표시되면 먼저 원본 파일을 백업한 뒤, 최근 추가한 영역을 블록 단위로 제거하며 이분 탐색 방식으로 오류를 찾으세요. 문제가 구독 업데이트 이후 발생했다면 구독 링크와 설정 가져오기 안내를 참고해 가져온 내용이 구독 주소인지, 완전한 YAML인지, 노드 정보만 포함한 내용인지 확인하세요.

02 / GENERAL FIELDS

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

수신 포트 선택 방법

port는 HTTP 프록시, socks-port는 SOCKS5 프록시에 사용되며, mixed-port는 하나의 포트에서 HTTP와 SOCKS5 요청을 모두 받을 수 있습니다. 데스크톱 클라이언트는 보통 하나의 mixed-port만 사용하고, 애플리케이션의 프록시 주소를 127.0.0.1과 해당 포트로 설정합니다. 포트는 로컬 수신 진입점일 뿐 원격 노드의 포트가 아닙니다. 노드 객체의 port는 원격 서버 포트를 뜻하므로 이름은 같아도 계층과 용도가 다릅니다.

수신 포트는 다른 프로그램이 사용 중인 포트와 겹치면 안 됩니다. 시작 로그에 address already in use, bind failed 또는 유사한 메시지가 나타나면 먼저 남아 있는 프로세스를 종료하거나 로컬 수신 포트를 사용되지 않는 값으로 변경하세요. 클라이언트 화면에서 포트 설정을 자동으로 기록한다면 화면에서 최종 생성한 실행 설정을 기준으로 삼아야 합니다. 구독 원본 파일만 수정했는데 클라이언트가 이후 로컬 오버라이드를 적용하면 실제 실행 포트가 파일 내용과 다를 수 있습니다.

필드	용도	일반적인 사용 방법	확인할 점
port	HTTP 프록시 수신 포트	HTTP 프록시만 지원하는 프로그램에서 사용	프로그램의 프록시 유형과 포트가 일치하는지 확인
socks-port	SOCKS5 프록시 수신 포트	SOCKS5를 지원하는 프로그램에서 사용	원격 노드 포트를 잘못 입력하지 않기
mixed-port	혼합 프록시 수신 포트	데스크톱 클라이언트에서 자주 사용하는 통합 진입점	포트 사용 여부와 시스템 프록시 설정 확인
redir-port	투명 프록시 리디렉션 진입점	특정 Linux 네트워크 구성	시스템 라우팅 및 방화벽 규칙과 함께 사용해야 함
tproxy-port	TPROXY 투명 프록시 진입점	Linux 라우터 또는 게이트웨이	커널과 정책 라우팅 지원 필요

allow-lan과 수신 주소

allow-lan은 로컬 네트워크 기기가 이 컴퓨터의 프록시를 사용할 수 있는지 제어합니다. false로 설정하면 일반적으로 로컬 연결만 처리하고, true로 설정한 뒤에는 bind-address, 운영체제 방화벽, 현재 네트워크 유형을 함께 확인해야 다른 기기에서 접근할 수 있습니다. 로컬 네트워크에서 프록시를 공유할 때는 신뢰할 수 있는 네트워크에서만 활성화하고, 제어 인터페이스와 프록시 진입점의 접근 범위를 명확히 설정하세요. 공용 네트워크에서는 컨트롤러나 프록시 포트를 신뢰할 수 없는 기기에 노출해서는 안 됩니다.

mixed-port: 7890
allow-lan: true
bind-address: 0.0.0.0
authentication:
  - "device-user:your-password"

예제의 인증은 프록시 진입점에 적용됩니다. 구체적인 클라이언트와 커널이 인증 필드를 지원하는 방식은 실제 실행 설정을 기준으로 확인해야 합니다. 로컬에서만 사용할 경우 allow-lan: false를 유지하는 것이 가장 간단합니다. 로컬 네트워크 기기에서 연결할 수 없다면 로컬 네트워크 주소, 포트 수신 범위, 방화벽 인바운드 규칙, 같은 네트워크에 연결되어 있는지, 모바일 기기에서 프록시 유형을 잘못 입력하지 않았는지를 순서대로 확인하세요.

mode의 일반적인 세 가지 값

mode: rule은 rules를 위에서 아래로 매칭하며 일상적인 사용에 가장 적합한 모드입니다. mode: global은 연결을 전역 정책 그룹으로 전달하므로 특정 노드의 사용 가능 여부를 임시로 확인할 때 유용하지만 세밀한 분류를 우회합니다. mode: direct는 연결이 직접 접속하도록 하여 문제가 프록시 경로에서 발생했는지 확인할 때 적합합니다. 문제 해결 중에는 비교를 위해 잠시 모드를 전환할 수 있지만, 확인이 끝나면 원래 목적의 모드로 돌아가고 전역 모드를 규칙 누락을 수정하지 않는 장기 대안으로 사용하지 마세요.

모드는 트래픽이 정책으로 들어가는 방식만 결정하며 DNS 해석, 시스템 프록시 미활성화, TUN 미인계, 애플리케이션의 프록시 우회 문제를 자동으로 해결하지 않습니다. 브라우저는 접속되지만 명령줄 도구가 접속되지 않는다면 브라우저는 시스템 프록시를 따르고 명령줄 프로그램은 시스템 프록시 설정을 읽지 않는 경우가 흔합니다. 이때는 프로그램에 HTTP 또는 SOCKS5 프록시를 명시적으로 설정하거나 올바르게 구성된 TUN 모드를 사용해야 합니다.

로그, IPv6와 컨트롤러

log-level의 일반적인 값은 silent, error, warning, info, debug입니다. 평상시에는 info면 충분하며, 설정과 연결 문제를 확인할 때만 일시적으로 debug로 바꾼 뒤 점검이 끝나면 되돌리는 것이 좋습니다. 로그를 읽을 때는 마지막 줄만 보지 말고 가장 먼저 발생한 오류를 찾으세요. 이후의 대량 연결 실패는 최초 DNS 또는 설정 오류가 연쇄적으로 발생한 결과일 수 있습니다.

ipv6은 커널의 관련 네트워크 동작에서 IPv6를 활성화할지 결정합니다. 네트워크 자체에 안정적인 IPv6 라우팅이 없다면 무작정 활성화할 경우 해석 결과는 얻지만 연결 경로를 사용할 수 없는 상황이 생길 수 있습니다. DNS 영역에는 별도의 dns.ipv6도 있으며, 이는 AAAA 결과를 반환할지 제어합니다. 최상위 IPv6와 DNS IPv6는 실제 네트워크 조건을 함께 고려해 설정해야 하며, 한쪽만 수정해서는 안 됩니다.

external-controller는 클라이언트 화면과 커널이 통신하는 제어 인터페이스이며, 일반적인 형식은 127.0.0.1:9090입니다. 루프백 주소에 바인딩하면 로컬에서만 접근할 수 있습니다. secret을 설정했다면 제어 측에서 해당 인증 정보를 함께 보내야 합니다. 컨트롤러 포트와 프록시 포트는 용도가 다르므로 시스템 프록시를 컨트롤러 포트로 지정하면 안 됩니다. 그래픽 클라이언트는 보통 이 필드를 자동 관리하므로 수동 수정 전에 시작 시 클라이언트가 값을 덮어쓰는지 확인하세요.

03 / DNS PIPELINE

DNS 설정과 해석 경로

DNS 모듈이 처리하는 문제

DNS 영역은 도메인을 어떤 서버가 해석할지, 어떤 전송 방식을 사용할지, Fake IP를 반환할지, 그리고 해석 요청 자체를 직접 연결로 보낼지 프록시로 보낼지를 결정합니다. 브라우저에 연결 실패가 표시되면 노드 경로와 DNS 경로를 따로 확인해야 합니다. 노드가 연결을 설정할 수 있어도 도메인이 올바르게 해석되었다는 뜻은 아니며, DNS가 주소를 반환해도 해당 주소로 가는 연결 경로가 도달 가능하다는 뜻은 아닙니다. DNS 설정의 목표는 해석 출처, 분류 규칙, 실제 연결 출구를 일치시키는 것입니다.

dns.enable은 커널 DNS 모듈을 활성화합니다. TUN, Fake IP를 사용하거나 시스템 해석 경로와 프록시 분류가 분리되는 것을 막아야 할 때는 일반적으로 활성화해야 합니다. listen은 DNS 서비스의 수신 주소를 지정하며, 예를 들어 0.0.0.0:1053처럼 작성합니다. 데스크톱 GUI는 커널 내부에서 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
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query

default-nameserver와 nameserver

default-nameserver는 주로 암호화된 DNS 서버 자체의 도메인을 해석하고 업스트림 연결을 시작하기 전에 기본 해석을 제공하는 데 사용됩니다. 여기에는 직접 접근할 수 있는 IP 주소 형식의 DNS를 작성하는 것이 일반적이며, 여전히 도메인 해석이 필요한 DoH 주소만 입력하는 것은 피해야 합니다. 그렇지 않으면 “DNS 서버의 도메인을 해석하려면 먼저 해당 DNS 서버에 접속해야 하는” 의존 고리가 생길 수 있습니다. nameserver는 주요 업스트림으로 일반 UDP DNS, DoT 또는 DoH를 사용할 수 있습니다. 업스트림을 선택할 때는 프로토콜 이름이 복잡한지보다 로컬 네트워크에서 도달 가능한지와 분류 출구를 고려해야 합니다.

proxy-server-nameserver는 프록시 서버 도메인을 해석하는 데 사용됩니다. 노드의 server에 도메인을 입력했다면 커널은 노드에 연결하기 전에 해당 도메인의 주소를 먼저 얻어야 합니다. 이 단계가 아직 구축되지 않은 프록시에 잘못 의존하면 시작 과정에서 순환 의존이 발생합니다. 프록시 서버에 독립적이고 직접 접근 가능한 해석 업스트림을 제공하면 이런 문제를 줄일 수 있습니다. 노드 서버에 IP를 직접 입력하면 해석은 필요 없지만 서버 주소가 바뀌어도 DNS를 통한 자동 갱신은 사용할 수 없습니다.

nameserver-policy는 도메인 또는 geosite 분류에 따라 업스트림을 지정할 수 있습니다. 이는 “어떤 종류의 도메인을 어느 DNS 그룹에 조회할지”를 정하는 기능이지 “최종 연결을 어느 프록시로 보낼지”를 정하는 기능은 아닙니다. 연결 출구는 여전히 rules가 결정합니다. DNS 정책과 트래픽 규칙은 비슷한 도메인 집합을 사용할 수 있지만 적용 단계가 다릅니다. 한쪽을 수정할 때는 다른 쪽도 여전히 예상대로 작동하는지 확인해야 합니다.

Fake IP와 Redir Host

enhanced-mode: fake-ip는 예약된 주소 범위에서 매핑 주소를 도메인에 반환합니다. 애플리케이션이 이 주소에 연결하면 커널이 매핑을 통해 원래 도메인을 복원한 뒤 규칙 매칭과 프록시 전달을 수행합니다. 이렇게 하면 도메인 정보를 유지할 수 있어 애플리케이션이 시스템 단계에서 실제 해석을 먼저 완료해 분류에서 도메인 맥락이 사라지는 상황을 줄일 수 있습니다. fake-ip-range는 별도로 예약된 주소 범위를 사용해야 하며 현재 로컬 네트워크, VPN 또는 다른 가상 네트워크 대역과 겹치면 안 됩니다.

일부 로컬 네트워크 서비스, 기기 검색, 시간 동기화, 게임 플랫폼 또는 실제 주소 결과에 의존하는 프로그램은 Fake IP와 맞지 않을 수 있으므로 fake-ip-filter에 추가할 수 있습니다. 필터 범위가 너무 넓으면 많은 도메인이 실제 해석으로 돌아가 Fake IP의 일관성이 약해지고, 너무 좁으면 로컬 네트워크 서비스를 찾지 못하거나 애플리케이션이 예약 주소를 거부할 수 있습니다. 출처가 불분명한 긴 목록을 그대로 복사하지 말고 로그와 실제 도메인을 기준으로 하나씩 추가하세요.

redir-host는 실제 해석 주소를 반환한 뒤 연결 과정에서 다시 매칭합니다. 일부 기존 투명 프록시 환경과의 호환성은 좋지만, 일부 경로에서는 도메인 정보가 부족할 수 있습니다. 강화 모드를 선택할 때는 먼저 클라이언트가 TUN, 시스템 프록시, 라우터 투명 프록시 중 무엇을 사용하는지 확인한 다음 실제 애플리케이션 호환성으로 검증하세요. 모드를 전환한 뒤에는 운영체제와 브라우저의 DNS 캐시를 지워야 하며, 그렇지 않으면 이전 결과가 테스트에 계속 영향을 줄 수 있습니다.

DNS 장애 확인 순서

첫째, 커널 DNS 모듈이 시작되었고 로그에 포트 사용 중 또는 설정 해석 오류가 없는지 확인합니다. 둘째, 일반 도메인을 직접 조회해 결과가 반환되는지 확인합니다. Fake IP 모드에서 예약 주소가 반환되는 것은 정상입니다. 셋째, 노드 서버 도메인이 proxy-server-nameserver를 통해 해석되는지 테스트합니다. 넷째, 대상 도메인이 어떤 규칙에 매칭되고 어느 정책 그룹으로 연결되는지 확인합니다. 다섯째, 운영체제가 여전히 다른 인터페이스로 DNS 요청을 보내고 있지 않은지 확인합니다.

이른바 DNS 누출은 보통 “어떤 해석 요청이 예상한 경로를 우회했는가”와 관련됩니다. 서로 다른 DNS 서비스가 다른 결과를 반환한다는 사실만으로 원인을 단정할 수는 없습니다. 브라우저가 별도의 보안 DNS를 사용하거나, 시스템에 다른 네트워크 인터페이스가 남아 있거나, 애플리케이션이 자체적으로 DoH를 요청할 수도 있습니다. 문제를 확인할 때는 먼저 브라우저·시스템·커널의 DNS 경로를 통일한 뒤 필요한 기능을 하나씩 다시 활성화하세요. TUN 환경에서는 DNS 하이재킹 설정이 UDP와 TCP 조회를 모두 처리하는지도 확인해야 합니다.

증상	우선 확인할 항목	일반적인 원인
노드 도메인을 해석할 수 없음	proxy-server-nameserver	해석 경로가 아직 구축되지 않은 프록시에 의존함
로컬 네트워크 기기 이름이 작동하지 않음	fake-ip-filter	로컬 도메인에 Fake IP가 할당됨
AAAA는 반환되지만 연결 시간이 초과됨	dns.ipv6와 실제 네트워크	IPv6 해석은 가능하지만 라우팅이 불가능함
DNS를 수정해도 변화가 없음	시스템 및 브라우저 캐시	이전 해석 결과가 아직 캐시 기간에 있음

04 / PROXY DEFINITIONS

프록시 노드 필드

노드 객체의 공통 구조

proxies는 노드 객체의 시퀀스입니다. 각 객체에는 최소한 고유한 name, 프로토콜 type, 서버 server, 원격 port가 필요하며 나머지 인증 및 전송 필드는 프로토콜에 따라 달라집니다. 노드 이름은 로컬 설정에서 참조 식별자로만 사용되며 서버 매개변수를 바꾸지 않습니다. 정책 그룹과 규칙을 관리하기 쉽도록 이름에 지역이나 용도를 표시하되 안정적으로 유지하세요. 구독을 갱신할 때마다 이름이 바뀌면 수동 정책 그룹의 직접 참조가 쉽게 끊어집니다.

server에는 도메인 또는 IP를 사용할 수 있습니다. 도메인은 서버 이전에 유리하지만 DNS에 의존하고, IP는 한 번의 해석을 줄여 주지만 주소 변경 시 설정을 갱신해야 합니다. udp는 해당 노드가 UDP 트래픽을 처리할 수 있는지 나타내며, 실제 사용 가능 여부는 프로토콜·서버·네트워크 경로에도 달려 있습니다. 클라이언트에서 UDP 옵션만 켠다고 UDP를 지원하지 않는 서버가 UDP를 지원하게 되지는 않습니다.

Shadowsocks와 Trojan 예제

proxies:
  - name: Example-SS
    type: ss
    server: ss.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

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

Shadowsocks의 cipher는 서버와 일치해야 하며 비밀번호도 문자열로 처리해야 합니다. 암호화 방식마다 요구하는 키가 다르므로 클라이언트에서 이름만 바꿔서는 안 됩니다. Trojan은 일반적으로 TLS로 연결하며, sni는 TLS 핸드셰이크에서 사용할 서버 이름을 지정하므로 보통 서버가 요구하는 도메인을 입력합니다. skip-cert-verify: false는 인증서를 정상적으로 검증한다는 뜻입니다. 인증서 이름이 일치하지 않으면 먼저 서버 도메인, SNI, 시스템 시간, 서버 인증서 설정을 확인하고 인증서 검증 해제를 장기 해결책으로 사용하지 마세요.

VMess와 VLESS의 인증 및 전송 필드

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

  - name: Example-VLESS
    type: vless
    server: vless.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000000
    network: tcp
    tls: true
    servername: vless.example.com
    udp: true

uuid는 인증 식별자이며 표준 형식을 유지하고 서버와 일치해야 합니다. 예제 UUID는 구조를 보여 주기 위한 것일 뿐 실제 연결 매개변수로 사용할 수 없습니다. VMess 설정의 alterId, cipher 등의 필드는 서버가 제공한 값에 맞춰 입력해야 합니다. VLESS의 전송 및 흐름 제어 필드는 서버 구성에 따라 달라집니다. 클라이언트가 특정 필드를 지원한다고 해서 임의로 추가하면 서버가 호환된다는 뜻은 아닙니다.

network는 TCP, WebSocket, gRPC와 같은 전송 계층 형태를 설명합니다. WebSocket을 사용할 때는 ws-opts.path와 Host 요청 헤더가 서버의 리버스 프록시 설정과 일치해야 합니다. gRPC를 사용할 때는 서비스 이름을 확인하세요. TLS 관련 servername, SNI, ALPN, 지문 필드는 핸드셰이크 매개변수이므로 어느 하나라도 서버 진입점과 다르면 연결 직후 종료되는 것처럼 보일 수 있습니다.

프로토콜 필드는 노드 간에 그대로 복사하면 안 됩니다

노드 객체에는 모든 프로토콜에 적용되는 완전한 공통 필드 표가 없습니다. 같은 이름의 필드라도 커널 버전이나 프로토콜 구현에 따라 제약이 다를 수 있습니다. 가장 안전한 출처는 서버 또는 구독이 생성한 매개변수이며, 이를 현재 커널이 지원하는 구조에 맞춰 정리해야 합니다. 다른 노드의 TLS, WebSocket 또는 플러그인 매개변수를 통째로 복사하면 필드는 존재하지만 의미가 맞지 않을 수 있습니다. 파서는 이를 받아들여도 연결은 실패할 수 있습니다.

구독 링크는 보통 제공업체가 노드 매개변수를 관리합니다. 사용자가 수정해야 하는 부분은 대개 노드 이름, 정책 그룹 구성, 트래픽 분류 규칙이지 프로토콜 하위 필드가 아닙니다. 구독을 가져온 뒤 모든 노드가 동시에 작동하지 않는다면 먼저 구독 유효성, 시스템 시간, DNS, 로컬 네트워크를 확인하세요. 하나의 노드만 실패한다면 해당 노드의 서버·포트·인증·전송 설정을 대조하세요. 노드 선택 방법은 지연 시간, 지역, 배율과 프로토콜 판단에서 확인할 수 있습니다.

노드 사용 가능 여부와 지연 시간 테스트의 범위

지연 시간 테스트는 일반적으로 테스트 주소에 요청을 보내 완료 시간을 기록합니다. 이는 특정 시점과 테스트 경로의 응답을 나타낼 뿐 모든 웹사이트의 접속 품질과 같지는 않습니다. 테스트 시간 초과는 노드에 접근할 수 없거나 테스트 주소가 차단되었거나 DNS가 실패했거나 정책 그룹 참조가 잘못되어 발생할 수 있습니다. 지연 시간이 짧다고 대역폭, 안정성, 대상 지역 접속성이 반드시 더 좋은 것도 아닙니다. 노드를 선택할 때는 연속 테스트, 실제 대상 사이트, 지속 연결 성능을 함께 고려하세요.

노드 객체는 정상적으로 로드되었지만 정책 그룹에 보이지 않는다면 정책 그룹이 해당 노드를 참조하지 않거나 Provider 필터 조건에서 제외했을 가능성이 큽니다. 구독 업데이트 후 노드 이름이 바뀌면 정적 proxies 목록의 참조도 끊어집니다. 장기적으로 유지할 설정에는 proxy-providers와 use를 함께 사용하고 안정적인 필터 규칙으로 노드를 구성하는 편이 좋습니다. 여러 정책 그룹에 많은 이름을 반복해서 작성하는 방식은 피하세요.

05 / POLICY GROUPS

정책 그룹 필드와 선택 로직

정책 그룹은 규칙과 노드 사이의 중간 계층입니다

proxy-groups는 노드, 내장 동작, 다른 정책 그룹을 선택 가능한 출구로 구성합니다. 규칙은 보통 변경될 수 있는 특정 노드 이름이 아니라 “노드 선택”, “스트리밍”, “다운로드 서비스”처럼 안정적인 정책 그룹을 가리킵니다. 이렇게 하면 구독 노드가 바뀌어도 모든 규칙을 다시 작성하지 않고 정책 그룹의 구성원만 조정하면 됩니다. 정책 그룹은 중첩할 수 있지만 순환 참조는 피해야 합니다. A가 B를 참조하고 B가 다시 A를 참조하면 유효한 출구를 구성할 수 없습니다.

내장 대상에는 일반적으로 DIRECT, REJECT 및 호환 커널이 제공하는 기타 동작이 있습니다. DIRECT는 직접 연결, REJECT는 요청 거부를 뜻합니다. 규칙 대상은 정책 그룹, 특정 노드, 내장 동작 중 하나가 될 수 있습니다. 유지 관리성을 높이려면 몇 가지 고정된 상황을 제외하고 규칙이 정책 그룹을 가리키도록 한 뒤 실제 출구는 정책 그룹에서 결정하는 것이 좋습니다.

select, url-test, fallback과 load-balance

유형	선택 방식	적합한 상황	주의 사항
select	사용자가 구성원을 직접 선택	주 정책, 지역 선택, 고정 업무	선택 결과를 위해 구성원 이름을 안정적으로 유지해야 함
url-test	테스트 결과에 따라 응답이 빠른 구성원 선택	같은 용도의 노드를 자동 선택	테스트 주소와 간격이 결과에 영향을 줌
fallback	현재 구성원에 장애가 발생하면 전환	우선순위가 명확한 예비 경로	복구 및 전환 속도는 확인 주기에 따라 달라짐
load-balance	정책에 따라 연결을 분배	여러 사용 가능한 출구로 연결 분산	단일 연결의 대역폭을 합산하는 기능은 아님

select가 가장 이해하기 쉽습니다. 구성원 순서가 화면 표시 순서를 결정하고 현재 선택은 클라이언트가 저장합니다. url-test는 지정한 URL에 주기적으로 요청을 보내 결과에 따라 자동으로 선택합니다. interval은 확인 간격을, tolerance는 결과가 비슷할 때 잦은 전환을 줄이는 기준을 제어합니다. 확인이 너무 잦으면 노드 요청이 늘고, 간격이 너무 길면 경로 변화를 제때 반영하지 못합니다. 테스트 주소는 안정적이고 응답 본문이 작으며 예상 네트워크 경로를 대표할 수 있어야 합니다.

fallback은 구성원 순서대로 우선순위를 유지하며 현재 노드를 사용할 수 없을 때 다음 사용 가능한 구성원을 선택하므로 주·예비 관계가 분명한 설정에 적합합니다. load-balance는 여러 노드에 연결을 분배하며 구체적인 분배 방식은 strategy 등의 필드에 따라 달라집니다. 하나의 다운로드 연결을 여러 노드로 나누거나 단일 노드 및 대상 서버의 대역폭 제한을 넘어설 수는 없습니다. 동일한 대상 세션에서 출구를 안정적으로 유지해야 한다면 일관성을 보장할 수 있는 전략을 선택하세요.

proxy-groups:
  - name: 노드 선택
    type: select
    proxies:
      - 자동 선택
      - 장애 전환
      - DIRECT

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

  - name: 장애 전환
    type: fallback
    proxies:
      - Example-Trojan
      - Example-SS
    url: https://www.gstatic.com/generate_204
    interval: 300

정책 그룹 중첩과 업무별 계층화

명확한 계층은 보통 “전체 진입점—지역 또는 자동 선택—특정 노드”로 구성됩니다. 예를 들어 규칙이 일반 프록시 트래픽을 “노드 선택”으로 보내고, “노드 선택”이 “자동 선택”, “장애 전환” 및 여러 지역 그룹을 포함하며, 지역 그룹이 다시 해당 노드를 포함하도록 구성할 수 있습니다. 이렇게 하면 자동 정책을 사용하면서도 지역을 수동으로 고정할 수 있습니다. 중첩 단계가 너무 깊으면 화면에서 선택하는 경로와 장애 위치를 찾는 과정이 길어집니다.

업무별 그룹은 출구 요구 사항을 표현해야 하며 노드 목록을 단순히 복사해서는 안 됩니다. 예를 들어 “스트리밍”은 지역 그룹을 참조하고, “개발 서비스”는 주 선택 그룹을 참조하며, “직접 연결 서비스”에는 DIRECT만 포함할 수 있습니다. 여러 업무 그룹이 같은 지역 그룹을 참조하면 노드 관리를 한 곳에 집중할 수 있습니다. 모든 업무 그룹에 수십 개의 노드를 반복해서 적으면 구독 업데이트 후 구성원 차이와 누락이 발생하기 쉽습니다.

Provider 구성원과 필터

정책 그룹은 use를 사용해 하나 이상의 proxy-providers를 참조하고 외부 노드 집합에서 구성원을 동적으로 가져올 수 있습니다. 일부 커널은 filter, exclude-filter 등의 필터링 방식도 지원합니다. 필터는 보통 정규 표현식을 사용하므로 먼저 소수의 이름으로 검증하세요. 지역 키워드는 요금제 설명, 배율 표시, 다른 노드 이름에도 함께 나타날 수 있습니다. 표현식이 너무 넓으면 원치 않는 항목을 포함하고, 너무 엄격하면 빈 그룹이 될 수 있습니다.

proxy-groups:
  - name: 홍콩 노드
    type: url-test
    use:
      - subscription-main
    filter: "(?i)홍콩|HK|Hong Kong"
    url: https://www.gstatic.com/generate_204
    interval: 300

  - name: 노드 선택
    type: select
    proxies:
      - 홍콩 노드
      - DIRECT
    use:
      - subscription-main

proxies와 use를 동시에 작성하면 정책 그룹은 커널이 지원하는 방식에 따라 정적 구성원과 Provider 구성원을 조합합니다. 화면에 중복 노드가 많이 나타나면 동일한 노드가 정적으로 작성된 동시에 Provider에서도 가져와지는지 확인하세요. 자동 정책 그룹이 비어 있다면 먼저 Provider 다운로드 성공 여부를 확인하고, 다음으로 필터 표현식, 마지막으로 Provider 내부 노드 이름이 예상과 일치하는지 확인합니다.

06 / RULE ENGINE

규칙 문법과 매칭 순서

위에서 아래로, 매칭되면 즉시 중지

rules는 순서가 있는 규칙 시퀀스입니다. 연결이 들어오면 커널은 첫 번째 규칙부터 확인하고 매칭되는 즉시 해당 규칙의 정책으로 요청을 전달한 뒤 이후 항목은 확인하지 않습니다. 따라서 구체적인 규칙은 범위가 넓은 규칙보다 앞에 두고, 최종 대체 규칙은 마지막에 배치해야 합니다. MATCH를 중간에 작성하면 뒤의 규칙이 실행되지 않으며, 광범위한 도메인 접미사 규칙을 정확한 도메인보다 앞에 두면 뒤의 예외 처리가 가려질 수 있습니다.

대부분의 규칙은 쉼표로 구분된 구조를 사용합니다. 규칙 유형, 매칭 내용, 대상 정책 순서이며 일부 규칙은 추가 매개변수를 사용할 수 있습니다. 예를 들어 DOMAIN-SUFFIX,example.com,노드 선택은 example.com과 하위 도메인을 “노드 선택”으로 전달합니다. 규칙의 대상 이름은 실제로 존재해야 합니다. 이름에 쉼표가 들어가면 구분 구조가 깨지므로 정책 그룹 이름에는 쉼표를 사용하지 않는 것이 좋습니다.

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

도메인 규칙의 차이

DOMAIN은 완전한 도메인만 매칭하므로 명확한 API 호스트나 특정 출구가 필요한 단일 서비스에 적합합니다. DOMAIN-SUFFIX는 지정한 도메인과 하위 도메인을 매칭하므로 사이트 전체의 트래픽을 분류할 때 적합합니다. DOMAIN-KEYWORD는 도메인에 키워드가 포함되기만 해도 매칭될 수 있어 범위가 넓고 오탐도 발생하기 쉽습니다. 정확한 도메인을 사용할 수 있다면 설정 몇 줄을 줄이기 위해 광범위한 키워드 규칙으로 바꾸지 마세요.

도메인 매칭은 연결 단계에서 커널이 도메인 정보를 얻을 수 있어야 합니다. 시스템 프록시의 HTTP 요청, SNI가 포함된 TLS 연결, Fake IP 매핑은 일반적으로 도메인 맥락을 제공하지만 순수 IP 연결은 IP 유형 규칙으로만 들어갈 수 있습니다. 애플리케이션이 자체적으로 해석한 뒤 IP에 직접 연결하면 도메인 규칙이 매칭되지 않을 수 있습니다. 로그에 대상 IP만 표시된다면 DNS를 커널이 인계받고 있는지, 애플리케이션이 시스템 프록시를 우회하는지 확인하세요.

IP, GEOIP와 no-resolve

IP-CIDR은 IPv4 대역, IP-CIDR6은 IPv6 대역에 사용합니다. 로컬 네트워크, 루프백, 링크 로컬 등의 주소는 보통 직접 연결해 원격 프록시로 보내지 않도록 해야 합니다. CIDR 접두사 길이가 범위를 결정하며 한 자리만 잘못 입력해도 예상보다 훨씬 넓은 주소 대역이 될 수 있습니다. 네트워크 규칙을 수정하기 전에는 대상 주소가 어느 네트워크에 속하는지 확인하고, 한 번의 해석 결과만 보고 지나치게 넓은 범위를 추가하지 마세요.

no-resolve는 해당 IP 규칙을 매칭할 때 DNS 해석을 능동적으로 수행하지 않는다는 뜻입니다. 이미 대상 IP를 얻었고 규칙 판단을 위해 추가로 도메인을 해석하고 싶지 않을 때 적합합니다. 규칙이 DNS 해석을 통해 IP를 얻어야 한다면 no-resolve를 추가할 경우 매칭 조건이 달라집니다. 이 매개변수는 일반적인 성능 향상 옵션이 아니므로 규칙 유형과 현재 연결 맥락에 맞춰 사용해야 합니다.

GEOIP는 IP 데이터베이스를 기준으로 분류하며 주소의 귀속 정보를 매칭할 뿐 도메인 유형과 같지는 않습니다. 데이터베이스는 커널 리소스와 함께 업데이트해야 하고 분류 결과에도 경계 차이가 있을 수 있습니다. 특정 업무를 안정적으로 제어하려면 도메인 규칙이나 명확하게 관리되는 규칙 집합이 더 직접적이며, GEOIP는 최종 대체 규칙에 가까운 위치에서 넓은 범위를 분류할 때 적합합니다.

프로세스, 포트와 네트워크 유형 규칙

호환 커널은 프로세스 이름, 프로세스 경로, 대상 포트, 인바운드 유형 등의 확장 규칙을 제공할 수 있습니다. 프로세스 규칙은 운영체제 권한과 커널이 프로세스 정보를 얻을 수 있는지에 따라 달라지며, 모바일 플랫폼·컨테이너 환경·일부 샌드박스 애플리케이션에서는 정보가 완전하지 않을 수 있습니다. 프로세스 이름도 업데이트에 따라 바뀔 수 있으므로 실행 로그에서 실제 인식 결과를 확인해야 합니다.

포트 규칙은 프로토콜 범위가 명확한 상황에 적합하지만 하나의 포트가 여러 서비스를 전달할 수 있어 포트만으로 분류하면 범위가 지나치게 넓어질 수 있습니다. 네트워크 유형 규칙은 TCP와 UDP를 구분할 수 있어 특정 UDP 애플리케이션이나 직접 연결이 필요한 로컬 서비스에 적합합니다. 복잡한 규칙에는 용도를 주석으로 남기고 개수를 관리하세요. 반년 뒤에도 존재 이유를 이해할 수 있는 구성이 지나치게 짧은 설정보다 낫습니다.

사용자 지정 규칙의 삽입 위치

사용자 지정 규칙의 적용 여부는 최종 규칙 목록의 어느 위치에 삽입되었는지에 달려 있습니다. 구독의 기본 동작을 덮어쓸 정확한 규칙은 해당하는 광범위한 규칙보다 앞에 두고, 로컬 직접 연결 대역은 프록시 대체 규칙보다 앞에 배치하며, MATCH는 항상 마지막에 둡니다. 많은 클라이언트가 “규칙 앞에 추가”, “규칙 뒤에 추가”, 스크립트 오버라이드를 제공합니다. 앞에 추가하는 방식은 우선순위가 높은 예외에, 뒤에 추가하는 방식은 구독에 없고 기존 대체 규칙에 먼저 매칭되지 않는 규칙을 보완할 때 적합합니다.

규칙을 확인할 때 설정 텍스트만 보지 말고 실행 로그의 규칙 매칭 정보를 확인하세요. 먼저 명확한 대상을 접속한 뒤 도메인 또는 IP, 매칭된 규칙 유형, 대상 정책 그룹, 최종 노드가 예상과 일치하는지 확인합니다. 로그가 더 앞선 규칙에 매칭되었다면 순서를 조정하거나 앞선 규칙의 범위를 좁히세요. 더 많은 일반적인 문제는 자주 묻는 질문에서 “사용 팁”과 “문제 해결” 분류를 기준으로 확인할 수 있습니다.

07 / PROVIDERS

Proxy Provider와 Rule Provider

외부 콘텐츠를 Provider로 분리하는 이유

Provider는 자주 업데이트되는 노드 또는 규칙 집합을 주 설정에서 분리하는 데 사용됩니다. proxy-providers는 노드 객체를 제공하고 정책 그룹이 use로 참조하며, rule-providers는 규칙 콘텐츠를 제공하고 RULE-SET이 호출합니다. 주 설정은 실행 프레임워크와 정책 관계를 담당하고 Provider는 외부 데이터 업데이트를 담당합니다. 이렇게 하면 노드나 규칙이 바뀔 때마다 주 설정 전체를 교체하지 않아도 됩니다.

Provider는 정책 그룹이 아닙니다. 노드 Provider 다운로드가 성공해도 반드시 정책 그룹에서 참조해야 하며, 규칙 Provider 다운로드가 성공해도 rules에서 RULE-SET으로 대상 정책을 지정해야 합니다. Provider만 정의하고 참조하지 않으면 트래픽이 자동으로 바뀌지 않습니다. 반대로 존재하지 않거나 로드에 실패한 Provider를 규칙에서 참조하면 해당 집합을 매칭할 수 없습니다.

proxy-providers 구조

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

proxy-groups:
  - name: 자동 선택
    type: url-test
    use:
      - subscription-main
    url: https://www.gstatic.com/generate_204
    interval: 300

  - name: 노드 선택
    type: select
    proxies:
      - 자동 선택
      - DIRECT
    use:
      - subscription-main

type: http는 원격 주소에서 콘텐츠를 가져온다는 뜻이고, url은 구독 주소, path는 로컬 캐시 경로, interval은 업데이트 간격입니다. 경로는 클라이언트가 쓰기를 허용하는 설정 디렉터리 안에 두어야 합니다. 여러 Provider가 같은 캐시 파일을 공유하면 업데이트 과정에서 서로 덮어쓸 수 있습니다. 구독 주소는 접근 자격 정보이므로 클라이언트 설정과 통제된 백업에 보관하고 공개 문서나 스크린샷에 게시하지 마세요.

health-check는 Provider에 포함된 노드의 사용 가능 여부를 검사합니다. 정책 그룹 자체의 url-test와 관련은 있지만 완전히 같지는 않습니다. Provider 상태 확인은 노드 상태를 관리하고, 정책 그룹 테스트는 구성원을 선택하는 데 사용됩니다. 테스트 주소, 주기, 네트워크 환경이 결과에 영향을 줍니다. 노드가 많을 때는 요청이 집중되지 않도록 주기를 지나치게 짧게 설정하지 마세요.

rule-providers의 behavior

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

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

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

behavior는 규칙 집합의 콘텐츠 유형을 설명합니다. domain은 도메인 항목, ipcidr은 주소 대역, classical은 규칙 유형이 포함된 고전 형식을 담는 데 사용됩니다. Provider 파일의 콘텐츠는 behavior와 일치해야 합니다. 완전한 DOMAIN-SUFFIX,example.com 항목을 도메인 값만 받는 집합에 넣거나 순수 대역을 맞지 않는 형식에 넣으면 로드 오류가 발생하거나 항목이 작동하지 않습니다.

도메인 behavior의 YAML 값은 보통 payload 시퀀스로 작성하며, 구체적인 항목 형식은 커널 규약에 따릅니다. 고전 형식은 완전한 규칙 유형을 유지합니다. behavior를 선택할 때는 파일 이름만 보고 판단하지 말고 규칙 출처가 실제로 제공하는 형식을 확인하세요. 원격 주소가 웹 페이지, 로그인 페이지, 오류 메시지를 반환하면 HTTP 요청이 성공했더라도 유효한 규칙 파일이 아닙니다.

Provider 업데이트와 캐시

원격 업데이트가 실패해도 커널은 로컬 캐시를 계속 사용할 수 있으므로 “현재 계속 실행된다”는 사실만으로 Provider가 이번 갱신을 완료했다고 볼 수 없습니다. 로그에서는 다운로드 실패, 해석 실패, 쓰기 실패, 캐시 읽기 성공을 구분해야 합니다. 다운로드 실패는 네트워크·주소·접근 권한을 확인하고, 해석 실패는 반환 콘텐츠 형식을 확인하며, 쓰기 실패는 디렉터리 권한과 경로를 확인하세요. 캐시가 손상되었다면 설정을 백업한 뒤 해당 캐시를 삭제해 클라이언트가 다시 가져오도록 할 수 있습니다.

업데이트 간격은 초 단위로 지정합니다. 노드 구독과 규칙 집합이 같은 주기를 사용할 필요는 없습니다. 노드는 자주 바뀔 수 있지만 안정적인 규칙 집합은 업데이트 빈도를 낮출 수 있습니다. 클라이언트 시작 시 즉시 업데이트할지, 실패 후 어떻게 재시도할지는 커널과 GUI 관리 방식에 따라 다릅니다. 너무 짧은 주기로 설정해 수동 문제 해결을 대신하지 마세요. 실패가 계속되면 요청과 로그만 반복해서 발생합니다.

여러 Provider 구성 방법

여러 구독을 동시에 사용할 때는 Provider마다 독립적인 이름, 캐시 경로, 상태 확인을 지정해야 합니다. 정책 그룹은 출처별로 직접 참조하거나 이름으로 필터링한 뒤 지역별로 조합할 수 있습니다. 출처 이름은 구독 관리에, 지역 정책은 일상적인 선택에 적합하므로 두 명명 계층을 섞지 마세요. 예를 들어 Provider에는 “subscription-main”, 정책 그룹에는 “홍콩 노드”, “자동 선택”을 사용하면 사용자 화면이 더 명확해집니다.

규칙 Provider도 사설 네트워크, 개발 서비스, 미디어 서비스, 차단 목록처럼 용도에 따라 나누는 것이 좋습니다. 너무 세분화하면 원격 요청과 순서가 복잡해지고, 지나치게 통합하면 서로 다른 정책을 지정하기 어렵습니다. “독립적인 업데이트, 독립적인 정책, 독립적인 우선순위가 필요한가”를 기준으로 판단하세요. 여러 RULE-SET 사이에서도 위에서 아래로 처음 매칭되는 규칙이 적용되는 로직은 그대로 유지됩니다.

08 / OVERRIDE AND MERGE

오버라이드, 병합과 설정 유지 관리

먼저 설정의 출처 계층을 확인하세요

그래픽 클라이언트의 최종 실행 설정은 보통 여러 출처로 구성됩니다. 구독 원본 콘텐츠, 클라이언트가 생성한 기본 매개변수, 사용자 화면 설정, 로컬 오버라이드 파일, 스크립트 처리 결과, 실행 시 추가되는 필드가 함께 포함될 수 있습니다. 사용자가 보는 구독 YAML이 커널이 최종으로 로드하는 설정과 항상 같은 것은 아닙니다. 수정이 적용되지 않을 때는 먼저 클라이언트에서 “실행 설정”, “설정 미리보기”, 로그 출력 등을 찾아 최종 값이 어느 계층에서 왔는지 확인하세요.

Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu 등은 오버라이드 화면의 명칭과 실행 순서가 다를 수 있으며, 모바일 버전은 일부 필드만 제공할 수도 있습니다. 데스크톱과 모바일 기기에서는 클라이언트가 제공하는 오버라이드 진입점을 우선 사용하고 구독이 관리하는 캐시 파일을 직접 편집하지 마세요. 구독 캐시는 새로 고칠 때 다시 생성되는 경우가 많아 수동 수정이 다음 업데이트에서 덮어써질 수 있습니다.

매핑, 시퀀스와 스칼라의 병합 차이

YAML 최상위 값은 매핑, 시퀀스, 스칼라로 나눌 수 있습니다. dns는 내부에 여러 단계의 키가 있는 매핑이고, rules, proxies, proxy-groups는 일반적으로 시퀀스이며, mode와 mixed-port는 스칼라입니다. 오버라이드 시스템은 이 세 가지 값을 서로 다르게 처리할 수 있습니다. 스칼라는 보통 바로 교체되고, 매핑은 키 단위로 재귀 병합될 수 있으며, 시퀀스는 전체 교체·앞에 추가·뒤에 추가·이름 기준 처리 방식이 사용될 수 있습니다.

이 차이에 따라 오버라이드의 안전성이 결정됩니다. 규칙 하나만 추가하려는데 오버라이드가 rules를 전체 교체 방식으로 처리하면 구독의 모든 규칙이 사라집니다. dns.enhanced-mode만 수정하려는데 시스템이 얕은 교체를 수행하면 전체 dns 매핑에 필드 하나만 남을 수 있습니다. 작업 전에는 클라이언트가 merge, prepend, append, override를 어떻게 정의하는지 확인해야 하며 모든 클라이언트가 같은 알고리즘을 사용한다고 가정해서는 안 됩니다.

작업	일반적인 결과	적합한 콘텐츠	주요 위험
Override	새 값으로 이전 값을 교체	mode, 포트, 전체 DNS 블록	시퀀스가 전체 덮어쓰기됨
Merge	키 기준으로 매핑 병합	공통 필드, DNS 하위 항목	얕은 병합과 깊은 병합의 결과가 다름
Prepend	시퀀스 맨 앞에 삽입	우선순위가 높은 사용자 지정 규칙	너무 넓은 규칙이 구독 규칙을 가림
Append	시퀀스 맨 끝에 추가	정책 구성원 또는 보완 규칙	MATCH 뒤에 놓여 적용되지 않을 수 있음

규칙 병합 시 MATCH 처리

규칙 오버라이드에서 가장 흔한 문제는 대체 규칙의 위치입니다. 구독 규칙은 보통 MATCH로 끝나므로 로컬 규칙을 단순히 마지막에 추가하면 실행되지 않습니다. 일반적으로는 로컬 우선순위 규칙을 구독 규칙 앞에 삽입하거나, 스크립트에서 마지막 MATCH를 잠시 꺼낸 뒤 추가 규칙을 넣고 다시 배치해야 합니다. 최종 목록에는 명확한 대체 대상 하나만 남겨야 합니다.

# 앞에 추가하는 규칙 예시
rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,dev.example.com,노드 선택

# 최종 설정은 구독 규칙을 이어받고 MATCH 하나로 끝나야 함
# - RULE-SET,...
# - GEOIP,...
# - MATCH,노드 선택

앞에 추가하는 규칙은 최대한 정확해야 합니다. 맨 앞에 범위가 넓은 DOMAIN-KEYWORD, 대규모 CIDR, 지역 규칙을 넣으면 구독의 세부 정책이 먼저 차단될 수 있습니다. 새 규칙을 추가할 때마다 적어도 매칭되어야 하는 대상 하나와 매칭되면 안 되는 인접 대상 하나를 검증하고 로그에서 실제 매칭 항목을 확인하세요.

정책 그룹과 노드 이름 병합

정책 그룹 시퀀스의 병합은 객체 위치만 보고 판단할 수 없습니다. 일부 도구는 name으로 기존 그룹을 찾아 수정하지만, 일부 도구는 새 객체를 목록에 추가하기만 합니다. 같은 이름의 정책 그룹을 추가하면 커널이 중복 이름 오류를 낼 수도 있고, 클라이언트가 사전 처리 과정에서 하나만 남길 수도 있어 결과를 예측하기 어렵습니다. 기존 그룹의 구성원을 수정해야 한다면 클라이언트가 명확히 제공하는 이름 기준 오버라이드 방식을 사용하세요. 지원하지 않는다면 대상 정책 그룹 시퀀스 전체를 생성하는 편이 더 제어하기 쉽습니다.

노드 목록에도 동명 충돌이 발생할 수 있습니다. 구독에 이미 “홍콩 01”이 있는데 로컬에서 같은 이름의 노드를 추가하면 참조 출처를 구분하기 어렵습니다. 직접 만든 노드에는 “LOCAL-” 같은 안정적인 접두사나 용도 이름을 사용하세요. Provider 필터가 이름에 의존한다면 해당 접두사가 지역 정규 표현식에 잘못 매칭되지 않는지도 확인해야 합니다.

DNS 오버라이드는 전체 의존성을 유지해야 합니다

DNS를 수정할 때는 nameserver만 확인해서는 안 됩니다. 도메인 형식의 DoH 업스트림을 사용한다면 작동하는 default-nameserver가 필요하고, 노드 서버에 도메인을 사용한다면 proxy-server-nameserver를 확인해야 하며, Fake IP를 사용한다면 주소 범위와 필터 항목도 유지해야 합니다. 업스트림 주소만 바꾸는 단순한 얕은 오버라이드가 이 의존 필드를 실수로 삭제할 수 있습니다.

더 안전한 방법은 먼저 최종 DNS 블록을 내보내 로컬 관리 버전으로 복사한 뒤 한 번에 수정하고 검증하는 것입니다. 클라이언트가 재귀 병합을 사용한다는 것을 확인했을 때만 최소 하위 키 오버라이드를 사용하세요. DNS 구성을 전환한 뒤에는 설정을 다시 로드하고 캐시를 정리한 다음 노드 서버 도메인과 일반 대상 도메인을 테스트해야 합니다. 클라이언트에 “설정 성공”이라고 표시되는 것만으로 완료 처리하지 마세요.

복구 가능한 수정 절차 만들기

한 번에 하나의 주제만 수정하세요. 예를 들어 DNS를 먼저 바꾸고, 정책 그룹을 바꾼 뒤, 마지막으로 규칙을 수정합니다. 수정 전에는 현재 정상적으로 실행되는 설정을 보존하고, 수정 후에는 문법 로드, Provider 업데이트, 정책 그룹 구성원 확인, 규칙 매칭, 실제 접속의 다섯 가지를 검증하세요. 여러 블록을 한 번에 교체하면 오류가 어느 계층에서 발생했는지 판단하기 어렵습니다.

설정 파일의 주석에 수정 목적, 출처, 의존성을 기록할 수 있습니다. 예를 들어 “구독 규칙보다 앞에 배치해야 함”, “Provider subscription-main 필요”, “로컬 네트워크 주소만 직접 연결”처럼 작성하세요. 주석에 구독 자격 정보나 노드 비밀번호를 포함해서는 안 됩니다. 장기 유지 관리에서는 전체 행의 단순 비교보다 구조 변화를 비교하는 편이 효과적입니다. 구독에 따라 노드 순서와 이름이 바뀔 수 있기 때문입니다.

구독 업데이트 후 시작 오류가 발생하면 먼저 보존해 둔 정상 실행 설정으로 되돌리고 클라이언트와 커널 자체가 시작되는지 확인한 다음 새 설정과 이전 설정의 최상위 필드, 정책 그룹 이름, 규칙 대상을 비교하세요. 클라이언트가 시작 즉시 종료되거나 창이 표시되지 않거나 업데이트 후 충돌한다면 클라이언트 시작 시 충돌 문제 해결 순서를 확인할 수 있습니다. 최초 연결 확인을 다시 진행해야 한다면 사용 안내로 돌아가 구독, 노드, 시스템 프록시, 연결 상태를 단계별로 점검하세요.

최종 설정 자체 점검 목록

로드 전에는 YAML 들여쓰기, 콜론 뒤 공백, 따옴표, 시퀀스 계층을 확인하고, 로드 후에는 포트가 정상적으로 수신 중인지, DNS가 시작되었는지, Provider가 유효한 콘텐츠를 가져왔는지 확인하세요. 이어서 모든 규칙 대상에 대응하는 정책 그룹이 있는지, 모든 정책 그룹에 유효한 구성원이 하나 이상 있는지, 중첩 관계에 순환이 없는지, 최종 규칙 목록의 맨 끝에 MATCH가 하나만 있는지 확인합니다. 마지막으로 직접 연결 도메인, 프록시 도메인, 로컬 네트워크 주소, 노드 서버 도메인, UDP가 필요한 애플리케이션을 각각 테스트하세요.

설정이 한 번 테스트를 통과했다고 해서 모든 네트워크 환경이 같은 것은 아닙니다. Wi-Fi, 모바일 네트워크, 회사 네트워크, IPv6 환경으로 전환하면 DNS 도달성, MTU, 방화벽, 시스템 프록시 동작이 달라질 수 있습니다. 문제를 확인할 때는 같은 설정을 유지하고 환경 변수 하나만 바꿔야 문제가 설정에서 비롯되었는지 네트워크에서 비롯되었는지 판단할 수 있습니다. 클라이언트를 바꿔야 한다면 다운로드 센터에서 Windows, macOS, Android, iOS, Linux에 맞는 옵션을 확인하세요. 일반 사용자는 Clash Plus를 우선 선택한 뒤 동일한 구독을 가져와 비교 테스트하는 것이 좋습니다.