Clash YAML 설정 가이드

SECTION 01 / DOCUMENT MODEL

YAML 구조와 설정 출처

맵, 목록, 들여쓰기 단계

Clash 설정은 줄 단위로 실행되는 스크립트가 아니라, 수신 포트와 이름 확인 방식, 트래픽 전달 방식을 정의하는 구조화된 문서입니다. 최상위 필드는 전역 동작을 정하고, 중첩된 맵에는 같은 기능의 매개변수가 들어가며, 목록은 순서가 있는 항목을 나타냅니다. 읽을 때는 먼저 들여쓰기를 확인한 다음 필드명을 살펴보세요. 콜론 뒤의 값은 해당 필드에 속하고, 다음 줄에서 들여쓴 필드는 상위 맵에 포함됩니다. 하이픈으로 시작하는 항목은 목록의 일부이므로 같은 단계의 맵으로 임의 변경하면 안 됩니다.

들여쓰기는 공백 두 칸으로 통일하고 탭은 사용하지 않는 것이 좋습니다. 같은 단계의 필드는 나란히 정렬해야 하지만, 들여쓰기 깊이가 우선순위를 뜻하지는 않습니다. 예를 들어 dns.enable은 dns 아래에 있어야 의도한 대로 동작합니다. enable을 최상위로 옮기면 파일은 파싱되더라도 DNS 설정에는 반영되지 않을 수 있습니다. 오류를 찾을 때는 문법 검사에 그치지 말고, 해당 필드가 코어에서 인식하는 위치에 있는지도 확인하세요.

mixed-port: 7890
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
proxies: []
proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,PROXY

위 예제는 구조를 확인하기 위한 것으로, 정책 그룹에는 직접 연결만 포함되어 있어 원격 프록시로 연결되지 않습니다. proxies: []는 빈 목록이지 문자열이나 필드 누락이 아닙니다. 불리언 값은 true와 false를 사용하고, 포트는 보통 정수로 지정합니다. 샵 기호, 콜론 뒤 공백, 별표 등 특수 문자가 들어간 문자열은 따옴표로 감싸는 것이 좋습니다. 숫자처럼 보이는 비밀번호도 파서가 형식을 바꾸지 않도록 문자열로 저장하세요.

프로필, 구독, 실행 설정

클라이언트에서 프로필(Profile)은 로컬 파일이나 원격 구독을 연결할 수 있는 설정 항목입니다. 구독에서 내려받은 YAML에는 보통 프록시 항목, 정책 그룹, 규칙이 들어 있지만, 클라이언트가 수신 포트나 시스템 연동 옵션, 설정 덮어쓰기 결과를 추가할 수도 있습니다. 코어가 실제로 읽는 파일은 이러한 입력을 처리한 뒤 만들어진 실행 설정입니다. 구독 캐시, 원본 파일, 설정 덮어쓰기 내용을 수정하는 작업은 각각 영향을 미치는 범위가 다릅니다.

원격 구독을 업데이트하면 캐시에 직접 적용한 수정 사항이 덮어써질 수 있습니다. 따라서 구독에서 관리하는 내용과 계속 유지할 사용자 설정은 분리해 관리하세요. 공통 포트와 로그 수준은 클라이언트에서 통합 관리하고, 개인 규칙은 계속 적용할 수 있는 설정 덮어쓰기 계층에 두는 것이 좋습니다. 구체적인 병합 방식은 클라이언트마다 다르므로 파일 이름만으로 설정 출처를 판단할 수 없습니다. 차이를 비교할 때는 편집기에서 현재 열려 있는 탭만 확인하지 말고 원본 구독과 최종 출력 파일을 모두 저장해 살펴보세요.

파일 편집 시 기본 원칙

하나의 맵에서 같은 키를 중복 정의하지 마세요. dns 블록을 두 번 작성해도 자동으로 병합된다고 보장할 수 없습니다. 파서에 따라 오류가 발생하거나 한쪽만 남을 수 있습니다. DNS 서버를 추가하려면 파일 끝에 같은 필드를 다시 쓰지 말고 기존 목록을 수정하세요. 규칙 목록도 출처를 하나로 명확히 관리해야 합니다. 구독과 로컬 수정이 각각 최상위 rules를 만들지 않도록 주의하세요.

파일은 UTF-8로 저장하고 일반 ASCII 콜론과 하이픈을 사용하세요. 한글 문장에는 전각 문장 부호를 써도 되지만 YAML 구조 기호를 대신할 수는 없습니다. 주석은 샵 기호로 시작하며 실행 필드로 처리되지 않습니다. 다만 따옴표 안의 샵 기호는 문자열의 일부입니다. 예제를 복사한 뒤에는 공백 문자를 먼저 확인하고, 이어서 설정 참조가 올바른지 살펴보세요. 웹페이지에서 보이는 정렬만으로 편집기 안의 실제 공백을 판단해서는 안 됩니다.

설정 파일 경로는 운영체제, 설치 방식, 클라이언트 설정에 따라 달라지므로 이 안내서에서는 특정 사용자 디렉터리를 공통 경로로 제시하지 않습니다. 클라이언트의 설정 디렉터리 열기 기능이나 로그에서 실제 위치를 확인하세요. 여러 설정을 함께 사용할 때는 용도를 알 수 있는 이름으로 프로필을 구분하고 현재 활성화된 항목을 기록해 두세요. 로컬 파일, 원격 구독, 설정 전환의 관계는 프로필 기초와 여러 설정 관리에서 자세히 확인할 수 있습니다.

SECTION 02 / LISTENERS AND MODE

수신 포트와 실행 모드

프록시 프로토콜과 수신 주소

프록시 포트는 애플리케이션에서 코어로 전달되는 연결을 받습니다. 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
external-controller: 127.0.0.1:9090

이 설정은 프록시와 제어 진입점을 로컬 컴퓨터로 제한합니다. 다른 기기에서 사용하려면 수신 주소, allow-lan, 시스템 방화벽, 접근 제어를 함께 고려해야 합니다. 하나의 스위치만 바꾸는 것으로는 충분하지 않습니다. 모든 네트워크 인터페이스에서 수신하면 더 많은 인터페이스를 통해 서비스에 접근할 수 있습니다. 특히 제어 인터페이스를 공용 네트워크에 직접 노출하지 마세요. 원격 관리가 꼭 필요하다면 인증을 설정하고 네트워크 접근 범위를 제한해야 합니다.

규칙, 전역, 직접 연결 모드의 차이

mode: rule은 규칙 목록에 따라 출구를 선택하므로 도메인, 주소, 규칙 모음별로 트래픽을 나누려는 경우에 적합합니다. mode: global은 코어에 들어온 연결을 전역 정책으로 처리하지만, 시스템의 모든 애플리케이션을 자동으로 프록시 처리한다는 뜻은 아닙니다. mode: direct는 코어에 들어온 연결을 목적지로 직접 전달합니다. 여전히 프록시 진입점의 처리 과정을 거치며 클라이언트 프로세스를 종료하는 것은 아닙니다.

모드와 시스템 프록시는 서로 다른 계층에서 동작합니다. 모드는 연결이 코어에 들어온 뒤 어떻게 전달되는지를 결정하고, 시스템 프록시는 시스템 설정을 따르는 애플리케이션이 요청을 해당 진입점으로 보낼지 결정합니다. 자체 프록시 설정을 사용하는 프로그램도 있고 시스템 프록시를 무시하는 프로그램도 있습니다. 특정 앱의 동작이 다르면 규칙을 보기 전에 프록시 진입점이 해당 앱을 포함하는지 확인하세요. 브라우저에서 접속된다고 해서 다른 프로그램도 같은 경로를 이용한다고 볼 수는 없습니다.

포트 변경과 프로세스 범위

혼합 포트를 변경했다면 애플리케이션에 설정된 프록시 주소도 함께 바꿔야 합니다. 클라이언트가 시스템 프록시를 관리하더라도 브라우저 확장 프로그램, 터미널 환경 변수, 개발 도구에 고정된 포트까지 자동으로 바뀌는 것은 아닙니다. 클라이언트는 정상인데 터미널이 예전 포트에 연결되는 경우가 흔합니다. HTTP_PROXY, HTTPS_PROXY, ALL_PROXY의 실제 값과 앱 내부에 별도로 저장된 프록시 설정을 각각 확인하세요.

포트 충돌은 지정한 로컬 주소와 포트 조합이 이미 사용 중이거나 이전 코어 프로세스가 종료되지 않았다는 뜻일 수 있습니다. 중복 실행 중인 클라이언트를 종료한 뒤 포트를 점유한 프로세스를 확인하세요. 모든 수신 포트를 무작위로 바꾸는 것은 권장하지 않습니다. 로그에 권한 오류가 명시되어 있다면 실행 권한이나 시스템의 포트 예약 상태를 확인하세요. 포트 번호 자체가 연결 품질을 좌우하지는 않습니다. 애플리케이션 간 설정 일치 여부와 로컬에서 사용할 수 있는 포트를 기준으로 선택하면 됩니다.

평소에는 로그 수준을 info로 유지하고, 규칙 매칭 과정을 추적할 때만 잠시 debug로 바꾸는 것이 좋습니다. 상세 로그에는 접속 대상이 포함될 수 있으니 공유 전에 구독 주소, 인증 정보, 개인 접속 기록을 삭제하세요. 처음 설치할 때 포트와 시스템 프록시를 확인하는 방법은 최초 설치와 초기 설정을 참고하세요. 로컬 진입점 하나의 문제를 해결하려고 전체 구독을 바꿀 필요는 없습니다.

SECTION 03 / NAME RESOLUTION

DNS 확인과 Fake-IP

DNS 필드의 역할

DNS 설정은 도메인을 연결과 규칙 판정에 사용할 정보로 변환합니다. dns.enable은 코어의 DNS 기능을 켜고, listen은 질의를 받을 로컬 주소를 지정하며, nameserver에는 일반 업스트림 서버를 나열합니다. DNS를 켰다고 시스템의 모든 질의가 자동으로 코어를 거치는 것은 아닙니다. 시스템 DNS, 앱 내장 암호화 DNS, TUN의 DNS 가로채기 설정에 따라 실제 질의 경로가 달라집니다.

default-nameserver는 DNS 업스트림 서버 자체의 도메인을 확인할 때 자주 사용되며, 이를 통해 필요한 연결을 시작할 수 있습니다. 예를 들어 업스트림에 HTTPS 도메인 주소를 지정했다면 먼저 해당 도메인의 IP 주소를 알아내야 합니다. 모든 질의에 우선 적용되는 만능 필드는 아닙니다. 혼동하기 쉬운 proxy-server-nameserver는 프록시 서버 도메인을 확인하는 필드로, 프록시 연결에 필요한 DNS 경로를 분리해 지정할 때 유용합니다.

dns:
  enable: true
  listen: 127.0.0.1:1053
  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

이 예제는 로컬 DNS 서비스만 설정하며 시스템 전체의 DNS를 가로채지는 않습니다. 업스트림 주소는 현재 네트워크에서 연결 가능한지를 기준으로 선택해야 합니다. 암호화된 전송을 사용한다고 해서 어떤 네트워크에서나 연결할 수 있는 것은 아닙니다. 로컬 수신 포트를 변경했다면 운영체제나 포워딩 프로그램도 해당 포트로 질의를 전달할 수 있어야 합니다. 일반적인 시스템 DNS 설정에서는 주소만 입력할 수 있고 사용자 지정 포트는 함께 지정할 수 없는 경우가 많습니다.

Fake-IP와 실제 주소 확인

Fake-IP 모드는 도메인에 코어가 알아볼 수 있는 매핑 주소를 할당하고, 이 매핑을 이용해 도메인 정보를 보존합니다. 예제의 주소 대역은 내부 매핑용이므로 실제 웹사이트의 접속 주소가 아니며 원격 서버 주소로 입력해서도 안 됩니다. 요청이 코어에 들어올 때 도메인을 더 안정적으로 연결할 수 있다는 장점이 있지만, 앱과 시스템의 DNS 질의가 같은 코어 인스턴스를 거쳐야 합니다.

redir-host 모드는 실제 DNS 응답을 반환하며 Fake-IP와는 다른 경로로 처리됩니다. 실제 주소를 필요로 하는 일부 로컬 서비스에는 이 방식이 더 적합할 수 있지만, 모드를 바꾸는 것이 DNS 문제의 만능 해결책은 아닙니다. 먼저 질의 실패인지, 매핑 문제인지, 앱이 코어를 우회했는지 확인하세요. 모드를 바꾼 뒤에는 시스템과 앱에 남아 있는 DNS 캐시도 고려해야 합니다. 이전 결과가 새 연결에 계속 영향을 줄 수 있습니다.

fake-ip-filter는 지정한 도메인에 가상 매핑을 적용하지 않도록 설정합니다. 호환성 문제가 실제로 있는 로컬 도메인이나 서비스 검색 도메인에 사용할 수 있습니다. 필터 범위가 지나치게 넓으면 도메인 매핑 효과가 떨어지므로 영향을 받는 도메인부터 추가하세요. 자주 쓰이는 접미사를 한꺼번에 모두 넣는 것은 피해야 합니다. 필터의 구체적인 매칭 방식은 현재 코어 문서를 확인하세요. 일반 도메인 목록을 임의 형식의 규칙 모음으로 간주해서는 안 됩니다.

DNS 경로와 트래픽 분기의 연결 관계

DNS 요청 자체를 분기 규칙에 따라 처리하려면 업스트림 연결이 어떤 경로로 나가는지도 확인해야 합니다. respect-rules는 DNS 연결이 라우팅 규칙을 따르도록 하지만, 프록시 서버 도메인을 어떻게 확인할지 명확히 하지 않으면 순환 의존성이 생길 수 있습니다. 프록시가 있어야 DNS를 확인할 수 있고 DNS를 확인해야 프록시에 연결할 수 있는 상황입니다. 이 필드를 추가하기 전에 업스트림 DNS 확인, 프록시 핸드셰이크, 목적지 접속의 순서를 정리하세요.

nameserver-policy를 사용하면 도메인 조건에 따라 DNS 서버를 지정할 수 있습니다. 이 필드는 어떤 DNS 경로를 사용할지 정할 뿐, 해당 웹사이트의 접속 규칙을 자동으로 만들지는 않습니다. DNS 분기와 연결 분기는 서로 다른 단계입니다. 전자는 DNS 서버를, 후자는 실제 접속 경로를 선택합니다. 도메인이 특정 DNS 서버를 사용한다고 해서 실제 연결도 같은 출구를 이용하는 것은 아닙니다. 두 동작을 일치시키려면 관련 설정을 모두 확인하세요.

문제를 확인할 때는 연결 가능한 업스트림 하나만 남겨 기본 DNS 질의가 되는지 먼저 확인한 다음 정책과 필터를 하나씩 추가하세요. LAN의 이름을 확인할 수 없다면 모든 질의를 공용 DNS로 보내기보다 라우터나 로컬 DNS의 역할부터 확인해야 합니다. 브라우저와 명령줄의 결과가 다르면 각각의 캐시를 비우고 별도 DNS 설정이 있는지도 확인하세요. DNS 변경은 포트나 모드 변경과 나눠 진행해야 로그와 동작의 차이를 명확히 연결할 수 있습니다.

SECTION 04 / OUTBOUND DEFINITIONS

프록시 필드와 원격 제공자

공통 필드와 프로토콜 필드 구분

proxies에는 선택 가능한 아웃바운드 프록시를 정의합니다. 일반적으로 항목에는 이름, 프로토콜 유형, 서버 주소, 포트가 필요하며, 프로토콜에 따라 비밀번호, 사용자 ID, 전송 설정을 추가합니다. 이름은 내부 참조에 사용되므로 정책 그룹의 구성원으로 지정한 이름과 일치해야 합니다. 서버 필드는 실제 연결 대상을 나타내며 이름을 대신할 수 없습니다. 예제 정보를 실제 서비스로 오인하지 않도록 이 절에서는 프로토콜 필드만 보여 주며 실제 연결 항목은 제공하지 않습니다.

type은 코어가 후속 매개변수를 어떤 프로토콜로 해석할지 결정합니다. 프로토콜이 달라도 server와 port를 함께 쓸 수 있지만 인증 필드는 서로 바꿔 쓸 수 없습니다. 어떤 유형은 비밀번호가 필요하고, 어떤 유형은 사용자 ID가 필요하며, 별도의 암호화 방식을 지정해야 하는 유형도 있습니다. 다른 프로토콜의 필드를 그대로 남겨 두면 무시되거나 설정을 불러오지 못할 수 있습니다.

# Shadowsocks 프로토콜 필드만 표시한 예제이며 완전한 프록시 항목이 아닙니다
type: ss
server: proxy.example.com
port: 443
cipher: aes-128-gcm
password: "your-password"
udp: true

예제의 도메인과 비밀번호는 설명용입니다. 실제 사용 시에는 서비스 제공자가 안내한 프로토콜 매개변수를 정확히 지정해야 하며, 포트 번호만으로 프로토콜 유형을 추정하면 안 됩니다. 443은 흔히 사용하는 서버 포트 중 하나일 뿐 TLS가 자동으로 활성화되는 것은 아닙니다. udp: true는 관련 기능을 허용하지만 실제 사용 가능 여부는 프로토콜, 서버 구현, 전체 네트워크 경로에 달려 있습니다. 모든 앱의 UDP 통신을 보장하지는 않습니다.

TLS와 전송 계층 매개변수

TLS를 지원하는 프로토콜에서는 서버 주소와 인증서 검증에 사용할 이름이 다를 수 있습니다. servername은 일반적으로 핸드셰이크에 사용할 서버 이름을 지정하며 서비스 설정 및 인증서와 일치해야 합니다. skip-cert-verify는 인증서 검증을 제어하지만 연결 실패를 해결하기 위해 상시 사용하는 옵션이 아닙니다. 인증서 오류의 원인은 잘못된 도메인, 시스템 시간 오류, 불완전한 서버 인증서 체인일 수 있습니다. 검증을 건너뛰면 이런 문제를 가릴 수 있습니다.

WebSocket, HTTP 등의 전송 설정은 일반적으로 해당 프로토콜에서 지원하는 중첩 필드에 지정합니다. 경로, 요청 헤더, 핸드셰이크 이름은 서로 다른 계층에 있으므로 모두 도메인처럼 보여도 서로 바꿔 쓸 수 없습니다. 서비스 제공자가 원본 YAML을 제공한다면 해당 프로토콜 블록의 구조를 유지하고 코어가 관련 옵션을 지원하는지 확인하세요. 구독 변환 과정에서 확장 필드가 누락될 수 있으므로 원본 링크는 작동하지만 변환된 결과가 작동하지 않는다면 구조 차이를 비교해야 합니다.

proxy-providers의 역할과 범위

proxy-providers는 원격 프록시 항목을 독립 리소스로 관리하고, 정책 그룹은 use로 제공자를 참조합니다. 전체 프로필 구독과는 다른 계층입니다. 전체 설정에는 DNS, 규칙, 그룹도 들어갈 수 있지만 프록시 제공자의 데이터는 지정된 형식에 맞아야 합니다. 전체 구독 주소를 제공자에 바로 입력해도 코어가 이를 프록시 모음으로 읽는다고 보장할 수 없습니다.

proxy-providers:
  REMOTE:
    type: http
    url: "https://example.com/proxies.yaml"
    path: ./providers/remote.yaml
    interval: 86400
proxy-groups:
  - name: PROXY
    type: select
    use:
      - REMOTE

여기서 REMOTE는 제공자 식별자이지 단일 프록시 항목이 아닙니다. 예제 주소에는 실제 설정이 없으므로 접근 권한이 있고 형식이 호환되는 리소스로 바꾸세요. interval은 초 단위로 리소스 업데이트 주기를 지정합니다. 정책 그룹의 탐색 주기와는 역할이 다릅니다. path는 캐시 위치를 뜻하며 접근 가능 여부는 코어의 작업 디렉터리와 경로 보안 제한에도 영향을 받습니다. 데스크톱 클라이언트가 이러한 파일을 별도로 관리할 수도 있습니다.

제공자 다운로드에 실패하면 URL 접속 불가, 인증 만료, 웹페이지 응답, YAML 데이터 구조 오류 중 무엇이 원인인지 먼저 확인하세요. 캐시가 남아 있다면 업데이트 실패 후에도 이전 내용이 유지될 수 있으므로 화면에 구성원이 보인다고 해서 갱신에 성공한 것은 아닙니다. 원격 구독 URL에는 접근 자격 증명이 포함될 수 있으니 스크린샷이나 공개 로그에 붙여 넣지 마세요. 가져오기 형식의 차이와 전체 절차는 구독 링크 가져오기와 형식 안내에서 확인할 수 있습니다.

SECTION 05 / POLICY GRAPH

정책 그룹 필드와 참조 관계

정책 그룹은 트래픽 가로채기 진입점이 아닙니다

proxy-groups는 사용 가능한 출구를 구성해 재사용할 수 있는 의사 결정 단위로 만듭니다. 규칙의 대상으로 정책 그룹을 지정할 수 있고, 그룹 안에서는 프록시, 내장 동작, 참조가 허용된 다른 그룹을 가리킬 수 있습니다. 그룹은 연결이 도달한 뒤 다음 경로를 어떻게 선택할지 결정할 뿐, 앱이 프록시를 사용하도록 만들지는 않습니다. 앱 요청이 코어에 들어오지 않으면 그룹 구성이 아무리 완벽해도 동작하지 않습니다.

각 그룹에는 고유하고 안정적인 name이 필요하며 type으로 선택 방식을 지정합니다. select는 현재 출구를 직접 고르고 싶을 때 적합합니다. url-test는 탐색 결과에 따라 구성원을 선택하고, fallback은 구성원 순서에 따라 사용 가능한 출구를 선택하는 방식에 가깝습니다. load-balance는 설정된 정책에 따라 연결을 분배합니다. 선택 로직은 화면에 표시되는 순서만으로 판단할 수 없습니다.

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT
      - REJECT
rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - MATCH,DIRECT

이 예제는 참조 관계를 이해하기 위한 것입니다. DIRECT는 직접 연결, REJECT는 연결 거부를 뜻합니다. 후자를 선택하면 해당 그룹에 매칭된 요청이 거부됩니다. 두 항목은 코어 내장 대상이므로 proxies에 다시 정의할 필요가 없습니다. 실제 설정에는 유효한 출구를 그룹에 추가할 수 있지만, 정의되지 않은 이름을 목록에 적어 둔다고 코어가 자동으로 만들어 주지는 않습니다.

구성원 출처와 탐색 설정

proxies는 직접 지정한 구성원 목록이고 use는 프록시 제공자를 참조합니다. 고정된 구성을 원한다면 직접 목록을, 별도로 업데이트되는 리소스를 원한다면 제공자를 사용할 수 있습니다. 둘을 함께 쓸 때는 현재 코어가 구성원 조합을 어떻게 처리하는지, 제공자가 이미 로드됐는지 확인하세요. 그룹이 화면에 표시된다고 해서 선택 가능한 구성원이 있다는 뜻은 아닙니다. 제공자가 비어 있거나 필터 조건이 지나치게 엄격하거나 리소스를 읽지 못하면 그룹이 비게 됩니다.

자동 선택 유형에는 일반적으로 url, interval 등의 탐색 매개변수가 필요합니다. 탐색 주소는 안정적이고 응답이 가벼우며 선택한 경로로 접속할 수 있는 HTTP 서비스여야 합니다. 탐색 결과는 해당 주소에 요청했을 때의 상태만 보여 줄 뿐 모든 웹사이트, 인증 절차, 애플리케이션 프로토콜이 작동한다는 뜻은 아닙니다. 테스트 주소가 네트워크 정책에 차단되면 실제로 사용할 수 있는 구성원도 사용 불가로 판정될 수 있습니다.

tolerance 등의 매개변수는 잦은 전환을 줄이는 데 사용되며, 적합성은 그룹 유형과 현재 코어에 따라 달라집니다. 화면이 더 자주 바뀌도록 탐색 간격을 지나치게 짧게 설정하지 마세요. 탐색 빈도가 높으면 요청이 늘고 네트워크가 불안정할 때 선택 결과가 계속 바뀔 수 있습니다. 설정을 조정하기 전에 자동으로 최적 경로를 고를지, 예비 경로를 유지할지, 연결을 분산할지 먼저 결정하세요. 미세 조정보다 그룹 유형 선택이 더 중요합니다.

계층형 설계와 순환 참조

계층형 정책 그룹은 사용자 선택과 규칙 분류를 분리하는 데 유용합니다. 예를 들어 규칙은 용도가 명확하고 안정적인 정책 그룹을 가리키고, 그 그룹은 공통 수동 선택 그룹을 참조하도록 구성할 수 있습니다. 이렇게 하면 원격 리소스가 바뀌어도 규칙을 하나씩 수정할 필요가 없습니다. 다만 계층이 깊어질수록 문제를 찾기 어려워집니다. 각 계층의 역할을 명확히 하고 같은 전달만 반복하는 불필요한 그룹은 피하세요.

그룹끼리 순환 참조를 만들면 안 됩니다. A 그룹이 B 그룹을 참조하고 B 그룹이 다시 A 그룹을 참조하면 아웃바운드 경로가 끝나지 않습니다. 큰 설정에서는 그룹끼리 직접 참조하지 않아도 중간 계층을 거쳐 순환이 생길 수 있습니다. 규칙 대상부터 시작해 실제 프록시나 내장 동작에 도달할 때까지 각 단계를 펼쳐 확인하세요. 모든 경로는 끝이 있어야 하며 이미 거친 그룹을 다시 만나서는 안 됩니다.

로그인 상태를 유지해야 하는 서비스에서 새 연결을 여러 경로로 분산하면 출구가 바뀌어 추가 인증이 발생할 수 있습니다. 연결 분배를 기본 최적화로 여기지 말고 앱에 필요한 안정성에 맞춰 경로를 선택하세요. 그룹 선택을 바꿔도 기존 연결은 보통 자동으로 이동하지 않으며 새 연결부터 변경된 결정이 적용됩니다. 설정을 검증할 때는 대상 앱의 기존 연결을 종료한 후 다시 시도하세요. 규칙 매칭과 최종 출구 경로도 함께 확인해 기존 세션을 설정 미적용으로 오인하지 않도록 하세요.

SECTION 06 / FIRST MATCH

규칙 문법과 매칭 순서

첫 번째 매칭 규칙과 기본 규칙

규칙 모드에서 코어는 rules를 위에서 아래로 확인하고, 적용되는 첫 번째 규칙을 만나면 지정된 대상을 사용합니다. 뒤에 있는 규칙이 더 구체적인지 비교하지 않습니다. 따라서 우선순위는 규칙 이름이나 도메인 길이가 아니라 목록에서의 위치로 결정됩니다. 일반적으로 명확한 예외를 위에 두고, 일반 분류를 중간에 배치하며, 기본 규칙을 맨 마지막에 둡니다.

대부분의 규칙은 유형, 조건, 대상을 쉼표로 구분하는 형식입니다. MATCH에는 매칭 조건이 없으며 나머지 연결의 처리 대상을 바로 지정합니다. 그 앞의 규칙이 구체적인 분류를 처리하므로 뒤에 있는 규칙은 보통 실행되지 않습니다. 규칙이 적용되지 않는 이유를 찾을 때는 같은 규칙을 반복해서 추가하지 말고 위쪽에 먼저 매칭되는 항목이 있는지 확인하세요.

rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,github.com,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

이 규칙은 PROXY라는 정책 그룹이 이미 정의되어 있다고 가정합니다. LAN 주소 예제는 모든 사설 네트워크 범위를 빠짐없이 포함하지 않으므로 실제 환경에 맞게 보완해야 합니다. GEOIP는 해당 지리 정보 데이터가 제공되어야 하며, 분류 결과가 서비스 운영 주체의 소재지와 반드시 일치하는 것도 아닙니다. 명확한 업무 요건이 있다면 지리적 추정에만 의존하기보다 설명 가능한 도메인이나 주소 규칙을 우선 사용하세요.

도메인 규칙과 IP 주소 규칙의 차이

DOMAIN은 도메인 전체와 일치하므로 특정 호스트에 예외를 적용할 때 적합합니다. DOMAIN-SUFFIX는 지정한 도메인과 하위 도메인을 모두 매칭하므로 서비스 도메인 전체에 적용할 수 있습니다. DOMAIN-KEYWORD는 키워드로 매칭하므로 의도한 범위를 벗어나기 쉬워 주의해야 합니다. 규칙 조건에는 보통 프로토콜 접두사, URL 경로, 포트를 쓰지 않습니다. 도메인 조건에 웹페이지 전체 주소를 넣어도 경로 단위로 매칭되지는 않습니다.

IP-CIDR와 IP-CIDR6은 목적지 IP 주소 범위에 따라 판단합니다. 도메인으로 시작된 요청에 일부 IP 규칙을 적용하면 DNS 조회가 발생할 수 있습니다. no-resolve는 해당 규칙이 직접 DNS 조회를 일으키지 않도록 하지만 전체 접속 경로에서 DNS를 전혀 사용하지 않는다는 뜻은 아닙니다. 연결에 목적지 IP가 이미 있다면 주소 매칭을 할 수 있습니다. 도메인만 있고 주소가 없다면 이 규칙으로는 매칭되지 않을 수 있습니다.

하나의 웹사이트에서 여러 도메인에 접근할 수 있으며 정적 리소스, 로그인, API 요청에 같은 접미사가 사용된다고 보장할 수 없습니다. 홈페이지 도메인에만 규칙을 추가해도 전체 사용 과정이 같은 경로를 이용한다는 뜻은 아닙니다. 문제를 확인할 때는 웹페이지가 열린다는 사실만으로 검증을 끝내지 말고 실제로 실패한 요청을 살펴보세요. IP 주소에 직접 연결하는 앱은 도메인 규칙에 필요한 정보가 없을 수 있으므로 실제 연결 대상을 기준으로 정책을 정해야 합니다.

규칙 제공자와 데이터 형식

rule-providers는 별도로 업데이트할 수 있는 규칙 모음을 관리하며, 주 규칙 목록에서 RULE-SET으로 참조합니다. 제공자는 매칭 조건을 보관하고 주 규칙은 적용 위치와 대상을 지정합니다. 규칙 모음을 정상적으로 다운로드해도 주 규칙에서 참조하지 않으면 매칭에 사용되지 않습니다. 기본 규칙 뒤에 참조를 두어도 예상대로 동작하지 않습니다.

rule-providers:
  LOCAL-DOMAINS:
    type: inline
    behavior: domain
    payload:
      - "+.example.com"
rules:
  - RULE-SET,LOCAL-DOMAINS,DIRECT
  - MATCH,PROXY

예제는 외부 파일에 의존하지 않도록 도메인 목록을 설정에 직접 넣습니다. behavior: domain의 데이터에는 도메인 조건이 들어가며 정책 대상을 포함한 전체 규칙 행을 넣어서는 안 됩니다. ipcidr와 classical은 데이터 의미가 다르므로 원격 리소스 형식이 선언과 일치해야 합니다. 제공자 유형이나 형식을 바꿀 때는 필드명만 수정하지 말고 실제 데이터도 함께 확인하세요.

규칙을 정리할 때는 로컬에서 추가한 각 규칙의 이유를 기록하고 상위 규칙에 이미 포함된 중복 항목은 주기적으로 삭제하는 것이 좋습니다. 여러 설정 덮어쓰기 스크립트에서 주 규칙을 순서 없이 추가하면 최종 순서를 파악하기 어렵습니다. 자세한 유형 설명, 순서 예제, 매칭 분석은 Clash 사용자 규칙 문법과 우선순위에서 확인할 수 있습니다. 이 페이지의 설정 덮어쓰기 절에서는 구독 업데이트 후에도 개인 규칙을 유지하는 방법을 설명합니다.

SECTION 07 / CONFIGURATION PIPELINE

설정 덮어쓰기, 병합, 업데이트 범위

클라이언트 처리와 코어 필드 구분

설정 덮어쓰기는 원본 설정에 추가 변경 사항을 적용하는 클라이언트 처리 방식이며 모든 YAML 파일에서 공통으로 사용하는 최상위 필드는 아닙니다. Clash Nyanpasu의 설정 생성 과정에는 클라이언트 관리 항목, 설정 병합, 스크립트 처리가 포함될 수 있습니다. 설정 덮어쓰기 메뉴, 실행 순서, 지원 문법은 클라이언트마다 다르므로 특정 클라이언트의 확장 설정을 그대로 mihomo 설정인 것처럼 코어에 전달해서는 안 됩니다.

설정 덮어쓰기를 이해할 때는 입력, 변환, 출력을 구분하세요. 입력은 구독 또는 로컬 프로필이고, 변환은 필드 덮어쓰기, 목록 수정, 스크립트 변경 등의 과정이며, 출력은 코어가 읽는 실행 설정입니다. 문제를 해결할 때는 변경이 어느 단계에서 적용됐는지 확인하고 최종 출력 파일을 살펴보세요. 설정 덮어쓰기 편집기에 원하는 필드가 보인다는 사실만으로 이후 단계에서 다시 덮어쓰이지 않았다고 단정할 수 없습니다.

# 일반 필드 병합을 지원하는 설정 덮어쓰기 기능에서만 사용
mode: rule
log-level: info
dns:
  enable: true
  enhanced-mode: fake-ip

이 예제는 유지할 필드 값을 보여 주지만 모든 클라이언트가 같은 병합 알고리즘을 사용하는 것은 아닙니다. 일부 구현은 맵을 재귀적으로 병합하고 다른 기능은 객체 전체를 교체합니다. dns 전체가 교체되면 구독에 있던 업스트림 목록, 필터, 정책도 함께 사라질 수 있습니다. 따라서 적용 후에는 enable이 참으로 바뀌었는지만 확인하지 말고 최종 dns 객체 전체를 살펴보세요.

목록 추가, 앞에 삽입, 교체

맵 병합과 목록 병합은 구분해서 이해해야 합니다. 수신 포트는 단일 값이므로 보통 그대로 덮어쓸 수 있지만, 규칙과 정책 그룹은 구조가 있는 목록이며 처리 방식은 전체 교체, 뒤에 추가, 앞에 삽입, 스크립트 자체 처리 등으로 달라질 수 있습니다. 짧은 rules 목록을 작성하면 구독의 나머지 항목이 자동으로 유지된다고 가정하지 마세요. 해당 기능이 교체 방식으로 동작하면 기존 분류 규칙이 모두 사라질 수 있습니다.

규칙에서는 순서가 특히 중요합니다. 개인 예외 규칙은 일반 규칙보다 앞에 넣어야 하는 경우가 많습니다. MATCH 뒤에 추가하면 기대한 대로 매칭되지 않습니다. 정책 그룹은 고유한 이름을 찾아 구성원을 수정해야 하며 같은 이름의 그룹을 단순히 다시 추가해서는 안 됩니다. 자동 업데이트 설정에서는 같은 입력에 같은 처리를 반복해도 규칙이나 구성원이 중복으로 늘어나지 않도록 설정 덮어쓰기 과정의 멱등성을 보장해야 합니다.

구독 업데이트와 개인 설정의 역할 분리

서비스 제공자가 관리하는 프록시 매개변수와 리소스 모음은 구독에서 관리하는 것이 적합합니다. 로컬 수신 포트, 로그 설정, 개인적으로 필요한 명확한 접속 규칙은 직접 관리할 수 있습니다. 역할을 나눈다고 해서 모든 로컬 값을 구독 위에 덮어써야 하는 것은 아닙니다. 서비스 제공자가 지정한 프로토콜 매개변수를 오래된 덮어쓰기 설정으로 고정하면 업데이트 후 인증이나 전송 방식이 호환되지 않을 수 있습니다. 필요한 차이만 설정 덮어쓰기로 관리하세요.

스크립트 변경은 일반 필드 병합보다 유연하지만 적용 범위를 더 꼼꼼하게 확인해야 합니다. 처리 전에 대상 배열이 있는지 확인하고, 원하는 그룹을 찾은 경우에만 수정하세요. 그룹을 찾지 못했을 때 불완전한 객체를 조용히 새로 만들면 안 됩니다. 원격 설정 업데이트로 그룹 이름이 바뀌는 경우가 흔하므로 스크립트는 이해하기 쉬운 오류를 내거나 안전하게 건너뛰어야 합니다. 불러올 수 없는 실행 설정을 생성해서는 안 됩니다. 실행 순서가 바뀌면 참조 관계도 다시 검증하세요.

수정하기 전에 정상적으로 작동하는 프로필과 설정 덮어쓰기 파일을 백업하세요. 구독 자격 증명이 포함된 파일을 공개 코드 저장소에 올리지 않도록 주의해야 합니다. 백업에는 설정 출처, 개인 규칙, 필요한 클라이언트 설정이 포함되어야 합니다. 임시로 생성된 실행 파일만 복사하면 기존 업데이트 관계를 복원하지 못할 수 있습니다. DNS만 바꾸거나 규칙 하나만 앞에 추가하는 식으로 변경 목표를 기록해 두면 되돌릴 범위를 크게 줄일 수 있습니다.

설정 덮어쓰기를 적용한 후에는 세 단계로 검증하세요. 먼저 YAML 문법을 확인하고, 다음으로 그룹 및 제공자 참조가 모두 유효한지 살펴본 뒤, 새 연결을 만들어 실제 동작을 확인합니다. 업데이트 후 갑자기 작동하지 않으면 개인 설정을 모두 삭제하지 말고 리소스 변경과 설정 덮어쓰기 대상이 여전히 존재하는지 비교하세요. 클라이언트, 코어, 구독을 한꺼번에 교체하는 것보다 처리 단계를 하나씩 비활성화하며 충돌을 찾는 편이 유효한 정보를 보존하기 쉽습니다. 설정 출처의 기본 개념은 프로필 관리 안내에서 다시 확인할 수 있습니다.

SECTION 08 / VALIDATE AND ISOLATE

설정 검증과 문제 원인 찾기

출력을 먼저 확인한 다음 트래픽을 검증하세요

설정은 문법, 의미, 실행 동작의 세 단계로 점검해야 합니다. 문법 검사는 들여쓰기, 따옴표, 목록 구조를 확인합니다. 의미 검사는 필드 지원 여부, 정책 참조, 리소스 형식을 살펴봅니다. 실행 검사는 포트, 네트워크 연결 여부, 실제 매칭 결과를 확인합니다. 한 단계의 통과가 다음 단계의 검사를 대신하지는 않습니다. 특히 원격 리소스가 아직 로드되지 않았거나 시스템 프록시가 트래픽을 받지 않는다면 파일을 읽는 데 성공해도 앱에서 사용할 수 있는 것은 아닙니다.

mihomo를 직접 실행할 수 있다면 테스트 옵션을 사용해 지정한 파일을 검사할 수 있습니다. 클라이언트에서 실제로 실행 중인 코어를 사용하고, 상대 경로의 리소스를 찾을 수 있도록 같은 작업 디렉터리나 지정된 데이터 디렉터리에서 테스트하세요. 데스크톱 클라이언트에 설정 테스트나 실행 설정 확인 기능이 있다면 우선 해당 기능을 사용하세요. 별도의 프로세스를 실행해 기존 수신 서비스와 충돌하는 일을 방지할 수 있습니다.

# 설정 파일이 있는 디렉터리에서 실행하고 실행 파일 위치에 맞춰 명령을 조정하세요
mihomo -t -f ./config.yaml

# Windows PowerShell에서 현재 디렉터리에 해당 실행 파일이 있는 경우
.\mihomo.exe -t -f .\config.yaml

테스트 결과에 표시된 줄 번호는 파싱이 실패한 위치인 경우가 많지만 실제 원인은 바로 앞 줄에 있을 수 있습니다. 예를 들어 따옴표가 닫히지 않았거나 들여쓰기가 잘못됐을 수 있습니다. 여러 오류가 같은 원인에서 비롯될 수 있으므로 가장 먼저 표시된 명확한 오류부터 고치고 다시 테스트하세요. 필드 미지원 메시지가 나타나면 다른 위치로 옮겨 보지 말고 코어 유형과 현재 옵션의 지원 여부를 확인하세요.

연결 경로를 따라 원인 범위 좁히기

첫째, 클라이언트와 코어가 정상적으로 시작됐고 로그에 수신 실패가 없는지 확인합니다. 둘째, 앱이 올바른 프록시 주소에 실제로 연결하는지 확인하고 필요한 경우 명시적 프록시로 테스트합니다. 셋째, DNS가 예상한 경로로 목적지를 확인할 수 있는지 살펴봅니다. 넷째, 규칙과 정책 그룹의 최종 결정 결과를 확인합니다. 마지막으로 원격 프로토콜의 핸드셰이크와 서버 응답을 점검합니다. 이 순서로 확인하면 로컬 설정 문제와 원격 연결 문제를 구분하기 쉽습니다.

# 로컬 HTTP 프록시 진입점과 이후 요청 경로만 확인
curl --proxy http://127.0.0.1:7890 --head https://example.com

# SOCKS 테스트에서 프록시가 목적지 도메인을 확인하도록 설정
curl --proxy socks5h://127.0.0.1:7890 --head https://example.com

이 명령을 실행하려면 시스템에 curl이 설치되어 있어야 하며 포트가 실행 설정과 일치해야 합니다. 테스트 웹사이트는 요청 경로를 확인하기 위한 용도입니다. 명령이 실패했다고 해서 전체 설정이 잘못됐다고 단정하지 말고 구체적인 오류를 살펴보세요. 연결이 거부되면 우선 로컬 수신 상태를 확인하고, 도메인 확인이 실패하면 DNS를 확인하세요. 프록시 핸드셰이크 오류라면 프로토콜 진입점과 인증을 점검합니다. 오류가 발생한 단계에 따라 해결 방법도 달라야 합니다.

운영체제별 차이와 최소 범위 복구

Windows의 시스템 프록시와 방화벽 설정, macOS의 서비스 권한, Linux 데스크톱 환경의 프록시 설정은 트래픽을 가로채는 범위에 영향을 주지만 YAML의 기본 구조를 바꾸지는 않습니다. 시스템 경고가 표시되면 규칙 목록에서 해결 방법을 찾지 말고 설치 및 권한 관련 계층을 확인하세요. macOS 설정 경로는 설치 권한과 키체인 안내에서 확인할 수 있습니다. 필요한 권한은 실제 설치 방식에 따라 다릅니다.

최소 범위 복구는 설정 전체를 삭제하는 것이 아니라 가장 최근 변경 하나를 취소하면서 문제 증거를 보존하는 것입니다. 먼저 새로 추가한 설정 덮어쓰기를 끄고, 다음으로 필드 하나를 복원한 뒤, 마지막에 백업 프로필 전환을 고려하세요. 한 번에 변수 하나만 바꾸고 새 연결에서 같은 테스트를 반복합니다. 클라이언트, 코어, 구독을 동시에 업데이트하면 어느 단계에서 결과가 달라졌는지 판단하기 어렵고 문제를 재현하기도 힘듭니다.

문제 해결 정보를 공유할 때는 오류 문구, 필드 계층, 작업 순서를 남기고 구독 URL, 비밀번호, 인증 매개변수, 개인 접속 대상은 삭제하세요. 스크린샷은 읽을 수 있는 오류 정보 대신 사용할 수 없으며, 전체 설정을 그대로 공개해서도 안 됩니다. 문제를 해결한 뒤에는 로그 수준을 일반 값으로 되돌리고 임시 테스트 규칙을 삭제한 다음 최종적으로 유효한 변경 사항을 기록하세요. 필드 개념은 용어 안내에서 확인할 수 있습니다. 가져오기와 검증 과정을 다시 진행해야 한다면 빠른 시작 가이드로 돌아가 시스템 설정 안내와 최초 사용 절차를 혼동하지 않도록 하세요.