Clash 설정 파일
참고서

01 / DOCUMENT MAP

YAML 구조 개요와 읽는 순서

최상위 필드가 하나의 설정을 구성하는 방식

Clash 설정 파일은 보통 config.yaml로 이름을 지정하며, 본질적으로 매핑, 목록, 스칼라로 이루어진 데이터 트리입니다. 최상위 매핑은 기능 영역을 나눕니다. 포트와 실행 모드는 트래픽이 커널로 들어오는 방식을 정하고, dns는 도메인 해석을 제어하며, proxies는 개별 프록시 노드를 설명합니다. proxy-groups는 노드를 선택하거나 자동으로 테스트할 수 있는 정책으로 구성하고, rules는 연결을 순서대로 특정 정책 그룹으로 보냅니다. mihomo에서는 proxy-providers, rule-providers, tun, sniffer 등의 확장 영역도 사용할 수 있습니다.

설정을 해석할 때 들여쓰기는 부모와 자식의 관계를 나타냅니다. 같은 수준의 필드는 동일한 공백 수를 사용해야 하며, 일반적으로 한 단계마다 공백 두 칸을 사용합니다. 목록 항목은 하이픈으로 시작하고, 하이픈 뒤의 객체에도 하위 필드를 계속 포함할 수 있습니다. YAML에서는 문자열에 따옴표를 생략할 수 있지만 노드 이름, 비밀번호, 정규식, 콜론이나 특수 기호가 포함된 값은 잘못 해석될 수 있으므로 따옴표를 붙이는 편이 안전합니다. 불리언 값은 true와 false를 사용하고, 숫자 포트는 숫자 형식을 유지하며 추가 설명이 붙은 문자열로 작성하지 마세요.

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

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

proxies:
  - name: "예시 노드"
    type: ss
    server: example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "예시 노드"
      - DIRECT

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

매핑, 목록 및 이름 참조

dns: 뒤에는 매핑 필드가 오고, proxies: 뒤에는 객체 목록이 옵니다. 정책 그룹의 proxies도 목록이지만 노드를 다시 선언하는 것이 아니라 이름을 참조합니다. 이름은 대소문자, 공백, 기호를 포함해 한 글자씩 정확히 일치해야 합니다. 노드 이름이 “홍콩 01”이라면 정책 그룹에 “홍콩01”로 작성하는 순간 존재하지 않는 참조가 됩니다. 규칙의 마지막 부분도 DIRECT, REJECT 같은 정책 그룹 이름이나 내장 정책을 참조합니다. 이름을 변경할 때는 정책 그룹, 규칙, 인터페이스 오버라이드의 모든 참조 위치를 함께 확인해야 합니다.

YAML 앵커와 별칭은 중복을 줄일 수 있지만, 모든 그래픽 클라이언트의 저장·변환·오버라이드 과정에서 앵커가 완전히 보존되는 것은 아닙니다. 장기적으로 관리할 공개 설정은 명확한 명시적 필드를 우선 사용하세요. 설정이 커지면 노드와 규칙을 provider 파일로 분리하고 메인 설정에서 참조할 수 있습니다. 단일 파일에 수천 줄을 쌓는 것보다 업데이트가 쉽고, “노드 데이터”와 “라우팅 로직”도 분리해 관리할 수 있습니다.

최소 설정과 로딩 범위

실행 가능한 최소 설정이 곧 정상적인 인터넷 연결을 보장하는 것은 아닙니다. 포트와 모드만 설정하면 커널이 정상적으로 수신 대기하더라도, 규칙이 참조하는 정책이 없거나 DNS가 노드 도메인을 해석하지 못해 연결이 실패할 수 있습니다. 점검은 문법부터 시작해 참조의 완전성을 확인하고, 마지막으로 네트워크 동작을 검증해야 합니다. 클라이언트에 “설정 로드 성공”이 표시되는 것은 구조를 기본적으로 해석할 수 있다는 뜻일 뿐, 모든 노드 인증 정보, 원격 프로바이더 주소와 규칙 대상이 유효하다는 의미는 아닙니다.

또한 커널마다 유지보수 단계에 따라 지원하는 필드 범위가 완전히 같지 않습니다. 원본 Clash, Clash Meta와 현재 mihomo의 명칭 변화 및 호환 관계는 커널 버전 차이 안내를 참고하세요. 클라이언트가 mihomo 커널을 사용한다면 확장 필드를 이용할 수 있지만, 여러 클라이언트에서 설정을 공유하려면 각 클라이언트에 실제로 탑재된 커널을 먼저 확인해야 합니다. 클라이언트 화면의 이름만 보고 판단하지 마세요.

02 / RUNTIME

공통 필드: 포트, 모드 및 제어 인터페이스

mixed-port, port 및 socks-port

mixed-port는 하나의 수신 포트에서 HTTP와 SOCKS5 프록시 연결을 모두 받아 데스크톱 클라이언트와 대부분의 수동 프록시 환경에 적합합니다. port는 HTTP 프록시만 제공하고 socks-port는 SOCKS5만 제공합니다. 세 필드는 필요에 따라 조합할 수 있지만 여러 필드가 같은 포트를 사용하거나 다른 로컬 프로그램의 수신 포트와 충돌하게 해서는 안 됩니다. 그래픽 클라이언트가 포트 설정을 관리하는 경우 시작 시 화면의 값이 설정 파일을 덮어쓸 수 있으므로, 문제를 확인할 때는 화면과 실제 실행 로그를 함께 살펴보세요.

애플리케이션에 프록시 주소를 입력할 때 같은 기기에서 실행 중인 프로그램은 일반적으로 127.0.0.1에 연결합니다. LAN의 다른 기기는 Clash가 실행 중인 기기의 LAN 주소에 연결해야 하며, allow-lan을 활성화하고 시스템 방화벽이 해당 포트를 허용하는지도 확인해야 합니다. LAN 수신을 개방하면 접근 범위가 넓어지므로 bind-address로 인터페이스를 제한하고 필요하면 인증 정보도 설정하세요. 포트 설정 후에는 포트를 계속 바꿔 보는 대신 운영체제의 네트워크 연결 정보로 수신 대기 상태를 확인할 수 있습니다.

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

rule, global 및 direct 모드

mode: rule은 rules를 위에서 아래로 매칭하는 일상적인 기본 모드입니다. global은 프록시 가능한 트래픽을 하나의 전역 정책으로 보내 특정 노드의 사용 가능 여부를 임시로 확인할 때 적합하지만, 기존의 라우팅 의도를 우회합니다. direct는 트래픽을 직접 연결해 문제가 프록시 경로에서 비롯됐는지 빠르게 판단할 때 사용합니다. 화면에서 모드를 전환하면 일부 클라이언트는 YAML을 수정하지 않고 실행 상태만 변경합니다. 재시작 후 유지되는지는 클라이언트 설정에 따라 달라집니다.

장애를 좁힐 때는 비교 테스트를 해 보세요. 규칙 모드에서는 실패하지만 전역 모드에서는 성공한다면 규칙 대상, 규칙 순서 또는 정책 그룹 참조에 문제가 있을 가능성이 큽니다. 전역 모드도 실패하면 노드, 시스템 프록시, TUN, DNS 또는 네트워크 환경을 계속 확인해야 합니다. 직접 연결 모드에서도 로컬 서비스에 접근할 수 없다면 문제는 Clash 설정과 무관할 수 있습니다. 모드 전환은 진단 수단일 뿐이므로 테스트가 끝나면 규칙 모드로 복원해 도메인 및 지역 라우팅이 장기간 사라지지 않도록 하세요.

로그, IPv6 및 외부 컨트롤러

log-level에서 자주 사용하는 값은 silent, error, warning, info, debug입니다. 일상적인 사용에는 info면 충분합니다. 규칙 매칭이나 연결 단계가 불분명할 때만 잠시 debug로 전환해 정보를 수집한 뒤 복원하세요. 로그가 빠르게 늘어나는 것을 막을 수 있습니다. 로그에서는 대상 도메인, 매칭된 규칙, 최종 정책, DNS 오류와 연결 시간 초과를 중점적으로 확인하고 마지막 줄만 보지 마세요.

ipv6은 커널이 IPv6 관련 기능을 처리할지 제어하지만 DNS 영역에도 별도의 IPv6 옵션이 있습니다. 네트워크가 안정적인 IPv6을 제공하고 노드 경로도 지원한다면 활성화할 수 있습니다. 로컬에는 IPv6 주소가 있지만 사용 가능한 출구가 없으면 애플리케이션이 IPv6 연결을 먼저 시도한 뒤 시간 초과를 기다리는 현상이 발생할 수 있습니다. 문제를 확인할 때는 시스템 네트워크, DNS 응답, Clash 최상위 스위치와 DNS 하위 항목을 각각 확인하세요.

external-controller는 제어 패널과 클라이언트 프론트엔드에 127.0.0.1:9090 같은 API를 제공합니다. 수신 범위가 로컬을 벗어나면 secret을 설정하고 방화벽 접근을 제한해야 합니다. 제어 인터페이스는 프록시 포트가 아니므로 브라우저나 애플리케이션에서 HTTP 프록시로 사용할 수 없습니다. external-ui는 정적 패널 파일 디렉터리를 가리킵니다. 경로는 실행 환경의 실제 디렉터리를 기준으로 정해야 하며, 한 기기의 절대 경로를 다른 시스템에 그대로 동기화해서는 안 됩니다.

external-controller: 127.0.0.1:9090
secret: "your-controller-secret"
external-ui: ui

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

profile.store-selected는 정책 그룹의 선택 결과를 저장해 재시작 후에도 이전 선택을 유지합니다. store-fake-ip는 Fake-IP 매핑의 영속화와 관련됩니다. 여러 기기에서 설정을 동기화할 때 실행 상태까지 YAML과 함께 동기화된다고 가정해서는 안 됩니다. 구독, 오버라이드, 비공개 저장소라는 세 가지 동기화 경로의 범위는 Clash 여러 기기 설정 동기화에서 계속 확인할 수 있습니다.

03 / DNS PIPELINE

DNS 설정과 Fake-IP 해석 과정

DNS 요청은 어떤 단계를 거치는가

Clash의 DNS 모듈은 단순히 도메인을 특정 서버로 전달하는 기능이 아닙니다. 활성화되면 애플리케이션의 조회를 받아 nameserver-policy와 fallback 등의 규칙에 따라 업스트림을 선택하고, 해석 결과를 규칙 매칭과 연결 과정으로 전달합니다. 노드 서버 자체가 도메인을 사용하는 경우에는 bootstrap 해석도 필요합니다. 커널이 노드 도메인의 주소를 먼저 얻어야 암호화 연결을 설정할 수 있기 때문입니다. 따라서 DNS 장애는 웹 도메인이 열리지 않는 형태뿐 아니라 모든 도메인 노드가 동시에 시간 초과되는 형태로도 나타날 수 있습니다.

listen은 DNS 서비스의 수신 주소를 지정합니다. 데스크톱 그래픽 클라이언트는 보통 시스템 DNS나 TUN 가로채기를 이미 처리하므로 사용자가 시스템 DNS를 해당 포트로 수동 변경할 필요가 없을 수 있습니다. 라우터나 LAN 게이트웨이에서는 클라이언트의 조회를 이곳으로 전달하는 경우가 많습니다. 0.0.0.0에서 수신한다면 방화벽으로 접근 범위를 제한하고, 로컬에서만 사용할 때는 루프백 주소에서 수신하는 것을 우선하세요.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  use-hosts: true
  respect-rules: true
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  proxy-server-nameserver:
    - https://1.1.1.1/dns-query
  direct-nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "+.stun.*.*"

default-nameserver와 nameserver의 차이

default-nameserver는 주로 암호화 DNS 업스트림 자체의 도메인을 해석합니다. 보통 직접 접근 가능한 IP 형식의 DNS 주소를 입력해 “DoH 도메인에 접근하려면 먼저 DoH 도메인을 해석해야 하는데 해석도 DoH에 의존하는” 순환을 피합니다. nameserver는 주요 조회 업스트림으로 UDP, TCP, DoT 또는 DoH 주소를 입력할 수 있습니다. 업스트림은 많을수록 좋은 것이 아닙니다. 동작 방식이 크게 다른 해석기를 섞으면 결과를 예측하기 어렵고 문제 해결 분기도 늘어납니다.

proxy-server-nameserver는 프록시 노드 서버 도메인을 별도로 해석해 노드 도메인 조회가 잘못된 경로로 향하지 않도록 할 수 있습니다. direct-nameserver는 직접 연결 도메인 해석에 사용하며, 로컬 지역 트래픽을 가까운 해석기로 보내기에 적합합니다. respect-rules를 활성화하면 DNS 조회가 규칙 경로를 더 많이 참조하므로 프록시 노드 도메인에 독립적인 해석 출구가 있는지 확인해야 합니다. 그렇지 않으면 정책 의존 순환이 발생할 수 있습니다.

Fake-IP와 Redir-Host 선택 방법

enhanced-mode: fake-ip은 예약 주소 대역에서 임시 주소를 할당해 도메인에 매핑합니다. 애플리케이션은 먼저 이 매핑 주소를 받고, 연결이 들어오면 커널이 원래 도메인을 복원해 도메인 규칙을 적용합니다. 연결 단계에서 도메인 정보를 유지할 수 있어 “먼저 IP로 해석되어 IP 규칙만 매칭되는” 상황을 줄일 수 있습니다. Fake-IP는 실제 연결 대상이 예약 대역에 있다는 뜻이 아니라 커널 내부의 도메인 매핑 식별자일 뿐입니다.

redir-host는 실제 해석 주소를 반환하고, 이후 투명 프록시나 스니핑 기능으로 도메인 정보를 보완합니다. LAN 검색, 로컬 도메인, 특수 인증 또는 해석 주소를 직접 확인하는 일부 프로그램은 실제 주소 모드가 더 적합할 수 있지만, 규칙 정밀도와 캐시 동작은 플랫폼별로 평가해야 합니다. 대부분의 데스크톱 및 모바일 일반 프록시 환경에서는 먼저 Fake-IP를 사용하고, 호환되지 않는 도메인을 fake-ip-filter에 추가하는 편이 낫습니다.

제외 항목은 가능한 한 구체적으로 작성하세요. *.lan과 *.local은 로컬 기기 검색에 자주 사용되며, 시간 동기화, STUN, 게임 플랫폼과 일부 기업 내부망 도메인도 실제 결과가 필요할 수 있습니다. 지나치게 넓은 와일드카드는 많은 도메인이 Fake-IP를 우회하게 만들어 규칙 매칭의 일관성을 낮춥니다. 매핑, 규칙 매칭, 제외 항목의 전체 과정은 Fake-IP 모드 원리에서 확인하세요.

DNS 유출 및 해석 장애를 찾는 방법

DNS 경로 이상은 보통 세 가지 문제로 나눠야 합니다. 어떤 구성 요소가 조회를 보냈는지, 요청이 어느 업스트림으로 전달됐는지, 최종 연결이 어떤 정책을 사용했는지입니다. 브라우저가 자체 보안 DNS를 사용할 수 있고, 시스템 서비스가 애플리케이션 프록시를 우회할 수도 있으며, TUN이 DNS 가로채기로 조회를 맡을 수도 있습니다. 웹페이지에 표시된 해석기 이름만으로 전체 트래픽 경로를 단정할 수는 없습니다. 테스트에 참여하지 않는 브라우저 자체 DNS를 먼저 끈 뒤 Clash 로그에서 조회 및 규칙 기록을 확인하세요.

구독은 업데이트되지만 모든 노드에서 도메인 해석 실패가 표시된다면 먼저 default-nameserver와 노드 도메인 해석을 확인하세요. 일반 웹사이트는 실패하지만 IP 주소에는 연결된다면 주요 nameserver, 수신 포트와 시스템 DNS 인계를 점검합니다. 일부 LAN 기기만 작동하지 않을 때는 Fake-IP 제외 항목을 확인하세요. 간헐적인 시간 초과가 발생하면 우선 접근 가능하다고 확인된 업스트림 하나만 남겨 업스트림 간 차이, 네트워크 차단과 캐시 영향을 분리한 뒤 하나씩 복원할 수 있습니다.

04 / PROXY OBJECTS

프록시 노드 필드와 프로토콜 객체

모든 노드에 공통으로 필요한 식별 필드

proxies의 각 객체에는 최소한 name, type, server, port가 필요하며 나머지 필드는 프로토콜에 따라 달라집니다. name은 설정 내부의 고유 식별자이자 클라이언트 화면에 표시되는 이름입니다. 이름이 중복되면 정책 그룹 참조와 화면의 선택 항목이 모호해질 수 있으므로 설정을 생성할 때 고유성을 보장해야 합니다. server에는 도메인이나 IP를 사용할 수 있습니다. 도메인을 사용하면 서버 주소를 전환하기 쉽지만 노드 도메인 해석이라는 사전 단계가 추가됩니다.

udp는 노드가 UDP를 전달할 수 있는지 나타내지만 실제 사용 가능 여부는 프로토콜, 서버와 클라이언트 진입점에도 달려 있습니다. 게임, 음성, QUIC 및 일부 DNS 트래픽은 UDP에 의존할 수 있습니다. 이 필드를 활성화했다고 경로가 반드시 지원되는 것은 아닙니다. 서버나 중간 네트워크가 지원하지 않으면 로그에 핸드셰이크는 성공했지만 UDP 응답이 없는 현상이 나타날 수 있습니다. interface-name과 routing-mark는 멀티 NIC나 Linux 라우팅에 가까운 제어 필드이므로 일반적인 데스크톱 설정에는 굳이 추가하지 않아도 됩니다.

Shadowsocks 및 Trojan 예제

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

  - name: "Trojan-예시"
    type: trojan
    server: trojan.example.com
    port: 443
    password: "your-password"
    sni: service.example.com
    skip-cert-verify: false
    udp: true
    network: tcp

Shadowsocks의 cipher는 서버와 일치해야 하며 비밀번호도 원문 그대로 입력해야 합니다. 필드 이름이 같다는 이유로 서로 다른 프로토콜의 인증 정보를 바꿔 쓰지 마세요. Trojan은 TLS에 의존하며 sni는 핸드셰이크의 서버 이름을 지정하므로 일반적으로 서버 인증서에 포함된 도메인과 일치해야 합니다. skip-cert-verify: false는 인증서 검증을 수행한다는 뜻으로 정상 설정에서 우선해야 합니다. 검증에 실패하면 기기 시간, 인증서 도메인, SNI와 서버 인증서 체인을 확인하세요.

network는 TCP, WebSocket, gRPC 같은 하위 전송을 설명합니다. WebSocket을 선택하면 경로와 요청 헤더도 제공해야 하고, gRPC를 선택하면 보통 서비스 이름이 필요합니다. 전송 필드는 서버 진입점과 완전히 일치해야 합니다. 흔한 실수는 프로토콜, 주소와 비밀번호만 복사하고 전송 계층의 경로를 빠뜨리는 것입니다. 그러면 TCP로 포트에는 도달해도 핸드셰이크가 계속 실패합니다.

VMess 및 VLESS의 계층형 필드

proxies:
  - name: "VLESS-WS-예시"
    type: vless
    server: edge.example.com
    port: 443
    uuid: "00000000-0000-4000-8000-000000000000"
    network: ws
    tls: true
    servername: service.example.com
    udp: true
    ws-opts:
      path: /network-path
      headers:
        Host: service.example.com

  - name: "VMess-gRPC-예시"
    type: vmess
    server: grpc.example.com
    port: 443
    uuid: "00000000-0000-4000-8000-000000000000"
    alterId: 0
    cipher: auto
    tls: true
    servername: grpc.example.com
    network: grpc
    grpc-opts:
      grpc-service-name: proxy-service

VLESS와 VMess는 모두 UUID 형식의 식별 정보를 사용하지만 프로토콜 동작과 필드 구성은 다릅니다. ws-opts와 grpc-opts는 network에 대응하는 중첩 매핑이므로 들여쓰기가 어긋나면 매개변수가 노드 객체의 잘못된 계층에 들어갑니다. TLS 환경에서는 연결 주소, SNI 또는 servername, HTTP Host가 서로 다를 수 있습니다. 연결 주소는 실제 접속 대상을 정하고, SNI는 TLS 인증서와 가상 호스트 선택에 사용되며, Host는 HTTP 또는 WebSocket 요청 헤더에 속합니다. 세 값이 같은지는 서버 배포 방식에 따라 결정되므로 경험만으로 서로 바꿔서는 안 됩니다.

예시 UUID와 도메인은 필드 구조를 보여 주기 위한 것이며 실제 연결에 사용할 수 없습니다. 실제 노드 데이터는 사용 권한이 있는 서비스 설정에서 가져와야 합니다. 구독으로 생성된 노드는 전송 필드 하나만 빠져도 원인을 파악하기 어려운 차이가 생기므로 항목별 수동 수정을 권장하지 않습니다. provider로 불러온 뒤 정책 그룹과 규칙으로 관리하는 편이 적합합니다.

Reality, 인증서 및 지문 관련 필드

mihomo가 지원하는 일부 VLESS 설정에는 공개 키, 짧은 식별자와 클라이언트 지문 같은 Reality 매개변수가 포함됩니다. 필드 이름과 계층은 현재 커널이 지원하는 형식을 따르고 서버 설정과 일치해야 합니다. 이러한 기능은 구형 커널이나 클라이언트에서 빠져 있을 수 있으므로 다른 기기에 설정을 동기화하기 전에 커널 호환성을 확인하세요. “필드 미지원” 또는 “설정 해석 실패”가 발생하면 먼저 클라이언트의 커널 유형을 확인한 뒤 필드를 조정할지 해당 설정을 지원하는 클라이언트로 바꿀지 결정해야 합니다.

client-fingerprint는 TLS 클라이언트 지문 모방에 영향을 주지만 모든 핸드셰이크 문제를 해결하는 만능 스위치는 아닙니다. 인증서 이름 오류, 시스템 시간 오차, SNI 불일치와 네트워크 차단은 각각 따로 처리해야 합니다. 클라이언트 선택 시 데스크톱과 모바일 모두 설치 패키지 페이지에서 Clash Plus를 우선 선택하세요. 다른 화면이나 시스템 대응이 필요할 때 Clash Verge Rev, FlClash, Clash Nyanpasu, Clash Meta for Android, Surfboard, ClashX Meta와 보관된 Clash for Windows를 비교하면 됩니다.

05 / POLICY GROUPS

정책 그룹 필드와 선택 로직

select: 선택을 사용자에게 맡기기

정책 그룹은 규칙과 노드 사이의 중간 계층입니다. 규칙이 변경될 수 있는 특정 노드 이름을 직접 가리키기보다는 “노드 선택”, “스트리밍” 또는 “다운로드 서비스”처럼 안정적인 정책 그룹을 가리키는 편이 좋습니다. 노드가 업데이트되어도 정책 그룹의 구성원만 조정하면 규칙 구조는 유지됩니다. select 그룹은 사용자가 구성원 하나를 직접 선택하며, 구성원은 노드일 수도 있고 다른 정책 그룹이나 내장 정책일 수도 있습니다.

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "자동 선택"
      - "장애 전환"
      - "홍콩 노드"
      - "일본 노드"
      - DIRECT

  - name: "홍콩 노드"
    type: select
    use:
      - subscription-main
    filter: "(?i)港|hk|hong kong"

proxies는 정적 노드나 다른 그룹을 참조하고 use는 proxy-providers를 참조합니다. 두 방식은 커널 기능에 따라 함께 사용할 수 있습니다. filter는 보통 정규식으로 provider의 노드 이름을 선별하므로 명명 규칙이 결과에 직접 영향을 줍니다. 구독에서 지역 이름 형식이 바뀌면 기존 필터가 빈 그룹을 만들 수 있습니다. 설정을 관리할 때는 필터 표현식을 구독 명명에 의존하는 데이터 규칙으로 보고, 업데이트 후에도 그룹에 구성원이 남아 있는지 확인하세요.

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

url-test는 지정한 URL에 주기적으로 접속해 테스트 결과에 따라 그룹에서 적합한 노드를 선택합니다. url은 용량이 작고 응답이 안정적이며 실제 사용 경로에 맞는 테스트 리소스를 가리켜야 합니다. interval은 테스트 주기이고 tolerance는 결과가 비슷할 때 잦은 전환을 줄입니다. 속도 측정은 특정 시점에 탐색 대상이 응답하는 상황만 반영하며 다운로드 속도, 동영상 처리량이나 모든 사이트의 체감 품질과 같지 않습니다.

  - name: "자동 선택"
    type: url-test
    use:
      - subscription-main
    url: https://www.gstatic.com/generate_204
    interval: 600
    tolerance: 80
    lazy: true
    expected-status: 204

lazy: true는 정책이 실제로 사용될 때 필요에 따라 테스트를 수행한다는 뜻으로, 사용하지 않는 그룹의 탐색 요청을 줄이는 데 도움이 됩니다. 테스트 주소가 현재 네트워크에서 리디렉션되거나 차단되거나 다른 상태를 반환하면 모든 노드가 사용할 수 없는 것으로 잘못 판단될 수 있습니다. 이때는 먼저 테스트 URL의 접근 가능 여부를 직접 확인하고 안정적인 리소스로 바꾸세요. 자동 선택 그룹은 일반 웹 트래픽에 적합하지만 고정 출구 주소가 필요한 로그인 세션, 원격 관리나 허용 목록 서비스에는 수동으로 선택한 노드를 유지하는 편이 낫습니다.

fallback 및 load-balance

fallback은 목록이나 탐색 결과에 따라 사용 가능한 순서를 관리하고 현재 노드가 실패하면 다른 구성원으로 전환해 연속적인 사용 가능성을 중시합니다. 매번 지연 시간이 가장 짧은 노드를 선택한다고 보장하지는 않습니다. load-balance는 여러 연결을 여러 노드에 분산해 여러 출구를 허용할 수 있는 동시 요청에 적합합니다. 웹사이트가 동일한 로그인 과정에서 출구 변경을 이상 동작으로 간주한다면 부하 분산이 세션에 오히려 영향을 줄 수 있습니다.

  - name: "장애 전환"
    type: fallback
    proxies:
      - "홍콩 노드 01"
      - "일본 노드 01"
      - "싱가포르 노드 01"
    url: https://www.gstatic.com/generate_204
    interval: 600

  - name: "동시 분배"
    type: load-balance
    use:
      - subscription-main
    url: https://www.gstatic.com/generate_204
    interval: 600
    strategy: consistent-hashing

부하 분산 정책에서 일관성 해시는 같은 대상이 안정적인 노드로 향하도록 하고, 라운드 로빈은 연결을 분산하는 데 더 중점을 둡니다. 사용하기 전에 서비스가 출구 변경을 허용하는지 확인해야 하며, “여러 노드를 동시에 사용한다”는 말을 단일 연결의 대역폭이 합쳐진다는 뜻으로 이해해서는 안 됩니다. 하나의 TCP 연결은 보통 하나의 노드가 담당하고 여러 노드는 주로 서로 다른 연결을 나눠 처리합니다.

정책 그룹 중첩 및 순환 방지

그룹은 다른 그룹을 참조할 수 있으므로 “서비스 정책 → 지역 정책 → 노드” 계층을 만들 수 있습니다. 예를 들어 동영상 규칙이 “스트리밍”을 가리키고, 해당 그룹에서 “홍콩 노드”나 “일본 노드”를 선택하도록 구성할 수 있습니다. 이 구조는 중복을 줄이지만 계층이 지나치게 깊어지면 문제 해결이 어려워집니다. 무엇보다 순환 참조를 만들면 안 됩니다. A가 B를 포함하고 B가 다시 A를 포함하면 설정 검증이 실패하거나 실행 로직을 결정할 수 없습니다.

이름은 임시 노드 상태가 아니라 기능을 표현해야 합니다. 규칙 대상은 “메신저”, “개발 서비스”, “기본 프록시”처럼 안정적인 이름으로 지정하고, 지역 그룹은 “홍콩 노드”, “일본 노드”로 명명하며 구체적인 노드 이름은 가장 하위에 둡니다. 이렇게 하면 구독 업데이트, 노드 추가·삭제 또는 지역 필터 변경 시 상위 규칙을 다시 작성할 필요가 없습니다. 재시작 후 정책 선택이 사라진다면 profile.store-selected와 클라이언트 자체의 설정 저장 방식을 확인하세요.

06 / ROUTING RULES

규칙 문법, 매칭 순서 및 기본 처리

규칙은 위에서 아래로 처음 매칭됩니다

rules는 순서가 있는 목록입니다. 연결이 들어오면 커널은 첫 번째 항목부터 검사하고 매칭되는 즉시 해당 규칙의 정책을 적용하며, 더 “구체적인” 규칙을 찾기 위해 아래로 내려가지 않습니다. 따라서 구체적인 도메인, 서비스 규칙과 특수 직접 연결은 앞에 두고, 더 넓은 도메인 접미사 및 IP 지역 규칙은 뒤에 배치하며 마지막에는 MATCH로 남은 트래픽을 처리합니다. 규칙 순서를 거꾸로 작성하는 것은 “규칙이 존재하지만 한 번도 적용되지 않는” 주요 원인 중 하나입니다.

표준 규칙은 보통 쉼표로 구분합니다. 규칙 유형, 매칭 내용, 대상 정책 순서이며 일부 유형에는 추가 매개변수가 붙습니다. 예를 들어 DOMAIN-SUFFIX,example.com,노드 선택은 해당 도메인과 하위 도메인을 매칭하고, DOMAIN,api.example.com,DIRECT는 완전한 도메인만 매칭하며, DOMAIN-KEYWORD,example,노드 선택은 키워드가 포함된 도메인을 매칭합니다. 마지막 방식은 범위가 넓으므로 너무 일반적인 키워드는 피해야 합니다.

rules:
  - DOMAIN,router.local,DIRECT
  - DOMAIN-SUFFIX,example.cn,DIRECT
  - DOMAIN-SUFFIX,example.com,노드 선택
  - DOMAIN-KEYWORD,video,스트리밍
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

도메인 규칙의 정밀도 차이

DOMAIN은 완전한 하나의 도메인을 정확히 매칭해 특정 API, 다운로드 도메인이나 LAN 호스트를 별도로 처리할 때 적합합니다. DOMAIN-SUFFIX는 도메인 경계에 따라 주 도메인과 하위 도메인을 매칭하므로 사이트 규칙을 관리할 때 가장 자주 사용됩니다. DOMAIN-KEYWORD는 도메인에 지정 텍스트가 나타나기만 해도 매칭될 수 있어 다른 사이트에 잘못 적용되기 쉽습니다. 정확한 규칙 뒤에 배치하고 충분히 고유한 키워드를 선택하세요.

하나의 서비스가 여러 도메인을 사용한다면 홈 도메인만 추가해서는 부족한 경우가 많습니다. 웹페이지는 로그인, API, 이미지, 미디어와 정적 리소스 도메인에도 요청을 보낼 수 있습니다. 페이지 제목으로 추측하지 말고 연결 로그에서 실제 요청을 확인한 뒤 규칙을 추가하세요. 지속적으로 변하는 대형 서비스에는 많은 도메인을 수동으로 추가하기보다 잘 관리되는 rule-provider를 사용하는 편이 합리적입니다.

IP-CIDR, GEOIP 및 no-resolve

IP-CIDR은 IPv4 네트워크 대역으로 매칭하고 IP-CIDR6은 IPv6에 사용합니다. 내부망, 루프백과 특정 서비스 주소는 CIDR을 통해 직접 연결하는 경우가 많습니다. 규칙 끝의 no-resolve는 해당 IP 규칙을 매칭할 때 주소를 얻기 위한 추가 DNS 해석을 수행하지 않는다는 뜻으로, 연결 자체에 대상 IP가 이미 있는 경우에 적합합니다. 도메인을 해석한 IP가 있어야 판단할 수 있는 규칙에는 이 매개변수를 기계적으로 추가하면 안 됩니다.

GEOIP는 IP 데이터베이스로 지역을 판단합니다. 대상 IP를 얻은 뒤에 작동하므로 도메인 규칙을 완전히 대체할 수 없습니다. CDN은 네트워크 환경에 따라 서로 다른 지역의 주소를 반환할 수 있고, 하나의 사이트가 여러 지역의 인프라를 사용할 수도 있습니다. 따라서 “도메인이 특정 지역에 속한다”와 “현재 IP가 데이터베이스에서 특정 지역으로 분류된다”는 같은 의미가 아닙니다. 명확한 서비스에는 도메인이나 규칙 프로바이더를 우선 사용하고, GEOIP는 뒤쪽의 광범위한 지역 라우팅에 활용하는 편이 좋습니다.

프로세스, 포트 및 논리 조합 규칙

해당 기능을 지원하는 플랫폼과 커널에서는 PROCESS-NAME, PROCESS-PATH, DST-PORT, SRC-IP-CIDR 등의 규칙을 사용할 수 있습니다. 프로세스 규칙은 시스템이 제공하는 프로세스 정보에 의존하므로 모바일, 컨테이너, 권한 제한 환경이나 TUN 구현 차이에서는 작동하지 않을 수 있습니다. 포트 규칙은 대상 포트만 나타낼 뿐 애플리케이션 유형을 의미하지 않습니다. 많은 서비스가 443 포트를 공유하므로 포트만 기준으로 프록시를 적용하면 범위가 지나치게 넓어집니다.

mihomo의 논리 규칙은 AND, OR, NOT으로 여러 조건을 조합해 “특정 프로세스가 특정 네트워크 대역에 접근할 때” 같은 조건을 표현할 수 있습니다. 하지만 논리식이 복잡할수록 괄호, 따옴표와 매개변수 구분을 명확히 해야 합니다. 실제로 관리할 때는 먼저 일반 규칙으로 각 조건이 단독으로 매칭되는지 확인한 뒤 조합하세요. 문법 오류, 플랫폼 기능과 논리 결과를 한꺼번에 점검하는 일을 피할 수 있습니다.

rules:
  - PROCESS-NAME,example-client,노드 선택
  - DST-PORT,22,개발 서비스
  - AND,((NETWORK,TCP),(DST-PORT,443)),노드 선택
  - OR,((DOMAIN-SUFFIX,example.org),(DOMAIN-SUFFIX,example.net)),개발 서비스
  - MATCH,기본 프록시

규칙이 예상대로 매칭되지 않을 때 확인하는 방법

첫 단계는 연결 로그에서 대상 도메인이나 IP, 매칭된 규칙과 최종 정책을 확인하는 것입니다. 두 번째로 매칭된 규칙 위에 더 넓은 규칙이 있어 먼저 가로채는지 확인하세요. 세 번째로 규칙 대상 정책 그룹에서 현재 어떤 구성원이 선택되어 있는지 확인합니다. 네 번째로 DNS 모드가 도메인 정보를 보존하는지 확인하세요. 애플리케이션이 IP에 직접 연결하면 도메인 규칙은 당연히 매칭되지 않습니다. 마지막으로 rule-provider가 정상적으로 업데이트되었는지, 동작 유형이 파일 내용과 일치하는지 확인합니다.

임시 테스트에서는 정확한 규칙 하나를 목록 맨 앞에 배치하고 설정을 다시 불러온 뒤 새 연결을 시작할 수 있습니다. 기존 연결은 이전 경로를 계속 재사용할 수 있으므로 페이지만 새로 고치는 것으로는 부족할 수 있습니다. 필요하면 애플리케이션 연결을 종료하거나 연결 목록을 정리하세요. 검증이 끝나면 규칙을 적절한 계층으로 옮기세요. 지역 라우팅의 전체 YAML 구성 예제는 Clash 라우팅 분기 설정 실전에서 확인할 수 있습니다.

07 / PROVIDERS

프록시 프로바이더, 규칙 프로바이더 및 원격 업데이트

proxy-providers로 노드 데이터를 메인 설정에서 분리하기

proxy-providers는 원격 또는 로컬 노드 프로바이더를 불러오는 데 사용합니다. 메인 설정에는 프로바이더 이름, 출처, 업데이트 주기와 상태 확인만 남기고 정책 그룹은 use로 프로바이더를 참조합니다. 이렇게 하면 구독 업데이트는 노드 계층만 변경하고 포트, DNS, 정책 그룹과 규칙은 로컬 설정이 계속 관리할 수 있습니다. 구독을 완전한 설정으로 직접 사용하는 것보다 고정된 라우팅 로직을 유지하기에 적합합니다.

proxy-providers:
  subscription-main:
    type: http
    url: "https://subscription.example.com/profile.yaml"
    path: ./providers/subscription-main.yaml
    interval: 3600
    proxy: DIRECT
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600
      lazy: true

proxy-groups:
  - name: "노드 선택"
    type: select
    use:
      - subscription-main
    proxies:
      - DIRECT

type: http는 원격 주소에서 가져온다는 뜻이고, path는 다운로드한 파일의 로컬 저장 위치이며, interval은 자동 업데이트 간격입니다. proxy는 업데이트 요청이 어떤 정책을 거칠지 결정합니다. 최초 시작 시에는 프록시 정책에 사용 가능한 노드가 없을 수 있으므로 보통 DIRECT를 사용합니다. 구독 주소에 현재 네트워크에서 직접 접근할 수 없다면 클라이언트의 구독 업데이트 프록시 기능을 활용하세요. provider 자체가 아직 불러오지 않은 노드에 의존하게 만들면 시작 의존성이 생기기 쉽습니다.

상태 확인은 고정된 URL에서 노드 응답을 검증할 뿐 구독 다운로드 오류를 해결하지는 않습니다. 구독 업데이트 실패는 HTTP 상태, 네트워크 시간 초과, 만료된 주소, YAML이 아닌 응답, 파일 쓰기 실패와 해석 실패를 구분해야 합니다. 클라이언트에 같은 “업데이트 실패”가 표시되더라도 로그의 단계 정보가 원인을 찾는 기준입니다. 일반적인 처리 방법은 자주 묻는 질문에서도 확인할 수 있습니다.

rule-providers 및 behavior

rule-providers는 많은 규칙을 독립 파일로 분리하고 메인 규칙 목록에서 RULE-SET으로 참조합니다. 핵심 필드인 behavior는 프로바이더 내용의 형태를 설명합니다. domain은 도메인 항목에, ipcidr은 IP 네트워크 대역에, classical은 완전한 클래식 규칙 표현식에 적합합니다. behavior와 파일 내용이 일치하지 않으면 프로바이더가 로드되지 않거나 예상대로 매칭되지 않을 수 있습니다.

rule-providers:
  local-services:
    type: http
    behavior: domain
    format: yaml
    url: "https://rules.example.com/local-services.yaml"
    path: ./ruleset/local-services.yaml
    interval: 86400

  private-networks:
    type: file
    behavior: ipcidr
    format: yaml
    path: ./ruleset/private-networks.yaml

rules:
  - RULE-SET,private-networks,DIRECT
  - RULE-SET,local-services,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

domain behavior의 YAML 파일은 보통 payload에 도메인 항목을 저장하고, ipcidr 파일에는 네트워크 대역을 저장합니다. classical 파일의 각 항목은 메인 설정의 완전한 규칙과 비슷하지만, 일반적으로 항목 안에 최종 정책을 작성하지 않습니다. 정책은 메인 설정의 RULE-SET 행에서 지정하기 때문입니다. 참조 계층은 이동할 대상을 결정하고 프로바이더 파일은 매칭 대상을 설명하므로, 하나의 프로바이더를 여러 설정에서 서로 다른 정책으로 연결할 수 있습니다.

payload:
  - "+.example.cn"
  - "api.example.net"
  - "download.example.org"

업데이트 주기, 캐시 및 실패 시 대체

업데이트 간격은 데이터 변경 빈도에 맞춰 설정해야 합니다. 노드 구독은 짧은 주기가 필요할 수 있고 안정적인 규칙 프로바이더는 하루 단위로 업데이트해도 됩니다. 간격이 너무 짧으면 원격 요청과 설정 리로드가 늘어나며 네트워크가 불안정할 때 오류 로그가 많이 발생합니다. 원격 업데이트가 실패하면 커널은 보통 로컬 캐시 파일을 계속 사용하려 하므로 path가 위치한 디렉터리에 쓰기 권한이 있어야 하고 시스템 정리 도구가 자주 삭제해서도 안 됩니다.

처음 로드할 때 실패하면 로컬에 캐시가 없어 해당 provider를 참조하는 그룹이나 규칙 세트를 사용할 수 없을 수 있습니다. 새 기기에 배포하기 전에 원격 주소 접근 가능 여부, 응답 형식, 저장 디렉터리 생성 가능 여부를 테스트하세요. 여러 플랫폼에서 설정을 동기화할 때는 상대 경로를 우선 사용하세요. Windows, macOS, Android, iOS와 Linux는 설정 루트 디렉터리가 다르므로 한 플랫폼의 절대 경로를 고정하면 다른 기기에서 로드에 실패합니다.

구독 인증 정보와 설정 계층 분리

구독 주소에는 보통 접근 인증 정보가 포함되므로 공개 저장소, 공개 로그나 공개 스크린샷에 올려서는 안 됩니다. 여러 기기에서 동기화해야 한다면 인증 정보가 없는 메인 설정, 정책 그룹과 규칙은 비공개 관리 경로에 두고 구독 주소는 클라이언트 로컬 오버라이드나 기기 전용 파일로 추가하세요. 이렇게 하면 라우팅 로직은 공유하면서도 모든 기기가 완전히 같은 실행 매개변수를 사용하도록 강제하지 않을 수 있습니다.

설정 계층은 네 부분으로 이해할 수 있습니다. 메인 설정은 실행 방식을 담당하고, provider는 노드나 규칙 데이터를 담당하며, 정책 그룹은 선택 가능한 출구를 담당하고, 기기 오버라이드는 로컬 차이를 담당합니다. 업데이트할 때는 가능한 한 해당 계층만 수정하세요. 포트, 노드, 규칙과 기기 경로를 모두 하나의 구독 생성 파일에 넣으면 업데이트 충돌과 문제 해결 비용이 크게 늘어납니다.

08 / OVERRIDE & DEBUG

오버라이드, 병합, 검증 및 문제 해결

구독 업데이트가 수동 변경을 덮어쓰는 이유

많은 그래픽 클라이언트는 원격 구독을 실행 설정으로 변환합니다. 변환된 파일을 직접 편집하면 다음 업데이트 때 클라이언트가 내용을 다시 생성하므로 추가한 규칙, 포트와 DNS 설정이 사라질 수 있습니다. 오버라이드 기능은 구독 업데이트 후 커널이 로드하기 전에 로컬 변경 사항을 생성 결과에 다시 적용하기 위한 것입니다. 클라이언트마다 이를 오버라이드, 확장, 스크립트, 혼합 또는 설정 병합이라고 부를 수 있으며 지원하는 병합 규칙도 다릅니다.

단순 스칼라 필드는 보통 나중 값이 이전 값을 덮어씁니다. 예를 들어 로컬 mixed-port가 구독의 포트를 대체합니다. 매핑 필드는 재귀적으로 병합될 수 있어 dns.ipv6만 수정하고 나머지 DNS 항목은 유지할 수 있습니다. 목록은 구현 차이가 가장 큽니다. 어떤 구현은 rules 전체를 대체하고, 어떤 구현은 앞에 추가·뒤에 추가·삭제를 지원하며, 어떤 구현은 스크립트가 완전한 배열을 반환해야 합니다. 사용하기 전에 클라이언트의 오버라이드 안내를 확인하고 최종 생성 설정으로 결과를 검증하세요.

# 로컬 오버라이드 예시: 실제 파일 진입점은 클라이언트에 따라 다름
mixed-port: 7890
mode: rule
log-level: info

dns:
  enable: true
  ipv6: false

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

규칙 병합 시 앞에 넣을지 뒤에 넣을지 명확히 해야 합니다

규칙은 처음 매칭되는 항목을 사용하므로 추가 위치가 의미를 바꿉니다. LAN 직접 연결, 특정 도메인 수정과 구독 기본 동작보다 우선해야 하는 규칙은 보통 앞에 둡니다. 기존의 정확한 규칙에 영향을 주지 않는 보완 항목은 구독 규칙 뒤, 최종 MATCH 앞에 배치할 수 있습니다. 새 규칙을 MATCH 뒤에 단순히 추가하면 모든 남은 연결을 MATCH가 이미 가로채므로 적용되지 않습니다.

클라이언트가 목록 전체 교체만 지원한다면 오버라이드에 완전한 규칙 순서를 유지하거나, rule-provider를 사용해 사용자 지정 프로바이더를 메인 설정에서 안정적으로 참조해야 합니다. “병합 도구가 더 구체적인 규칙을 자동으로 판단한다”고 기대하지 마세요. YAML 병합은 데이터 구조만 처리할 뿐 라우팅 의미를 이해하지 못합니다. 병합할 때마다 최종 설정을 열어 사용자 지정 규칙의 위치를 검색하고 합리적인 기본 처리 항목이 하나만 있는지 확인하세요.

rules:
  # 로컬 서비스 및 LAN 규칙 우선 배치
  - DOMAIN,router.local,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

  # 사용자 지정 규칙 프로바이더
  - RULE-SET,development-services,개발 서비스

  # 일반 지역 및 기본 처리 규칙
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

로드 전 문법 및 참조 검증

문법 검증에서는 먼저 YAML을 해석할 수 있는지 확인하고, 다음으로 Clash 필드가 유효한지 확인합니다. 일반 YAML 도구는 들여쓰기, 콜론과 따옴표 오류를 찾을 수 있지만 proxy-groups가 존재하지 않는 노드를 참조하는지는 알지 못합니다. 커널의 설정 테스트는 필드 유형, 정책 참조, provider 정의와 규칙 형식까지 확인할 수 있습니다. 그래픽 클라이언트는 가져오기나 다시 불러오기 때 오류 위치를 표시하는 경우가 많습니다. Linux 명령줄 배포에서는 설치한 커널이 제공하는 설정 테스트 매개변수를 사용할 수 있으며, 실제 명령은 해당 커널의 도움말을 기준으로 해야 합니다.

행 번호가 표시되어도 해당 행만 확인하지 마세요. YAML 파서는 구조를 더 이상 이어 갈 수 없다고 판단한 위치를 보고하는 경우가 많으며, 실제 원인은 앞의 몇 줄에서 빠진 따옴표, 들여쓰기나 목록 하이픈일 수 있습니다. 오류 행에서 위로 올라가 가장 가까운 같은 수준의 필드를 찾고 들여쓰기를 비교하세요. 긴 설정은 최근 추가한 영역을 이분법으로 주석 처리해 오류가 어느 부분에 있는지 빠르게 좁힐 수 있습니다.

# Linux 환경 예시: 먼저 실제 설치된 커널의 매개변수 확인
mihomo -h

# 일반적인 설정 테스트 형식, 경로는 로컬 디렉터리에 맞게 조정
mihomo -t -f ./config.yaml

재현 가능한 문제 해결 절차

첫 단계는 커널이 시작되는지 확인하는 것입니다. 설정 로드 결과, 수신 포트와 제어 인터페이스를 확인하고 시작 전부터 실패한다면 YAML, 필드 호환성과 파일 권한을 우선 처리하세요. 두 번째 단계는 트래픽이 Clash로 들어오는지 확인하는 것입니다. 시스템 프록시, 애플리케이션 프록시, TUN 상태와 로그에 해당 요청이 나타나는지 확인하세요. 요청 기록이 없다면 트래픽이 아직 커널에 도달하지 않은 것이므로 노드나 규칙을 먼저 수정해서는 안 됩니다.

세 번째 단계는 DNS와 노드를 확인하는 것입니다. 로그로 대상 도메인이 해석되는지, 노드 서버에 접근할 수 있는지, TLS 또는 프로토콜 핸드셰이크가 어느 단계에서 실패하는지 판단합니다. 모드를 잠시 전역으로 바꾸고 사용 가능하다고 확인된 노드 하나를 선택하면 규칙 문제와 노드 문제를 분리할 수 있습니다. 네 번째 단계는 정책과 규칙을 확인하는 것입니다. 매칭된 규칙, 대상 정책 그룹, 그룹에서 현재 선택된 항목과 provider 상태를 기록하세요. 다섯 번째 단계에서야 브라우저 자체 프록시, 보안 DNS, QUIC, 프로세스 식별과 LAN 검색 같은 애플리케이션 특례를 처리합니다.

안전한 롤백과 변경 기록

한 번에 하나의 기능 영역만 수정하고 로드 가능한 설정을 한 부 보관하세요. 포트, DNS, TUN과 규칙을 동시에 바꾸면 장애가 발생했을 때 원인을 찾기 어렵습니다. 안전한 절차는 원본 설정을 복사하고 변경 목표를 기록한 뒤 한 묶음의 변경을 적용하고 문법 테스트를 실행한 다음 다시 불러온 후 새 연결을 관찰하는 것입니다. 안정성을 확인한 뒤 다음 묶음으로 넘어가세요. 설정을 비공개 버전 저장소에 넣을 때는 “LAN 도메인을 실제 해석으로 변경”이나 “개발 서비스 규칙을 앞에 배치”처럼 동작 변화를 커밋 메시지에 명확히 작성하고 단순히 “설정 업데이트”라고만 쓰지 마세요.

롤백할 때는 YAML뿐 아니라 클라이언트에 저장된 정책 선택, Fake-IP 캐시, provider 캐시와 시스템 프록시 상태도 고려해야 합니다. 파일을 복원한 뒤에도 현상이 같다면 설정을 다시 불러오고 새 연결을 만들어야 하며, 필요하면 커널을 재시작해 기존 연결이 이전 정책을 계속 사용하는 상황을 배제하세요. 모든 캐시와 설정을 먼저 지우지는 마세요. 현장 정보를 보존해야 어느 계층에서 변화가 발생했는지 판단하기 쉽습니다.

매뉴얼에서 실제 설정으로 돌아가기

처음 구축할 때는 작은 단계로 구성하는 것이 좋습니다. 먼저 mixed-port, 규칙 모드와 사용 가능한 노드 하나를 설정한 다음 “노드 선택” 정책 그룹을 만들고 기본 직접 연결 및 MATCH 규칙을 추가하세요. 트래픽이 정상인지 확인한 뒤 DNS 강화 모드를 활성화하고 provider와 서비스 규칙 프로바이더를 추가합니다. 각 단계마다 확인할 결과가 명확해지며 구독, DNS, TUN과 복잡한 규칙을 한꺼번에 도입하는 일도 피할 수 있습니다.

클라이언트를 설치하거나 변경해야 한다면 Clash 설치 패키지 페이지에서 운영체제에 맞는 항목을 선택하고, 데스크톱과 모바일에서는 Clash Plus를 우선 사용하세요. 구독 가져오기, 모드 선택과 연결 확인만 필요하다면 Clash 사용 튜토리얼로 돌아가세요. 포트 충돌, 구독 업데이트 실패, 시스템 프록시 미복원이나 특정 플랫폼의 권한 문제는 자주 묻는 질문에서 장애 유형별로 찾을 수 있습니다. Linux 데스크톱, 명령줄과 systemd 서비스 배포는 Linux에 Clash 배포를 참고하세요.