Clash 설정 파일 YAML 매뉴얼

설정 파일 구조 총정리

Clash 계열 클라이언트의 모든 동작은 하나의 YAML 형식 설정 파일로 결정됩니다. 구독 링크를 가져오면 클라이언트가 구독 주소에서 받아오는 것도 본질적으로 이 파일이며, 화면에서 노드를 전환하거나 모드를 조정하거나 규칙을 추가·삭제하는 동작도 결국 파일 내 해당 필드로 반영됩니다. 이 파일을 이해하면 클라이언트의 모든 화면 조작이 명확해집니다.

이 파일은 보통 config.yaml이라는 이름으로 클라이언트 설정 디렉터리에 저장됩니다. Clash Plus, Clash Verge Rev, FlClash 등 GUI 클라이언트는 이 파일의 읽기·쓰기를 대신 관리합니다: 구독을 가져올 때 생성되고, 옵션을 전환할 때 다시 작성됩니다. 직접 편집하기 전에는 먼저 클라이언트를 종료하거나 해당 클라이언트의 오버라이드 정책을 확인하는 것이 좋습니다. 그렇지 않으면 방금 수정한 내용이 화면 조작으로 통째로 덮어써질 수 있습니다. 오버라이드 메커니즘에 대한 자세한 설명은 이 페이지의 8장을 참고하세요.

최상위 필드 한눈에 보기

완전한 설정 파일의 최상위는 여러 필드가 나란히 구성되며, 필드 간 선후 의존 관계가 없어 작성 순서는 파싱에 영향을 주지 않습니다. 자주 쓰이는 필드와 그 역할은 다음과 같습니다:

최소한으로 동작하는 설정에는 세 가지만 있으면 됩니다: 리스닝 포트, 최소 하나의 노드, 최소 하나의 규칙. 나머지 필드는 모두 기본값이 있어 생략 시 커널이 기본 동작으로 실행됩니다. 구독 변환 서비스가 생성하는 설정은 대개 필드가 모두 갖춰져 있으므로, 직접 간소화할 때는 핵심만 남기면 되고 항목별로 그대로 옮길 필요는 없습니다.

YAML 문법의 4가지 기본 원칙

YAML의 파싱 규칙은 엄격하며, "설정이 시작되지 않는" 문제 대부분은 내용이 아니라 형식 문제에서 비롯됩니다. 작성 시 다음 4가지 원칙을 지켜야 합니다:

• 들여쓰기는 공백만 사용하고 Tab은 쓰지 않습니다. 같은 레벨의 들여쓰기 폭은 반드시 일치해야 하며, 관례적으로 2칸을 사용합니다.
• 키와 값 사이는 반각 콜론과 공백 하나로 구분하여 key: value 형태로 씁니다. 콜론 뒤 공백 누락은 흔한 오류입니다.
• 목록 항목은 반각 하이픈과 공백으로 시작합니다. 하이픈을 맨 앞에 두거나 들여써도 되지만, 같은 파일 안에서는 스타일을 통일해야 합니다.
• 값에 콜론, 우물 정(#), 중괄호 등 특수 문자가 포함되면 값 전체를 큰따옴표로 감싸야 합니다. 비밀번호나 토큰 계열 필드는 항상 따옴표를 붙이는 것이 좋습니다.

config.yaml · 최소 뼈대

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

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

rules:
  - MATCH,노드 A

이 뼈대는 아홉 줄뿐이지만 이미 실행 가능한 설정입니다: 로컬 7890 포트에서 프록시 요청을 받아 모든 트래픽을 단일 노드로 전달합니다. 실제 구독 설정은 이 위에 노드, 정책 그룹, 규칙을 확장한 것으로 뼈대 구조 자체는 변하지 않습니다. 이후 장에서 각 부분의 필드를 하나씩 자세히 설명합니다.

공통 필드: 포트, 모드와 스위치

최상위 공통 필드는 커널의 전반적인 동작을 제어합니다: 어떤 포트로 요청을 받을지, 어떤 정책으로 분기할지, 로그를 어느 수준까지 남길지, LAN 공유를 허용할지 등입니다. GUI 클라이언트 대부분은 이 필드들을 설정 페이지의 스위치로 매핑해 두었으므로, 직접 작성할 때는 이 절을 참고하면 됩니다.

리스닝 포트

port는 HTTP 프록시 포트, socks-port는 SOCKS5 포트, mixed-port는 혼합 포트로 하나의 진입점에서 HTTP와 SOCKS5 연결을 동시에 받습니다. 현재 대부분 클라이언트는 혼합 포트만 노출하며, 시스템 프록시와 브라우저 확장 프로그램도 이곳을 가리킵니다. 세 필드는 포트가 서로 충돌하지 않는 한 함께 사용할 수 있으며, 필요 없는 진입점은 해당 줄 전체를 생략하면 커널이 그 포트를 열지 않습니다.

redir-port와 tproxy-port는 Linux 투명 프록시용으로 iptables 포워딩과 함께 사용되며, 데스크톱 사용자는 대개 필요하지 않고 라우터·게이트웨이 환경에서만 활성화합니다. 관련 배포 절차는 Linux 명령줄 배포 글을 참고하세요.

실행 모드

mode는 세 값 중 하나를 가집니다: rule은 규칙 목록에 따라 분기하는 일상적인 사용 모드이고, global은 모든 트래픽을 GLOBAL이라는 내장 정책 그룹에 넘기는 것으로 화면상 "전역 모드"에 해당하며, direct는 전체 직결로 프록시를 일시 중지하는 것과 같습니다. 화면에서 모드를 전환하는 것은 이 필드를 다시 쓰고 즉시 반영하는 것일 뿐이며, 설정 파일의 초기값이 매번 시작할 때의 기본 모드를 결정합니다.

로그와 외부 제어

log-level은 조용한 순서부터 시끄러운 순서로 silent, error, warning, info, debug가 있습니다. 평소에는 warning이나 info를 사용하고, 규칙 매칭 문제를 조사할 때는 일시적으로 debug로 조정하면 각 연결의 매칭 과정과 결과를 확인할 수 있습니다.

external-controller는 외부 제어 인터페이스의 리스닝 주소를 지정하며, GUI 클라이언트의 연결 패널, 지연 테스트, 설정 즉시 반영이 모두 이 인터페이스를 통해 이뤄집니다. external-ui는 정적 패널 파일 세트를 가리키며 브라우저로 해당 주소를 열면 커널을 직접 관리할 수 있습니다. secret은 인터페이스 접근 키로, 비워두면 검증하지 않습니다.

LAN 공유와 기타 스위치

allow-lan을 true로 설정하면 같은 LAN의 다른 기기가 이 기기를 프록시 게이트웨이로 사용할 수 있습니다. bind-address는 리스닝할 네트워크 인터페이스를 제한하며, 기본값 *는 모든 인터페이스를 의미합니다. 그 외 자주 쓰는 스위치로는: ipv6는 IPv6 해석과 전달 여부를 제어하고, unified-delay는 지연 테스트 시점을 핸드셰이크 완료 기준으로 통일해 프로토콜 간 측정 결과를 비교 가능하게 하며, tcp-concurrent는 후보 노드에 동시 연결을 시도해 가장 빠른 것을 선택하고, profile.store-selected는 각 정책 그룹의 수동 선택을 기억해 재시작 후 기본 노드로 되돌아가지 않게 합니다.

config.yaml · 공통 필드 예시

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: warning
ipv6: false
external-controller: 127.0.0.1:9090
secret: ""
unified-delay: true
tcp-concurrent: true
profile:
  store-selected: true
  store-fake-ip: false

DNS 필드: 해석 동작과 상위 서버

분기 규칙은 도메인과 IP의 대응 관계에 의존하며, DNS 설정은 도메인이 언제, 어떤 상위 서버에 의해 해석되는지를 결정하는 규칙 매칭의 전제 조건입니다. 설정이 잘못되었을 때 나타나는 전형적인 증상은 프록시를 타야 할 사이트가 직결로 판정되거나, 웹페이지를 열기 전 눈에 띄는 지연이 발생하는 것입니다.

기본 스위치

dns.enable은 이 섹션 전체의 총 스위치이며 기본값은 false로, 이 경우 커널은 도메인 해석을 시스템에 맡기고 이 절의 나머지 필드는 모두 적용되지 않습니다. listen은 내장 DNS 서비스의 리스닝 주소를 지정하며 TUN 모드나 시스템 DNS를 로컬로 지정할 때 사용합니다. ipv6는 AAAA 쿼리 응답 여부를 제어합니다.

해석 모드: fake-ip와 redir-host

enhanced-mode는 fake-ip 또는 redir-host 값을 가집니다. fake-ip 모드에서는 커널이 도메인 쿼리를 받으면 fake-ip-range 구간(기본값 198.18.0.1/16) 내의 가상 주소를 바로 반환하고, 애플리케이션은 이 가상 주소로 연결을 시작하며 커널이 연결이 들어올 때 테이블을 조회해 도메인을 복원한 뒤 규칙에 따라 분기하고 실제 IP를 해석합니다. 이 방식은 애플리케이션 측의 해석 대기 시간을 없애고, 시스템 DNS의 오염된 결과가 분기를 잘못 이끄는 것도 방지합니다. redir-host는 전통적인 방식으로, 프록시가 먼저 실제 IP를 해석한 뒤 애플리케이션에 전달하며 호환성이 가장 좋지만 속도는 약간 느립니다.

fake-ip-filter는 가상 주소를 반환하지 않아야 할 도메인을 나열하며, 이 도메인에 해당하면 실제 해석을 거칩니다. LAN 도메인, 시간 서버, 실제 IP로 서비스 검색이 필요한 프로토콜은 모두 여기에 포함해야 하며, 그렇지 않으면 LAN 기기를 찾지 못하거나 시스템 시간이 동기화되지 않는 등의 이상 현상이 나타날 수 있습니다.

상위 서버

default-nameserver는 "DNS 서버 자체의 도메인"을 해석하는 역할을 합니다. 예를 들어 상위 서버를 dns.alidns.com처럼 도메인 형태로 쓴 경우, 이를 먼저 해석해줄 순수 IP 형태의 상위 서버가 있어야 하므로 이 계층은 반드시 IP를 채워야 합니다. nameserver는 주 상위 서버 목록으로 UDP, TLS, HTTPS 세 가지 방식을 지원합니다. fallback은 프록시를 통한 해석이 필요하다고 판단될 때 사용하는 예비 상위 서버입니다. nameserver-policy는 도메인이나 GEOSITE 분류에 따라 전용 상위 서버를 지정할 수 있어, 예를 들어 중국 도메인은 통신사 DNS로 고정하고 특정 서비스는 암호화된 상위 서버로 지정하는 식으로 fallback보다 세밀하게 제어할 수 있습니다.

config.yaml · DNS 섹션 예시

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"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
    - tls://8.8.4.4

프록시 노드 필드

proxies는 노드 목록이며, 목록의 각 항목은 하나의 아웃바운드 노드를 기술합니다. 어떤 프로토콜이든 기본이 되는 네 필드는 name 노드 이름, type 프로토콜 타입, server 서버 주소, port 서버 포트입니다. 나머지 필드는 프로토콜에 따라 달라집니다. 구독으로 가져온 노드는 이미 구독 제공처에서 생성한 것이며, 직접 작성하는 경우는 주로 백업 노드를 추가하거나 개별 필드를 미세 조정하는 상황입니다.

공통 필드

name은 설정 전체에서 고유해야 합니다. 정책 그룹은 이름으로 노드를 참조하므로 이름이 중복되면 참조 결과를 예측할 수 없습니다. udp는 해당 노드가 UDP 트래픽을 전달할지 여부를 제어하며, 음성 통화, 일부 게임, QUIC 프로토콜이 이에 의존합니다. sni는 TLS 핸드셰이크 시 선언할 도메인을 지정하며, 대부분의 노드는 노드 도메인과 일치해야 합니다. skip-cert-verify를 true로 설정하면 인증서 검증을 건너뛰는데, 자체 서명 인증서를 쓰는 테스트 환경에서만 사용해야 합니다. alpn과 client-fingerprint는 TLS 지문을 미세 조정하고, dialer-proxy는 전치 노드를 지정해 이 노드를 다른 노드 뒤에 이어 체인 중계를 구성합니다.

프로토콜별 작성법

config.yaml · 4가지 프로토콜 노드 예시

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

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

  - name: "Trojan 노드"
    type: trojan
    server: tj.example.com
    port: 443
    password: "your-password"
    sni: tj.example.com
    skip-cert-verify: false

  - name: "Hysteria2 노드"
    type: hysteria2
    server: hy2.example.com
    port: 443
    password: "your-password"
    sni: hy2.example.com
    skip-cert-verify: false

각 프로토콜의 필수 필드와 확장 항목은 차이가 크며, 아래 표는 자주 쓰이는 프로토콜의 체크리스트입니다. 필드명 철자가 틀리면 커널이 시작 검증 단계에서 구체적인 줄 번호를 알려주며, 오류 위치를 찾는 방법은 9장을 참고하세요.

구독을 가져온 뒤 노드 필드를 확인하려면 클라이언트의 설정 미리보기에서 파싱 결과를 볼 수 있습니다: 전송 계층(network), TLS 스위치, SNI가 모두 갖춰져 있는지가 노드의 시작 검증 통과 여부를 결정합니다. 노드를 직접 추가할 때는 먼저 필수 필드만 작성해 연결을 확인한 뒤 확장 필드를 하나씩 추가하는 것이 좋습니다. 그러면 문제가 생겼을 때 원인을 찾는 범위가 훨씬 좁아집니다.

정책 그룹 필드

proxy-groups는 노드를 선택 가능한 집합으로 구성합니다. 분기 규칙의 대상은 보통 노드 이름을 직접 쓰지 않고 정책 그룹 이름을 씁니다: 규칙은 "트래픽을 어느 그룹에 넘길지"를 결정하고, 그룹은 "그룹 내에서 현재 어떤 노드를 쓸지"를 결정합니다. 이렇게 두 계층을 분리하면 노드를 바꿀 때 규칙을 건드릴 필요가 없고, 규칙을 바꿀 때 노드를 건드릴 필요가 없습니다.

그룹 타입과 선택 방식

측정 필드

url-test, fallback, load-balance 세 유형의 그룹은 상태 검사에 의존합니다. url은 측정 대상 주소로 기본값은 http://www.gstatic.com/generate_204이며, 204를 반환하면 사용 가능한 것으로 간주합니다. interval은 측정 간격(초)으로, 너무 촘촘하면 노드 트래픽을 불필요하게 소모합니다. tolerance는 지연 허용 오차(밀리초)로, 기존 최적 노드와의 차이가 이 값보다 작으면 전환하지 않아 노드가 자주 바뀌는 것을 방지합니다. lazy를 true로 설정하면 그룹 내 연결이 없을 때 측정을 일시 중지하며, 여러 백업 경로를 걸어둔 설정에 적합합니다.

그룹 멤버의 출처

proxies 필드는 멤버 이름을 직접 나열하며, 노드 이름일 수도 있고 다른 정책 그룹 이름일 수도 있습니다. 그룹은 중첩이 가능하여 화면상 "노드 선택" 그룹 안에 "자동 선택" 그룹을 넣는 방식이 흔히 쓰입니다. use 필드는 proxy-providers에 선언된 구독을 참조해 구독 내 모든 노드를 그룹에 포함시킵니다. filter 정규식과 함께 사용하면 이름이 일치하는 노드만 남길 수 있고, exclude-filter는 반대로 제외할 수 있습니다.

config.yaml · 정책 그룹 예시

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "자동 선택"
      - "수동 노드 A"
      - "수동 노드 B"
      - DIRECT

  - name: "자동 선택"
    type: url-test
    use:
      - mysub
    filter: "홍콩|대만"
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true

  - name: "광고 차단"
    type: select
    proxies:
      - REJECT
      - DIRECT

DIRECT와 REJECT는 커널에 내장된 두 가지 아웃바운드로 proxies에 정의할 필요가 없습니다: DIRECT는 직결을 의미하고, REJECT는 연결을 즉시 거부하는 것을 의미하며 광고 및 추적 도메인 차단에 자주 쓰입니다.

그룹이 중첩되면 화면에는 가장 바깥쪽 그룹이 표시되고, 안쪽 그룹의 현재 선택이 바깥쪽 그룹의 멤버 하나로 나타납니다. "자동 선택"을 PROXY 안에 넣으면, 평소에는 PROXY에서 이를 선택한 상태로 두기만 하면 측정과 전환은 안쪽 그룹이 처리합니다. 특정 노드를 지정해야 할 때는 바깥쪽에서 일시적으로 선택을 바꾸면 되며, 규칙 목록은 전혀 건드릴 필요가 없습니다.

규칙 문법과 매칭 순서

rules는 분기의 핵심입니다. 연결이 생성될 때마다 커널은 목록의 첫 번째 항목부터 순서대로 비교하며, 매칭되면 해당 항목이 지정한 정책 그룹으로 나가고 더 이상 아래로 진행하지 않습니다. 모두 매칭되지 않으면 마지막 MATCH가 기본값으로 처리합니다. 순서가 곧 우선순위이며, 규칙 작성 노력의 절반은 순서 배치에 들어갑니다.

규칙의 3단 구조

규칙 하나는 쉼표로 세 부분으로 나뉩니다: 타입, 매칭 내용, 목표 정책 그룹. 예를 들어 DOMAIN-SUFFIX,example.com,PROXY와 같습니다. IP 계열 규칙은 네 번째 항목 no-resolve를 추가할 수 있습니다: 기본적으로 도메인으로 연결을 시도하며 IP 규칙과 비교하면 먼저 해석이 한 번 발생합니다. no-resolve를 붙인 IP 규칙은 이미 IP인 연결만 매칭하고 그것을 위해 도메인을 해석하지 않아, DNS 요청을 절약하고 해석 결과가 분기를 방해하는 것도 막습니다. GEOIP와 IP-CIDR 규칙은 관례적으로 이 접미사를 붙입니다.

규칙 타입 빠른 참조

정렬의 실전 의미

예외 규칙은 범위가 넓은 규칙보다 앞에 씁니다: 특정 사이트를 강제로 직결시키고 싶다면 해당 DOMAIN-SUFFIX는 GEOSITE, GEOIP 같은 넓은 범위 항목보다 위에 있어야 합니다. 그렇지 않으면 트래픽이 그 항목에 도달하기 전에 앞선 항목에 가로채입니다. 범위가 좁은 규칙일수록 앞쪽에, 넓을수록 뒤쪽에 두며 MATCH는 항상 맨 마지막입니다. 프로세스 계열 규칙은 시스템 프로세스 정보에 의존하며 Windows 데스크톱에서는 사용 가능하지만, 모바일 커널은 대개 프로세스 이름을 가져오지 못해 작성해도 매칭되지 않습니다.

config.yaml · 규칙 목록 예시

rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - RULE-SET,ads,REJECT
  - GEOSITE,private,DIRECT
  - GEOSITE,google,PROXY
  - GEOSITE,cn,DIRECT
  - GEOIP,private,DIRECT,no-resolve
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,PROXY

설정 제공자: 구독과 규칙 세트

노드와 규칙 모두 메인 설정에서 분리해 "제공자"가 관리하도록 할 수 있습니다: 메인 설정은 소스와 업데이트 방식만 선언하고, 내용은 클라이언트가 주기적으로 가져옵니다. 구독 링크를 가져오면 생성되는 것이 바로 proxy-providers 항목이며, 규칙 세트는 수천수만 개의 분기 규칙을 하나의 참조로 압축한 것입니다.

proxy-providers 구독 소스

각 구독은 하나의 이름 있는 항목입니다. type은 http(원격 가져오기) 또는 file(로컬 파일) 중 하나이고, url은 구독 주소, path는 로컬 캐시 경로로 오프라인일 때 캐시로 시작하며, interval은 자동 업데이트 간격(초)입니다. health-check 하위 섹션은 해당 구독의 모든 노드에 대해 일괄적으로 측정을 켜며, 필드는 정책 그룹의 측정 필드와 동일합니다. override 하위 섹션은 구독 내 노드 필드를 일괄 재작성할 수 있으며, 예를 들어 UDP를 강제로 켤 수 있습니다.

rule-providers 규칙 세트 소스

규칙 세트의 핵심 필드는 behavior입니다: domain은 항목이 도메인 접미사로 매칭됨을, ipcidr은 IP 네트워크 대역으로 매칭됨을, classical은 항목 자체가 완전한 규칙(타입 접두사 포함)임을 의미합니다. 앞의 두 유형은 커널이 전용 인덱스를 구축해 매칭이 매우 빠르지만, 파일에는 순수한 도메인이나 네트워크 대역 목록만 쓸 수 있습니다. format은 yaml과 text 두 가지 파일 형식을 지원합니다.

config.yaml · 제공자 예시

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

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

선언 후에는 실제로 참조해야 적용됩니다: 정책 그룹에서 use: [mysub]로 구독 노드를 포함시키고, 규칙 목록에서 RULE-SET,ads,REJECT로 규칙 세트를 연결합니다. 구독 링크 획득과 형식 변환은 구독 가져오기 글을 참고하세요.

인라인 방식과 제공자 방식은 함께 쓸 수 있습니다: proxies에 백업 노드 한두 개를 직접 유지하고, proxy-providers로 구독의 대량 노드를 관리하며, 정책 그룹에 둘 다 포함시킵니다. 구독을 업데이트해도 제공자 항목에만 영향을 주고 수동 노드는 영향을 받지 않으므로, "전부 proxies에 작성"하는 것보다 안정적인 구성 방식입니다.

오버라이드와 병합

구독 업데이트의 본질은 전체 교체입니다: 클라이언트가 새 설정을 가져오면 기존 파일과 함께 수동 변경 사항도 덮어써집니다. 자신의 수정 사항을 장기적으로 유지하려면 두 가지 방법이 있습니다. 클라이언트가 제공하는 오버라이드 메커니즘으로 변경 사항을 "패치"로 만들거나, YAML의 앵커 문법을 활용해 중복을 줄이고 유지 관리 비용을 낮추는 것입니다.

클라이언트의 오버라이드 메커니즘

주요 GUI 클라이언트는 모두 "구독 원본"과 "사용자 변경 사항"을 계층으로 나눠 저장합니다. Clash Verge Rev는 전역 확장 설정(Merge)과 스크립트라는 두 가지 오버라이드 방식을 제공하는데, 전자는 필드 단위로 병합하고 후자는 JavaScript로 자유롭게 재작성합니다. FlClash는 오버라이드 페이지에서 임의의 필드를 추가·삭제·수정할 수 있습니다. Clash Plus는 화면 설정과 구독 설정을 분리해 저장해 구독을 업데이트해도 설정 항목이 자동으로 유지됩니다. 공통점은 구독 파일이 원본 그대로 유지되고, 사용자 변경 사항은 패치 형태로 얹혀 매 업데이트 후 다시 적용된다는 것입니다.

주의할 점은 병합 방식이 클라이언트마다 다르다는 것입니다: 스칼라 필드(포트, 모드)는 항상 패치가 우선하고, 배열 필드(rules, proxies)는 클라이언트에 따라 항목 단위로 병합하거나, 전체를 교체하거나, 앞뒤 삽입을 지원하기도 합니다. 변경 사항이 적용된 후 가장 확실한 확인 방법은 클라이언트가 최종적으로 생성한 실행 설정을 내보내 목표 필드가 원하는 대로 되었는지 확인하는 것이며, 오버라이드 페이지의 패치 텍스트만 보는 것으로는 부족합니다.

YAML 앵커와 참조

설정을 직접 작성할 때 앵커는 중복을 없앨 수 있습니다: 값 앞에 &이름을 써서 앵커를 정의하고, 이후 *이름으로 그대로 참조합니다. 매핑 타입에서는 <<: *이름으로 앵커의 키-값을 병합해 들여올 수도 있습니다. 여러 정책 그룹이 같은 노드 목록이나 같은 측정 파라미터를 공유할 때, 앵커를 쓰면 하나의 원본만 유지하면 되어 한 곳만 고치면 전체가 바뀝니다.

config.yaml · 앵커 재사용 예시

proxy-groups:
  - name: "자동 선택"
    type: url-test
    url: &test-url http://www.gstatic.com/generate_204
    interval: &test-interval 300
    proxies: &all-nodes
      - "노드 A"
      - "노드 B"
      - "노드 C"

  - name: "백업 경로"
    type: fallback
    url: *test-url
    interval: *test-interval
    proxies: *all-nodes

검증과 문제 해결

설정 문제는 크게 세 가지로 나뉩니다: YAML 형식 오류, 필드 참조 오류, 규칙 로직이 예상과 다른 경우입니다. 이 절의 순서대로 점검하면 대부분의 문제를 몇 분 안에 찾아낼 수 있습니다.

실행 전 검증

mihomo 커널에는 설정 검사 기능이 내장되어 있어 실행하지 않고도 검증할 수 있습니다:

터미널 · 설정 검증 명령

mihomo -t -d /path/to/config-dir

출력이 configuration ok이면 문법과 필드 검사를 통과한 것입니다. 실패하면 오류 메시지에 줄 번호와 필드명이 표시되므로, 안내에 따라 해당 장으로 돌아가 확인하면 됩니다. GUI 클라이언트도 설정을 가져오거나 저장할 때 동일한 검증을 수행하며, 오류 팝업의 문구는 명령줄과 동일합니다.

자주 발생하는 오류 대조표

재시작 없이 변경 사항 적용하기

GUI 클라이언트는 설정을 저장하면 즉시 반영되어 커널을 재시작할 필요가 없습니다. 명령줄 환경에서는 외부 제어 인터페이스에 요청할 수 있습니다: /configs?force=true에 새 설정 경로를 담아 PUT을 보내면 전체가 다시 로드됩니다. fake-ip 캐시로 인한 해석 잔여물은 해당 캐시 인터페이스를 비운 뒤 다시 시도하면 됩니다. 규칙 매칭이 예상과 다를 때는 log-level을 일시적으로 debug로 조정하면, 로그에 각 연결이 매칭된 규칙 번호가 순서대로 출력되어 그 번호를 rules 목록과 대조하면 어느 항목이 트래픽을 가로챘는지 알 수 있습니다.

설정 외의 문제—구독 가져오기 실패, 시스템 프록시 미작동, 부팅 시 자동 실행 등—은 초보자 10문 10답에서 항목별로 답했습니다. 입문 가이드는 사용 문서, 클라이언트 설치 파일은 다운로드 페이지를 참고하세요.