Clash 설정 파일 필드 참고

YAML 구조 개요와 로딩 순서

최상위 매핑이 코어의 읽기 범위를 결정합니다

Clash 설정 파일은 본질적으로 하나의 YAML 문서입니다. 최외곽에는 일반적으로 여러 키와 값이 배치됩니다. 포트와 실행 옵션은 스칼라, dns는 중첩 매핑, proxies·proxy-groups·rules는 목록을 사용합니다. 코어는 시작할 때 먼저 YAML 문법을 파싱한 뒤 필드 유형과 참조 관계를 검증하고, 마지막으로 수신 포트, DNS 모듈, 프록시 아웃바운드, 정책 그룹과 규칙 트리를 구성합니다. 문법 파싱에 성공했다고 해서 반드시 실행 가능한 설정이라는 뜻은 아닙니다. 예를 들어 정책 그룹이 존재하지 않는 노드를 참조하면 설정 검증 단계에서 오류가 발생할 수 있습니다.

YAML은 중괄호로 객체를 감싸지 않고 들여쓰기로 계층을 표현합니다. 두 칸 들여쓰기를 일관되게 사용하고 같은 파일에 탭 문자를 섞지 않는 것이 좋습니다. 콜론 뒤에는 공백이 필요하며 목록 항목은 하이픈과 공백으로 시작합니다. 콜론, 샵, 별표, 대괄호가 포함되거나 앞뒤에 공백이 있는 이름은 파서가 문법 기호로 해석하지 않도록 따옴표로 감싸야 합니다. 노드명에 한글을 사용할 수는 있지만 정책명과 규칙 대상에서 반복해 참조하므로 짧을수록 확인하기 쉽습니다.

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

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip

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

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

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

위 예시는 최소한의 흐름을 구성합니다. 인바운드 트래픽이 mixed-port로 들어오고, 도메인 조회는 DNS 모듈이 처리하며, 규칙은 요청을 “노드 선택”으로 보냅니다. 정책 그룹은 다시 특정 노드나 DIRECT를 선택합니다. proxy-groups를 삭제하면 규칙 대상에 노드명이나 내장 동작을 직접 적어야 하고, rules를 삭제하면 rule 모드에서 완전한 트래픽 분기 동작을 구현하기 어렵습니다. 실제 구독에는 더 많은 노드가 포함되지만 구조적 관계는 같습니다.

스칼라, 목록, 매핑의 유형은 서로 바꿀 수 없습니다

mode: rule은 스칼라이므로 목록으로 작성할 수 없습니다. rules는 순서가 있는 목록이므로 규칙 유형을 키로 하는 매핑으로 바꿀 수 없습니다. dns는 매핑이며 각 하위 필드마다 고유한 유형이 있습니다. 불리언 값은 소문자 true 또는 false로 작성하고 “예”, “아니요”나 따옴표로 감싼 문자열로 대신하지 않는 것이 좋습니다. 포트는 정수로 작성해야 합니다. "7890"처럼 쓰면 호환 모드에서 처리되기도 하지만 클라이언트별 차이가 커질 수 있습니다.

앵커와 별칭은 YAML 자체 기능입니다. 예를 들어 &common으로 공통 매개변수를 정의한 다음 <<: *common으로 병합할 수 있습니다. 중복을 줄이는 데 유용하지만 여러 클라이언트에서 동기화해야 하는 구독 설정에는 적합하지 않습니다. 일부 오버라이더가 직렬화 과정에서 앵커를 펼치거나 잃어버릴 수 있기 때문입니다. 장기 유지보수가 필요한 파일에서는 핵심 필드를 명시적으로 작성하고, 가져오기 경로가 YAML 의미를 온전히 보존하는지 확인한 경우에만 앵커를 사용하세요.

로딩 경로, 구독 파일과 런타임 설정

그래픽 클라이언트는 보통 원격 구독을 로컬 설정 디렉터리에 내려받은 뒤 선택한 설정을 mihomo 코어에 전달합니다. 화면에 표시되는 설정명, 구독 주소와 업데이트 시간은 클라이언트 관리 계층의 정보이므로 YAML에 반드시 포함되지는 않습니다. 코어는 최종 생성된 설정 파일만 처리합니다. 일부 클라이언트는 로딩 전에 스크립트, 전역 오버라이드나 로컬 패치를 적용하므로 화면에서 내보낸 파일이 구독 서버가 반환한 원문과 다를 수 있습니다.

파싱에 실패했을 때는 먼저 다운로드 단계와 파싱 단계를 구분해야 합니다. 브라우저에서 구독 주소가 열린다는 사실은 서버가 응답했다는 뜻일 뿐, 응답 내용이 YAML이라는 뜻은 아닙니다. 로그인 페이지, 속도 제한 안내 또는 JSON 오류 객체가 반환되면 클라이언트는 이를 그대로 저장한 뒤 첫 줄에서 문법 오류를 보고할 수 있습니다. 구독 파싱 실패 자가 점검 절차에 따라 응답 상태, 콘텐츠 유형, 들여쓰기와 캐시를 확인하세요. 직접 편집할 때는 원본을 보관하고 변경을 작은 단위로 나누어 한 번에 하나의 구조 영역만 조정한 뒤 다시 검증하세요.

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

인바운드 포트와 LAN 접근

port는 HTTP 프록시만 제공하고 socks-port는 SOCKS5 프록시만 제공합니다. mixed-port는 하나의 포트에서 두 연결 유형을 모두 지원합니다. 데스크톱 클라이언트에서는 보통 mixed-port를 사용하므로 시스템 프록시, 브라우저와 SOCKS를 지원하는 도구가 같은 수신 포트를 공유할 수 있습니다. 세 포트를 모두 켤 필요는 없습니다. 동시에 설정한다면 서로 다른 포트를 사용해야 하며, 그렇지 않으면 코어가 수신 주소를 바인딩할 수 없습니다. 포트 번호 자체에는 네트워크 가속 기능이 없습니다. 사용 중이지 않고 시스템 프록시 설정과 일치하면 됩니다.

allow-lan은 LAN 기기의 연결 허용 여부를 제어합니다. false이면 일반적으로 로컬 기기에서만 접근할 수 있고, true이면 bind-address, 운영체제 방화벽과 라우터의 격리 설정도 확인해야 합니다. LAN 수신을 개방하면 접근 범위가 넓어지므로 인증을 설정하거나 방화벽에서 출발지를 제한하고, 프록시 포트를 인터넷에 직접 노출하지 마세요. 모바일 기기에서 컴퓨터 프록시를 사용할 때 입력하는 값은 컴퓨터의 LAN 주소와 Clash 인바운드 포트이며, 원격 노드 서버 주소가 아닙니다.

mixed-port: 7890
allow-lan: false
bind-address: "*"
authentication:
  - "local-user:your-password"

mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

LAN 공유가 실제로 필요할 때만 allow-lan을 활성화하세요. 일부 클라이언트는 화면의 스위치로 YAML 값을 덮어쓸 수 있으므로 수정 후 실행 상태 페이지에서 실제 수신 주소를 확인해야 합니다. 시스템 프록시는 켜졌지만 브라우저가 연결되지 않는다면 먼저 클라이언트 로그에 “address already in use”가 나타나는지 확인한 다음 시스템 프록시 포트가 이전 설정을 가리키고 있지 않은지 점검하세요. Windows 앱 컨테이너는 UWP 루프백 제한의 영향을 받을 수도 있습니다. 이는 규칙 필드가 아니라 시스템 네트워크 권한 문제입니다.

mode는 규칙이 의사 결정에 참여할지 결정합니다

mode에서 자주 사용하는 값은 rule, global, direct입니다. rule 모드에서는 요청이 rules와 순서대로 매칭되고, global 모드에서는 트래픽이 일반적으로 전역 정책 그룹으로 전달되며, direct 모드에서는 일반 규칙 분기를 사용하지 않고 직접 연결합니다. 설정을 디버깅할 때는 장기 사용 상태에 가장 가까운 rule을 우선 유지하세요. 일시적으로 글로벌 모드로 전환하면 문제가 규칙에서 비롯되었는지 판단할 수 있지만, DNS, 노드와 시스템 프록시가 모두 정상이라는 뜻은 아닙니다.

그래픽 클라이언트의 모드 스위치는 런타임 상태인 경우가 많습니다. 구독을 새로 고친 뒤 클라이언트가 마지막 선택을 유지할 수도 있고 YAML의 mode를 다시 적용할 수도 있습니다. 동작을 안정적으로 유지하려면 설정 파일과 클라이언트의 전역 오버라이드 설정을 함께 확인하세요. 규칙 모드에서 “특정 웹사이트가 잘못된 정책으로 연결되는” 경우에는 규칙 적중 기록을 확인해야 합니다. 글로벌 모드에서는 모든 요청이 하나의 정책으로 들어가므로 도메인 규칙을 수정해도 효과가 없습니다. 이는 문제 해결에서 가장 흔히 놓치는 맥락입니다.

로그, IPv6와 동시 연결

log-level은 로그의 상세 수준을 제어하며 silent, error, warning, info, debug 등이 자주 사용됩니다. 일상적인 사용에는 info면 충분합니다. 파싱, 핸드셰이크 또는 규칙 적중 문제를 찾을 때만 일시적으로 debug로 전환하고 끝나면 되돌리세요. 로그가 너무 많으면 핵심 정보가 묻힐 수 있습니다. 로그의 도메인, 노드명과 대상 주소에는 접속 정보가 포함될 수 있으므로 장애 분석 화면을 공유하기 전에 민감한 내용을 삭제하세요.

ipv6은 코어가 IPv6 관련 조회와 연결을 처리할지 결정합니다. 이를 끈다고 운영체제의 IPv6가 완전히 비활성화되는 것은 아니며 Clash의 해당 모듈이 제한된 방식으로 동작한다는 뜻입니다. 네트워크, 프록시 노드와 상위 DNS가 안정적으로 IPv6를 지원한다면 켤 수 있습니다. 일부 사이트에서 AAAA 레코드를 먼저 얻지만 연결되지 않는다면 규칙을 반복해서 전환하기보다 DNS 조회 결과와 노드의 지원 여부를 먼저 대조하세요. tcp-concurrent는 대상 주소에 대한 동시 연결 시도를 허용합니다. 여러 주소가 조회되는 환경에서는 대기 시간을 줄일 수 있지만 짧은 시간에 생성되는 연결 수가 늘어납니다.

unified-delay는 지연 시간 테스트를 보다 통일된 기준으로 계산하도록 합니다. 정책 그룹 테스트 결과의 해석에 영향을 줄 뿐, 사용할 수 없는 노드를 사용 가능하게 만들지는 않습니다. 지연 시간 테스트는 테스트 주소까지의 연결 상태만 나타내며 실제 접속은 대상 사이트, 프로토콜 핸드셰이크, 출구 품질과 규칙 경로의 영향도 받습니다. 따라서 한 번의 수치만으로 노드를 정렬해서는 안 됩니다. 노드 선택 방법은 지연 시간, 배율, 지역과 프로토콜 안내를 참고하세요.

외부 컨트롤러와 관리 인터페이스

external-controller는 코어의 제어 인터페이스를 노출하며 그래픽 클라이언트는 이를 통해 연결을 조회하고 정책을 전환하며 설정을 다시 불러옵니다. 일반적으로 로컬 주소와 포트로 수신합니다. 로컬이 아닌 주소에 바인딩한다면 secret을 설정하고 방화벽으로 출발지를 제한하세요. external-ui는 정적 관리 인터페이스 디렉터리를 가리키며 프런트엔드 리소스를 자동으로 내려받지는 않습니다. 일반적인 그래픽 클라이언트에 이미 관리 계층이 포함되어 있다면 별도로 설정할 필요가 없습니다.

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

profile:
  store-selected: true
  store-fake-ip: true

profile.store-selected는 정책 그룹 선택을 저장해 재시작 후 마지막 선택을 복원하고, profile.store-fake-ip는 Fake-IP 매핑을 저장해 재시작으로 인한 매핑 변화를 줄입니다. 실제 저장 위치는 클라이언트 작업 디렉터리에 따라 달라집니다. 설정 파일은 저장 의도만 선언하므로 클라이언트가 시작할 때마다 캐시 디렉터리를 지우면 영속 필드도 상태를 유지할 수 없습니다. 여러 기기에서 동기화할 때는 실행 디렉터리 전체를 복사하지 말고 구독, 오버라이드와 필요한 설정 파일만 동기화하세요. 잠금 파일, 캐시와 플랫폼별 경로가 함께 복사되는 것을 피해야 합니다.

DNS 필드, Fake-IP와 조회 경로

DNS 모듈은 연결 결정 전에 위치합니다

도메인 요청은 일반적으로 먼저 DNS 조회를 거친 다음 규칙과 아웃바운드가 연결을 구성합니다. Clash의 DNS 모듈은 단순히 “도메인을 주소로 변환”하는 역할만 하지 않습니다. 도메인 규칙을 유지할 수 있는지, Fake-IP 매핑을 어떻게 만들지, 상위 서버별로 어떻게 분기할지, 프록시 노드 서버 주소를 누가 조회할지에도 영향을 줍니다. “프록시는 연결됐지만 웹 페이지가 열리지 않는” 문제는 실제로 DNS 상위 서버에 접근할 수 없거나, 응답이 오염되었거나, Fake-IP 필터가 불완전하거나, 시스템 요청이 코어를 우회해서 발생하는 경우가 많습니다.

dns.enable은 내장 DNS를 활성화하고 listen은 수신 주소를 정의합니다. 데스크톱 클라이언트는 시스템 DNS 가로채기, TUN 또는 로컬 포트를 통해 조회를 이 모듈로 전달할 수 있습니다. YAML에서 DNS를 켜는 것만으로 운영체제가 반드시 이를 사용하는 것은 아닙니다. 클라이언트가 시스템 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
  use-hosts: true
  respect-rules: true
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.example/dns-query
    - tls://dns.example:853
  proxy-server-nameserver:
    - 223.5.5.5
  nameserver-policy:
    "geosite:cn":
      - 223.5.5.5

default-nameserver는 주로 암호화된 DNS 상위 서버 자체의 도메인을 조회하는 데 사용하므로 직접 접근할 수 있는 IP 주소를 적는 경우가 많습니다. 여기에 도메인을 적으면 “상위 서버를 사용하려면 먼저 상위 서버의 도메인을 조회해야 하는데, 그 조회도 해당 상위 서버에 의존하는” 순환이 생길 수 있습니다. nameserver는 주요 조회 상위 서버이며 UDP, TCP, DoT 또는 DoH 형식을 사용할 수 있습니다. 예시의 dns.example는 가상 도메인이므로 실제 설정에서는 사용 가능한 서비스로 바꿔야 합니다.

proxy-server-nameserver는 프록시 노드 서버의 도메인을 전담해 조회합니다. 노드의 server에 도메인을 적으면 코어가 프록시 연결을 만들기 전에 실제 주소를 얻어야 합니다. 이 단계까지 아직 구성되지 않은 프록시 체인으로 보내면 의존성 순환이 생길 수 있습니다. 이 필드에 직접 연결 가능한 조회 상위 서버를 지정하면 노드 도메인 조회와 일반 웹사이트 조회를 분리할 수 있습니다. 노드에 IP를 직접 적으면 이 단계는 거치지 않지만, 도메인 변경에 따라 백엔드 주소를 전환하는 기능은 사용할 수 없습니다.

Fake-IP 모드가 도메인 정보를 유지하는 방식

enhanced-mode: fake-ip에서는 코어가 먼저 애플리케이션에 예약 주소 범위의 매핑 주소를 반환합니다. 애플리케이션이 해당 주소에 연결하면 코어는 매핑 테이블에서 원래 도메인을 복원하고 규칙을 적용합니다. 따라서 애플리케이션이 IP 연결만 시작하더라도 코어가 도메인 규칙으로 판단할 수 있습니다. fake-ip-range는 기본적으로 별도로 예약된 테스트 주소 범위를 사용해야 하며 실제 LAN, 기업 VPN이나 컨테이너 네트워크와 겹치면 안 됩니다.

Fake-IP는 원격 서버 주소가 아니며 인터넷으로 전송되지도 않습니다. 로컬 코어가 관리하는 임시 매핑입니다. 시스템 연결 대상이 198.18.x.x로 표시된다고 해서 DNS 오류라는 뜻은 아닙니다. 실제로 확인해야 할 것은 해당 연결이 Clash에 의해 가로채졌는지 여부입니다. 애플리케이션이 시스템 프록시를 우회하고 TUN도 트래픽을 가로채지 않으면 예약 주소에 직접 연결을 시도해 타임아웃이 발생합니다. 이때는 모든 도메인을 필터 목록에 넣기보다 가로채기 경로를 확인해야 합니다.

fake-ip-filter는 특정 도메인이 실제 주소를 반환하도록 합니다. LAN 서비스, 네트워크 탐색, 시간 동기화, 일부 게임이나 로컬 검색이 필요한 서비스는 매핑 주소와 맞지 않을 수 있습니다. 필터 범위는 가능한 한 정밀하게 유지하세요. 지나치게 넓은 와일드카드는 많은 도메인에서 Fake-IP의 도메인 식별 기능을 잃게 합니다. 수정 후에는 기존 DNS 캐시를 지우거나 관련 애플리케이션을 다시 시작해야 하며, 그렇지 않으면 애플리케이션이 이전 결과를 계속 사용할 수 있습니다.

dns:
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "localhost.ptlogin2.qq.com"
    - "+.stun.*.*"
    - "time.*.com"
    - "time.*.gov"

redir-host와 Fake-IP의 선택

redir-host는 실제 조회 주소를 반환하므로 경로를 이해하기 쉽고 실제 IP에 의존하는 애플리케이션과의 호환성이 좋습니다. 다만 투명 프록시 환경에서는 코어가 대상 IP만 볼 수 있어 스니핑이나 조회 매핑으로 도메인을 복원해야 할 수 있으며, 도메인 규칙의 안정성은 가로채기 경로에 좌우됩니다. fake-ip는 도메인 정보를 온전히 유지하려는 TUN 환경에 더 적합하지만 예약 주소를 허용하지 않는 일부 프로그램을 별도로 처리해야 합니다. 모드는 노드 속도 스위치가 아니라 시스템 가로채기 방식과 애플리케이션 호환성을 기준으로 선택해야 합니다.

respect-rules는 기존 규칙을 참고해 DNS 조회를 수행하지만, 조회 상위 서버와 프록시 정책 사이에 순환 의존성이 없어야 합니다. 주요 DoH 상위 서버가 프록시를 거쳐야 하고 프록시 노드 서버의 도메인도 해당 DoH에 의존한다면 초기 연결을 완료하지 못할 수 있습니다. 노드 도메인을 위한 독립적인 직접 연결 조회기를 준비하거나 최소 하나의 기본 상위 서버를 프록시 없이 접근 가능하게 하세요. 로그에 DNS timeout이 계속 나타나면 의존성 체인의 가장 아래 단계부터 확인해야 합니다.

nameserver-policy의 분기 범위

nameserver-policy는 도메인 또는 geosite 집합에 따라 조회 상위 서버를 선택합니다. 즉 “DNS를 어디에 물어볼지”를 결정할 뿐, 이후 연결에서 DIRECT를 사용할지 프록시를 사용할지를 직접 결정하지는 않습니다. 연결 정책은 여전히 rules가 제어합니다. 같은 도메인이 상위 서버마다 다른 주소를 반환하면 조회 정책이 연결 대상에 간접적으로 영향을 줍니다. 따라서 DNS 분기와 규칙 분기는 일관된 지역 의도로 구성해야 합니다. 예를 들어 중국 본토 도메인이 원격 상위 서버에서 다른 지역 주소로 조회되거나 프록시 도메인이 로컬 상위 서버에서 비정상 응답을 받지 않도록 해야 합니다.

DNS 문제를 해결할 때는 세 단계로 확인하는 것이 좋습니다. 먼저 시스템 조회가 Clash로 들어오는지 확인하고, 다음으로 Clash가 지정한 상위 서버에 접근할 수 있는지 확인하며, 마지막으로 반환 주소와 규칙 적중 결과가 예상과 일치하는지 확인합니다. 브라우저 페이지만 테스트하면 캐시, HTTP/3와 시스템 프록시의 영향을 구분하기 어렵습니다. 브라우저의 보안 DNS를 잠시 끄고 애플리케이션 캐시를 삭제한 뒤 코어 로그에서 도메인 조회와 연결 기록을 관찰할 수 있습니다. 더 자세한 네트워크 점검 순서는 시스템 프록시, DNS와 규칙 모드 문제 해결 체크리스트를 참고하세요.

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

모든 노드에는 참조 가능한 고유 이름이 필요합니다

proxies의 각 항목은 하나의 정적 아웃바운드 노드를 나타냅니다. 공통 필드는 name, type, server, port이며 나머지는 프로토콜에 따라 달라집니다. name은 정책 그룹과 규칙이 참조하는 식별자이므로 같은 설정 안에서 고유해야 합니다. 이름이 중복되면 클라이언트가 앞 항목을 덮어쓰거나 화면에 같은 이름의 두 옵션을 표시할 수 있어 규칙이 실제로 어느 항목을 참조하는지 알기 어렵습니다. 구독 생성기는 노드명에 지역이나 용도를 남기되 지나치게 긴 공지 문구를 넣지 않는 것이 좋습니다.

server에는 IP 또는 도메인을 사용할 수 있지만 프로토콜 접두사나 경로를 붙일 수 없습니다. port는 원격 서비스 포트이며 로컬 mixed-port가 아닙니다. 연결에 실패했을 때는 로컬 인바운드와 원격 아웃바운드를 구분해야 합니다. 시스템 프록시는 로컬 포트에 연결하고 코어는 노드 필드에 따라 서버에 연결합니다. 두 종류의 포트를 혼동하는 것은 수동 설정에서 흔한 오류입니다.

proxies:
  - name: "SS-예시"
    type: ss
    server: 192.0.2.20
    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: gateway.example.com
    skip-cert-verify: false
    udp: true

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

예시의 주소와 인증 정보는 필드 관계를 보여주기 위한 것입니다. Shadowsocks의 cipher는 서버와 일치해야 합니다. Trojan은 보통 TLS로 연결하며 sni는 서버 이름을 전송하는 데 사용됩니다. VMess의 uuid, 전송 방식, TLS와 WebSocket 매개변수는 하나의 조합으로 맞아야 합니다. 한 필드만 따로 수정한다고 핸드셰이크 실패가 해결되는 것은 아니며 오히려 클라이언트와 서버 설정이 어긋날 수 있습니다.

TLS, SNI와 인증서 검증

TLS를 사용하는 프로토콜에서는 연결 주소, SNI와 HTTP Host를 구분해야 합니다. server는 연결할 위치를 결정하고 sni 또는 servername은 TLS 핸드셰이크에서 선언할 호스트명을 결정하며 WebSocket의 Host는 HTTP 요청 헤더에 속합니다. 세 값이 같을 수도 있고 서버 배포 요구에 따라 다를 수도 있습니다. 인증서 이름이 일치하지 않으면 곧바로 skip-cert-verify를 켜지 말고 서버 인증서가 포함하는 도메인과 SNI를 확인하세요.

skip-cert-verify: true는 인증서 유효성 검사를 건너뜁니다. 서버 인증서 상태를 명확히 알고 있는 임시 테스트에만 적합합니다. 장기 설정에서는 false를 유지하고 시스템 시간, 인증서 체인, SNI 또는 서버 배포를 수정해야 합니다. 시스템 시간이 잘못되면 인증서가 아직 유효하지 않거나 이미 만료되었다는 판단이 모두 틀어질 수 있습니다. 이런 오류는 보통 로그에 TLS 검증 실패로 나타나며 규칙이나 정책 그룹과는 관계가 없습니다.

전송 계층 옵션은 계층에 맞게 중첩해야 합니다

WebSocket 매개변수는 ws-opts에, gRPC 매개변수는 grpc-opts에, HTTP 매개변수는 해당 전송 옵션 안에 배치합니다. 이들을 server와 같은 수준에 두거나 임의로 이름을 바꿀 수 없습니다. YAML 들여쓰기가 잘못되면 headers가 ws-opts 밖으로 나갈 수 있습니다. 설정은 읽을 수 있는 텍스트처럼 보여도 코어가 알 수 없는 위치의 필드를 무시하거나 로딩을 거부할 수 있습니다. 문제를 해결할 때는 필드 값만 비교하지 말고 프로토콜 문서를 기준으로 각 계층을 확인하세요.

  - name: "VLESS-gRPC-예시"
    type: vless
    server: 192.0.2.40
    port: 443
    uuid: "00000000-0000-4000-8000-000000000001"
    network: grpc
    tls: true
    servername: grpc.example.com
    udp: true
    grpc-opts:
      grpc-service-name: example-service

udp는 노드가 UDP를 전달할 수 있는지 나타냅니다. 이 필드를 켜려면 프로토콜, 서버와 네트워크 경로 모두 UDP를 지원해야 합니다. 게임이나 음성 애플리케이션이 작동하지 않을 때 udp: true가 적혀 있는지만 확인해서는 안 됩니다. TUN 가로채기, 정책 그룹 선택, 서버 전달과 애플리케이션 자체 프로토콜도 확인해야 합니다. UDP에 문제가 있어도 TCP 웹 접속은 정상일 수 있습니다.

프로토콜 필드 차이와 선택 원칙

노드 필드는 실제 서버나 구독에서 가져와야 하며 추측으로 채워서는 안 됩니다. 클라이언트 간 호환성 차이는 새로운 프로토콜 기능, 전송 매개변수 이름이나 코어 기능에서 주로 발생합니다. “지원하지 않는 프록시 유형” 또는 “알 수 없는 필드”가 나타나면 먼저 현재 클라이언트가 사용하는 코어 유형을 확인한 뒤 구독이 해당 클라이언트에 맞는 형식으로 생성되었는지 점검하세요. 클라이언트를 바꿔야 한다면 다운로드 페이지에서 Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu, Clash Meta for Android, ClashX Meta, Surfboard 등 플랫폼별 진입점을 제공합니다.

정적 노드는 소량의 수동 설정에 적합합니다. 노드가 많거나 원격 업데이트가 필요하다면 proxy-providers를 사용하세요. 두 방식을 함께 사용할 수 있으며 정책 그룹이 정적 노드와 제공자 노드를 동시에 참조하는 것도 가능합니다. 어떤 출처를 사용하든 정책 그룹에 들어가는 최종 이름은 코어가 해석할 수 있어야 하고, 원격 파일 다운로드가 성공하더라도 유효한 노드 구조를 갖춰야 합니다.

정책 그룹 유형, 중첩과 상태 점검

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

proxy-groups는 여러 노드, 다른 정책 그룹과 내장 동작을 참조 가능한 대상으로 묶습니다. 규칙은 보통 특정 노드를 직접 가리키지 않고 “노드 선택”, “자동 선택”, “스트리밍” 같은 정책 그룹을 가리킵니다. 따라서 노드가 바뀌어도 많은 규칙을 수정하지 않고 그룹 내부 구성원만 조정하면 됩니다. 정책 그룹 이름도 대소문자를 구분하며 참조 이름 앞뒤에 불필요한 공백이 없어야 합니다.

select는 수동 선택 그룹으로 클라이언트 화면에서 구성원을 지정합니다. url-test는 일정한 간격으로 구성원을 테스트해 성능이 좋은 노드를 선택합니다. fallback은 순서대로 사용 가능한 구성원을 찾고, load-balance는 지정한 정책에 따라 여러 구성원에게 연결을 분배합니다. 유형마다 해결하는 문제가 다릅니다. 고정된 출구가 필요하면 수동 그룹을 사용하고 자동 그룹의 잦은 전환에 의존하지 마세요. 장애 발생 시 우선순위에 따라 대체 노드로 돌아가고 싶다면 최저 지연 시간만 고르는 방식보다 fallback이 의도에 더 적합합니다.

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

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

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

url은 상태 점검 대상이므로 안정적이고 응답 내용이 작으며 모든 후보 노드에서 접근할 수 있는 주소를 선택해야 합니다. 테스트 성공은 노드가 해당 주소에 접근할 수 있다는 뜻일 뿐 모든 웹사이트가 정상이라는 의미는 아닙니다. interval은 테스트 간격입니다. 너무 짧으면 불필요한 연결이 늘고 너무 길면 노드 장애가 발생해도 갱신이 늦습니다. lazy를 켜면 그룹이 실제로 사용되지 않을 때 능동적인 테스트를 줄일 수 있습니다. tolerance는 결과가 비슷할 때 잦은 전환을 막는 값이며 고정된 속도 차이를 뜻하지 않습니다.

그룹 중첩은 단방향 참조를 유지해야 합니다

정책 그룹은 다른 정책 그룹을 참조할 수 있습니다. 예를 들어 “노드 선택”이 “자동 선택”을 포함하고 “스트리밍”이 다시 “노드 선택”을 포함할 수 있습니다. 이런 중첩은 기본 정책과 용도별 정책을 구성하는 데 적합하지만 순환을 만들면 안 됩니다. A가 B를 포함하고 B가 다시 A를 포함하면 코어가 최종 아웃바운드를 결정할 수 없습니다. 그룹 관계는 업무 그룹에서 기본 그룹, 노드로 이어지는 단방향 트리로 설계하고 모든 경로가 구체적인 노드, DIRECT 또는 REJECT에 도달하도록 하세요.

중첩 단계가 지나치게 많으면 문제 해결 비용도 커집니다. 요청이 “스트리밍”에 적중한 뒤 “지역 선택”, “자동 선택”을 거쳐 마지막에 노드로 갈 수 있습니다. 화면에는 최외곽 선택만 보이므로 실제 출구를 오해하기 쉽습니다. 기본 설정은 규칙 대상 그룹, 선택 또는 테스트 그룹, 구체적인 노드의 세 단계 이내로 유지하는 것이 좋습니다. 서비스별로 지역을 고정해야 한다면 노드 목록을 복사하지 말고 업무 그룹에서 지역 그룹을 직접 참조하세요.

filter와 use로 제공자 노드 관리

정책 그룹은 use로 proxy-providers를 참조하고 filter로 노드명에 따라 구성원을 필터링합니다. 필터 표현식은 보통 정규식으로 처리되므로 문자를 올바르게 이스케이프해야 합니다. 노드명은 구독 제공자가 정하므로 업데이트에 따라 바뀔 수 있습니다. 따라서 필터어는 안정적인 지역 표기를 포함하되 지나치게 넓게 매칭하지 않아야 합니다. 예를 들어 “미”만 쓰면 공지 문구까지 매칭될 수 있으므로 자주 쓰이는 지역 코드와 이름을 명확히 적는 편이 안전합니다.

proxy-groups:
  - name: "미국 노드"
    type: url-test
    use:
      - remote-nodes
    filter: "(?i)미국|US|United States"
    exclude-filter: "테스트|만료|기한 만료"
    url: https://www.gstatic.com/generate_204
    interval: 600

  - name: "업무별 분기"
    type: select
    proxies:
      - "미국 노드"
      - "노드 선택"
      - DIRECT

필터 결과가 비어 있으면 정책 그룹을 사용할 수 없게 될 수 있습니다. 구독을 새로 고친 뒤 갑자기 그룹에 노드가 없어졌다면 먼저 제공자 업데이트가 성공했는지 확인하고, 다음으로 노드명이 바뀌었는지 점검한 뒤 정규식이 YAML 따옴표와 백슬래시의 영향을 받지 않았는지 확인하세요. 큰따옴표 문자열은 이스케이프 문자를 처리하므로 복잡한 정규식에는 작은따옴표를 사용해 백슬래시 계층을 줄이는 방법도 있습니다.

DIRECT, REJECT와 PASS의 의미

DIRECT는 프록시 노드를 거치지 않고 대상에 직접 연결하고, REJECT는 연결을 거부하며, PASS는 특정 규칙 조합이나 하위 규칙 집합에서 매칭을 다음 처리 단계로 넘길 때 주로 사용합니다. 이들은 내장 동작이므로 proxies에 선언할 필요가 없습니다. 수동 정책 그룹에 DIRECT를 넣으면 사용자가 일시적으로 직접 연결로 전환할 수 있다는 뜻입니다. 광고나 악성 도메인 규칙에 REJECT를 사용할 때는 오탐으로 페이지 리소스가 차단될 영향을 고려하세요.

정책 그룹에 DIRECT를 넣을지는 업무 범위에 따라 결정합니다. 기본 프록시 그룹에 넣으면 진단하기 쉽지만 잘못 선택했을 때 민감한 트래픽이 직접 연결될 수 있습니다. 특정 용도에서 프록시가 반드시 필요하다면 직접 연결 구성원을 제공하지 않아도 됩니다. 그룹명은 동작을 드러내야 합니다. 예를 들어 “노드 선택”은 수동 조정을 허용하고, “자동 선택”은 테스트 결과로 결정하며, “중국 본토 직접 연결”은 노드 지역이 아니라 규칙 대상을 의미하도록 구성합니다.

자동 정책 그룹은 “노드가 많을수록 좋다”는 뜻이 아닙니다. 후보가 너무 많으면 테스트 트래픽이 늘고 품질 차이가 클 때 결과가 흔들릴 수 있습니다. 먼저 지역, 용도와 프로토콜로 필터링한 뒤 제한된 후보를 테스트하면 안정적인 동작을 얻기 쉽습니다. 여러 기기에서 같은 정책 구조를 유지해야 한다면 여러 기기 설정 동기화 방법을 참고해 구독, 오버라이드와 기기별 설정을 계층적으로 보관하세요.

규칙 문법, 우선순위와 대체 순서

규칙은 선언 순서대로 처음 적중합니다

rules는 순서가 있는 목록입니다. 코어는 위에서 아래로 확인하며 일반적으로 한 규칙이 적중하면 뒤의 일반 규칙을 계속 비교하지 않습니다. 따라서 구체적인 규칙은 앞에, 포괄적인 규칙은 뒤에 배치하고 마지막에는 MATCH로 대체 처리하세요. 도메인 규칙이 IP 규칙보다 본질적으로 우선하는 전역 메커니즘은 없습니다. 실제 우선순위는 파일 순서로 결정됩니다. MATCH를 중간에 넣으면 그 뒤의 모든 규칙이 기회를 잃습니다.

일반적인 형식은 “규칙 유형, 매칭 내용, 정책 대상”이며 일부 규칙에는 추가 매개변수가 있습니다. 쉼표는 필드 구분자이므로 매칭 내용에 복잡한 값을 표현해야 한다면 해당 규칙 유형이나 규칙 제공자를 사용하고 임의로 쉼표를 추가하지 마세요. 정책 대상은 이미 존재하는 정책 그룹, 노드 또는 내장 동작이어야 합니다. 규칙 자체가 정책 그룹을 만들지는 않습니다.

rules:
  - DOMAIN,api.example.com,노드 선택
  - DOMAIN-SUFFIX,example.com,노드 선택
  - DOMAIN-KEYWORD,example,노드 선택
  - GEOSITE,cn,DIRECT
  - 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는 도메인에 키워드가 포함되기만 해도 매칭될 수 있어 범위가 가장 넓고 오탐이 쉽습니다. 완전한 도메인을 사용할 수 있다면 키워드를 쓰지 말고, 접미사를 사용할 때도 루트 도메인까지 포함해야 하는지 확인하세요. 예를 들어 DOMAIN-SUFFIX,example.com은 example.com과 www.example.com을 모두 포함하므로 사이트 전체에 같은 정책을 적용할 때 적합합니다.

IP 규칙과 no-resolve

IP-CIDR은 IPv4 주소 대역에, IP-CIDR6은 IPv6 주소 대역에 사용합니다. 요청에 대상 IP가 이미 있으면 바로 매칭할 수 있지만 요청이 여전히 도메인으로 표시되면 코어가 해당 주소 대역에 속하는지 판단하기 위해 먼저 조회해야 할 수 있습니다. no-resolve를 추가하면 이 규칙을 위해 조회를 적극적으로 실행하지 않습니다. 사설 주소나 이미 IP로 확정된 연결에 사용해 불필요한 조회를 줄일 수 있습니다.

GEOIP는 주소 데이터베이스로 지역을 판단하며 결과는 로컬 데이터베이스의 내용과 업데이트 상태에 따라 달라집니다. 넓은 범위의 대체 규칙에는 적합하지만 특정 서비스 하나를 정밀하게 처리하기에는 적합하지 않습니다. 클라우드 서비스와 CDN 주소는 바뀔 수 있고 같은 도메인도 네트워크에 따라 다른 지역 주소를 반환할 수 있습니다. 서비스 수준 규칙에는 도메인이나 명확히 관리되는 규칙 집합을 우선 사용하세요. IPv6를 켰다면 해당 주소 체계도 규칙이 함께 다루는지 확인해야 합니다.

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

데스크톱 플랫폼은 PROCESS-NAME, PROCESS-PATH 같은 프로세스 규칙을 지원할 수 있지만 사용 가능 여부는 시스템 권한, 코어 실행 방식과 플랫폼 기능에 따라 달라집니다. 프로세스명 규칙은 특정 애플리케이션을 정책 그룹에 고정하는 데 적합하고, 경로 규칙은 더 정확하지만 설치 디렉터리가 바뀌면 쉽게 무효화됩니다. 모바일 플랫폼은 보통 데스크톱 방식으로 프로세스 경로를 읽을 수 없으므로 여러 플랫폼에서 사용할 설정을 프로세스 규칙에 전적으로 의존해서는 안 됩니다.

DST-PORT, SRC-PORT 같은 포트 규칙은 특정 프로토콜이나 로컬 서비스를 처리할 수 있지만 포트가 곧 애플리케이션의 식별자는 아닙니다. 현대적인 서비스 대부분이 443 포트를 공유하므로 DST-PORT,443로 포괄적인 프록시 규칙을 만들면 거의 모든 HTTPS 트래픽을 덮게 됩니다. 포트 규칙은 알려진 서비스 포트, LAN 관리 포트나 디버깅에 더 적합하며 더 구체적인 규칙을 가리지 않는 위치에 배치해야 합니다.

rules:
  - PROCESS-NAME,example-client.exe,업무별 분기
  - DST-PORT,22,DIRECT
  - NETWORK,udp,노드 선택
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - MATCH,노드 선택

NETWORK,udp는 광범위한 UDP 트래픽을 매칭합니다. 적합성은 노드의 UDP 지원 여부, DNS를 독립 모듈이 처리하는지와 애플리케이션 용도에 따라 달라집니다. 모든 UDP를 UDP를 지원하지 않는 정책으로 보내면 음성, 게임이나 QUIC 연결이 실패할 수 있습니다. 특정 애플리케이션만 프록시로 보내려면 모든 UDP를 덮는 하나의 규칙보다 도메인, 프로세스와 포트를 조합하는 편이 좋습니다.

규칙은 문법보다 의도를 먼저 설계해야 합니다

규칙을 관리하기 전에 요구사항을 몇 가지 계층으로 정리해 보세요. 사설 네트워크 직접 연결, 명시적으로 거부할 도메인, 특정 지역을 반드시 사용해야 하는 업무, 자주 사용하는 중국 본토 도메인의 직접 연결, 나머지 트래픽의 기본 정책 순서입니다. 그런 다음 각 계층을 규칙으로 바꾸고 “예외를 앞에, 일반 규칙을 뒤에” 배치하세요. 여러 네트워크 설정 조각을 바로 이어 붙이는 것보다 충돌을 찾기 쉽습니다.

예를 들어 특정 도메인 전체는 직접 연결해야 하지만 그 안의 API 하위 도메인 하나는 프록시를 사용해야 한다면 완전한 API 도메인 규칙을 먼저 쓰고 전체 도메인 접미사 직접 연결 규칙을 뒤에 작성해야 합니다. 순서가 반대면 접미사 규칙이 먼저 적중해 예외 규칙이 실행되지 않습니다. 문제를 해결할 때는 파일에 특정 규칙이 있는지만 검색하지 말고 연결 로그에서 실제로 적중한 규칙 유형과 대상 정책을 확인하세요.

rules:
  - DOMAIN,api.example.com,노드 선택
  - DOMAIN-SUFFIX,example.com,DIRECT
  - GEOSITE,private,DIRECT
  - GEOIP,LAN,DIRECT,no-resolve
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

규칙이 늘어나면 중복과 충돌을 눈으로만 찾기 어렵습니다. 안정적인 공용 규칙은 rule-providers로 옮기고 로컬 rules에는 우선순위가 높은 소수의 예외와 최종 대체 규칙만 남길 수 있습니다. 원격 규칙 집합도 동작 유형과 정책 대상을 확인해야 하며 출처를 신뢰할 수 있다는 이유로 적용 범위를 무시해서는 안 됩니다. 규칙 업데이트 후 특정 웹사이트의 경로가 잘못되면 곧바로 노드를 바꾸기보다 업데이트 전후의 적중 결과를 비교하세요.

프록시 제공자와 규칙 제공자

proxy-providers는 원격 노드 집합을 관리합니다

proxy-providers는 노드 목록을 주 설정에서 분리합니다. 각 제공자에는 일반적으로 유형, 다운로드 주소, 로컬 캐시 경로, 업데이트 간격과 상태 점검 설정이 포함됩니다. 정책 그룹은 노드명을 proxies에 하나씩 적는 대신 use로 제공자를 참조합니다. 이 구조는 구독 업데이트에 적합하고 여러 출처에 별도의 필터와 점검을 적용하기도 쉽습니다.

type: http는 원격 주소에서 가져온다는 뜻이고 path는 다운로드 후 로컬 캐시 위치이며 interval은 업데이트 간격을 제어합니다. 원격 파일은 코어가 지원하는 프록시 제공자 형식이어야 하며 전체 Clash 설정을 순수 노드 집합으로 바로 사용할 수는 없습니다. 구독이 전체 설정을 반환한다면 클라이언트 구독 관리 계층에서 가져오거나 신뢰할 수 있는 변환 절차로 provider 파일을 생성해야 합니다.

proxy-providers:
  remote-nodes:
    type: http
    url: "https://subscription.example/nodes.yaml?token=xxxx"
    path: ./providers/remote-nodes.yaml
    interval: 21600
    health-check:
      enable: true
      lazy: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "제공자 선택"
    type: select
    use:
      - remote-nodes
    proxies:
      - DIRECT

예시 구독 주소에는 분명한 가상 값이 사용되었습니다. 실제 구독에는 보통 접근 인증 정보가 포함되므로 공개 저장소, 스크린샷이나 공유 문서에 적지 마세요. 제공자 다운로드에 실패해도 코어가 로컬 캐시를 계속 사용할 수 있어 화면에 이전 노드가 표시될 수 있습니다. 문제를 해결할 때는 “이번 업데이트가 성공했는지”와 “캐시를 여전히 읽을 수 있는지”를 함께 확인해야 합니다. 노드 목록이 존재한다는 사실만으로 구독이 정상이라고 판단해서는 안 됩니다.

path는 클라이언트가 쓰기를 허용하는 설정 디렉터리 안에 있어야 합니다. 절대 경로는 여러 플랫폼에서의 이식성을 낮추며 Windows, macOS, Linux와 Android의 디렉터리 구조도 다릅니다. 클라이언트 작업 디렉터리 아래의 상대 경로를 우선 사용하고 제공자마다 다른 파일명을 지정하세요. 여러 제공자가 같은 경로에 쓰면 서로 덮어써 한 출처를 새로 고친 뒤 다른 출처의 노드가 갑자기 바뀌는 현상이 나타납니다.

상태 점검은 제공자 수준의 가용성 관찰입니다

제공자의 health-check는 노드가 테스트 주소에 접근할 수 있는지 확인합니다. 정책 그룹의 url-test와 관련은 있지만 목적은 다릅니다. 전자는 제공자 노드의 사용 가능 상태를 관리하고 후자는 그룹 내부 구성원 중에서 선택합니다. 두 곳 모두 간격을 지나치게 짧게 설정하면 테스트 요청이 많이 중복됩니다. 일반적인 설정에서는 제공자가 긴 주기로 점검하도록 하고 자동 선택이 필요한 정책 그룹만 적절한 간격으로 테스트하도록 구성할 수 있습니다.

테스트 주소는 안정적이고 응답이 가벼워야 합니다. 특정 노드가 테스트 주소에 접근하지 못하는 이유는 노드 장애일 수도 있고 해당 출구 네트워크가 대상을 제한하기 때문일 수도 있습니다. 모든 노드가 동시에 실패하면 먼저 DNS와 테스트 주소 자체를 확인하고, 특정 프로토콜만 실패하면 핸드셰이크 로그를 살펴보세요. 상태 점검은 대역폭 테스트가 아니며 동영상, 로그인이나 특정 지역 콘텐츠의 사용 가능 여부를 검증하지도 않습니다.

rule-providers로 대규모 규칙 집합 분리

rule-providers는 원격 또는 로컬 규칙 집합을 불러오는 데 사용합니다. 일반적인 behavior에는 domain, ipcidr, classical이 있습니다. domain 집합은 도메인 항목에, ipcidr는 주소 대역에, classical은 유형이 포함된 고전 규칙에 사용합니다. 동작 유형은 파일 내용과 일치해야 하며, 그렇지 않으면 파싱에 실패하거나 규칙이 적용되지 않습니다.

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

  service-rules:
    type: http
    behavior: classical
    format: yaml
    url: "https://rules.example/service-rules.yaml"
    path: ./rules/service-rules.yaml
    interval: 86400

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-rules,업무별 분기
  - MATCH,노드 선택

규칙 제공자는 매칭 집합만 제공하며 이를 사용할 때는 주 설정의 rules에서 RULE-SET을 통해 정책 대상을 지정해야 합니다. 같은 규칙 집합을 여러 설정에서 서로 다른 정책 그룹에 매핑할 수 있습니다. 원격 파일이 업데이트되면 매칭 범위가 바뀔 수 있으므로 출처와 용도를 기록하고 정체를 알 수 없는 대규모 집합을 최우선 순위에 바로 배치하지 마세요.

format은 원격 콘텐츠와 일치해야 합니다. YAML 규칙 파일은 보통 payload 목록으로 구성하고, 바이너리 형식은 코어 지원 여부와 해당 확장 기능에 의존합니다. 파일 확장자만 바꾼다고 콘텐츠 형식이 변환되지는 않습니다. 내려받은 파일이 실제로 HTML 오류 페이지라면 파서는 대개 처음부터 오류를 보고합니다. 제공자 업데이트에 실패하면 먼저 HTTP 상태와 응답 내용을 확인한 뒤 동작 유형, 형식과 로컬 경로 권한을 점검하세요.

제공자와 주 설정의 업데이트 범위

주 설정은 포트, DNS, 정책 그룹 구조와 최종 규칙 순서를 제어하고 제공자는 변경되는 노드 집합이나 규칙 집합을 담당합니다. 안정적인 구조는 주 설정에, 자주 바뀌는 데이터는 제공자에 두면 구독 새로 고침으로 로컬 설정이 덮어써질 가능성을 줄일 수 있습니다. 모든 내용이 원격 구독으로 생성된다면 로컬 개인 설정은 캐시 파일을 새로 고칠 때마다 직접 수정하지 말고 오버라이드 계층으로 추가하세요.

여러 노드 출처는 각각 제공자를 만든 뒤 정책 그룹에서 조합할 수 있습니다. 이때 노드명이 겹치는 문제에 주의해야 합니다. 서로 다른 출처에 같은 표시 이름이 있으면 그룹 필터와 로그 식별이 어려워집니다. 규칙에서 동명이인 노드에 의존하기보다 구독 변환 또는 오버라이드 단계에서 출처 접두사를 추가하세요. 규칙 제공자도 역할이 겹치지 않도록 해야 합니다. 범위가 넓은 두 도메인 집합이 서로 다른 정책을 가리키더라도 실제 동작은 rules에서의 순서로 결정됩니다.

오버라이드, 병합, 검증과 문제 해결

오버라이드 계층은 안정적인 구조를 수정하고 구독 캐시는 직접 수정하지 않아야 합니다

구독을 새로 고치면 보통 캐시 파일을 다시 내려받아 교체하므로 구독 내용을 직접 편집하면 다음 업데이트에서 사라지기 쉽습니다. 더 안정적인 방법은 원격 구독을 데이터 원본으로 유지하고 클라이언트가 제공하는 전역 오버라이드, 확장 스크립트나 로컬 병합 파일로 포트, DNS, 정책 그룹과 규칙을 수정하는 것입니다. 클라이언트마다 지원하는 오버라이드 형식이 다르고 Clash Plus, Clash Verge Rev, FlClash 등의 화면 이름과 실행 순서도 다를 수 있습니다. 오버라이드가 구독 파싱 전후 어느 시점에 적용되는지 먼저 확인하세요.

오버라이드는 “스칼라 교체”, “매핑 병합”, “목록 추가”, “목록 앞에 삽입”, “필드 삭제”로 나눌 수 있습니다. mode 같은 스칼라는 보통 직접 교체하고, 매핑인 dns는 일부 하위 필드만 바꿀 수 있습니다. rules는 순서가 있는 목록이므로 단순히 끝에 추가하면 MATCH 뒤에 놓여 적용되지 않을 수 있습니다. 따라서 로컬 우선 규칙은 목록 앞부분에 삽입해야 합니다. 정책 그룹 목록을 이름으로 병합할 때는 클라이언트가 객체 키로 식별하는 기능을 지원하는지 확인해야 하며, 그렇지 않으면 같은 이름의 정책 그룹이 두 개 생길 수 있습니다.

# base.yaml
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
rules:
  - GEOSITE,cn,DIRECT
  - MATCH,노드 선택

# override.yaml의 대상 의미
dns:
  ipv6: false
  fake-ip-filter:
    - "*.lan"
    - "*.local"

# MATCH 앞에 삽입해야 하는 로컬 규칙
rules-prepend:
  - DOMAIN,api.example.com,업무별 분기
  - DOMAIN-SUFFIX,internal.example,DIRECT

rules-prepend는 오버라이드 도구에서 사용할 수 있는 의미를 보여주는 예시이며 모든 코어가 최상위 필드로 직접 인식하는 것은 아닙니다. mihomo에 최종 전달되는 파일은 표준 rules 목록으로 펼쳐져야 합니다. 특정 클라이언트의 확장 필드를 사용할 때는 클라이언트 오버라이드 파일에만 두고 코어에 직접 전달할 설정에는 복사하지 마세요. 필드가 클라이언트용인지 코어용인지 판단하려면 내보낸 최종 설정과 시작 로그를 확인할 수 있습니다.

목록을 병합할 때 순서와 중복 제거 방식을 명확히 해야 합니다

규칙 목록을 병합할 때 가장 중요한 것은 순서입니다. 로컬 강제 규칙은 원격 규칙보다 앞에, 보충 규칙은 지역 규칙보다 앞에 배치하고 최종 대체 규칙은 유일한 마지막 항목으로 유지하는 것이 좋습니다. 병합 후에는 MATCH가 여러 개 있는지, 사설 네트워크 규칙이 프록시 대체 규칙 뒤에 놓이지 않았는지, 같은 도메인이 더 이른 포괄 규칙에 가려지지 않았는지 확인하세요. 규칙 텍스트가 중복되어도 시작 오류가 발생하지 않을 수 있지만 매칭과 유지보수 비용이 커집니다.

정책 그룹과 노드 목록의 중복은 전체 행 텍스트만 비교해서는 안 됩니다. 노드 객체는 이름이 같아도 서버가 다를 수 있고, 서버가 같아도 이름이 다를 수 있습니다. 수동 관리에서는 고유 이름을 첫 번째 기준으로 삼은 뒤 프로토콜, 서버와 포트를 대조하세요. 정책 그룹 이름 중복은 노드 이름 중복보다 위험한 경우가 많습니다. 규칙은 그룹명만 참조하며 중복 정의의 처리 방식이 파서나 클라이언트에 따라 달라질 수 있기 때문입니다.

DNS 매핑을 병합할 때는 목록 필드가 교체되는지 추가되는지 특히 주의하세요. 오버라이더가 nameserver를 완전히 교체하면 기본 설정의 보조 상위 서버가 사라집니다. fake-ip-filter를 추가하는 방식은 보통 필터를 보충하려는 의도에 맞습니다. 오버라이드 조각만 보지 말고 반드시 병합된 최종 YAML을 확인해야 합니다. 그래픽 클라이언트에 “실행 설정 보기”나 “현재 설정 내보내기” 기능이 있다면 그 결과를 검증 대상으로 삼으세요.

설정 검증은 네 가지 계층으로 진행해야 합니다

첫 번째 계층은 YAML 문법입니다. 들여쓰기, 콜론, 따옴표, 목록과 데이터 유형이 올바른지 확인해야 합니다. 두 번째는 필드 검증으로 코어가 필드를 인식하는지, 프로토콜 필수 매개변수가 모두 있는지 확인합니다. 세 번째는 참조 관계로 규칙 대상, 정책 그룹 구성원, 제공자 이름과 로컬 경로가 존재하는지 점검합니다. 네 번째는 실행 동작으로 포트 수신 가능 여부, DNS 상위 서버 접근 여부, 노드 핸드셰이크와 규칙 적중 결과를 확인합니다. 앞 계층이 통과하지 못한 상태에서 뒤의 네트워크 테스트를 해도 의미가 없습니다.

# 클라이언트 내장 검증 기능을 사용할 때는 실제 코어 경로와 설정 경로를 기준으로 합니다
mihomo -t -f config.yaml

# 설정이 통과되면 출력에 보통 설정 테스트가 완료되었다는 내용이 표시됩니다
# 실패하면 오류 행 번호, 필드명과 참조 이름을 중점적으로 기록합니다

명령줄의 실행 파일명과 매개변수는 실제 설치 방식에 따라 달라지며 그래픽 클라이언트에는 보통 설정 검사 기능이 포함되어 있습니다. 테스트할 때는 클라이언트와 같은 mihomo 코어를 사용하세요. 한 코어는 필드를 허용하지만 다른 코어는 지원하지 않을 수 있습니다. 오류 행 번호는 파서가 문제를 발견한 위치를 가리킬 뿐 근본 원인의 위치가 아닐 수 있습니다. 예를 들어 이전 줄에 닫는 따옴표가 없으면 다음 줄에서 오류가 드러날 수 있습니다.

설정을 수정할 때 여러 장을 한 번에 다시 작성하지 마세요. 먼저 실행 가능한 버전으로 되돌린 다음 DNS, 노드, 정책 그룹과 규칙을 블록별로 추가하는 이분 탐색 방식이 좋습니다. 특정 블록에서 오류가 발생하면 구체적인 필드까지 범위를 좁히세요. 원격 제공자는 잠시 한두 개의 정적 예시 노드로 바꾸어 문제가 다운로드 경로에 있는지 정책 구조에 있는지 판단할 수 있습니다. 문제 해결이 끝나면 전체 출처를 복원하세요.

흔한 오류의 확인 경로

설정은 시작되지만 인터넷에 연결되지 않는다면 먼저 Clash를 거치지 않았을 때 기본 네트워크가 정상인지 확인하세요. 다음으로 로컬 인바운드 포트를 확인하고 DNS, 정책 그룹, 노드 핸드셰이크와 규칙 적중을 차례로 점검합니다. 처음부터 모든 규칙을 삭제하거나 보안 설정을 전부 끄지 마세요. 장애 상황을 훼손할 수 있습니다. 로그에는 첫 실패 시점을 남기고 당시 선택한 모드와 정책 그룹을 대조하세요. 반복해서 재시작하는 것보다 효과적인 경우가 많습니다.

브라우저만 이상하면 브라우저에서 독립 보안 DNS, 프록시 확장이나 QUIC를 사용하고 있는지 확인하세요. 모든 애플리케이션이 이상하면 시스템 프록시나 TUN을 점검합니다. LAN 기기만 이상하고 로컬 기기는 정상이라면 수신 범위와 방화벽을 확인하세요. 특정 정책 그룹만 이상하면 그룹 구성원과 상태 점검을 확인합니다. 증상 범위에 따라 관련 설정 계층도 달라지므로 먼저 범위를 정하면 불필요한 수정을 피할 수 있습니다.

유지보수 가능한 설정을 위한 최종 체크리스트

설정을 완료한 뒤 최상위 필드가 유효한 정의 하나만 갖는지, 포트가 서로 충돌하지 않는지, DNS 상위 서버에 기본 조회 경로가 있는지, 모든 노드명이 고유한지 확인하세요. 정책 그룹 참조가 단방향인지, 모든 규칙 대상이 존재하는지, MATCH가 마지막에 한 번만 나타나는지, 제공자 캐시 경로가 서로 덮어쓰지 않는지, 로컬 오버라이드에 구독 인증 정보가 공개 복사본으로 포함되지 않았는지, 최종 실행 설정이 현재 코어 검증을 통과하는지도 점검해야 합니다. 이후 직접 연결 도메인, 프록시 도메인, IP 대상과 UDP 애플리케이션을 각각 테스트해 단일 웹페이지에서만 우연히 성공한 것이 아닌지 확인하세요.

설정 파일은 구독 출처, 오버라이드 파일과 실행 상태와 분리해 백업해야 합니다. 여러 기기에서 재사용하려면 먼저 플랫폼 전용 경로와 제어 포트를 제거하고 각 기기에 독립적인 시스템 가로채기 설정을 남기세요. 원격 구독은 노드 변화를 담당하고 로컬 오버라이드는 안정적인 기본 설정을 담당하며 클라이언트 실행 디렉터리는 캐시와 선택 상태를 담당합니다. 세 영역을 구분하면 구독 업데이트, 클라이언트 업그레이드와 기기 이전이 서로 덮어쓰지 않습니다.

분류하기 어려운 문제는 도움말 센터에서 기본 개념, 설치 및 설정, 사용 팁과 문제 해결 항목별로 계속 찾아보세요. 설치부터 첫 연결까지 다시 작동 가능한 기준선을 만들려면 시작 가이드로 돌아가 단계별로 실행하세요. 클라이언트나 코어 설치 패키지를 다시 선택해야 한다면 설치 패키지 페이지에서 플랫폼별로 확인하세요. 문제를 해결할 때는 항상 현재 설정을 먼저 저장한 뒤 되돌릴 수 있는 작은 범위만 수정하세요.