Clash YAML 설정 필드 참고

YAML 구조 개요

설정 파일은 임의로 이어 붙일 수 있는 매개변수 목록이 아니라 연결 처리 흐름을 정의합니다. 공통 필드는 수신 방식을 정하고, DNS는 도메인 조회를, 프록시 노드는 실제 아웃바운드를 담당합니다. 정책 그룹은 아웃바운드 선택을 구성하고, 규칙은 연결을 적절한 정책으로 전달합니다. 파일을 살펴볼 때는 먼저 최상위 항목을 구분한 다음 이름 참조를 따라가세요. 파일을 파싱할 수 있더라도 규칙에서 존재하지 않는 그룹을 참조하거나 정책 그룹에서 잘못된 노드 이름을 참조하면 로드 또는 연결 단계에서 실패할 수 있습니다.

맵, 리스트 및 들여쓰기

YAML의 맵은 키와 값으로 구성되고, 리스트 항목은 하이픈으로 시작하며, 계층은 공백 들여쓰기로 표현합니다. 공백 두 칸으로 통일하고 탭은 사용하지 않는 것이 좋습니다. 콜론 뒤에는 공백 하나를 두고 같은 수준의 필드는 맞춰 정렬하세요. 아래 설정은 내장 직결 정책만 사용해 최상위 구조를 보여 주며 원격 프록시 아웃바운드는 만들지 않습니다. 설정이 정상적으로 로드되는지 확인하기 위한 예제일 뿐, 노드가 포함된 구독 파일로 사용하면 안 됩니다.

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

proxies: []

proxy-groups:
  - name: 출구 선택
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,출구 선택

여기서 proxies: []는 빈 리스트를 뜻합니다. 필드가 없는 상태나 빈 문자열과는 다릅니다. proxy-groups는 리스트이며 각 항목은 다시 맵으로 구성됩니다. 그룹 안의 proxies는 이름 목록입니다. 최상위 노드 정의와 그룹 내부의 이름 참조는 같은 필드명을 사용해도 의미가 다릅니다. 수정할 때는 필드가 속한 계층을 함께 확인하세요. 단어 하나만 검색해 일괄 치환해서는 안 됩니다.

샵(#), 콜론 또는 특수 문자가 포함된 문자열은 따옴표로 묶는 것이 좋습니다. 특히 비밀번호, 구독 URL, 숫자처럼 보이는 식별자는 주의하세요. 따옴표가 없는 샵은 위치에 따라 주석 시작으로 처리될 수 있고, 큰따옴표를 잘못 사용하면 백슬래시 이스케이프가 발생할 수 있습니다. 일반 문자열에는 작은따옴표를 사용할 수 있으며, 문자열 자체에 작은따옴표가 있으면 YAML 규칙에 따라 작은따옴표 두 개를 연속으로 씁니다. 불리언은 true 또는 false로, 포트는 정수로 작성하세요. 모든 값을 무조건 문자열로 바꾸면 안 됩니다.

파일, 프로필 및 실행 설정

GUI 클라이언트에서 프로필은 대개 입력 자료일 뿐입니다. 클라이언트가 수신 포트, 컨트롤 인터페이스, TUN 매개변수와 사용자 오버라이드를 추가한 뒤 코어에 전달할 실행 설정을 생성할 수도 있습니다. 따라서 구독 원본과 실제 실행 파일이 다르다고 해서 반드시 가져오기에 실패한 것은 아닙니다. 특정 필드가 적용되지 않는 이유를 찾으려면 먼저 현재 활성 프로필을 확인하고, 클라이언트의 실행 설정 미리보기나 관련 로그를 살펴보세요.

같은 맵 계층에서 동일한 키를 중복 정의하면 안 됩니다. 예를 들어 dns를 한 번 작성한 뒤 파일 끝에 다시 dns를 추가해도 설정이 안정적으로 누적되지는 않습니다. 파서에 따라 중복 키를 거부하거나 둘 중 하나만 남길 수 있습니다. 의도한 하위 필드를 하나의 맵에 모아야 설정을 명확하게 표현할 수 있습니다. 리스트 추가나 맵의 재귀 병합은 클라이언트 또는 스크립트의 동작이지 YAML 형식 자체가 통일된 방식으로 제공하는 기능이 아닙니다.

파일은 UTF-8 인코딩으로 저장하고 정상적으로 시작되는 사본을 따로 보관하세요. 오류가 생기면 사본을 복원한 뒤 수정 범위를 좁히는 편이 클라이언트를 반복해서 재설치하는 것보다 원인을 찾기 쉽습니다. 명령줄 테스트를 지원하는 환경에서는 다음 명령으로 설정을 검사할 수 있습니다. 실행 파일과 설정 파일의 경로는 현재 기기에 맞춰 지정해야 합니다. 테스트 통과는 코어가 설정을 받아들였다는 뜻일 뿐, 원격 노드, DNS 또는 네트워크 권한이 정상이라는 보장은 아닙니다.

mihomo -t -f ./config.yaml

원본 Clash, mihomo, 각종 GUI 클라이언트는 지원하는 필드가 서로 다릅니다. 예제를 복사하기 전에 앱 이름만으로 추측하지 말고 실제 사용 중인 코어를 확인하세요. GUI와 코어의 역할을 더 알아보려면 Clash 오픈 소스 생태계와 클라이언트 구성을 참고하세요. 이 핸드북에서는 필드 간 의존 관계를 중심으로 설명합니다.

공통 필드 및 트래픽 처리 방식

공통 필드는 트래픽이 코어에 들어오는 경로와 코어가 연결을 처리하는 방식을 정합니다. 수신 포트, 시스템 프록시, TUN은 서로 관련은 있지만 다른 개념입니다. 포트는 코어가 제공하는 로컬 진입점이고, 시스템 프록시는 운영체제가 앱에 알리는 진입 주소이며, TUN은 가상 네트워크 인터페이스를 통해 라우팅 조건에 맞는 패킷을 받습니다. 수신 포트만 설정했다고 해서 시스템이 앱 트래픽을 해당 포트로 보내는 것은 아닙니다.

수신 포트 및 접근 범위

포트 번호가 항상 고정되는 것은 아닙니다. 예제 값은 흔히 쓰이는 숫자일 뿐입니다. 기기에서 다른 프로세스가 같은 포트를 사용 중이면 코어가 수신하지 못할 수 있습니다. 로그에서 주소와 포트를 확인한 뒤 충돌 항목을 변경하세요. 클라이언트가 시스템 프록시를 설정한다면 새 포트로 동기화됐는지도 확인해야 합니다. 구독 파일의 숫자만 바꾸고 클라이언트는 이전 진입점을 계속 가리키면 코어는 정상 작동해도 브라우저가 연결되지 않을 수 있습니다.

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

수신 주소는 서비스가 바인딩되는 로컬 인터페이스를 지정합니다. 이 기기에서만 사용할 때는 진입점을 루프백 범위로 제한할 수 있습니다. LAN 기기와 공유해야 한다면 수신 주소, LAN 접근 허용 및 방화벽 규칙을 함께 검토하세요. 컨트롤 인터페이스는 코어 관리용이며 브라우저에 입력하는 프록시 포트가 아닙니다. 다른 기기에 관리 인터페이스를 공개하기 전에는 인증 정보를 설정하고 네트워크 범위를 제한해야 합니다. 둘 다 포트로 표시된다는 이유로 같은 기능으로 취급하면 안 됩니다.

규칙, 전역 및 직결 모드

rule 모드는 규칙 목록에 따라 정책을 선택하고, global 모드는 연결을 전역 정책으로 전달하며, direct 모드는 트래픽을 직결 처리합니다. 모드를 바꿔도 노드 연결 상태가 확인되는 것은 아닙니다. 전역 모드라고 해서 모든 앱의 트래픽이 자동으로 처리되는 것도 아닙니다. 앱이 시스템 프록시를 사용하지 않는다면 전역 모드로 전환해도 트래픽 진입 경로는 달라지지 않을 수 있습니다. 먼저 트래픽 처리 경로를 확인한 다음 분기 결과를 점검하세요.

TUN 모드 및 플랫폼 권한

TUN은 시스템 프록시 설정을 따르지 않는 앱의 트래픽을 처리하는 데 적합하지만, 가상 인터페이스와 시스템 라우팅, 실행 권한이 필요합니다. 클라이언트마다 서비스 프로세스, 관리자 승인 또는 플랫폼 네트워크 확장 기능을 통해 인터페이스를 만들 수 있으므로 한 플랫폼의 권한 설정을 다른 플랫폼에 그대로 적용하면 안 됩니다. 아래는 mihomo에서 흔히 쓰이는 필드의 관계를 보여 줍니다. GUI 클라이언트가 이미 해당 필드를 관리한다면 설정 페이지를 이용해 설정이 생성되는 과정에서 서로 덮어쓰지 않도록 하세요.

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

auto-route는 관련 라우트를 자동으로 설정하고, auto-detect-interface는 아웃바운드 인터페이스를 감지하며, dns-hijack는 일치하는 DNS 요청을 가로채는 데 관여합니다. 이 옵션들이 모든 네트워크 환경에서 정상 작동하는 것은 아닙니다. 다른 VPN, 가상 머신 네트워크 어댑터, 기업용 네트워크 소프트웨어 또는 수동 라우팅이 경로를 바꿀 수 있습니다. 활성화 후 LAN 리소스에 접근할 수 없다면 라우트와 제외 범위를 확인하세요. 모든 DNS 설정을 꺼서 문제를 덮으려 해서는 안 됩니다.

시스템 프록시와 TUN을 함께 사용할 수 있지만, 문제를 진단할 때는 먼저 트래픽 처리 방식을 하나로 명확하게 유지하는 것이 좋습니다. 로컬 진입점으로 브라우저 연결이 되는지 확인한 뒤 TUN을 활성화해 다른 앱을 테스트하세요. 활성화한 다음에만 오류가 생긴다면 권한, 인터페이스 및 라우팅 변경을 중점적으로 점검합니다. 복구하기 전에 현재 설정을 기록하세요. 특히 클라이언트가 종료될 때 시스템 프록시를 자동 복원하는지 확인해야 앱 종료 후 시스템이 이미 중지된 포트를 가리키는 일을 막을 수 있습니다.

Windows의 앱 컨테이너 접근, Android의 VPN 권한, 데스크톱의 백그라운드 서비스는 플랫폼의 트래픽 처리 계층 문제이지 YAML 문법 오류와는 다릅니다. 플랫폼별 사용 방법은 빠른 시작에서 확인하고, 이상 증상은 도움말 센터에서 찾아보세요. 클라이언트 선택 시 다운로드 센터의 Clash Plus 플랫폼 옵션을 먼저 확인한 뒤 필요한 트래픽 처리 기능을 점검할 수 있습니다.

DNS 조회

DNS 설정은 세 가지를 함께 설명해야 합니다. 누가 코어에 조회를 요청하는지, 코어가 어느 업스트림에 질의하는지, 그리고 질의가 어떤 네트워크 경로를 이용하는지입니다. DNS 주소 한 곳만 바꿔도 브라우저 내장 암호화 DNS, 시스템 캐시, 다른 네트워크 서비스까지 자동으로 제어되지는 않습니다. DNS 유출을 분석하려면 먼저 코어가 처리해야 할 요청의 범위를 정하고 트래픽 처리 방식과 로그를 확인하세요. 검사 페이지 하나에 표시된 지역만 보고 결론 내리면 안 됩니다.

수신, 업스트림 및 부트스트랩 조회

enable은 코어의 DNS 모듈을 제어하고, listen은 수신 주소를 지정하며, nameserver는 일반 조회에 사용할 업스트림을 지정합니다. 업스트림 주소에 도메인이 포함되어 있다면 코어가 먼저 해당 도메인의 IP를 알아내야 합니다. 이를 위한 부트스트랩 조회에는 default-nameserver를 사용할 수 있습니다. 부트스트랩 DNS가 현재 네트워크에서 실제로 접근 가능한지 확인하세요. 그렇지 않으면 암호화된 업스트림에 연결하기도 전에 조회가 막히는 순환 의존이 생길 수 있습니다.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 1.1.1.1
    - 8.8.8.8
  nameserver:
    - https://cloudflare-dns.com/dns-query
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - localhost

이 예제는 필드 구조를 보여 줄 뿐, 나열된 공용 DNS 서비스가 모든 네트워크에 적합하다는 뜻은 아닙니다. 포트 1053이 자동으로 시스템 DNS가 되는 것도 아닙니다. 클라이언트의 DNS 가로채기 설정이나 별도의 명시적인 전달 방식이 필요합니다. 데스크톱 환경에서 시스템 리졸버가 비표준 포트를 지정할 수 없다면 이 수신 주소를 시스템 설정에 그대로 복사해서는 안 됩니다. 실제 요청이 들어오는지는 코어 로그와 앱 접속 결과로 확인하세요.

fake-ip 및 실제 주소 응답

fake-ip 모드는 앱에 매핑된 주소를 반환하고, 코어는 주소와 도메인의 관계를 보관합니다. 이후 연결이 코어에 들어오면 이 정보를 바탕으로 도메인 규칙을 적용합니다. 목적은 분기에 필요한 도메인 정보를 보존하는 것이지, 대상 서버를 실제로 매핑 대역의 주소로 바꾸는 것이 아닙니다. 앱이 매핑 주소를 받았지만 코어를 우회해 직접 연결하면 접속이 실패할 수 있으므로 DNS 응답 경로와 연결 처리 경로를 함께 확인해야 합니다.

fake-ip-filter를 사용하면 일부 도메인에는 매핑 주소 대신 실제 주소를 반환할 수 있습니다. LAN 서비스, 실제 주소가 필요한 기기 검색 절차 또는 호환성 문제가 있는 앱은 필요한 도메인만 필터에 추가할 수 있습니다. 도메인 하나의 문제를 해결하려고 모든 도메인을 필터링하지 마세요. 다른 규칙에서 도메인 정보를 얻는 조건까지 달라질 수 있습니다. 필터를 추가한 뒤에는 관련 캐시를 지우거나 영향을 받는 앱을 다시 시작해 이전 매핑과 새 응답이 함께 남지 않도록 하세요.

실제 주소를 반환하는 조회 방식에서는 앱이 실제 IP를 받습니다. 도메인 규칙을 적용할 수 있는지는 코어가 확보한 정보와 연결 진입 경로에 따라 달라집니다. IP 규칙은 추가 조회를 발생시킬 수 있고, 도메인 스니핑으로 모든 프로토콜의 이름을 복원할 수 있는 것도 아닙니다. 두 모드를 비교할 때는 실제 규칙 일치 결과와 대상 앱의 동작, 로그를 살펴보세요. 한 모드가 항상 더 빠르거나 다른 모드가 항상 더 안전하다고 단정하면 안 됩니다.

도메인별 업스트림 및 조회 경로

nameserver-policy를 사용하면 특정 도메인의 업스트림을 지정할 수 있습니다. 예를 들어 내부 도메인은 해당 네트워크의 DNS 서버에 질의해야 할 수 있습니다. 이는 DNS 서버 선택에 관한 설정이지 최종 서비스 연결의 프록시 아웃바운드를 지정하는 설정은 아닙니다. 서비스 트래픽은 여전히 규칙과 정책 그룹에 따라 처리됩니다. respect-rules를 사용해 DNS 연결도 규칙을 따르게 한다면 프록시 서버 도메인의 조회 출처를 함께 고려하세요. 프록시에 아직 연결할 수 없는데 프록시에 연결해야만 프록시 도메인을 조회할 수 있는 상황을 피해야 합니다.

dns:
  enable: true
  nameserver:
    - https://cloudflare-dns.com/dns-query
  nameserver-policy:
    '+.example.com':
      - 192.168.1.1

여기서 LAN 주소는 “현재 네트워크의 DNS 서버에 질의한다”는 사용 예를 나타내므로 실제로 쓸 수 있는 주소로 바꿔야 합니다. 기업 내부 도메인을 공용 DNS에 잘못 보내면 레코드가 없다는 응답을 받을 수 있습니다. 반대로 외부 도메인을 모두 내부 DNS에 보내면 해당 네트워크 정책의 영향을 받을 수 있습니다. 도메인 접미사 정책을 사용할 때는 일치 범위를 확인하고, 명확한 테스트 도메인 하나로 동작을 검증한 다음 범위를 넓히세요.

문제 해결은 도메인과 IP를 비교하는 것부터 시작할 수 있습니다. 같은 대상에서 IP로는 접속되지만 도메인으로는 실패하면 DNS 로그를 먼저 확인하세요. 특정 앱에서만 문제가 생기면 앱 자체의 DNS 설정을 확인합니다. 노드 도메인을 조회하지 못한다면 부트스트랩과 노드 조회 경로부터 점검하세요. 설정을 바꾼 뒤 새 연결로 다시 시도하고, 필요하면 시스템 및 앱 캐시를 비웁니다. 자세한 순서는 노드 시간 초과 및 연결 실패 문제 해결을 참고하세요.

프록시 노드 필드

프록시 노드 정의에는 원격 서비스에 연결하는 데 필요한 프로토콜 매개변수가 들어갑니다. 노드 이름, 지역 태그, 속도 측정 결과와는 별개의 정보입니다. 이름은 참조와 식별에 쓰이고, 실제 연결 동작은 프로토콜, 주소, 포트, 인증 및 전송 설정에 따라 달라집니다. 입력하기 전에 서비스 제공자가 안내한 매개변수를 모두 확인하세요. 서버 주소만 보고 프로토콜을 추측하거나 다른 클라이언트의 필드명을 YAML에 그대로 옮겨도 같은 의미일 거라고 가정하면 안 됩니다.

공통 필드 및 프로토콜별 필드

일반적인 공통 필드에는 name, type, server, port가 있습니다. name은 정책 그룹에서 참조하는 이름과 정확히 일치해야 하므로 중복되지 않고 알아보기 쉽게 지정하는 것이 좋습니다. type에 따라 유효한 필드가 달라지고, server에는 도메인이나 IP를 쓸 수 있습니다. port는 원격 서비스의 진입 포트이지 로컬 수신 포트가 아닙니다. 두 포트 개념을 뒤바꾸면 YAML 파싱 오류 대신 연결 실패로 나타날 수 있습니다.

proxies:
  - name: SS 예제
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: 'your-password'
    udp: true

이 조각은 Shadowsocks 노드의 필드 구조를 보여 줍니다. 예제 도메인과 비밀번호로는 실제 연결할 수 없습니다. cipher와 비밀번호는 서버 설정과 일치해야 하며, “보안을 강화한다”는 이유로 알고리즘 이름만 임의로 바꾸면 안 됩니다. 포트가 443이라고 해서 HTTPS나 TLS를 사용하는 것도 아닙니다. 암호화 및 위장 기능의 유무는 포트 숫자가 아니라 해당 프로토콜과 전송 필드로 확인해야 합니다.

TLS, SNI 및 전송 매개변수

TLS를 사용하는 프로토콜은 서버 이름과 인증서의 관계도 확인해야 합니다. 연결 주소, TLS의 SNI, WebSocket의 Host, 경로는 각각 다른 역할을 할 수 있습니다. 서버에서 우연히 같은 도메인을 사용하더라도 서로 대체할 수 있는 필드라고 보면 안 됩니다. 일부 프로토콜은 servername을 사용하고 다른 프로토콜은 별도 필드를 사용할 수 있습니다. 프로토콜별 설정 구조를 확인해 겉보기에는 범용적이지만 실제로 인식되지 않는 매개변수 목록을 만들지 마세요.

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

인증서 오류가 발생하면 검증을 바로 건너뛰기보다 시스템 시간, 도메인, 인증서 체인 및 서버 설정을 먼저 확인하세요. 검증을 끄면 연결 상대를 인증하는 조건이 달라질 뿐, 잘못 입력한 SNI가 수정되지는 않습니다. 서비스 제공자가 별도 인증서나 전용 전송 매개변수를 요구한다면 안내 출처를 확인하고 해당 프로토콜에 맞게 설정하세요. 프로토콜별 필드가 많으므로 이 핸드북은 확인 방법을 안내하며 서로 다른 프로토콜의 매개변수를 하나의 예제에 몰아넣지 않습니다.

노드 정의와 실제 연결 가능성

udp: true는 해당 기능을 설정에서 허용한다는 뜻일 뿐, UDP를 지원하지 않는 서버에 그 기능을 추가하지 않습니다. 앱은 시스템 프록시 유형, TUN 처리, 통신사 네트워크 및 방화벽의 영향도 받을 수 있습니다. 웹페이지는 열리지만 음성 통화나 게임에 문제가 생긴다면 TCP와 UDP 경로를 각각 검증하세요. HTTP 테스트 한 번에 성공했다고 모든 전송 방식이 정상이라고 볼 수는 없습니다.

파일에 노드를 추가한 뒤에는 정책 그룹이나 규칙에서 실제로 참조해야 합니다. proxies에 항목을 추가해도 현재 아웃바운드가 자동으로 바뀌지는 않습니다. 연결 화면을 볼 때는 일치한 규칙, 거친 정책 그룹, 최종 노드를 함께 확인하세요. 규칙이 여전히 직결을 선택한다면 새 노드의 비밀번호부터 의심할 필요는 없습니다. 반대로 정책이 해당 노드를 가리키는데 핸드셰이크가 실패한다면 주소, 인증 및 프로토콜 매개변수를 확인하세요.

구독에는 접근 인증 정보가 포함되는 경우가 많고, 스크린샷과 로그에도 노드 주소 전체가 노출될 수 있습니다. 문제를 공유할 때는 필요한 필드만 남기고 비밀번호와 구독 주소의 민감한 부분을 가리세요. 원본 링크, YAML 및 다른 설정 형식을 비교한다면 프로토콜이 모두 표현됐는지 항목별로 확인해야 합니다. 변환에 성공했다고 모든 기능이 보존된 것은 아닙니다. 관련 차이는 구독 형식 비교 및 변환을 참고하세요.

정책 그룹

정책 그룹은 규칙과 노드 사이에 있습니다. 규칙에서 특정 원격 노드를 직접 지정하는 대신 용도가 분명한 그룹 이름을 참조하고, 그룹에서 사용할 아웃바운드를 결정하는 방식이 일반적입니다. 이렇게 하면 구독을 바꾸거나 노드를 전환해도 규칙은 그대로 둘 수 있습니다. 정책 그룹을 설계할 때는 지역별 이름으로 여러 계층을 쌓기보다 선택 기준과 참조 관계부터 명확히 하세요. 중첩 계층을 추가할 때마다 해결하려는 선택 문제가 무엇인지 설명할 수 있어야 합니다.

수동 선택, 자동 검사 및 장애 조치

select는 직접 선택하는 방식으로 사용자용 기본 진입점에 적합합니다. url-test는 지정한 대상의 검사 결과에 따라 아웃바운드를 선택하고, fallback은 후보 순서에 따라 사용 가능한 항목을 선택하며, load-balance는 설정된 정책에 따라 연결을 분배합니다. 각 유형의 목적은 다릅니다. 검사 시간이 짧다고 특정 서비스에서 더 좋은 경험을 보장하는 것은 아니며, 장애 조치가 여러 노드의 대역폭을 합쳐 주는 것도 아닙니다.

proxy-groups:
  - name: 출구 선택
    type: select
    proxies:
      - 자동 선택
      - DIRECT

  - name: 자동 선택
    type: url-test
    use:
      - 기본 구독
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

이 조각은 아래에서 정의하는 기본 구독 provider를 참조합니다. use는 원격 노드 모음을 참조하고, proxies는 개별 노드, 내장 정책 또는 다른 정책 그룹을 참조합니다. 둘 다 이름으로 표시된다고 서로 바꿔 쓸 수 있는 것은 아닙니다. 파일을 읽기 쉬운 순서로 정렬할 수는 있지만 모든 참조가 최종 설정에 존재해야 합니다. 이름의 공백, 기호 및 대소문자도 일치시켜야 합니다.

url은 검사 대상이고 interval은 검사 간격입니다. tolerance를 사용하면 미세한 검사 결과 차이로 전환이 자주 발생하는 일을 줄일 수 있습니다. 예제 숫자는 매개변수의 단위와 관계를 설명하기 위한 값입니다. 현재 네트워크나 일부 노드에서 대상에 접근할 수 없다면 검사 결과는 노드 전체 품질보다 해당 대상의 접근 가능성을 반영할 수 있습니다. 검사 사이트 하나에 접속하지 못한다고 서버 전체를 사용할 수 없다고 단정하지 마세요.

후보 범위 및 이름 안정성

구독 노드가 많다면 지원되는 필터 필드로 후보 범위를 제한할 수 있습니다. 필터는 대개 이름을 기준으로 하므로 구독 제공자의 이름 지정 방식에 따라 결과가 달라집니다. 지역명, 기호 또는 태그가 바뀌면 기존 표현식으로 노드를 하나도 찾지 못할 수 있습니다. 필터를 조정한 뒤에는 YAML 테스트 통과 여부뿐 아니라 그룹에 실제로 포함된 항목도 확인하세요. 정규식을 사용한다면 YAML 따옴표 처리와 정규식 자체의 이스케이프 규칙을 함께 고려해야 합니다.

같은 설정 안에 의미가 다른 그룹이나 노드가 같은 이름으로 여러 개 있으면 안 됩니다. 규칙을 오래 유지하려면 “업무 서비스”나 “미디어 서비스”처럼 용도가 명확한 그룹 이름을 정하고, 실제 노드 선택은 하위 아웃바운드 그룹에 맡길 수 있습니다. 그러면 노드 출처가 바뀌어도 규칙을 대량 수정할 필요가 없습니다. 반면 모든 서비스가 결국 같은 아웃바운드를 사용한다면 진입 그룹 하나면 충분할 수 있습니다. 겉으로 분류를 늘리려고 중복 구조를 만들 필요는 없습니다.

중첩, 저장 상태 및 전환 확인

그룹이 다른 그룹을 참조할 수 있지만 순환 참조는 만들면 안 됩니다. 예를 들어 A 그룹이 B 그룹을 참조하고 B 그룹이 다시 A 그룹을 참조하는 경우입니다. 복잡한 참조 관계는 규칙 대상부터 시작해 실제 아웃바운드 경로를 노드나 내장 정책에 도달할 때까지 단계별로 그려 보세요. 어느 단계에서 이미 거친 그룹으로 되돌아간다면 구조를 다시 나눠야 합니다. 특히 여러 오버라이드 파일에서 그룹 멤버를 각각 추가할 때 순환 참조를 놓치기 쉽습니다.

클라이언트가 수동 선택을 기억할 수 있고, 설정에서 profile.store-selected로 관련 상태를 저장할 수도 있습니다. 상태를 저장해도 이름을 바꾼 뒤 올바르게 복원된다는 보장은 없습니다. 이전 이름이 사라지면 클라이언트나 코어가 기본 후보를 선택할 수 있습니다. 구독을 업데이트한 뒤 현재 선택이 의도한 아웃바운드를 가리키는지 확인하세요. 특히 업무별 그룹을 분리한 설정에서는 선택 변경을 규칙 순서 문제로 오해하지 않도록 주의해야 합니다.

정책을 전환하면 주로 새 연결에 적용되며 이미 연결된 장시간 세션은 이전 아웃바운드를 계속 사용할 수 있습니다. 확인할 때는 앱 세션을 새로 고치거나 연결을 다시 만든 다음 연결 화면에서 실제 경로를 살펴보세요. 기존 연결을 끊어야 한다면 다운로드, 회의 또는 기타 진행 중인 작업에 미칠 영향을 고려해야 합니다. 화면 버튼 위치는 클라이언트의 프록시, 프로필 및 연결 화면 안내를 참고하세요.

규칙 문법

규칙은 위에서 아래로 평가되며 먼저 일치한 규칙이 처리 정책을 결정합니다. 규칙을 관리할 때는 개수보다 순서가 중요한 경우가 많습니다. 구체적인 예외는 범위가 넓은 규칙보다 앞에, 최종 기본 규칙은 맨 뒤에 두세요. 규칙 대상은 정책 그룹, 노드 또는 내장 정책일 수 있지만 현재 실행 설정에서 유효해야 합니다. 규칙 자체가 올바르더라도 앞의 포괄적인 규칙에 항상 먼저 걸리면 기대한 결과를 얻을 수 없습니다.

도메인, 주소 및 기본 규칙

rules:
  - DOMAIN,login.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,출구 선택
  - DOMAIN-KEYWORD,example,출구 선택
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,출구 선택

DOMAIN은 전체 도메인과 일치하므로 특정 호스트를 따로 처리할 때 적합합니다. DOMAIN-SUFFIX는 지정한 도메인과 하위 도메인에 일치합니다. DOMAIN-KEYWORD는 도메인 내 키워드를 기준으로 일치하므로 범위가 넓어 주의해서 사용해야 합니다. 예제에서는 먼저 로그인 도메인을 직결로 처리한 다음 도메인 접미사 전체를 지정합니다. 접미사 규칙을 앞에 두면 로그인 도메인은 뒤의 정확한 예외 규칙까지 도달하지 않습니다.

IP-CIDR은 대상 주소가 속한 네트워크 대역을 기준으로 일치하며, LAN 주소나 고정 서비스 주소에 자주 사용합니다. no-resolve는 해당 규칙에 일치시키기 위해 도메인 조회를 새로 시작하지 않는다는 뜻입니다. DNS를 전체적으로 끈다는 뜻도, 대상 IP가 이미 있을 때 비교를 생략한다는 뜻도 아닙니다. 불필요한 조회를 줄이는 데 유용하지만, 도메인 조회 후에야 특정 IP 규칙과 일치하는 설정이라면 그에 따른 일치 범위를 이해해야 합니다.

MATCH는 앞에서 일치하지 않은 연결을 처리하는 최종 기본 규칙입니다. 목록 맨 앞에 두면 대부분의 뒤쪽 규칙이 평가되지 않습니다. 기본 경로는 “분류되지 않음”을 오류로 취급하기보다 명확한 의도를 반영해야 합니다. 관리할 때는 검증 가능한 소수의 규칙과 기본 규칙 하나로 일치 관계를 확인한 뒤 큰 규칙 모음을 추가하세요. 진입점, DNS, 노드, 규칙을 한꺼번에 바꾸면 원인을 구분하기 어렵습니다.

프로세스 규칙 및 플랫폼별 차이

프로세스 규칙으로 앱별 트래픽을 분기할 수 있지만, 현재 플랫폼의 기능과 권한, 트래픽 처리 경로가 코어에 프로세스 정보를 제공해야 합니다. 다른 기기에서 전달된 연결은 원격 기기의 앱 프로세스와 연결되지 않을 수 있습니다. 일부 플랫폼의 네트워크 인터페이스는 동일한 정보를 제공하지도 않습니다. 따라서 다른 컴퓨터에서 작동한 프로세스 규칙이 휴대전화나 라우터에서도 그대로 작동한다고 볼 수 없습니다.

도메인 규칙도 필요한 정보가 있어야 일치합니다. 앱이 IP에 직접 연결하거나 자체 조회 절차를 사용하거나 다른 방식으로 코어에 연결하면 연결 기록에 예상한 도메인이 없을 수 있습니다. 이때 도메인 접미사 규칙을 계속 추가해도 해결되지 않을 수 있으므로 DNS 처리와 연결 메타데이터를 먼저 확인하세요. 스니핑으로 이름을 보완할 수 있는 경우도 있지만 프로토콜과 암호화 방식에 제한이 있으므로 명확한 DNS 및 라우팅 설계를 대신할 수는 없습니다.

규칙 provider 및 실제 일치 결과

RULE-SET은 rule-providers에 정의된 규칙 모음을 참조합니다. 도메인 모음, 주소 모음 또는 기존 형식의 규칙 모음에 사용할 수 있지만 리소스 형식은 provider의 동작 유형과 일치해야 합니다. 전체 설정 파일을 도메인 목록으로 불러오거나 정책 대상이 포함된 규칙을 도메인만 허용하는 리소스에 넣으면 형식 오류가 발생합니다. 리소스 정의와 로드 방법은 다음 장을 참고하세요.

분기가 잘못될 때는 먼저 안정적이고 명확한 대상 하나를 정한 뒤 새 연결을 만들어 일치한 규칙 이름과 정책 경로를 확인하세요. 대상이 원치 않는 앞쪽 규칙에 걸리면 해당 규칙의 범위를 줄이거나 순서를 조정합니다. 올바른 규칙에 이미 일치했는데 접속이 실패한다면 최종 노드와 조회 결과를 확인하세요. 이렇게 하면 “잘못된 아웃바운드 선택”과 “아웃바운드 사용 불가”를 구분해 노드 문제를 규칙 문법 탓으로 돌리는 일을 피할 수 있습니다.

대규모 규칙 모음은 원본 업데이트에 따라 내용이 바뀔 수 있습니다. 관리할 때는 로컬 예외를 최소한으로 유지하고 삽입 위치를 명확히 하세요. 원격 규칙 리소스를 직접 수정한 뒤 업데이트 후에도 변경 내용이 남아 있을 거라고 기대하면 안 됩니다. 계속 유지해야 하는 규칙은 별도 오버라이드나 로컬 리소스에 두고 구독 업데이트 후 최종 순서를 다시 확인하세요. 모드와 규칙에 관한 흔한 오해는 도움말 센터에서 더 알아볼 수 있습니다.

구독 및 원격 리소스

구독이 모두 같은 파일 형식인 것은 아닙니다. 어떤 주소는 완전한 Clash 설정을 반환하고, 어떤 주소는 노드 목록만 반환하며, 또 다른 주소는 노드 공유 링크를 인코딩한 텍스트를 반환합니다. GUI 클라이언트가 구독 변환이나 전처리를 제공할 수는 있지만 코어의 proxy-providers가 모든 형식을 자동으로 인식해 노드로 사용할 수 있는 것은 아닙니다. 설정 전에 응답 구조를 확인한 뒤 클라이언트에서 완전한 설정으로 가져올지, 코어에서 원격 노드 리소스로 불러올지 결정하세요.

노드 provider

proxy-providers:
  기본 구독:
    type: http
    url: 'https://subscription.example.com/nodes.yaml'
    path: ./providers/main.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

proxy-groups:
  - name: 출구 선택
    type: select
    use:
      - 기본 구독

rules:
  - MATCH,출구 선택

type: http는 원격 주소에서 리소스를 가져온다는 뜻이고, url은 리소스 주소, path는 로컬 캐시 위치, interval은 업데이트 간격입니다. 예제 주소는 설명용이므로 호환되는 노드 목록을 실제로 반환하는 구독 주소로 바꿔야 합니다. 캐시 경로는 대개 코어의 작업 디렉터리를 기준으로 하며 구독 파일이 있는 위치를 기준으로 하지 않을 수 있습니다. 데스크톱과 모바일 클라이언트의 쓰기 가능 경로도 다를 수 있습니다.

노드 provider 리소스는 보통 최상위 proxies 목록을 포함하며 포트, DNS, 규칙이 모두 들어 있는 완전한 설정 파일이 아닙니다. 아래는 리소스 파일의 형태를 보여 주는 예제이며 실제 연결할 수 없는 설명용 매개변수를 사용합니다. 구독이 웹페이지, 로그인 안내 또는 오류 메시지를 반환하면 HTTP 요청 자체가 성공했더라도 사용할 노드를 얻지 못합니다. 클라이언트 로그에서 응답의 콘텐츠 유형과 파싱 오류를 확인하세요.

proxies:
  - name: 구독 예제 노드
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: 'your-password'
    udp: true

업데이트 간격과 상태 검사 간격은 서로 다른 기능입니다. 전자는 노드 정의의 변경 사항을 가져오고, 후자는 이미 등록된 노드의 사용 가능 여부를 검사합니다. 상태 검사 간격을 줄여도 새 노드가 구독에 더 빨리 나타나는 것은 아닙니다. 노드가 많을 때 검사를 너무 자주 하면 네트워크 요청이 증가할 수 있습니다. 리소스 변경 빈도, 기기 배터리 및 실제 선택 요구를 고려해 설정하고 모든 간격을 무조건 짧게 만들지 마세요.

규칙 provider

rule-providers:
  서비스 도메인:
    type: http
    behavior: domain
    format: yaml
    url: 'https://rules.example.com/business.yaml'
    path: ./rules/business.yaml
    interval: 86400

rules:
  - RULE-SET,서비스 도메인,출구 선택
  - MATCH,DIRECT

behavior는 규칙 리소스를 해석하는 방식을 정합니다. 일반적인 domain, ipcidr, classical은 각각 다른 내용을 나타냅니다. format은 파일 인코딩 형식을 지정하므로 확장자만 보고 판단하면 안 됩니다. 도메인 유형의 YAML 리소스는 대개 항목을 payload로 감쌉니다. 기존 형식의 규칙 리소스는 더 많은 규칙 유형을 표현할 수 있지만 해당 형식을 따라야 하며 완전한 설정의 최상위 필드를 섞어 넣을 수는 없습니다.

payload:
  - '+.example.com'
  - api.example.net

리소스 이름과 캐시 경로는 각각 고유해야 합니다. 두 provider가 같은 로컬 파일을 사용하면 나중 업데이트가 이전 내용을 덮어써 현재 모음과 관계없는 규칙이 로드될 수 있습니다. 리소스 유형이나 형식을 바꾼 뒤에는 이전 캐시가 계속 사용되는지도 확인하세요. 클라이언트 데이터 디렉터리 전체를 바로 지우지 마세요. 로그에서 관련 캐시 파일을 찾고 복구할 수 있는 사본을 남기세요.

업데이트 실패, 부트스트랩 의존성 및 개인정보

원격 리소스 업데이트에 실패하면 코어가 기존 캐시를 계속 사용할 수도 있고, 처음 실행해 사용할 파일이 없으면 로드를 완료하지 못할 수도 있습니다. 실제 동작은 로그를 확인하세요. 구독을 가져오려면 특정 프록시를 거쳐야 하는데 그 프록시도 해당 구독에서만 얻을 수 있다면 시작 단계에서 의존성이 생깁니다. 해결하려면 접근 가능한 업데이트 경로나 별도의 초기 연결 경로를 마련해야 합니다. 아직 없는 노드로 다운로드가 될 거라 기대하며 업데이트 버튼을 반복해서 눌러서는 안 됩니다.

구독 주소에는 접근 인증 정보가 포함되는 경우가 많으므로 공개 저장소나 공개 변환 서비스에 올리면 안 됩니다. 형식을 변환할 때는 변환 서비스가 어떤 정보를 볼 수 있는지 먼저 확인한 뒤 출력에 프로토콜, 전송 설정 및 그룹 정보가 보존됐는지 점검하세요. 여러 기기 간 동기화에서도 “같은 구독 주소 동기화”와 “실행 설정 전체 동기화”를 구분해야 합니다. 후자는 다른 플랫폼에 맞지 않는 수신 설정, 라우팅 및 경로를 함께 가져올 수 있습니다.

여러 기기에서 사용할 때는 노드 출처와 서비스별 규칙을 공유하고 플랫폼별 설정은 각 클라이언트에 맡기는 편이 안정적입니다. 비공개 저장소, 구독 주소 및 오버라이드 파일을 함께 사용하는 방법은 PC와 휴대전화에서 설정을 함께 사용할 때 고려할 점을 참고하세요. 리소스가 병합되는 실제 순서는 다음 장의 방법으로 최종 실행 결과를 확인해야 합니다.

오버라이드, 병합 및 검증

오버라이드를 사용하면 계속 유지할 로컬 설정과 주기적으로 업데이트되는 구독 내용을 분리할 수 있습니다. 예를 들어 구독은 노드와 기본 정책을 제공하고, 로컬 오버라이드는 LAN 예외, 서비스별 규칙 또는 플랫폼의 트래픽 처리 매개변수를 담당합니다. 오버라이드는 YAML에서 통일해 정의한 범용 최상위 필드가 아니라 클라이언트가 설정을 생성할 때 수행하는 처리 과정입니다. 이름이 같은 “병합”, “오버라이드”, “스크립트” 기능도 클라이언트마다 실행 단계와 리스트 처리 방식이 다를 수 있습니다.

먼저 병합 규칙 확인

맵 병합과 리스트 병합은 구분해서 이해해야 합니다. 스칼라 필드는 대개 나중에 입력한 값으로 교체됩니다. 중첩 맵은 재귀적으로 병합되거나 전체가 교체될 수 있고, 리스트는 뒤에 추가되거나 앞에 삽입되거나 통째로 교체될 수 있습니다. 어떤 클라이언트가 기존 DNS 하위 필드를 보존한다고 해서 기존 규칙 목록도 보존한다고 단정할 수는 없습니다. 작업 전에 클라이언트의 안내와 미리보기를 확인하고 기능 이름이 아니라 최종 결과로 동작을 판단하세요.

# 기본 설정 조각
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://cloudflare-dns.com/dns-query

# 추가하려는 필드 조각
# 클라이언트가 지원하는 병합 방식을 사용하세요. dns 키를 그대로 중복해서 붙여 넣지 마세요.
# dns:
#   fake-ip-filter:
#     - '*.lan'

클라이언트가 dns를 통째로 교체한다면 fake-ip-filter만 제출했을 때 기존 업스트림 설정이 사라질 수 있습니다. 재귀 병합을 하더라도 리스트가 유지되는지는 구현 방식에 따라 다릅니다. 안전하게 확인하려면 영향이 적은 필드 하나로 먼저 시험하고 실행 설정의 DNS 전체 영역을 살펴보세요. 원하는 변경을 적용하는 동안 기본 설정과 오버라이드 파일의 사본을 각각 보관하세요.

규칙 앞에 삽입 및 이름 변경

특히 구독에 기본 규칙이 이미 있다면 로컬 규칙은 보통 원격 규칙보다 앞에 삽입해야 합니다. 클라이언트가 로컬 목록을 뒤에 추가하기만 한다면 새 규칙은 MATCH 뒤에 놓여 문법은 맞아도 일치하지 않습니다. 클라이언트가 지원하는 앞쪽 삽입 기능을 사용하거나 스크립트에서 삽입 위치를 지정해야 합니다. 변경 후에는 오버라이드 편집기의 내용만 보지 말고 최종 규칙 목록의 앞과 끝을 직접 확인하세요.

rules:
  - DOMAIN,internal.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,출구 선택
  - MATCH,출구 선택

위 내용은 원하는 최종 순서를 나타낼 뿐, 모든 클라이언트에 공통으로 적용되는 오버라이드 지시문은 아닙니다. 로컬 규칙이 “출구 선택”을 참조하는데 구독 업데이트 후 그룹 이름이 바뀌거나 삭제되면 참조가 유효하지 않게 됩니다. 로컬에서 안정적인 그룹 이름을 유지하고 구독이 제공하는 노드 목록에 연결하거나, 업데이트 후 참조 관계를 확인하세요. 화면에 해당 이름이 표시된 적이 있다는 이유로 현재 실행 설정에도 남아 있다고 가정하면 안 됩니다.

최소 변경 및 단계별 검증

한 번에 한 영역만 수정하는 것이 좋습니다. 먼저 파일 파싱 여부를 확인하고, 이름 참조를 점검한 다음 수신 및 트래픽 처리를 확인하고, 마지막으로 서비스별 분기를 검증하세요. DNS, TUN, 노드 프로토콜, 규칙 순서를 동시에 바꾸면 문제가 잠시 사라져도 무엇이 해결에 영향을 줬는지 알기 어렵습니다. 변경할 때마다 목적, 수정 필드 및 테스트 대상을 기록해 두면 이후 구독 업데이트 때 같은 문제를 다시 조사하는 수고를 줄일 수 있습니다.

1. 현재 정상 작동하는 설정을 저장하고 활성 프로필과 주요 옵션을 기록합니다.
2. YAML 들여쓰기, 중복 키, 데이터 유형 및 이름 참조를 확인합니다.
3. 생성된 실행 설정을 열어 로컬 필드가 덮어써지지 않았는지 확인합니다.
4. 새 테스트 연결을 만들어 규칙, 정책 그룹 및 최종 노드를 확인합니다.
5. 구독을 업데이트하고 다시 로드한 뒤 로컬 설정이 의도대로 유지되는지 확인합니다.

직결 경로와 프록시 경로를 각각 하나 이상 검증해야 합니다. 웹페이지 하나가 열리는지만 확인하면 모든 트래픽이 잘못 직결되거나 프록시되는 상황을 놓칠 수 있습니다. DNS를 조정했다면 도메인 조회와 연결 결과가 일치하는지도 확인하세요. TUN을 조정했다면 LAN, 다른 VPN 및 절전 모드에서 깨어난 뒤의 동작을 점검해야 합니다. 설정 테스트 명령은 문법과 일부 의미 오류를 확인할 뿐이며 실제 네트워크 검증은 별도로 수행해야 합니다.

플랫폼 간 설정을 옮길 때는 로컬 파일 경로, 네트워크 인터페이스 이름, 컨트롤 포트 및 플랫폼 전용 트래픽 처리 매개변수를 분리해야 합니다. 공유할 핵심은 노드 출처와 트래픽 분기 의도이지 한 기기의 실행 세부 설정 전체가 아닙니다. Clash Plus 같은 GUI 클라이언트에서는 다운로드 센터에서 해당 플랫폼 옵션을 선택해 기본 환경을 만든 뒤 필요한 설정을 옮기세요. 설치 문제와 필드 호환성 문제를 동시에 겪는 일을 피할 수 있습니다.

최종적으로 관리할 설정은 각 관계를 설명할 수 있어야 합니다. 원격 리소스마다 출처가 명확하고, 그룹 이름마다 안정적인 용도가 있으며, 예외 규칙마다 테스트 대상이 있고, 병합할 때마다 결과를 확인할 수 있어야 합니다. 처음 설정한다면 빠른 시작으로 돌아가 기본 연결 절차를 마치세요. 설정은 로드되지만 문제가 계속되면 도움말 센터나 연결 실패 문제 해결 문서를 확인하고 진입점, 조회, 규칙, 아웃바운드 순으로 점검하세요.