Clash 설정 파일 가이드: YAML 필드, DNS, 프록시 그룹 및 규칙

YAML 구조와 파일 구분

Clash 설정 파일은 보통 YAML 형식입니다. 파일 이름은 config.yaml인 경우가 많지만, 파일 이름만으로 용도가 결정되지는 않습니다. 실제로 불러오는 파일은 클라이언트에서 선택한 설정이나 커널을 시작할 때 지정한 파일 경로에 따라 달라집니다. 이 페이지의 예제는 mihomo에서 자주 사용하는 필드를 기준으로 합니다. 다른 Clash 계열 커널은 일부 필드만 지원할 수 있으며, 클라이언트가 시작 전에 별도의 실행 설정을 생성하기도 합니다. 문제를 확인할 때는 먼저 커널 이름, 설정 출처, 최종 로드 경로를 파악한 뒤 해당 필드가 적용되는지 살펴보세요.

맵, 목록 및 들여쓰기

YAML 맵은 키와 값으로 설정을 표현합니다. 예를 들어 mode: rule과 같습니다. 목록은 각 항목을 하이픈으로 시작하며, rules에 여러 규칙을 나열하는 식입니다. 최상위 필드는 줄의 맨 앞에서 시작하고 하위 필드는 공백으로 들여씁니다. 두 칸 들여쓰기를 일관되게 사용하는 것이 좋습니다. 들여쓰기 깊이는 항목 간 관계를 나타내며 단순한 장식이 아닙니다. nameserver를 dns와 같은 깊이에 두면 DNS 하위 항목이 아니라 별도의 최상위 키가 됩니다. 문법 분석에 성공해도 커널이 의도한 대로 사용한다는 뜻은 아닙니다.

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

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query

proxy-groups:
  - name: 기본 출구
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,기본 출구

이 설정은 구조를 확인하기 위한 직접 연결 예제로, 원격 프록시 노드는 포함하지 않습니다. 가져오면 규칙이 요청을 “기본 출구” 그룹으로 보내며, 이 그룹에는 현재 DIRECT만 있습니다. 파일 로드 여부, 포트 수신 여부, 그룹 이름 참조 여부를 확인하는 데 적합하지만 원격 프록시의 사용 가능 여부를 판단할 수는 없습니다. 다른 절의 예제 조각은 해당 필드에 병합해야 합니다. 최상위 dns가 각각 들어 있는 여러 예제를 그대로 이어 붙이지 마세요.

문자열과 데이터 형식

불리언 값은 true 또는 false로 쓰고, 포트는 정수로 지정합니다. 주소와 이름은 보통 문자열입니다. 비밀번호, 특수 기호로 시작하는 값, 콜론 뒤에 공백이 포함된 텍스트는 따옴표로 묶는 것이 좋습니다. 주석은 #으로 시작합니다. 비밀번호에 샵 기호가 있다면 올바르게 인용해야 나머지 문자열이 주석으로 처리되지 않습니다. 작은따옴표 문자열에서는 백슬래시 이스케이프를 처리하지 않지만, 큰따옴표에서는 일부 이스케이프 시퀀스를 해석합니다. 다른 형식에서 비밀번호를 복사할 때 백슬래시를 함부로 추가하거나 삭제하지 마세요.

목록의 각 노드는 보통 하나의 맵으로 구성됩니다. 노드의 name, type, server 등의 키는 모두 같은 목록 항목에 속해야 합니다. 하이픈을 빠뜨리면 새 노드가 앞 항목에 합쳐질 수 있습니다. 같은 맵에 name을 중복으로 쓰거나 최상위 필드를 반복해서 쓰면 파서가 거부하거나 나중 값이 앞선 값을 덮어쓸 수 있습니다. 중복 키를 오버라이드 수단으로 사용하지 말고 클라이언트가 제공하는 병합 기능을 사용하세요.

전체 설정과 노드 모음의 차이

전체 설정에는 포트, DNS, 노드, 프록시 그룹 및 규칙이 포함될 수 있습니다. 반면 프록시 모음 파일은 보통 proxies 목록만 제공합니다. 규칙 모음에도 별도의 payload 구조가 있습니다. 모두 YAML을 사용할 수 있지만 서로 다른 위치에 로드해야 합니다. 구독 주소에서 유효한 YAML이 반환되더라도 이를 주 설정으로 바로 가져올 수 있다는 뜻은 아닙니다. 단일 노드 URI, Base64 텍스트 또는 로그인 페이지가 반환된다면 들여쓰기를 계속 수정하기 전에 구독 형식부터 확인하세요.

편집 전에 원본 파일을 복사해 두고, 편집기는 UTF-8을 사용하며 공백 문자를 표시하도록 설정하세요. 먼저 최소한의 로드 가능한 구조를 유지한 다음 DNS, 노드, 프록시 그룹, 규칙 순으로 내용을 추가합니다. 한 번에 한 영역만 수정하면 오류가 생겼을 때 되돌릴 범위를 분명하게 파악할 수 있습니다. 온라인 YAML 서식 도구를 필수 절차로 여기지 마세요. 설정에는 구독 주소나 인증 정보가 포함될 수 있으므로 로컬 편집과 로컬 문법 검사가 더 적합합니다.

포트, 모드 및 접근 범위

공통 필드는 커널이 요청을 받는 방식, 라우팅 모드, 접근 허용 대상을 결정합니다. 먼저 세 가지 연결 방식을 구분하세요. 앱이 HTTP 또는 SOCKS 포트로 직접 프록시 요청을 보내는 방식, 시스템 프록시 설정으로 해당 설정을 지원하는 앱을 포트에 연결하는 방식, 가상 네트워크 인터페이스를 통해 라우팅 조건에 맞는 트래픽을 처리하는 TUN 방식입니다. 수신 포트를 활성화해도 시스템 프록시가 자동으로 설정되지는 않으며, 시스템 프록시를 켜도 모든 프로그램이 이를 따르는 것은 아닙니다. 연결 경로를 확인하려면 앱이 실제로 어떤 프록시 방식을 사용하는지 살펴보세요.

port, socks-port 및 mixed-port

필드	주요 용도	설정 범위
`port`	HTTP 프록시 포트	HTTP 요청 및 CONNECT 터널 지원
`socks-port`	SOCKS 프록시 포트	앱에서 해당 프록시 프로토콜을 선택해야 함
`mixed-port`	HTTP와 SOCKS 통합 포트	하나의 포트로 두 종류의 요청 수신
`redir-port`	투명 전달 포트	시스템 리디렉션 규칙 필요
`tproxy-port`	TProxy 투명 프록시 포트	시스템 지원 및 정책 라우팅 필요

일반적인 데스크톱 사용에서는 mixed-port만 설정하면 앱과 포트의 연결 관계를 단순하게 유지할 수 있습니다. 같은 주소에서 여러 수신 필드가 동일한 포트를 사용하지 않도록 하세요. 다른 클라이언트나 이전 커널 프로세스가 이미 포트를 점유했는지도 확인해야 합니다. 포트를 변경해도 앱에 직접 입력한 프록시 주소가 자동으로 바뀌지는 않습니다. 클라이언트가 관리하는 시스템 프록시 설정은 함께 변경될 수 있지만, 시스템 설정에서 호스트와 포트가 현재 인스턴스와 일치하는지 확인하세요.

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

allow-lan 및 bind-address

allow-lan: false는 로컬 기기에서만 접속하는 경우에 사용합니다. LAN 기기에 프록시를 제공하려면 true로 설정하고 적절한 bind-address를 지정하세요. 127.0.0.1에 바인딩하면 로컬 IPv4 루프백 요청만 받으며, "*"에 바인딩하면 수신 범위가 넓어집니다. 접근 가능 여부는 수신 범위, 운영체제 방화벽, 라우터 격리 및 클라이언트 인증에 따라 달라집니다. 불리언 값 하나만 바꿔서는 휴대전화나 TV의 연결을 보장할 수 없습니다.

LAN 기기에서는 커널이 실행 중인 컴퓨터의 주소를 입력해야 하며, 해당 기기 자신의 127.0.0.1을 입력하면 안 됩니다. 컴퓨터 주소는 DHCP 임대가 갱신되면 바뀔 수 있으므로 라우터에서 주소 예약을 설정하면 변경을 줄일 수 있습니다. 공유할 때는 신뢰할 수 있는 네트워크 대역만 허용하고 프록시 포트를 공인 인터넷에 노출하지 마세요. 자세한 설정과 방화벽 확인은 mixed-port와 allow-lan으로 LAN 공유하기를 참고하세요. 공유용 포트와 관리용 포트는 별도로 제한해야 합니다.

mode 및 로그 수준

mode: rule은 rules 순서에 따라 대상을 선택하고, global은 전역 그룹에서 대상을 선택하며, direct는 직접 연결을 사용합니다. 문제 범위를 좁힐 때 모드를 바꿔 볼 수 있지만, 전역 모드에서 접속된다고 해서 규칙 모드의 문법이 잘못됐다고 단정할 수는 없습니다. 특정 규칙이 다른 출구를 선택한 것일 수도 있습니다. 규칙 모드에서는 내부망 요청, 지정 도메인, 기본 요청에 서로 다른 대상을 사용할 수 있으므로 규칙 순서를 관리해야 합니다.

일반적으로 log-level은 info를 사용하고, 문제를 찾을 때는 잠시 debug로 변경할 수 있습니다. 상세 로그에는 접속 도메인, 연결 대상 또는 구독 관련 정보가 포함될 수 있으므로 장기간 공개적으로 보관하지 마세요. ipv6: false는 커널의 관련 IPv6 동작을 제어하지만 운영체제의 모든 IPv6 네트워크 기능을 자동으로 끄지는 않습니다. DNS 하위 항목에도 별도의 ipv6 설정이 있습니다. 두 설정은 트래픽이 들어오는 경로를 함께 고려해야 하며, 이 설정만으로 기기 전체의 IPv6가 차단됐다고 볼 수는 없습니다.

TUN의 enable, auto-route, auto-detect-interface, dns-hijack 설정은 권한, 네트워크 인터페이스 및 시스템 라우팅과 관련됩니다. 설정 문법이 비슷하다고 해서 모든 플랫폼의 설치 절차까지 같은 것은 아닙니다. 먼저 빠른 시작 안내에 따라 일반 프록시 포트가 정상 작동하는지 확인한 뒤 TUN을 활성화하세요. 그렇지 않으면 포트, 권한, DNS 문제가 한꺼번에 발생해 원인을 구분하기 어렵습니다.

DNS 및 Fake-IP

dns는 별도의 맵 영역입니다. enable은 내장 DNS 사용 여부를, listen은 수신 주소를, enhanced-mode는 향상된 DNS 모드를 지정합니다. DNS를 활성화해도 시스템 DNS, TUN 하이재킹 또는 다른 전달 설정에 따라 실제 쿼리가 커널에 도달하지 않을 수 있습니다. 수신 주소를 설정해도 그 주소로 쿼리가 들어오지 않으면 커널은 해당 쿼리의 도메인 매핑을 만들 수 없으며, 앱이 자체적으로 사용하는 암호화 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
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - "*.lan"
    - "localhost"
  nameserver-policy:
    "+.lan": 192.168.1.1

예제의 192.168.1.1은 로컬 이름을 확인할 수 있는 라우터를 가정합니다. 실제 네트워크가 다르면 알맞은 주소로 바꾸세요. nameserver는 일반 업스트림 목록이며, 사용할 수 있는 주소 형식은 커널에 따라 달라집니다. 예제에서는 HTTPS DNS를 사용합니다. 업스트림 주소 자체에 호스트 이름이 포함된 경우 그 이름을 먼저 확인해야 하며, default-nameserver는 이런 초기 DNS 조회에 자주 사용됩니다. 초기 조회가 아직 설정되지 않은 같은 프록시 경로에 의존하면 시작 단계에서 순환 참조가 발생할 수 있습니다.

nameserver-policy는 도메인별로 DNS 서버를 지정해 LAN 도메인을 로컬 DNS에 전달하는 데 적합합니다. 이는 쿼리를 전달할 서버를 정하는 설정이며 rules에서 연결 출구를 선택하는 것과는 다릅니다. fallback과 fallback-filter는 결과 선택에 관여할 수 있지만, 단순히 “첫 번째 서버가 실패하면 두 번째 서버에 조회”하는 기능은 아닙니다. 명확한 분기 요구가 없다면 공용 업스트림을 여러 개 추가하기보다 경로를 설명하기 쉬운 DNS 체인 하나부터 관리하는 편이 검증하기 좋습니다.

Fake-IP와 redir-host의 차이

fake-ip 모드에서는 커널이 예약된 주소 풀에서 만든 가상 주소를 앱에 반환하고, 매핑 정보를 이용해 도메인을 복원한 뒤 출구를 선택할 수 있습니다. 이 주소는 대상 웹사이트의 실제 주소가 아니므로 명령줄에서 198.18로 시작하는 결과가 보인다고 해서 반드시 DNS 오류인 것은 아닙니다. redir-host는 실제 DNS 응답을 주로 사용합니다. 두 모드 모두 올바른 트래픽 유입 경로와 도메인 정보가 필요합니다. 앱 호환성, DNS 경로, 투명 프록시 방식에 따라 적절한 모드를 선택하세요.

fake-ip-filter는 일부 로컬 이름이나 특수한 검증이 필요한 서비스처럼 가상 주소를 반환하기에 적합하지 않은 도메인을 제외합니다. 앱 전체의 트래픽을 직접 연결로 바꾸거나 라우팅 규칙을 자동으로 수정하는 기능은 아닙니다. 호환성 문제가 있다면 먼저 특정 도메인 하나만 제외해 동작을 비교하고, 흔한 접미사를 모두 필터 목록에 추가하지 마세요. 제외 범위가 지나치게 넓으면 트래픽마다 DNS 경로가 달라져 이후 관리가 어려워집니다.

노드 DNS 조회와 규칙 DNS 조회

프록시 서버의 도메인은 프록시에 연결하기 전에 먼저 확인해야 합니다. mihomo의 proxy-server-nameserver로 이 조회에 사용할 업스트림을 지정할 수 있으며, DNS 연결에도 규칙을 적용하려면 respect-rules가 관련될 수 있습니다. 이 설정 조합에서는 프록시 서버 도메인의 조회가 다시 해당 프록시에 의존하는 순환을 피해야 합니다. 복잡한 DNS 분기 설정을 복사하기 전에 일반 직접 연결 업스트림으로 노드 주소가 확인되는지 살펴보고, DNS 출구 규칙을 단계적으로 추가하세요.

IP 규칙은 대상 주소가 특정 대역에 속하는지 판단하기 위해 도메인을 조회해야 할 수 있습니다. 규칙의 no-resolve는 해당 IP 규칙의 일치 여부를 확인하기 위한 추가 조회를 막지만, 앱이 이미 보낸 DNS 쿼리까지 차단하지는 않습니다. DNS 유출을 확인하려면 시스템 DNS, 앱 내장 DoH, 커널 업스트림, 프록시 측 DNS를 각각 살펴봐야 합니다. 브라우저에 표시된 DNS 주소 하나만으로 기기의 모든 쿼리가 같은 경로를 이용한다고 판단할 수는 없습니다.

검증할 때는 일반 도메인 하나를 조회하고, 이어서 로컬 도메인을 조회한 다음 해당 서비스에 연결해 보세요. 일반 도메인은 되지만 로컬 이름이 실패하면 로컬 DNS 정책과 필터를 먼저 확인하세요. 모든 쿼리가 시간 초과되면 수신 주소, 포트, 방화벽, 업스트림 연결을 점검하세요. DNS 응답을 받는 단계와 앱 연결은 서로 다릅니다. DNS 조회가 실패한 상황에서 노드 프로토콜 매개변수를 먼저 바꾸지 마세요.

프록시 노드 필드

proxies는 정책 그룹에서 참조할 수 있는 출구 목록입니다. 공통 필드에는 보통 name, type, server, port가 포함되며 인증 및 전송 필드는 프로토콜에 따라 달라집니다. 노드 이름은 설정에서 사용하는 참조 식별자이지 단순한 표시용 메모가 아닙니다. 이름을 바꾸면 프록시 그룹의 같은 이름 참조도 함께 수정해야 합니다. 서로 다른 노드가 같은 이름을 사용하지 않도록 고유한 이름을 지정하세요. 그렇지 않으면 어떤 노드가 선택됐는지 파악하기 어렵습니다.

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

type은 커널이 나머지 매개변수를 어떤 프로토콜로 해석할지 결정합니다. 예를 들어 Shadowsocks에는 cipher와 password가 필요하고, Trojan은 비밀번호와 TLS 설정을 사용합니다. VMess와 VLESS는 각각 고유한 ID 및 전송 매개변수를 사용합니다. type만 다른 프로토콜로 바꾼다고 변환이 완료되는 것은 아닙니다. 서버 프로토콜, 인증 방식, 전송 계층, TLS 설정을 실제 서버 설정에 맞춰야 합니다. 필요한 매개변수는 서비스 제공자에게 확인하세요.

proxies:
  - name: SS-예제
    type: ss
    server: 192.0.2.10
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

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

여기서는 문서용 예약 주소와 예시 도메인을 사용하므로 필드 구조만 보여 주며 실제로 연결할 수 있는 서비스는 아닙니다. 실제로 사용할 때는 서버 주소, 인증 정보, TLS 호스트 이름을 모두 올바른 값으로 바꾸세요. server에는 IP 또는 도메인을 쓸 수 있고, port는 서버의 수신 포트로 로컬 mixed-port와 다릅니다. 서버에 도메인을 쓰면 연결 전에 노드 도메인 조회가 필요하며, 서버에 IP를 써도 TLS 호스트 이름을 별도로 지정해야 할 수 있습니다.

TLS, SNI 및 인증서 검증

Trojan에서는 TLS 핸드셰이크에 사용할 서버 이름을 sni로 지정하는 경우가 많습니다. 다른 프로토콜은 servername 등의 필드를 사용할 수 있으므로 프로토콜 정의에 맞춰 입력하세요. TLS 호스트 이름은 서버 인증서 및 배포 방식과 일치해야 합니다. 웹사이트 도메인을 임의로 넣지 마세요. skip-cert-verify: false는 인증서 검증을 유지합니다. 인증서 오류가 발생하면 검증을 건너뛰는 방식으로 해결하려 하지 말고 시스템 시간, 호스트 이름, 인증서 체인을 먼저 확인하세요.

WebSocket 요청 경로와 Host 헤더, gRPC 서비스 이름은 각각 별도의 전송 설정입니다. 서버가 WebSocket을 요구한다면 클라이언트에도 적절한 network와 ws-opts가 필요합니다. 경로의 대소문자와 슬래시도 라우팅에 영향을 줄 수 있습니다. 기존 URI를 YAML로 변환한 뒤에는 이런 세부 항목을 하나씩 확인하세요. 링크에서 인코딩된 문자를 올바르게 디코딩해야 합니다. 비밀번호나 경로를 잘못 디코딩하면 설정은 로드되지만 핸드셰이크가 실패할 수 있습니다.

UDP 및 연결 경로 지원

udp: true는 해당 필드를 지원하는 프로토콜에서 관련 UDP 기능을 활성화하지만, 전체 연결 경로에서 UDP가 전달된다고 보장하지는 않습니다. 앱의 연결 방식, 프록시 프로토콜, 서버 설정, 방화벽, 통신사 네트워크가 모두 제한 요소가 될 수 있습니다. 웹 TCP 요청은 되지만 실시간 통신이 실패하면 먼저 앱이 UDP를 지원하는 연결 경로를 실제로 사용하는지 확인한 뒤 노드 설정을 살펴보세요. HTTP 테스트 하나가 성공했다고 해서 DNS, QUIC 또는 게임 트래픽도 정상이라고 볼 수는 없습니다.

일부 프로토콜에는 ALPN, 클라이언트 지문, Reality 또는 기타 전용 매개변수가 사용됩니다. 지원되는 필드는 커널 구현에 따라 다르며, 오래된 클라이언트는 YAML을 받아들이더라도 해당 프로토콜을 지원하지 않을 수 있습니다. 알 수 없는 필드나 지원하지 않는 유형이 있으면 클라이언트를 바꾸기 전에 커널 지원 여부부터 확인하세요. 다운로드 페이지에서 Clash Plus 또는 플랫폼에 맞는 다른 클라이언트를 선택할 수 있습니다. 설정을 통과시키려고 낯선 필드를 삭제하지 마세요. 서버에서 요구하는 인증이나 전송 방식이 달라질 수 있습니다.

고정된 출구가 몇 개뿐이라면 노드를 직접 관리해도 됩니다. 노드가 자주 바뀐다면 프록시 모음에서 일괄 관리하고 그룹이 이를 참조하게 하세요. 구독에서 생성된 노드 이름을 매번 직접 수정하면 다음 새로고침 때 원래 이름으로 돌아갈 수 있습니다. 형식 변환 후 문제가 발생했다면 YAML 구독과 노드 링크 형식 안내를 참고해 인증, 전송, TLS 매개변수가 모두 유지됐는지 확인하세요.

프록시 그룹과 노드 모음

proxy-groups는 출구 선택 로직을 정의하고, proxy-providers는 노드 모음의 출처를 지정합니다. 두 기능의 역할은 다릅니다. 노드 모음은 후보를 제공하고 프록시 그룹은 후보 중에서 선택하는 방법을 결정합니다. 규칙에서는 자주 바뀌는 노드 이름 대신 안정적으로 유지할 그룹 이름을 참조하는 것이 좋습니다. 노드가 갱신되어도 그룹 이름과 모음 참조가 유효하다면 규칙을 하나씩 수정할 필요가 없습니다. 그룹이 다른 그룹을 참조할 수도 있지만 자기 자신을 참조하거나 순환 참조가 생기지 않도록 하세요.

select, url-test 및 fallback

select는 사용자나 관리 인터페이스에서 구성원을 선택하므로 출구를 직접 제어하기에 적합합니다. url-test는 지정한 URL의 테스트 결과에 따라 자동으로 선택하며, fallback은 일반적으로 구성원 순서에 따라 사용 가능한 항목을 선택합니다. load-balance는 지원되는 부하 분산 정책에 사용되며, 하나의 연결을 여러 경로로 나눠 대역폭을 합치는 기능은 아닙니다. 유형마다 해결하는 문제가 다르므로 “자동”이라는 이유만으로 모든 분기 그룹을 자동 테스트 방식으로 바꾸지 마세요.

proxy-groups:
  - name: 기본 출구
    type: select
    proxies:
      - 자동 선택
      - 장애 조치
      - DIRECT

  - name: 자동 선택
    type: url-test
    use:
      - 직접 관리 노드
    url: https://cp.cloudflare.com/generate_204
    interval: 300
    tolerance: 50

  - name: 장애 조치
    type: fallback
    use:
      - 직접 관리 노드
    url: https://cp.cloudflare.com/generate_204
    interval: 300

proxy-providers:
  직접 관리 노드:
    type: file
    path: ./providers/nodes.yaml
    health-check:
      enable: true
      url: https://cp.cloudflare.com/generate_204
      interval: 300

예제를 사용하려면 작업 디렉터리에 providers/nodes.yaml이 있어야 하며, 이 파일에는 proxies 목록이 들어 있어야 합니다. use는 provider 이름인 “직접 관리 노드”를 참조합니다. 파일 이름이나 특정 노드를 가리키는 것이 아닙니다. proxies 목록은 기존 노드, 다른 그룹 또는 내장 출구를 직접 참조합니다. 두 참조 방식을 함께 사용할 수 있지만, 후보 모음에 실제 항목이 있는지 확인해야 합니다. 비어 있으면 자동 그룹에 선택 가능한 구성원이 없을 수 있습니다.

테스트 매개변수의 의미

url은 상태 확인 요청의 대상을 지정하고, interval은 보통 초 단위로 테스트 간격을 설정합니다. tolerance는 해당 자동 선택 로직에서 작은 차이 때문에 선택이 자주 바뀌는 것을 줄이는 데 사용됩니다. 테스트 결과는 지정한 대상까지 요청을 보낸 결과일 뿐, 모든 웹사이트, 장시간 연결 또는 대용량 전송 성능을 나타내지는 않습니다. 대상 사이트가 요청을 차단하거나 TLS 핸드셰이크 또는 DNS에 문제가 있으면 프록시 서버 포트에 연결할 수 있어도 테스트는 실패할 수 있습니다.

provider의 상태 확인과 그룹 단위 테스트는 각각 별도로 설정할 수 있습니다. 설정 전에 어떤 테스트를 노드 모음이 담당하고 어떤 테스트를 프록시 그룹이 담당하는지 정해 같은 노드를 불필요하게 자주 확인하지 않도록 하세요. 특히 모바일 기기에서는 테스트 간격을 짧게 설정할수록 기기가 더 자주 깨어나고 네트워크 요청도 늘어납니다. 그룹을 바꿔도 기존 연결이 새 노드로 즉시 이동하지는 않습니다. 전환 후에는 계속 열려 있던 다운로드 연결만 보지 말고 새 연결을 만들어 테스트하세요.

노드 모음 갱신, 필터링 및 이름 유지

HTTP 유형의 proxy-providers는 url, path, interval로 원격 출처, 로컬 캐시, 업데이트 주기를 지정합니다. 다운로드한 내용은 커널이 지원하는 노드 모음 형식이어야 하며, 아무 웹페이지나 전체 클라이언트 설정을 사용할 수 있는 것은 아닙니다. 원격 링크에 인증 정보가 있다면 로컬 설정에만 보관하고 공개 문의 글에 붙여 넣지 마세요. 구독 업데이트 오류는 구독 업데이트 실패 해결도 참고하세요. 먼저 요청 실패인지 콘텐츠 파싱 실패인지 구분해야 합니다.

그룹의 filter는 이름으로 후보를 필터링하며, 정규식 매칭 규칙에 따라 동작합니다. 이름 규칙이 바뀌면 필터 결과가 비어 있을 수 있습니다. 따라서 구독을 갱신한 뒤에는 노드 전체 목록뿐 아니라 각 그룹에 실제로 어떤 구성원이 들어 있는지도 확인하세요. 지역명, 특수문자, 대소문자가 매칭 결과에 영향을 줍니다. 간단한 조건으로 원하는 항목이 선택되는지 먼저 확인한 다음 범위를 좁혀 가면 복잡한 표현식을 한꺼번에 작성하는 것보다 관리하기 쉽습니다.

profile.store-selected는 프록시 그룹의 선택 상태를 저장하고, profile.store-fake-ip는 관련 매핑 상태를 저장할 수 있습니다. 저장이 필요한지는 사용 방식과 클라이언트의 설정 관리 로직에 따라 달라집니다. 그룹 구성원을 수정한 뒤에는 현재 선택을 다시 확인해 저장된 선택, 필터 결과, 실제 실행 설정 사이에 차이가 없는지 살펴보세요.

규칙과 규칙 모음

rules는 순서가 있는 목록입니다. 커널은 위에서 아래로 적용 가능한 규칙을 찾고, 일치하는 항목을 찾으면 해당 규칙의 출구를 사용합니다. 규칙은 “더 구체적으로 보이는” 항목이 자동으로 먼저 실행되지 않으며, 뒤쪽 도메인 규칙이 앞당겨 적용되지도 않습니다. 보통 명확한 로컬 또는 업무 예외를 먼저 두고, 범위가 넓은 도메인, 주소, 규칙 모음을 배치한 뒤 마지막에 MATCH로 기본 처리를 합니다. 순서도 설정 로직의 일부이므로 규칙을 수정할 때는 앞뒤 조건도 함께 확인하세요.

도메인, 주소 및 기본 처리 문법

rules:
  - DOMAIN,intranet.example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,기본 출구
  - DOMAIN-KEYWORD,example,기본 출구
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - RULE-SET,로컬 도메인,DIRECT
  - MATCH,기본 출구

DOMAIN은 전체 도메인과 일치하므로 단일 호스트에 적합합니다. DOMAIN-SUFFIX는 지정 도메인과 하위 도메인에 일치하고, DOMAIN-KEYWORD는 키워드 기준으로 더 넓은 범위를 매칭합니다. 키워드가 너무 짧으면 관련 없는 사이트까지 포함될 수 있습니다. IP-CIDR과 IP-CIDR6은 각각 IPv4와 IPv6 네트워크 대역에 일치합니다. 예제의 내부망 대역은 전체 목록이 아니라 문법을 보여 주기 위한 것입니다. 실제 네트워크에 맞게 보완해야 하며 완전한 사설 주소 목록으로 간주하지 마세요.

규칙 끝의 출구에는 노드 이름, 그룹 이름 또는 DIRECT, REJECT 같은 내장 대상이 올 수 있습니다. 이름은 공백과 문장 부호까지 포함해 정의된 값과 정확히 일치해야 합니다. MATCH에는 추가 조건이 없으므로 기본 처리 위치에 둬야 합니다. 목록 앞에 쓰면 대부분의 뒤쪽 규칙이 실행되지 않습니다. 업무 규칙이 적용되지 않는다면 비슷한 규칙을 더 추가하기 전에 앞선 범위가 넓은 규칙에 가로막혔는지 확인하세요.

rule-providers 선언 및 파일 형식

rule-providers는 여러 매칭 조건을 모아 재사용하는 기능입니다. type은 파일 또는 HTTP 출처를, behavior는 콘텐츠의 의미를, format은 직렬화 형식을 지정합니다. domain 모음에는 도메인 매칭 항목을, ipcidr 모음에는 주소 범위를 저장합니다. classical 모음에는 해당 형식에서 지원하는 일반 규칙 조건을 넣을 수 있습니다. 둘 다 YAML이라고 해서 프록시 노드 모음을 규칙 모음 디렉터리에 넣지 마세요. 최상위 필드와 각 항목의 구조가 서로 다릅니다.

rule-providers:
  로컬 도메인:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domain.yaml

# ./rules/local-domain.yaml 내용:
# payload:
#   - "+.lan"
#   - "intranet.example.com"

위 파일의 payload는 별도 파일의 내용입니다. 주석을 적었다고 해당 파일이 실제로 만들어지는 것은 아닙니다. 주 설정에서는 RULE-SET,로컬 도메인,DIRECT를 사용해 이 조건 모음의 출구를 지정합니다. classical 형식을 사용하면 모음 항목은 보통 조건만 설명하므로 주 설정 규칙의 출구 이름을 기계적으로 덧붙이지 마세요. 원격 모음은 다운로드와 캐시도 필요합니다. 첫 실행 때 가져오지 못하고 로컬 캐시도 없다면 먼저 리소스에 접근할 수 있도록 해결해야 합니다.

조회 시점, 프로세스 및 플랫폼 차이

일부 IP 조건은 도메인 요청과 일치하는지 확인하기 위해 DNS 조회를 발생시킬 수 있습니다. 해당 규칙에 no-resolve가 있으면 매칭을 위해 도메인을 능동적으로 조회하지 않습니다. 이미 대상 IP가 정해진 트래픽에는 적합하지만 조회 결과가 필요한 규칙은 더 이상 적용되지 않을 수 있습니다. 도메인 규칙이 적용되려면 커널에서 도메인 정보를 확인할 수 있어야 합니다. 트래픽에 대상 IP만 있고 사용할 DNS 매핑이나 스니핑 결과가 없다면 도메인 조건이 적용된다고 가정할 수 없습니다.

PROCESS-NAME 같은 프로세스 규칙은 운영체제에서 제공하는 정보와 커널 권한, 트래픽 유입 경로에 따라 사용할 수 있습니다. 데스크톱 앱에서 쓸 수 있는 프로세스 조건이 라우터 뒤에 연결된 다른 기기에도 적용되는 것은 아닙니다. GEOIP와 GEOSITE는 관련 데이터 리소스와 커널 지원이 필요하며, 데이터베이스가 바뀌면 매칭 결과도 달라집니다. 다른 플랫폼으로 옮길 때는 규칙 텍스트가 같은지만 비교하지 말고 외부 의존 항목부터 확인하세요.

규칙 파일은 용도별로 나누고 짧은 주석을 추가하세요. 예외 규칙을 테스트할 때는 특정 도메인을 대상으로 한 규칙 하나를 앞쪽에 넣고 새 연결을 만들어 적용 여부를 확인한 다음 장기적으로 사용할 위치를 정하세요. 새 규칙을 계속 최상단에 추가하는 방식으로 문제를 영구 해결하지 마세요. 우선순위를 정한 이유를 나중에 파악하기 어렵고, 범위가 넓은 규칙이 기존 분기 로직을 가릴 수 있습니다.

구독, 오버라이드 및 병합

클라이언트에서 “구독 설정”으로 보이는 내용이 커널이 실제로 읽는 최종 파일과 항상 같은 것은 아닙니다. 일반적인 처리 과정은 원격 문서를 다운로드하고 구독 사본을 저장한 다음 로컬 오버라이드나 스크립트를 적용하고, 인터페이스에서 제어하는 포트와 TUN 설정을 더한 뒤 실행 설정을 생성하는 방식입니다. 클라이언트마다 단계 이름과 실행 순서는 다를 수 있습니다. “파일을 수정했는데 설정이 바뀌지 않는다”면 다운로드 캐시를 계속 편집하기보다 실행 설정이나 설정 미리보기에서 최종 필드를 확인하세요.

원본 파일, 저장 설정 및 실행 결과 구분

원본 파일은 구독에서 제공한 내용을 보관하고, 로컬 오버라이드는 기기별 설정을 표현하며, 실행 설정은 두 항목과 클라이언트 설정을 조합한 결과입니다. 각 단계에 동일한 mixed-port, dns, tun 설정이 있을 수 있고, 인터페이스의 스위치가 더 높은 우선순위를 가질 수도 있습니다. 파일 이름만 보고 우선순위를 추측하지 마세요. 클라이언트 문서를 확인하거나 포트 또는 로그 수준 하나만 바꾸고 다시 생성한 뒤 실행 결과를 확인하세요.

Clash Plus, Clash Verge Rev, FlClash 등은 설정 관리 인터페이스가 서로 다르므로 설정 가져오기, 확장, 병합 메뉴를 실제 클라이언트에서 확인해야 합니다. 클라이언트를 바꿀 때 특정 클라이언트 전용 확장 스크립트를 일반 mihomo 필드처럼 사용하지 마세요. 커널이 읽는 것은 최종 설정이며 이를 생성하는 방식은 클라이언트가 담당합니다. 클라이언트 선택과 플랫폼 지원은 클라이언트 선택 가이드에서 확인하고, 처음 설정할 때는 빠른 시작 안내를 따라 하세요.

맵 병합 및 목록 대체

맵은 키별로 덮어쓸 수 있지만 목록은 전체 대체되거나 앞이나 뒤에 추가될 수 있습니다. 구체적인 동작은 병합 도구에 따라 다릅니다. 예를 들어 dns를 재귀적으로 병합하면 nameserver만 바꾸고 다른 하위 키를 유지할 수 있지만, 얕은 병합에서는 DNS 영역 전체가 새 내용으로 대체될 수 있습니다. rules 목록을 대체하면 구독에 포함된 분기 규칙이 모두 사라질 수 있습니다. “병합”이라는 말만 보고 기존 값이 보존된다고 판단하지 마세요.

# YAML 오버라이드를 지원하는 클라이언트에서 사용;
# 재귀 병합 여부는 해당 클라이언트의 규칙을 확인하세요.
log-level: info

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

dns:
  enable: true
  nameserver:
    - https://dns.alidns.com/dns-query

이 오버라이드를 적용한 뒤 기존 dns.listen, enhanced-mode, 필터 목록, DNS 정책이 그대로 있는지 확인하세요. 결과가 예상과 다르면 중복 필드를 계속 추가하기보다 병합 방식을 조정해야 합니다. 규칙이 앞이나 뒤 어디에 들어가는지도 확인하세요. 기존 MATCH 뒤에 일반 규칙을 추가해도 보통 의도한 분기가 적용되지 않으며, 범위가 넓은 규칙을 앞에 두면 기존 업무 예외가 가로막힐 수 있습니다.

구독 갱신과 로컬 수정 보호

다운로드된 구독 파일을 직접 수정하면 새로고침할 때 원격 내용으로 덮어써질 수 있습니다. 로컬 DNS, LAN 규칙, 포트 설정처럼 계속 유지해야 하는 값은 클라이언트가 지원하는 로컬 저장 영역에 두세요. 직접 관리하는 노드 모음과 규칙 모음도 별도 경로를 사용하고 구독 캐시와 같은 파일을 공유하지 마세요. 여러 HTTP provider가 같은 캐시 경로를 사용하면 서로의 내용이 덮어써져 노드가 갑자기 사라지거나 잘못된 구조로 파싱될 수 있습니다.

구독 형식을 변환해도 모든 필드가 그대로 보존되는 것은 아닙니다. 단일 노드 URI에는 전체 DNS, 규칙, 그룹 설정을 담을 수 없는 경우가 많습니다. 전체 YAML을 노드 링크로 변환하면 최상위 설정이 사라질 수 있습니다. 변환한 뒤에는 프로토콜, 인증, 전송 설정을 먼저 비교하고, 이어서 그룹과 규칙이 변환기에서 새로 생성됐는지 확인하세요. 비공개 구독을 변환할 때 출처를 알 수 없는 온라인 서비스에 전체 링크를 넘기지 마세요. 신뢰할 수 있는 로컬 도구나 서비스 제공자가 안내한 형식을 우선 사용하세요.

되돌릴 수 있는 업데이트 절차

업데이트 전에 현재 작동하는 설정과 로컬 확장을 저장하고, 현재 선택한 설정 이름을 기록하세요. 새로고침 후에는 문법 검사를 실행하고 프록시 그룹 구성원과 규칙 대상을 확인한 뒤 새 연결을 만들어 테스트합니다. 다운로드는 성공했지만 로드에 실패했다면 반환된 내용이 웹페이지, 오류 메시지 또는 다른 구독 형식으로 바뀌었는지 비교하세요. 로드는 성공했지만 동작이 달라졌다면 원본 구독만 보지 말고 실행 설정을 비교해야 합니다. 시간 초과, 만료된 링크, 자동 업데이트 간격에 대해서는 구독 업데이트 문제 해결을 참고하세요.

설정 차이를 공유해야 한다면 관련 필드와 민감 정보를 가린 참조 관계만 남기세요. DNS 하위 키 하나를 설명하기 위해 실행 설정 전체를 올리지 마세요. 노드 비밀번호, 관리 인증 정보, 원격 구독 자격 증명이 포함될 수 있습니다. 관련 없는 규칙이 많은 전체 파일보다 재현 가능한 최소 예제가 더 정확한 진단에 도움이 됩니다.

검증, 로그 및 문제 해결 절차

설정 검증은 정적 구조 확인에서 실제 연결 테스트 순으로 진행하세요. 처음부터 모드, 노드, DNS를 한꺼번에 바꾸지 마세요. 먼저 커널이 파일을 받아들이는지 확인하고, 요청이 올바른 포트로 들어오는지 확인한 다음 규칙 적용과 노드 연결을 살펴봅니다. 단계마다 한 가지 문제만 제외하고 입력, 결과, 변경 사항을 기록하세요. 전체 설정에 사용 가능한 노드가 여럿 있어도 현재 그룹이 선택한 노드가 동작한다는 보장은 없습니다. 클라이언트 인터페이스에 실행 중이라고 표시돼도 실제 요청 테스트를 대신할 수는 없습니다.

먼저 파일을 확인한 뒤 실행하기

mihomo를 직접 실행하는 경우 설정 테스트 옵션을 사용할 수 있습니다. 명령의 디렉터리 경로는 실제 작업 디렉터리로 바꿔야 합니다. 상대 경로로 지정한 provider와 캐시 경로는 작업 디렉터리의 영향을 받습니다. GUI 사용자는 클라이언트 내장 검사, 미리보기, 로그 기능을 우선 사용하고 같은 포트를 점유할 수 있는 두 번째 인스턴스를 실행하지 마세요. 설정 검사를 통과한 뒤에도 시작 로그에서 수신 실패나 리소스 로드 오류가 있는지 확인해야 합니다. 이런 문제는 정적 검사에서 발견되지 않을 수 있습니다.

# 설정 및 리소스가 있는 디렉터리에서 실행
mihomo -t -d . -f ./config.yaml

# 로컬 HTTP 프록시 포트로 요청 보내기
curl -I --proxy http://127.0.0.1:7890 https://example.com

# SOCKS를 사용하고 도메인 조회를 프록시 측에 맡기기
curl -I --proxy socks5h://127.0.0.1:7890 https://example.com

두 curl 요청은 DNS 조회 경로가 다를 수 있으므로 동일한 테스트로 간주하면 안 됩니다. socks5h는 프록시가 호스트 이름을 처리하도록 하며, 일반 socks5는 보통 로컬에서 먼저 조회합니다. Windows 터미널에서 curl이 다른 명령으로 연결되어 있다면 실제 curl 프로그램을 명시적으로 실행하세요. HTTP 오류 상태가 표시돼도 프록시에 연결할 수 없다는 뜻은 아닙니다. 웹사이트의 요청 거부, 프록시 인증 실패, 기본 연결 실패를 구분해야 합니다.

오류 발생 단계별로 범위 좁히기

증상	먼저 확인할 항목	다음 단계
YAML 파싱 오류	오류 줄 주변의 들여쓰기, 따옴표 및 목록	먼저 파싱 가능한 구조로 복구
프록시 또는 그룹이 없음	이름 참조 및 provider 로드 여부	최종 설정에서 실제 구성원 확인
수신 주소를 이미 사용 중	이전 프로세스, 다른 클라이언트, 포트 충돌	충돌하는 인스턴스를 종료하거나 포트 통일
DNS 조회 시간 초과	조회 경로, 업스트림 및 초기 DNS 조회	단일 DNS 경로로 테스트
TLS 핸드셰이크 실패	시간, 호스트 이름, 인증서 및 전송 매개변수	서버 요구 사항에 따라 하나씩 확인
요청이 잘못된 출구로 전달됨	모드, 일치한 규칙 및 그룹 내 선택	새 연결을 만들어 재테스트

오류 행 번호는 처음 잘못된 위치가 아니라 파서가 중단된 위치를 가리킬 때도 있습니다. 해당 줄뿐 아니라 바로 앞 줄에서 따옴표나 콜론이 빠졌는지도 살펴보세요. 알 수 없는 프록시 이름은 대개 참조 문제이므로 네트워크부터 조정할 필요는 없습니다. 연결 시간 초과는 대상에 따라 구분해야 합니다. 구독 서버, 노드 서버, 대상 웹사이트 중 어디서 시간 초과가 발생했는지 확인하고 각각 다운로드 경로, 프록시 경로, 웹사이트 경로를 따라 점검하세요.

로그 기록과 최소 재현

debug를 잠시 활성화한 뒤 대상 요청 하나만 재현하고 시간, 대상, 일치한 규칙, 최종 출구를 기록한 다음 일반 로그 수준으로 되돌리세요. TUN, 시스템 프록시, 앱에서 직접 설정한 프록시 등 여러 연결 경로가 있다면 먼저 하나만 사용해 비교하세요. 브라우저 연결 풀, 백그라운드 서비스, DNS 캐시 때문에 기존 연결이 계속 유지될 수 있습니다. 중요한 설정을 바꿀 때마다 새 요청 프로세스를 사용하거나 테스트 앱을 재시작해 이전 상태를 보고 혼동하지 않도록 하세요.

최소 재현 설정에는 확인된 노드 하나, 직접 선택하는 그룹 하나, 테스트 도메인 규칙 하나, 마지막 기본 규칙을 남길 수 있습니다. 최소 설정에서 문제가 없으면 DNS 정책, 규칙 모음, 자동 선택, 로컬 오버라이드를 차례로 복원하세요. 모든 규칙을 한꺼번에 삭제한 뒤 규칙이 문제라고 단정하지 마세요. 삭제 과정에서 DNS 조회 시점이나 기본 출구가 바뀌었을 수도 있습니다. 어떤 변경이 결과에 영향을 줬는지 설명할 수 있도록 매 단계의 설정 차이를 보관하세요.

자주 발생하는 경계 사례

설정 검사를 통과했는데도 앱이 연결되지 않는 이유는 무엇인가요?

검사는 필드와 참조가 커널 요구 사항을 만족하는지만 확인합니다. 앱이 프록시를 사용하지 않거나 노드에 연결할 수 없을 수도 있습니다. 로컬 포트를 명시한 요청으로 먼저 테스트한 뒤 연결 기록을 확인하세요. 요청이 정상이면 앱의 프록시 설정이나 시스템 연결 경로를 점검해야 합니다.

구독을 업데이트한 뒤 수동 선택한 노드가 바뀌는 이유는 무엇인가요?

노드 이름, 그룹 구성원, 저장 상태가 바뀌었을 수 있습니다. 업데이트 후 그룹 구성원과 현재 선택을 확인하고 profile.store-selected 및 클라이언트의 저장 동작을 살펴보세요. 이전 이름이 더 이상 존재하지 않으면 저장된 선택을 계속 사용할 수 없을 수도 있습니다.

시스템 프록시는 되는데 TUN은 작동하지 않는 이유는 무엇인가요?

TUN은 추가로 권한, 가상 인터페이스, 시스템 라우팅, DNS 하이재킹에 의존합니다. 이미 검증한 노드와 규칙은 그대로 둔 채 이 조건을 하나씩 확인하세요. 이 문제를 해결하려고 노드 인증 설정을 다시 작성하지 마세요. 권한 승인과 인터페이스 관리 방식은 플랫폼 및 클라이언트 안내에 따라 다릅니다.

문제 해결이 끝나면 임시 테스트 규칙을 삭제하고 적절한 로그 수준으로 되돌린 뒤, 점검 중 LAN 접근 범위가 넓어지지 않았는지 확인하세요. 안정적으로 사용할 변경 사항은 로컬 영구 오버라이드에 반영하고 구독을 새로고침한 뒤 다시 로드해 테스트합니다. 이렇게 하면 현재 연결뿐 아니라 다음 업데이트 이후에도 설정이 예상대로 유지되는지 확인할 수 있습니다.