Clash 고급 설정 매뉴얼

시작하기 전에: 매뉴얼의 위치와 설정 기초

먼저 이 페이지와 튜토리얼 페이지의 역할 분담부터 설명합니다. 구독 설정 입문은 메인 튜토리얼입니다: 구독 가져오기, 모드 선택, 연결 시작, 적용 확인까지 따라 하면 클라이언트를 바로 쓸 수 있습니다. 이 페이지는 그 흐름을 반복하지 않고, 고급 주제를 아홉 장으로 나누어 필요한 부분만 찾아볼 수 있게 구성했으니 북마크에 두고 매뉴얼처럼 활용하기 좋습니다. 아직 첫 연결을 해보지 않았다면 먼저 튜토리얼 페이지를 한 번 따라 하거나, 블로그 글 「Clash 첫 연결 튜토리얼: 노드 선택, 지연 시간 테스트와 프록시 적용 확인」을 참고한 뒤 돌아와 주제별로 살펴보세요.

이 페이지의 설정 대상은 mihomo 코어(구 Clash Meta)입니다. 클라이언트 다운로드 페이지에 나열된 유지 관리 중인 클라이언트——Clash Plus, Clash Verge Rev, FlClash, Clash Meta for Android 등——는 모두 이 코어를 기반으로 하며 설정 문법이 동일합니다. 이 페이지의 모든 YAML 조각은 mihomo 설정입니다. 데스크톱과 모바일의 GUI 클라이언트는 보통 설정 편집이나 재정의 메뉴를 제공하고, 코어를 직접 실행하는 사용자는 설정 디렉터리 아래의 config.yaml을 직접 편집합니다.

손대기 전에 먼저 "현재 적용 중인 설정 파일"을 찾아야 합니다. Clash Verge Rev는 「구독」 페이지에서 해당 설정을 우클릭하면 파일을 편집하거나 전역 확장을 작성할 수 있고, Clash Plus는 설정 관리에서 현재 구독을 열고, FlClash는 설정 상세에서 재정의 구간을 편집합니다. 코어를 직접 쓰는 경우 기본으로 설정 디렉터리의 config.yaml을 읽습니다. 여러 구독을 함께 쓸 때 잘못된 파일을 고치는 것이 "수정했는데 적용이 안 된다"는 문제의 가장 큰 원인입니다.

YAML 문법에는 네 가지 원칙이 있으며 이후 모든 예제도 이를 따릅니다. 들여쓰기는 Tab 없이 공백만 사용하고 두 칸으로 통일합니다. 키 이름 뒤의 콜론 다음에는 공백 하나를 두고 값을 씁니다. 값에 콜론, #, 와일드카드가 포함되면 전체를 영문 따옴표로 감쌉니다. 같은 레벨의 키는 엄격하게 정렬합니다. 9장에 흔한 문법 오류 대조표를 실었습니다.

# config.yaml 최소 골격(mihomo)
mixed-port: 7890        # HTTP와 SOCKS 혼합 포트
allow-lan: false        # LAN 기기의 접속 허용 여부
mode: rule              # rule 규칙 / global 전역 / direct 직접 연결
log-level: info
dns: {}                 # 4장에서 설명
proxies: []             # 노드, 보통 구독 또는 proxy-providers가 제공
proxy-groups: []        # 2장에서 설명
rules: []               # 3장에서 설명

프록시 그룹 유형과 실전 활용

프록시 그룹은 트래픽 분배의 중추입니다. rules의 각 규칙 끝에는 구체적인 노드가 아니라 프록시 그룹 이름을 씁니다. 트래픽이 규칙에 매칭되면 그룹에 넘겨지고, 그룹은 자신의 유형 로직에 따라 실제 출구를 골라냅니다. "노드 고르기"를 규칙에서 분리하는 것이 mihomo 설정의 핵심 사상입니다. 규칙은 분류만 담당하고 그룹은 선택만 담당합니다. 실제 노드를 참조하는 것 외에도 그룹에는 두 가지 내장 정책을 넣을 수 있습니다. DIRECT는 직접 연결, REJECT는 바로 거부(광고와 추적 도메인에 자주 사용)를 의미합니다.

다섯 가지 유형 살펴보기

select: 수동 선택. proxies 목록의 첫 번째 항목이 기본 출구이며, 이후 대시보드에서 수동으로 전환합니다. 가장 많이 쓰이며 보통 최상위 출구 그룹으로 사용합니다.

url-test: 자동 속도 측정으로 최적 노드 선택. 그룹 내 노드에 url로 HTTP 요청을 보내 지연 시간을 재고, interval초마다 한 번씩 측정해 지연이 가장 낮은 노드를 고릅니다. tolerance는 밀리초 단위 허용 오차를 지정해 기존 노드와의 차이가 오차 범위 내면 전환하지 않아 노드 출렁임을 피합니다. lazy를 true로 설정하면 그룹에 트래픽이 없을 때 측정하지 않아 요청과 배터리를 아낍니다.

fallback: 장애 조치. proxies 순서대로 첫 번째로 상태 검사를 통과한 노드를 사용합니다. 주력 노드가 고장 나면 예비 노드로 자동 전환되고, 주력 노드가 복구되면 다시 돌아오는 주-예비 구성에 적합합니다.

load-balance: 부하 분산. strategy를 consistent-hashing으로 하면 같은 대상 도메인이 항상 같은 노드로 해시되어 출구 IP가 바뀌면서 사이트 로그인이 풀리는 일이 없습니다. round-robin은 요청마다 순환하므로 멀티스레드 다운로드 같은 시나리오에 적합합니다.

relay: 체인 프록시. proxies가 순서대로 직렬 연결되어 트래픽이 먼저 경유 노드를 거쳐 최종 노드에 도달합니다. "입구를 거쳐 착지"하는 특수한 경로에 쓸 수 있지만, 홉이 하나 늘 때마다 지연과 장애 지점이 배로 늘어 일상적인 분배에는 쓰지 않습니다.

그룹 중첩과 use 참조

proxies에는 노드 이름뿐 아니라 다른 그룹 이름도 쓸 수 있습니다——「노드 선택」 안에 「자동 선택」과 지역별 그룹을 넣어두면 사용자는 한 곳에서 전환하면 됩니다. 또한 그룹은 use 필드로 proxy-providers가 가져온 구독 노드 집합 전체를 참조할 수 있습니다(7장 참조). 구독이 업데이트되면 그룹 내 노드도 자동으로 따라 바뀌므로 그룹 목록을 손으로 고칠 필요가 없습니다.

실전 조합 예시

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies: ["자동 선택", "홍콩", "일본", "미국", "DIRECT"]

  - name: "자동 선택"
    type: url-test
    use: ["airport-a"]        # 7장의 구독 집합 참조
    url: "http://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 80
    lazy: true

  - name: "스트리밍"
    type: select
    proxies: ["홍콩", "일본", "노드 선택"]

  - name: "다운로드"
    type: load-balance
    use: ["airport-a"]
    strategy: consistent-hashing
    url: "http://www.gstatic.com/generate_204"
    interval: 600

규칙 집합의 구독형 관리

규칙은 "어떤 트래픽이 어떤 출구로 갈지"를 결정합니다. 수십, 수백 개의 규칙을 config.yaml에 하드코딩하면 두 가지 문제가 생깁니다. 규칙은 금방 낡아 도메인 목록이 매일 바뀌고, 구독 업데이트가 수동 수정 내용을 통째로 덮어씁니다. 규칙 제공자(rule-providers)는 규칙을 독립된 원격 파일로 분리해 코어가 interval 주기로 새로 가져오게 하고, 메인 설정에는 참조 한 줄만 남깁니다.

필드 항목별 설명

type: http는 URL에서 가져오고, local은 로컬 파일을 읽습니다. behavior: 규칙 집합의 내용 형태——domain은 순수 도메인 접미사 목록, ipcidr은 순수 IP 대역 목록, classical은 클래식 규칙(파일의 각 줄이 DOMAIN-SUFFIX,example.com처럼 유형 접두사가 붙은 완전한 규칙)입니다. format: 파일 형식으로 yaml, text, mrs를 지원합니다(mrs는 바이너리 형식으로 용량이 가장 작아 초대형 목록에 우선 사용합니다). url / path: 원격 주소와 로컬 캐시 경로로, 가져오기에 실패하면 path의 캐시로 버팁니다. interval: 업데이트 간격, 단위는 초입니다.

참조 방법과 순서 원칙

rules에서는 RULE-SET,규칙집합이름,프록시그룹 형식으로 참조합니다. 규칙 매칭은 위에서 아래로 진행되고 처음 매칭되는 규칙에서 멈추므로 순서가 곧 우선순위입니다. 광고 차단 집합을 맨 앞에, LAN과 중국 본토 직접 연결을 중간에, FINAL 최종 규칙을 맨 뒤에 둡니다. RULE-SET 위치를 잘못 쓰면 그 뒤에 있는 규칙은 영원히 적용되지 않습니다. 또한 GEOSITE 규칙(예: GEOSITE,cn)은 코어에 내장된 geosite 데이터베이스에서 제공되며 RULE-SET의 외부 파일과는 별개의 소스로, 함께 섞어 쓸 수 있습니다.

rule-providers:
  reject:
    type: http
    behavior: domain
    format: yaml
    url: "https://example.com/rules/reject.yaml"
    path: ./ruleset/reject.yaml
    interval: 86400
  lan:
    type: http
    behavior: classical
    format: text
    url: "https://example.com/rules/lan.txt"
    path: ./ruleset/lan.txt
    interval: 86400

rules:
  - RULE-SET,reject,REJECT
  - RULE-SET,lan,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

DNS 설정 최적화

DNS는 분배 품질을 가르는 분수령입니다. 대표적인 세 가지 문제: 통신사 DNS가 오염된 결과를 반환하는 경우, 시스템이나 브라우저가 프록시를 우회해 통신사에 직접 질의하면서 DNS 유출이 발생하는 경우, 해외 도메인을 중국 본토 DNS로 해석해 최적이 아닌 CDN 노드를 받는 경우입니다. mihomo의 dns 섹션은 이 세 가지를 직접 처리하기 위한 것입니다.

권장 구성

코어 DNS를 켜고(enable과 listen), enhanced-mode는 fake-ip를 선택합니다(원리는 5장 참조). nameserver에는 중국 본토 공용 DNS를 넣어 기본을 받치고, nameserver-policy로 geosite 기준 중국 본토 도메인을 중국 본토 DNS에 고정합니다. fallback에는 해외 도메인용 DoH를 넣고, fallback-filter로 geoip 필터링을 합니다——해석 결과가 CN 대역 밖에 있을 때만 fallback 결과를 채택하므로 오염된 결과가 들어오지 못합니다.

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "*.msftconnecttest.com"
    - "localhost.ptlogin2.qq.com"
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
  fallback:
    - "https://1.1.1.1/dns-query"
    - "https://dns.google/dns-query"
  fallback-filter:
    geoip: true
    geoip-code: CN
  nameserver-policy:
    "geosite:cn":
      - 223.5.5.5
      - 119.29.29.29

DNS 유출이란

유출은 애플리케이션이 코어를 거치지 않고 통신사 DNS에 직접 질의를 보내는 것을 말하며, 접속 기록이 통신사에 그대로 노출됩니다. 대책은 코어가 모든 DNS 질의를 맡게 하는 것입니다. TUN 모드에서는 dns-hijack으로 기기 전체의 53번 포트를 가로채고(5장), TUN이 아닌 환경에서는 시스템 DNS를 127.0.0.1로 지정하고 listen이 53번 포트를 수신하는지 확인합니다. 유출 증상과 검증 방법은 문제 해결 페이지의 DNS 항목을 참고하세요.

TUN 모드와 Fake-IP

시스템 프록시는 "말을 듣는" 애플리케이션——브라우저와 시스템 프록시 설정을 따르는 소프트웨어——만 관리합니다. 게임, 일부 명령줄 도구, UWP 앱은 시스템 프록시를 타지 않고, UDP와 ICMP 트래픽도 관리할 수 없습니다. TUN 모드는 가상 네트워크 카드를 만들어 기기 전체 트래픽을 가져오는, 적용 범위가 가장 넓은 방식입니다. 일상적인 브라우징은 시스템 프록시로 충분하고, 프록시 설정을 따르지 않는 앱을 만났을 때 TUN을 켜면 됩니다.

주요 필드

stack: 프로토콜 스택 구현으로, 차이는 아래 표를 참조하세요. dns-hijack: DNS 하이재킹으로, any:53은 기기 전체의 53번 포트 질의를 모두 코어 DNS로 가로채며 4장의 설정과 연동됩니다. auto-route: 라우팅 테이블을 자동 구성해 트래픽을 가상 네트워크 카드로 유도합니다. auto-detect-interface: 출구 네트워크 카드를 자동 인식해 트래픽 루프를 방지합니다. mtu: 기본값이면 충분하며, 일부 캠퍼스 네트워크나 전용선 환경에서는 낮춰야 합니다.

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

Fake-IP와 redir-host의 차이

redir-host 모드에서는 앱이 먼저 도메인을 실제로 해석해 IP를 얻은 뒤 연결을 시작하고, 코어는 IP로 도메인을 역조회해 규칙을 매칭합니다——실제 해석을 한 번 더 기다려야 하고 오염된 IP를 받을 수도 있습니다. fake-ip 모드는 DNS 단계에서 198.18.0.1/16 대역의 가짜 주소를 바로 반환하고, 앱이 그 가짜 주소로 접속하면 코어가 가짜 주소로 도메인을 역조회해 규칙을 매칭합니다——실제 해석을 생략하고 규칙 매칭이 도메인을 바로 얻으므로 분배가 더 정확하고 첫 연결이 더 빠릅니다.

대가로 가짜 주소를 받으면 안 되는 서비스가 있습니다. LAN 도메인, NTP 시간 동기화, 일부 중국 본토 직접 연결 서비스입니다. 이들을 fake-ip-filter에 넣으면 코어가 해당 도메인에는 실제 해석 결과를 반환합니다. 4장의 예제에 기본 목록이 포함되어 있으니 필요에 따라 추가하세요.

도메인 스니핑

이상적으로는 코어가 연결에서 대상 도메인을 바로 얻습니다. 하지만 많은 앱이 DNS를 자체 처리합니다——내장 DoH, 하드코딩된 IP——코어 단계에는 IP 주소만 남아 도메인 규칙이 모두 빗나가고 IP 규칙에만 의존하게 되어 분배 정확도가 눈에 띄게 떨어집니다. 도메인 스니핑(sniffer)은 이렇게 잃어버린 도메인을 되찾는 기능입니다.

작동 원리

코어는 연결의 첫 핸드셰이크 패킷을 검사합니다. TLS의 ClientHello에는 SNI 필드가, HTTP 요청에는 Host 헤더가 있으며 둘 다 대상 도메인이 적혀 있습니다. 스니핑은 도메인을 추출해 연결 대상을 교체하고 규칙 매칭을 다시 수행합니다——원래 IP 규칙에만 걸리던 트래픽이 이제 도메인 규칙에 걸리고, 대시보드에 벌거벗은 IP로 표시되던 연결도 눈에 띄게 줄어듭니다.

설정 예제

sniffer:
  enable: true
  sniff:
    TLS:
      ports: [443, 8443]
    HTTP:
      ports: [80, 8080]
      override-destination: true
  skip-domain:
    - "Mijia Cloud"
    - "+.push.apple.com"

override-destination은 스니핑으로 얻은 도메인으로 연결 대상을 덮어쓴다는 뜻으로, fake-ip와 TUN 환경에서는 켜는 것을 권장합니다. 순수 redir-host이면서 규칙이 IP 대역 위주인 설정은 켜지 않아도 됩니다. skip-domain에는 스니핑 시 문제가 생기는 서비스를 넣습니다. Apple 푸시, Mijia처럼 인증서 바인딩이 엄격한 서비스는 스니핑 재작성이 핸드셰이크 실패를 일으키므로 그냥 건너뛰는 것이 가장 간단합니다.

로컬 재정의와 다중 구독 병합

구독은 통째로 배포됩니다. 서비스 업체가 설정을 업데이트하고 클라이언트가 새로 가져오면 수동으로 고친 프록시 그룹과 규칙이 모두 덮어씌워집니다. 올바른 방법은 구독은 구독대로, 로컬 수정은 로컬대로 두고 로드 시점에 병합하는 것입니다. 같은 파일에 섞지 않습니다.

Clash Verge Rev: Merge 재정의

「구독」 페이지에서 전역 확장 설정으로 들어가 Merge(병합) 방식을 선택하고, 고정된 키 이름으로 변경 사항을 기술합니다. prepend-rules와 append-rules는 규칙의 앞이나 뒤에 삽입하고, prepend-proxies와 append-proxies는 노드를 추가하며, prepend-proxy-groups와 append-proxy-groups는 프록시 그룹을 추가합니다. 처리 시점은 구독 로드 이후라서 구독이 어떻게 업데이트되든 재정의가 다시 적용됩니다. JavaScript에 익숙한 사용자는 Script 방식으로 처리 함수를 작성할 수도 있어 자유도가 더 높지만, 대부분의 요구는 Merge 키 이름으로 충분합니다.

# Clash Verge Rev 전역 확장 설정(Merge)
prepend-rules:
  - "DOMAIN-SUFFIX,internal.example.com,DIRECT"
append-proxy-groups:
  - name: "다운로드"
    type: select
    proxies: ["노드 선택", "DIRECT"]

다른 클라이언트의 진입점

Clash Plus는 설정 관리에서 현재 구독에 재정의를 적용하고, FlClash는 설정 상세에서 재정의 구간을 편집합니다. 코어를 직접 쓰는 사용자에게는 재정의 계층이 없으므로 메인 설정은 직접 관리하고 구독은 proxy-providers로 노드만 제공받는 방식을 권장합니다.

다중 구독 병합: proxy-providers

프록시 서비스를 두 개 이상 쓰고 있다면 노드를 메인 설정에 복사할 필요가 없습니다. proxy-providers는 각 구독을 독립된 노드 집합으로 가져와 각각 정기 업데이트와 상태 검사를 수행합니다. 프록시 그룹은 use로 여러 집합을 동시에 참조해 노드 합집합을 그룹에 넣고 한 곳에서 전환합니다.

proxy-providers:
  airport-a:
    type: http
    url: "https://example.com/sub-a.yaml"
    path: ./providers/airport-a.yaml
    interval: 86400
    health-check:
      enable: true
      url: "http://www.gstatic.com/generate_204"
      interval: 300
  airport-b:
    type: http
    url: "https://example.com/sub-b.yaml"
    path: ./providers/airport-b.yaml
    interval: 86400
    health-check:
      enable: true
      url: "http://www.gstatic.com/generate_204"
      interval: 300

proxy-groups:
  - name: "자동 선택"
    type: url-test
    use: ["airport-a", "airport-b"]
    url: "http://www.gstatic.com/generate_204"
    interval: 300

외부 제어 대시보드

mihomo에는 RESTful API가 내장되어 있고, 데스크톱 클라이언트의 인터페이스는 본질적으로 모두 이 API의 프론트엔드입니다. API를 노출하면 브라우저에 제어 대시보드를 붙일 수 있습니다——서버나 라우터에서 코어를 직접 실행할 때는 그래픽 인터페이스가 없으므로 이것이 표준 관리 방식입니다.

API 열기

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

external-controller는 수신 주소이고, secret은 접근 키이며, external-ui는 대시보드 정적 파일 디렉터리를 가리킵니다. 설정 후 http://127.0.0.1:9090/ui에 접속하면 대시보드가 바로 열립니다. 대시보드 파일을 직접 호스팅하고 싶지 않다면 온라인 대시보드를 쓰면 됩니다——metacubexd, zashboard, yacd-meta 모두 활발히 유지 관리되고 있으며, 웹페이지를 열어 API 주소와 키를 입력하면 바로 사용할 수 있습니다.

자주 쓰는 API

# 모든 프록시 그룹과 노드 보기
curl -H "Authorization: Bearer your-password" http://127.0.0.1:9090/proxies

# 「노드 선택」을 지정한 노드로 전환
curl -X PUT -H "Authorization: Bearer your-password" \
  -d '{"name":"홍콩 01"}' \
  http://127.0.0.1:9090/proxies/노드 선택

자주 쓰는 API로 /connections(활성 연결 목록, 개별 종료 가능), /traffic(실시간 속도), /logs(로그 스트림)도 있습니다. 스크립트로 노드를 일괄 전환하거나 상태 점검을 자동화할 때 모두 이 API들을 활용합니다.

설정 검증과 문제 해결

설정을 고친 뒤에는 먼저 검증하고 재시작하세요. GUI 클라이언트의 로그 페이지는 YAML 오류의 줄 번호를 바로 알려줍니다. 코어를 직접 쓰는 경우 명령줄로 전체 로드 테스트를 합니다:

mihomo -t -d /etc/mihomo

-t는 실행하지 않고 테스트만 한다는 뜻이고, -d는 설정 디렉터리를 지정합니다. 문법 오류, 존재하지 않는 프록시 그룹 참조, 규칙 집합 경로 없음 같은 문제가 모두 이 단계에서 드러나므로 문제를 안고 배포되는 일이 없습니다.

YAML 빈발 오류 대조표

점검 순서

"수정했는데 적용이 안 된다"는 네 단계로 점검합니다. 첫째, 편집한 파일이 현재 적용 중인 설정인지 확인합니다. 여러 구독을 함께 쓸 때 가장 많이 겪는 함정입니다. 둘째, 구독 업데이트 후 재정의가 그대로인지 확인합니다. 셋째, 런타임 설정을 보고 병합 결과가 기대와 맞는지 확인합니다. 넷째, 규칙 집합과 노드 캐시를 지우고 코어를 재시작합니다. 규칙이 매칭되지 않을 때는 대시보드나 로그에서 해당 연결이 실제로 매칭된 규칙 체인을 확인하세요. 대부분 순서 문제입니다——더 구체적인 오류 문답은 문제 해결 페이지에 모여 있고, Windows 플랫폼의 설치 함정은 블로그 글 「Clash Windows 버전 설치·설정 전 과정과 빈번한 문제 피하기」를 참고하세요.

문제가 클라이언트나 코어 자체에 있다면 먼저 최신 버전을 쓰고 있는지 확인하세요. 클라이언트 다운로드 페이지에는 다섯 플랫폼의 클라이언트와 코어 패키지가 정리되어 있으며, 전 플랫폼에서 Clash Plus를 가장 먼저 추천합니다. 구독 차원의 업데이트 실패 점검은 블로그 글 「Clash 구독 업데이트 실패의 흔한 원인과 자동 업데이트 설정 방법」을 참고하세요.