Clash 설정 필드 가이드

YAML 구조 한눈에 보기

Clash 설정은 서로 무관한 옵션의 모음이 아니라, 항목끼리 참조하는 구조입니다. 공통 필드는 코어의 연결 수신 방식을 정하고, DNS는 도메인 조회를 처리하며, 노드는 실제 연결 출구를 제공합니다. 프록시 그룹은 출구를 묶고, 규칙은 요청을 적절한 그룹으로 전달합니다. 모든 키 이름을 외우기보다 이 흐름을 이해하는 편이 유용합니다. 문제를 찾을 때도 요청이 코어에 들어왔는지 확인한 뒤 규칙의 대상과 선택된 노드를 차례로 살펴보세요.

먼저 계층을, 다음에 필드를 살펴보세요

YAML은 들여쓰기로 계층을 표현합니다. 최상위의 dns, proxies, proxy-groups, rules는 같은 단계에 있고, DNS에 속하는 nameserver는 들여써야 합니다. 목록의 하이픈은 새 항목을 나타내며 장식 기호가 아닙니다. 들여쓰기는 공백 두 칸으로 통일하고 탭은 사용하지 않는 것이 좋습니다. 편집기에서 정렬되어 보여도 실제 문자가 같다는 뜻은 아니므로, 웹페이지에서 복사한 내용은 특히 줄 앞에 전각 공백이 섞이지 않았는지 확인하세요.

아래는 직결 출구만 포함한 구조 예제입니다. 설정 로드, 수신 포트, 정책 참조를 확인하는 데 사용할 수 있습니다. 이 설정만으로 프록시 서비스가 생기는 것은 아니며, 서비스 제공자가 안내한 연결 정보도 대체하지 않습니다. 먼저 작은 설정이 검사를 통과하도록 한 다음 노드와 규칙을 차례로 추가하면, 출처가 다른 여러 조각을 한 번에 붙여 넣는 것보다 문제를 찾기 쉽습니다.

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

dns:
  enable: false

proxies: []

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,PROXY

문자열, 목록, 참조

노드 이름과 프록시 그룹 이름은 문자열 참조로 사용됩니다. 규칙에 PROXY가 있다면 설정에도 같은 이름의 프록시 그룹이나 출구가 있어야 합니다. 비슷한 이름은 같은 이름이 아니며 대소문자, 공백, 문장 부호도 일치 여부에 영향을 줍니다. 짧고 안정적인 이름을 사용하고, 바뀔 수 있는 트래픽 안내나 날짜를 주요 참조 이름으로 쓰지 마세요. 노드 이름을 바꾸면 프록시 그룹 목록과 해당 노드를 직접 참조하는 규칙도 함께 확인해야 합니다. 파일 문법이 올바르더라도 참조 관계 검사는 실패할 수 있습니다.

불리언 값은 보통 true 또는 false로, 포트와 간격은 숫자로 씁니다. 비밀번호 같은 텍스트는 따옴표로 감싸는 편이 좋습니다. 콜론 뒤에 공백이 있거나 우물 정자, 대괄호 등 특수 문자가 포함된 문자열은 특히 명시적으로 인용하세요. 따옴표는 민감한 정보를 숨기는 기능이 아니라 데이터 형식을 명확히 하는 역할을 합니다. 키와 값 사이에 전각 콜론을 쓰지 마세요. 한국어 입력기의 따옴표도 YAML에서 요구하는 반각 따옴표를 대신할 수 없습니다.

같은 계층에서 동일한 키를 중복 선언하지 마세요. 앞에서 DNS 설정을 작성한 뒤 파일 끝에 dns:를 다시 붙여 넣어도 두 설정이 자동으로 합쳐지는 것은 아닙니다. 파서에 따라 중복 키를 거부하거나 뒤의 값만 남길 수 있어 결과를 신뢰하기 어렵습니다. DNS 서버를 추가하려면 기존 목록을 수정하세요. 클라이언트에서 설정을 병합해야 한다면 명시적인 오버라이드 기능을 사용하고, 최종 결과도 확인해야 합니다.

전체 설정과 노드 목록의 차이

전체 설정에는 수신 설정, 프록시 그룹, 규칙 등 실행에 필요한 정보가 포함됩니다. 노드 목록은 주로 연결 매개변수를 설명합니다. 둘 다 YAML일 수 있지만 용도는 다릅니다. proxy-providers가 참조하는 파일은 보통 제공자 형식이므로 확장자만 보고 전체 구독 설정으로 사용할 수는 없습니다. 가져오기에 실패하면 응답이 로그인 페이지, 오류 안내 또는 인코딩된 문자열로 바뀌지 않았는지 먼저 확인하세요. 형식 차이는 구독 링크와 YAML 형식 안내에서 더 살펴볼 수 있습니다.

이후 예제의 코드는 특정 필드의 작성 방법을 보여주는 조각이지, 각각 독립적으로 실행할 수 있는 파일이 아닙니다. 특히 프록시 그룹이나 제공자 이름이 들어간 조각은 실제 설정에 정의된 이름과 일치해야 합니다. 저장하기 전에 해당 조각을 최상위에 둘지 목록 항목 안에 넣을지 확인하세요. 계층이 잘못되면 즉시 오류가 나지 않고 필드가 무시된 채 이전 동작이 계속될 수도 있습니다.

포트 및 실행 모드

포트 설정은 애플리케이션이 연결을 어디로 보낼지를 정하며, 최종적으로 어느 노드를 통해 나갈지는 결정하지 않습니다. 시스템 프록시는 보통 애플리케이션이 로컬 HTTP 또는 혼합 포트를 사용하도록 설정하고, 앱 내부의 SOCKS 설정에는 해당하는 SOCKS 수신 포트가 필요합니다. 먼저 수신 유형을 확인한 뒤 주소와 포트를 입력하세요. 원격 프록시 서버 포트를 로컬 수신 포트에 입력하거나 그 반대로 설정하면 연결에 실패할 수 있습니다. 두 포트는 연결 경로에서 서로 다른 위치에 있습니다.

port, socks-port, mixed-port

port는 HTTP 프록시 수신 포트, socks-port는 SOCKS 프록시 수신 포트이며, mixed-port는 하나의 포트에서 HTTP와 SOCKS 요청을 모두 받습니다. 일반적으로는 혼합 포트 하나만 사용해도 충분하므로 모든 수신 포트를 켤 필요는 없습니다. 여러 수신 포트가 동일한 주소와 포트 조합을 점유할 수는 없습니다. 이미 다른 클라이언트나 백그라운드 서비스가 포트를 사용 중이면 새 코어가 시작되지 않을 수 있습니다.

mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false
profile:
  store-selected: true

LAN 접근에는 여러 조건이 필요합니다

allow-lan: false는 이 컴퓨터에서만 사용할 때 적합합니다. 다른 기기에서 연결하려면 LAN 접근을 허용하고, 해당 기기에서 접근할 수 있는 수신 주소를 설정해야 합니다. 상대 기기에는 클라이언트를 실행하는 컴퓨터의 LAN 주소를 입력해야 하며, 상대 기기 자신의 루프백 주소를 입력해서는 안 됩니다. 이후 운영체제 방화벽과 무선 네트워크의 기기 간 격리 설정을 확인하세요. LAN 접근을 허용한다고 인증이 자동으로 설정되는 것은 아니며, 수신 포트를 인터넷에 직접 공개해도 된다는 뜻도 아닙니다.

수신 포트를 공유할 때는 사용 대상과 네트워크 경계를 분명히 하세요. 필요하다면 수신 인증과 클라이언트가 지원하는 접근 제한을 설정해야 합니다. 관리 인터페이스와 프록시 수신 포트도 구분하세요. external-controller는 코어를 제어하는 인터페이스이지 브라우저에 입력하는 프록시 주소가 아닙니다. 원격 제어가 필요하지 않다면 로컬에서만 접근하도록 설정하세요. 외부에 공개하는 관리 인터페이스 예제를 그대로 복사하거나, 공개 다운로드 설정 파일에 제어 인증 정보를 넣지 마세요.

모드와 트래픽 가로채기는 별개입니다

rule은 규칙에 따라 출구를 선택하고, global은 전역 정책을 사용하며, direct는 직결을 뜻합니다. 전역 모드는 모든 프로그램을 프록시에 강제로 연결하지 않습니다. 이미 코어에 들어온 요청의 경로 선택 방식만 바꿉니다. 시스템 프록시를 우회하는 앱은 화면에 전역 모드가 표시되어도 계속 직결될 수 있습니다. 따라서 모드 설정을 의심하기 전에 해당 앱의 연결이 클라이언트 연결 목록에 나타나는지 확인하세요.

시스템 프록시는 시스템 프록시 설정을 따르는 앱의 연결을 처리합니다. TUN은 가상 네트워크 인터페이스를 통해 트래픽을 가로채므로 둘은 같은 필드의 다른 이름이 아닙니다. TUN에는 권한, 라우팅, DNS 가로채기, 다른 가상 네트워크 카드와 관련된 설정도 필요합니다. 스위치를 켰다고 모든 준비가 끝난 것은 아닙니다. 처음에는 혼합 포트를 지원하는 앱으로 확인한 뒤 TUN을 별도로 활성화하세요. 수신 포트 문제와 라우팅 문제가 동시에 생기는 것을 피할 수 있습니다.

클라이언트가 설정의 모드나 그룹 선택을 저장된 상태로 덮어쓸 수 있습니다. 예제의 store-selected는 프록시 그룹 선택을 저장해 재시작 후 다시 선택할 필요를 줄여 줍니다. 반면 기본 목록 순서를 바꿔도 현재 선택에는 바로 반영되지 않을 수 있습니다. 확인할 때는 구독 텍스트의 한 줄만 보지 말고 화면에 표시된 실시간 모드, 그룹의 현재 출구, 코어 실행 설정을 기준으로 판단하세요.

포트 충돌이 발생하면 중복 실행 중인 클라이언트를 먼저 종료하고 백그라운드 코어가 계속 포트를 수신하고 있는지 확인한 다음 포트 변경을 검토하세요. 포트를 바꾼 뒤에는 시스템 프록시, 브라우저 확장 프로그램, 앱에 수동 입력한 주소도 함께 수정해야 합니다. YAML만 바꾸고 앱에 이전 포트를 남겨 두면 코어는 정상인데 웹페이지가 열리지 않는 것처럼 보입니다. 소프트웨어를 다시 설치할 필요 없이 수신 포트와 앱 설정을 일치시키면 해결되는 경우가 많습니다.

DNS 설정

DNS는 도메인을 주소로 변환하며, 도메인이나 주소를 이용한 분기 판단에도 영향을 줍니다. 웹페이지가 열리지 않는다고 노드가 항상 문제인 것은 아닙니다. 원격 서버에 연결하기 전에 도메인 조회가 실패했을 수 있습니다. 문제를 찾을 때는 대상 웹사이트의 도메인, 프록시 서버의 도메인, DNS 업스트림 서버의 도메인을 구분하세요. 각각 다른 경로로 조회될 수 있습니다. 하나의 DNS 서버가 모든 역할을 맡도록 설정하면 간단해 보이지만, 네트워크 환경이 바뀔 때 의존성 순환이 생기기 쉽습니다.

내장 DNS와 fake-ip 사용

dns.enable은 내장 DNS 기능을 제어합니다. listen은 수신 주소를 지정하지만, 수신 주소를 설정했다고 운영체제가 자동으로 DNS 요청을 보내는 것은 아닙니다. 시스템 DNS 설정, 클라이언트의 트래픽 가로채기 또는 TUN DNS 가로채기를 통해 요청을 코어로 보내야 합니다. enhanced-mode: fake-ip는 도메인에 가상 주소를 할당하고 코어가 도메인 매핑을 유지한 뒤 실제 연결 시 출구를 처리하도록 합니다. 가상 주소는 웹사이트의 실제 서버 주소가 아니므로 노드 주소로 사용하지 마세요.

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:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - "*.lan"
    - "localhost"

위 주소는 필드 간 관계를 설명하기 위한 예시입니다. 현재 네트워크에 적합한지는 직접 확인해야 합니다. default-nameserver는 DNS 업스트림 서버 자체의 도메인을 조회할 때 주로 사용하므로 현재 네트워크에서 직접 접근할 수 있는 부트스트랩 DNS를 선택해야 합니다. proxy-server-nameserver는 프록시 서버 도메인의 조회 경로를 지정해, 프록시에 연결하려고 노드 도메인을 조회하는데 그 조회에 다시 프록시가 필요한 순환을 방지하는 데 도움이 됩니다. 모든 웹사이트 조회에 공통으로 사용되는 출구는 아닙니다.

DNS 조회 경로와 연결 경로를 따로 확인하세요

nameserver는 기본 업스트림 목록이고, nameserver-policy는 도메인이나 지원되는 규칙 조건에 따라 업스트림을 지정할 수 있습니다. 세밀한 제어가 필요하다면 범위가 작고 결과를 확인할 수 있는 정책부터 작성한 뒤 점차 넓히세요. DNS 요청의 경로와 이후 웹사이트 연결의 출구는 같지 않을 수 있습니다. 최종 연결은 여전히 라우팅 규칙을 거칩니다. 두 경로를 혼동하면 DNS 조회에 성공한 것을 프록시 연결 성공으로 오해할 수 있습니다.

mihomo의 respect-rules를 사용하면 DNS 업스트림 연결에 라우팅 규칙을 따르게 할 수 있습니다. 활성화하기 전에 프록시 서버 도메인의 조회 경로를 먼저 정하고, 규칙이 아직 완료되지 않은 조회에 역으로 의존하지 않는지 확인하세요. 초보자에게는 암호화 업스트림을 여러 개 쌓는 것보다 명확한 부트스트랩 경로가 중요합니다. 현재 네트워크에서 업스트림 하나에 접근할 수 없다면 같은 경로에 다른 주소를 더해도 가용성이 높아지지 않을 수 있으며, 로그만 복잡해질 수 있습니다.

fake-ip-filter는 특정 LAN 검색 서비스나 실제 주소가 필요한 앱처럼 가상 주소를 할당하면 안 되는 도메인을 처리할 때 유용합니다. 하지만 필터는 조회 결과를 바꿀 뿐 직결 규칙을 자동으로 적용하지 않습니다. 도메인을 직결해야 한다면 연결 규칙이 DIRECT를 가리키는지도 확인하세요. 문제가 생긴 웹사이트를 모두 필터에 추가하지 마세요. 목록이 지나치게 커지면 실제 트래픽 가로채기 오류를 가리고 도메인 매핑을 관찰하기 어려워질 수 있습니다.

IPv6, 캐시, 문제 발생 범위

최상위 ipv6와 DNS 내부의 같은 이름 필드는 완전히 동일한 스위치가 아닙니다. 전자는 코어의 IPv6 사용과 관련되고, 후자는 내장 리졸버의 주소 조회와 응답 동작에 영향을 줍니다. 시스템, 앱, 다른 DNS 서비스에도 별도의 IPv6 경로가 있을 수 있습니다. 일부 웹사이트가 간헐적으로 열리지 않는다면 특정 노드가 불안정하다고 단정하기 전에 IPv4만 가로채고 IPv6 트래픽은 우회하는 상황인지 확인하세요.

DNS를 바꿔도 기존 연결이 자동으로 다시 조회되지는 않으며, 앱과 시스템 캐시에 이전 결과가 남아 있을 수 있습니다. 먼저 설정을 다시 불러온 뒤 관련 앱 연결을 종료하고 새 요청을 보내세요. 필요한 경우에만 해당 캐시를 비우세요. fake-ip를 사용한다면 호환되지 않는 다른 주소 매핑에 이전 캐시를 오래 유지하지 마세요. 주소가 하나 반환됐다는 사실은 조회 단계가 완료됐다는 뜻일 뿐입니다. 연결 목록의 대상, 규칙, 출구도 계속 확인해야 합니다.

여러 DNS 설정을 비교할 때는 한 번에 한 가지씩만 바꾸세요. 먼저 업스트림을 바꾸고, 다음으로 필터를 테스트한 뒤 규칙 적용 방식을 조정하는 식입니다. 실패한 도메인, 테스트 시각, 로그에서 오류가 발생한 단계를 기록하고 단순히 웹페이지가 느렸다고만 남기지 마세요. 그래야 부트스트랩 실패, 업스트림 접근 불가, 도메인 매핑 오류, 조회 후 대상 연결 실패를 구분할 수 있습니다. 마지막 경우에는 DNS 서버를 더 추가하기보다 노드와 규칙 설정을 확인해야 합니다.

프록시 노드 필드

proxies는 원격 서비스에 실제로 연결하는 데 필요한 정보를 정의합니다. 노드 이름은 로컬에서 사용하는 식별자일 뿐 프로토콜을 결정하지 않습니다. 프로토콜은 type으로 지정하며 필수 항목도 프로토콜에 따라 달라집니다. 이름에 특정 프로토콜이 들어 있어도 실제 설정이 그 프로토콜을 사용한다는 뜻은 아닙니다. 문제를 찾을 때는 실제 필드를 확인하고 현재 코어가 해당 유형을 지원하는지 살펴보세요. 그래픽 인터페이스에서 텍스트를 가져올 수 있어도 코어의 연결 성공까지 보장되지는 않으므로 두 단계를 따로 검증해야 합니다.

공통 정보와 프로토콜별 정보

대부분의 노드에는 name, type, server, port가 들어갑니다. 서버는 도메인이나 주소를 지정하고 포트는 원격 서비스와 일치해야 합니다. 인증 방식은 프로토콜마다 다르며 비밀번호, 사용자 식별 정보 또는 다른 인증 정보를 사용할 수 있습니다. 서로 다른 프로토콜의 필드를 섞어 쓰지 말고 type 이름만 바꾸면 프로토콜이 변환된다고 생각하지 마세요. 서버와 클라이언트가 같은 연결 방식을 사용해야 합니다.

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

이 조각은 Shadowsocks 노드 구조를 보여줍니다. example.com과 예시 비밀번호는 실제로 사용할 수 있는 서비스 정보가 아닙니다. 실제 사용 시에는 서비스 제공자가 안내한 정보로 바꾸고 노드 이름을 프록시 그룹 참조에 추가해야 합니다. cipher는 서버 설정과 일치해야 하며, 더 강해 보인다는 이유로 다른 방식을 임의로 고르면 안 됩니다. 서버 주소가 맞더라도 인증 정보가 틀리면 기본 연결은 성립해도 앱 데이터가 정상적으로 전달되지 않을 수 있습니다.

TLS와 전송 계층을 혼동하지 마세요

TLS를 지원하는 프로토콜은 servername, 인증서 검증, 애플리케이션 계층 프로토콜 등의 매개변수를 사용할 수 있습니다. 일부 전송 방식에는 경로, 요청 헤더, 전송 옵션도 따로 있습니다. 각 항목은 서로 다른 계층을 설명합니다. 서버 주소는 연결할 대상을 정하고, 서버 이름은 TLS 핸드셰이크에 사용되며, 전송 경로는 서버가 상위 연결을 식별하는 방식에 영향을 줍니다. 서버 주소를 조회된 IP로 바꾸면서 기존 서버 이름을 유지하지 않으면 인증서 검증이 실패할 수 있습니다.

인증서 오류가 발생하면 시스템 시간, 서버 이름의 정확성, 인증서 체인, 네트워크 중간 장비를 먼저 확인하세요. 인증서 검증을 건너뛰는 방법을 일반적인 해결책으로 사용하지 말고, 일시적으로 연결됐다고 문제가 해결된 것으로 간주하지도 마세요. 서비스 제공자가 지정한 매개변수가 있다면 안내에 따라 확인하고 오류 로그에서 어느 단계에 실패했는지 기록하세요. 핸드셰이크 실패, 인증 실패, 대상 서버 시간 초과는 각각 해결 방향이 다릅니다.

udp: true는 해당 노드 설정에서 관련 UDP 기능을 허용한다는 뜻입니다. 실제 사용 가능 여부는 프로토콜, 원격 서비스, 수신 방식, 로컬 네트워크에 따라 달라집니다. 모든 앱에서 UDP 프록시가 바로 작동하게 하는 만능 스위치는 아닙니다. 브라우저로 웹페이지를 열 수 있어도 일부 TCP 또는 앱 연결만 가능할 수 있습니다. 게임, 음성 통화 등 UDP 앱은 별도로 확인하고, 앱이 현재 프록시 수신 포트를 우회하는지도 살펴보세요.

노드 제공자와 구독 업데이트

노드가 많고 자주 업데이트된다면 proxy-providers를 사용해 노드 출처와 프록시 그룹 정의를 분리할 수 있습니다. 제공자는 노드 목록을 읽거나 가져오며, 프록시 그룹은 use로 제공자 이름을 참조합니다. 여기서 참조하는 것은 개별 노드가 아니라 제공자입니다. 파일 형식, 접근 가능한 경로, 업데이트 방식이 현재 코어와 클라이언트에서 지원되는지 확인하세요. 노드 목록만 받는 입력란에 클라이언트 전체 설정을 넣어서는 안 됩니다.

proxy-providers:
  local-nodes:
    type: file
    path: ./providers/local-nodes.yaml
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: PROXY
    type: select
    use:
      - local-nodes

해당 파일은 최상위 proxies: 목록에 노드를 배치해야 합니다. 경로는 보통 코어의 작업 디렉터리를 기준으로 해석되지만, 그래픽 클라이언트가 허용된 파일 위치를 제한하거나 디렉터리를 재구성할 수 있습니다. 파일과 구독을 같은 위치에 두었다는 것만으로 판단하지 마세요. 파일을 찾지 못하면 실행 로그에 기록된 실제 경로를 먼저 확인하세요. 상태 확인 결과가 없으면 제공자 로드 실패, 빈 목록, 테스트 요청 실패를 구분해야 합니다. 곧바로 모든 노드를 사용할 수 없다고 판단하지 마세요.

구독을 업데이트하면 노드 이름이 바뀌거나 삭제되어 이름으로 직접 참조하는 프록시 그룹에 영향을 줄 수 있습니다. 장기간 사용하는 사용자 설정에는 안정적인 제공자 참조를 사용하거나 클라이언트가 지원하는 필터링 기능으로 노드를 관리하는 편이 낫습니다. 업데이트 때마다 덮어쓰이는 원본 노드 목록을 계속 수동 수정하지 마세요. 업데이트 자체가 실패했다면 먼저 구독 새로고침 문제 해결 절차에 따라 링크, 네트워크, 응답 형식을 확인한 뒤 노드 매개변수를 살펴보세요.

프록시 그룹 및 상태 확인

프록시 그룹은 규칙과 노드 사이의 중간 계층입니다. 규칙은 현재 어느 서버가 작동하는지 알 필요 없이 안정적인 그룹 이름으로 요청을 전달하고, 그룹은 수동 선택, 자동 선택, 장애 조치 중 하나로 출구를 정합니다. 따라서 노드를 바꿀 때 규칙을 일일이 수정할 필요가 없고 용도별로 구성을 나눌 수 있습니다. 예를 들어 일반 웹 탐색과 특정 서비스에 서로 다른 그룹을 사용할 수 있습니다. 그룹 이름 자체에 특별한 기능이 있는 것은 아니며 실제 동작은 그룹의 출구, 테스트 방식, 규칙 매칭에 따라 결정됩니다.

자주 사용하는 네 가지 유형 고르기

select는 출구를 직접 고르는 방식으로, 특정 출구를 유지하고 싶을 때 적합합니다. url-test는 테스트 결과를 바탕으로 자동 선택하므로 후보 중에서 코어가 출구를 바꾸도록 할 수 있습니다. fallback은 테스트 값이 가장 낮은 후보보다 목록 순서에 따라 사용 가능한 후보를 선택하는 데 중점을 둡니다. load-balance는 지원되는 방식에 따라 연결을 분산합니다. 한 번의 다운로드에 여러 회선의 대역폭을 자동으로 합치는 기능은 아닙니다.

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - 자동 선택
      - DIRECT
  - name: 자동 선택
    type: url-test
    proxies:
      - SS-예시
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

이 조각은 앞 장에서 정의한 동일한 이름의 노드와 함께 사용해야 합니다. 바깥쪽 수동 그룹은 사용자가 직접 제어하고, 안쪽 자동 그룹은 후보를 테스트합니다. 자동 그룹에 후보가 하나만 있어도 테스트할 수 있지만 전환할 다른 노드는 없습니다. interval은 검사 간격이고 tolerance는 테스트 값의 작은 변화로 선택이 자주 바뀌는 일을 줄입니다. 다운로드 속도 기준이 아니며 모든 웹사이트에서 같은 경험을 보장하지도 않습니다.

테스트 성공으로 알 수 있는 것은 한 가지뿐입니다

상태 확인은 지정한 방식으로 테스트 대상에 접근할 수 있는지를 알려줄 뿐, 실제 서비스 동작을 대신 검증하지는 않습니다. 테스트 대상에 접근할 수 없거나 현재 네트워크에서 접근이 제한된 경우, 또는 해당 대상의 DNS 조회에 문제가 있으면 원래 사용 가능한 노드도 실패로 표시될 수 있습니다. 반대로 테스트 요청이 성공해도 계정 서비스, 스트리밍, 게임이 모두 정상 작동한다는 뜻은 아닙니다. 테스트 대상은 안정적이고 가벼우며 실제 용도와 적절히 관련된 곳을 선택하세요.

검사 간격을 지나치게 짧게 설정하면 요청이 계속 늘어날 뿐 더 나은 선택으로 이어지지 않을 수 있습니다. 네트워크 상태가 자주 바뀌면 테스트 결과도 흔들릴 수 있습니다. 먼저 문제가 일정한 패턴을 보이는지 확인하세요. 절전 모드에서 깨어난 뒤에만 나타나는지, 특정 네트워크에서만 발생하는지, 특정 테스트 주소에서만 실패하는지 살펴봅니다. 원인을 찾을 때는 잠시 수동 그룹으로 전환해 노드 하나를 고정하세요. 자동 전환이 로그와 실제 사용에 미치는 영향을 줄인 뒤 후보를 따로 검증할 수 있습니다.

제공자의 상태 확인과 프록시 그룹의 상태 확인은 서로 다른 계층에서 이루어집니다. 설정할 때 누가 검사를 시작하고 어떤 후보를 대상으로 하는지 알아야 합니다. 제공자에 검사 결과가 있다고 해서 해당 제공자를 참조하는 모든 그룹이 완전히 같은 방식으로 선택한다고 볼 수는 없습니다. use로 노드 출처를 참조할 때는 제공자가 정상적으로 로드됐는지 확인하세요. 이름 목록과 제공자를 함께 사용한다면 후보가 중복되거나 직결 출구가 의도치 않게 포함되지 않았는지도 살펴보세요.

중첩 참조와 상태 저장

프록시 그룹은 다른 그룹을 참조할 수 있지만 순환 참조를 만들어서는 안 됩니다. A 그룹이 B 그룹을 가리키고 B 그룹이 다시 A 그룹을 가리키면 이름이 모두 존재해도 출구를 결정할 수 없습니다. 계층은 적게 유지하세요. 용도별 그룹이 선택 그룹을 참조하고, 선택 그룹이 노드를 참조하는 정도면 충분합니다. 계층이 너무 많으면 연결 기록을 읽기 어려워지고 화면에서 선택한 노드와 실제 출구 사이에 여러 단계가 생겨 동작을 파악하기 어려워집니다.

로그인, 결제, 장시간 세션은 출구 변경에 민감할 수 있습니다. 자동 전환이나 연결 분산으로 요청마다 다른 출구를 사용하면 서버가 다시 인증을 요구할 수 있으며, 반드시 노드가 잘못됐다는 뜻은 아닙니다. 이런 용도에는 별도의 수동 선택 그룹을 만들어 안정적으로 사용하세요. 그룹 유형을 바꾼 뒤에는 새 연결을 만들어 확인해야 합니다. 기존 장시간 연결은 바로 다른 출구로 이동하지 않을 수 있어 화면의 새 선택과 기존 세션이 잠시 함께 유지될 수 있습니다.

구독을 바꾼 뒤 프록시 그룹 선택이 예상과 다르면 클라이언트가 이전 선택을 복원했는지, 기존 노드가 삭제됐는지, 새 설정에서 같은 그룹 이름을 재사용했는지 확인하세요. 안정적인 그룹 이름은 기존 설정을 이어 쓰기 편리하지만 저장된 상태도 함께 이어받습니다. 문제를 재현할 때는 현재 선택된 실제 노드를 기록하고 자동 선택을 사용한다고만 적지 마세요. 다시 불러오거나 자동 전환된 뒤에도 당시 연결 조건을 정확히 확인할 수 있습니다.

규칙 문법과 매칭 순서

규칙은 위에서 아래로 확인하며 보통 처음 일치한 규칙이 출구를 결정합니다. 범위가 좁은 예외는 앞에, 범위가 넓은 분류는 뒤에 두고 마지막에 MATCH로 나머지 요청을 처리하세요. 키워드 하나로 규칙 순서를 대신할 수는 없습니다. 같은 규칙도 순서를 바꾸면 결과가 달라질 수 있습니다. 사용자 지정 규칙을 작성할 때는 먼저 어떤 요청을 처리하려는지 한 문장으로 정의한 뒤 그 조건을 정확하게 나타내는 규칙 유형을 고르세요.

도메인 규칙과 IP 주소 규칙

DOMAIN은 지정한 도메인과 일치하고, DOMAIN-SUFFIX는 해당 도메인과 하위 도메인에 적용되며, DOMAIN-KEYWORD는 키워드를 기준으로 더 넓게 매칭합니다. 키워드가 너무 짧으면 관련 없는 웹사이트까지 포함될 수 있으므로 일반적인 예외에는 전체 도메인이나 접미사 규칙을 우선 사용하세요. 규칙의 도메인에는 프로토콜, 경로, 쿼리 매개변수를 넣지 마세요. 웹 주소는 완전한 URL이고 도메인 규칙은 그중 호스트 이름을 처리합니다.

rules:
  - DOMAIN,router.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,example,PROXY
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

예제의 router.example.com은 먼저 정확한 직결 규칙에 일치하므로 뒤에 있는 접미사 규칙에서 프록시로 바뀌지 않습니다. IP 대역 규칙은 LAN이나 명확한 네트워크 범위에 적합하고, GEOIP는 지리 데이터에 따라 분류합니다. 지리적 위치가 웹사이트의 용도와 같은 것은 아니며, 콘텐츠 전송 네트워크에서는 같은 서비스가 여러 지역의 주소를 사용할 수 있습니다. 따라서 주소의 분류 결과를 영구적인 서비스 분류로 간주해서는 안 됩니다.

no-resolve가 적용되는 범위

no-resolve는 주소 규칙에서 주로 사용하며 이 규칙에 일치시키기 위해 도메인을 새로 조회하지 않도록 합니다. 전체 요청에서 DNS를 금지한다는 뜻도 아니고, 모든 도메인 요청이 규칙을 건너뛴다는 뜻도 아닙니다. 코어가 이미 대상 주소를 알고 있다면 주소 매칭이 이루어질 수 있습니다. 불필요한 조회를 줄이거나 매칭 과정을 제어하는 데 사용해야 하며, 모든 DNS 문제를 우회하는 방법으로 사용해서는 안 됩니다.

도메인 규칙이 작동하려면 코어가 도메인 정보를 알아야 합니다. 요청에 IP 주소를 직접 사용하거나 앱이 암호화된 DNS 조회를 자체적으로 수행하거나 수신 단계에서 사용할 수 있는 호스트 이름이 전달되지 않으면 도메인 규칙에 필요한 조건이 없을 수 있습니다. DNS 매핑이나 스니핑으로 정보를 보완할 수 있는 경우도 있지만, 스니핑에는 프로토콜과 암호화 방식, 설정에 따른 제한이 있습니다. 먼저 연결 상세 정보에 도메인이 있는지 확인하고 규칙을 잘못 작성했는지, 매칭에 필요한 정보가 없는지 판단하세요.

GEOSITE와 RULE-SET

GEOSITE는 도메인 분류 데이터를 사용해 서비스 범위를 지정하고, RULE-SET은 규칙 제공자를 참조합니다. 둘 다 사용할 수 있는 데이터가 필요하며 분류 이름도 실제로 존재해야 합니다. 인터넷에서 본 분류 이름을 규칙에 적는 것만으로 데이터가 생기지는 않습니다. 큰 규칙 설정을 가져오기 전에 데이터 형식, 업데이트 경로, 코어 지원 여부를 확인하세요. 설정은 읽히더라도 실행 중에 참조한 리소스를 찾지 못할 수 있습니다.

rule-providers:
  private-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/private-domains.yaml

rules:
  - RULE-SET,private-domains,DIRECT
  - MATCH,PROXY

위의 제공자 파일은 최상위 payload:를 사용하고 목록에 따옴표로 묶은 "+.example.com" 같은 도메인 매칭 항목을 넣을 수 있습니다. behavior: domain은 도메인 집합, ipcidr은 주소 대역 집합, classical은 지원되는 전체 규칙 항목을 대상으로 합니다. 서로 변환 없이 바꿔 쓸 수는 없습니다. 전체 규칙 항목을 도메인만 받는 목록에 잘못 넣으면 형식 오류가 나거나 예상과 다르게 매칭될 수 있습니다.

규칙 제공자는 매칭 조건을 제공하고, RULE-SET 항목은 일치한 요청을 어느 프록시 그룹으로 보낼지 정합니다. 따라서 한 도메인 목록을 여러 설정에서 사용할 수 있고 목록 내부에 모든 출구를 고정할 필요가 없습니다. 여러 집합의 범위가 겹쳐도 최상위 규칙의 순서가 우선합니다. 집합 이름이 더 구체적이라고 자동으로 우선순위가 높아지는 것은 아닙니다. 우선순위를 바꾸려면 참조 규칙의 위치를 직접 조정하세요.

연결 기록으로 매칭 결과 확인하기

트래픽이 잘못 분기되면 구체적인 연결 하나를 찾아 도메인, 대상 주소, 일치한 규칙, 최종 출구를 기록하세요. MATCH가 선택됐다면 앞선 조건에 일치하지 않았다는 뜻이지 기본 규칙이 잘못됐다는 뜻은 아닙니다. 규칙은 맞지만 출구가 잘못됐다면 프록시 그룹의 현재 선택을 확인하세요. 요청 자체가 연결 목록에 없다면 수신 및 트래픽 가로채기 문제를 다시 살펴보세요. 규칙을 조합하는 더 자세한 방법은 GEOIP·GEOSITE·RULE-SET 라우팅 실전 가이드를 참고하세요.

설정 오버라이드와 병합

오버라이드는 구독을 업데이트하면서도 로컬 설정을 유지해야 할 때 사용합니다. 구독 원문을 직접 수정하면 다음 업데이트에서 서비스 제공자의 내용으로 되돌아갈 수 있고, 실행 중 생성된 파일을 직접 수정해도 클라이언트가 재시작하면서 다시 만들 수 있습니다. 일반적으로 클라이언트가 제공하는 영구 오버라이드, 확장 설정, 병합 기능을 사용해야 합니다. 클라이언트마다 구현 방식이 다르므로 한 화면의 오버라이드 형식이 모든 코어에서 인식되는 표준 필드라고 생각하지 마세요.

최종 설정을 생성하는 주체부터 확인하세요

설정이 적용되는 과정에는 보통 구독 원문, 로컬에 저장된 설정, 클라이언트 가공 결과, 코어 실행 상태가 포함됩니다. 클라이언트가 수신 포트를 고정하거나 제어 인터페이스를 추가하고 DNS를 바꾸거나, 로드 과정에서 규칙을 넣을 수 있습니다. 구독의 설정이 적용되지 않는다고 해서 반드시 해당 필드가 지원되지 않는 것은 아닙니다. 이후 단계에서 덮어썼을 수도 있습니다. 클라이언트가 제공하는 실행 설정 미리 보기, 내보내기, 로그 메뉴를 찾아 수정 전후에 실제로 코어에 전달되는 결과를 비교하세요.

Clash Plus는 여러 플랫폼에서 사용할 클라이언트를 고를 때 우선 검토할 수 있습니다. 지원되는 설정 입력 방식은 실제 화면에서 확인하세요. 설치가 필요하면 클라이언트 다운로드 페이지에서 플랫폼에 맞는 항목을 선택하세요. Clash Verge Rev, FlClash 등의 클라이언트는 확장 설정의 이름과 실행 순서가 다를 수 있습니다. 다른 클라이언트의 버튼 이름을 그대로 따라 하거나, 로컬 규칙을 유지하려고 클라이언트가 매번 자동 생성하는 임시 파일을 수정하지 마세요.

객체 병합과 목록 병합은 다릅니다

객체 필드는 재귀적으로 병합될 수도 있고 전체가 교체될 수도 있습니다. 목록은 교체, 앞에 삽입, 뒤에 추가, 중복 제거 방식으로 처리될 수 있습니다. 예를 들어 DNS 하위 키 하나만 오버라이드했을 때 어떤 방식은 기존의 다른 DNS 필드를 보존하고, 다른 방식은 객체 전체를 다시 지정해야 합니다. 규칙 목록은 특히 주의해야 합니다. 기존 MATCH 뒤에 사용자 지정 규칙을 추가하면 파일에 규칙이 있어도 실제 매칭 기회는 없습니다.

# 지원되는 병합 방식이 있는 클라이언트의 오버라이드 예시
# 모든 코어에서 바로 사용할 수 있는 공통 필드는 아닙니다
prepend-rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
append-proxies:
  - name: 로컬 SOCKS
    type: socks5
    server: 127.0.0.1
    port: 1080

prepend-rules, append-proxies 같은 이름은 클라이언트에서 제공할 수 있는 병합 작업을 나타냅니다. 이를 일반 config.yaml의 최상위에 확인 없이 넣어서는 안 됩니다. 코어의 최종 실행 설정에는 일반적인 rules와 proxies 목록이 있어야 합니다. 현재 클라이언트에서 해당 키를 지원하지 않는다면 클라이언트 자체의 병합 메뉴나 확장 기능을 사용하세요. 같은 조각을 반복해서 붙여 넣어서는 안 됩니다.

로컬 SOCKS 조각은 해당 서비스가 지정된 주소와 포트에서 실제로 수신 중이어야 합니다. 노드 정의를 추가해도 서비스가 시작되는 것은 아닙니다. 노드를 추가한 뒤에는 화면에서 선택할 수 있도록 보통 프록시 그룹에도 넣어야 합니다. 그룹이 제공자에서 자동으로 생성된다면 로컬 노드가 포함되는지도 확인하세요. 설정에 노드가 존재하는 것과 규칙을 통해 노드에 연결할 수 있는 것은 별도로 확인해야 합니다.

변경 범위를 좁혀 유지 관리하기

장기간 설정을 관리할 때는 구독 전체를 복사해 별도로 유지하기보다 명확한 필드 몇 개만 오버라이드하세요. 전체를 복사하면 노드 변경, 프록시 그룹 조정, 규칙 리소스 업데이트까지 로컬에서 관리해야 합니다. 도메인 하나를 직결하려는 경우에는 설명 가능한 규칙 하나를 앞에 추가하고, 포트만 고정하려면 수신 포트 필드만 바꾸세요. 수정 범위가 작을수록 구독 구조가 바뀌었을 때 충돌을 발견하고 되돌리기 쉽습니다.

스크립트로 설정을 가공해야 한다면 임의의 텍스트 조각이 아니라 설정을 빌드하는 프로그램으로 다루세요. 필드가 없거나 목록이 비었거나 이름이 바뀌면 스크립트가 실패할 수 있으므로 입력 조건과 실패 동작을 명확히 해야 합니다. 인증 정보를 콘솔에 출력하지 말고 노드 목록의 고정된 인덱스에도 의존하지 마세요. 안정적인 그룹 이름이나 명확한 조건을 기준으로 처리하되, 완료 후 빈 그룹, 이름 중복, 잘못된 참조가 생기지 않았는지 확인해야 합니다.

설정이 유지되는지 확인하려면 두 차례 검증해야 합니다. 먼저 로컬 설정을 다시 불러와 이번 실행에서 올바르게 적용되는지 확인하고, 다음으로 구독을 업데이트해 로컬 변경 사항이 올바른 위치에 계속 남아 있는지 살펴보세요. 마지막으로 클라이언트를 종료했다가 다시 열어 저장된 상태가 결과에 영향을 주는지 확인합니다. 편집 직후 한 번 테스트하는 것만으로는 업데이트 과정이 정상임을 증명할 수 없습니다. 원본 구독과 로컬 오버라이드의 역할을 기록해 두면 나중에 클라이언트를 옮길 때도 설정을 재구성하기 쉽습니다.

설정 검증 및 문제 해결

검증은 세 단계로 나눠야 합니다. 파일이 파싱되는지, 코어가 시작되는지, 실제 요청이 예상한 출구를 사용하는지 확인하세요. 첫 번째 단계를 통과해도 나머지 두 단계의 성공을 보장하지 않습니다. 테스트 대상에 접근할 수 있어도 모든 앱의 트래픽이 가로채졌다는 뜻은 아닙니다. 단계를 나누면 반복해서 재설치하는 것보다 빠르게 문제를 찾을 수 있습니다. 한 번에 관련 필드 하나만 바꾸고 변경 전 설정과 재현 가능한 요청 하나를 보관해야 무엇이 달라졌는지 판단할 수 있습니다.

정적 검사를 먼저 하고 설정을 다시 불러오세요

독립형 mihomo 코어를 사용한다면 설정 검사 옵션으로 파일을 검증할 수 있습니다. 그래픽 클라이언트에서는 우선 자체 검사 및 다시 불러오기 기능을 사용하세요. 명령은 실행 파일과 설정 파일이 있는 위치에서 실행해야 하며, 프로그램 경로가 환경 변수에 없다면 실제 경로를 지정하세요. 아래 명령은 앱의 시스템 프록시를 자동으로 설정하거나 원격 노드가 온라인인지 확인하지 않습니다. 주로 파싱, 참조, 관련 설정 오류를 미리 찾는 데 사용합니다.

mihomo -t -f ./config.yaml

Windows 명령 환경에서는 프로그램 이름과 경로를 실제 실행 파일 형식으로 입력해야 할 수 있습니다. 오류 메시지가 특정 줄을 가리키더라도 해당 줄뿐 아니라 직전 목록 항목, 닫히지 않은 따옴표, 상위 계층의 들여쓰기도 확인하세요. 존재하지 않는 그룹 참조 오류라면 오류 줄만 삭제하지 말고 해당 이름의 정의와 사용 위치를 모두 검색하세요. 규칙을 바로 삭제하면 트래픽이 다른 기본 출구로 향할 수 있습니다.

연결 단계에 따라 로그를 확인하세요

설정을 다시 불러온 뒤 먼저 로드 성공 여부와 수신 포트가 열린 상태인지 확인하세요. 포트 사용 중, 권한 부족, 제공자 파일 읽기 실패는 웹 요청을 보내기 전에도 발생할 수 있습니다. 클라이언트가 시작되지 않으면 시작 시 충돌 문제 단계별 해결을 참고하세요. 코어가 작동하기 시작하면 새 요청을 보내 DNS, 규칙 매칭, 그룹 선택, 원격 연결 순으로 확인하세요. 모든 오류를 막연히 네트워크 문제라고 부르지 마세요.

로그의 시간 초과는 대상과 발생 단계에 따라 해석해야 합니다. DNS 서버 시간 초과라면 DNS 업스트림 경로를 확인하세요. 프록시 서버 연결이 시간 초과되면 노드 주소와 포트, 현재 네트워크를 살펴보세요. 프록시 연결은 성립했지만 대상 웹사이트가 시간 초과되면 서버 측 출구와 대상 접근 가능성을 확인해야 합니다. 오류 한 줄만으로 결론을 내리기보다 앞뒤 로그와 같은 시각의 연결 상세 정보를 함께 살펴보세요. 로그 읽는 방법은 실행 로그 해석 및 문제 해결 절차를 참고하세요.

최소한의 실험으로 원인을 구분하세요

수동 노드 하나를 고정하고 불필요한 자동 전환을 끈 다음 프록시를 명시적으로 지원하는 앱에서 요청을 보내세요. 이 수신 경로는 작동하는데 TUN을 켠 뒤 실패한다면 노드 비밀번호를 계속 바꾸기보다 권한, 라우팅, DNS 가로채기, 다른 가상 네트워크 카드를 확인하세요. 직결과 프록시 모두 같은 도메인을 조회할 수 없다면 DNS 경로부터 해결해야 합니다. 한 번에 조건 하나만 바꿔야 결과를 비교할 수 있습니다.

사용자 지정 규칙을 테스트할 때는 정확한 도메인 규칙 하나를 앞에 두고 새 연결을 만들어 매칭 결과를 확인하세요. 정확한 규칙은 작동하는데 큰 규칙 집합이 작동하지 않으면 집합 형식, 로드 상태, 외부 규칙 순서를 살펴보세요. 정확한 규칙도 매칭되지 않으면 요청의 호스트 이름이 예상과 같은지 확인해야 합니다. 웹페이지는 여러 도메인에 요청을 보낼 수 있으므로 첫 화면이 열린다고 페이지의 모든 리소스가 같은 출구를 사용하는 것은 아닙니다. 실제 실패한 연결을 확인하세요.

설정을 다시 불러온 뒤에도 기존 연결, DNS 캐시, 저장된 선택의 영향을 고려해야 합니다. 장시간 연결은 이전 출구를 계속 사용할 수 있고 브라우저는 기존 연결 풀을 재사용할 수 있으며 클라이언트는 이전에 저장한 그룹 선택을 복원할 수 있습니다. 조건을 초기화해 테스트하려면 먼저 현재 상태를 기록한 뒤 관련 연결을 종료하고 새 요청을 보내세요. 이전 세션을 유지한 채 화면에 표시된 새 그룹 이름만 보고 모든 트래픽이 이동했다고 판단하면 서로 모순되는 결과를 얻기 쉽습니다.

설정 되돌리기와 문제 해결 정보 공유

수정에 실패하면 오류가 있는 설정에 옵션을 계속 덧붙이지 말고 가장 최근에 정상 작동한 설정으로 되돌리세요. 포트, DNS, 노드, 프록시 그룹, 규칙, 오버라이드 순으로 변경 사항을 다시 추가하면서 성공과 실패가 갈리는 지점을 기록할 수 있습니다. 도움을 요청할 때는 운영체제, 클라이언트 이름, 사용 중인 코어, 실패 단계, 관련된 최소 설정 조각을 알려주세요. 구독 주소, 비밀번호, 사용자 식별 정보, 제어 인증 정보는 먼저 삭제해야 합니다. 공개 스크린샷에서도 사이드바와 로그에 민감한 내용이 보이지 않는지 확인하세요.