Clash 설정 파일
YAML 구조와 필드

YAML 구조 한눈에 보기

설정 파일은 계층 구조를 가진 텍스트이지, 설정 이름을 아무렇게나 늘어놓은 목록이 아닙니다. YAML은 들여쓰기로 상하 관계를 나타내고, 콜론으로 필드와 값을 구분하며, 하이픈으로 목록 항목을 표시합니다. 처음 보는 설정 파일은 가장 왼쪽의 최상위 필드부터 찾고, 각 필드 아래에 들여쓴 내용을 확인하세요. 이렇게 하면 전역 설정과 특정 노드에만 해당하는 설정을 구분해 올바른 위치에 값을 넣을 수 있습니다.

들여쓰기로 객체와 목록 구분하기

들여쓰기는 공백 두 칸으로 통일하고 탭은 섞지 않는 것이 좋습니다. 같은 단계의 필드는 왼쪽을 맞추고, 하위 필드는 상위 필드보다 한 단계 더 들여씁니다. 콜론 뒤에는 보통 공백을 하나 넣으며, 목록 항목의 하이픈 뒤에도 공백을 넣습니다. 편집기에서 ‘공백 문자 표시’를 켜면 눈에 보이지 않던 들여쓰기를 확인할 수 있습니다. 오류가 난 줄뿐 아니라 그 앞의 몇 줄도 살펴보세요. 따옴표 누락이나 잘못된 들여쓰기는 뒤쪽에서야 오류로 드러나는 경우가 많습니다.

# 이 필드를 지원하는 mihomo 커널에서 불러올 수 있음
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: 직접 선택
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,직접 선택

이 예제는 계층 구조만 보여 줍니다. 모든 연결은 직접 연결되며 사용할 수 있는 원격 프록시는 포함되어 있지 않습니다. 최상위 proxy-groups는 목록이고, 각 항목은 프록시 그룹 객체입니다. 객체 안의 proxies도 목록이며, 후보 출구의 이름을 담습니다. 최상위 proxies에는 프록시 노드 정의가 들어갑니다. 두 필드는 이름은 같지만 위치와 역할이 다릅니다.

설정을 참조 관계의 연결 고리로 보면 이해하기 쉽습니다. 프록시 노드가 연결 방식을 정의하고, 프록시 그룹이 노드 이름을 참조하며, 규칙이 프록시 그룹 이름을 참조합니다. DIRECT는 내장 직접 연결 출구이므로 프록시 목록에 같은 이름의 노드를 따로 만들 필요가 없습니다. 참조하는 이름은 대소문자, 공백, 문장 부호까지 정확히 일치해야 합니다. “직접 선택”을 “일반 출구”로 바꾸면 규칙의 대상도 함께 바꾸세요. 문법 검사를 통과하더라도 불러올 때 대상이 없다는 오류가 날 수 있습니다.

문자열, 불리언 값과 빈 값

특수 문자가 포함된 값은 따옴표로 감싸는 것이 좋습니다. 특히 비밀번호, 샵 기호가 포함된 이름, 날짜처럼 보이는 값에 주의하세요. 특정 위치의 샵 기호는 주석을 시작하므로 따옴표가 없으면 값이 잘릴 수 있습니다. 불리언 값은 true 또는 false로, 포트는 숫자로 입력하세요. 모양을 통일하려고 모든 값을 문자열로 쓰면 안 됩니다. []는 빈 목록을 뜻하며, 필드 이름만 있고 값이 없는 경우와는 다릅니다. 민감한 필드의 원래 문자는 그대로 유지하고, 값 안의 공백을 임의로 지우지 마세요.

같은 객체 안에 동일한 키를 중복 선언하지 마세요. 최상위 rules가 두 개 있다고 규칙이 이어지는 것은 아닙니다. 파서에 따라 불러오기를 거부하거나 한쪽 내용만 남길 수 있습니다. 다른 사람이 준 조각을 받았다면 먼저 완성된 파일인지, 상위 필드 안에 넣을 내용인지 확인한 다음 붙여넣으세요. nameserver의 하위 항목만 받았다면 파일 맨 왼쪽에 바로 넣어서는 안 됩니다.

수정하기 전에 원본 파일을 복사하고, 사본 이름에 용도를 적어 두세요. 위의 최소 구조로 들여쓰기부터 연습한 다음 실제 구독 설정을 살펴보세요. 연습용 파일을 실제 설정 파일 대신 사용하면 안 됩니다. 한 부분을 추가할 때마다 불러와 확인하면 수백 줄을 한꺼번에 붙여넣은 뒤 오류를 찾는 것보다 수월합니다. 전체 파일을 순서대로 살펴보려면 config.yaml 읽는 순서를 참고하고, 이 페이지의 다음 항목에서 필드의 의미와 주의점을 확인하세요.

포트와 실행 모드

공통 필드는 클라이언트가 트래픽을 어디서 받고, 받은 트래픽을 어떻게 처리할지 정합니다. ‘로컬 입구’와 ‘원격 출구’를 구분하세요. 로컬 포트는 브라우저나 시스템 프록시가 연결하는 곳이고, 원격 노드 포트는 서버에 연결하는 데 사용됩니다. 두 포트의 숫자가 같더라도 서로 관련은 없습니다. 앱이 실제로 로컬 입구에 요청을 보내야 이후 규칙이 판단에 참여합니다. 따라서 설정이 올바르더라도 모든 프로그램이 자동으로 프록시를 사용하는 것은 아닙니다.

입구 선택과 수신 범위 설정

port는 HTTP 프록시 입구, socks-port는 SOCKS 입구를 제공하며, mixed-port는 같은 포트에서 두 종류의 프록시 연결을 모두 받습니다. 보통 혼합 포트 하나면 데스크톱 앱의 일반적인 사용에 충분하므로, 설정을 빠짐없이 갖추겠다고 모든 포트를 열 필요는 없습니다. 예제의 숫자는 로컬에서 정한 값일 뿐입니다. 다른 프로그램이 이미 사용 중이면 비어 있는 포트로 바꾸고 시스템 프록시와 앱 설정도 함께 수정하세요.

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

allow-lan: false는 이 기기에서만 사용할 때 적합하며, bind-address는 수신 주소를 지정합니다. 루프백 주소 127.0.0.1은 현재 기기만 가리킵니다. LAN 연결을 허용하도록 바꾸더라도 수신 주소, 방화벽, 클라이언트의 덮어쓰기 설정을 확인해야 합니다. 프록시 입구를 인터넷에 직접 공개하지 마세요. 같은 LAN의 다른 기기에서 꼭 사용해야 한다면 먼저 접근 범위를 제한한 뒤, 커널이 지원하는 입구 인증 방식을 확인하세요.

규칙 모드는 연결 스위치가 아닙니다

mode: rule은 규칙 목록에 따라 요청을 처리한다는 뜻입니다. global은 보통 프록시로 들어온 트래픽을 전역 정책에 맡기고, direct는 직접 연결로 처리합니다. 전역 모드로 바꾸면 규칙이 특정 요청에 영향을 주는지 확인하는 데 도움이 될 수 있지만, 모든 문제를 해결하는 버튼은 아닙니다. 앱이 프록시 입구를 거치지 않거나 노드 자체에 연결할 수 없다면 모드를 바꿔도 이런 선행 문제는 해결되지 않습니다.

시스템 프록시와 TUN 모드는 서로 다른 계층의 기능입니다. 시스템 프록시는 시스템에 프록시 주소를 등록하며, 앱은 이 설정을 따를지 선택할 수 있습니다. TUN은 가상 네트워크 인터페이스로, 라우팅을 통해 조건에 맞는 패킷을 커널로 전달합니다. TUN은 관리자 권한, 라우팅, DNS 가로채기가 필요할 수 있고 플랫폼에 따라서도 설정 필드가 달라집니다. 처음 문제를 진단할 때는 시스템 프록시로 명확한 요청 하나를 먼저 성공시킨 뒤 사용 안내에 따라 TUN을 활성화하세요. 두 종류의 입구를 동시에 점검하는 상황을 피할 수 있습니다.

클라이언트 UI의 포트와 모드가 파일의 설정에 우선할 수 있습니다. 파일에는 규칙 모드라고 적혀 있는데 UI에는 전역으로 표시된다면 원본 파일을 계속 수정하지 말고 실행 중인 최종 설정을 확인하세요. 일부 클라이언트는 포트를 앱 수준에서 관리하므로 구독을 다시 불러와도 바뀌지 않습니다. 실제 수신 포트를 확인한 다음 브라우저나 명령에서 사용하는 주소를 점검하면, 실행 중인 다른 프록시 프로그램으로 요청이 들어가는 일을 막을 수 있습니다.

로그 수준은 평소에는 info로 두고, 문제를 찾을 때만 debug로 잠시 바꾸면 됩니다. 상세 로그는 출력량을 늘리고 대상 도메인, 주소, 연결 경로를 기록할 수 있으므로 공유 전에 민감한 정보를 확인하세요. 디버깅이 끝나면 일반 수준으로 되돌려 불필요한 기록이 쌓이지 않게 하세요. 제어 인터페이스는 커널을 관리하는 용도이지 인터넷 연결 입구가 아닙니다. 시스템 프록시에 제어 인터페이스 포트를 입력하거나, 편의를 위해 수신 범위를 함부로 넓히지 마세요.

마지막으로 IPv6을 확인하세요. 최상위 ipv6와 DNS 영역의 같은 이름 옵션은 각각 연결과 조회 동작에 영향을 주며, 실제 효과는 커널 구현에 따라 다릅니다. 예제에서 IPv6을 끈 것은 입문 단계의 점검 범위를 줄이기 위한 것이며, 모든 네트워크에서 계속 꺼야 한다는 뜻은 아닙니다. 네트워크와 프록시 출구가 IPv6을 지원한다면 기본 연결이 안정된 뒤 따로 켜서 테스트하세요. AAAA 조회 결과와 실제 출구 주소를 함께 확인해 UI의 스위치만 바뀐 것은 아닌지 살펴보세요.

DNS와 도메인 조회

DNS는 도메인 이름을 네트워크 주소로 바꾸는 과정입니다. 규칙에 도메인을 적었다고 해서 전체 연결 과정에 조회가 필요 없는 것은 아닙니다. 프록시 서버나 대상 사이트에 연결하거나 주소의 지역을 판별할 때 DNS 조회가 발생할 수 있습니다. 문제를 진단할 때는 ‘누가 조회하는지, 어디에 요청하는지, 어떤 결과를 받는지’를 먼저 확인하세요. 곧바로 시간 초과를 노드 장애로 단정하면 안 됩니다. 브라우저에 내장된 암호화 DNS가 시스템 조회 경로를 우회하면 같은 기기의 앱마다 결과가 달라질 수도 있습니다.

일반 조회와 Fake IP

enhanced-mode는 향상된 DNS 조회 모드를 선택합니다. fake-ip는 앱에 매핑용 주소를 반환하고, 커널은 매핑 정보를 통해 원래 도메인을 찾습니다. 이 주소는 웹사이트의 실제 주소가 아닙니다. 규칙에서 도메인 정보를 활용하기 쉽지만, 이후 요청이 같은 커널로 들어와야 합니다. redir-host는 주로 실제 조회 주소를 반환해 전통적인 DNS 조회 방식에 가깝게 동작합니다. 입구를 제대로 이해하지 않은 채 특정 사이트의 추천만 보고 모드를 반복해서 바꾸지 마세요.

dns:
  enable: true
  listen: "127.0.0.1:1053"
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query

이 설정은 로컬 DNS 수신 입구를 제공하지만 listen만으로 시스템 DNS가 자동 변경되거나 TUN이 자동으로 트래픽을 가로채지는 않습니다. 시스템이 계속 라우터로 요청을 보내고 있다면 커널 설정이 아직 적용되지 않았을 수 있습니다. 입구가 제대로 연결됐는지 확인하려면 클라이언트의 DNS 가로채기 설정, 시스템 네트워크 설정, 로그를 함께 살펴보세요. 표준이 아닌 포트에서 수신하는 경우 일반적인 시스템 DNS 설정에 해당 포트를 그대로 입력할 수 없으므로, 해당 입구를 지원하는 프로그램이나 가로채기 기능을 사용해야 합니다.

default-nameserver는 암호화 DNS 서비스의 도메인을 먼저 조회할 때 주로 사용합니다. 따라서 예제에서는 DNS 서버를 찾기 전에 도메인을 먼저 조회해야 하는 순환을 피하려고 IP 주소를 사용합니다. nameserver는 일반적인 상위 DNS 서버이며, 예제에서는 흔히 DoH라고 부르는 HTTPS 전송 방식을 사용합니다. 암호화된 조회도 네트워크 연결이 가능해야 하므로 모든 환경에서 바로 사용할 수 있는 것은 아니며, 프록시 노드를 대신하지도 않습니다. 상위 DNS 서버를 바꾸기 전에 현재 네트워크에서 해당 서버에 접속할 수 있는지 확인하세요.

도메인별 DNS 서버 지정

일부 도메인은 사내 DNS에만 등록된 내부 도메인처럼 특정 DNS 경로를 거쳐야 합니다. mihomo에서는 nameserver-policy를 사용해 도메인별로 상위 DNS 서버를 지정할 수 있습니다. 아래의 내부 도메인과 DNS 주소는 구조를 보여 주는 예일 뿐입니다. 실제로는 현재 네트워크에서 제공하는 값으로 바꾸고, 최상위 DNS 필드를 새로 만들지 말고 기존 dns 객체 안에 넣으세요.

# 기존 dns 객체 내부에 병합
nameserver-policy:
  "+.corp.example.com":
    - 192.168.1.1

Fake IP 필터 목록은 지정한 도메인이 가상 주소 매핑을 사용하지 않도록 하는 기능이며, 규칙의 직접 연결 목록과는 다릅니다. 도메인을 필터에 추가해도 트래픽은 계속 분기 규칙의 영향을 받습니다. LAN 기기 검색, 일부 게임 또는 실제 주소에 의존하는 프로그램에 문제가 생기면 원인이 확인된 도메인만 대상으로 필터를 테스트하세요. 모든 도메인을 필터에 추가하면 원래 사용하려던 기능을 사실상 해제하게 됩니다.

지원되는 mihomo 설정에서는 proxy-server-nameserver로 프록시 서버 도메인을 조회할 DNS 서버를 지정할 수 있습니다. 이는 웹사이트 도메인 조회와 다르며, 프록시 연결을 맺기 전에 서버 주소를 알아내기 위한 설정입니다. DNS 연결이 분기 규칙을 따르게 하는 respect-rules 같은 옵션을 사용할 때는 순환이 생기지 않는지 특히 주의하세요. DNS 조회에 프록시가 필요하고, 프록시 서버 주소를 얻으려면 다시 그 DNS 조회가 필요한 상황이 발생할 수 있습니다. 분명한 목적이 없다면 단순한 조회 경로를 유지하세요.

DNS를 확인할 때는 두 단계를 거치세요. 먼저 조회 요청이 실제로 커널에 도달하는지 확인하고, 다음으로 조회 결과를 연결에 사용할 수 있는지 살펴봅니다. Fake IP 모드에서 매핑 주소가 보이는 것은 정상일 수 있으며, 이를 원격 서버의 실제 주소로 사용하면 안 됩니다. 앱 하나에서만 문제가 생기면 앱 자체 DNS, 캐시, 프록시 연결 방식을 먼저 확인하세요. 모든 앱에서 동시에 문제가 생기면 상위 DNS 서버에 연결할 수 있는지와 DNS 가로채기 경로를 점검하세요. 조회 옵션은 한 번에 하나씩 바꿔야 어떤 부분이 영향을 줬는지 판단할 수 있습니다.

프록시 노드 필드

프록시 노드는 원격 연결에 필요한 매개변수의 모음이지, 이름만 넣으면 사용할 수 있는 태그가 아닙니다. 프로토콜에 따라 필요한 필드가 달라지고, 실제 값은 서버가 정하며, 지원 여부는 클라이언트 커널에 따라 다릅니다. 구독에 노드가 이미 있다면 원래 매개변수를 유지하고 프록시 그룹이나 규칙만 조정하세요. 암호화 방식, 전송 방식, 인증 정보를 임의로 바꿔도 보통 연결이 빨라지지 않으며 클라이언트와 서버 설정이 맞지 않을 수 있습니다.

공통 필드부터 확인

name은 프록시 그룹에서 참조할 로컬 이름이고, type은 프로토콜 식별자입니다. server는 원격 서버의 도메인이나 IP 주소, port는 서버가 수신하는 포트입니다. 이름은 용도에 맞게 정하되 고유하게 지정하고, 프록시 그룹이나 내장 출구와 같은 이름을 사용하지 마세요. 도메인 필드에는 호스트 부분만 입력하고 https://나 페이지 경로는 붙이지 않습니다. 포트도 로컬 혼합 포트를 그대로 복사하지 말고 서버 제공 정보에 따라 입력해야 합니다.

proxies:
  - name: 예시 출구
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

proxy-groups:
  - name: 직접 선택
    type: select
    proxies:
      - 예시 출구
      - DIRECT

이 예제는 예약된 테스트 도메인과 가짜 비밀번호로 Shadowsocks 노드의 구조만 보여 주며, 실제 프록시 서비스를 제공하지 않습니다. 연결하려면 정당하게 제공받은 서버 주소, 포트, 암호화 방식, 비밀번호가 필요합니다. cipher는 서버 설정과 일치해야 하며, 임의로 고르는 보안 등급이 아닙니다. 비밀번호를 복사할 때는 따옴표 안의 공백, 특수 문자, 줄바꿈에 특히 주의하세요. 화면에 비슷하게 표시되어도 실제 문자 값은 다를 수 있습니다.

프로토콜 매개변수를 섞어 쓰지 마세요

인증 필드는 프로토콜마다 다릅니다. 예를 들어 어떤 프로토콜은 비밀번호를 사용하고 다른 프로토콜은 UUID를 사용합니다. 전송 계층도 TCP, WebSocket 등으로 나뉩니다. 여러 안내서의 필드를 한데 합치면 커널이 알아서 판단할 것이라고 기대해서는 안 됩니다. 먼저 프로토콜을 확인하고, 현재 커널에서 해당 프로토콜이 사용하는 필드 정의를 읽으세요. 다른 클라이언트에서 지원되는 필드라고 해서 현재 커널도 같은 방식으로 지원하는 것은 아닙니다. 알 수 없는 필드는 무시될 수 있어 오류가 명확히 표시되지 않을 수도 있습니다.

TLS는 연결을 암호화하고 상대방의 신원을 확인하는 데 사용하는 방식입니다. servername은 핸드셰이크에서 서버 이름을 지정할 때 사용하며, 노드 표시 이름과는 다릅니다. 인증서 오류가 나면 먼저 서버 정보, 기기의 시간, 이름이 서로 맞는지 확인하세요. 인증서 검증을 끄는 방법을 장기적인 해결책으로 삼지 마세요. 잘못된 주소나 신뢰 문제를 가릴 수 있습니다. WebSocket 요청 경로와 요청 헤더도 서버 설정과 일치해야 하며, 웹사이트 첫 화면 주소만 보고 값을 추측하면 안 됩니다.

udp: true는 해당 노드의 UDP 기능을 사용할 수 있게 한다는 뜻이지, UDP를 지원하지 않는 서버에 기능을 추가하는 설정은 아닙니다. 웹 탐색은 정상인데 게임이나 음성 통화에 문제가 있으면 로컬 입구에서 UDP가 전달되는지, 프로토콜과 서버가 UDP를 지원하는지, 규칙이 요청을 올바른 출구로 보내는지 각각 확인하세요. HTTP 연결 테스트만으로 UDP 경로 전체가 정상이라고 판단할 수 없습니다. 노드가 사용 가능으로 표시되는데 앱이 작동하지 않는 흔한 원인입니다.

노드가 많으면 proxy-providers로 프록시 목록을 관리하고, 프록시 그룹에서 use로 참조할 수 있습니다. 이는 완성된 설정 파일을 반환하는 구독과 다릅니다. 프록시 제공자는 호환되는 노드 목록 구조를 기대하므로 아무 구독 주소나 입력할 수 없습니다. 원격 주소에 접근 정보가 포함될 수도 있으므로 설정을 공유할 때는 삭제하세요. 초보자는 클라이언트의 기본 구독 관리 기능을 먼저 사용하고, 노드 목록을 별도로 관리할 필요가 확인된 뒤 제공자를 도입하는 것이 좋습니다.

클라이언트를 바꿀 때는 설정 사본을 보관하고 사용할 커널과 지원 프로토콜을 확인하세요. 클라이언트 선택은 먼저 다운로드 페이지의 Clash Plus를 살펴보고, 다른 클라이언트도 기기에 맞춰 선택할 수 있습니다. 노드 정보가 서비스 제공업체에서 온 것이라면 연결 실패 시 모든 노드 이름을 바꾸기보다 원래 제공된 정보와 대조하세요. 알아보기 쉬운 이름은 로그 확인에 도움이 되지만 연결 성능을 바꾸지는 않습니다. 이름을 복잡하게 짓기보다 필드 참조를 정확하게 유지하는 것이 중요합니다.

프록시 그룹과 선택

프록시 그룹은 여러 연결 옵션 가운데 출구를 결정하는 중간 계층입니다. 규칙이 특정 원격 노드에 직접 연결되지 않아도 되고, 요청을 그룹에 전달한 다음 그룹에서 출구를 선택하면 됩니다. 노드를 바꿀 때 대개 그룹의 선택만 조정하면 되므로 모든 규칙을 다시 작성할 필요가 없습니다. 프록시 그룹은 후보 구성원, 선택 방식, 해당 그룹을 참조하는 규칙 순서로 확인하세요. 이름만 봐서는 트래픽이 최종적으로 어디로 가는지 알 수 없습니다.

수동 선택, 자동 선택과 장애 전환

select는 출구를 직접 선택하므로 사용자가 명확하게 제어해야 하는 상황에 적합합니다. url-test는 지정한 테스트 주소의 연결 결과에 따라 후보를 선택하지만, 테스트 결과는 해당 대상과 방식에 한정되며 모든 앱의 사용 경험을 나타내지는 않습니다. fallback은 후보 순서에 따라 사용할 수 있는 항목을 찾는 방식으로, 주·대체 출구가 정해진 경우에 적합합니다. 각 그룹의 용도는 다르므로 ‘자동’이라는 이유만으로 모든 트래픽을 같은 유형의 그룹에 맡기지 마세요.

proxy-groups:
  - name: 자동 후보
    type: url-test
    proxies:
      - 예시 출구
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: 일반 출구
    type: select
    proxies:
      - 자동 후보
      - 예시 출구
      - DIRECT

이 조각을 사용하려면 먼저 proxies에 “예시 출구”를 정의해야 합니다. 단독으로는 완성된 설정 파일로 불러올 수 없습니다. 테스트 간격의 단위는 초이며, tolerance는 결과가 조금 흔들릴 때 선택이 자주 바뀌지 않도록 하는 밀리초 단위의 허용 오차입니다. 테스트 주소는 안정적이고 접속 가능해야 하며 현재 네트워크에 적합해야 합니다. 예제 주소를 반드시 사용할 필요는 없습니다. 테스트 대상 자체에 접근할 수 없다면 그룹의 모든 후보가 실패하더라도 다른 대상에 모든 노드를 사용할 수 없다는 뜻은 아닙니다.

“일반 출구”가 “자동 후보”를 선택하면 내부 그룹에서 노드를 다시 선택합니다. “예시 출구”를 선택하면 해당 노드를 바로 사용하고, DIRECT를 선택하면 직접 연결합니다. 그룹에 직접 연결이 포함되어 있다면 단순한 참고 항목이 아니라 실제 선택 가능한 출구입니다. 특정 트래픽에 프록시가 반드시 필요하다면 관련 경로에 직접 연결을 실수로 남겨 두지 마세요. 적어도 현재 어떤 구성원이 선택되어 있는지는 확인해야 합니다.

참조 관계와 안정성

그룹이 다른 그룹을 참조할 수는 있지만 순환 참조를 만들면 안 됩니다. 예를 들어 “일반 출구”가 “미디어 출구”를 포함하고, “미디어 출구”가 다시 “일반 출구”를 포함하면 선택을 끝낼 경로가 없습니다. 용도별 그룹이 선택 그룹을 가리키고, 선택 그룹이 노드나 내장 출구를 가리키는 단순한 단방향 구조를 먼저 구상하세요. 계층을 추가할 때마다 이유가 있어야 합니다. UI의 분류를 보기 좋게 만들려고 중첩을 지나치게 늘리면 문제가 생겼을 때 실제 선택 항목을 단계별로 확인해야 합니다.

자동 전환은 주로 이후에 시작하는 연결에 영향을 주며, 기존 연결이 즉시 다른 출구로 옮겨간다고 보장하지 않습니다. 웹 연결 재사용이나 영상의 장시간 연결 때문에 전환 뒤에도 이전 출구를 계속 사용할 수 있습니다. 로그인, 결제, 출구 IP가 중요한 작업에는 테스트 결과를 자주 따라가는 것보다 안정적인 선택이 나을 수 있습니다. 전환 효과를 확인하려면 기존 연결을 닫고 새 요청을 보낸 뒤 연결 세부 정보에서 정책 경로를 확인하세요. 그룹 버튼의 색만 봐서는 충분하지 않습니다.

load-balance는 설정한 정책에 따라 연결을 후보에 분배하는 기능이지, 다운로드 연결 하나의 대역폭을 합산하는 기능이 아닙니다. 연결마다 출구가 달라질 수 있으며, 사이트에서 인증을 다시 요구할 수도 있습니다. 분산이 꼭 필요한 상황이 아니라면 수동 선택이나 단순한 자동 후보 그룹부터 사용하세요. 복잡한 그룹은 커널 지원뿐 아니라 후보의 가용성, 연결 유지, 서비스에서 출구 일관성을 요구하는지에 대한 이해도 필요합니다.

제공자로 노드를 가져올 때 프록시 그룹에서는 제공자 이름을 use로 참조해야 하며, 제공자를 일반 노드 이름으로 잘못 적으면 안 됩니다. 필터 옵션은 실제 후보 목록에 영향을 주므로 정규식이 잘못되면 그룹이 비어 있을 수 있습니다. 구독을 업데이트한 뒤 그룹에서 노드가 사라졌다면 제공자 업데이트 성공 여부, 필터 일치 여부, 노드 이름 변경 여부를 차례로 확인하세요. 규칙은 요청을 그룹에 전달할 뿐 그룹 구성원을 만들지 않으므로 규칙부터 삭제하지 마세요.

클라이언트는 사용자가 직접 선택한 항목을 저장할 수 있으므로 설정을 다시 불러와도 목록의 첫 번째 항목으로 돌아가지 않을 수 있습니다. 문제를 진단할 때 현재 선택을 기록하고, 필요하면 항목을 다시 명시적으로 선택한 뒤 새 요청을 보내세요. 특히 규칙, 오버라이드 파일, 클라이언트의 선택 기록이 참조하는 프록시 그룹 이름은 그대로 유지하는 것이 좋습니다. 그룹 구조를 바꿔야 한다면 원래 이름을 유지한 채 새 후보를 검증한 뒤 참조를 단계적으로 바꾸세요. 모든 그룹 이름을 한꺼번에 변경하는 것보다 되돌리기 쉽습니다.

규칙 문법과 순서

규칙 목록은 보통 위에서 아래로 판단하며, 처음 일치하는 규칙이 처리 대상을 결정합니다. 자동으로 더 ‘정확한’ 규칙을 비교하지 않으므로 규칙 내용뿐 아니라 위치도 중요합니다. 트래픽이 분기하는 강줄기의 연속된 갈림길을 떠올려 보세요. 요청은 앞쪽 규칙부터 거치며, 이미 다른 방향으로 빠진 트래픽은 아래쪽 규칙까지 도달하지 않습니다. 흔히 잘못 판단하는 문제는 범위가 넓은 앞쪽 규칙이 뒤쪽의 구체적인 규칙보다 먼저 일치하는 경우입니다.

도메인, IP 주소와 최종 대체 규칙

대부분의 규칙은 ‘유형, 일치 값, 대상’ 형식입니다. 예를 들면 DOMAIN-SUFFIX,example.com,일반 출구와 같습니다. 도메인 규칙에는 웹 주소가 아니라 도메인을 입력해야 하며 프로토콜, 포트, 경로는 포함하지 않습니다. DOMAIN은 전체 도메인과 일치하고, DOMAIN-SUFFIX는 해당 도메인 및 하위 도메인과 일치합니다. DOMAIN-KEYWORD는 도메인 문자열에 키워드가 있는지 확인합니다. 키워드 규칙은 예상보다 넓은 범위와 일치할 수 있으므로 정확한 도메인을 알고 있다면 전체 도메인이나 접미사 일치를 우선 사용하세요.

rules:
  - DOMAIN,router.lan,DIRECT
  - DOMAIN-SUFFIX,example.com,일반 출구
  - DOMAIN,ads.example.net,REJECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,일반 출구

이 예제는 “일반 출구” 프록시 그룹이 이미 정의되어 있어야 합니다. IP-CIDR은 IP 대역으로 판단하고, GEOIP는 주소 데이터베이스를 기준으로 지역을 판단합니다. MATCH는 일치 값을 지정하지 않으며 마지막 대체 규칙으로 사용합니다. MATCH를 앞에 두면 뒤의 규칙은 적용될 기회가 없습니다. 사설 IP 대역 예제는 두 개만 보여 주며 모든 로컬 주소를 포함하지는 않습니다. 실제 네트워크에는 다른 대역, IPv6, 내부 도메인 규칙이 필요할 수 있습니다.

조회 동작과 규칙 제공자

no-resolve는 이 옵션을 지원하는 주소 기반 규칙 뒤에 자주 사용하며, 규칙 판단만을 위해 도메인 조회를 새로 시작하지 않도록 합니다. 그렇다고 해당 연결에 DNS가 전혀 필요 없다는 뜻은 아닙니다. 요청에 실제 주소가 이미 있으면 주소 규칙과 일치할 수 있지만, 도메인만 있고 사용할 주소가 없다면 규칙이 적용되지 않을 수 있습니다. 모든 주소 규칙에 이 옵션을 추가하면 일치 가능성이 달라지므로 앞선 도메인 규칙과 최종 대체 규칙을 함께 살펴보세요.

GEOIP,CN은 주소 데이터베이스에 기록된 지역을 판단합니다. 웹사이트에서 사용하는 언어나 도메인 등록 국가를 기준으로 하는 것은 아닙니다. 콘텐츠 전송 네트워크를 사용하는 사이트는 지역에 따라 서로 다른 주소를 반환할 수 있으며, 데이터베이스 업데이트가 늦을 수도 있습니다. 특정 서비스에 안정적인 출구가 필요하다면 지역 판단에만 의존하지 말고 명확한 도메인 규칙을 고려하세요. Clash GeoIP 데이터를 업데이트할 때는 현재 커널이 사용하는 데이터 형식과 경로를 확인한 다음 클라이언트에서 제공하는 업데이트 기능을 사용하세요.

규칙이 많으면 rule-providers로 목록을 따로 관리하고 RULE-SET으로 참조할 수 있습니다. 제공자의 동작 유형과 콘텐츠 형식은 서로 맞아야 합니다. 예를 들어 도메인 목록과 클래식 규칙 목록은 임의로 섞어 쓸 수 없습니다. 원격 규칙 업데이트에는 다운로드 경로와 네트워크 연결도 필요하므로 규칙이 로컬에 항상 있다고 가정하면 안 됩니다. 먼저 로컬 규칙 몇 개로 방향을 확인하고 순서가 올바른지 검증한 다음 규칙 모음을 추가하세요. 내용 오류와 업데이트 오류를 구분하기 쉽습니다.

프로세스 규칙은 프로그램 이름이나 경로를 기준으로 일치시킬 수 있지만 운영체제, 커널 권한, 트래픽 전달 방식에 따라 지원 여부가 달라집니다. 프로세스 정보가 표시되지 않는다면 프로세스 규칙을 더 추가해도 적용되지 않을 수 있습니다. 모바일 기기와 데스크톱에서 같은 프로그램 식별 규칙을 그대로 사용할 수는 없습니다. 앱이 커널에 도달하는지 확인하려면 연결 기록에 프로세스 정보가 실제로 있는지 먼저 살펴본 다음 이런 규칙을 사용할지 결정하세요.

규칙을 검증할 때 대상 도메인, 일치한 규칙, 프록시 그룹, 최종 출구를 기록하세요. 웹사이트는 메인 페이지뿐 아니라 이미지, 로그인, API 도메인에도 연결할 수 있어 주 도메인만으로 페이지 전체를 처리하지 못할 수 있습니다. “페이지는 열리지만 이미지가 실패하는” 경우 실패한 리소스의 실제 요청부터 확인하고 관련 없는 키워드까지 규칙 범위를 넓히지 마세요. 흔한 규칙 문제는 FAQ 문제 해결 항목에서도 확인할 수 있습니다. 증상을 바탕으로 범위를 좁힌 다음 규칙 목록을 수정하세요.

오버라이드와 설정 병합

오버라이드는 원본 설정을 유지하면서 별도의 설정 계층을 통해 최종 결과를 변경하는 방식입니다. 병합은 여러 출처의 설정을 커널이 실제로 읽는 하나의 설정으로 합치는 과정입니다. 두 기능 모두 YAML에 공통으로 내장된 기능은 아니며 클라이언트마다 구현 방식이 다를 수 있습니다. YAML 파일은 객체와 목록을 표현할 수 있지만 ‘목록 앞에 삽입’, ‘노드 유지’, ‘스크립트로 가공’ 같은 동작은 보통 클라이언트에서 처리합니다. 다른 사람의 오버라이드 조각을 사용할 때는 대상 클라이언트와 실행 시점을 먼저 확인하세요. 모든 소프트웨어가 같은 방식으로 처리한다고 가정하면 안 됩니다.

원본 설정과 적용된 설정은 다릅니다

구독 설정은 다운로드 후 클라이언트 기본 설정의 덮어쓰기, 사용자 오버라이드, 스크립트 처리 과정을 거친 뒤 커널에 전달될 수 있습니다. 실제 적용 순서는 클라이언트 문서에서 확인하세요. 수정한 내용과 UI가 다르면 ‘실행 설정 보기’, ‘최종 설정 내보내기’와 같은 기능을 찾아보세요. 다운로드한 원본 파일만 계속 열어 보면 클라이언트가 마지막에 추가한 포트, DNS, 규칙 변경을 확인할 수 없을 수도 있습니다.

구독에서 다운로드한 파일을 직접 편집하면 다음 업데이트 때 원격 설정을 다시 받아 로컬 변경 사항이 덮어써질 수 있습니다. 구독은 원격 노드를 관리하고, 오버라이드는 개인 규칙과 로컬 설정을 관리하도록 나누는 편이 안전합니다. 클라이언트가 필요한 오버라이드를 지원하지 않는다면 로컬 설정 파일로 복사할 수 있지만, 이후 구독 변경 사항이 자동으로 반영되지 않는다는 점을 감안해야 합니다. 어떤 방법을 선택할지는 UI의 버튼 수보다 계속 업데이트해야 하는지에 따라 결정하세요.

# 원본 조각
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5

# 원하는 최종 결과: 다른 키는 유지하고 상위 서버 목록만 교체
# 여기에 보이는 것은 결과 예시이며, 범용 오버라이드 지침이 아닙니다

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 119.29.29.29

위 예제의 핵심은 “객체의 다른 키 유지”입니다. 클라이언트가 얕은 병합을 사용하면 nameserver만 포함된 새 dns 객체를 적용할 때 원래의 enable과 향상 모드가 함께 사라질 수 있습니다. 재귀 병합을 사용하면 유지될 수도 있습니다. 조각이 그럴듯해 보인다는 이유만으로 병합 결과를 추측하지 마세요. 실제 적용 후 최종 DNS 객체를 펼쳐 수정하지 않은 필수 필드가 남아 있는지 확인하세요.

목록 교체와 삽입 위치

목록을 다룰 때는 특히 주의해야 합니다. rules, proxies, 프록시 그룹의 후보는 모두 목록입니다. 병합 도구는 목록 전체를 교체하거나 이어 붙일 수 있고, 이름으로 항목을 처리할 수도 있습니다. 규칙 목록 전체를 바꾸면 원래 구독의 트래픽 분기 규칙이 사라집니다. 단순히 뒤에 추가하는 방식이라면 사용자 규칙이 기존 MATCH 뒤에 붙어 전혀 적용되지 않을 수도 있습니다. 따라서 필요한 작업은 단순히 ‘추가’하는 것이 아니라 대체 규칙을 유지하면서 정해진 위치에 넣는 것입니다.

예를 들어 docs.example.com을 직접 연결하려면 넓은 범위의 규칙에 먼저 걸릴 가능성이 있는 규칙보다 앞에 DOMAIN,docs.example.com,DIRECT를 넣으세요. 삽입 기능의 이름은 클라이언트마다 다릅니다. ‘prepend’ 같은 도구 설정을 커널의 rules 목록에 직접 넣으면 안 됩니다. 작업을 마친 뒤 최종 목록의 위와 아래를 확인해 규칙 위치가 올바른지, 예상한 대체 규칙만 있는지, 참조하는 프록시 그룹이 계속 존재하는지 점검하세요.

프록시 그룹 목록도 배열 위치만 보고 덮어쓰면 안 됩니다. 구독 업데이트로 구성원의 순서가 달라지면 기존의 두 번째 그룹이 더 이상 같은 용도라고 보장할 수 없습니다. 이름으로 일치시키는 오버라이드 방식은 보통 관리하기 쉽지만, 상위 설정에서 그룹 이름이 바뀌는 상황은 여전히 처리해야 합니다. 업데이트할 때마다 주요 그룹에 후보가 남아 있는지, 개인 규칙의 참조가 유효한지 확인하세요. 고정된 노드 이름을 후보로 추가했다면 상위 구독에서 해당 노드가 삭제되거나 이름이 바뀔 때 함께 수정해야 합니다.

로컬에서 설정을 관리할 때는 원본 구독 사본, 개인 오버라이드 파일, 정상 작동이 확인된 최종 설정 스냅샷 세 가지로 나누는 것이 좋습니다. 오류가 나면 가장 최근의 오버라이드를 먼저 끄고, 검증된 이전 설정을 복구한 다음 하나씩 다시 추가하세요. 노드, DNS, 규칙 목록을 한 번에 모두 바꾸면 차이가 발생한 계층을 파악하기 어렵습니다. 수정 기록에는 날짜만 쓰기보다 “내부 도메인 직접 연결”처럼 목적을 적어 두면 나중에 이해하기 쉽습니다.

병합을 마친 뒤에는 구독 업데이트도 한 번 테스트하세요. 수동으로 불러오기에 성공했다는 사실만으로 다음 원격 업데이트 뒤에도 개인 설정이 유지된다고 볼 수 없습니다. 업데이트 후 대상 규칙, DNS, 프록시 그룹 선택을 다시 확인해 오버라이드가 예상한 단계에서 실행됐는지 점검하세요. 업데이트 후 동작이 달라졌다면 클라이언트를 바로 다시 설치하지 말고 최종 설정의 차이를 비교한 뒤 상위 구독 내용을 확인하세요. 대부분의 병합 문제는 이 과정에서 어떤 필드가 사라지거나 중복됐는지 찾을 수 있습니다.

검증과 문제 원인 찾기

설정 검증은 세 단계로 나눠야 합니다. 텍스트를 파싱할 수 있는지, 참조된 항목을 불러올 수 있는지, 실제 연결이 예상대로 되는지 확인하세요. YAML 문법 검사를 통과했다는 것은 들여쓰기와 기본 형식이 올바르다는 뜻일 뿐입니다. 노드 이름이 없거나 프로토콜 필드가 지원되지 않으면 커널에서 불러올 때 실패할 수 있으며, 불러오기에 성공해도 앱이 프록시를 사용하지 않을 수 있습니다. 이 세 단계를 순서대로 점검하면 시간 초과가 발생했을 때 설정 파일 전체를 무작정 수정하는 것보다 원인을 정확히 찾기 쉽습니다.

불러오기 전에 먼저 검사

편집한 뒤 사본을 저장하고 클라이언트에서 제공하는 설정 검사 기능을 사용하세요. 명령줄 환경을 사용할 수 있고 mihomo가 이미 설치되어 있다면 커널 테스트 명령을 실행할 수 있습니다. 명령에 표시된 경로는 예제 파일명이며 실제 파일이 있는 폴더에서 실행해야 합니다. Windows에서는 설치 위치에 맞는 실행 파일을 사용하세요. 상대 경로로 지정된 리소스, 규칙 파일, 데이터 디렉터리도 확인해야 합니다. 설정 파일만 복사했다고 클라이언트와 같은 환경이라고 가정하면 안 됩니다.

mihomo -t -f ./config.yaml

YAML 파싱 오류가 표시되면 오류 위치 주변의 들여쓰기, 콜론, 따옴표, 하이픈을 먼저 확인하세요. 프록시나 그룹이 없다는 오류는 이름 참조를 따라 정의된 위치를 찾습니다. 필드나 프로토콜이 지원되지 않는다는 메시지가 나오면 무작위로 필드를 삭제하지 말고 현재 커널이 지원하는지 확인하세요. 테스트 명령을 통과한 뒤 설정을 불러오고 시작 로그에서 실제로 해당 파일을 사용했는지 확인합니다. 사본을 검사했지만 다른 Profile이 실행되는 상황을 피할 수 있습니다.

명확한 요청 하나로 입구 검증

반복해서 접속할 수 있는 테스트 대상을 하나 고르고, 로컬 포트를 확인한 뒤 프록시를 명시해 요청을 보내세요. 아래 명령을 실행하려면 예제 포트에서 로컬 혼합 입구가 수신 중이어야 하며 환경에 curl이 설치되어 있어야 합니다. 이 명령은 HTTP 프록시를 사용해 HTTPS 웹사이트에 접속하므로 요청이 로컬 입구로 들어가는지 확인하는 데 도움이 됩니다. 명령이 성공해도 시스템의 다른 앱까지 프록시를 사용한다는 뜻은 아닙니다.

curl --proxy http://127.0.0.1:7890 --head https://example.com

동시에 클라이언트의 연결 기록도 살펴보세요. 새 요청이 전혀 없다면 포트, 수신 주소, 프로그램 실행 여부를 확인하고 명령이 다른 프록시에 연결된 것은 아닌지 살펴보세요. 요청이 나타나면 일치한 규칙과 정책 경로를 이어서 확인합니다. 규칙, 그룹 선택, 출구가 모두 예상과 일치한 뒤에 노드와 원격 연결을 점검하세요. 상태 코드는 대상 사이트에 따라 해석해야 합니다. 모든 사이트가 HEAD 요청에 일반 페이지 요청과 같은 응답을 보내는 것은 아닙니다.

로그의 ‘연결 거부’, ‘조회 실패’, ‘핸드셰이크 실패’, ‘시간 초과’는 서로 다른 단계를 가리킵니다. 연결 거부는 해당 포트에서 수신 중인 서비스가 없을 수 있습니다. 조회 실패라면 DNS 경로를 먼저 살펴보세요. 핸드셰이크 실패는 프로토콜, 인증, TLS 설정을 확인해야 하며, 시간 초과는 발생한 위치에 따라 네트워크 연결 여부를 판단해야 합니다. 오류의 마지막 한 줄만 캡처하지 말고 앞뒤 관련 기록을 함께 보관하세요. 단, 공유 전에는 구독 주소, 인증 정보, 공개하고 싶지 않은 접속 대상을 삭제해야 합니다.

Windows 스토어 앱에서만 문제가 생기고 같은 입구를 사용하는 브라우저는 정상이라면 UWP 루프백 제한 해결 방법을 확인하세요. 클라이언트를 실행할 때 바로 종료된다면 시작 시 충돌 문제 해결 안내에 따라 로그와 설정 복구 방법을 확인하세요. 서로 다른 증상에 같은 해결책을 적용하지 마세요. 문제가 생길 때마다 재설치하는 것도 피해야 합니다. 기존 설정이 그대로 남거나 원인 파악에 필요한 단서가 사라질 수 있습니다.

검증이 끝나면 임시 디버깅 설정을 원래대로 돌리고 정상 작동하는 최종 설정을 저장한 다음, 테스트 대상과 수정 범위를 기록하세요. 다음에 문제가 생기면 가장 최근에 바꾼 항목부터 되돌리면 됩니다. 사용 흐름을 다시 확인하려면 사용 안내로 돌아가고, 흔한 증상은 FAQ에서 확인하세요. 기기에 맞는 클라이언트로 바꾸려면 다운로드 페이지를 방문하세요. 이 페이지의 점검 순서는 언제나 입구 확인부터 시작해 조회, 규칙, 출구를 차례로 살펴보는 것입니다.