Clash 설정 파일 완벽 가이드

01YAML 구조 개요

config.yaml은 커널의 유일한 입력값입니다. Clash Verge Rev, Clash Plus, FlClash 같은 GUI 클라이언트는 본질적으로 이 파일을 관리해서 mihomo 커널에 전달하는 역할을 합니다. 노드 변경, 모드 전환, 포트 수정 등 화면에서의 모든 클릭은 결국 YAML 텍스트로 귀결됩니다. 이 파일을 이해하면 클라이언트의 동작 전체를 이해하는 것이고, 이 파일을 제대로 수정하면 모든 클라이언트에서 제대로 동작합니다.

파일 경로를 직접 외울 필요는 없습니다. Clash Verge Rev 설정 페이지에서 구독 카드를 우클릭하면 「파일 열기」로 현재 설정 원문에 바로 접근할 수 있고, 같은 메뉴에서 업데이트·편집도 가능합니다. 서버나 라우터처럼 커널을 직접 실행하는 환경에는 GUI가 없으므로, 파일 위치는 실행 옵션 -f(파일 지정) 또는 -d(디렉터리 지정)로 결정되며 클라이언트와는 무관합니다.

최상위 구조는 역할에 따라 다섯 영역으로 나뉩니다. 작성 순서에 제약은 없지만, 커뮤니티에서 관례적으로 쓰는 순서는 다음과 같습니다.

# ① 공통 필드: 포트, 모드, 로그, 외부 컨트롤
mixed-port: 7897
mode: rule
log-level: info

# ② DNS: 커널이 도메인 해석을 담당
dns:
  enable: true

# ③ 프록시 노드: 아웃바운드 목록
proxies: []

# ④ 정책 그룹: 노드 구성 방식
proxy-groups: []

# ⑤ 규칙: 트래픽 분류 판정, 위에서 아래로
rules:
  - MATCH,DIRECT

다섯 영역 외에 확장 영역도 있습니다. proxy-providers는 구독 노드를 모아주고, rule-providers는 외부 규칙 세트를 불러오며, tun은 시스템 트래픽을 가로채고, hosts는 정적 도메인 매핑 테이블, listeners는 추가 리스너입니다. 필요한 항목이 있을 때 해당 절을 찾아 보면 됩니다.

YAML 문법에는 6가지 필수 규칙이 있으며, 하나라도 어기면 활성화에 실패합니다.

• 들여쓰기는 공백만 사용하고 탭은 금지합니다. 같은 계층은 반드시 폭이 같아야 하며, 관례적으로 공백 2개를 씁니다.
• key: value에서 콜론 뒤에는 반드시 공백이 있어야 합니다. key:value는 잘못된 표기입니다.
• 목록 항목은 - 로 시작하며 하이픈 뒤에도 공백이 필요합니다. -는 부모 키와 같은 열에 두거나 더 들여써도 되지만, 파일 전체에서 통일해야 합니다.
• 문자열에 #, : 가 포함되거나 @, &, *로 시작하거나 숫자·불리언처럼 보일 때는 반드시 인용부호를 붙여야 합니다. 비밀번호 필드는 거의 항상 필요합니다.
• #로 주석을 시작하며, 줄 끝 주석은 내용과 공백으로 구분해야 합니다. 그렇지 않으면 #가 앞의 문자열에 포함되어 버립니다.
• 앵커 &name과 참조 *name으로 중복 구간을 재사용할 수 있습니다. 커널은 표준 YAML 파서로 해석하므로 이 기능을 지원합니다.

최소 동작 설정입니다. 20줄 정도로 「로컬 혼합 포트 + 단일 노드 + 중국 본토 직결·나머지는 프록시」 분류를 완성할 수 있습니다.

mixed-port: 7897
allow-lan: false
mode: rule
log-level: info
dns:
  enable: true
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
proxies:
  - name: 노드A
    type: ss
    server: ss.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
proxy-groups:
  - name: 기본 프록시
    type: select
    proxies:
      - 노드A
      - DIRECT
rules:
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,기본 프록시

수정 후 적용은 두 단계입니다. 파일을 고치고, 커널이 다시 불러오게 하는 것이죠. Clash Verge Rev에서는 설정을 다시 활성화하면 즉시 핫 리로드가 일어납니다. GUI의 시스템 프록시, TUN, 자동 시작 같은 항목은 클라이언트 설정으로 구독 파일에 기록되지 않으므로 두 가지를 혼동하면 안 됩니다.

커널 차이도 유의해야 합니다. 원조 Clash는 업데이트가 중단됐고, Clash Meta는 mihomo로 이름을 바꿔 계속 유지보수되고 있습니다. 세 세대의 커널은 필드가 서로 통용되지 않습니다. mihomo가 추가한 vless, hysteria2, tuic, wireguard 노드 유형과 논리 규칙은 예전 커널이 인식하지 못합니다. 각 클라이언트가 내장한 커널의 대응 관계는 블로그 《Clash 커널 버전별 차이 정리》에서 확인할 수 있습니다. 이 페이지의 필드는 모두 mihomo 기준입니다.

02공통 필드: 포트, 모드와 기본 동작

공통 필드는 최상위에 위치하며 커널의 리스닝, 모드, 기본 동작을 관리합니다. 특정 노드와는 무관하며, 어느 항목을 바꿔도 전역에 영향을 줍니다. 구독으로 받은 설정에는 보통 합리적인 기본값이 이미 들어 있어, 주로 손볼 곳은 포트, 모드, 로그 세 가지입니다.

포트 계열. port는 HTTP 프록시 포트, socks-port는 SOCKS5 포트, mixed-port는 두 프로토콜을 한 포트로 합친 것입니다. 시스템 프록시나 대다수 앱은 둘 중 하나만 인식하는데, 혼합 포트를 쓰면 고민할 필요가 없습니다. Clash Verge Rev는 기본적으로 7897 혼합 포트를 사용합니다. redir-port와 tproxy-port는 Linux 투명 프록시 전용이므로 데스크톱 사용자는 비워 두면 됩니다.

LAN 관련. allow-lan: true로 LAN 접속을 허용하고, bind-address가 리스닝할 네트워크 인터페이스를 결정하며 *는 모든 인터페이스를 뜻합니다. 스마트폰이나 TV가 PC의 프록시를 공유하는 전체 설정법은 블로그 《혼합 포트와 LAN 공유 프록시 설정》에서 확인하세요. 열어 두면 노출된다는 뜻이니 신뢰할 수 있는 네트워크에서만 켜고, 공용 Wi-Fi에서는 false로 유지하세요.

모드. mode는 세 가지 중 하나입니다. rule은 규칙에 따라 분류하는 일상적인 값이고, global은 전체 트래픽이 선택된 프록시 그룹을 거치며, direct는 전부 직결입니다. GUI에서 모드를 전환하는 것은 이 필드를 다시 쓰는 것과 같습니다. 규칙 문제를 진단하는 표준 방법은 이분법입니다. 먼저 global로 바꿔 프록시 연결 자체가 정상인지 확인한 뒤, rule로 되돌려 규칙을 단계별로 살펴보세요.

로그와 외부 컨트롤. log-level은 silent부터 debug까지 5단계이며, 평소에는 info로 두고 문제를 진단할 때만 잠시 debug로 올렸다가 끝나면 되돌리세요. debug 로그는 양이 많고 방문한 도메인까지 포함됩니다. external-controller는 커널 RESTful API의 리스닝 주소로, GUI와 서드파티 대시보드가 모두 이를 통해 커널을 제어합니다. 리스닝 주소를 루프백이 아닌 값으로 바꿀 때는 반드시 secret도 함께 설정해야 하며, 그렇지 않으면 같은 네트워크의 누구에게나 프록시 제어권을 넘겨주는 것과 같습니다.

동작 미세 조정. unified-delay: true는 프로토콜 핸드셰이크 차이를 없애 측정 기준을 통일하므로, 노드 간 지연 시간을 비교할 수 있게 해줍니다. tcp-concurrent: true는 후보 주소들에 동시에 연결을 시도해 가장 빠른 것을 선택합니다. find-process-mode는 프로세스 매칭을 제어하며, PROCESS-NAME 규칙이 이 값에 의존합니다. profile.store-selected: true로 수동 선택한 노드를 재시작 후에도 유지할 수 있습니다. ipv6: false는 IPv6 환경이 불안정할 때 「연결은 되는데 열리지 않는」 문제의 흔한 해법입니다.

port: 7890
socks-port: 7891
mixed-port: 7897
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true
find-process-mode: strict
external-controller: 127.0.0.1:9090
secret: "your-secret"
profile:
  store-selected: true
  store-fake-ip: false

03DNS 필드: 해석 경로와 fake-ip

DNS는 별도의 장으로 다룰 만큼 중요합니다. 분류의 정확성이 절반은 여기에 달려 있기 때문입니다. 규칙에 쓰이는 GEOIP, IP-CIDR은 모두 먼저 해석 결과가 필요한데, 해석이 오염되면 분류도 함께 틀어집니다. dns.enable: true가 전제 조건입니다. false로 두면 이 섹션 전체가 무효화되어 커널이 시스템 해석으로 되돌아가고, 가상 IP나 정책 해석이 전혀 작동하지 않습니다.

리스닝과 모드. listen은 커널 DNS 서비스의 리스닝 주소를 결정하며, TUN 모드에서는 쿼리를 커널이 내부적으로 처리하므로 시스템 쪽을 손댈 필요가 없습니다. enhanced-mode: fake-ip는 주류 선택으로, 도메인 조회 시 198.18.0.1/16 풀에서 가상 IP를 즉시 반환하고 실제 연결이 이루어질 때 커널이 도메인 기준으로 규칙을 매칭합니다. 실제 해석을 기다리는 시간을 없애 웹 페이지가 눈에 띄게 빨리 열립니다. 옛 redir-host 모드는 mihomo에서 이미 제거됐으므로, 오래된 설정에 보이면 삭제하면 됩니다.

fake-ip 경계. fake-ip-range는 기본값이 198.18.0.1/16이며, 내부 네트워크 대역과 충돌할 때만 바꾸면 됩니다. fake-ip-filter는 가상 IP를 내주지 않는 화이트리스트입니다. LAN 도메인, NTP 시간 동기화, 시스템 연결성 확인은 반드시 포함해야 하며, 그렇지 않으면 프린터, 라우터 관리 페이지, 시간 동기화가 이유 없이 실패할 수 있습니다. 아래 예제에 흔히 쓰는 항목을 넣었으니 그대로 쓰고 자신의 내부 도메인을 추가하세요.

해석기 그룹. nameserver는 기본 그룹으로 여러 작성 방식(아래 표 참고)을 지원하며, 여러 서버에 동시 질의해 가장 빠른 응답을 취합니다. proxy-server-nameserver는 노드 도메인 전용 해석기입니다. 노드 주소 자체도 도메인일 수 있는데, 신뢰할 수 있는 해석기를 지정해 「프록시에 먼저 연결해야 프록시 주소를 해석할 수 있는」 순환 오류를 피할 수 있습니다. direct-nameserver는 직결 도메인용으로, 보통 통신사나 중국 본토 공공 DNS를 넣습니다.

정책 해석. nameserver-policy는 도메인별로 해석기를 지정하며, 키는 구체적인 도메인, geosite: 카테고리, rule-set: 규칙 세트 모두 가능합니다. 중국 본토 도메인은 통신사 DoH로, 그 외는 신뢰할 수 있는 해외 DoH로 보내는 식의 구성이 모두 이 항목으로 표현됩니다. 예전 필드 fallback은 더 이상 사용되지 않으며, mihomo에서는 nameserver-policy가 이를 대체하므로 마이그레이션할 때는 「어떤 도메인은 어떤 서버 그룹」 방식으로 다시 작성하세요.

그 외 옵션. respect-rules: true는 해외 해석기도 규칙에 따라 아웃바운드를 결정하게 하며, proxy-server-nameserver와 함께 써야 합니다. use-hosts와 use-system-hosts는 hosts 테이블 출처를 제어합니다. prefer-h3는 DoH 질의가 HTTP/3를 우선 사용하게 합니다.

dns:
  enable: true
  listen: 0.0.0.0:53
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "ntp.*.com"
    - "+.msftconnecttest.com"
    - "+.msftncsi.com"
  use-hosts: true
  use-system-hosts: true
  prefer-h3: true
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - https://doh.pub/dns-query
  direct-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver-policy:
    "geosite:cn":
      - 223.5.5.5
      - https://doh.pub/dns-query
    "geosite:geolocation-!cn":
      - https://dns.cloudflare.com/dns-query
      - https://dns.google/dns-query

문제 해결의 실마리. 웹 페이지가 「연결은 되는데 열리지 않을」 때, 로딩이 매우 느릴 때, 잘못된 지역으로 해석될 때는 먼저 DNS를 확인하세요. 로그에서 도메인별로 해석 경로를 살펴, 어떤 해석기 그룹을 거쳤고 어떤 결과를 받았는지 확인한 뒤 해당 필드를 고치면 됩니다.

04프록시 노드 필드: proxies 배열

proxies는 배열이며 원소 하나가 노드 하나입니다. 모든 노드는 name, type, server, port 네 가지 기본 필드를 공유하고, 나머지 필드는 type에 따라 달라집니다. type별 고유 필드명을 잘못 쓰면 커널은 오류 없이 그냥 무시하며, 결과적으로 해당 노드는 연결이 안 되는 것처럼 보입니다.

name은 노드의 신분증과 같습니다. 정책 그룹이 이름으로 참조하며, 이름이 중복되면 나중 것이 앞의 것을 덮어쓰고, 이름을 바꾸면 모든 참조가 끊어집니다. 이름에 공백, 콜론, #가 있으면 인용부호를 붙이세요. server는 도메인이나 IP 모두 가능하며, 도메인을 쓰면 proxy-server-nameserver가 해석을 담당합니다(앞 장 참고).

공통 선택 필드. udp: true는 UDP 포워딩을 허용하며, QUIC, 게임, 음성 통화에 필요합니다. skip-cert-verify: true는 인증서 검증을 건너뛰는 것으로 임시 진단용으로만 써야 합니다. tfo는 TCP Fast Open을 활성화합니다. interface-name은 출력 네트워크 카드를 지정하며 멀티 네트워크 카드 환경에서 유용합니다.

Shadowsocks

  - name: ss-node
    type: ss
    server: ss.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

cipher의 흔한 값: aes-128-gcm, aes-256-gcm, chacha20-ietf-poly1305, 2022-blake3-aes-128-gcm. plugin에는 obfs나 v2ray-plugin을 연결해 트래픽 위장을 할 수 있으며, 파라미터는 plugin-opts에 넣습니다.

VMess

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

alterId는 최신 서버에서는 항상 0입니다. network는 tcp, ws, grpc, h2, http를 지원합니다. ws 전송 시 ws-opts의 path와 headers.Host는 서버 측과 정확히 일치해야 하며, 한 글자만 달라도 400 오류가 발생합니다.

VLESS + Reality

  - name: vless-reality
    type: vless
    server: 192.0.2.10
    port: 443
    uuid: 00000000-0000-0000-0000-000000000000
    network: tcp
    tls: true
    udp: true
    flow: xtls-rprx-vision
    servername: www.microsoft.com
    client-fingerprint: chrome
    reality-opts:
      public-key: "your-public-key"
      short-id: "0123456789abcdef"

flow는 xtls-rprx-vision만 인식합니다. Reality의 public-key와 short-id는 서버 설정에서 가져오며, client-fingerprint는 chrome을 권장하고, servername에는 서버가 위장한 도메인을 넣습니다.

Trojan

  - name: trojan-node
    type: trojan
    server: trojan.example.com
    port: 443
    password: "your-password"
    sni: trojan.example.com
    alpn:
      - h2
      - http/1.1
    skip-cert-verify: false
    udp: true

sni는 서버 인증서의 도메인과 일치해야 하며, alpn은 h2와 http/1.1이 흔합니다. 비밀번호는 곧 인증 정보이므로 노출되면 노드가 노출된 것과 같습니다.

Hysteria2

  - name: hy2-node
    type: hysteria2
    server: hy2.example.com
    port: 443
    password: "your-password"
    obfs: salamander
    obfs-password: "obfs-password"
    sni: hy2.example.com
    skip-cert-verify: false
    up: 50
    down: 200

QUIC 기반으로 UDP를 강제하므로 udp 필드는 쓸 필요가 없습니다. obfs는 현재 salamander만 지원하며, 비밀 값은 obfs-password에 넣습니다. up, down은 Mbps 단위이며, 대역폭을 실제보다 부풀리면 혼잡 제어가 역효과를 낼 수 있으니 실제 값을 입력하세요. 통신사 QoS 제한이 심할 때는 ports로 포트 호핑을 설정할 수 있습니다.

TUIC

  - name: tuic-node
    type: tuic
    server: tuic.example.com
    port: 443
    uuid: 00000000-0000-0000-0000-000000000000
    password: "your-password"
    alpn:
      - h3
    congestion-controller: bbr
    udp-relay-mode: native
    reduce-rtt: true
    sni: tuic.example.com

5세대 프로토콜입니다. congestion-controller는 bbr, cubic, new_reno 중 선택할 수 있으며, 손실률이 높은 회선에는 bbr이 더 안정적입니다. udp-relay-mode는 기본값이 native이며, reduce-rtt: true는 핸드셰이크 지연을 줄여줍니다.

WireGuard

  - name: wg-node
    type: wireguard
    server: 198.51.100.20
    port: 51820
    ip: 172.16.0.2
    private-key: "your-private-key"
    public-key: "peer-public-key"
    mtu: 1420
    udp: true

ip는 할당된 터널 주소이고, private-key는 내 기기의 개인키, public-key는 상대의 공개키입니다. 서로 바꿔 넣지 않도록 주의하세요. mtu는 보통 1420이며, 일부 서비스는 reserved 3바이트 값을 요구하므로 공식 클라이언트에서 내보낸 값을 그대로 쓰세요.

구독 통합: proxy-providers

구독으로 받은 노드는 proxy-providers로 관리됩니다. 커널이 주기적으로 가져와 health-check로 상태를 점검하며, 정책 그룹은 use로 그룹 전체 노드를 참조합니다. 직접 작성한 노드와 provider 노드는 같은 설정 안에 섞어도 됩니다.

proxy-providers:
  provider-01:
    type: http
    url: "https://example.com/subscribe?token=xxxx"
    path: ./providers/provider-01.yaml
    interval: 86400
    health-check:
      enable: true
      url: http://www.gstatic.com/generate_204
      interval: 300

필드 대조 방법: 노드가 연결되지 않을 때는 type에 맞는 절의 예제를 찾아 필드를 하나씩 대조하세요. 여분의 필드는 무시되고, 빠진 필드는 기본값이 쓰이며, 잘못 쓴 필드는 경고 없이 지나갑니다. 구독 노드의 필드는 서비스 제공자가 내려주는 값에 따르지만, 커널 필드명은 전체적으로 통일되어 있습니다.

05정책 그룹 필드: proxy-groups

정책 그룹은 「트래픽을 누구에게 맡길지」를 결정합니다. 규칙에는 정책 이름만 적히고, 정책 이름 뒤에는 그룹이, 그룹 안에는 노드가 있습니다. 이 3계층 분리 구조 덕분에 노드를 바꿔도 규칙은 그대로이고, 규칙을 바꿔도 노드는 그대로입니다.

5가지 유형이 있으며, 동작 방식이 각각 다릅니다.

• select: 수동 선택 방식으로, 다른 그룹을 그 아래 걸어두는 최상위 진입 그룹으로 적합합니다.
• url-test: 그룹 내 노드의 지연을 주기적으로 측정해 가장 낮은 값을 선택합니다. tolerance를 50(밀리초)으로 설정하면 지연 변동으로 노드가 계속 바뀌는 현상을 방지할 수 있습니다.
• fallback: proxies 순서대로 첫 번째로 헬스 체크를 통과한 노드를 사용하며, 주 노드가 복구되면 자동으로 돌아갑니다.
• load-balance: strategy 세 가지 중 선택 — consistent-hashing은 같은 도메인이 같은 노드로 고정돼 세션이 가장 안정적이고, round-robin은 순차 분배, sticky-sessions은 같은 세션이 같은 노드를 씁니다.
• relay: 트래픽이 첫 번째 노드로 들어가 마지막 노드로 나가는 구조로, 경로상의 모든 홉이 정상이어야 하며 하나라도 끊기면 전체 연결이 끊깁니다.

공통 필드. proxies는 노드 이름 목록, use는 proxy-providers 이름 목록이며 둘을 함께 써도 됩니다. filter는 정규식으로 노드 이름을 걸러내고(예: 홍콩|HK), exclude-filter는 반대로 제외하며, exclude-type은 프로토콜 유형으로 제외합니다. icon은 GUI 아이콘 표시용, hidden: true는 GUI에서 해당 그룹을 숨기며, disable-udp: true는 해당 그룹의 UDP 포워딩을 금지합니다.

측정 관련 필드. url은 기본값이 http://www.gstatic.com/generate_204이며 204를 반환하면 사용 가능으로 판정합니다. interval은 초 단위로, 너무 짧으면 전력을 낭비하고 너무 길면 반응이 느려지므로 300이 흔한 절충값입니다. timeout은 단일 측정의 타임아웃이고, lazy: true(기본값)는 아무도 쓰지 않는 그룹은 측정하지 않는다는 뜻입니다. max-failed-times는 연속 실패 횟수로 노드 불가용 여부를 판정하며, expected-status는 기대하는 HTTP 상태 코드를 지정합니다.

중첩. 그룹의 proxies에는 다른 그룹 이름도 넣을 수 있으며, 「기본 프록시 → 자동 선택 → 각 노드」 같은 3계층 구조가 이렇게 만들어집니다. rules에서는 최상위 그룹 이름만 참조하면 됩니다. 구독으로 받은 설정에는 보통 여러 계층의 그룹이 이미 구성돼 있으니, 노드를 직접 추가할 때는 최상위 그룹에 넣으면 전체 경로에 반영됩니다.

proxy-groups:
  - name: 기본 프록시
    type: select
    proxies:
      - 자동 선택
      - 장애 조치
      - DIRECT
    use:
      - provider-01

  - name: 자동 선택
    type: url-test
    use:
      - provider-01
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true

  - name: 장애 조치
    type: fallback
    proxies:
      - 홍콩 노드
      - 일본 노드
    url: http://www.gstatic.com/generate_204
    interval: 120

  - name: 로드 밸런싱
    type: load-balance
    use:
      - provider-01
    strategy: consistent-hashing
    url: http://www.gstatic.com/generate_204
    interval: 300

  - name: 중계 체인
    type: relay
    proxies:
      - 입구 노드
      - 출구 노드

세 가지 자동 그룹의 선택 기준—측정 기반 최적화, 장애 조치, 로드 밸런싱 각각 어떤 상황에 적합한지—는 블로그 《Clash 정책 그룹 유형 고르는 법》에서 확인하세요. 그룹 설계 원칙은 단 하나, 적고 정밀하게입니다. 그룹이 늘어날수록 관리 비용도 늘어나며, 그룹 이름은 규칙에서 참조되므로 이름을 바꿀 때는 규칙도 함께 수정해야 합니다.

06규칙 문법: 위에서 아래로, 첫 매칭 우선

규칙은 트래픽 분류의 핵심이며, 매칭 모델은 한 문장으로 요약됩니다. 위에서 아래로, 첫 매칭에서 멈춘다. 순서가 곧 우선순위이며, MATCH는 무조건 매칭되므로 반드시 마지막에 두어야 합니다. 그 뒤에 오는 규칙은 절대 실행되지 않습니다.

규칙 한 줄은 3단 구조입니다: 유형,파라미터,정책. 일부 유형은 네 번째 항목 no-resolve를 추가할 수 있습니다. 정책은 정책 그룹 이름이거나 내장 정책일 수 있습니다: DIRECT는 직결, REJECT는 거부 후 오류 반환, REJECT-DROP은 조용히 드롭, PASS는 현재 분기를 건너뛰고 계속 매칭합니다(주로 SUB-RULES와 함께 사용).

도메인 기반과 IP 기반은 갈림길입니다. 도메인 규칙(DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD, GEOSITE)은 연결에 포함된 도메인을 바로 비교하므로 해석이 필요 없습니다. IP 기반 규칙(IP-CIDR, GEOIP, IP-ASN)은 목적지 IP가 필요합니다. 도메인 연결이 IP 규칙에 도달하면 커널은 판단을 위해 먼저 DNS 해석을 강제로 수행해야 합니다. 네 번째 항목 no-resolve는 이 해석을 금지합니다. 도메인 연결은 해당 규칙을 그냥 건너뛰고, 순수 IP 연결만 매칭에 참여합니다. 해석 결과에 따라 명확히 분류하고 싶은 경우가 아니라면, 모든 IP 규칙에는 no-resolve를 붙여야 합니다.

GEO 데이터. GEOSITE와 GEOIP는 geosite.dat과 geoip.dat(또는 mmdb) 데이터 파일에 의존합니다. geodata-mode: true로 dat 형식으로 전환할 수 있습니다. 파일은 커널 업데이트와 함께 갱신되며, 파일이 없으면 해당 규칙이 조용히 매칭되지 않아 분류가 작동하지 않는 것처럼 보입니다.

논리 규칙

mihomo는 AND, OR, NOT으로 서브 규칙을 조합할 수 있으며, 서브 규칙은 이중 괄호로 감쌉니다.

rules:
  - AND,((DOMAIN-SUFFIX,example.com),(PROCESS-NAME,chrome.exe)),기본 프록시
  - OR,((DOMAIN-KEYWORD,blog),(DOMAIN-SUFFIX,notes.io)),기본 프록시
  - NOT,((GEOSITE,cn)),기본 프록시

규칙 세트: rule-providers

양이 많고 자주 갱신되는 규칙은 rule-providers 외부 규칙 세트로 맡기며, rules에서는 RULE-SET,이름,정책으로 참조합니다. behavior는 세 가지 중 하나입니다: domain(도메인 서픽스), ipcidr(IP 대역), classical(전통적인 3단 구조).

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

rules:
  - RULE-SET,ad-list,REJECT
  - MATCH,기본 프록시

프로세스 매칭. PROCESS-NAME과 PROCESS-PATH는 find-process-mode에 의존합니다. Windows에서는 프로세스명에 .exe가 붙고, macOS와 Linux에서는 실행 파일명을 씁니다.

정렬 원칙:

• 구체적인 것을 앞에, 넓은 것을 뒤에 두세요: DOMAIN이 DOMAIN-SUFFIX보다 먼저, 서픽스가 GEOSITE보다 먼저 옵니다.
• LAN과 내부 네트워크 대역은 맨 위에 두고 직결시키며, 프록시로 보내지 않습니다.
• 중국 본토 직결 마무리는 GEOSITE,cn과 GEOIP,CN을 쓰고, 도메인을 하나씩 나열하지 마세요.
• MATCH는 항상 마지막에 두고 메인 프록시 그룹이나 DIRECT를 가리키게 하세요.

rules:
  # LAN 및 내부 네트워크 직결
  - DOMAIN-SUFFIX,local,DIRECT
  - 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
  # 프로세스와 앱
  - PROCESS-NAME,steam.exe,게임 가속
  # 도메인 규칙, 구체적인 것부터
  - DOMAIN,api.example.com,기본 프록시
  - DOMAIN-KEYWORD,telegram,기본 프록시
  # 카테고리 데이터베이스로 마무리
  - GEOSITE,category-games@cn,DIRECT
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT,no-resolve
  # 기본값
  - MATCH,기본 프록시

07오버라이드와 병합: 구독 갱신에도 변경 사항 유지

구독 파일을 직접 고치면 곤란한 문제가 하나 있습니다. 구독이 갱신되면 변경 사항이 전부 사라진다는 것이죠. Clash Verge Rev는 이를 위해 3계층 수정 체계를 제공하며, 「무엇을 바꾸고 유지할지」에 따라 역할이 나뉩니다.

1계층, 파일 편집. 설정 페이지의 구독 카드를 우클릭해 「파일 편집」을 선택하면 YAML 원문을 바로 고칠 수 있고 저장하면 즉시 적용되지만, 다음 구독 갱신 때 덮어써집니다. 임시 디버깅과 아이디어 검증에만 쓰고, 검증이 끝난 변경은 아래 두 계층으로 옮겨야 합니다.

2계층, 구독 단위 편집. 우클릭 메뉴의 「규칙 편집」, 「프록시 편집」, 「프록시 그룹 편집」으로 해당 구독의 규칙, 노드, 정책 그룹에 앞/뒤로 항목을 추가할 수 있습니다. 현재 구독에 연결되어 있어 갱신에도 사라지지 않으며, 가장 자주 쓰는 계층입니다. 내부망 직결 규칙 추가, 자체 구축 노드 추가 등이 모두 여기서 이루어집니다.

3계층, 전역 확장 설정. 설정 페이지 우측 상단 진입점으로, 두 가지 형태가 있습니다. Merge는 YAML로 병합 의도를 선언하고, Script는 JavaScript로 전체 설정 객체를 자유롭게 다시 작성합니다. 모든 설정에 적용되며 구독을 바꿔도 사라지지 않아, 구독과 무관한 개인 기본 설정을 담기에 적합합니다.

Merge: 선언형 병합

6개의 전용 키가 배열 병합 방향을 제어합니다. prepend는 앞, append는 뒤에 추가되며, 규칙을 앞에 추가하면 구독에 원래 있던 규칙보다 먼저 매칭됩니다. 그 외 최상위 키는 원래 값을 그대로 덮어씁니다. mixed-port, mode 같은 스칼라 값은 쓴 그대로 적용되며, dns 같은 중첩 구조는 통째로 교체되므로 오버라이드할 때는 해당 섹션 전체를 다 써야 하며 절반만 쓰면 안 됩니다.

prepend-rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
append-rules:
  - DOMAIN-KEYWORD,download,다운로드 그룹
prepend-proxies:
  - name: 자체 구축 백업
    type: ss
    server: 203.0.113.10
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
append-proxy-groups:
  - name: 다운로드 그룹
    type: select
    proxies:
      - 자체 구축 백업
      - DIRECT
mixed-port: 7897

Script: 프로그래밍 방식 재작성

조건 로직이 필요할 때는 스크립트를 씁니다. 진입점은 항상 main(config)이며, 파라미터는 병합된 전체 설정이고, 반환값이 커널에 전달되는 최종 설정입니다.

function main(config) {
  config["mixed-port"] = 7897;
  const extra = {
    name: "자체 구축 백업",
    type: "ss",
    server: "203.0.113.10",
    port: 8388,
    cipher: "aes-256-gcm",
    password: "your-password"
  };
  config.proxies = config.proxies || [];
  config.proxies.push(extra);
  (config["proxy-groups"] || []).forEach(function (group) {
    if (Array.isArray(group.proxies)) {
      group.proxies.push("자체 구축 백업");
    }
  });
  return config;
}

적용 순서는 고정되어 있습니다: 구독 원문 → 구독 단위 편집(규칙/프록시/프록시 그룹) → 전역 Merge → 전역 Script → 커널. 문제를 진단할 때는 이 순서를 거꾸로 따라가세요. 먼저 런타임에 최종 적용된 설정이 어떤 모습인지 확인하고, 그다음 어느 계층에서 문제가 생겼는지 단계별로 찾으면 됩니다.

자주 쓰는 오버라이드 시나리오:

• 내부망 도메인 직결: prepend-rules에 DOMAIN-SUFFIX 규칙을 추가하면 앞에 삽입되어 가장 먼저 매칭됩니다.
• 자체 구축 노드를 모든 그룹에 주입: Script로 proxy-groups를 순회하며 일괄 추가합니다.
• 포트 통일: Merge에 mixed-port 한 줄을 씁니다.
• fake-ip-filter에 내부망 도메인 추가: dns 섹션 전체를 오버라이드하며, 구독의 filter 목록을 전부 복사한 뒤 추가합니다.

다른 클라이언트와 직접 실행. Clash Plus, FlClash도 「구독 + 로컬 수정」 체계를 제공하며 방식은 같고 진입점만 다릅니다. 커널을 직접 실행할 때는 오버라이드 계층이 없어 원본 파일을 직접 관리해야 하므로, Git으로 이력을 관리하는 것을 권장합니다. 여러 기기에서 같은 설정을 유지하는 방법 비교는 블로그 《Clash 설정 멀티 디바이스 동기화 3가지 방법》에서 확인하세요.

08검증과 문제 해결: 오류부터 로그까지

활성화에 실패하면 먼저 오류 메시지를 읽으세요. Clash Verge Rev는 설정을 활성화할 때 커널이 전체 파싱을 수행하며, 오류 메시지에 줄 번호와 원인이 함께 표시됩니다. 줄 번호를 따라 파일로 돌아가면 대부분의 문제는 이 단계에서 찾아집니다. 오류가 잘려 보인다면 로그 페이지에서 전체 출력을 확인하세요.

YAML에서 자주 발생하는 오류를 빈도순으로 정리했습니다.

• 탭 들여쓰기: 에디터 설정에서 탭을 공백으로 바꾸고, 파일 전체를 공백 2개로 통일하세요.
• 콜론 뒤 공백 누락: port:7890은 잘못된 표기입니다.
• 비밀번호에 #가 있는데 인용부호를 안 붙임: # 뒤의 내용이 주석으로 처리되어 비밀번호가 잘립니다.
• 목록 들여쓰기 오류: -와 부모 키의 소속 관계가 흐트러져 노드가 다른 키 아래로 들어가 버립니다.
• 노드 이름 중복: 나중 것이 앞의 것을 덮어써서 정책 그룹에서 참조되는 노드가 하나만 남습니다.
• 존재하지 않는 정책 이름을 규칙이 참조: 활성화 즉시 proxy not found 오류가 뜨므로 그룹 이름 오타를 확인하세요.

로그는 두 번째 현장입니다. log-level을 잠시 debug로 올리면 커널 로그 페이지에서 각 연결이 어떤 규칙에 매칭됐고 어떤 아웃바운드를 탔는지 볼 수 있습니다. 화면 각 영역의 기능은 블로그 《Clash Verge Rev 화면 기능 한눈에 보기》에서 확인하세요. 확인이 끝나면 info로 되돌리세요.

「고쳤는데 적용이 안 될」 때는 순서대로 확인하세요.

1. 파일은 고쳤지만 설정 페이지에서 다시 활성화하지 않아 커널이 여전히 예전 설정으로 돌아가고 있는 경우.
2. 구독 원문을 고쳤지만 오버라이드 계층이 다시 원래대로 되돌려 놓은 경우 — 런타임 최종 설정을 확인하세요.
3. 설정은 맞지만 GUI가 예전 커널 프로세스에 연결돼 있는 경우, 커널을 재시작하거나 다시 연결하세요.
4. 시스템 프록시나 TUN이 켜져 있지 않아 트래픽이 애초에 커널로 들어가지 않는 경우, 무엇을 고쳐도 소용없습니다.

포트와 LAN. bind: address already in use 오류는 포트가 점유됐다는 뜻입니다. mixed-port를 바꾸거나 점유 중인 프로세스를 종료하세요. allow-lan을 켰는데 스마트폰이 연결되지 않는다면, 먼저 PC 방화벽이 해당 포트를 허용하는지 확인하고, 두 기기가 같은 네트워크 대역에 있는지, PC의 내부 IP를 정확히 입력했는지 확인하세요.

fake-ip 관련 이상. 은행, 공공기관, 일부 안티치트가 있는 게임 등 특정 앱은 가상 IP에 민감합니다. 해당 도메인을 fake-ip-filter에 추가하고 direct-nameserver를 설정하세요. 필요하면 규칙 전체를 직결로 지정하세요. 추가한 뒤에는 설정을 다시 활성화해야 적용됩니다.

TLS와 시간. 인증서 관련 오류는 먼저 시스템 시간을 맞추세요. 몇 분만 어긋나도 핸드셰이크가 반드시 실패합니다. skip-cert-verify는 임시 진단 목적으로만 쓰고, 연결이 확인되면 false로 되돌리세요.

DNS 유출과 오염. 유출이 의심될 때는 순서대로 확인하세요: nameserver가 모두 신뢰할 수 있는 경로를 거치는지, proxy-server-nameserver가 설정되어 있는지, respect-rules가 기대대로 동작하는지, nameserver-policy의 geosite 키에 있는 카테고리명이 정확한지—카테고리명을 잘못 쓰면 오류 없이 조용히 무효화됩니다.

마무리. 여전히 해결되지 않는다면 자주 묻는 질문 페이지의 분류 목록을 한번 훑어보세요. 클라이언트 다운로드와 커널 설명은 다운로드 페이지에, 선택 비교는 클라이언트 비교 페이지에 있습니다.