설정 파일의 본질: 한 편의 YAML 텍스트
Clash와 mihomo(Clash Meta) 코어의 모든 동작은 YAML 형식의 설정 파일 하나로 결정됩니다. 구독 링크로 내려받는 파일도 결국 서버 쪽에서 미리 작성해 둔 YAML이며, 클라이언트 화면의 모드 전환이나 노드 선택 역시 이 파일의 필드 값을 바꾸는 것에 불과합니다. 구조를 이해하면 포트 변경, 규칙 추가, DNS 조정 모두 해당 항목을 찾아 몇 줄만 고치면 끝나는 일입니다.
YAML 문법은 세 가지만 기억하면 됩니다. 들여쓰기는 공백만 쓰고 탭은 금지이며 보통 두 칸씩 들여씁니다. 키와 값은 콜론(:)으로 구분하고 콜론 뒤에는 반드시 공백을 넣습니다. 하이픈(-)으로 시작하는 항목은 리스트이며 # 뒤의 내용은 주석입니다. 설정 전체는 여러 최상위 필드로 구성되며, 자주 등장하는 필드와 역할은 다음과 같습니다.
| 최상위 필드 | 역할 |
|---|---|
| mixed-port | HTTP와 SOCKS5 요청을 함께 받는 혼합 프록시 포트 |
| allow-lan | 같은 네트워크의 다른 기기 접속 허용 여부 |
| mode | 동작 모드: rule(규칙) / global(전체) / direct(직결) |
| log-level | 로그 출력 상세도 |
| external-controller | 코어 API 수신 주소, 웹 패널이 이를 통해 통신 |
| dns | 내장 DNS 해석 설정 |
| proxies | 프록시 노드 목록 |
| proxy-groups | 프록시 그룹, 클라이언트 화면에서 전환하는 대상 |
| rules | 트래픽 분류 규칙, 위에서부터 순서대로 매칭 |
| tun | TUN 가상 네트워크 카드 모드(mihomo 전용) |
이 중 proxies, proxy-groups, rules 세 항목이 트래픽 경로를 결정하는 핵심으로 이 글의 중심 내용이며, dns 항목은 도메인 해석 방식을, 나머지 필드는 포트와 실행 동작을 제어합니다. 아래에서 항목별로 자세히 살펴봅니다.
포트 및 전역 필드: mixed-port부터 external-controller까지
mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
external-controller: 127.0.0.1:9090mixed-port는 혼합 포트로 HTTP와 SOCKS5 요청이 모두 여기로 들어와 코어에 전달되며, 대부분의 클라이언트와 구독은 기본값으로 7890을 사용합니다. 예전 설정에서 따로 쓰던 port(HTTP 전용)와 socks-port도 여전히 유효하지만, 새 설정에서는 mixed-port 하나만 두면 충분합니다.
allow-lan: true로 설정하면 같은 네트워크의 휴대폰이나 태블릿이 이 기기를 프록시 게이트웨이로 사용할 수 있습니다.bind-address는 어떤 네트워크 카드에서 수신할지 지정합니다. 공용 네트워크 환경에서는 false를 유지하세요.mode: rule은 rules 항목에 따라 트래픽을 분류하고, global은 모든 트래픽을 선택한 프록시 그룹으로 보내며, direct는 전부 직결합니다. 클라이언트 화면에서 모드를 전환할 때 바뀌는 값이 바로 이것입니다.log-level: 평소에는 info로 충분하며, 연결 문제를 진단할 때만 잠시 debug로 바꾸고, silent는 로그를 아예 출력하지 않습니다.external-controller: 코어의 RESTful API 수신 주소로 metacubexd, yacd 같은 웹 패널이 이를 통해 상태를 조회하고 노드를 전환합니다. 다음 줄에secret을 지정하면 접속 비밀번호를 설정할 수 있어 포트가 노출돼도 함부로 제어당하지 않습니다.
mihomo 설정에는 unified-delay, tcp-concurrent, find-process-mode 같은 확장 필드도 자주 보이는데, 이는 Meta 코어 전용 항목입니다. 원본 Clash는 알 수 없는 키를 만나면 곧바로 오류를 일으키므로 코어를 혼용할 때 주의해야 합니다.
dns 항목: 도메인 해석 방식
dns:
enable: true
listen: 0.0.0.0:1053
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
nameserver:
- 223.5.5.5
- 119.29.29.29
fallback:
- tls://1.1.1.1
- https://dns.google/dns-query
fake-ip-filter:
- "*.lan"
- "*.local"enable은 전체 스위치로 TUN 모드를 쓸 때는 반드시 켜야 합니다. listen은 내장 DNS 서비스의 수신 주소로 시스템이 보낸 도메인 조회 요청을 여기서 받아 설정에 따라 상위 서버로 전달합니다.
enhanced-mode: fake-ip 모드는 코어가 먼저 가짜 IP를 반환한 뒤 연결이 성립되면 도메인 기준으로 트래픽을 분류하므로 속도가 빠르고 판별이 정확합니다. redir-host는 예전 방식으로 최신 코어에서는 점차 사용하지 않으므로 fake-ip를 유지하는 편이 좋습니다.fake-ip-range: 가짜 IP 주소 풀로 기본값은 198.18.0.1/16이며 보통 바꿀 필요가 없습니다.nameserver: 기본 상위 DNS 서버로 세 가지 형식을 지원합니다. 순수 IP는 UDP로,tls://로 시작하면 DoT로,https://로 시작하면 DoH로 조회합니다.fallback: 해외 도메인 해석에 쓰이는 상위 서버로 예전 방식이며, mihomo는 도메인 접미사별로 다른 서버를 지정할 수 있는nameserver-policy사용을 더 권장합니다.fake-ip-filter: 목록에 있는 도메인은 가짜 IP를 반환하지 않으며, 로컬 네트워크 호스트명이나 일부 QR 코드 로그인 도메인이 여기 자주 들어갑니다.
언제 적용되는가
dns 항목은 코어가 트래픽을 직접 처리할 때만 작동합니다. 순수 시스템 프록시 모드에서는 브라우저가 도메인을 직접 해석하므로 dns 항목이 관여하지 않으며, TUN 모드에서는 모든 조회가 코어를 거치므로 이 항목의 설정이 실제로 적용됩니다.
proxies 항목: 하이픈 하나가 노드 하나
proxies:
- name: "홍콩 01"
type: ss
server: hk1.example.com
port: 8388
cipher: aes-128-gcm
password: "example-password"
udp: true
- name: "일본 01"
type: vmess
server: jp1.example.com
port: 443
uuid: 00000000-0000-0000-0000-000000000000
alterId: 0
cipher: auto
tls: true
network: wsproxies는 노드 목록으로 하이픈으로 시작하는 각 항목이 하나의 노드를 나타냅니다. name은 표시 이름, type은 프로토콜, server와 port는 서버 주소이며, 나머지 필드는 프로토콜에 따라 다릅니다. ss는 cipher와 password가 필요하고, vmess는 uuid, alterId, cipher가 필요하며, vless는 uuid, trojan은 password와 sni, hysteria2는 password가 필요합니다. udp: true는 UDP 트래픽 전달을 허용한다는 의미입니다.
mihomo가 지원하는 프로토콜은 원본 Clash보다 많습니다. 원본은 ss, ssr, vmess, trojan, snell 등을 지원하고, Meta 코어는 vless, hysteria, hysteria2, tuic 등을 추가로 지원합니다. 이 항목은 거의 항상 구독으로 자동 생성되므로 직접 수정하기 전에 한 가지를 확인하세요. 다음에 구독을 갱신하면 수동으로 고친 내용은 덮어써집니다.
proxy-groups 항목: 화면에서 전환하는 대상
proxy-groups:
- name: "자동 선택"
type: url-test
proxies:
- "홍콩 01"
- "일본 01"
url: "http://www.gstatic.com/generate_204"
interval: 300
tolerance: 50
- name: "수동 선택"
type: select
proxies:
- "자동 선택"
- "홍콩 01"
- "일본 01"
- DIRECT클라이언트 화면에서 선택하는 대상은 개별 노드가 아니라 언제나 프록시 그룹입니다. type은 네 가지가 있습니다. select는 수동 선택, url-test는 지연 시간 기준 자동 최속 선택, fallback은 가용성에 따라 순차 전환, load-balance는 여러 노드에 연결을 분산합니다.
url: 지연 시간 테스트 대상 주소로 보통 http://www.gstatic.com/generate_204 를 사용합니다.interval: 자동 속도 측정 주기(초 단위)로 300이면 5분마다 한 번 측정합니다.tolerance: 허용 오차(밀리초 단위)로 새로 측정한 노드의 지연 시간이 현재 노드보다 이 값만큼 낮아야 전환되며, 이를 통해 잦은 전환을 방지합니다.
그룹의 proxies 목록에는 노드 이름뿐 아니라 다른 그룹 이름도 쓸 수 있어 '수동 선택 → 자동 선택 → 여러 노드' 형태의 중첩 구조를 만들 수 있으며, 내장 정책인 DIRECT와 REJECT도 사용할 수 있습니다. 규칙 항목은 그룹 이름을 참조하므로 노드는 구독 갱신에 따라 바뀌어도 그룹 구조는 그대로 유지됩니다.
rules 항목: 위에서부터 순서대로, 매칭되면 즉시 중단
rules:
- DOMAIN-SUFFIX,ads.example.com,REJECT
- DOMAIN-KEYWORD,bilibili,DIRECT
- GEOSITE,cn,DIRECT
- IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
- GEOIP,CN,DIRECT,no-resolve
- MATCH,수동 선택규칙은 위에서부터 순서대로 매칭되며 하나라도 맞으면 즉시 멈추므로 작성 순서가 곧 우선순위입니다. 맨 아래에 두는 MATCH는 앞의 어떤 규칙에도 걸리지 않은 트래픽을 모두 받는 최종 처리 규칙입니다. 각 규칙은 유형, 매칭 값, 정책 대상의 세 부분으로 구성되며, 정책 대상에는 프록시 그룹 이름, 노드 이름, 또는 DIRECT(직결)와 REJECT(차단)를 쓸 수 있습니다.
| 규칙 유형 | 매칭 대상 | 예시 |
|---|---|---|
| DOMAIN | 전체 도메인 | DOMAIN,www.example.com,PROXY |
| DOMAIN-SUFFIX | 도메인 접미사 | DOMAIN-SUFFIX,google.com,PROXY |
| DOMAIN-KEYWORD | 도메인 키워드 | DOMAIN-KEYWORD,bilibili,DIRECT |
| GEOSITE | 도메인 분류 라이브러리(mihomo 전용) | GEOSITE,cn,DIRECT |
| IP-CIDR | 대상 IP 대역 | IP-CIDR,10.0.0.0/8,DIRECT,no-resolve |
| GEOIP | IP 소속 지역 | GEOIP,CN,DIRECT |
| DST-PORT | 대상 포트 | DST-PORT,443,PROXY |
| PROCESS-NAME | 프로세스 이름 | PROCESS-NAME,telegram.exe,PROXY |
| MATCH | 최종 처리, 전체 매칭 | MATCH,PROXY |
실수하기 쉬운 부분이 두 가지 있습니다. 첫째, IP-CIDR와 GEOIP처럼 IP로 판단하는 규칙은 도메인 요청을 만나면 먼저 DNS 조회를 한 번 실행하는데, no-resolve 옵션을 추가하면 이를 막고 판단을 뒤쪽의 도메인 규칙에 넘길 수 있습니다. 둘째, GEOSITE는 mihomo만 지원하며 geosite 데이터 파일이 필요해 원본 Clash가 읽으면 곧바로 오류가 발생합니다. GEOIP는 두 코어 모두 지원하지만 데이터 파일 형식이 코어마다 다릅니다.
수정 내용 적용 방법과 자주 나오는 오류
데스크톱 클라이언트에서는 설정을 고친 뒤 설정 화면에서 새로고침 버튼만 누르면 됩니다. mihomo는 핫 리로드를 지원하므로 프로그램을 다시 시작할 필요가 없습니다. 명령줄로 실행하는 mihomo는 API로 새 설정을 전달해 갱신할 수 있습니다.
YAML 오류가 자주 발생하는 지점
들여쓰기에 탭이 섞여 있는 경우, 콜론을 전각 문자 「:」로 잘못 입력한 경우, 콜론 뒤에 공백을 빠뜨린 경우, 리스트 항목의 들여쓰기가 앞 항목과 맞지 않는 경우, 노드 이름에 콜론이나 특수 문자가 있는데 인용부호를 붙이지 않은 경우가 대표적입니다. 클라이언트가 시작에 실패하며 「yaml: line xx」 같은 메시지를 띄우면 해당 줄 번호를 기준으로 이 항목들을 하나씩 확인해 보세요. 대부분의 문제는 여기서 발생합니다.
그 외 자주 생기는 문제 두 가지가 있습니다. 하나는 포트 충돌로, 7890 포트가 다른 프로그램에 점유되어 있으면 코어가 시작에 실패하므로 mixed-port 값을 바꾸거나 점유 중인 프로세스를 종료하세요. 다른 하나는 rules를 수정했는데도 적용되지 않는 경우로, 대부분 앞쪽에 더 넓은 범위의 규칙이 먼저 매칭되기 때문입니다. log-level을 debug로 바꾸면 로그에서 각 트래픽이 실제로 어느 규칙에 매칭됐는지 확인할 수 있습니다.
설정 파일의 구조는 결국 이 몇 가지로 정리됩니다. 포트 필드는 입구를 정하고, dns는 해석 방식을 정하며, proxies는 노드 목록, proxy-groups는 선택 스위치, rules는 배분표 역할을 합니다. 이 순서대로 자신의 구독 설정을 한 번 읽어 보면 모든 줄이 이해될 것입니다.