Clash YAML 설정 파일 가이드

1. YAML 구조와 설정 로드 경로

원본 파일과 실행 파일 구분하기

Clash 설정은 노드만 기록하는 목록이 아닙니다. 최상위에는 보통 수신 포트, 프록시 모드, DNS, 노드, 정책 그룹, 규칙이 함께 들어갑니다. 클라이언트가 구독을 가져오면 원격 설정을 저장한 뒤 로컬 옵션을 덧붙이고, 마지막으로 코어에 전달할 실행 파일을 만들 수 있습니다. 따라서 편집기에서 보는 구독 내용과 코어가 실제로 읽는 내용은 다를 수 있습니다. 문제를 점검할 때는 현재 선택한 설정의 이름을 기록하고 클라이언트에서 실행 설정을 확인하는 메뉴를 찾으세요. 사용하지 않는 파일을 수정한 뒤 계속 재시작하는 일을 막을 수 있습니다.

원본 구독은 서버에서 관리하는 노드와 그룹을 보존하는 데 적합하고, 로컬 확장 설정은 개인 규칙을 저장하는 데 적합합니다. 두 종류를 분리하면 업데이트 과정에서 서로 덮어쓸 가능성을 줄일 수 있습니다. 클라이언트에서 확장 설정의 적용 범위를 명확히 표시하지 않는다면, 먼저 확인하기 쉬운 규칙 하나로 테스트한 뒤 현재 구독에만 적용되는지 확인하세요. 파일 이름만으로 로드 여부를 판단하지 마세요. 화면에서 선택한 항목, 로그의 로드 결과, 실제 요청의 규칙 기록이 서로 일치해야 합니다.

들여쓰기, 자료형, 참조 이름

YAML은 들여쓰기로 계층을 표현하므로 공백 두 칸을 일관되게 사용하고 탭은 섞지 않는 것이 좋습니다. 콜론 뒤의 공백으로 키와 값을 구분하고, 하이픈은 목록 항목을 나타냅니다. 같은 목록에 있는 각 객체의 속성은 들여쓰기를 맞추세요. 포트는 보통 정수로 쓰고, 스위치 값은 소문자 불리언으로 씁니다. 불리언 값을 따옴표로 감싸면 문자열이 되어 일부 필드에서 자료형 오류가 발생할 수 있습니다. 노드 이름과 정책 그룹 이름은 참조 식별자이므로 대소문자, 공백, 문장 부호까지 일치해야 하며 비슷한 이름을 자동으로 보정하지 않습니다.

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

proxies: []

proxy-groups:
  - name: 출구 선택
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,출구 선택

위 예제는 파싱과 참조 관계를 확인하기 위한 직결 전용 기본 설정이며, 프록시 출구는 제공하지 않습니다. 노드 목록이 비어 있어도 유효하며, 정책 그룹은 내장된 DIRECT를 참조합니다. 노드를 추가할 때는 먼저 proxies에 정의한 뒤 이름을 정책 그룹에 넣으세요. 규칙은 마지막으로 정책 그룹을 참조해 요청에서 규칙으로, 규칙에서 정책으로, 정책에서 출구로 이어지는 흐름을 만듭니다. 복잡한 필드를 한꺼번에 많이 복사하는 것보다 이 흐름을 이해하는 것이 중요합니다.

따옴표와 중복 키

비밀번호, 특수 문자가 들어간 이름, 다른 자료형으로 해석될 수 있는 문자열에는 따옴표를 사용하는 것이 좋습니다. 문자열에 콜론 뒤 공백, 주석 기호 또는 줄바꿈이 포함되면 파싱 결과에 특히 주의하세요. 작은따옴표 안에 작은따옴표를 넣으려면 두 번 연속 입력해야 합니다. 큰따옴표에서는 이스케이프를 사용할 수 있으며, 백슬래시도 규칙에 맞게 처리해야 합니다. 웹 페이지에서 표시용으로 사용하는 굽은 따옴표를 YAML 따옴표로 착각하지 마세요. 주석은 내용을 설명할 뿐 필드의 의미를 바꾸지 않으며, 필수 매개변수를 대신할 수도 없습니다.

같은 계층에 dns, rules, proxy-groups를 중복으로 정의하지 마세요. 일부 파서는 중복 키를 거부하고, 일부 처리 과정에서는 나중 값만 남을 수 있어 결과를 예측하기 어렵습니다. dns 키가 각각 들어 있는 예제 두 개를 이어 붙인다고 DNS 설정이 병합되는 것은 아닙니다. 상위 키는 하나만 남기고 필요한 하위 필드를 그 안으로 옮기세요. 목록도 마찬가지입니다. 규칙을 추가할 때는 기존 rules 목록에 넣어야 하며 같은 이름의 최상위 키를 새로 만들면 안 됩니다.

코어 명령줄에 접근할 수 있다면 아래 테스트 명령을 사용할 수 있습니다. 실행 파일 이름과 설정 경로는 기기에 맞게 조정하세요. 그래픽 클라이언트에 설정 검사 기능이 있다면 해당 메뉴를 우선 사용하세요. 문법 검사를 통과해도 파일을 읽을 수 있다는 뜻일 뿐, 원격 노드에 연결되거나 정책이 예상대로 동작한다는 보장은 없습니다. 시작 후에는 수신 포트, 규칙 매칭, 출구 선택도 확인해야 합니다. 로그를 자세히 읽는 방법은 실행 로그로 문제 찾기를 참고하세요.

mihomo -t -f config.yaml

2. 포트, 프록시 모드 및 공통 필드

수신 포트는 요청을 받는 역할만 합니다

port는 HTTP 프록시 수신 포트, socks-port는 SOCKS 수신 포트이며 mixed-port는 하나의 포트에서 HTTP와 SOCKS 요청을 모두 받습니다. 이 값은 애플리케이션이 로컬 코어에 연결하는 입력 경로를 가리키며 원격 노드의 포트가 아닙니다. 애플리케이션에 로컬 주소와 mixed-port를 입력하면 요청이 코어로 들어갑니다. 원격 노드 연결 방식은 노드 필드에서 정합니다. 처음 설정할 때는 보통 혼합 포트 하나만 사용하면 되며, 별도 입력 경로가 꼭 필요할 때만 다른 포트를 추가하세요.

포트 충돌은 클라이언트 두 개를 동시에 실행하거나 이전 코어가 종료되지 않았을 때, 또는 다른 프로그램이 같은 주소를 이미 수신 중일 때 주로 발생합니다. 주소 사용 중 오류가 나면 먼저 중복 프로세스를 종료한 다음 포트를 바꿀지 결정하세요. 포트를 변경했다면 브라우저의 수동 프록시 설정, 터미널 환경 변수, LAN 기기의 설정도 함께 업데이트해야 합니다. 클라이언트에 시작 성공이 표시되어도 모든 앱이 새 포트를 사용한다는 뜻은 아닙니다. 클라이언트 스위치만 보지 말고 앱 자체의 프록시 입력 설정을 확인하세요.

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

규칙, 전역, 직결 모드

mode: rule은 rules 순서에 따라 출구를 결정하고, mode: global은 트래픽을 전역 정책으로 보내며, mode: direct는 직결합니다. 여기서 전역은 이미 코어에 들어온 트래픽에만 적용되며 모든 앱을 자동으로 가로채지는 않습니다. 시스템 프록시를 따르지 않는 프로그램은 전역 모드로 바꿔도 계속 직결할 수 있습니다. 모드가 적용되는지 확인하려면 먼저 연결 기록에 요청이 나타나는지 확인한 다음 해당 출구를 점검하세요. 모드 전환 방법은 프록시 모드 안내를 참고하세요.

전역 모드는 분기 규칙 때문에 문제가 생기는지 임시로 확인할 때 유용하지만, 모든 네트워크 문제를 해결하는 버튼처럼 사용해서는 안 됩니다. 규칙 모드에서는 실패하고 전역 모드에서는 성공한다면 매칭된 규칙과 선택된 정책 그룹을 먼저 확인하세요. 두 모드에서 모두 실패한다면 노드 매개변수, 네트워크 연결, 이름 해석 경로를 점검하는 편이 좋습니다. 직결 모드로 바꿔도 운영체제 프록시 설정은 자동으로 해제되지 않습니다. 앱이 로컬 수신 포트에 연결된 뒤 코어가 직결할 수도 있으므로, 코어를 종료하기 전에 시스템 프록시가 정상적으로 복구되는지 확인하세요.

수신 범위와 관리 인터페이스

allow-lan과 bind-address는 함께 살펴봐야 합니다. 전자는 LAN에서 사용할 수 있는지, 후자는 수신 주소를 제한합니다. 로컬에서만 사용할 때는 루프백 주소로 제한할 수 있습니다. 공유가 꼭 필요하다면 실제 네트워크 인터페이스, 방화벽, 인증 요구사항을 확인한 뒤 여세요. 모든 인터페이스로 수신 주소를 설정해도 외부 기기에서 반드시 연결되는 것은 아니며 라우팅과 시스템 보안 규칙에도 좌우됩니다. 휴대전화 연결 문제를 점검하려고 서비스를 인터넷에 그대로 노출하지 마세요.

프록시 입력 포트와 external-controller 관리 인터페이스는 서로 다른 기능입니다. 관리 인터페이스는 설정, 정책, 연결 상태를 제어하기 위한 것이며 브라우저 프록시 포트로 입력하면 안 됩니다. 클라이언트가 인터페이스 주소와 인증 정보를 자동으로 생성하는 경우가 많아 직접 바꾸면 화면에서 연결할 수 없게 될 수 있습니다. 일반적인 데스크톱 사용이라면 예제를 따라 관리 인터페이스를 추가로 열 필요가 없습니다. 원격 관리가 필요하면 프록시 수신 포트와 동일한 신뢰 범위를 적용하지 말고 접근 제한을 별도로 설계하세요.

일상적인 사용에는 보통 log-level을 info로 두면 충분합니다. 문제를 찾을 때만 잠시 debug로 바꾸고 한 번 재현한 뒤 원래대로 돌리세요. 로그에는 방문 도메인, 노드 이름, 로컬 경로가 포함될 수 있으므로 공유 전에 개인정보를 삭제해야 합니다. 공통 필드가 시작할 때마다 원래 값으로 돌아간다면 클라이언트 설정 화면에서 같은 옵션을 관리하는지 먼저 확인하세요. 그렇다면 설정 화면에서 변경하고 자동 생성 파일을 계속 수정하지 마세요. 브라우저와 터미널의 동작이 다르다면 시스템 프록시 경로별 문제 해결도 참고하세요.

3. 프록시 노드 필드와 외부 노드 모음

노드 객체의 공통 필드

proxies는 노드 객체 목록이며 각 노드에는 보통 name, type, server, port가 들어갑니다. name은 정책 그룹에서 참조하고, type은 프로토콜과 나머지 필드의 해석 방식을 정합니다. server는 원격 주소, port는 원격 서비스 포트입니다. 프로토콜에 따라 인증 필드, 암호화 방식, 전송 설정도 달라집니다. type만 다른 프로토콜로 바꾸고 기존 매개변수를 그대로 두면 자동으로 호환될 것이라고 기대해서는 안 됩니다. 클라이언트가 객체를 파싱할 수 있어도 원격 서버가 해당 서비스를 제공한다는 뜻은 아닙니다.

구독에서 제공한 노드 매개변수는 TLS, 전송 계층, 프로토콜 전용 필드를 특히 주의해 그대로 유지하세요. 일부 공유 링크는 클라이언트에서 노드 객체로 변환할 수 있지만, 변환 결과도 코어가 지원하는 범위 안에서만 사용할 수 있습니다. 클라이언트 이름이나 화면 구성이 비슷하다고 해서 같은 코어가 내장된 것은 아닙니다. 클라이언트를 고를 때는 먼저 다운로드 센터를 확인하고 Clash Plus를 우선 고려하세요. 기존 설정을 옮기기 전에는 클라이언트 비교에서 플랫폼과 설정 호환성을 확인하세요.

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

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

위 예제는 Shadowsocks 노드와 정책 그룹의 참조 관계를 보여줍니다. 도메인과 비밀번호는 설명용이므로 실제 서비스 매개변수로 바꿔야 합니다. cipher는 서버 설정과 일치해야 하며 복잡할수록 좋은 것은 아닙니다. udp는 해당 노드가 관련 UDP 트래픽을 처리하도록 허용하지만, 원래 UDP를 지원하지 않는 서비스에 기능을 추가하지는 않습니다. 노드 이름을 바꾸면 이를 직접 참조하는 모든 정책 그룹의 이름도 함께 바꿔야 합니다. 그렇지 않으면 참조 검사에 실패할 수 있습니다.

TLS와 전송 계층은 임의로 켜고 끄는 최적화 옵션이 아닙니다

TLS를 사용하는 프로토콜에서 server, servername, 인증서 검증은 각각 역할이 다릅니다. server는 연결 대상이며, servername은 보통 TLS 핸드셰이크의 서버 이름 표시와 인증서 이름 확인에 사용됩니다. 두 값은 같을 수도 다를 수도 있으므로 서비스에서 제공한 매개변수에 맞춰 입력해야 합니다. 연결에 실패했다고 먼저 인증서 검증을 건너뛰지 마세요. 기기 시간, 서버 이름, 인증서 유효성, 네트워크 경로를 먼저 확인해 설정 오류가 계속 가려지지 않도록 하세요.

WebSocket 경로, 요청 헤더, 기타 전송 매개변수도 원격 서버 설정과 일치해야 합니다. 서버 주소를 올바르게 복사했어도 경로나 요청 헤더를 빠뜨리면 핸드셰이크가 실패할 수 있습니다. 점검은 아래 계층부터 진행하세요. 도메인이 해석되는지, 대상 포트에 연결되는지, TLS가 성공하는지, 프로토콜 인증이 통과하는지 확인한 뒤 규칙과 대상 사이트를 살펴보세요. 로그에 인증 실패가 명확히 표시된다면 DNS나 정책 그룹 순서를 반복해서 바꾸지 말고 노드 매개변수와 계정 상태를 확인하세요.

proxy-providers로 외부 노드 관리하기

proxy-providers는 노드 모음을 기본 설정 파일에서 분리합니다. 노드를 정기적으로 업데이트하면서 규칙과 정책 그룹은 안정적으로 유지하고 싶을 때 유용합니다. 제공자 콘텐츠는 코어가 지원하는 노드 모음 형식이어야 하며, 아무 웹 페이지나 사용할 수 있는 것은 아닙니다. 전체 클라이언트 구독과 형식이 같다고 단정할 수도 없습니다. 기본 설정의 정책 그룹은 use로 제공자 이름을 참조합니다. 제공자 이름을 일반 노드처럼 proxies에 넣으면 안 됩니다. 두 목록은 참조 관계가 다르므로 혼용하지 마세요.

proxy-providers:
  로컬 노드:
    type: file
    path: ./providers/local.yaml
    health-check:
      enable: false

proxy-groups:
  - name: 출구 선택
    type: select
    use:
      - 로컬 노드
    proxies:
      - DIRECT

로컬 파일은 다음과 같은 구조로 사용할 수 있습니다. 상대 경로는 실제 설정 디렉터리와 클라이언트 실행 방식에 따라 달라지므로 데스크톱 바로 가기가 있는 폴더를 기준으로 한다고 단정할 수 없습니다. 먼저 파일을 실제로 읽는지 확인한 뒤 노드가 표시되는지 점검하세요. 원격 제공자는 업데이트 간격, 캐시, 요청 출구도 영향을 받습니다. 업데이트에 실패하면 다운로드 요청과 기존 캐시를 각각 확인하세요. 설정을 전부 바로 삭제하지 마세요.

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

구독 링크에는 계정 인증 정보가 포함될 수 있으므로 자격 증명처럼 안전하게 보관해야 합니다. 설정을 공유할 때는 비밀번호뿐 아니라 원격 제공자 주소와 요청 헤더도 확인하세요. 서버 업데이트로 노드 이름이 바뀌면 수동으로 입력한 단일 노드 참조가 끊길 수 있습니다. 제공자를 통해 연결한 정책 그룹은 노드 모음 변경을 따라가기 쉽습니다. 노드를 고를 때는 테스트 결과뿐 아니라 용도, 지역, 트래픽 규칙도 고려해야 합니다. 자세한 판단 방법은 노드 선택 방법을 참고하세요.

4. 정책 그룹 유형과 참조 관계

정책 그룹은 출구를 결정하는 계층입니다

정책 그룹은 규칙 참조와 실제 노드를 분리합니다. 규칙은 이름이 안정적인 그룹을 가리키고, 그룹 안에서 노드나 다른 그룹을 선택합니다. 이렇게 하면 노드를 바꿀 때 모든 규칙을 다시 작성할 필요가 없습니다. 그룹 이름과 노드 이름은 서로 겹치지 않게 알아보기 쉬운 이름으로 정하세요. 설계할 때는 요청이 한 방향으로 흐르는 구조를 먼저 그려 보세요. 규칙에서 서비스 그룹으로, 서비스 그룹에서 선택 그룹으로, 선택 그룹에서 실제 노드나 DIRECT로 이어져야 합니다. 모든 경로는 끝나야 하며 자기 자신으로 되돌아가면 안 됩니다.

select는 수동 선택, url-test는 테스트 결과에 따른 자동 선택, fallback은 순서에 따라 사용 가능한 항목을 찾는 방식, load-balance는 설정된 정책에 따라 연결을 분배하는 방식입니다. 각 유형이 해결하는 문제는 다르며 성능 순위를 나타내는 네 단계가 아닙니다. 출구를 안정적으로 유지해야 하는 로그인 서비스에서는 자동 전환이 잦으면 다시 인증해야 할 수 있습니다. 일반적인 웹 브라우징에는 자동 선택이 수동 관리를 줄여 줄 수 있습니다. 모든 노드를 같은 자동 그룹에 넣기보다 실제 용도에 맞는 유형을 고르세요.

proxy-groups:
  - name: 출구 선택
    type: select
    proxies:
      - 자동 선택
      - DIRECT

  - name: 자동 선택
    type: url-test
    use:
      - 로컬 노드
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

rules:
  - MATCH,출구 선택

이 설정 조각은 이전 장의 로컬 노드 제공자를 사용합니다. url은 실제로 검사할 대상, interval은 검사 간격(초), tolerance는 자동 전환에 적용되는 지연 허용 범위(밀리초)입니다. 검사 대상은 현재 용도를 대표할 수 있어야 하며 지속적으로 접속할 수 있어야 합니다. 예제 주소는 외부 페이지 리소스가 아니므로 이 페이지의 브라우저가 자동으로 불러오지 않습니다. 검사 요청에 성공해도 해당 테스트 경로를 사용할 수 있다는 뜻일 뿐 모든 사이트, 동영상 서비스, UDP 앱이 정상 작동한다는 보장은 없습니다.

자동 선택과 장애 복구의 한계

url-test는 보통 테스트 조건에서 결과가 좋은 후보를 선호하고, fallback은 순서와 사용 가능성을 더 중시합니다. 고정 출구를 우선 사용하다가 실패하면 예비 출구로 전환하고 싶다면, 테스트 시간을 줄이는 데만 집중하는 방식보다 fallback이 더 적합할 수 있습니다. 검사 실패는 대상 주소 제한, 일시적인 이름 해석 오류, 네트워크 변동 때문일 수도 있으므로 노드가 완전히 작동하지 않는다고 바로 판단하지 마세요. 실제 업무에서 먼저 확인한 뒤 검사 대상을 바꾸거나 관찰 시간을 늘리세요.

load-balance는 여러 회선을 하나의 다운로드 연결로 합치지 않으며 모든 연결이 같은 공인 IP를 사용한다고 보장하지도 않습니다. 분배 정책에 따라 대상과 연결을 처리하는 방식이 달라지므로, 사용 전에 출구가 바뀌어도 되는지 확인하세요. 계정 위험 관리, 결제, 장시간 연결이 필요한 앱은 보통 출구를 고정하는 편이 적합합니다. 부하 분배를 켜도 단일 연결의 속도는 실제로 거치는 노드, 원격 서비스, 로컬 네트워크에 따라 달라집니다. 그룹 안의 노드 수를 총 대역폭으로 계산하면 안 됩니다.

이름, 순환 참조, 선택 상태 유지

그룹은 다른 그룹을 참조할 수 있지만 순환 구조를 만들면 안 됩니다. 예를 들어 서비스 그룹이 출구 그룹을 참조하고 출구 그룹이 다시 서비스 그룹을 참조하면 실제 출구에 도달할 수 없습니다. 그룹 계층을 늘리기 전에 각 계층에 독립적인 용도가 있는지 확인하세요. 중첩이 지나치면 화면은 정상적으로 보여도 최종적으로 어떤 노드를 쓰는지 파악하기 어렵습니다. 문제를 찾을 때는 현재 선택된 항목에서 시작해 실제 노드, DIRECT 또는 REJECT가 나타날 때까지 한 단계씩 따라간 다음 연결 기록과 대조하세요.

클라이언트는 수동 선택 상태를 저장할 수 있어 설정을 다시 불러온 뒤에도 이전에 선택한 그룹 항목을 유지할 수 있습니다. 따라서 YAML에서 후보 순서를 바꿔도 현재 출구가 바뀌지 않을 수 있습니다. 새 설정을 불러왔는데도 출구가 그대로라면 노드를 계속 재정렬하지 말고 정책 그룹의 현재 선택과 선택 상태 저장 방식을 확인하세요. 초기화해야 한다면 클라이언트의 선택 기능을 우선 사용하세요. 설정 디렉터리 전체를 삭제하면 구독과 로컬 규칙까지 함께 잃을 수 있습니다.

5. DNS 설정과 Fake-IP 동작 방식

먼저 앱이 누구에게 이름 해석을 맡기는지 확인하세요

DNS 설정은 코어의 도메인 해석 방식을 정하지만 앱이 반드시 코어 DNS를 사용하는 것은 아닙니다. 시스템 리졸버, 브라우저의 보안 DNS, 앱 자체 DNS, TUN 가로채기가 동시에 작동할 수 있습니다. Clash DNS 유출이 의심된다면 설정을 바꾸기 전에 어떤 요청이 예상한 입력 경로를 우회하는지 확인하세요. nameserver를 암호화 주소로 바꾸는 것만으로 기기의 모든 DNS 요청이 프록시를 거친다고 증명할 수는 없습니다. 암호화는 전송 내용을 읽기 어렵게 하는 문제를 해결하고, 프록시 출구와 요청 가로채기는 별개의 문제입니다.

dns.enable은 코어 DNS 기능을 켜고, listen은 수신 주소를 정하며, nameserver는 일반 상위 DNS 서버를 지정합니다. default-nameserver는 보통 상위 DNS 서버 주소에 포함된 도메인을 해석해 시작 단계의 기본 이름 해석을 돕습니다. proxy-server-nameserver는 프록시 노드 서버 도메인에 별도의 해석 경로를 지정할 수 있습니다. 대상 사이트 도메인 해석과 프록시 서버 도메인 해석은 구분해야 합니다. 후자가 아직 연결되지 않은 프록시에 의존하면 초기 연결 순환이 생겨 노드 도메인이 계속 해석되지 않을 수 있습니다.

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"
    - "*.local"
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5

이 설정 조각은 필드의 계층을 보여줄 뿐 모든 네트워크에 적합하다는 뜻은 아닙니다. 상위 DNS 주소는 현재 네트워크에서 연결 가능해야 합니다. 네트워크를 바꾼 뒤에는 해석 지연 시간과 반환 결과를 다시 테스트하세요. 루프백 주소의 포트가 수신 중이어도 시스템 DNS가 자동으로 그곳을 사용하는 것은 아닙니다. 클라이언트, TUN, 시스템 설정 중 하나가 DNS 요청을 해당 주소로 보내야 합니다. PC에서 시스템 HTTP 프록시만 켜져 있고 SOCKS를 사용하는 앱이 로컬에서 직접 이름을 해석한다면 두 앱의 DNS 경로는 다를 수 있습니다.

Fake-IP와 실제 주소 매핑

Fake-IP는 앱에 매핑용 가상 주소를 반환하고 코어는 그 주소에 대응하는 원래 도메인을 기록합니다. 이후 연결이 다시 코어를 통과하면 매핑을 바탕으로 도메인을 복원해 규칙 매칭에 사용할 수 있습니다. 가상 주소를 공인 인터넷의 실제 대상 주소처럼 취급하지 않습니다. Fake-IP는 공용 DNS에서 받은 또 다른 실제 해석 결과가 아니며 라우터를 통해 인터넷으로 전달해서도 안 됩니다. 설정이 올바르려면 DNS 질의와 연결이 같은 매핑 정보를 인식하는 처리 경로를 거쳐야 합니다.

일부 LAN 검색, 기기 관리, 실제 주소를 필요로 하는 프로그램은 가상 주소와 호환되지 않을 수 있습니다. 이런 경우 필요에 따라 fake-ip-filter로 해당 도메인을 제외할 수 있습니다. 제외하면 보통 일반 해석 결과를 반환하지만, 그 도메인에 직결 규칙이 추가되는 것은 아닙니다. 최종 출구는 여전히 rules에서 결정합니다. 앱 하나의 호환성 문제 때문에 모든 도메인을 제외하면 Fake-IP의 도메인 매핑 기능을 잃게 됩니다. 구체적인 도메인 접미사만 지정하고 이전 캐시를 지운 뒤 영향을 확인하세요.

도메인별 상위 DNS와 해석 경로

nameserver-policy는 도메인별로 상위 DNS 서버를 지정하므로 사내 도메인, LAN 접미사, 공용 도메인에 서로 다른 DNS가 필요한 환경에 적합합니다. 아래에는 사내 DNS를 예시 주소로 표시합니다. 해당 주소가 실제 네트워크의 DNS 서버일 때만 사용하세요. 정책이 매칭되어도 상위 서버까지 가는 경로가 열려 있어야 합니다. 그렇지 않으면 설정이 올바르더라도 시간 초과가 발생합니다. 사무실 네트워크에서만 접속되는 서버를 모든 네트워크에 영구적으로 적용하지 마세요.

dns:
  nameserver-policy:
    "+.corp.example.com":
      - 192.168.1.1

respect-rules 같은 설정은 DNS 상위 서버 연결이 라우팅 규칙을 따를지에 영향을 줍니다. 관련 의존성을 이해하고 노드 서버 도메인의 별도 해석 경로를 마련한 뒤 사용하세요. 모든 DNS 요청을 먼저 프록시로 보내야 하는데 프록시 서버 이름도 같은 DNS를 통해서만 해석할 수 있다면 초기화 단계에서 막힙니다. 도메인별 DNS 규칙과 프록시 분기 규칙은 서로 다른 체계이므로 따로 확인해야 합니다. 어떤 도메인이 지정된 상위 DNS를 사용한다고 해서 이후 연결도 반드시 같은 출구를 사용한다고 단정하지 마세요.

DNS를 변경한 뒤에는 기존 연결을 닫고 클라이언트와 시스템 캐시를 지우세요. 필요하다면 내장 캐시를 사용하는 앱도 재시작한 다음 전체 요청을 다시 테스트하세요. 앱이 어떤 해석 방식을 사용하는지, 반환 주소의 유형은 무엇인지, 연결이 어떤 규칙에 매칭됐는지 기록하세요. IPv6도 별도로 확인해야 합니다. 코어 관련 옵션을 꺼도 시스템의 다른 경로에서 IPv6 요청이 나가지 않는다는 뜻은 아닙니다. 문제가 계속되면 자주 묻는 질문의 네트워크 점검 순서에 따라 범위를 좁히세요. 보안 및 DNS 설정을 여러 개 한꺼번에 끄지 마세요.

6. 규칙 문법, 규칙 모음, 매칭 순서

규칙은 위에서 아래로 확인하고, 매칭되면 처리를 멈춥니다

rules는 순서가 있는 목록이며 구체성에 따라 자동 정렬되는 집합이 아닙니다. 먼저 매칭된 규칙이 출구를 결정하고 이후 규칙은 해당 요청을 처리하지 않습니다. 따라서 구체적인 도메인은 범위가 넓은 지역 규칙보다 위에 두고, MATCH는 마지막 기본 규칙으로 배치하는 것이 일반적입니다. 앞에서 모든 요청을 포괄하는 규칙이 이미 매칭되면 그 아래에 예외를 추가해도 적용되지 않습니다. 특정 사이트가 잘못된 출구를 사용하는지 확인할 때는 연결 상세 정보에서 실제 매칭 항목을 읽고, 해당 위치부터 위쪽 규칙을 확인하세요. 기대하는 규칙 한 줄만 검색해서는 안 됩니다.

일반적인 규칙 형식은 유형, 매칭 대상, 정책 순입니다. MATCH에는 정책만 필요합니다. 정책은 노드 이름, 그룹 이름, 내장 동작 중 하나일 수 있지만 실제로 존재하고 사용할 수 있어야 합니다. 업무 규칙에서는 자주 바뀌는 노드 이름 대신 안정적인 그룹 이름을 참조하는 것이 좋습니다. DOMAIN은 전체 도메인, DOMAIN-SUFFIX는 도메인 접미사와 하위 도메인, DOMAIN-KEYWORD는 키워드에 매칭됩니다. 키워드 매칭 범위는 넓으므로 경계가 명확한 접미사 규칙을 대신하는 용도로 사용하면 안 됩니다.

rules:
  - DOMAIN,login.example.com,출구 선택
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,출구 선택

위 예제는 출구 선택이라는 정책 그룹을 참조합니다. 첫 번째 줄은 지정된 로그인 도메인만 처리하고, 두 번째 줄은 예시 접미사를 처리하며, 세 번째 줄은 대상 주소가 지정된 네트워크 대역에 속하는 연결을 처리합니다. GEOIP는 로컬 지리 데이터로 대상 주소가 속한 지역을 판단하며 요청을 보낸 사람의 지역을 뜻하지 않습니다. 마지막 줄은 앞에서 매칭되지 않은 요청을 받습니다. 실제 설정에서는 사용하는 네트워크의 다른 사설 주소 대역도 포함해야 합니다. 예제의 대역 하나가 모든 LAN 범위를 대표하지는 않습니다.

해석 시점과 no-resolve

도메인 규칙이 적용되려면 코어가 도메인 정보를 확인할 수 있어야 합니다. 앱이 주소만 전달하고 사용 가능한 매핑이나 다른 도메인 식별 경로가 없다면 도메인 규칙만으로는 매칭되지 않을 수 있습니다. 도메인 대상에 IP 규칙을 적용할 때는 이름 해석이 발생할 수 있습니다. no-resolve는 해당 규칙을 위해 도메인을 능동적으로 해석하지 말라는 뜻이지 요청 전체에서 모든 DNS 조회를 금지한다는 뜻은 아닙니다. 요청에 대상 주소가 이미 있으면 주소 매칭을 계속할 수 있습니다. 사용 가능한 주소가 없다면 다음 규칙을 확인합니다.

규칙에서 REJECT는 거부 동작, DIRECT는 직결 동작이며 둘 다 노드 유형이 아닙니다. 정확한 도메인 규칙 하나를 잠시 거부하도록 설정하면 규칙이 실제로 로드됐는지 확인할 수 있지만 테스트 후에는 원래 설정으로 복구해야 합니다. 진단에 범위가 지나치게 넓은 키워드 거부 규칙을 사용하면 로그인, 업데이트, 리소스 도메인까지 차단할 수 있습니다. 웹페이지는 여러 연결을 만들 수 있습니다. 메인 사이트, 정적 리소스, 인증 서비스가 서로 다른 정책에 매칭될 수 있으므로 각 항목을 확인하세요. 페이지 제목만으로 전체 요청을 대표할 수는 없습니다.

규칙 모음으로 관리 대상을 분리하기

rule-providers는 외부 규칙 모음을 위한 기능이며 proxy-providers의 노드 모음과는 다릅니다. 규칙 모음에는 올바른 behavior를 지정해야 합니다. 흔히 사용하는 값은 domain, ipcidr, classical입니다. 파일 내용은 동작 유형과 일치해야 합니다. domain 모음은 주로 도메인 패턴을, ipcidr 모음은 네트워크 대역을, classical은 규칙 유형과 매칭 내용을 담습니다. 규칙 모음을 참조할 때 기본 설정에서 정책을 지정하므로 같은 모음을 여러 설정에서 서로 다른 출구로 재사용할 수 있습니다.

rule-providers:
  업무 도메인:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/business.yaml

rules:
  - RULE-SET,업무 도메인,출구 선택
  - MATCH,DIRECT

해당하는 로컬 규칙 모음은 다음과 같습니다. 정책은 기본 설정의 RULE-SET 참조 위치에서 지정하므로 payload의 각 줄에 출구 정책을 추가하지 않습니다. 파일 경로, 인코딩, 목록 들여쓰기, behavior 중 하나라도 맞지 않으면 로드에 실패할 수 있습니다. 원격 규칙 모음은 다운로드 성공 여부, 캐시 갱신 여부, 제공된 콘텐츠가 선언된 형식과 일치하는지도 확인해야 합니다. 오류 페이지를 반환하는 주소는 확장자가 YAML이라고 해서 규칙 모음이 되지 않습니다.

payload:
  - DOMAIN,login.example.com
  - DOMAIN-SUFFIX,example.org

규칙을 관리할 때는 먼저 관찰 가능한 문제를 해결한 뒤 적용 범위를 넓히세요. 대상 도메인, 현재 매칭 항목, 기대하는 정책, 수정 이유를 기록하면 서로 덮어쓰는 예외 규칙이 쌓이는 일을 줄일 수 있습니다. 지리 데이터, 규칙 모음 캐시, 기본 설정은 각각 업데이트 주기가 다르므로 하나를 수정해도 나머지가 함께 갱신되지는 않습니다. 규칙 파일이 올바른데도 동작이 바뀌지 않는다면 실행 설정에서 오버라이드가 적용된 위치를 확인하고 기존 연결이 이전 출구를 계속 사용하는지도 살펴보세요. 규칙을 업데이트해도 기존 연결이 자동으로 이동하지는 않습니다.

7. TUN, 시스템 프록시, DNS 가로채기의 범위

트래픽 분기를 논하기 전에 입력 경로부터 선택하세요

시스템 프록시는 시스템 설정을 따르는 앱에 요청을 로컬 프록시 입력 경로로 보내도록 알립니다. TUN은 가상 네트워크 인터페이스와 라우팅을 통해 더 많은 네트워크 트래픽을 처리합니다. 둘 다 입력 계층의 기능이며 노드 인증 매개변수를 바꾸거나 잘못된 규칙을 자동으로 고쳐 주지는 않습니다. 명령줄 도구, 게임, 자체 네트워크 스택을 사용하는 프로그램은 시스템 프록시를 읽지 않을 수 있습니다. 클라이언트에 연결 기록이 없다면 원격 노드를 계속 바꾸기보다 먼저 입력 경로가 해당 앱을 처리하는지 확인한 다음 TUN이 필요한지 판단하세요.

TUN의 실제 기능은 운영체제, 권한, 클라이언트 통합 방식, 코어 구현에 따라 달라집니다. 데스크톱 클라이언트는 서비스 구성 요소를 통해 권한을 요청할 수 있고, 모바일에서는 보통 시스템 VPN 권한으로 네트워크 입력을 만듭니다. 권한 미부여, 가상 네트워크 인터페이스 생성 실패, 라우팅 설정 실패는 노드에 연결하기도 전에 발생할 수 있습니다. Clash Plus, Clash Verge Rev, FlClash 등의 클라이언트는 메뉴 구성이 서로 다르므로 한 클라이언트의 서비스 설치 절차를 다른 클라이언트에 그대로 적용하지 마세요.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

이 설정 조각은 흔히 사용하는 필드 관계를 보여줄 뿐 모든 플랫폼에서 수정 없이 실행된다는 뜻은 아닙니다. enable은 기능을 켜고, stack은 프로토콜 스택 구현을 선택하며, auto-route는 라우팅 설정을 시도하고, auto-detect-interface는 출구 네트워크 인터페이스를 자동으로 찾습니다. 시스템에 여러 네트워크 인터페이스, 가상 네트워크, 기업 VPN, 컨테이너 브리지가 있으면 자동 감지가 예상과 다를 수 있습니다. 프로토콜 스택을 바꾸기 전에 로그에 명확한 오류가 있는지 확인하세요. 이유를 알 수 없는 문제를 해결하려고 stack만 바꾸는 습관은 피하세요.

DNS 가로채기가 모든 해석을 맡는 것은 아닙니다

dns-hijack은 매칭되는 DNS 트래픽을 코어의 이름 해석 과정으로 보냅니다. 예제는 주로 기존 DNS의 지정 포트 트래픽을 대상으로 합니다. 앱이 암호화 프로토콜로 DNS 서버에 직접 연결하면 트래픽 형태가 다르므로 이 설정만으로 일반 DNS 질의로 자동 전환되지 않습니다. 브라우저의 보안 DNS, 앱 자체 DNS, 시스템 DNS를 각각 확인하세요. 앱이 통일된 해석 정책을 따르게 하려면 해당 앱의 DNS 설정을 우선 조정하고 요청이 최종적으로 어떤 경로를 거치는지 검증하세요.

Fake-IP를 TUN과 함께 사용할 때는 가상 주소로 연결하는 트래픽도 같은 코어를 통과해야 합니다. 앱이 가상 주소를 캐시한 상태에서 TUN을 끄거나 다른 설정으로 전환하면 이전 주소에 대응하는 매핑이 사라져 일부 사이트에 갑자기 접속할 수 없게 될 수 있습니다. 이때는 상위 DNS를 바로 바꾸기보다 관련 캐시를 지우고 연결을 다시 만드세요. 클라이언트, 설정, 앱을 어떤 순서로 재시작하고 복구했는지도 기록해야 어떤 조치가 효과가 있었는지 구분할 수 있습니다.

라우팅 충돌과 LAN 접근

기업 VPN, 다른 프록시 클라이언트, 가상 머신 네트워크, 보안 소프트웨어가 라우팅을 바꿀 수 있습니다. 여러 프로그램이 기본 경로를 동시에 가로채면 트래픽이 반복 전달되거나 잘못된 출구를 사용하고 로컬 서비스에 접속할 수 없게 될 수 있습니다. 문제를 찾을 때는 네트워크 가로채기 방식을 하나만 남기고 다른 입력 경로를 끈 다음 재현해 보세요. 다른 도구를 영구적으로 제거하라는 뜻은 아닙니다. 단독 실행이 정상인 것을 확인한 뒤 공존을 지원하는지 살펴보고, 직접 연결해야 하는 네트워크 대역을 위한 제외 또는 분기 규칙을 설계하세요.

LAN 프린터, 네트워크 스토리지, 개발 서비스에 접속할 수 없다면 먼저 이름 해석을 확인한 뒤 대상 주소와 라우팅을 점검하세요. 도메인에 직결 규칙을 추가해도 시스템 라우팅 계층에서 잘못된 인터페이스로 보내는 문제는 해결되지 않을 수 있습니다. 반대로 라우팅 경로가 열려 있어도 도메인이 제대로 해석된다는 보장은 없습니다. 도메인 이름과 알고 있는 주소를 각각 사용해 테스트하고 문제가 이름 해석에 있는지 연결에 있는지 구분한 다음 필요한 범위만 조정하세요. 내부 서비스 하나 때문에 전체 트래픽을 가로채기 대상에서 제외하지 마세요.

서버를 원격으로 관리할 때는 데스크톱 TUN 설정을 그대로 적용해 전체 라우팅을 가로채지 마세요. 먼저 콘솔이나 복구 가능한 접속 경로를 준비하고 관리 연결에 영향이 없는지 확인한 다음 단계별로 활성화하세요. 일반 사용자는 그래픽 클라이언트 다운로드 페이지에서 플랫폼에 맞는 클라이언트를 선택하세요. 독립 코어는 서비스, 권한, 네트워크 규칙을 직접 관리할 수 있는 환경에 더 적합합니다. 최초 설치 권한 문제는 플랫폼별 초기 설정도 참고하세요.

8. 구독 오버라이드, 병합, 변경 사항 검증

먼저 각 설정 계층의 관리 주체를 확인하세요

설정 출처는 보통 원격 구독, 로컬 확장 설정, 클라이언트 전역 설정, 최종 실행 파일로 나눌 수 있습니다. 원격 구독은 서버에서 제공하는 내용을 관리하고, 로컬 확장 설정은 개인 규칙을 저장하며, 클라이언트 설정은 수신, 권한, 네트워크 입력을 관리합니다. 실행 파일은 이 출처들이 처리된 결과입니다. 클라이언트마다 처리 순서와 세부 동작이 다르므로 특정 오버라이드 문법이 YAML 표준이라고 볼 수 없습니다. 클라이언트를 옮길 때는 확장 파일만 복사하지 말고 필요한 동작과 실제 필드를 함께 이전하세요.

구독 원본 파일을 직접 수정하면 다음 업데이트에서 덮어써질 수 있습니다. 실행 파일을 직접 수정하면 새로고침이나 설정 전환 때 다시 생성될 수 있습니다. 장기간 유지할 사용자 설정은 클라이언트에서 공식 지원하는 확장 메뉴에 넣고 별도로 백업하는 편이 안전합니다. 클라이언트가 로컬 설정 파일 전체만 지원한다면 업데이트 절차를 직접 관리해야 합니다. 한 번 수정한 내용이 즉시 적용됐다고 해서 그 위치에 영구 저장된다고 단정하지 마세요. 최소한 새로고침 한 번과 구독 업데이트 한 번을 거쳐 확인해야 합니다.

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

객체 필드는 키를 기준으로 재귀 병합될 수도 있고 해당 영역 전체가 교체될 수도 있습니다. 목록은 앞에 추가, 뒤에 추가, 전체 교체, 전용 처리 방식 등으로 적용될 수 있습니다. 예를 들어 rules 뒤에 추가한 예외가 MATCH 뒤에 놓이면 텍스트에는 남아 있어도 매칭되지 않습니다. 목록 전체를 교체하면 구독에 있던 기존 분기 규칙이 사라질 수 있습니다. nameserver에 상위 서버를 추가하면 기존 서버가 교체되는 것이 아니라 병렬 조회 범위가 늘어날 수도 있습니다. 확장 설정을 사용하기 전에 클라이언트가 객체와 목록을 각각 어떻게 처리하는지 확인하세요.

# 목표는 예외 규칙을 기존 규칙 앞에 두는 것이며,
# 이 조각을 모든 클라이언트의 오버라이드 문법으로 그대로 사용하는 것이 아닙니다.
rules:
  - DOMAIN,dev.example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,출구 선택
  - MATCH,출구 선택

위 예제는 원하는 최종 순서를 나타냅니다. 실제로 적용할 때는 해당 클라이언트가 지원하는 규칙 앞에 추가하는 기능, 확장 설정, 스크립트 방식을 사용해야 합니다. 구독 파일 맨 끝에 그대로 붙여 넣으면 안 됩니다. 최종적으로 실행 파일에 최상위 rules 키가 하나만 있고, 예외가 기본 규칙보다 앞에 있으며, 참조하는 정책 그룹이 존재하는지 확인하세요. 개인 개발 규칙이 다른 구독이나 기기에 적용되지 않도록 확장 설정의 적용 범위도 확인해야 합니다.

구독 업데이트와 수동 선택을 각각 검증하세요

구독 업데이트 성공은 특정 업데이트 단계가 완료됐다는 뜻일 뿐, 현재 실행 설정이 다시 생성되어 활성화됐다는 보장은 없습니다. 일부 클라이언트는 다운로드, 파싱, 저장, 다시 불러오기를 각각 따로 처리하므로 어느 단계에서든 실패하면 이전 내용이 계속 사용될 수 있습니다. 업데이트 시간에 해당하는 로그, 노드 모음의 변경 사항, 현재 선택된 설정을 확인한 뒤 코어의 다시 불러오기 결과도 확인하세요. 업데이트에 실패했다면 먼저 구독 관련 자주 묻는 질문에 따라 네트워크 문제, 콘텐츠 형식 오류, 인증 문제를 구분하세요.

백업을 복원할 때는 클라이언트에 저장된 선택 상태도 확인해야 합니다. 파일을 원래대로 복구해도 정책 그룹은 이전 수동 선택을 유지할 수 있으며 DNS 캐시와 기존 연결도 남아 있을 수 있습니다. 재현 테스트에서는 모드, 정책 그룹의 출구, 요청 대상, 앱의 입력 경로를 고정하세요. 필요하다면 기존 연결을 닫은 뒤 새 요청을 보내세요. 한 번에 변수 하나만 바꾸고 결과를 기록해야 설정 복원이 실제로 문제를 해결했는지, 원격 서비스가 우연히 복구된 것인지 판단할 수 있습니다.

네 단계로 변경 사항을 검증하세요

첫 번째 단계에서는 문법과 자료형을 확인합니다. 들여쓰기, 따옴표, 불리언 값, 중복 키를 점검하세요. 두 번째 단계에서는 참조 관계를 확인합니다. 규칙이 가리키는 그룹, 그룹 안의 노드, 제공자가 모두 존재하고 순환 참조가 없는지 살펴보세요. 세 번째 단계에서는 실행 상태를 확인합니다. 코어가 새 설정을 읽었는지, 포트가 정상적으로 수신 중인지, DNS와 TUN 초기화 오류가 없는지 점검하세요. 마지막 네 번째 단계에서 실제 업무를 검증합니다. 대상 앱으로 분명한 주소에 접속한 뒤 매칭된 규칙과 출구를 확인하세요. 이전 단계가 통과하지 못했다면 다음 단계로 넘어가며 무작정 설정을 바꾸지 마세요.

백업에는 로컬 규칙, 정책 그룹 구조, 클라이언트 관련 확장 설정이 모두 포함되어야 합니다. 노드 목록만 내보내서는 안 됩니다. 민감한 노드 매개변수는 접근을 통제할 수 있는 위치에 보관하고 다른 사람과 공유할 때는 설명용 예시 값으로 바꾸세요. 이전 파일을 정리하기 전에 원본 파일, 캐시, 클라이언트가 생성한 파일을 구분하세요. 캐시 디렉터리를 함부로 지우면 오프라인에서 시작할 수 없게 될 수 있고, 원본 파일을 삭제하면 동기화하지 않은 개인 설정을 잃을 수 있습니다.

마지막으로 다음 세 가지 질문에 답할 수 있어야 합니다. 앱 요청은 어떤 입력 경로로 들어오는가, 어떤 규칙이 출구를 결정하는가, 이 규칙은 어느 설정 계층에서 관리되는가. 답이 분명하지 않다면 오버라이드를 더 쌓기보다 최소한의 기본 설정으로 돌아가 기능을 하나씩 추가하는 편이 문제를 찾기 쉽습니다. 빠른 연결 설정은 빠른 시작을 따르세요. 용어가 궁금하다면 용어 설명을, 구체적인 오류를 분석하려면 실행 로그 안내를 참고하세요. 이 가이드를 한 번에 모든 기능을 활성화해야 하는 목록으로 여기지 마세요.