YAML 구조 개요
설정 파일은 어디에 있나
GUI 클라이언트는 보통 파일을 직접 다루게 하지 않습니다. Clash Verge Rev는 「구독 / 설정」 페이지에서 여러 설정을 관리하고, Clash Plus는 앱 내에서 구독과 로컬 설정을 함께 관리하며, 파일은 각 앱의 데이터 디렉터리에 저장되고 「설정 디렉터리 열기」 같은 메뉴가 제공됩니다. 반면 mihomo 코어(그리고 Clash for Windows 같은 구버전 클라이언트)는 YAML 파일을 직접 읽으며, 기본 파일명은 config.yaml이고 실행 시 -d 옵션으로 해당 파일이 위치한 디렉터리를 지정합니다. 어떤 방식을 쓰든 최종적으로 적용되는 것은 동일한 구조의 YAML입니다: 최상위에는 스칼라 필드(포트, 모드, 로그 레벨)가 먼저 오고, 이어서 dns, proxies, proxy-groups, rules 네 개의 기능 섹션, 그리고 proxy-providers, rule-providers 두 개의 외부 리소스 섹션이 있습니다. 이 골격을 이해하면 Clash 계열 클라이언트 전체에 공통되는 설정 로직을 이해한 것입니다.
YAML 문법 4가지 규칙
YAML의 문법 제약은 많지 않지만, 하나하나가 파일이 파싱되는지 여부를 직접 좌우합니다:
- 들여쓰기는 반드시 공백만 사용하고 Tab은 쓰지 않습니다. 초보자가 가장 흔히 겪는 오류 원인이므로, 에디터에서 Tab을 공백 2칸으로 자동 변환하도록 설정해두면 편합니다.
- 키와 값 사이는 「콜론 + 공백 한 칸」입니다.
port:7890이나port : 7890처럼 쓰면 파싱이 실패하거나 예상치 못한 결과가 나옵니다. - 리스트 항목은 「- 」로 시작하며 하이픈 뒤에도 공백 한 칸을 둡니다. 리스트는 부모 키와 같은 열에 써도 되고 한 단계 더 들여써도 되며, 두 방식은 동등하므로 파일 전체에서 하나로 통일하면 됩니다.
- 문자열에 콜론, #, 중괄호, 대괄호, 쉼표 등 특수 문자가 들어갈 경우 영문 큰따옴표로 전체를 감싸야 합니다. #뒤의 내용은 주석이며 파싱 대상이 아닙니다.
그 외에 YAML은 앵커와 참조(& 로 앵커 정의, * 로 참조, << 로 병합)를 지원해, 여러 노드가 같은 설정을 공유할 때 중복 줄을 줄일 수 있습니다. 구체적인 예시는 「대리 노드 필드」 절에서 확인하세요.
최상위 필드 한눈에 보기
완전한 설정 파일의 최상위는 대략 세 그룹으로 나뉩니다: 네트워크 리스닝(port, socks-port, mixed-port 등), 동작 설정(mode, log-level, ipv6, external-controller 등), 기능 섹션(dns, proxies, proxy-groups, rules). 아래 표로 전체 개요를 먼저 보고, 이후 절에서 하나씩 자세히 설명합니다.
| 필드 | 타입 | 역할 |
|---|---|---|
port | 정수 | HTTP 프록시 리스닝 포트 |
socks-port | 정수 | SOCKS5 프록시 리스닝 포트 |
mixed-port | 정수 | HTTP와 SOCKS 혼합 포트 |
allow-lan | 불리언 | LAN 기기 접속 허용 여부 |
mode | 열거형 | rule / global / direct 3가지 동작 모드 |
log-level | 열거형 | silent / error / warning / info / debug |
external-controller | 문자열 | RESTful 관리 API 리스닝 주소 |
dns | 섹션 | 내장 DNS 서버 및 해석 동작 |
proxies | 리스트 | 대리 노드 목록 |
proxy-groups | 리스트 | 정책 그룹 목록 |
rules | 리스트 | 트래픽 분리 규칙, 순서대로 매칭 |
rule-providers | 매핑 | 외부 규칙셋 정의 |
# config.yaml 골격: 스칼라 먼저, 섹션은 나중에
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
dns:
enable: true
# ...자세한 내용은 「DNS 필드」 절 참고
proxies:
- name: "node-a"
# ...자세한 내용은 「대리 노드 필드」 절 참고
proxy-groups:
- name: "PROXY"
type: select
proxies: ["node-a", DIRECT]
rules:
- DOMAIN-SUFFIX,local,DIRECT
- MATCH,PROXY
실무 팁
YAML 파싱이 실패하면 코어는 실행을 거부하며, GUI 클라이언트에서는 보통 「설정 로드 실패」로 나타나거나 프록시 목록이 비어있게 됩니다. 오류 메시지의 줄 번호는 대체로 신뢰할 수 있으니, 해당 줄 주변의 들여쓰기, 따옴표, 콜론을 먼저 확인하세요.
공통 필드: 포트, 모드, 전역 동작
포트 필드
Clash는 4가지 인바운드 리스닝을 제공합니다. port는 전통적인 HTTP 프록시 포트, socks-port는 UDP 포워딩을 지원하는 SOCKS5 포트, mixed-port는 두 프로토콜을 하나의 포트로 합쳐 코어가 요청 특성에 따라 자동 인식하며 현재 대부분의 GUI 클라이언트는 기본적으로 이 혼합 포트만 엽니다. redir-port와 tproxy-port는 Linux 투명 프록시용으로 데스크톱 사용자는 쓸 일이 거의 없습니다. 실행 시 「bind: address already in use」 오류가 뜨면 포트가 이미 사용 중이라는 뜻이니, 포트를 바꾸거나 점유 중인 프로세스를 찾아 종료하세요. 혼합 포트를 활용한 LAN 공유의 실제 사용법은 기술 노트에 별도로 정리되어 있습니다.
| 필드 | 프로토콜 | 일반적인 값 | 설명 |
|---|---|---|---|
port | HTTP | 7890 | 구버전 클라이언트 기본값, 점차 혼합 포트로 대체됨 |
socks-port | SOCKS5 | 7891 | UDP 포워딩 지원, 게임/음성 앱에서 자주 사용 |
mixed-port | HTTP + SOCKS5 | 7890 / 7897 | 현재 주류 기본값, 한 포트로 두 프로토콜 처리 |
redir-port | 투명 프록시(redirect) | 기본값 없음 | Linux 게이트웨이/라우터 환경 |
tproxy-port | 투명 프록시(tproxy) | 기본값 없음 | Linux 게이트웨이 환경, UDP 지원 |
동작 모드
mode는 요청의 출구 방향을 결정하며 값은 3가지입니다: rule은 rules 목록을 순서대로 매칭하는 일상적인 기본값, global은 모든 트래픽을 GLOBAL 정책 그룹(보통 패널에서 선택한 노드와 동일)에 넘겨 「규칙 설정이 잘못됐는지」를 확인할 때 가장 직접적이고, direct는 모두 직결로 보내 프록시 자체가 정상 작동하는지 확인할 때 씁니다. GUI 클라이언트 홈 화면의 모드 전환 버튼이 바로 이 필드를 바꾸는 것입니다.
LAN 및 외부 접속
allow-lan을 켜면 같은 LAN에 있는 스마트폰, 태블릿에서 이 PC의 IP와 포트로 프록시를 지정해 같은 출구를 공유할 수 있습니다. bind-address는 리스닝할 네트워크 인터페이스를 지정하며 기본값 "*"은 모든 인터페이스를 의미하고, allow-lan과 함께 써야 실질적인 의미가 있습니다. external-controller는 코어의 RESTful 관리 API로, GUI 패널은 이를 통해 상태를 조회하고 노드를 전환하고 로그를 가져옵니다. secret은 이 API의 접근 토큰입니다. 이 API의 리스닝 주소를 0.0.0.0으로 바꿔 외부에 노출한다면 반드시 secret을 함께 설정해야 하며, 그렇지 않으면 프록시 제어권을 전체 네트워크에 넘기는 것과 같습니다. external-ui는 정적 패널 디렉터리를 지정해 브라우저에서 직접 관리 화면에 접근할 수 있게 합니다.
보안 주의
allow-lan은 신뢰할 수 있는 네트워크에서만 켜세요. 공용 Wi-Fi에서 프록시 포트를 개방하면 같은 네트워크에 있는 모르는 사람에게 대역폭과 출구를 빌려주는 것과 같습니다. LAN 공유의 전체 설정과 검증 절차는 기술 노트 《Clash 혼합 포트와 LAN 프록시 공유 설정》을 참고하세요.
로그, 지연 측정 및 기타 동작 필드
log-level은 silent부터 debug까지 5단계이며, 문제를 진단할 때만 일시적으로 debug로 올리고 평소에는 info를 유지하세요. ipv6은 AAAA 레코드 처리 여부를 결정하며, IPv6 출구가 없는 네트워크에서는 끄는 것을 권장합니다. unified-delay는 지연 측정에 TCP/TLS 핸드셰이크 시간을 포함시켜 노드 간 수치를 비교 가능하게 만듭니다. tcp-concurrent는 후보 노드에 동시 연결을 시도해 첫 연결을 더 빠르게 합니다. find-process-mode는 로컬 프로세스명을 해석할지 결정하며 PROCESS-NAME 규칙이 여기에 의존합니다. global-client-fingerprint는 TLS 클라이언트 지문 위장(흔히 chrome 값 사용)을 지정하며 uTLS에 의존하는 프로토콜에서 의미가 있습니다. profile 섹션의 store-selected는 패널에서 수동 선택한 노드를 기억해 설정 재로드 후에도 선택이 유지되게 합니다. 그 외 tun 섹션은 가상 네트워크 인터페이스 수준의 트래픽 인수용으로 고급 주제에 속하며 일반 데스크톱 환경에서는 켤 필요가 없습니다.
port: 7890
socks-port: 7891
mixed-port: 7897
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: ""
unified-delay: true
tcp-concurrent: true
find-process-mode: strict
global-client-fingerprint: chrome
profile:
store-selected: true
store-fake-ip: true
DNS 필드: 오염 방지와 누출 방지
DNS가 왜 별도 섹션인가
프록시는 「트래픽이 어떻게 흐를지」만 해결하고, DNS는 「도메인이 무엇으로 해석되는지」를 결정합니다. 시스템 기본 DNS는 통신사의 평문 UDP 53번 포트를 사용해 가로채기에 취약하고, 접속 의도가 로컬 네트워크에 그대로 노출됩니다. 이것이 흔히 말하는 DNS 누출입니다. Clash의 dns 섹션은 코어 내부에 DNS 서버를 내장해 쿼리 요청을 가로채고, 정책에 따라 도메인별로 다른 상위 서버에 전달합니다. fake-ip 모드와 결합하면 「먼저 도메인 기준으로 규칙을 매칭하고, 그 뒤에 프록시 여부를 결정」하는 방식이 가능해져, 「오염된 IP로 먼저 해석되지만 규칙은 도메인으로 작성되는」 모순을 피할 수 있습니다.
기본 필드
enable은 전체 스위치입니다. listen은 내장 DNS의 리스닝 주소로, GUI 클라이언트가 시스템 수준 인수를 하지 않는다면 설정하지 않아도 됩니다. enhanced-mode는 두 가지 값이 있습니다: redir-host는 실제 해석 결과를 반환하며 코어가 도메인-IP 매핑을 기록합니다. fake-ip는 198.18.0.0/16 대역의 가짜 주소를 즉시 반환하고, 연결이 들어올 때 도메인을 역조회해 규칙을 매칭하므로 속도가 빠르고 오염에 영향받지 않아 현재 주류 선택입니다. fake-ip-filter는 fake-ip를 쓰지 않을 도메인을 나열합니다—LAN 기기명, NTP 시간 동기화, 실제 IP가 필요한 일부 서비스 등이 이 목록에 있으면 실제 해석으로 처리됩니다. default-nameserver는 「상위 DNS 서버 자체의 도메인」만 해석하는 용도이므로 순수 IP의 전통 UDP 서버를 지정해야 합니다. 그렇지 않으면 「DoH 도메인을 해석하려면 먼저 DoH에 물어봐야 하는」 순환에 빠집니다.
상위 서버
nameserver는 메인 상위 목록으로, 여러 줄을 동시에 질의해 가장 빠른 결과를 사용할 수 있습니다. fallback은 백업 그룹으로 fallback-filter와 함께 GEOIP를 기준으로 판단합니다: 해석 결과가 해외 IP 대역에 속하면 fallback으로 재조회합니다. mihomo는 nameserver-policy를 더 권장합니다—도메인 집합별로 상위 서버를 직접 지정할 수 있어, 예를 들어 geosite:cn은 중국 본토 DoH로, 나머지는 신뢰할 수 있는 해외 DoH로 보내는 식으로 fallback의 「먼저 조회하고 판단하는」 방식보다 더 확정적입니다. proxy-server-nameserver는 프록시 노드의 도메인 해석만 전담해, 노드 도메인이 오염되어 연결이 안 되는 상황을 막습니다. respect-rules를 켜면 DNS 요청 자체도 규칙에 따라 출구를 선택합니다(프록시를 거쳐 해외 DNS에 질의). 다만 설정 복잡도가 올라갑니다. 그 외 sniffer 스니핑 섹션은 TLS/HTTP 핸드셰이크에서 도메인을 복원해 「앱이 IP로 직접 연결」할 때 규칙 매칭을 보정합니다.
| 형식 | 프로토콜 | 설명 |
|---|---|---|
223.5.5.5 | UDP 53 | 전통적인 평문 쿼리, default-nameserver에만 적합 |
tls://dns.alidns.com | DNS over TLS | 853번 포트 암호화 전송 |
https://doh.pub/dns-query | DNS over HTTPS | HTTPS 경유, 가장 방해받기 어려움 |
quic://dns.example | DNS over QUIC | mihomo 지원, 저지연 |
dhcp://en0 | DHCP로 전달 | 네트워크 인터페이스를 따라 통신사 DNS 획득 |
dns:
enable: true
listen: 0.0.0.0:1053
ipv6: false
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- "*.lan"
- "*.local"
- time.*.com
- ntp.*.com
default-nameserver:
- 223.5.5.5
- 119.29.29.29
nameserver:
- https://doh.pub/dns-query
- https://dns.alidns.com/dns-query
proxy-server-nameserver:
- https://doh.pub/dns-query
nameserver-policy:
"geosite:geolocation-!cn":
- https://dns.cloudflare.com/dns-query
- https://dns.google/dns-query
점검 순서
DNS 누출의 대표적인 증상: 브라우저에 프록시를 걸어놨는데도 누출 테스트 사이트에서 로컬 통신사가 그대로 표시됨. 처리 순서: dns.enable이 켜져 있는지, 시스템 또는 브라우저의 DNS가 코어 리스닝 주소를 가리키는지, nameserver에 통신사 UDP가 남아있지 않은지 순서대로 확인하세요. 더 많은 증상 대조는 FAQ 페이지에서 확인할 수 있습니다.
대리 노드 필드: proxies 목록
공통 필드
proxies는 리스트이며 각 항목이 하나의 노드에 해당합니다. 모든 프로토콜이 공통으로 쓰는 필드는 5개뿐입니다: name(표시 이름, 규칙과 정책 그룹이 이를 참조하므로 파일 전체에서 유일해야 함), type(프로토콜 종류), server, port, udp(UDP 포워딩 여부, 노드가 지원하면 켜기). 나머지 필드는 프로토콜마다 다릅니다. 같은 프로토콜의 노드를 여러 개 수동 관리할 때는 YAML 앵커로 공통 부분을 뽑아내고, 이후 노드에서는 병합 키로 참조해 차이가 나는 필드만 쓰면 됩니다:
proxies:
- &ss-base
name: "ss-a"
type: ss
server: 203.0.113.10
port: 8388
cipher: aes-128-gcm
password: "your-password"
udp: true
- <<: *ss-base
name: "ss-b"
server: 203.0.113.11
port: 8389
프로토콜별 예제
아래 예제는 mihomo에서 자주 쓰는 5가지 프로토콜을 다루며, 주소는 모두 문서용 예약 대역을 사용했으니 실제 서버 정보로 바꿔서 사용하세요:
proxies:
- name: "ss-example"
type: ss
server: 203.0.113.10
port: 8388
cipher: aes-128-gcm
password: "your-password"
udp: true
- name: "vmess-example"
type: vmess
server: 198.51.100.20
port: 443
uuid: 11111111-2222-3333-4444-555555555555
alterId: 0
cipher: auto
tls: true
servername: example.com
network: ws
ws-opts:
path: /ray
headers:
Host: example.com
- name: "trojan-example"
type: trojan
server: 192.0.2.30
port: 443
password: "your-password"
sni: example.com
skip-cert-verify: false
udp: true
- name: "hy2-example"
type: hysteria2
server: 203.0.113.40
port: 443
password: "your-password"
sni: example.com
skip-cert-verify: false
- name: "vless-example"
type: vless
server: 198.51.100.50
port: 443
uuid: 11111111-2222-3333-4444-555555555555
network: tcp
tls: true
udp: true
flow: xtls-rprx-vision
servername: www.microsoft.com
reality-opts:
public-key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
short-id: "0123456789abcdef"
client-fingerprint: chrome
skip-cert-verify는 인증서 체인에 특별한 이유가 확인된 경우에만 임시로 켜야 하며, 장기간 켜두면 TLS의 신원 검증을 포기하는 것과 같습니다. sni / servername은 TLS 핸드셰이크 시 선언되는 도메인을 결정하며, 잘못 입력하면 바로 연결이 안 됩니다.
프로토콜 지원 차이
원조 Clash는 유지보수가 중단되어 새로운 프로토콜은 mihomo 코어에만 추가됩니다. 이것이 본 사이트 다운로드 페이지가 전부 mihomo 계열 클라이언트를 우선 추천하는 이유입니다:
| 프로토콜 | 원조 Clash(유지보수 종료) | mihomo |
|---|---|---|
| Shadowsocks | 지원 | 지원 |
| VMess | 지원 | 지원 |
| Trojan | 지원 | 지원 |
| Snell | 지원 | 지원 |
| Hysteria / Hysteria2 | 미지원 | 지원 |
| TUIC | 미지원 | 지원 |
| VLESS / Reality | 미지원 | 지원 |
| WireGuard | 미지원 | 지원 |
구독 사용자 주의
구독을 가져오면 클라이언트가 자동으로 proxies 목록을 생성하므로 이 섹션을 직접 작성할 일은 거의 없습니다. 구독 파일 내의 노드를 직접 수정하면 다음 구독 업데이트 때 전부 덮어씌워집니다. 자체 노드를 장기간 유지하려면 「오버라이드와 병합」 절의 방법으로 추가하세요.
정책 그룹 필드: proxy-groups
5가지 유형
정책 그룹은 「노드 묶음 + 선택 정책」입니다. select는 수동 선택으로 패널에서 클릭한 대로 전환되며, 거의 모든 설정에 하나의 메인 진입 그룹이 있습니다. url-test는 일정 간격으로 그룹 내 노드의 지연을 측정해 가장 낮은 것을 자동 선택합니다. fallback도 동일하게 측정하지만 「현재 노드가 죽었을 때만 다음으로 전환」하는 의미이며 목록 순서가 곧 우선순위입니다. load-balance는 연결을 정책에 따라 여러 노드에 분산합니다(strategy는 consistent-hashing 또는 round-robin), 여러 회선의 대역폭을 합칠 때 적합합니다. relay는 여러 노드를 체인 형태로 연결해 트래픽이 순서대로 통과하며 최종 출구는 마지막 노드입니다. mihomo는 정책 그룹에 icon 필드를 추가해 패널에 커스텀 아이콘을 표시하는 것도 지원합니다.
| 타입 | 선택 방식 | 주요 용도 |
|---|---|---|
select | 수동 선택 | 메인 진입, 기능별 그룹(예: 광고 차단 스위치) |
url-test | 자동 최저 지연 | 같은 지역 여러 노드 중 최적 선택 |
fallback | 장애 전환 | 메인/백업 라인, 안정성 우선 |
load-balance | 로드 밸런싱 | 여러 회선 대역폭 합산 |
relay | 체인 포워딩 | 진입점과 출구가 분리된 중계 체인 |
속도 측정 파라미터
url은 속도 측정 대상이며 관례적으로 http://www.gstatic.com/generate_204를 사용합니다. 204 응답은 내용이 없어 오버헤드가 가장 적습니다. interval은 측정 간격(초)이며 너무 짧으면 트래픽과 배터리를 소모하므로 300이 흔한 값입니다. tolerance는 전환 임계값(밀리초)으로, 새 노드가 현재 노드보다 이 값 이상 빨라야 전환해 비슷한 두 라인 사이를 계속 오가는 것을 막습니다. lazy가 true면 그룹이 실제로 사용될 때만 측정해 잘 쓰지 않는 백업 그룹이 불필요한 트래픽을 쓰지 않게 합니다. timeout은 1회 측정의 최대 대기 시간입니다.
중첩과 참조
정책 그룹의 proxies 목록에는 다른 정책 그룹의 이름을 다시 쓸 수 있습니다—이것이 중첩입니다: 메인 진입 그룹 PROXY에 「홍콩」, 「일본」, 「미국」 세 지역 그룹을 넣고, 각 지역 그룹은 url-test로 만들어 지역은 수동 선택, 노드는 그룹 내에서 자동 선택하도록 두 계층으로 역할을 나눕니다. use 필드는 proxy-providers의 구독 소스를 참조해 전체 노드를 그룹에 끌어옵니다. filter는 정규식으로 노드 이름을 필터링합니다. 예를 들어 filter: "홍콩|HK"는 이름에 홍콩이 들어간 노드만 남깁니다. DIRECT(직결)와 REJECT(차단)는 두 개의 내장 출구로, 어떤 proxies 목록에도 바로 쓸 수 있어 select 그룹과 결합하면 「광고 차단 스위치」 같은 기능 그룹을 만들 수 있습니다.
proxy-groups:
- name: "PROXY"
type: select
proxies: ["HK-AUTO", "JP-AUTO", "US-AUTO", DIRECT]
- name: "HK-AUTO"
type: url-test
use: ["provider-main"]
filter: "홍콩|HK|Hong Kong"
url: http://www.gstatic.com/generate_204
interval: 300
tolerance: 50
lazy: true
- name: "JP-AUTO"
type: url-test
use: ["provider-main"]
filter: "일본|JP|Japan"
url: http://www.gstatic.com/generate_204
interval: 300
- name: "US-AUTO"
type: fallback
use: ["provider-main"]
filter: "미국|US|United States"
url: http://www.gstatic.com/generate_204
interval: 300
- name: "AD-BLOCK"
type: select
proxies: [REJECT, DIRECT]
relay에 대해
체인 프록시는 어느 한 구간이 끊기면 전체 체인을 쓸 수 없게 되고, 구간을 지날수록 지연이 누적됩니다. 이는 「진입점과 출구를 반드시 분리해야 하는」 특수한 요구를 해결하는 것으로 일상적인 속도 향상 수단이 아니며, 일반적인 상황에서는 앞의 4가지 유형만으로 충분합니다.
규칙 문법: rules는 위에서 아래로
매칭 순서
rules는 순서가 있는 목록입니다: 코어가 위에서 아래로 순서대로 비교하며, 첫 번째로 일치하는 규칙에서 멈추고 이후 규칙은 확인하지 않습니다. 작성 시 지켜야 할 원칙은 「구체적인 것을 앞에, 포괄적인 것을 뒤에, MATCH는 항상 맨 마지막」입니다. 규칙은 두 종류로 나뉩니다: 도메인 계열(DOMAIN / DOMAIN-SUFFIX / DOMAIN-KEYWORD / GEOSITE)은 해석 전에 판단이 가능하고, IP 계열(IP-CIDR / GEOIP)은 해석 결과가 필요합니다. IP 계열 규칙에 no-resolve 파라미터를 추가하면 「요청이 원래 도메인일 때는 이 규칙을 매칭하려고 DNS 해석을 트리거하지 않음」을 의미하며, 순수 도메인 요청은 이 규칙을 건너뛰고 계속 아래로 진행해 불필요한 조회를 크게 줄일 수 있습니다. GEOSITE와 GEOIP는 지리 데이터 파일에 의존하며 GUI 클라이언트가 자동으로 관리하지만, 코어를 단독으로 실행할 때는 데이터 파일이 설정 디렉터리 안에 있거나 자동 업데이트가 켜져 있어야 합니다.
규칙 유형 빠른 참조
| 형식 | 매칭 대상 | 설명 |
|---|---|---|
DOMAIN,example.com,출구 | 단일 도메인 | 정확히 일치, 서브도메인 미포함 |
DOMAIN-SUFFIX,example.com,출구 | 도메인 접미사 | 해당 도메인과 모든 서브도메인 매칭 |
DOMAIN-KEYWORD,google,출구 | 도메인 키워드 | 포함되면 매칭, 신중히 사용 |
GEOSITE,cn,출구 | 도메인 분류 라이브러리 | 커뮤니티가 관리하는 분류 데이터 |
IP-CIDR,192.168.0.0/16,출구 | IPv4 대역 | no-resolve 추가 권장 |
IP-CIDR6,fe80::/10,출구 | IPv6 대역 | 위와 동일 |
GEOIP,CN,출구 | IP 소속 지역 | no-resolve 추가 권장 |
SRC-IP-CIDR,192.168.1.201/32,출구 | 소스 IP | LAN 내 기기별 트래픽 분리 |
DST-PORT,443,출구 | 목적지 포트 | 목적지 포트 기준 트래픽 분리 |
PROCESS-NAME,telegram.exe,출구 | 프로세스명 | find-process-mode에 의존 |
RULE-SET,이름,출구 | 외부 규칙셋 | rule-providers 정의 참조 |
MATCH,출구 | 기본값 | 마지막 규칙이어야 함 |
rule-providers 규칙셋
규칙셋은 수백~수천 개의 규칙을 외부 파일로 뽑아내고, 메인 설정에는 한 줄만 참조하도록 합니다. type이 http면 url로 주기적으로 가져와(interval초) path에 캐시하고, file이면 로컬 파일을 읽습니다. behavior는 3가지입니다: domain(순수 도메인 접미사 집합, 도메인 트리로 로드되어 매칭이 가장 빠름), ipcidr(순수 IP 대역), classical(전통적인 규칙 행, 다양한 유형을 섞어 쓸 수 있음). 규칙셋 파일 자체는 yaml(payload 목록) 형식이거나 한 줄에 한 항목씩인 순수 텍스트일 수 있습니다.
rule-providers:
reject-ads:
type: http
behavior: domain
url: "https://example.org/rules/ads.yaml"
path: ./ruleset/ads.yaml
interval: 86400
local-direct:
type: file
behavior: classical
path: ./ruleset/direct.yaml
rules:
- RULE-SET,reject-ads,AD-BLOCK
- RULE-SET,local-direct,DIRECT
- DOMAIN-SUFFIX,lan,DIRECT
- GEOSITE,private,DIRECT
- GEOSITE,cn,DIRECT
- GEOIP,CN,DIRECT,no-resolve
- GEOSITE,geolocation-!cn,PROXY
- MATCH,PROXY
MATCH는 필수
MATCH로 마무리하지 않은 설정에서는 매칭되지 않은 요청이 기본 동작(코어와 버전에 따라 다름)으로 처리되어 「특정 사이트가 이유 없이 안 열리는」 현상이 나타납니다. 어떤 설정이든 MATCH로 끝맺어야 하며, 출구는 보통 메인 진입 정책 그룹입니다.
오버라이드와 병합: 구독과 커스텀 설정 공존
구독 파일을 직접 수정하면 안 되는 이유
구독의 본질은 「제공자가 내려주는 완전한 설정 파일」로, 클라이언트가 일정 시간마다 다시 가져와 전체를 덮어씁니다. 구독 파일에 추가한 커스텀 규칙이나 수정한 정책 그룹은 다음 업데이트 때 모두 사라집니다. 올바른 방법은 「구독 내용」과 「로컬 커스텀」을 두 계층으로 나누는 것입니다: 구독은 노드를 담당하고, 오버라이드는 여러분의 규칙과 필드를 담당하며, 클라이언트 실행 시 이 둘이 합쳐져 최종 설정이 됩니다. 이렇게 하면 구독이 자유롭게 업데이트돼도 로컬 계층은 그대로 유지됩니다.
클라이언트 오버라이드 메커니즘
Clash Verge Rev를 예로 들면: 구독 목록에서 우클릭해 편집으로 들어가면 모든 구독에 적용되는 전역 확장 설정(Merge)을 관리할 수 있습니다. Merge는 두 종류의 키를 지원합니다: 첫째, prepend- / append- 접두사가 붙은 추가 키로, 해당 목록의 맨 앞이나 맨 뒤에 내용을 삽입합니다. 둘째, 최상위와 같은 이름의 덮어쓰기 키로, 구독의 값을 직접 대체합니다. Clash Plus도 구독 외에 커스텀 설정 입구를 제공하며 방식은 동일합니다. 아직 Clash for Windows를 쓰고 있다면 주의하세요: 이 프로젝트는 유지보수가 중단되었고 Mixin 메커니즘도 오랫동안 업데이트되지 않았으니, 《Clash Verge Rev와 Clash Plus로 이전하는 방법》을 참고해 활발히 유지보수되는 클라이언트로 옮기는 것을 권장합니다.
# 전역 확장 설정(Merge) 예시
prepend-rules:
- DOMAIN-SUFFIX,internal.example.com,DIRECT
append-proxy-groups:
- name: "MY-SELECT"
type: select
use: ["provider-main"]
mixed-port: 7897
세 가지 방식 비교
| 방식 | 특징 | 적합한 상황 |
|---|---|---|
| 클라이언트 오버라이드(Merge / 커스텀 설정) | 외부 의존 없음, 클라이언트와 함께 동작 | 일상적인 규칙 추가, 포트 변경, 정책 그룹 추가에 추천 |
| 로컬 템플릿 + 구독 변환 | 한 번에 완전한 설정 생성 | 여러 구독 통합, 세밀한 템플릿 관리 |
| 자체 구축 subconverter | 완전한 자체 제어, 여러 사람과 공유 가능 | 자체 서버가 있는 고급 사용자 |
추천 방식
일반 사용자는 클라이언트 기본 오버라이드만으로 대부분의 커스텀 요구(규칙 추가, 포트 변경, 정책 그룹 추가)를 처리할 수 있습니다. 구독 형식 자체의 차이와 변환 방법은 기술 노트 《Clash 구독 링크는 어떤 형식인가》를 참고하고, 클라이언트 본체는 다운로드 페이지에서 받으세요. 전 플랫폼에서 Clash Plus를 우선 추천합니다.
검증, 디버깅과 흔한 오류
코어로 정적 검사하기
mihomo에는 설정 검사 기능이 내장되어 있습니다: config.yaml을 한 디렉터리에 두고 ./mihomo -t -d ./디렉터리를 실행하면 성공 시 검사 성공 메시지를 출력하고, 실패 시 필드명과 줄 번호를 알려줍니다. 변경 폭이 클 때는 먼저 명령줄에서 -t를 한 번 돌려보고 GUI로 로드하는 것이, 클라이언트를 반복 재시작하며 시행착오를 겪는 것보다 훨씬 빠릅니다. Windows 사용자는 코어 실행 파일과 설정을 같은 디렉터리에 두고 PowerShell에서 동일한 명령을 실행하면 됩니다.
핫 리로드와 로그
external-controller가 켜져 있으면 코어를 재시작하지 않고 설정을 바로 재로드할 수 있습니다:
curl -X PUT "http://127.0.0.1:9090/configs?force=true" \
-H "Content-Type: application/json" \
-d '{"path": "/절대경로/config.yaml"}'
force=true는 기존 연결을 강제로 끊고 재연결하며, 일상적인 재로드에서는 넣지 않아도 됩니다. 로그 측면에서 log-level을 debug로 올리면 각 연결의 매칭 과정(도메인, 매칭된 규칙, 출구 노드)이 모두 출력되어 「이 트래픽이 왜 프록시를 안 타는지」를 찾는 첫 번째 수단이 됩니다. GUI 클라이언트의 로그 / 연결 패널은 본질적으로 이 데이터를 시각화한 것입니다.
자주 발생하는 오류 대조표
| 증상 / 오류 | 흔한 원인 | 처리 방법 |
|---|---|---|
| yaml: line N: did not find expected key | 들여쓰기가 일정하지 않거나 Tab이 섞임 | 공백 2칸으로 통일 |
| cannot unmarshal | 필드 타입 오류(예: 포트를 문자열로 씀) | 이 페이지 표를 참고해 타입 수정 |
| 설정 로드는 성공했지만 노드 전체가 타임아웃 | 구독이 업데이트되지 않았거나 노드 도메인이 오염됨 | 구독 업데이트; proxy-server-nameserver 설정 |
| 일부 사이트가 안 열림 | 규칙이 매칭되지 않고 MATCH 기본값이 없음 | MATCH를 마지막에 추가 |
| fake-ip 환경에서 특정 서비스 오작동 | 해당 도메인은 실제 IP가 필요함 | fake-ip-filter에 추가 |
| 패널이 코어에 연결되지 않음 | external-controller 주소나 secret이 틀림 | 리스닝 포트와 토큰 확인 |
설정을 온라인 도구에 붙여넣지 마세요
문제 해결 시 설정 전체를 온라인 YAML 검증 사이트에 붙여넣지 마세요: 서버 주소, 포트, 비밀번호가 그대로 들어있습니다. 로컬 에디터(VS Code 등)의 YAML 플러그인만으로도 문법 검사가 충분하며, 코어의 -t 옵션만으로도 의미 검사가 충분합니다.
여기까지 오면 설정 파일의 골격부터 필드, 규칙, 오버라이드까지 전체 흐름이 정리됩니다. 실제 사용 중 더 구체적인 문제—연결이 안 됨, 속도가 느림, 특정 앱이 프록시를 안 탐—은 FAQ 페이지에 증상별로 해결 순서가 정리되어 있습니다. 아직 클라이언트를 설치하지 않았다면 다운로드 페이지에서 플랫폼별로 현재 유지보수 중인 선택지를 확인할 수 있고, 최소 흐름을 먼저 빠르게 실행해보고 이 페이지로 돌아와 필드를 찾고 싶다면 가이드 페이지부터 시작하세요.