Clash 설정 파일 완벽 가이드

01 / Structure

YAML 구조 개요

설정 파일은 어떤 부분으로 구성되나요?

Clash 설정 파일은 본질적으로 하나의 YAML 문서입니다. mihomo 코어는 파일을 읽은 뒤 먼저 수신 포트와 DNS 서비스를 설정하고, 이어서 프록시 노드, 정책 그룹, 규칙 집합과 실행 매개변수를 불러옵니다. 일반적인 파일은 공통 실행 필드, DNS, 노드 또는 노드 Provider, 정책 그룹, 규칙 Provider, 규칙의 여섯 계층으로 나눌 수 있습니다. 텍스트에 적힌 순서는 대개 파싱에 영향을 주지 않지만 참조 방향은 명확합니다. 규칙은 정책 그룹을 참조하고, 정책 그룹은 노드나 다른 정책 그룹을 참조하며, Provider는 정책 그룹과 규칙에 업데이트 가능한 데이터를 제공합니다.

아래 예시는 계층을 이해하기 위한 최소 골격입니다. 로컬 HTTP 및 SOCKS 포트를 사용하고 수동 정책 그룹을 정의하며, 앞선 규칙에 일치하지 않는 트래픽은 직접 연결합니다. 예시에 사용된 노드 주소와 비밀번호는 학습용 가짜 값이므로 실제 연결에 사용할 수 없습니다.

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

proxies:
  - name: Example-Trojan
    type: trojan
    server: example.com
    port: 443
    password: "your-password"
    sni: example.com

proxy-groups:
  - name: 노드 선택
    type: select
    proxies:
      - Example-Trojan
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,노드 선택
  - MATCH,DIRECT

최상위 키는 반드시 줄의 맨 앞에서 시작해야 합니다. 특정 키에 속한 하위 항목은 일정하게 들여쓰기하며, 일반적으로 공백 두 칸을 사용합니다. YAML은 반드시 두 칸을 요구하지 않지만 같은 계층의 들여쓰기는 일관되어야 하며, Tab 문자는 들여쓰기에 적합하지 않습니다. 목록 항목은 하이픈으로 시작하고, 키와 값 사이에는 반각 콜론과 공백 하나 이상을 둡니다. 노드 이름과 정책 그룹 이름에는 한글을 사용할 수 있지만, 공백·대소문자·구두점을 포함해 모든 참조 위치에서 완전히 동일해야 합니다.

매핑, 목록과 스칼라

세 가지 데이터 형태를 이해하면 대부분의 설정을 빠르게 읽을 수 있습니다. 매핑은 키와 값의 모음으로, 예를 들어 dns: 아래의 enable: true가 이에 해당합니다. 목록은 순서가 있는 항목들의 모음으로, rules: 아래에 규칙이 한 줄씩 배치됩니다. 스칼라는 문자열, 숫자, 불리언 또는 null 값입니다. true와 false는 따옴표 없이 불리언으로 작성하고, 포트는 숫자로 작성해야 합니다. 콜론이나 샵, 앞뒤 공백이 포함되거나 YAML이 다른 형식으로 해석할 수 있는 문자열은 따옴표로 감싸는 것이 좋습니다.

샵은 주석의 시작을 나타냅니다. 비밀번호나 이름 자체에 샵이 포함되어 있다면 반드시 따옴표를 사용해야 하며, 그렇지 않으면 샵 뒤의 내용이 주석으로 처리되어 사라집니다. 설정에 동일한 최상위 키가 반복되면 파서에 따라 앞 항목이나 뒤 항목만 남거나 오류가 발생할 수 있으므로, 중복 키 덮어쓰기에 의존하지 마세요. 구독 파일을 편집할 때 특히 주의할 점은 기존 dns: 뒤에 새 dns: 블록을 그대로 붙이는 것만으로는 병합이 완료되지 않는다는 것입니다.

이름 참조와 로드 순서

정책 그룹 이름은 규칙이 도달하는 최종 대상입니다. 예를 들어 규칙이 DOMAIN-SUFFIX,example.org,자동 선택으로 작성되어 있다면 설정에는 “자동 선택”이라는 이름의 정책 그룹 또는 같은 이름의 내장 동작이 존재해야 합니다. DIRECT와 REJECT 같은 동작은 코어가 인식하지만, 그 밖의 이름은 모두 proxy-groups에 선언해야 합니다. 정책 그룹이 다른 정책 그룹을 참조할 수도 있지만, A가 B를 참조하고 B가 다시 A를 참조하는 순환 구조는 피해야 합니다.

클라이언트가 설정을 가져올 때 원본 구독을 먼저 저장한 다음 로컬 오버라이드를 적용하고 마지막으로 코어에 파싱을 맡길 수 있습니다. 따라서 화면에 표시되는 최종 설정은 구독 서버가 반환한 텍스트와 완전히 같지 않을 수 있습니다. 문제를 해결할 때는 어떤 설정 파일이 실제로 실행 중인지, 마지막 업데이트가 성공했는지, 클라이언트에서 스크립트나 병합 규칙을 사용 중인지 확인해야 합니다. 구독 가져오기와 최초 연결만 필요하다면 YAML 전체를 직접 작성할 필요 없이 먼저 빠른 시작 문서를 따라 하세요.

02 / General

공통 필드: 포트, 모드와 로그

수신 포트 선택

port는 HTTP 프록시 포트를 제공하고, socks-port는 SOCKS5 프록시 포트를 제공하며, mixed-port는 하나의 포트에서 HTTP와 SOCKS 트래픽을 모두 받을 수 있게 합니다. 데스크톱에서는 시스템 프록시에 HTTP 또는 mixed 포트를 주로 사용하고, SOCKS5를 별도로 지정하는 명령줄 도구는 socks 포트를 사용할 수 있습니다. 대부분의 경우 mixed-port를 선택하면 포트 수를 줄일 수 있지만, 기존 스크립트가 7890과 7891을 고정 참조한다면 기존 포트 구성을 유지해야 합니다.

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

같은 기기에서 두 프로그램이 동일한 주소와 포트를 동시에 수신할 수는 없습니다. 클라이언트에 “address already in use”가 표시되면 먼저 다른 프록시 프로그램을 종료하거나 포트를 변경하세요. 문제를 노드 탓으로 돌려서는 안 됩니다. 포트 범위는 1~65535이며, 일부 데스크톱 시스템에서는 낮은 번호의 포트에 추가 권한이 필요할 수 있습니다. 포트를 변경한 뒤에는 브라우저, 터미널 환경 변수 또는 LAN 기기의 프록시 주소도 함께 수정해야 합니다.

LAN 접근과 바인딩 주소

allow-lan은 다른 기기가 현재 기기에서 제공하는 프록시 포트에 접근할 수 있는지 제어합니다. 기기에서만 사용할 때 false로 설정하면 불필요한 노출을 줄일 수 있습니다. 같은 Wi‑Fi의 컴퓨터, TV 또는 테스트 기기를 연결해야 한다면 true로 설정하고 프록시 호스트의 LAN 주소를 사용하세요. 이때 시스템 방화벽이 해당 포트를 허용하는지, 두 기기가 서로 통신 가능한 네트워크에 있는지도 확인해야 하며 공용 네트워크에서는 활성화하지 않는 것이 좋습니다.

bind-address는 어떤 로컬 주소에서 수신할지 결정합니다. 별표는 일반적으로 사용 가능한 모든 인터페이스를 뜻하고, 루프백 주소는 로컬 기기에서만 접근할 수 있게 합니다. 클라이언트에 따라 그래픽 인터페이스에서 이 매개변수를 관리할 수 있으며, 화면의 “LAN 허용” 스위치가 실행 중 해당 필드를 생성하기도 합니다. iOS의 네트워크 확장은 데스크톱 포트 프록시와 작동 방식이 다르므로, 동일한 설정을 가져와도 다른 기기에 수신 포트를 개방하지 않을 수 있습니다. 기기 간 공유 여부는 실제 클라이언트 기능을 기준으로 판단하세요.

rule, global과 direct

mode: rule은 규칙 목록을 위에서 아래로 확인해 각 연결의 경로를 결정하며, 일상적으로 가장 많이 사용하는 모드입니다. global은 트래픽을 모두 글로벌 정책 그룹으로 보내므로 특정 노드의 사용 가능 여부를 짧게 확인할 때 유용하지만 세부 규칙의 결과는 반영하지 않습니다. direct는 대상에 직접 연결해 프록시 사용 전후의 네트워크 상태를 비교할 수 있게 합니다. 모드 전환은 분기 진입점만 바꿀 뿐, 사용할 수 없는 노드나 잘못된 DNS를 자동으로 고쳐 주지는 않습니다.

클라이언트 화면에 “규칙 모드”, “글로벌 모드”, “직접 연결 모드”가 있다면 화면에서 선택한 값이 설정 파일의 기본 mode를 덮어쓰는 경우가 많습니다. 규칙이 적용되지 않을 때는 YAML과 현재 화면 상태를 함께 확인해야 합니다. 계속 글로벌 모드에 머물러 있다면 rules를 수정해도 변화가 보이지 않으며, 직접 연결 모드라면 정책 그룹의 노드 선택도 주요 트래픽을 처리하지 않습니다.

로그, 제어 인터페이스와 설정 저장

log-level은 보통 info를 사용하며, 연결·규칙 일치·일부 오류를 확인할 수 있습니다. 로그가 너무 적으면 원인을 찾기 어렵고, 디버그 출력을 장시간 유지하면 읽어야 할 정보가 지나치게 많아집니다. 연결에 실패했을 때는 대상 도메인, 일치한 규칙, 선택된 정책 그룹과 오류 유형을 먼저 기록한 뒤 설정과 대조해 수정하세요. 단순히 “열리지 않는다”는 현상만으로 모든 설정을 반복해서 바꾸지는 마세요.

external-controller는 호환되는 제어 화면에 API를 제공하며, 예를 들어 로컬 루프백 주소에서 수신하도록 설정할 수 있습니다. secret을 지정했다면 제어 클라이언트 연결에도 동일한 인증 정보가 필요합니다. 모바일 클라이언트는 보통 제어 인터페이스를 자체 관리하므로, 데스크톱 튜토리얼을 따라 하려고 LAN에 임의로 개방하지 않는 것이 좋습니다. 설정의 인증 정보는 직접 만든 값을 사용하고, 구독 주소·노드 비밀번호·제어 키가 포함된 전체 파일을 포럼에 공개해서는 안 됩니다.

profile 아래의 저장 옵션은 정책 그룹 선택이나 Fake IP 매핑을 유지하는 데 사용할 수 있습니다. 지원 여부와 저장 시점은 클라이언트의 코어 통합 방식에 따라 달라집니다. 클라이언트를 업그레이드하거나 설정을 바꾼 뒤에도 정책 그룹이 이전 선택을 유지한다면 선택 기억 기능이 활성화되어 있는지 먼저 확인하고, 그 다음 설정이 새로고침되지 않은 것인지 판단하세요. 시스템 요구 사항과 사용 가능한 클라이언트는 플랫폼별로 다운로드 페이지에서 확인할 수 있습니다.

03 / DNS

DNS 설정: 해석 경로와 가로채기

DNS 블록은 어떤 문제를 해결하나요?

DNS 블록은 도메인을 주소로 변환하는 방식과 조회 요청을 코어가 통합 처리할지 결정합니다. 프록시 노드를 사용할 수 있다고 해서 DNS가 올바르다는 뜻은 아닙니다. 도메인 조회가 여전히 시스템 네트워크에서 직접 처리되거나, 라우터·통신사 네트워크·다른 VPN이 가로챌 수 있습니다. 흔한 증상으로는 일부 도메인만 열리지 않거나, 규칙 일치 결과가 예상과 다르거나, 네트워크 전환 직후 잠시 이상이 생기거나, 프록시 연결은 되었지만 앱에서 접속할 수 없다고 표시되는 경우가 있습니다.

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  use-hosts: true
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"

enable은 내장 DNS 사용 여부를 제어합니다. listen은 DNS 서비스의 수신 주소로, 데스크톱이나 라우터 환경에서는 시스템 요청을 전달하는 데 사용할 수 있습니다. 모바일에서는 보통 네트워크 확장이 이를 처리하므로 수신 포트만 보고 적용 여부를 판단해서는 안 됩니다. ipv6은 AAAA 결과를 반환하고 처리할지 결정합니다. 로컬 네트워크의 IPv6 경로가 불안정하다면 잠시 끄고 문제가 듀얼 스택 네트워크에서 비롯되었는지 확인할 수 있지만, IPv6 비활성화를 모든 DNS 문제의 고정 해법으로 삼아서는 안 됩니다.

nameserver와 bootstrap의 관계

nameserver는 기본 해석기 목록으로, 일반 UDP 주소나 암호화된 DNS URL을 사용할 수 있습니다. DoH를 설정하면 DoH 서버 자체의 도메인도 먼저 해석해야 하므로 시작 단계에 의존성이 생깁니다. mihomo는 default-nameserver 또는 전용 서버 해석 항목으로 초기 해석을 처리할 수 있습니다. 이곳에는 직접 접근 가능한 IP 형식의 해석기를 배치해 초기 해석이 아직 구축되지 않은 프록시 경로에 다시 의존하지 않도록 하세요.

proxy-server-nameserver는 주로 프록시 서버 도메인을 해석하는 데 사용합니다. 일반 대상 도메인의 해석과 분리하면 “프록시 서버에 연결하려는데 그 서버의 도메인을 먼저 해당 프록시로 해석해야 하는” 순환 의존성을 줄일 수 있습니다. 노드의 server가 이미 IP 주소라면 영향이 작지만, 구독에 도메인을 사용하는 노드가 많다면 현재 네트워크에서 직접 접근할 수 있는 해석기를 지정하는 편이 안정적입니다.

암호화된 DNS라고 해서 모든 조회가 자동으로 프록시를 통과하는 것은 아닙니다. 해석기 URL은 직접 연결할 수도 있고, 코어가 지원하는 주소 매개변수에 따라 특정 정책을 거치게 할 수도 있습니다. 해석 경로를 설계할 때는 로컬 해석 간섭을 피할 것인지, 규칙에 일관된 결과를 제공할 것인지, 특정 도메인을 특정 해석기로 보낼 것인지 먼저 정해야 합니다. 목표가 다르면 설정도 달라집니다. 공용 DNS를 많이 추가한다고 코어가 가장 적합한 해석기를 자동으로 판단하는 것은 아니며, 해석기마다 응답이 달라 오히려 불확실성이 커질 수 있습니다.

fake-ip와 redir-host

fake-ip 모드는 먼저 앱에 예약 주소 풀의 매핑 주소를 반환하고, 코어가 매핑을 통해 원래 도메인을 복원한 뒤 규칙을 적용합니다. 도메인 정보를 유지한 채 규칙을 매칭할 수 있고 투명 프록시 환경에도 직접적이라는 장점이 있습니다. redir-host는 실제 해석 결과를 반환하므로 일부 LAN 서비스나 주소 동작에 민감한 프로그램과 더 잘 호환될 수 있지만, 도메인 정보의 유지 방식과 매칭 경로는 달라집니다.

fake-ip-range에는 별도로 계획한 주소 대역을 사용해야 하며, 가정·회사·컨테이너·VPN 네트워크에서 이미 사용하는 대역과 겹치지 않게 하세요. LAN 도메인에 접근한 뒤 Fake IP를 받는다면 해당 도메인이 제외되지 않은 것입니다. 실제 해석이 필요한 도메인은 fake-ip-filter에 추가할 수 있습니다. 예를 들면 LAN 접미사, 기기 검색 도메인 또는 특정 로그인 도메인이 해당합니다. 필터 항목은 가능한 한 구체적으로 작성하세요. 지나치게 넓은 와일드카드를 넣으면 많은 요청이 Fake IP를 우회해 통합 처리 효과가 약해집니다.

nameserver-policy와 도메인별 해석

nameserver-policy를 사용하면 특정 도메인이나 규칙 집합에 지정한 해석기를 적용할 수 있습니다. 예를 들어 내부 도메인은 회사 DNS로 보내고 나머지는 공용 암호화 해석기를 사용할 수 있습니다. 일치 조건이 구체적일수록 유지 관리가 쉽습니다. 하나의 도메인이 여러 정책에 동시에 해당한다면 코어의 우선순위에 따라 최종 결과를 확인하고, 설정 순서만 보고 추측하지 말고 로그로 검증하세요.

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query
  nameserver-policy:
    "geosite:cn":
      - https://223.5.5.5/dns-query
    "+.internal.example":
      - 192.168.1.1
  fake-ip-filter:
    - "+.internal.example"
    - "*.lan"

내부 해석기는 보통 특정 Wi‑Fi, 기업 네트워크 또는 VPN 안에서만 접근할 수 있습니다. 해당 네트워크를 벗어난 뒤에도 정책이 내부 도메인을 접근할 수 없는 주소로 보내면 조회가 시간 초과될 수 있습니다. 모바일 기기는 셀룰러 네트워크와 Wi‑Fi를 자주 오가므로, 이런 설정은 해당 연결 조건에 맞는 온디맨드 연결이나 별도 설정에 두는 것이 좋습니다. 사무실 네트워크에 강하게 묶인 DNS 설정 하나로 모든 환경을 덮어쓰지 마세요.

DNS 문제 해결 순서

먼저 도메인과 IP를 각각 테스트하세요. IP는 접근되지만 도메인만 실패하면 해석을 중점적으로 확인하고, 둘 다 실패하면 정책 그룹·노드·시스템 네트워크를 점검합니다. 다음으로 로그에서 DNS 시간 초과, 연결 거부 또는 해석기 핸드셰이크 오류를 확인하세요. 그 후 다른 VPN, Private DNS, 필터링 앱 또는 라우터의 DNS 재작성 기능이 동시에 활성화되어 있는지 살펴봅니다. 마지막으로 enhanced mode, 해석기 또는 IPv6를 조정하세요. 한 번에 하나의 변수만 변경하고 앱이나 시스템의 단기 캐시를 지운 뒤 다시 테스트해야 합니다.

“연결됨”으로 표시되지만 인터넷이 되지 않는다면 위에서 아래로 확인하는 문제 해결 체크리스트를 함께 참고하세요. fallback, 필터와 DNS 가로채기를 필드별로 이해하려면 DNS 설정 상세 가이드를 확인할 수 있습니다. 클라이언트마다 일부 필드를 그래픽 인터페이스로 감쌀 수 있으므로 최종 판단은 실행 로그와 내보낸 적용 설정을 기준으로 하세요.

04 / Proxies

프록시 노드 필드

공통 필드와 참조 이름

proxies는 정적 노드 목록입니다. 각 노드에는 최소한 name, type, server, port가 필요하며 나머지 필드는 프로토콜에 따라 달라집니다. name은 설정 내부에서 사용하는 참조 식별자일 뿐 네트워크 연결을 담당하지 않고, 서버 도메인이나 주소는 server에 지정합니다. 정책 그룹이 노드를 참조할 때는 이름을 사용하므로 노드 이름을 바꾸면 이를 직접 참조하는 모든 정책 그룹도 함께 수정해야 합니다.

노드 이름은 짧고 안정적으로 유지하는 것이 좋습니다. 구독 업데이트 때 서버에서 이름을 바꾸면 클라이언트가 기억한 정책 그룹 선택이 이전 항목을 찾지 못해 기본 노드로 되돌아갈 수 있습니다. 장기간 특정 선택을 유지해야 한다면 Provider와 필터를 통해 정책 그룹이 일정한 유형의 노드를 선택하게 하거나, 로컬 오버라이드에서 명명 규칙을 통일하세요. 이름에 포함된 지역명만으로 회선 품질을 판단해서는 안 됩니다. 실제 사용 가능 여부는 로컬 네트워크, 진입 경로, 전송 매개변수와 서버 상태에도 영향을 받습니다.

Trojan 예시

proxies:
  - name: Example-Trojan
    type: trojan
    server: edge.example.com
    port: 443
    password: "your-password"
    sni: edge.example.com
    udp: true
    skip-cert-verify: false

Trojan은 보통 TLS를 사용합니다. sni는 TLS 핸드셰이크의 서버 이름으로, 서버 인증서 및 배포 설정과 일치해야 합니다. password는 특수 문자를 포함해 완전히 보존해야 하며 따옴표를 사용하는 편이 안전합니다. udp는 노드가 UDP 트래픽을 처리할지 제어하지만 클라이언트·코어·서버가 모두 지원해야 실제로 사용할 수 있습니다. skip-cert-verify로 인증서 검증을 끄면 신원 확인이 약해집니다. 정상적인 배포에서는 false를 유지하고, 인증서 오류는 서버 이름·인증서 유효성·시스템 시간·네트워크 가로채기 문제를 해결해야 합니다.

Shadowsocks 예시

proxies:
  - name: Example-SS
    type: ss
    server: 203.0.113.10
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

Shadowsocks의 핵심 필드는 암호화 방식과 비밀번호이며 양쪽 설정이 일치해야 합니다. cipher는 개인 취향에 따라 임의로 바꾸는 값이 아닙니다. 서버에 설정된 값을 클라이언트에도 그대로 입력하세요. 연결에 실패하면 주소, 포트, 방식, 비밀번호 네 항목을 확인한 뒤 서버 방화벽과 로컬 네트워크가 해당 트래픽을 허용하는지 점검합니다. 다른 프로토콜의 필드를 복사한다고 호환성이 좋아지지는 않습니다. 인식되지 않은 필드는 무시되거나 설정 검증 실패를 일으킬 수 있습니다.

VMess, VLESS와 전송 계층 매개변수

VMess는 uuid, alterId, cipher 등의 필드를 자주 사용합니다. VLESS는 UUID를 사용하며 배포 환경에 따라 TLS, Reality 또는 다른 전송 설정을 선택합니다. WebSocket과 gRPC 같은 전송 계층에는 경로, Host, 서비스 이름과 요청 헤더가 추가로 필요할 수 있습니다. 필드 계층은 mihomo가 지원하는 형식과 일치해야 하며, 다른 클라이언트가 내보낸 JSON 필드를 그대로 YAML에 옮겨서는 안 됩니다.

  - name: Example-VMess-WS
    type: vmess
    server: ws.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    servername: ws.example.com
    network: ws
    ws-opts:
      path: /network
      headers:
        Host: ws.example.com

여기서 server는 연결 대상을 결정하고, servername 또는 해당 SNI 필드는 TLS에 영향을 주며, WebSocket의 Host는 상위 요청에 영향을 줍니다. 단순한 배포에서는 세 도메인이 같을 수 있지만, 리버스 프록시나 분리된 진입점을 사용하는 배포에서는 서로 다를 수 있습니다. 어느 하나라도 오타가 있으면 TCP 연결은 성립하지만 핸드셰이크가 실패하는 증상으로 나타날 수 있습니다. 문제 해결은 “도메인 해석, TCP 포트, TLS, 전송 계층, 프로토콜 인증” 순서로 계층별 진행하세요.

노드별 네트워크 옵션

interface-name은 출구 네트워크 인터페이스를 지정할 수 있고, routing-mark는 Linux 정책 라우팅에 자주 사용되지만 모바일 클라이언트에서는 보통 직접 설정할 필요가 없습니다. ip-version, prefer-ipv6 등의 옵션은 노드 서버 도메인에서 어떤 주소를 선택할지에 영향을 주며, 구체적인 지원 여부는 코어에 따라 다릅니다. 듀얼 스택 해석에서 잘못된 주소가 선택된 것이 확인된 경우에만 조정하고, 일반적인 회선 장애를 IP 버전 문제로 처리하지 않도록 하세요.

노드 필드는 올바르지만 여전히 사용할 수 없다면 먼저 해당 노드를 간단한 select 그룹에 넣고 잠시 글로벌 모드로 전환해 테스트하세요. 복잡한 규칙의 영향을 배제하기 위한 방법입니다. 테스트가 끝나면 규칙 모드로 돌아오세요. 모든 노드가 동시에 작동하지 않는다면 구독 상태, 시스템 시간, DNS와 로컬 네트워크를 우선 확인하고, 단일 노드만 실패할 때 해당 프로토콜 매개변수를 집중적으로 점검하세요. 클라이언트 선택과 플랫폼별 차이는 다운로드 페이지에서 확인할 수 있습니다. 모든 플랫폼에서 우선 추천하는 Clash Plus로 기본 연결을 먼저 완료한 뒤 설정을 단계적으로 조정하는 방법도 좋습니다.

05 / Policy

정책 그룹 필드와 선택 로직

select: 사용자가 직접 결정

정책 그룹은 노드와 규칙 사이에 있습니다. 규칙은 보통 특정 노드를 직접 지정하지 않고 정책 그룹을 가리키며, 클라이언트 화면에서 그룹 내 선택을 바꾸면 해당 그룹을 가리키는 모든 규칙이 새 선택을 사용합니다. select는 수동 선택 그룹으로, “노드 선택”, “스트리밍”, “다운로드”처럼 명확히 제어할 진입점에 적합합니다. 그룹 안에는 노드뿐 아니라 다른 정책 그룹이나 DIRECT도 넣을 수 있습니다.

proxy-groups:
  - name: 노드 선택
    type: select
    proxies:
      - 노드 자동 선택
      - 장애 조치
      - Example-Trojan
      - DIRECT

목록 순서는 화면의 기본 표시와 장애 발생 시 대체 경험에 영향을 줍니다. 가장 자주 사용할 선택지를 앞에 배치하되 상위 그룹과 하위 그룹이 순환 참조를 만들지 않게 하세요. 예를 들어 “노드 선택”에 “자동 선택”을 포함하는 것은 합리적이지만, “자동 선택”이 다시 “노드 선택”을 후보로 삼으면 해석하거나 실행할 수 없는 순환이 생깁니다. 복잡한 설정은 먼저 참조 방향을 그린 뒤 계층을 정하는 것이 좋습니다.

url-test: 탐색 결과에 따른 자동 선택

url-test는 지정한 URL로 후보 노드의 연결성을 테스트하고 결과가 적절한 노드를 선택합니다. 측정값은 테스트 대상까지의 요청 성능을 의미할 뿐 모든 웹사이트의 실제 속도와 같지는 않습니다. 테스트 URL은 안정적이고 응답 본문이 작으며 주요 사용 네트워크를 대표해야 합니다. 테스트 주기가 너무 짧으면 백그라운드 활동과 서버 요청이 늘어나고, 모바일 기기에서는 배터리도 더 소모될 수 있습니다.

  - name: 노드 자동 선택
    type: url-test
    proxies:
      - Example-Trojan
      - Example-SS
    url: https://www.gstatic.com/generate_204
    interval: 600
    tolerance: 80
    lazy: true

interval은 일반적으로 초 단위의 테스트 간격이고, tolerance는 후보 결과의 작은 차이만으로 선택이 자주 바뀌는 것을 막습니다. lazy는 필요할 때에 가깝게 테스트하도록 설정할 수 있습니다. 이 필드들은 계속 새로고침하기보다 안정성을 중심으로 구성하세요. 업무 연결에서 동일한 출구를 유지해야 한다면 노드가 자주 바뀔 때 세션이 끊길 수 있으므로 허용 오차와 간격을 늘리거나 수동 그룹을 사용하세요.

fallback과 load-balance

fallback은 목록 우선순위에 따라 노드를 사용하다가 현재 노드의 탐색이 실패하면 다음 후보로 전환합니다. “선호 회선을 우선 사용하고 불가능할 때만 교체”하는 상황에 적합합니다. url-test와 달리 가장 낮은 측정값만을 목표로 하지 않고 순서에 따른 선호를 유지합니다. 항상 두 번째 노드로 전환된다면 일반 웹페이지가 아니라 테스트 URL에 첫 번째 노드가 접근 가능한지 확인하세요.

load-balance는 정책에 따라 여러 노드에 서로 다른 연결을 분배합니다. 하나의 다운로드 작업의 대역폭을 단순히 합산하는 기능은 아니며, 출구 주소가 바뀌어 로그인 상태·위험 관리 판단·장기 연결에 영향을 줄 수도 있습니다. 출발지 주소를 고정해야 하는 웹사이트에는 부하 분산을 함부로 사용하지 않는 것이 좋습니다. 구체적인 분배 방식은 해시나 라운드 로빈 방식일 수 있으므로 사용 전에 현재 클라이언트 코어가 지원하는 필드를 확인하세요.

Provider로 노드 선택

노드가 proxy-providers에서 제공되는 경우 정책 그룹은 각 노드 이름을 proxies에 일일이 적는 대신 use로 Provider를 참조할 수 있습니다. 구독 업데이트로 노드가 추가되거나 삭제되면 그룹의 후보도 함께 바뀝니다. 또한 filter로 이름을 필터링해 특정 지역 표식이 포함된 노드만 선택할 수 있습니다. 필터 규칙은 대개 정규 표현식을 사용하므로 대소문자, 전각 기호와 서버 측 이름 변경에 따른 변화를 고려해야 합니다.

  - name: 모바일 네트워크
    type: select
    use:
      - provider-main
    filter: "(?i)mobile|모바일"
    exclude-filter: "(?i)expire|남은|만료"

이름 필터는 텍스트만 기준으로 하며 노드의 실제 위치, 프로토콜 또는 회선 속성을 검증하지 않습니다. 구독 명명 규칙이 바뀌면 그룹이 갑자기 비어 버릴 수 있습니다. 설정을 관리할 때는 중요한 정책 그룹에 확인 가능한 대체 항목을 준비하고, 구독 업데이트 후 후보 수를 확인하세요. 클라이언트 화면에 정책 그룹이 비어 있다고 표시되면 먼저 Provider 업데이트 성공 여부를 확인하고, 다음으로 필터 표현식, 마지막으로 Provider 이름의 오탈자를 점검합니다.

정책 그룹 계층은 지나치게 깊게 만들지 않는 것이 좋습니다. 대부분의 요구는 세 계층이면 충분합니다. 하위에는 노드 풀과 자동 테스트 그룹, 중간에는 “노드 선택” 같은 전체 진입점, 상위에는 동영상·다운로드·특정 서비스 정책을 배치합니다. 계층이 깊어질수록 로그에서 최종 출구를 추적하기 어려워집니다. 규칙이 일치한 뒤에는 “규칙 대상 그룹—현재 그룹 선택—하위 그룹 선택—실제 노드” 순서로 단계별 확인하세요.

06 / Rules

규칙 문법과 매칭 순서

위에서 아래로 확인하며 일치하면 중지

rules는 순서가 있는 목록입니다. 코어는 첫 번째 규칙부터 연결을 검사하고, 일치하면 해당 규칙의 정책을 적용한 뒤 뒤의 규칙은 더 확인하지 않습니다. 따라서 구체적인 규칙은 넓은 규칙보다 앞에 두고, 최종 대체 규칙은 마지막에 배치해야 합니다. MATCH를 앞에 두면 아래의 도메인 및 주소 규칙은 실행될 기회를 잃습니다. “규칙을 작성했지만 적용되지 않는다”면 규칙을 계속 추가하기보다 로그에서 실제로 어느 규칙에 먼저 일치했는지 확인하세요.

rules:
  - DOMAIN,api.example.com,노드 선택
  - DOMAIN-SUFFIX,example.com,노드 선택
  - DOMAIN-KEYWORD,example,노드 선택
  - IP-CIDR,203.0.113.0/24,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

일반적인 규칙은 규칙 유형, 매칭 내용, 정책 대상의 세 부분으로 구성되며 반각 쉼표로 구분합니다. 정책 대상은 기존 정책 그룹, 노드 이름 또는 내장 동작이어야 합니다. 규칙 행의 불필요한 공백이 내용의 일부로 처리될 수 있으므로 형식을 통일하는 것이 좋습니다. 도메인 매칭은 URL 경로를 포함하지 않습니다. 웹페이지 경로에 따라 분기하려면 DOMAIN 계열 규칙만으로는 처리할 수 없습니다.

DOMAIN, DOMAIN-SUFFIX와 DOMAIN-KEYWORD

DOMAIN은 전체 도메인을 정확히 매칭합니다. 예를 들어 DOMAIN,api.example.com은 해당 호스트만 매칭하며 www.example.com을 자동으로 포함하지 않습니다. DOMAIN-SUFFIX,example.com은 루트 도메인과 하위 도메인을 매칭해 하나의 서비스에 속한 여러 호스트를 포괄하는 데 적합합니다. DOMAIN-KEYWORD는 도메인에 지정한 텍스트가 포함되기만 해도 일치할 수 있어 범위가 넓고, 이름이 비슷하지만 무관한 사이트까지 잘못 처리할 수 있습니다.

규칙은 정확한 도메인과 접미사를 우선 사용하고, 도메인 목록을 정리하기 어려울 때만 키워드를 사용하세요. 서비스는 로그인·API·이미지·미디어 등 여러 도메인에 의존할 수 있으므로 웹의 주요 도메인만 처리하면 전체 요청을 포괄하지 못할 수 있습니다. 연결 로그를 관찰하며 조금씩 보완하되, 임시 CDN 호스트를 모두 주 설정에 고정하지는 마세요. 규모가 큰 도메인 목록은 규칙 집합 Provider에 넣는 편이 적합합니다.

IP-CIDR와 no-resolve

IP-CIDR은 IPv4 네트워크 대역을, IP-CIDR6은 IPv6 네트워크 대역을 매칭합니다. CIDR 접미사는 네트워크 프리픽스 길이를 뜻하며, 예를 들어 /24는 인접한 IPv4 주소 범위를 포함합니다. IP 규칙으로 자주 바뀌는 클라우드 서비스 도메인을 안정적으로 표현할 수는 없으므로, 한 번 해석된 주소를 장기 규칙으로 사용하지 마세요. 서비스가 안정적인 대역이나 LAN 주소 또는 명확한 네트워크 범위를 제공할 때 IP 규칙이 더 적합합니다.

no-resolve는 이 IP 규칙을 판단하기 위해 도메인 해석을 추가로 실행하지 않도록 합니다. 연결에 대상 IP가 이미 있다면 바로 매칭할 수 있지만, 도메인만 있는 경우 코어는 이 규칙을 위해 별도로 해석하지 않습니다. 불필요한 조회와 잠재적인 순환을 줄일 수 있지만, 해석 결과에 의존하는 IP 규칙이 일치하지 않을 수도 있습니다. 사용할지는 요청이 코어에 들어올 때 어떤 정보를 알고 있는지에 따라 결정하세요.

rules:
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,::1/128,DIRECT,no-resolve

LAN 직접 연결 규칙은 프린터, 라우터와 파일 서버가 원격 프록시로 전송되는 것을 막기 위해 앞쪽에 배치하는 경우가 많습니다. 회사 네트워크는 더 큰 사설 주소 대역을 사용하거나, 가정 네트워크가 VPN 대역과 겹칠 수도 있습니다. LAN 서비스에 접근할 수 없다면 먼저 실제 대상 주소를 확인한 뒤 규칙 오류인지, Fake IP 필터가 부족한지, 시스템 라우팅이 로컬 인터페이스를 가리키지 않는지 판단하세요.

GEOIP, GEOSITE와 규칙 집합

GEOIP는 대상 IP가 속한 데이터베이스 분류에 따라 지역 단위 IP 분기를 수행하는 데 적합하지만, 데이터베이스의 판단이 서비스의 실제 소속을 뜻하지는 않습니다. 국내 브랜드도 다른 지역의 클라우드 노드를 사용할 수 있고, 해외 서비스도 국내에 엣지 주소를 배치할 수 있습니다. GEOSITE는 도메인 분류 데이터를 사용하며, 적용 범위는 규칙 데이터베이스의 내용에 따라 달라집니다. 두 방식 모두 데이터 업데이트에 의존하므로 영원히 정확한 고정 사실로 이해해서는 안 됩니다.

mihomo에서 자주 사용하는 규칙 집합 매칭에는 RULE-SET도 있습니다. 규칙 집합에는 domain, ipcidr 또는 classical 형식의 데이터를 넣을 수 있으며, 참조할 때는 Provider의 behavior와 일치해야 합니다. classical 형식의 전체 규칙을 domain 유형 규칙 집합에 넣거나 IP 규칙 집합에 잘못된 유형을 사용하면 파싱에 실패하거나 매칭 결과가 비정상적일 수 있습니다.

프로세스 규칙과 플랫폼 제한

PROCESS-NAME과 PROCESS-PATH 같은 프로세스 규칙은 운영체제가 제공하는 프로세스 정보에 의존합니다. 데스크톱에서는 권한이 있으면 사용할 수 있지만, iOS 네트워크 확장은 일반적으로 데스크톱처럼 임의의 프로세스 경로를 읽을 수 없습니다. 크로스 플랫폼 설정을 작성할 때 핵심 분기를 프로세스 규칙에 전적으로 의존하지 마세요. 도메인·IP·규칙 집합을 주 경로로 삼고, 프로세스 규칙은 특정 데스크톱 환경의 보조 수단으로 사용하는 편이 안전합니다.

동일한 설정이 Windows, macOS, Android와 iOS에서 다르게 동작하는 것은 YAML 문법이 바뀌어서가 아니라 시스템 인계 방식, 권한과 네트워크 스택이 다르기 때문인 경우가 많습니다. 플랫폼별 규칙은 로컬 오버라이드에 넣어 구독 본문을 공통으로 유지하세요. 그러면 구독 업데이트 때 데스크톱 전용 프로세스 규칙이 모바일로 강제로 전달되는 일을 막을 수 있습니다.

REJECT, DIRECT와 최종 대체 규칙

DIRECT는 대상에 직접 연결하고, REJECT는 연결을 거부합니다. 차단 규칙은 정확해야 하며, 지나치게 넓은 키워드나 도메인 접미사는 로그인·결제·기본 API까지 차단할 수 있습니다. 마지막 규칙은 보통 MATCH를 전체 정책 그룹이나 직접 연결로 지정하지만, 구체적인 선택은 설정 목적에 따라 달라집니다. 최종 대체 규칙이 없으면 일치하지 않은 트래픽이 코어의 기본 로직에 따라 처리될 수 있어 설정 의도가 불명확해집니다.

규칙을 수정한 뒤에는 주요 분기를 모두 테스트해야 합니다. 직접 연결되어야 하는 도메인 하나, 프록시를 사용해야 하는 도메인 하나, LAN 주소 하나, 규칙 집합 대상 하나를 확인하세요. 웹페이지 하나만 테스트해서는 전체 규칙 체인이 올바르다고 증명할 수 없습니다. 속도 문제는 노드·회선·로컬 설정을 구분해야 하며, 느린 속도를 세 계층으로 점검하는 방법을 참고해 모든 성능 문제를 규칙 수 탓으로 돌리지 마세요.

07 / Providers

Proxy Provider와 Rule Provider

Provider를 사용하는 이유

Provider는 자주 업데이트되는 데이터를 주 설정에서 분리합니다. proxy-providers는 노드 목록을 제공하고, rule-providers는 규칙 집합을 제공합니다. 주 설정은 참조 이름, 업데이트 주기와 정책을 관리하고 원격 파일은 실제 내용을 담당합니다. 이렇게 하면 구독이 업데이트될 때 주 설정 전체를 다시 작성할 필요가 없고, 여러 정책 그룹이 동일한 노드 풀을 공유할 수도 있습니다.

Provider URL에는 접근 인증 정보가 포함되는 경우가 많으므로 전체 설정을 민감한 데이터로 취급해야 합니다. 문제 해결을 위해 구조를 공개할 때는 인증 정보를 삭제할 수 있지만 실제 구독 주소는 공개하지 마세요. 원격 파일에 접근할 수 없으면 클라이언트가 로컬 캐시를 계속 사용할 수도 있고, 최초 다운로드 실패로 해당 그룹이 비어 버릴 수도 있습니다. 오래된 노드가 남아 있다고 업데이트에 성공한 것은 아니므로 업데이트 시간과 Provider 로그를 확인하세요.

노드 Provider 설정

proxy-providers:
  provider-main:
    type: http
    url: "https://subscription.example/path?token=xxxx"
    path: ./providers/provider-main.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 900
      lazy: true

type: http는 원격에서 가져온다는 뜻이고, url은 리소스 주소, path는 로컬 캐시 경로, interval은 업데이트 간격을 지정합니다. 여러 Provider가 같은 파일을 공유하면 업데이트 중 서로 덮어쓸 수 있으므로 경로를 분리하세요. 클라이언트가 샌드박스 환경에서 실행된다면 실제 저장 위치는 앱이 관리합니다. 상대 경로는 보통 코어의 작업 디렉터리를 기준으로 해석되므로 데스크톱의 절대 경로를 그대로 복사하지 마세요.

health-check는 Provider에 포함된 노드의 사용 가능 여부를 확인합니다. 모든 정책 그룹의 선택을 자동으로 바꾸는 기능은 아니며, 탐색 결과를 반영하는 그룹은 url-test와 fallback 등입니다. 확인 주기는 신속성과 백그라운드 비용 사이에서 균형을 맞춰야 합니다. iPhone에서 Provider를 많이 설정하고 고주기로 검사하면 네트워크 확장의 작업량이 늘어납니다. 온디맨드 연결과 실제 사용 빈도를 함께 고려해 조정하세요.

Provider가 반환하는 내용은 전체 Clash 설정이 아니라 프록시 Provider 형식이어야 합니다. 일반적으로 proxies:로 시작하고 내부에 노드 목록이 들어갑니다. 원격에서 HTML 로그인 페이지, 오류 메시지 또는 일반 텍스트가 반환되면 HTTP 상태가 성공처럼 보여도 파싱할 수 없습니다. 업데이트에 실패하면 응답 콘텐츠 유형, 리디렉션, 접근 권한과 시스템 시간을 확인하세요.

규칙 Provider 설정

rule-providers:
  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    path: ./rules/private-network.yaml
    url: "https://rules.example/private-network.yaml"
    interval: 86400

  service-domains:
    type: http
    behavior: domain
    format: yaml
    path: ./rules/service-domains.yaml
    url: "https://rules.example/service-domains.yaml"
    interval: 86400

rules:
  - RULE-SET,private-network,DIRECT,no-resolve
  - RULE-SET,service-domains,노드 선택
  - MATCH,노드 선택

behavior는 규칙 집합 항목을 해석하는 방식을 결정합니다. domain은 도메인 모음, ipcidr은 주소 대역, classical은 유형과 매개변수가 포함된 고전 규칙을 담는 데 사용합니다. format은 원격 파일 형식과 일치해야 합니다. YAML 규칙 집합은 일반적으로 payload: 아래에 목록을 넣고, 텍스트 또는 바이너리 규칙 집합은 해당 형식을 사용합니다. 확장자만으로 콘텐츠 형식을 단정할 수 없으며 실제 데이터 구조를 기준으로 판단해야 합니다.

payload:
  - "+.example.com"
  - "api.example.net"
  - "*.service.example"

domain 유형 규칙 집합의 와일드카드 표현은 mihomo 규칙 집합의 의미에 맞춰야 하며, 브라우저 매칭 패턴이나 정규 표현식을 그대로 섞어 사용하지 마세요. classical 규칙 집합에는 DOMAIN-SUFFIX,example.com처럼 완전한 규칙 항목을 작성할 수 있습니다. 참조할 때 no-resolve를 추가한다면 해당 규칙 집합이 실제로 IP 유형이고 추가 해석이 필요하지 않은지 확인하세요.

업데이트, 캐시와 대체 처리

Provider 업데이트는 확인 가능한 독립 단계로 관리해야 합니다. 노드가 갑자기 사라지면 먼저 원격 파일이 변경되었는지 확인한 다음 필터 조건과 정책 그룹 참조를 살펴보세요. 규칙 동작이 갑자기 달라졌다면 규칙 집합 업데이트 시간을 기록하고 데이터 소스의 분류가 바뀌었는지 확인하세요. 모든 문제를 주 설정 탓으로 돌리면 외부 데이터의 변화를 놓칠 수 있습니다.

처음 실행할 때 Provider 파일을 가져오지 못하면 이를 참조하는 그룹이나 규칙 집합을 완전히 구성할 수 없습니다. 기존 캐시는 임시 대체 수단일 뿐, 잘못된 URL을 장기간 숨기는 용도로 사용해서는 안 됩니다. 원격에 접근할 수 없다면 네트워크가 허용되는 시점에 업데이트한 뒤 해당 설정을 활성화하세요. 핵심 LAN 규칙과 최종 대체 규칙을 주 설정에 남겨 외부 규칙 집합에 기본 연결을 전적으로 의존하지 않게 하는 방법도 있습니다.

업데이트 간격은 짧을수록 좋은 것이 아닙니다. 노드 구독은 하루에 여러 번 갱신될 수 있지만 안정적인 규칙 집합은 하루 한 번 또는 그보다 낮은 빈도면 충분합니다. 고주기 업데이트는 요청·쓰기·파싱 횟수를 늘리며 모바일 네트워크에서는 특히 불필요합니다. 설정 업데이트에 실패하면 “주소 접근 가능 여부—반환 내용 정확성—로컬 경로 쓰기 가능 여부—format과 behavior 일치 여부—참조 이름 정확성” 순서로 확인하세요.

08 / Override

오버라이드, 병합과 설정 문제 해결

구독, 로컬 오버라이드와 최종 설정

대부분의 클라이언트는 구독 원문을 그대로 실행하지 않습니다. 일반적인 과정은 구독 다운로드, 기본 설정 파싱, 로컬 오버라이드 또는 스크립트 적용, 최종 설정 생성, mihomo 코어 전달 순서입니다. 이 계층을 이해하는 것이 중요합니다. 구독 페이지에서 특정 규칙을 보았다고 해서 최종 실행 설정에도 그대로 남아 있다는 뜻은 아니며, 로컬에서 편집한 필드도 다음 구독 업데이트 때 교체될 수 있습니다.

구독에 넣기 적합한 내용은 서버에서 관리하는 노드, 기본 정책 그룹과 일반 규칙입니다. 로컬 오버라이드에는 포트, LAN 스위치, 기기 전용 DNS, 개인 규칙과 플랫폼별 차이를 넣는 것이 좋습니다. 자동 업데이트되는 구독 파일에 개인 수정 사항을 많이 장기간 유지하지 마세요. 업데이트할 때마다 다시 대조해야 합니다.

덮어쓰기와 깊은 병합은 다릅니다

덮어쓰기는 보통 새 값이 기존 값을 대체한다는 뜻이고, 깊은 병합은 매핑 내부로 들어가 지정한 하위 키만 교체합니다. 목록의 처리 방식은 더 다양합니다. 어떤 병합기는 목록 전체를 대체하고, 어떤 병합기는 앞에 추가·뒤에 추가 또는 이름 기준 수정을 지원합니다. “merge”라는 단어만으로 동작을 판단하지 말고, 클라이언트의 오버라이드 설명을 확인한 뒤 최종 설정을 내보내 검증하세요.

# 기본 설정
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query

# 변경할 내용
dns:
  ipv6: false
  nameserver:
    - https://8.8.8.8/dns-query

깊은 병합을 사용하면 최종 DNS에 enable과 enhanced-mode가 남는 동시에 ipv6와 nameserver만 교체될 수 있습니다. 최상위 덮어쓰기를 사용하면 기존 DNS 블록이 통째로 사라지고 오버라이드에 있는 두 필드만 남을 수 있습니다. 목록을 추가하는 방식이라면 nameserver가 두 개 모두 존재할 수도 있습니다. 클라이언트가 어떤 의미론을 사용하는지는 최종 결과를 확인해야 알 수 있습니다.

규칙의 앞에 추가, 뒤에 추가와 삭제

개인 규칙은 규칙이 일치하면 즉시 중단되므로 일반적으로 구독 규칙보다 앞에 배치해야 합니다. 특정 내부 도메인을 직접 연결하려면 해당 도메인을 포괄할 수 있는 넓은 프록시 규칙보다 앞에 둬야 합니다. MATCH 뒤에 추가하면 적용되지 않습니다. 오버라이드 도구가 prepend와 append를 지원한다면 정확한 예외는 prepend에 두고 최종 대체 규칙은 주 설정에 맡기세요.

# 논리 예시: 앞에 추가하는 규칙
rules-prepend:
  - DOMAIN,router.example,DIRECT
  - DOMAIN-SUFFIX,internal.example,DIRECT

# 논리 예시: MATCH 뒤에는 뒤쪽 내용을 배치할 수 없음
rules-append:
  - DOMAIN-SUFFIX,archive.example,노드 선택

위의 키 이름은 병합 로직을 설명하기 위한 예시이며 모든 클라이언트가 직접 인식하는 것은 아닙니다. 실제 작업에서는 클라이언트가 제공하는 오버라이드 화면이나 문서에 정의된 키를 사용하세요. 규칙 삭제는 추가보다 텍스트 차이의 영향을 더 많이 받습니다. 공백, 정책 그룹 이름 또는 매개변수가 다르면 정확한 삭제가 실패할 수 있습니다. 더 안정적인 방법은 취약한 문자열 삭제에 의존하지 않고 더 구체적인 앞쪽 규칙 하나로 기존 결과를 덮는 것입니다.

최소 설정으로 문제 위치 찾기

복잡한 설정에 문제가 생겼을 때 DNS, 노드, 정책 그룹과 규칙을 동시에 바꾸지 마세요. 먼저 알려진 노드 하나, select 그룹 하나, MATCH 규칙 하나만 남긴 최소 설정을 만드세요. 최소 설정으로 연결되면 제거한 계층 중 하나에 문제가 있다는 뜻입니다. 이후 DNS, Provider, 정책 그룹, 규칙 순서로 한 단계씩 다시 추가하세요. 최소 설정에서도 실패한다면 노드 매개변수, 시스템 권한과 현재 네트워크를 집중적으로 확인합니다.

mixed-port: 7890
mode: rule
log-level: info

proxies:
  - name: Test
    type: trojan
    server: example.com
    port: 443
    password: "your-password"
    sni: example.com

proxy-groups:
  - name: TEST
    type: select
    proxies:
      - Test
      - DIRECT

rules:
  - MATCH,TEST

모바일에서 테스트할 때는 시스템 VPN 상태도 고려해야 합니다. 네트워크 확장을 점유할 수 있는 다른 앱을 먼저 종료하고 현재 설정을 다시 활성화한 뒤, 클라이언트가 시스템 VPN을 성공적으로 구축했는지 확인하세요. Wi‑Fi에서는 정상인데 셀룰러 네트워크에서 실패한다면 앱의 셀룰러 데이터 권한, 온디맨드 연결 조건과 DNS 접근성을 점검합니다. 특정 Wi‑Fi에서만 실패한다면 해당 네트워크의 인증 페이지, 라우터 필터와 비공개 주소 정책을 확인하세요.

오류 유형별 계층적 처리

저장, 롤백과 변경 기록

수정하기 전에 작동하는 설정을 하나 보관하고, 로컬 사본에는 알아보기 쉬운 파일 이름을 사용하세요. 한 번에 한 종류의 필드만 변경하고 변경 목적과 테스트 결과를 기록합니다. 문제가 발견되면 여러 편집을 기억에 의존해 되돌리기보다 이전의 작동하는 설정으로 바로 돌아가는 편이 확실합니다. 구독 주소와 노드 인증 정보는 공개 코드 저장소에 넣어서는 안 됩니다. 구조를 기록해야 한다면 서버, 비밀번호와 접근 매개변수를 명확한 학습용 가짜 값으로 바꾸세요.

편집을 마친 뒤 네 계층으로 확인하세요. 첫 번째는 YAML로 들여쓰기·콜론·목록·중복 키를 점검합니다. 두 번째는 참조로 정책 그룹·Provider·규칙 대상 이름이 일치하는지 확인합니다. 세 번째는 실행으로 포트 충돌이 없고 DNS와 Provider가 로드되는지 봅니다. 네 번째는 동작으로 직접 연결·프록시·LAN·최종 대체 규칙이 각각 예상대로 일치하는지 검증합니다. 네 계층을 모두 통과해야 설정이 완료된 것으로 볼 수 있습니다.

참고 문서에서 실제 작업으로 돌아가기

목표가 최초 연결을 완료하는 것이라면 사용 문서로 돌아가 구독 가져오기, 모드 선택, 연결 설정과 검증을 순서대로 진행하세요. 클라이언트를 교체하거나 설치하려면 다운로드 페이지에서 Windows, Android, iOS, macOS 또는 Linux에 해당하는 경로를 선택할 수 있습니다. 설정은 로드되었지만 웹페이지에 인증서 오류가 계속 표시된다면 HTTPS 인증서 오류의 원인과 해결 방법을 확인하세요. iPhone에서 백그라운드 배터리 소모가 비정상적으로 크다면 네트워크 확장의 백그라운드 작동 방식과 절전 설정을 참고하세요.

설정 관리의 핵심은 모든 필드를 하나의 파일에 넣는 것이 아니라 참조를 명확하게 유지하고, 업데이트 출처를 추적할 수 있게 하며, 플랫폼 차이를 격리하는 데 있습니다. 주 설정은 안정적인 구조를 담당하고 Provider는 업데이트 가능한 데이터를 제공하며 로컬 오버라이드는 기기와 개인 요구를 처리합니다. 문제가 발생하면 YAML, DNS, 노드, 정책 그룹, 규칙, 시스템 네트워크 순서로 범위를 좁혀 가는 것이 설정 전체를 교체하는 것보다 실제 원인을 찾기 쉽습니다.