Clash 설정 파일 참고 가이드

CHAPTER 01

YAML 구조 개요

설정 파일은 어떻게 읽히나요?

Clash 설정 파일은 본질적으로 하나의 YAML 문서입니다. 코어는 시작할 때 먼저 문법을 해석한 뒤 수신 포트, DNS, 프록시 노드, 정책 그룹, 규칙 등의 최상위 필드를 읽고 로컬 프록시 진입점과 트래픽 매칭 체인을 구성합니다. 문법 단계에서 실패하면 클라이언트가 정상 상태로 실행되지 않는 경우가 많습니다. 문법은 통과했지만 필드 관계가 잘못되면 실행은 되더라도 선택 가능한 노드가 없거나 규칙이 매칭되지 않을 수 있습니다. 따라서 설정 문제를 확인할 때는 파일이 열리는지만 보지 말고 YAML 문법, 필드명, 객체 참조, 실행 환경을 순서대로 점검해야 합니다.

일반적인 최상위 구조에는 port, socks-port, mixed-port, mode, log-level, dns, proxies, proxy-groups, rules, proxy-providers, rule-providers가 포함됩니다. 모든 설정에 이 필드가 전부 필요한 것은 아닙니다. 예를 들어 mixed-port만 사용하는 경우 HTTP와 SOCKS 포트를 따로 지정하지 않아도 됩니다. 원격 제공자가 노드를 불러오는 경우 proxies는 비워 둘 수 있지만, 정책 그룹에서는 반드시 use로 해당 제공자를 참조해야 합니다.

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
  nameserver:
    - 223.5.5.5
    - https://dns.alidns.com/dns-query

proxies:
  - name: Example-Trojan
    type: trojan
    server: edge.example.net
    port: 443
    password: your-password
    sni: edge.example.net

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

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

위 예시는 가장 짧은 완전한 흐름을 보여 줍니다. 로컬 프로그램이 7890 포트에 연결되고, DNS 모듈이 도메인 해석을 처리하며, proxies가 하나의 출구를 정의하고, proxy-groups가 출구를 선택 가능한 정책으로 묶고, rules가 트래픽을 어느 정책으로 보낼지 결정합니다. 실제 구독에는 더 많은 노드와 규칙이 포함되지만 관계는 여전히 “진입점—해석—출구—정책—매칭”입니다. 이 흐름을 이해하면 연결 실패가 어느 계층에서 발생했는지 판단하기 쉬워집니다.

들여쓰기, 목록과 데이터 유형

YAML은 들여쓰기로 계층을 표현하므로 공백 두 칸을 일관되게 사용하고 Tab은 사용하지 않는 것이 좋습니다. 콜론 뒤에는 공백을 하나 넣고, 목록 항목은 하이픈과 공백으로 시작하며, 같은 수준의 필드는 동일한 들여쓰기를 유지해야 합니다. dns는 매핑 객체이므로 내부 필드는 한 단계 더 들여씁니다. nameserver는 목록이므로 각 주소를 다시 한 단계 더 들여씁니다. enable과 nameserver를 서로 다른 수준으로 잘못 들여쓰면 파서가 즉시 오류를 내거나 예상과 다른 구조로 해석할 수 있습니다.

불리언 값은 true와 false를 사용하고, 포트는 정수, 이름과 주소는 문자열로 작성하는 것이 좋습니다. 콜론, 샵, 쉼표가 포함되거나 불리언으로 오인될 수 있는 값에는 따옴표를 사용하는 편이 안전합니다. 예를 들어 비밀번호에 샵이 들어 있는데 따옴표를 쓰지 않으면 샵 뒤 내용이 주석으로 처리됩니다. 노드명을 on, off처럼 쓰면 YAML 파서에 따라 다르게 해석될 수 있습니다. 구독 링크, 정규식, 복잡한 비밀번호에는 작은따옴표를 권장하며, 이스케이프 문자가 필요할 때는 큰따옴표를 사용하세요.

이름 참조는 완전히 일치해야 함

정책 그룹과 규칙은 이름으로 다른 객체를 참조하며, 전각·반각 문자, 공백, 대소문자를 구분합니다. 노드명이 “홍콩 01”인데 정책 그룹에 “홍콩01”이라고 쓰면 같은 객체가 아닙니다. 규칙 끝에는 “노드 선택”이라고 적었지만 설정에는 “프록시 선택”만 있어도 끊어진 참조가 됩니다. 구독을 수정할 때는 정의 부분만 바꾸지 말고 모든 참조를 함께 검색해야 합니다. 노드 이름 중복도 피하세요. 화면에는 이름 하나만 표시될 수 있어 실제로 어떤 항목이 선택됐는지 알기 어렵습니다.

YAML에서는 주석을 사용할 수 있지만, 주석은 필드 용도를 설명하는 데만 쓰고 무효화된 설정을 대량으로 보관하는 용도로는 사용하지 않는 편이 좋습니다. 주석 처리한 노드가 정책 그룹에서 계속 참조될 수 있으며, 노드를 삭제하고 참조를 정리하지 않는 것도 흔한 오류입니다. 안정적인 관리 방법은 기본 설정을 별도로 보관하고 실험용 필드는 복사본에 작성한 뒤, 정상적으로 로드되는 것을 확인하고 자주 쓰는 설정으로 옮기는 것입니다. Clash Plus, Clash Verge Rev, FlClash 같은 그래픽 클라이언트를 사용한다면 클라이언트에서 먼저 설정 검사를 실행한 뒤 현재 설정으로 전환할 수도 있습니다. 클라이언트 진입점과 플랫폼 안내는 클라이언트 받기에서 확인하세요.

CHAPTER 02

공통 필드, 포트와 실행 모드

로컬 수신 포트

port는 HTTP 프록시 진입점을 제공하고, socks-port는 SOCKS5 진입점을 제공하며, mixed-port는 하나의 포트에서 HTTP와 SOCKS 요청을 모두 받습니다. 대부분의 데스크톱 환경에서는 mixed-port만 설정한 뒤 클라이언트의 시스템 프록시 기능으로 운영체제 프록시 주소를 해당 포트에 연결하면 됩니다. 특정 개발 도구가 SOCKS5만 지원한다면 socks-port를 별도로 활성화할 수 있습니다. 여러 필드를 동시에 활성화할 때는 포트 번호가 서로 달라야 하며 다른 로컬 프로그램이 사용하는 포트와도 겹치면 안 됩니다.

port: 7890
socks-port: 7891
mixed-port: 7892
redir-port: 7893
tproxy-port: 7894

redir-port와 tproxy-port는 주로 Linux 라우팅 포워딩이나 투명 프록시에 사용됩니다. 일반 데스크톱 프로그램에서 시스템 프록시를 설정하는 데 필수인 필드는 아니며, 설정에 추가한다고 방화벽과 라우팅 규칙이 자동으로 만들어지지도 않습니다. 투명 프록시를 사용하려면 시스템 수준에서 트래픽 포워딩, 정책 라우팅과 권한도 설정해야 합니다. 시스템 프록시를 따르지 않는 프로그램까지 Clash로 보내려는 목적이라면 먼저 TUN 모드를 알아보는 것이 좋습니다. 원리와 설정 절차는 Clash TUN 모드 활성화 방법을 참고하세요.

LAN 접근과 수신 주소

allow-lan은 다른 기기가 현재 기기의 프록시 포트에 연결할 수 있는지 결정합니다. false로 설정하면 로컬 앱은 프록시를 사용할 수 있지만 LAN의 휴대폰, TV 또는 다른 컴퓨터는 이 포트를 프록시 서버로 사용할 수 없습니다. true로 설정한 뒤에는 bind-address, 운영체제 방화벽과 네트워크 유형도 확인해야 합니다. 신뢰할 수 있는 LAN에서만 사용할 경우 수신 범위를 특정 내부 주소로 제한해 모든 네트워크 인터페이스에 개방되지 않도록 하세요.

allow-lan: true
bind-address: 192.168.1.20
authentication:
  - local-user:your-password

LAN 접근을 활성화하면 같은 네트워크의 기기가 수신 포트에 연결을 시도할 수 있으므로 네트워크 이름만으로 안전성을 판단해서는 안 됩니다. 공용 네트워크, 임시 핫스팟, 공유 기숙사 네트워크에서는 allow-lan을 끄는 것이 좋습니다. 공유가 꼭 필요하다면 인증 필드와 함께 사용하고 시스템 방화벽에서 지정된 대역만 허용하세요. 원격 제어 인터페이스와 프록시 진입점은 서로 다른 서비스입니다. 프록시 포트를 개방했다고 제어 인터페이스까지 LAN에 노출할 필요는 없습니다.

Rule, Global과 Direct 모드

mode: rule은 rules를 위에서 아래로 매칭하는 모드로, 일상적인 설정에서 가장 많이 사용됩니다. global은 연결을 전역 정책 그룹으로 보내며 분류 규칙을 한 줄씩 실행하지 않습니다. direct는 직접 연결합니다. 그래픽 클라이언트의 모드 전환이 실행 중 설정 파일의 기본값을 덮어쓸 수 있으므로 파일에는 rule이 적혀 있어도 화면은 Global일 수 있습니다. 예상과 다른 라우팅을 점검할 때는 설정 필드와 클라이언트의 현재 상태를 함께 확인해야 합니다.

Global 모드는 특정 문제가 규칙 때문인지 짧게 확인할 때 유용하지만, 완성된 규칙 설정을 대신할 수는 없습니다. Rule 모드에서는 웹사이트에 접속할 수 없지만 Global 모드에서는 접속된다면, 도메인이 잘못된 정책으로 전달됐거나 규칙 순서가 잘못됐거나 대상 정책 그룹이 현재 사용할 수 없는 노드를 선택했을 가능성이 큽니다. Direct 모드는 로컬 네트워크 자체가 연결되는지 확인하는 데 적합합니다. Direct에서도 실패한다면 프록시 노드를 계속 바꾸기보다 네트워크, DNS와 대상 서비스를 먼저 점검하세요.

로그, IPv6와 제어 인터페이스

log-level의 일반적인 값은 silent, error, warning, info, debug입니다. 일상적인 사용에는 info로 충분합니다. 설정 로드, DNS 조회 또는 연결 핸드셰이크 문제를 확인할 때는 잠시 debug로 바꿀 수 있습니다. 로그에는 접속 도메인, 노드명과 로컬 연결 정보가 포함될 수 있으므로 문제 해결 화면을 공유하기 전에 내용을 확인하세요. 오류를 해결한 뒤에는 일반 로그 수준으로 되돌려 불필요한 출력을 줄이세요.

ipv6는 단순히 “네트워크가 더 빨라지는” 스위치가 아닙니다. 지역 네트워크의 IPv6가 불안정한데 DNS가 AAAA 레코드를 반환하면 프로그램이 연결할 수 없는 주소를 먼저 시도할 수 있습니다. 반대로 IPv6를 완전히 끄면 IPv6만 제공하는 환경에 영향을 줄 수 있습니다. 실제 네트워크 기능에 따라 결정하고 최상위 ipv6, DNS 모듈과 TUN 설정을 일치시키세요. 같은 도메인이 간헐적으로 연결됐다 끊긴다면 IPv4만 반환하는 경우와 IPv6를 함께 반환하는 경우를 각각 테스트해 주소 체계 차이인지 확인하세요.

external-controller는 그래픽 인터페이스나 외부 패널에 제어 인터페이스를 제공합니다. 데스크톱 클라이언트는 이 필드를 자동으로 관리하는 경우가 많아 직접 개방할 필요가 없습니다. 직접 설정한다면 127.0.0.1:9090처럼 루프백 주소에서 우선 수신하고 제어 키를 설정하세요. 0.0.0.0:9090으로 지정하면 다른 네트워크 인터페이스에서도 접근할 수 있으므로 원격 관리가 명확히 필요하고 접근 제한을 완료한 경우에만 사용해야 합니다. external-ui는 정적 패널 파일 디렉터리일 뿐, 인터페이스를 자동으로 다운로드하거나 업데이트하지 않습니다.

external-controller: 127.0.0.1:9090
secret: your-control-secret
external-ui: dashboard

공통 필드는 “최소한으로 작동하는 설정”에서 시작해 추가하세요. 먼저 혼합 포트 하나, Rule 모드와 기본 로그가 작동하는지 확인한 뒤 LAN, TUN, 제어 인터페이스 또는 고급 네트워크 옵션을 단계적으로 활성화하세요. 한 번에 많은 필드를 넣으면 파일은 완성돼 보여도 오류 원인을 찾기 어려워집니다. Clash 계열마다 고급 필드 지원 범위가 다를 수 있으므로 그래픽 클라이언트에서는 실제 탑재 코어와 설정 검사 결과를 기준으로 판단하세요.

CHAPTER 03

DNS 설정과 해석 흐름

DNS 모듈은 어떤 문제를 해결하나요?

앱이 도메인에 접속하려면 먼저 대상 주소를 얻은 다음 연결을 만들어야 합니다. 도메인 해석은 Clash를 우회하고 연결만 프록시로 들어가면 해석 결과와 프록시 출구가 일치하지 않거나 오염된 결과가 그대로 사용되거나 규칙이 원래 도메인을 확인하지 못할 수 있습니다. Clash의 DNS 모듈은 로컬 조회를 받아 지정한 상위 DNS로 해석하고, Fake-IP 모드에서는 가상 주소와 도메인의 매핑을 만들어 이후 트래픽이 도메인 규칙에 따라 판단되도록 합니다.

dns.enable은 모듈 활성화 여부를 제어하고, listen은 수신 주소를 지정하며, nameserver는 주요 상위 DNS, fallback은 다른 해석 출처를 제공합니다. 데스크톱 클라이언트는 TUN이나 시스템 설정을 통해 조회를 내장 DNS로 자동 전달할 수 있습니다. 설정에 listen: 127.0.0.1:1053만 작성한다고 운영체제 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
  use-hosts: true
  nameserver:
    - 223.5.5.5
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fake-ip-filter:
    - '*.lan'
    - localhost.ptlogin2.qq.com
    - time.*.com

Fake-IP와 Redir-Host

enhanced-mode: fake-ip은 앱에 예약 주소 범위의 가상 IP를 반환하고 원래 도메인과의 대응 관계를 기록합니다. 앱이 이 가상 주소에 연결하면 Clash가 도메인을 복원해 규칙을 매칭합니다. 이 방식은 도메인 정보를 보존하기 쉽고 앱이 먼저 직접 해석한 뒤 연결하면서 발생하는 라우팅 오류도 줄일 수 있습니다. fake-ip-range에는 전용 예약 주소 대역을 사용해야 하며 가정용 LAN, 회사 네트워크 또는 실제 공인 주소 범위로 임의 변경하지 마세요. 기존 라우팅과 충돌할 수 있습니다.

일부 LAN 서비스, 게임 기기 검색, 프린터, 시간 동기화 또는 실제 주소에 의존하는 앱은 Fake-IP를 받기에 적합하지 않으므로 fake-ip-filter로 제외할 수 있습니다. 필터 항목은 많을수록 좋은 것이 아닙니다. 범위가 지나치게 넓으면 많은 도메인이 실제 해석으로 돌아가 Fake-IP의 도메인 식별 효과가 약해집니다. 특정 앱은 웹페이지가 열리지만 로컬 기기를 찾지 못한다면 모든 도메인을 필터에 넣기보다 해당 앱이 사용하는 LAN 도메인부터 확인하세요.

redir-host는 실제 해석 결과를 반환하므로 기존 DNS와의 호환성은 높지만 복잡한 투명 프록시 환경에서는 원래 도메인을 보존하기 어려울 수 있습니다. 어떤 모드를 선택할지는 클라이언트, 운영체제와 네트워크 가로채기 방식에 따라 달라집니다. 일반적인 데스크톱 및 모바일 그래픽 클라이언트에서는 먼저 기본 모드를 사용하세요. 명확한 호환성 문제가 있을 때만 변경하는 것이 좋습니다. 강화 모드를 바꾼 뒤에도 이전 DNS 캐시와 연결이 남아 있을 수 있으므로 테스트 전에 클라이언트의 DNS 모듈을 재시작하고, 필요하면 시스템 캐시를 지운 뒤 대상 앱을 다시 여세요.

Nameserver, Fallback과 부트스트랩 해석

nameserver에는 일반 UDP DNS 주소나 DoH 주소를 입력할 수 있습니다. 일반 주소는 설정이 간단하지만 조회 경로가 로컬 네트워크에 좌우됩니다. DoH는 HTTPS로 전송되지만 DoH 서버 자체의 도메인을 먼저 해석해야 하므로 부트스트랩 해석이 필요합니다. 관련 필드를 지원하는 코어에서는 default-nameserver에 순수 IP DNS를 지정해 다른 암호화 DNS의 호스트명을 해석할 수 있습니다. 이 목록에는 IP 주소를 입력하고, 다시 도메인 해석이 필요한 DoH URL을 넣지 마세요.

dns:
  enable: true
  enhanced-mode: fake-ip
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query

proxy-server-nameserver는 프록시 서버 주소를 해석하는 데 사용됩니다. 노드의 server에 도메인을 입력했다면 프록시 연결을 만들기 전에 해당 도메인의 IP를 얻어야 합니다. 아직 연결되지 않은 프록시 채널에 해석을 의존하면 순환이 발생합니다. 프록시 서버용으로 직접 연결 가능한 해석기를 준비하면 “노드 주소 해석”과 “일반 도메인 프록시”를 분리할 수 있습니다. 구독 노드가 모두 IP 주소를 사용한다면 이 필드의 영향은 작습니다.

fallback은 모든 조회를 두 번째 서버 그룹에 단순히 동시에 보내는 기능이 아닙니다. 실제 선택 로직은 코어 구현과 필터 필드의 영향을 받습니다. fallback-filter를 설정하면 지리 데이터베이스, IP 범위 또는 도메인에 따라 결과 유형을 선택할 수 있지만 필터가 지나치게 복잡하면 문제 해결 비용이 커집니다. 기본 설정에서는 먼저 안정적인 nameserver 하나가 정상 작동하도록 한 뒤 fallback을 고려하세요. 모든 해석기에 접근할 수 없다면 개수를 늘려도 네트워크 경로 문제는 해결되지 않습니다.

DNS 문제 해결 순서

문제 해결 시 먼저 조회가 Clash로 들어오는지 확인하고, 다음으로 Clash가 상위 DNS에 접근할 수 있는지 확인한 뒤 반환 결과가 규칙과 연결에서 어떻게 사용되는지 살펴보세요. 로그에 대상 도메인의 DNS 조회가 전혀 없다면 시스템이나 앱이 다른 해석 경로를 사용하고 있을 수 있습니다. 조회는 있지만 계속 시간 초과가 발생하면 상위 주소, 네트워크 방화벽과 프록시 의존성을 확인하세요. 조회는 성공하지만 접속이 실패한다면 규칙 매칭, 정책 선택과 대상 주소 체계를 계속 점검해야 합니다. 모든 연결 문제를 DNS로 단정하거나 경로를 확인하기 전에 해석기를 계속 바꾸지 마세요.

브라우저가 자체 보안 DNS를 활성화했거나 모바일 운영체제가 Private DNS를 사용할 수 있으며, 이러한 설정은 조회 경로를 바꿉니다. TUN 가로채기는 더 많은 트래픽을 처리할 수 있지만 시스템 권한과 라우팅 충돌도 해결해야 합니다. 노드 시간 초과, 간헐적인 도메인 실패, 혼재된 시스템 프록시 상태가 함께 나타난다면 구독부터 DNS까지 문제를 확인하는 순서에 따라 계층별로 점검하세요. DNS 설정의 목표는 상위 DNS를 많이 쌓는 것이 아니라 해석 경로를 명확하고 재현 가능하게 만드는 것입니다.

CHAPTER 04

프록시 노드 필드

모든 노드에 공통으로 적용되는 기본 관계

proxies는 노드 객체 목록입니다. 각 객체에는 최소한 이름, 프로토콜 유형, 서버 주소, 포트와 해당 프로토콜에 필요한 인증 필드가 있어야 합니다. name은 정책 그룹과 화면에서 참조하고, type은 이후 필드의 해석 방식을 결정하며, server는 IP 또는 도메인, port는 서버의 수신 포트와 일치해야 합니다. 노드 정보는 보통 구독에서 제공되므로 한 프로토콜의 필드를 다른 프로토콜에 추측으로 복사하지 마세요.

노드가 YAML 검사를 통과했다는 것은 필드 구조를 읽을 수 있다는 뜻일 뿐, 실제 서버에 접근 가능하다는 의미는 아닙니다. 서버 주소 오류, 닫힌 포트, 인증 불일치, 시스템 시간 오차, TLS 호스트명 불일치와 로컬 네트워크 차단이 모두 연결 실패를 일으킬 수 있습니다. 문제를 확인할 때는 먼저 원본 구독이 여전히 유효한지 확인한 뒤 클라이언트 로그에서 실패 단계를 살펴보세요. 서로 다른 프로토콜의 여러 노드가 동시에 시간 초과된다면 각 노드가 우연히 모두 고장 났다기보다 구독, DNS, 로컬 네트워크 또는 시스템 프록시 문제일 가능성이 큽니다.

Shadowsocks와 Trojan 예시

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

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

Shadowsocks의 cipher는 서버와 일치해야 하며 클라이언트 지원 목록만 보고 임의로 바꾸면 안 됩니다. password는 문자열로 처리하고 특수 문자가 포함되면 따옴표를 사용하세요. udp는 해당 노드가 UDP를 전달할 수 있음을 의미하지만 실제 사용 가능 여부는 서버, 네트워크 경로와 클라이언트 실행 모드에 따라 달라집니다. 시스템 프록시만 사용하는 경우 많은 UDP 트래픽이 자연스럽게 프록시로 들어오지 않습니다. TUN이나 투명 프록시 환경에서 UDP 가로채기가 더 자주 필요합니다.

Trojan은 일반적으로 TLS로 연결하며 sni는 핸드셰이크에서 서버 이름을 지정합니다. 노드 server에는 IP를 적었지만 인증서가 도메인으로 발급됐다면 올바른 SNI가 특히 중요합니다. skip-cert-verify: true는 인증서 검증을 건너뛰므로 일반적인 해결책으로 사용해서는 안 됩니다. 이 옵션을 켜야 연결된다면 서버 이름, 시스템 시간, 인증서 체인과 구독 필드가 올바른지 계속 확인하세요. 검증을 켜 두어야 핸드셰이크 대상과 인증서 신원이 일치하지 않는 문제를 발견할 수 있습니다.

VMess와 VLESS 전송 필드

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

  - name: Example-VLESS
    type: vless
    server: vless.example.net
    port: 443
    uuid: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    network: tcp
    tls: true
    servername: vless.example.net
    udp: true

VMess와 VLESS는 모두 UUID를 사용하지만 같은 프로토콜은 아닙니다. WebSocket 전송에서는 network, 경로와 Host도 확인해야 합니다. 서버가 특정 경로를 요구할 때 슬래시 하나가 빠지거나 대소문자가 달라도 핸드셰이크가 실패할 수 있습니다. TLS 필드명은 설정 형식과 코어 분기에 따라 다를 수 있으므로 구독이 생성한 구조를 우선 유지하고 “형식 통일”을 위해 일괄적으로 이름을 바꾸지 마세요. 설정 검사는 알 수 없는 필드를 식별할 수 있지만 원격 리버스 프록시가 같은 경로로 전달하는지까지 검증하지는 못합니다.

노드가 gRPC, HTTP/2, Reality 또는 다른 확장 전송을 사용하면 추가 서비스명, 공개 키, 짧은 식별자나 흐름 제어 필드가 생깁니다. 이러한 필드는 서버 설정에서 한 세트로 가져와야 합니다. 하나라도 빠지면 문법 검사는 통과해도 핸드셰이크가 완료되지 않을 수 있습니다. 노드를 수동으로 옮길 때는 server, port, UUID 세 항목만 복사하지 말고 완전한 객체 단위로 옮기세요. 확장 프로토콜 지원 여부는 코어에 따라 달라질 수 있으므로 그래픽 클라이언트에서는 구독 요구 사항에 맞는 코어를 선택해야 합니다.

DIRECT, REJECT와 내장 출구

DIRECT와 REJECT는 자주 사용하는 내장 정책이므로 proxies에 선언할 필요가 없습니다. DIRECT는 트래픽을 직접 연결하고 REJECT는 연결을 거부합니다. 정책 그룹의 proxies 목록에 넣거나 규칙 끝에 바로 작성할 수 있습니다. 사용할 때는 구독의 사용자 지정 노드가 같은 이름을 차지하지 않는지도 확인하세요. DIRECT라는 일반 프록시 노드를 만들면 읽기와 문제 해결이 혼란스러워집니다.

일부 설정은 호환, 패킷 폐기 또는 DNS 관련 내장 유형도 사용합니다. 지원 여부는 현재 코어를 기준으로 확인해야 합니다. Clash Plus, Clash Verge Rev, FlClash 같은 클라이언트 간에 설정을 옮기려면 기본 파일에는 일반적인 필드를 우선 사용하고 특정 코어 확장은 별도 오버라이드에 두는 것이 좋습니다. 모바일과 데스크톱은 시스템 가로채기 방식이 다르지만 노드 객체 자체는 최대한 동일하게 유지하고, 차이는 주로 포트, TUN, DNS 수신과 화면 설정에 두세요.

노드 장애를 계층별로 판단하기

지연 시간 테스트 실패가 모든 업무 연결의 실패를 뜻하지는 않으며, 테스트 주소도 실제 접속 대상과 같지 않습니다. 먼저 DNS 해석 실패인지, TCP 연결 시간 초과인지, TLS 핸드셰이크 오류인지, 인증 거부인지 확인하세요. 해석 실패는 server와 프록시 서버 DNS를 확인하고, 연결 시간 초과는 네트워크와 포트를 확인하며, TLS 오류는 SNI, 시스템 시간과 인증서를 확인하세요. 인증 실패라면 구독 정보로 돌아가야 합니다. 문제를 설명할 로그와 현재 필드를 잃을 수 있으므로 처음부터 전체 클라이언트 설정을 삭제하지 마세요.

수동 노드는 필드를 테스트하고 이해하는 데 적합하지만, 장기간 사용할 노드 목록은 구독 제공자가 관리하는 편이 좋습니다. 구독 업데이트로 노드 추가와 삭제를 일괄 처리할 수 있지만 로컬 정책 그룹과 규칙은 안정적으로 참조해야 합니다. 다음 장에서는 노드를 정책 그룹에 넣는 방법을, 7장에서는 proxy-providers로 원격 노드를 불러오는 방법을 설명합니다. 처음 가져온 뒤 노드를 선택하고 확인하는 방법을 모르겠다면 먼저 첫 연결 가이드를 읽어 보세요.

CHAPTER 05

정책 그룹 필드와 선택 로직

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

proxy-groups는 여러 프록시 노드, 다른 정책 그룹과 내장 출구를 하나의 참조 가능한 이름으로 묶습니다. 규칙은 보통 특정 노드를 직접 가리키지 않고 “노드 선택”, “자동 선택”, “스트리밍” 같은 정책 그룹을 가리킵니다. 이렇게 하면 노드가 바뀌어도 규칙을 한 줄씩 수정할 필요 없이 정책 그룹의 구성원이나 현재 선택만 조정하면 됩니다. 정책 그룹을 중첩할 수도 있지만 순환 참조는 피해야 합니다. 예를 들어 A가 B를 포함하고 B가 다시 A를 포함하면 설정 관계가 성립하지 않습니다.

가장 많이 사용하는 유형은 select, url-test, fallback, load-balance입니다. Select는 사용자가 구성원을 직접 선택하고, URL-Test는 주기적으로 테스트해 조건에 맞는 구성원을 선택하며, Fallback은 순서대로 사용 가능한 구성원을 찾고, Load-Balance는 여러 구성원에 연결을 분배합니다. 유형마다 해결하는 문제가 다르므로 “자동”을 무조건 더 빠르다는 뜻으로 이해하면 안 됩니다. 지연 시간 테스트는 테스트 대상과 당시 네트워크만 반영하며 실제 서비스는 다른 경로를 사용할 수 있습니다.

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

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

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

Select와 자동 테스트 그룹

select의 장점은 결과가 명확하다는 것입니다. 화면에서 노드를 선택하면 해당 선택이 유지되므로 고정 출구, 로그인 상태 또는 특정 지역이 필요한 서비스에 적합합니다. 단점은 노드가 고장 나도 자동으로 바뀌지 않아 직접 선택해야 한다는 점입니다. 자동 테스트 그룹을 Select의 첫 번째 구성원으로 두면 자동 선택과 수동 진입점을 함께 유지할 수 있습니다. 평소에는 “자동 선택”을 사용하고 고정 회선이 필요할 때 특정 노드로 전환하세요.

url-test는 url로 접근성 테스트를 시작하고 interval이 주기를 제어하며, tolerance는 지연 시간이 비슷한 여러 노드가 자주 바뀌는 것을 방지합니다. 테스트 간격이 너무 짧으면 지속적인 요청이 발생하고 화면의 선택이 계속 변할 수 있습니다. 너무 길면 장애를 늦게 발견합니다. 테스트 URL은 단순하고 안정적인 응답을 반환해야 하며 로그인, 복잡한 리디렉션 또는 로컬 네트워크에서 자주 차단되는 페이지는 피하세요. 테스트 성공은 해당 노드가 테스트 대상에 접근할 수 있다는 뜻일 뿐입니다.

fallback은 구성원의 순서를 더 중시합니다. 일반적으로 첫 번째 구성원이 사용 가능하면 계속 사용하고, 실패한 뒤 다음 구성원으로 전환하므로 주 회선과 예비 회선이 분명한 구성에 적합합니다. URL-Test와의 차이는 테스트 여부가 아니라 선택 원칙입니다. URL-Test는 테스트 결과를, Fallback은 순서와 사용 가능 여부를 우선합니다. 안정적인 세션이 필요할 때 노드가 자주 바뀌면 로그인 상태나 주소가 변할 수 있으므로 최저 테스트 수치를 추구하기보다 주 회선·예비 회선 그룹이 더 적합할 수 있습니다.

로드 밸런싱과 세션 일관성

load-balance는 여러 연결을 여러 노드에 분배할 수 있지만 단일 다운로드 작업의 대역폭을 합산한다는 뜻은 아닙니다. 웹페이지는 여러 연결을 만들 수 있고 이 연결들이 서로 다른 출구에서 나갈 수 있습니다. 대상 서비스가 동일한 출발 주소를 요구하면 출구 분산으로 인증 문자, 로그인 만료 또는 요청 거부가 발생할 수 있습니다. 관련 정책 필드를 지원하는 코어에서는 일관성 해시를 사용해 같은 대상이 동일한 구성원에 더 안정적으로 연결되도록 할 수 있지만 실제 업무로 확인해야 합니다.

  - name: 균등 출구
    type: load-balance
    strategy: consistent-hashing
    proxies:
      - Example-Trojan
      - Example-SS
    url: https://www.gstatic.com/generate_204
    interval: 300

로드 밸런싱은 여러 독립 대상이나 여러 독립 연결에 적합하며 모든 규칙의 기본 출구로 사용하기에는 적합하지 않습니다. 설정하기 전에 모든 구성원이 독립적으로 작동하고 지역, 접근 권한과 프로토콜 기능이 비슷한지 확인하세요. 차이가 큰 노드를 한 그룹에 넣으면 같은 서비스의 동작을 재현하기 어려워집니다. 노드 장애 시 자동 전환만 원한다면 Fallback이 보통 더 적합합니다.

노드 이름으로 구성원 필터링

proxy-providers를 사용할 때 정책 그룹은 use로 제공자 전체를 가져온 뒤 filter 또는 exclude-filter로 이름을 필터링할 수 있습니다. 필터는 보통 정규식을 사용하므로 먼저 구독의 실제 이름을 확인하세요. 특정 기호나 고정 접두사에 지나치게 의존하면 구독 서비스가 이름을 바꾼 뒤 정책 그룹이 갑자기 비어 버릴 수 있습니다. 간단한 키워드부터 시작하고 중요한 그룹에는 수동 선택 가능한 진입점을 남겨 두는 방법이 더 안정적입니다.

proxy-groups:
  - name: 홍콩 노드
    type: select
    use:
      - remote-nodes
    filter: '(?i)홍콩|HK|Hong Kong'

  - name: 노드 선택
    type: select
    proxies:
      - 홍콩 노드
      - DIRECT
    use:
      - remote-nodes

정규식의 괄호, 수직선과 특수 문자는 따옴표 안에 넣어야 합니다. 필터 결과가 비어 있으면 먼저 제공자가 정상적으로 로드됐는지 확인한 다음 이름이 일치하는지 점검하세요. 곧바로 구독에 노드가 없다고 판단하지 마세요. 클라이언트 화면에서 제공자의 원본 노드 목록을 볼 수 있다면 이름 한두 개를 복사해 최소 단위로 테스트하세요. 이름 필터링은 관리 수단일 뿐 노드 품질을 판단하는 기준이 아닙니다. “고속”, “전용 회선” 같은 이름만으로 회선 상태를 증명할 수 없습니다.

정책 그룹 계층 관리 원칙

규칙의 최상위 계층에서는 “노드 선택”, “직접 연결 서비스”, “차단 규칙”처럼 안정적인 정책을 소수만 참조하는 것이 좋습니다. 지역 그룹, 자동 그룹과 특정 노드는 이 정책 아래에 두세요. 계층이 너무 깊으면 화면에서 선택 경로가 복잡해지고 규칙 매칭 후 최종 출구를 추적하기도 어려워집니다. 일반적으로 “업무 정책—지역 정책—노드” 관계를 표현하는 데는 2~3단계면 충분합니다. 계층을 하나 더 만들 때마다 어떤 선택 문제를 해결하는지 설명할 수 있어야 합니다.

정책 그룹을 수정한 뒤에는 세 가지를 확인하세요. 모든 구성원이 존재하는지, 규칙이 참조하는 정책이 존재하는지, 정책 사이에 순환이 생기지 않았는지입니다. 구독 업데이트로 수동 그룹이 참조하던 특정 노드가 삭제될 수도 있으므로 장기 설정에서는 원격 노드명을 하나씩 복사하기보다 제공자와 필터로 참조하는 편이 좋습니다. 클라이언트에 정책 그룹은 보이지만 펼칠 수 없다면 먼저 빈 그룹, 잘못된 참조와 제공자 로드 상태를 확인하세요.

CHAPTER 06

규칙 문법과 매칭 순서

규칙은 위에서 아래로 실행됩니다

rules는 순서가 있는 목록입니다. 각 연결은 첫 번째 규칙부터 확인하고 매칭되면 즉시 중지하므로 뒤의 규칙은 더 이상 검사하지 않습니다. 따라서 규칙 유형이 올바라도 순서가 잘못되면 결과가 예상과 달라집니다. 범위가 구체적인 규칙은 앞에, 범위가 넓은 규칙은 뒤에 두고 MATCH는 마지막 기본 규칙으로 끝에 배치하세요. MATCH를 중간에 쓰면 이후 규칙은 실행될 기회를 잃습니다.

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

일반적인 규칙은 규칙 유형, 매칭 내용과 대상 정책으로 구성되며 영문 쉼표로 구분합니다. 정책명은 proxy-groups에 정의된 이름 또는 내장 정책과 일치해야 합니다. 한글 쉼표, 끝의 불필요한 공백과 이름 오타 때문에 규칙이 예상대로 로드되지 않을 수 있습니다. 규칙 값 자체에 쉼표가 포함되면 해당 규칙 유형이 이스케이프를 지원하는지 확인해야 하며, 복잡한 텍스트를 일반적인 세 부분 형식에 그대로 넣어서는 안 됩니다.

도메인 규칙의 차이

DOMAIN은 전체 도메인을 정확히 매칭합니다. 예를 들어 DOMAIN,api.example.com은 해당 호스트만 매칭하며 www.example.com까지 자동으로 포함하지 않습니다. DOMAIN-SUFFIX는 도메인 접미사를 매칭해 주 도메인과 하위 도메인을 함께 처리할 때 적합합니다. DOMAIN-KEYWORD는 키워드로 매칭하므로 범위가 가장 넓고 오매칭도 쉽습니다. 도메인 경계를 특정할 수 있다면 DOMAIN 또는 DOMAIN-SUFFIX를 우선 사용하고, 대상 도메인이 분산되어 안정적인 키워드가 있을 때만 키워드 규칙을 고려하세요.

도메인 규칙의 작동 여부는 연결 단계에서 코어가 도메인을 얻을 수 있는지에 달려 있습니다. 앱이 IP에 직접 연결하거나 DNS 조회를 완전히 우회하면 DOMAIN 계열 규칙이 매칭할 대상을 얻지 못할 수 있습니다. Fake-IP, TUN 스니핑과 시스템 프록시는 도메인 보존에 도움을 줄 수 있지만 경로는 각각 다릅니다. 도메인 규칙이 매칭되지 않는다면 먼저 연결 로그에 도메인과 IP 중 무엇이 표시되는지 확인한 뒤 DNS, 스니핑 또는 규칙 자체를 점검하세요.

규칙 범위는 업무 경계에서 출발해 정해야 합니다. 최상위 접미사 범위를 지나치게 넓게 프록시로 보내면 관련 없는 서비스의 출구까지 바뀔 수 있습니다. 로그인 도메인 하나만 적으면 정적 리소스, API와 콘텐츠 도메인을 놓칠 수 있습니다. 연결 로그로 한 번의 작업에 어떤 도메인이 사용되는지 확인한 뒤 같은 정책이 필요한 동일 서비스의 도메인을 규칙에 포함하세요. 주소 표시줄만 보고 모든 요청을 추측하지 마세요.

IP, 네트워크 대역과 no-resolve

IP-CIDR은 IPv4 네트워크 대역을, IP-CIDR6은 IPv6 네트워크 대역을 매칭합니다. CIDR 뒤의 숫자는 네트워크 접두사 길이를 나타냅니다. 예를 들어 192.168.0.0/16은 흔한 사설 주소 범위 하나를 포함합니다. IP 규칙은 LAN, 고정 서버 또는 데이터베이스가 제공하는 주소 범위를 처리하는 데 적합하지만, 서비스가 동적 주소와 CDN을 사용하면 단일 IP가 빠르게 바뀔 수 있습니다.

no-resolve는 이 IP 규칙을 실행할 때 IP를 얻기 위해 추가 해석을 자동으로 수행하지 않도록 합니다. LAN 대역이나 이미 IP 형태로 만들어진 연결에서는 불필요한 DNS 조회를 줄일 수 있습니다. 모든 IP 규칙에 반드시 추가해야 하는 장식용 필드는 아닙니다. 앞선 매칭 흐름에 실제로 도메인 해석 결과가 필요하다면 추가했을 때의 영향을 이해해야 합니다. 문제 해결 시 로그를 통해 규칙이 원래 IP, 해석 결과 또는 Fake-IP 중 무엇을 보는지 확인할 수 있습니다.

rules:
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - MATCH,노드 선택

LAN 직접 연결 규칙은 일반 프록시 규칙보다 앞에 두어 프린터, 라우터와 내부 서비스가 원격 노드로 보내지지 않도록 하는 것이 보통입니다. 그러나 회사 네트워크는 일반적인 사설망과 겹치는 복잡한 라우팅을 사용할 수 있고 TUN 환경에서는 실제 라우팅 테이블도 관련됩니다. 내부 주소 접속이 실패하면 규칙뿐 아니라 시스템이 해당 대역을 로컬 인터페이스로 올바르게 라우팅하는지도 확인해야 합니다. Clash는 자신에게 들어온 연결만 처리할 수 있으며 하위 네트워크 라우팅을 대신할 수 없습니다.

GEOIP, 규칙 집합과 데이터베이스

GEOIP는 로컬 주소 데이터베이스를 기준으로 IP의 지역을 판단합니다. 정확도는 데이터베이스 내용과 업데이트 상태에 좌우되므로 모든 주소가 영구적으로 변하지 않는다고 볼 수 없습니다. 서비스 이전, CDN 노드 변경과 데이터베이스 지연으로 분류가 달라질 수 있습니다. 중요한 서비스가 GEOIP에 의해 잘못된 정책으로 분류되면 광범위한 지역 규칙이 우연히 수정되기를 기다리지 말고 더 구체적인 도메인 또는 IP 규칙을 추가하세요.

규모가 큰 규칙 데이터베이스는 rule-providers로 관리한 뒤 RULE-SET으로 참조하는 것이 적합합니다. 이렇게 하면 기본 설정에는 규칙 집합의 순서와 대상 정책만 남고 구체적인 항목은 제공자가 업데이트합니다. 다만 여러 규칙 집합이 겹칠 수 있으므로 기본 설정의 참조 순서는 여전히 적용됩니다. 광고 차단, 직접 연결 도메인과 프록시 도메인에 같은 대상이 포함되어 있다면 앞에 있는 집합이 최종 결과를 결정합니다.

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,direct-domain,DIRECT
  - RULE-SET,proxy-domain,노드 선택
  - RULE-SET,private-ip,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

규칙이 매칭되지 않을 때 확인하기

먼저 연결 로그에서 대상 요청을 찾고 표시된 도메인 또는 IP, 매칭된 규칙과 최종 정책을 기록하세요. 범위가 지나치게 넓은 앞선 규칙에 매칭됐다면 순서를 조정하거나 범위를 줄입니다. 바로 MATCH로 떨어진다면 규칙 내용이 로그의 대상과 일치하는지 확인하세요. 올바른 정책에 매칭됐지만 잘못된 노드로 간다면 문제는 규칙이 아니라 정책 그룹의 현재 선택입니다. 이 세 계층을 분리하면 규칙을 계속 바꾸면서도 최종 출구가 바뀌지 않는 상황을 피할 수 있습니다.

규칙을 테스트할 때는 한 번에 조건 하나만 바꾸고 수정 후 현재 설정이 다시 로드됐는지 확인하세요. 브라우저의 연결 재사용, DNS 캐시와 앱 백그라운드 프로세스가 이전 연결을 계속 사용할 수 있으므로 필요하면 앱을 종료한 뒤 다시 시도하세요. 규칙은 읽기 쉽게 설계해야 합니다. 구체적인 예외를 앞에 두고, 규칙 집합을 가운데, 지역 규칙과 최종 기본 규칙을 뒤에 배치하며 소수의 특수 항목에는 간단한 주석으로 이유를 남기세요. 설명 없는 임시 규칙이 많으면 유지 관리가 점점 어려워집니다.

CHAPTER 07

구독, 프록시 제공자와 규칙 제공자

로컬 노드와 원격 제공자의 차이

노드를 proxies에 직접 작성하는 방식은 소수의 고정 노드와 임시 테스트에 적합합니다. proxy-providers를 사용하면 원격 주소에서 노드 목록을 주기적으로 업데이트하고 정책 그룹이 use로 이를 참조할 수 있습니다. 제공자는 “노드 데이터를 업데이트하는 방법”과 “노드가 정책에 참여하는 방법”을 분리합니다. 원격 내용이 바뀌어도 로컬 기본 설정의 정책명과 규칙을 함께 바꿀 필요가 없습니다.

제공자는 완전한 설정 구독과 같은 의미가 아닙니다. 일부 구독 주소는 포트, DNS, 정책 그룹과 규칙이 포함된 전체 Clash 설정을 반환하지만, proxy-providers는 일반적으로 노드 목록 형식을 필요로 합니다. 전체 설정 주소를 provider에 그대로 넣으면 내용 구조가 맞지 않아 로드에 실패할 수 있습니다. 클라이언트의 일반 구독 가져오기와 설정 내부의 프록시 제공자는 서로 다른 계층이므로 먼저 서버가 제공하는 파일 유형을 확인하세요.

proxy-providers:
  remote-nodes:
    type: http
    url: https://config.example.net/nodes.yaml
    path: ./providers/remote-nodes.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: 노드 선택
    type: select
    use:
      - remote-nodes
    proxies:
      - DIRECT

type: http는 원격 주소에서 가져온다는 뜻이고, url은 구독 주소, path는 로컬 캐시 위치, interval은 업데이트 주기입니다. 캐시가 있으면 원격 주소에 잠시 접근할 수 없어도 클라이언트가 마지막으로 성공한 내용을 읽을 수 있습니다. 경로는 클라이언트가 쓸 수 있는 설정 디렉터리 안에 두고 추가 시스템 권한이 필요한 위치는 피하세요. 여러 제공자가 같은 캐시 파일을 공유하면 업데이트 시 서로 덮어쓸 수 있습니다.

구독 주소에는 보통 접근 권한이 있으므로 공개적으로 공유하는 로그, 화면 캡처와 예제 파일에 기록하지 않도록 주의하세요. 이 문서의 예시는 실제 서비스에 사용할 수 없는 예시 도메인을 사용합니다. 구독 로드에 실패하면 정책 그룹이 비어 있는지만 보지 말고 HTTP 상태, TLS 오류, 응답 형식과 로컬 파일 쓰기 권한을 확인하세요. 원격 요청은 성공했지만 예상한 YAML이 아닌 내용이 반환되어도 파싱에 실패할 수 있습니다.

상태 점검과 정책 테스트

health-check는 제공자에 포함된 노드가 지정된 URL에 접근할 수 있는지 주기적으로 확인합니다. 정책 그룹의 URL-Test와 관련은 있지만 같은 계층은 아닙니다. 제공자 상태 점검은 노드의 사용 가능 상태를 관리하고 정책 그룹 테스트는 그룹 안에서 선택하는 방식을 결정합니다. 두 곳 모두 간격을 너무 짧게 설정하면 중복 테스트가 발생합니다. 노드 수와 사용 방식에 맞춰 적절한 주기를 유지하고 계속 높은 빈도로 탐색할 필요는 없습니다.

상태 점검 실패는 노드를 사용할 수 없어서일 수도 있지만 현재 네트워크나 대상 지역에서 테스트 URL에 접근할 수 없어서일 수도 있습니다. 모든 노드가 같은 시각에 동일한 테스트 주소에서 실패한다면 실제 대상과 다른 안정적인 주소로 교차 확인하세요. 테스트 URL이 리디렉션, 인증 문자 또는 큰 페이지를 반환하면 오판이 늘어날 수 있습니다. 간단한 빈 응답 엔드포인트가 접근성 확인에는 더 적합하지만 실제 업무 접속 검증을 대신할 수는 없습니다.

규칙 제공자 구조

rule-providers는 업데이트 가능한 규칙 집합을 불러오는 데 사용됩니다. 일반적인 필드에는 동작 유형 behavior, 형식 format, 원격 주소, 캐시 경로와 업데이트 주기가 있습니다. behavior: domain은 도메인 집합에, ipcidr은 IP 대역에, classical은 규칙 유형이 포함된 기존 형식 항목에 적합합니다. 기본 설정의 RULE-SET 참조는 집합의 동작 유형과 일치해야 하며 IP 집합은 보통 no-resolve와 함께 사용합니다.

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

  private-ip:
    type: http
    behavior: ipcidr
    format: yaml
    url: https://rules.example.net/private-ip.yaml
    path: ./rules/private-ip.yaml
    interval: 86400

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

Domain 동작의 YAML 내용은 일반적으로 도메인 항목 목록이고, IPCIDR 동작은 네트워크 대역 목록입니다. Classical 내용에는 DOMAIN-SUFFIX, IP-CIDR 같은 완전한 규칙 유형이 포함됩니다. Classical 파일을 Domain으로 선언하면 파서가 로드를 거부하거나 항목이 예상과 다르게 해석될 수 있습니다. 직접 규칙 집합을 만들 때는 먼저 동작 유형을 정한 뒤 해당 형식에 맞게 작성하고 서로 다른 유형을 하나의 간소화된 집합에 섞지 마세요.

업데이트, 캐시와 실패 복구

원격 업데이트는 설정 변경으로 간주해야 합니다. 노드 제공자가 업데이트되면 현재 선택한 노드가 삭제되거나 이름이 바뀔 수 있고, 규칙 제공자가 업데이트되면 같은 도메인이 다른 집합에 매칭될 수 있습니다. 업데이트가 끝나면 제공자 상태, 정책 그룹의 현재 선택과 주요 서비스의 규칙 매칭을 확인하세요. 자동 업데이트라고 해서 확인이 필요 없는 것은 아닙니다. 특히 로컬 설정이 이름 필터에 의존한다면 원격 이름 변경이 그룹 구성원에 직접 영향을 줍니다.

제공자 가져오기에 실패했지만 캐시가 남아 있으면 클라이언트가 이전 데이터를 계속 사용할 수 있습니다. 연결 유지에는 도움이 되지만 업데이트가 성공했다고 오해하기 쉽습니다. 상태를 확인할 때는 “캐시를 로드함”과 “방금 원격 업데이트를 완료함”을 구분해야 합니다. 캐시 파일이 손상됐다면 원격 주소가 정상인지 확인한 뒤 해당 캐시 하나만 삭제하고 다시 가져오세요. 전체 클라이언트 디렉터리를 비우면 정책 선택, 설정과 문제 해결 단서까지 함께 사라집니다.

구독이 빈 내용을 반환했다고 해서 즉시 빈 결과로 장기간 사용할 로컬 파일을 덮어쓰지 마세요. 그래픽 클라이언트는 일반적으로 파싱 실패 시 이전 설정을 유지하지만 구현에 따라 처리 방식이 다를 수 있습니다. 수동 스크립트로 업데이트할 때는 먼저 임시 파일로 다운로드하고 YAML 및 설정 검사를 통과한 뒤 대상 파일로 교체해야 합니다. “검증 후 교체” 흐름을 사용하면 네트워크 중단이나 서버 이상으로 사용 가능한 설정이 빈 파일로 바뀌는 것을 막을 수 있습니다.

민감 정보와 이식 가능한 설정

설정의 구독 URL, 노드 비밀번호, UUID와 제어 키는 모두 접근 관련 정보입니다. 문제 해결을 위해 설정을 공유할 때는 이 값을 삭제하되 필드 구조, 프로토콜 유형과 오류 주변의 들여쓰기는 남겨 두세요. 노드명만 바꾸는 것으로는 인증 정보가 제거되지 않습니다. 로그에도 전체 구독 주소가 나타날 수 있으므로 다른 사람에게 보내기 전에 먼저 처리하세요.

데스크톱과 모바일 기기 간 이식성을 높이려면 원격 노드, 공통 정책 그룹과 규칙을 기본 계층에 두고 포트, 제어 인터페이스, TUN, DNS 수신 주소처럼 기기별로 다른 항목은 오버라이드 계층에 두세요. 전 플랫폼 클라이언트인 Clash Plus는 다운로드 페이지에서 운영체제에 맞게 받을 수 있습니다. 다른 클라이언트는 오버라이드 진입점과 로컬 디렉터리 표시 방식이 다를 수 있지만 기본 YAML의 참조 관계는 명확하게 유지해야 합니다.

CHAPTER 08

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

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

원격 구독은 보통 서버에서 관리되며 업데이트할 때 설정을 다시 생성합니다. 구독 파일에 DNS, 정책 그룹 또는 규칙을 직접 추가하면 다음 업데이트에서 원격 버전으로 돌아갈 수 있습니다. 오버라이드나 병합은 원본 구독을 수정하지 않고 업데이트 결과 위에 로컬의 장기 설정을 적용하는 기능입니다. 클라이언트에 따라 이 기능을 오버라이드, 병합, 확장 설정 또는 전처리라고 부를 수 있으며 화면 위치와 지원 문법도 완전히 같지 않습니다.

오버라이드를 설계할 때는 먼저 “값 하나를 교체”, “목록에 항목 추가”, “기존 항목 삭제”, “이름으로 객체 수정”이라는 네 가지 작업을 구분해야 합니다. 일반 YAML 병합은 객체 키의 덮어쓰기는 표현할 수 있지만 이름이 같은 두 정책 그룹의 구성원을 자동으로 병합해야 한다는 의미까지 이해하지는 못합니다. 클라이언트 내장 오버라이드 시스템은 전용 규칙을 제공할 수 있지만 모든 클라이언트가 같은 의미를 사용한다고 가정해서는 안 됩니다. 설정을 옮기기 전에 오버라이드 원본만 보지 말고 실제 최종 생성 결과를 확인하세요.

매핑 덮어쓰기와 목록 교체

매핑 필드는 보통 키 기준으로 덮어씁니다. 예를 들어 기본 설정이 mode: rule이고 로컬 오버라이드가 mode: global이면 일반적으로 뒤의 값이 최종값이 됩니다. 중첩 매핑을 깊게 병합하는지는 도구에 따라 다릅니다. 어떤 도구는 dns에서 지정한 하위 필드만 덮어쓰고, 어떤 도구는 새 dns 객체 전체로 기존 객체를 교체합니다. 오버라이드 후 nameserver가 갑자기 사라진다면 중첩 객체가 통째로 교체됐을 가능성이 큽니다.

# base.yaml
mixed-port: 7890
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5

# override.yaml
mode: rule
dns:
  ipv6: false
  fake-ip-filter:
    - '*.lan'

이상적인 깊은 병합 결과는 enable, enhanced-mode, nameserver를 유지하면서 ipv6와 필터 항목을 추가합니다. 전체 교체 결과에는 오버라이드의 두 필드만 남습니다. 파일명만으로 어떤 동작인지 판단할 수 없으므로 클라이언트에서 최종 설정을 내보내거나 확인해야 합니다. 처음 오버라이드를 설정할 때는 DNS와 정책 그룹 전체를 한 번에 추가하기보다 관찰하기 쉬운 민감하지 않은 필드 하나로 테스트하는 편이 의미를 확인하기 쉽습니다.

목록은 더욱 주의해서 다뤄야 합니다. rules, proxies, proxy-groups는 모두 목록입니다. 일반 병합 도구는 목록 전체를 교체하는 경우가 많고, 다른 도구는 앞이나 뒤에 추가하거나 이름으로 삽입할 수 있습니다. 로컬 규칙을 구독 규칙보다 우선해야 한다면 “앞에 규칙 추가” 기능을 명시적으로 사용하세요. MATCH 뒤에 단순히 추가하면 실행되지 않습니다. 클라이언트가 전체 교체만 지원한다면 원격 규칙을 모두 유지하거나 규칙 제공자로 전환해야 하며, 새 규칙 몇 줄만 작성해서는 안 됩니다.

YAML 앵커의 적용 범위

YAML 앵커는 같은 파일 안에서 반복되는 필드를 줄이는 데 사용할 수 있습니다. 예를 들어 여러 자동 정책 그룹이 같은 테스트 주소와 주기를 사용한다면 공통 매핑을 정의한 뒤 병합할 수 있습니다. 하지만 앵커는 한 번의 YAML 파싱 안에서만 유효하며 원격 구독과 로컬 오버라이드 파일 사이에서 자동으로 공유되지 않습니다. 일부 설정 처리기는 생성 단계에서 앵커를 펼치거나 제거하므로 사용 전에 클라이언트가 최종 결과를 읽을 수 있는지 확인하세요.

group-test: &group-test
  type: url-test
  url: https://www.gstatic.com/generate_204
  interval: 300
  tolerance: 80

proxy-groups:
  - name: 자동 선택
    <<: *group-test
    proxies:
      - Example-Trojan
      - Example-SS

  - name: 보조 자동 그룹
    <<: *group-test
    proxies:
      - Example-SS
      - Example-Trojan

앵커는 정적인 반복을 줄이는 데 적합하지만 복잡한 계층을 숨기는 용도로는 적합하지 않습니다. 과도하게 사용하면 독자가 병합 출처를 오가며 추적해야 하고 클라이언트 간 이식도 어려워집니다. 장기간 유지할 공개 설정이라면 약간의 중복을 남기더라도 각 정책 그룹의 핵심 동작이 눈에 보이게 작성하는 편이 낫습니다. 앵커를 펼친 최종 설정을 확인하기 어렵다면 클라이언트가 명확히 지원하는 오버라이드 방식을 우선 사용하세요.

단계별로 최종 설정 검증하기

설정 수정은 네 단계로 검증해야 합니다. 1단계에서는 들여쓰기, 따옴표와 데이터 유형을 확인해 YAML 문법을 검사합니다. 2단계에서는 노드, 정책 그룹, 제공자와 규칙 참조가 모두 존재하는지 객체 관계를 확인합니다. 3단계에서는 클라이언트를 로드해 포트, DNS와 제어 인터페이스가 시스템 리소스와 충돌하지 않는지 확인합니다. 4단계에서는 실제 연결로 규칙 매칭과 최종 출구를 검증합니다. 1단계만 완료했다고 설정을 사용할 수 있는 것은 아닙니다.

1. 기본 파일과 현재 사용 가능한 상태 저장

   원본 구독, 로컬 오버라이드와 최종 생성 설정의 사본을 보관하고 수정 전에 정상적으로 작동했던 정책을 기록하세요. 복구할 때 기억에 의존해 항목을 하나씩 되돌리는 대신 명확한 상태로 돌아갈 수 있어야 합니다.

2. 한 번에 하나의 설정 계층만 수정

   먼저 공통 필드를 수정하고, 다음으로 DNS를 처리한 뒤 정책 그룹과 규칙을 추가하세요. 노드를 바꾸고 TUN을 활성화하면서 DNS까지 다시 작성하면 오류가 발생했을 때 어느 계층이 원인인지 판단하기 어렵습니다.

3. 최종 펼침 결과 확인

   오버라이드 후 기존 목록이 여전히 유지되는지, 같은 이름의 정책이 교체됐는지, 규칙이 MATCH 앞에 있는지, 제공자 캐시 경로가 서로 분리되어 있는지 확인하세요.

4. 연결 흐름에 따라 테스트

   직접 연결, 로컬 프록시 포트, DNS 조회, 단일 노드, 정책 그룹과 규칙 라우팅을 순서대로 테스트하세요. 각 단계가 통과한 뒤 다음 단계로 넘어가야 모든 현상을 노드 문제로 몰아가지 않을 수 있습니다.

자주 발생하는 오류와 처리 순서

포트 충돌은 운영체제 네트워크 도구로 확인할 수 있습니다. Windows에서는 터미널에서 netstat -ano를 사용해 수신 포트를 확인하고, macOS와 Linux에서는 lsof 또는 ss를 사용할 수 있습니다. 점유 프로세스를 찾은 뒤 다른 프록시 클라이언트가 실행 중인지 먼저 판단하세요. 여러 클라이언트의 시스템 프록시와 TUN을 동시에 켜지 마세요. 포트가 서로 달라도 라우팅, DNS 또는 시스템 프록시가 반복해서 덮어써 순환이 생길 수 있습니다.

# Windows: 7890 포트 확인
netstat -ano | findstr :7890

# macOS: 7890 포트 확인
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux: 수신 포트 확인
ss -lntp | grep 7890

최소 설정에서 복구하기

복잡한 설정에서 원인을 찾기 어렵다면 최소 테스트 파일을 만들고 로컬 포트 하나, 사용 가능하다고 확인한 노드 하나, Select 정책 그룹 하나와 MATCH 규칙 하나만 남기세요. 먼저 TUN, 사용자 지정 DNS, 규칙 제공자와 스크립트 오버라이드를 끄고 기본 프록시 흐름을 확인합니다. 기본 흐름이 성공한 뒤 DNS, 제공자, 정책 그룹, 규칙, TUN 순서로 계층을 하나씩 다시 추가하세요. 수천 줄의 설정에서 무작위로 삭제하고 수정하는 것보다 신뢰할 수 있는 방법입니다.

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

proxies:
  - name: Test-Node
    type: trojan
    server: edge.example.net
    port: 443
    password: your-password
    sni: edge.example.net

proxy-groups:
  - name: 노드 선택
    type: select
    proxies:
      - Test-Node
      - DIRECT

rules:
  - MATCH,노드 선택

최소 설정에서도 실패한다면 로그를 바탕으로 로컬 포트, 노드 해석, 서버 연결 또는 TLS 인증 중 어디가 문제인지 판단해야 합니다. 최소 설정은 작동하지만 전체 설정이 실패한다면 나중에 추가한 계층 중 하나가 원인입니다. 계층을 하나씩 다시 추가할 때마다 작동 상태를 저장하면 원인 범위를 명확히 좁힐 수 있습니다. 더 많은 현상별 처리 방법은 문제 해결에서 확인하세요. 아직 설치와 첫 구독 가져오기를 완료하지 않았다면 빠른 시작으로 돌아가 기본 절차를 진행하세요.

장기 유지 관리 권장 사항

안정적인 설정은 필드 수가 아니라 관계의 명확성, 업데이트 제어 가능성, 장애 복구 가능성으로 평가합니다. 기본 계층에는 공통 포트, DNS와 소수의 안정적인 정책을 두고, 원격 계층은 노드와 대규모 규칙 집합을 담당하게 하세요. 기기 계층에는 TUN, 수신 주소와 시스템별 차이를 두고, 오버라이드 계층에는 오래 유지할 로컬 변경만 저장합니다. 각 계층은 출처와 역할을 독립적으로 설명할 수 있어야 합니다.

구독 또는 규칙 데이터베이스를 업데이트한 뒤에는 제공자 상태, 빈 정책 그룹, 현재 노드와 주요 규칙 매칭을 중점적으로 확인하세요. 클라이언트를 업그레이드한 뒤에는 설정 검사를 통해 고급 필드가 계속 지원되는지 확인하고 일상 설정을 활성화하세요. 문제가 발생하면 로그, 최종 펼침 설정과 최소 재현 구간을 보관하고 결과를 기록하지 않은 채 여러 설정 파일을 오가지 마세요. “문법—참조—포트—DNS—노드—정책—규칙—시스템 가로채기” 순서로 확인하면 대개 문제를 명확한 계층으로 좁힐 수 있습니다.