Clash 설정 파일 필드 참조 매뉴얼

Clash 계열 클라이언트의 모든 동작은 하나의 YAML 설정 파일이 결정합니다: 어떤 포트를 리스닝할지, DNS를 어떻게 해석할지, 어떤 노드가 있는지, 트래픽을 어떤 규칙으로 분배할지 전부 이 파일에 기록됩니다. GUI 클라이언트의 스위치와 드롭다운은 사실상 이 파일을 시각적으로 편집하는 도구일 뿐입니다. 필드 자체를 이해해야 인터페이스 옵션이 부족하거나 구독 내용을 미세 조정해야 할 때 막힘없이 대응할 수 있습니다.

이 사이트는 설정 관련 콘텐츠를 명확히 분리했습니다: 사용 문서는 "다운로드부터 연결까지" 최단 경로만 다루며 필드 세부 사항은 다루지 않습니다. 자주 묻는 질문은 증상별로 검색 가능한 개별 문답을 모아둡니다. 이 페이지는 체계적인 필드 참조로, 설정 파일의 위에서 아래로 이어지는 작성 순서에 따라 구성되어 있어 전체를 통독하며 전체 구조를 이해하는 데 적합하고, 상단 목차로 특정 필드가 속한 섹션으로 바로 이동하기도 좋습니다.

필드 의미는 mihomo 커널을 기준으로 설명합니다. 오리지널 Clash 커널이 아카이브된 이후, 이 사이트가 우선 추천하는 Clash Plus를 비롯해 Clash Verge Rev, FlClash, Clash Nyanpasu 등 주요 GUI 클라이언트는 모두 mihomo로 전환되었으며, 이 페이지에서 설명하는 필드는 이들 클라이언트에서 공통으로 사용됩니다. 일부 mihomo 확장 필드는 매우 오래된 커널에서는 사용할 수 없으며, 본문에서 별도로 표시합니다. 각 클라이언트의 플랫폼 지원 범위와 다운로드 방법은 다운로드 페이지에서, 프로젝트 간 계보 관계는 문서 《Clash, mihomo, Verge Rev는 어떤 관계인가》를 참고하십시오.

최상위 구조: 최소 실행 가능한 골격

config.yaml은 여러 최상위 키로 구성된 매핑(mapping)입니다. 모든 선택 항목을 제외하면, 실제로 실행 가능한 최소 설정에는 다섯 부분만 필요합니다: 실행 파라미터, DNS, 노드 목록, 정책 그룹 목록, 규칙 목록. 먼저 골격을 보고, 이후 각 장에서 하나씩 자세히 다룹니다:

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://223.5.5.5/dns-query

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - HK-01
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

최상위 키의 로딩에는 순서 요구가 없으며 커널은 키 이름으로 값을 가져옵니다. 하지만 커뮤니티에서는 관례적으로 "실행 파라미터 → dns → proxies → proxy-groups → rules" 순서로 배치하며, 이는 트래픽 처리의 논리 흐름과 일치해 읽기와 문제 해결이 더 편합니다. 아래 표는 자주 쓰이는 최상위 키와 그 유형을 정리한 것입니다:

작성 규칙: 들여쓰기, 인용부호, 흔한 오타

YAML은 형식에 민감하며, 설정 오류의 상당 부분은 필드 오용이 아니라 작성 방식의 문제입니다. 세 가지 원칙: 첫째, 들여쓰기는 반드시 공백만 사용하며 통일된 2칸을 유지해야 합니다. 탭(Tab)은 바로 파싱 실패를 유발하며 오류 줄 번호가 파일 뒤쪽 먼 위치를 가리켜 원인 파악이 매우 어렵습니다. 둘째, 콜론 뒤에는 반드시 공백 하나가 있어야 하며, port:7890은 잘못된 표기입니다. 셋째, 배열 요소는 "하이픈 + 공백"으로 시작하며, 하이픈의 들여쓰기 단계가 어느 키에 속하는지를 결정합니다.

문자열은 기본적으로 인용부호가 필요 없지만, 세 가지 경우에는 반드시 붙여야 합니다: 값에 콜론, 샤프 등 특수 문자가 포함될 때; 값이 순수 숫자이지만 문자열로 처리하고 싶을 때; 비밀번호, UUID처럼 특수 문자로 시작할 수 있는 민감한 값일 때 — 항상 쌍따옴표를 붙이는 습관이 가장 안전합니다. 또한 YAML 1.1의 유산 문제도 주의해야 합니다: 인용부호 없는 yes, no, on, off는 일부 파서에서 불(boolean) 값으로 처리되므로, 노드 이름이 마침 이런 단어와 같다면 반드시 인용부호를 붙이십시오.

포트 계열: mixed-port, port, socks-port

포트 필드는 로컬 애플리케이션이 트래픽을 커널에 넘기는 방식을 결정합니다. mixed-port는 현재 권장되는 방식으로, 단일 포트에서 HTTP와 SOCKS5 두 프로토콜의 인바운드를 동시에 받아들여 시스템 프록시가 이 포트 하나만 가리키면 됩니다. 대부분의 클라이언트가 기본으로 생성하는 형태이며 관례적으로 7890을 사용합니다. 기존 방식인 port(순수 HTTP)와 socks-port(순수 SOCKS5)는 여전히 유효하며 mixed-port와 병행해 각각 다른 포트를 리스닝할 수 있어, 프로토콜별 입구를 구분해야 하는 디버깅 시나리오에 적합합니다.

또한 redir-port와 tproxy-port가 있으며, Linux 투명 프록시(iptables/nftables 포워딩과 함께 사용)를 위한 것으로 데스크톱 일상 사용에는 설정할 필요가 없습니다. 모든 포트는 동일한 제약을 공유합니다: 로컬의 다른 프로세스와 충돌하면 안 됩니다. 시작 시 bind: address already in use 오류가 나면 포트가 점유된 상태이며, 원인 파악과 포트 변경의 전체 단계는 문서 《Clash에서 포트 점유 오류가 뜰 때》를 참고하십시오.

allow-lan과 bind-address

allow-lan은 로컬 네트워크 내 다른 기기의 인바운드 연결을 허용할지 제어하며 기본값은 false(127.0.0.1만 리스닝)입니다. true로 설정하면 같은 Wi-Fi 상의 스마트폰, TV 셋톱박스가 프록시를 이 PC의 내부망 IP와 포트로 지정해 "한 대에서 프록시 실행, 전체 네트워크 공유"를 구현할 수 있습니다. 함께 사용하는 bind-address는 리스닝할 네트워크 어댑터를 제한하며, 기본값 "*"는 모든 어댑터를 의미하고 다중 어댑터 환경에서는 특정 어댑터의 주소를 입력해 진입 범위를 특정 네트워크 세그먼트로 좁힐 수 있습니다. allow-lan을 켜면 로컬 네트워크 내 모든 기기가 당신의 출구를 경유할 수 있게 되므로, 공용 네트워크 환경(회사, 호텔)에서는 꺼두는 것이 좋습니다.

mode: 세 가지 분기 모드

mode는 세 가지 값을 가집니다. rule은 규칙 모드로, 각 연결마다 rules 목록을 하나씩 비교해 경로를 결정하는 일상적인 표준 형태입니다. global은 전역 모드로, 규칙을 건너뛰고 모든 트래픽을 전역 출구로 보냅니다(인터페이스상 보통 노드 하나를 직접 선택하는 형태로 표시됩니다). direct는 직결 모드로, 모든 트래픽이 프록시를 경유하지 않으며 분기를 임시로 비활성화하되 커널은 계속 실행되는 상태와 같습니다. "특정 사이트가 실제로 어느 규칙을 탔는지" 확인할 때는 global과 rule을 전환해 대조하면 문제가 규칙에 있는지 노드에 있는지 빠르게 판단할 수 있습니다.

로그와 외부 컨트롤러

log-level은 커널 로그의 상세도를 제어하며, 단순한 순서부터 silent, error, warning, info, debug 순입니다. 평소에는 info를 권장하고, 문제 해결 시 debug로 전환하면 각 연결이 매칭된 구체적인 규칙과 DNS 해석 경로를 확인할 수 있으며, 안정화를 확인한 후에는 다시 낮춰 로그 파일이 불필요하게 커지는 것을 방지하십시오. external-controller는 RESTful 컨트롤 인터페이스의 리스닝 주소를 선언하며(관례적으로 127.0.0.1:9090), GUI 클라이언트와 웹 패널 모두 이를 통해 상태를 읽고 노드를 전환합니다. 함께 사용하는 secret은 인터페이스에 접근 암호를 설정하며, 컨트롤러를 0.0.0.0에 리스닝하거나 로컬 네트워크에 개방하는 경우에는 secret을 반드시 설정해야 합니다. 예: secret: "your-secret".

기타 자주 쓰는 스위치

ipv6는 기본값 false이며, true로 설정하면 커널이 AAAA 레코드를 해석하고 연결을 시도합니다. 로컬이나 노드 측 IPv6가 통하지 않으면 일부 사이트에서 오히려 타임아웃이 발생하므로, 링크가 IPv6를 지원하는지 확인한 후 켜는 것을 권장합니다. unified-delay(mihomo 확장)는 지연 테스트에서 핸드셰이크 오버헤드를 제외해 서로 다른 프로토콜 노드 간 지연 수치를 더 비교 가능하게 만듭니다. profile 블록 아래의 store-selected: true는 각 정책 그룹에서 마지막으로 선택한 노드를 기억해, 재시작이나 구독 업데이트 후에도 다시 선택할 필요가 없으며 거의 모든 클라이언트 템플릿에서 기본으로 켜져 있습니다.

왜 내장 DNS가 필요한가

분기의 전제는 "이 연결이 어디로 가는지 아는 것"이며, 도메인 해석이야말로 가장 오염되거나 유출되기 쉬운 지점입니다. 해석을 신뢰할 수 없는 상위 서버에 넘기면 반환된 IP가 잘못될 수 있고, 모든 해석을 로컬 ISP에 맡기면 접속 기록이 그대로 노출됩니다. dns 모듈은 커널이 해석 과정을 직접 담당하도록 하며, 규칙 시스템과 결합해 "어떤 도메인은 어느 DNS 그룹을 사용하고, 해석 결과를 애플리케이션에 어떻게 돌려줄지"를 결정합니다. TUN 모드나 투명 프록시에서는 dns 모듈이 필수이며, 시스템 프록시만 사용할 때는 활성화하지 않아도 되지만 활성화하면 분기 정확도가 눈에 띄게 좋아집니다.

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"
    - "time.*.com"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://223.5.5.5/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

enhanced-mode: fake-ip와 redir-host

이것은 dns 블록에서 영향력이 가장 큰 필드입니다. fake-ip 모드에서는 커널이 각 도메인에 먼저 예약 대역(fake-ip-range로 정의, 기본값 198.18.0.0/16) 안의 가상 주소를 반환합니다. 애플리케이션은 이 가상 IP로 연결을 시도하고, 커널은 가상 IP와 도메인 간 매핑을 유지합니다 — 이점은 애플리케이션 측이 실제 해석을 완전히 생략하고, 규칙이 도메인으로 직접 매칭할 수 있으며, 연결 수립이 빠르고 해석 유출이 없다는 것입니다. 대가는 일부 실제 IP에 의존하는 프로그램(로컬 네트워크 검색, 특정 게임 매칭, NTP 시간 동기화)이 오작동할 수 있어 이런 도메인은 fake-ip-filter 화이트리스트에 추가해야 하며, 화이트리스트에 매칭된 도메인은 실제 해석으로 되돌아갑니다. redir-host 모드는 항상 실제 IP를 반환해 호환성이 가장 좋지만, 일부 경로에서 도메인 정보가 손실되어 규칙 매칭률과 해석 속도가 fake-ip보다 떨어집니다. 데스크톱 클라이언트 템플릿은 대부분 fake-ip를 기본값으로 사용하며, 특정 애플리케이션에 문제가 생기면 filter를 추가하면 됩니다.

세 그룹의 상위 서버: default-nameserver, nameserver, fallback

세 목록은 역할이 명확히 구분됩니다. default-nameserver는 한 가지 역할만 합니다: 이후 두 그룹의 상위 서버인 DoH/DoT 서버 자체의 도메인을 해석하는 것이므로, 반드시 순수 IP를 입력해야 하며 그렇지 않으면 "리졸버 도메인을 아무도 해석해줄 수 없는" 데드락이 발생합니다. nameserver는 주력 상위 서버로 일상적인 모든 해석을 담당하며, 암호화 프로토콜 주소(https://로 시작하는 DoH 또는 tls://로 시작하는 DoT)를 입력하는 것을 권장해 평문 53번 포트가 경로 중간에서 조작되는 것을 방지합니다. fallback은 대체 상위 서버로, fallback-filter와 연동합니다: nameserver의 해석 결과가 필터 조건(전형적인 설정은 geoip: true와 geoip-code: CN, 즉 "결과가 중국 본토 IP가 아님")에 맞을 때 fallback의 결과를 사용합니다 — 이는 오염에 대응해 해외 도메인이 깨끗한 해석 결과를 받도록 하는 용도입니다. 이 메커니즘이 필요 없다면 nameserver만 남겨두면 구조가 더 간단해집니다.

모든 프로토콜이 공유하는 네 가지 필드

proxies 배열의 각 요소는 하나의 노드를 정의합니다. 프로토콜에 상관없이 네 가지 필드는 필수입니다: name(노드 이름, 파일 전체에서 고유해야 함. 정책 그룹과 규칙 모두 이것으로 참조하며 이름이 중복되면 로딩이 실패합니다), type(프로토콜 유형), server(서버 도메인 또는 IP), port(서버 포트). 선택 필드인 udp는 해당 노드가 UDP 트래픽을 전달할지 선언하며, 게임과 실시간 통화 시나리오에서는 켜는 것을 권장합니다(서버가 지원하는 경우). mihomo가 지원하는 프로토콜은 매우 다양합니다: ss, vmess, trojan, vless, hysteria2, tuic, wireguard, socks5, http 등이 모두 type 값으로 사용 가능하며, 아래에서 가장 흔한 세 가지를 자세히 설명합니다.

Shadowsocks(type: ss)

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

핵심은 암호화 파라미터입니다: cipher와 password는 서버와 완전히 일치해야 합니다. 자주 쓰는 cipher로는 aes-256-gcm, chacha20-ietf-poly1305, 그리고 신세대인 2022-blake3-aes-256-gcm(Base64로 인코딩된 고정 길이 키가 비밀번호여야 하며, 임의의 문자열을 입력하면 안 됨)이 있습니다. 암호화 파라미터가 일치하지 않을 때의 전형적인 증상은 연결이 즉시 끊기고 로그에 복호화 오류가 나는 것입니다. 서버가 플러그인(obfs 등)을 사용하면 plugin과 plugin-opts 두 필드를 추가해야 합니다.

VMess(type: vmess)

  - name: "JP-01"
    type: vmess
    server: jp01.example.com
    port: 443
    uuid: 23ad6b10-8d1a-40f7-8ad0-e3e35cd38297
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ray
      headers:
        Host: jp01.example.com

인증 정보는 uuid로, 서버가 발급하며 한 글자도 다르지 않게 그대로 입력해야 합니다. alterId는 현대적인 배포에서는 0(AEAD 활성화)으로 고정됩니다. network는 전송 계층 형태를 결정합니다: tcp는 직접 연결, ws는 WebSocket(주로 CDN 경유와 함께 사용), grpc는 gRPC를 사용합니다. ws를 선택하면 ws-opts에 path와 Host 헤더를 입력해야 하며, 셋 중 하나라도 서버와 불일치하면 핸드셰이크가 실패합니다. tls: true일 때는 servername으로 SNI를 별도 지정할 수 있습니다(server에 IP를 입력하고 인증서는 도메인에 발급된 경우 유용).

Trojan(type: trojan)

  - name: "SG-01"
    type: trojan
    server: sg01.example.com
    port: 443
    password: "your-password"
    sni: sg01.example.com
    skip-cert-verify: false
    udp: true

Trojan은 태생적으로 TLS 위에서 동작하며 일반 HTTPS 트래픽으로 위장합니다. sni는 서버 인증서의 도메인과 일치해야 합니다. skip-cert-verify는 인증서 검증을 건너뛸지 제어하는데, false를 유지하는 것이 기본선입니다 — true로 설정하면 서버 신원 검증을 포기한다는 뜻이며, 어떤 중간자든 노드를 사칭할 수 있게 됩니다. 자체 서명 인증서를 사용하는 테스트 환경에서만 임시로 켤 이유가 있습니다. 프록시 경로에서 인증서 오류가 발생하는 원인과 진단 방법은 문서 《프록시 활성화 후 HTTPS 인증서 오류가 나는 여러 원인》을 참고하십시오.

정책 그룹이란

proxy-groups는 노드와 규칙 사이에 한 단계 추상화를 추가합니다: 규칙이 특정 노드를 직접 가리키는 것이 아니라 정책 그룹을 가리키고, 그룹 내부에서 정해진 정책(수동 선택, 자동 속도 테스트, 페일오버 등)에 따라 실제 출구를 결정합니다. 장점은 명확합니다 — 노드를 바꿀 때는 그룹 안에서만 바꾸면 되고, 수백 개의 규칙은 한 줄도 손댈 필요가 없습니다. 구독 업데이트로 노드 이름이 바뀌어도 그룹의 멤버 목록에만 영향을 줍니다. 그룹의 proxies 멤버는 노드 이름, 내장 정책인 DIRECT(직결)와 REJECT(거부)가 될 수 있으며, 다른 그룹의 이름도 될 수 있어 "지역 그룹 → 총출구 그룹" 형태의 계층 구조를 만들 수 있습니다. 유일한 제약은 순환 참조가 발생하면 안 된다는 것입니다.

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - AUTO
      - HK-01
      - JP-01
      - DIRECT

  - name: "AUTO"
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true
    proxies:
      - HK-01
      - JP-01
      - SG-01

다섯 가지 그룹 유형 하나씩 설명

자동형 그룹(url-test/fallback/load-balance)은 세 가지 속도 테스트 파라미터에 의존합니다: url은 탐지 주소를 지정하며 관례적으로 204 빈 응답을 반환하는 경량 엔드포인트를 사용합니다. interval은 탐지 주기(초)로 300이 흔한 균형점이며, 너무 작게 설정하면 지속적인 테스트 트래픽이 발생합니다. tolerance는 url-test에서만 사용되며 "새/기존 최적 노드의 지연 차이가 이 밀리초 수를 넘어야 전환"한다는 의미로, 지연이 비슷한 두 노드가 왔다 갔다 하는 진동을 억제합니다. lazy: true(mihomo 확장)는 그룹이 사용되지 않을 때 탐지를 일시 중지시켜 노드가 많을 때 백그라운드 요청을 눈에 띄게 줄여줍니다. load-balance에는 별도로 strategy 필드가 있습니다: consistent-hashing은 같은 대상 사이트가 가능한 같은 노드를 계속 사용하도록 해 로그인 상태 유지에 유리하고, round-robin은 엄격하게 순서대로 순환합니다.

그룹 구성 제안

실무에서는 3단 구조를 추천합니다: 최상위에 select 총출구 하나(규칙은 주로 이곳을 가리킴), 중간에 지역별로 url-test 자동 그룹을 하나씩 구성, 최하위에 노드 자체. 스트리밍, AI 서비스처럼 특정 지역이 필요한 서비스는 별도로 select 그룹을 만들어 지역 그룹을 멤버로 참조하게 합니다. 이렇게 하면 일상적으로는 조작이 필요 없고(자동 속도 테스트가 처리), 특수한 서비스는 수동으로 지역을 고정할 수 있으며, 구독 업데이트의 영향 범위도 지역 그룹 내부로 격리됩니다.

기본 형식과 매칭 순서

rules 배열의 각 요소는 유형,매칭값,정책 3단 콤마 구분 문자열입니다. 정책 부분에는 그룹 이름, 노드 이름 또는 내장된 DIRECT/REJECT를 넣을 수 있습니다. 커널은 새 연결마다 위에서 아래로 하나씩 비교하며, 첫 번째로 매칭되면 즉시 멈춥니다 — 이 규칙이 모든 것을 결정합니다: 정확한 규칙(완전한 도메인)은 광범위한 규칙(접미사, 키워드, GEOIP)보다 앞에 두어야 하며, 그렇지 않으면 영영 매칭되지 않습니다. 목록 마지막에는 MATCH로 마무리해 매칭되지 않은 모든 트래픽을 흡수합니다. 규칙 수는 성능에 미치는 영향이 적지만(도메인 규칙은 프리픽스 트리 인덱스를 사용), 순서 오류로 인한 분기 오류는 매우 은밀하므로 변경 후에는 매번 로그로 매칭 상황을 확인하는 것을 권장합니다.

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,tracker,REJECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOSITE,category-ads-all,REJECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

규칙 유형 대조표

no-resolve와 도메인/IP 규칙의 상호작용

IP형 규칙(IP-CIDR/GEOIP)은 간과하기 쉬운 부작용이 있습니다: 연결 대상이 아직 도메인일 때 IP로 비교하려면 먼저 해석해야 하는데, 이 해석이 로컬 DNS를 경유해 유출이 발생할 수 있고 매칭도 느려집니다. IP 규칙에 네 번째 항목 no-resolve를 추가하면 "대상이 원래부터 IP일 때만 비교하고, 도메인이면 이 규칙을 건너뛴다"는 뜻이 되며, 내부망 세그먼트 규칙에는 반드시 붙여야 합니다. 전체 순서 원칙: 도메인형 규칙을 앞에, IP형을 뒤에, MATCH로 마무리; 광고 차단(REJECT)은 같은 도메인 규칙류 중 가장 앞에 둡니다. 규칙 작성 전체 주제(사용자 정의 규칙을 구독 규칙 앞 또는 뒤에 넣어야 하는지 포함)는 문서 《Clash 사용자 정의 규칙 작성법》을 참고하십시오.

rule-providers: 규칙을 외부화하기

rule-providers:
  streaming:
    type: http
    behavior: classical
    format: yaml
    url: https://example.com/rules/streaming.yaml
    path: ./rules/streaming.yaml
    interval: 86400

rules:
  - RULE-SET,streaming,PROXY

수천 개의 규칙을 메인 파일에 밀어넣으면 유지보수도 공유도 어렵습니다. rule-providers는 외부 URL이나 로컬 파일에서 규칙 집합을 불러오는 것을 허용하며, interval 초 단위로 주기적으로 갱신됩니다. behavior는 집합 내용의 형태를 선언합니다: domain(순수 도메인 목록), ipcidr(순수 네트워크 세그먼트 목록), classical(rules와 동일한 완전한 3단 형식). behavior와 파일의 실제 내용이 일치하지 않으면 집합이 조용히 무효화되는데, 이는 외부화된 규칙이 "로딩되는 것처럼 보이지만 적용되지 않는" 가장 흔한 원인입니다.

구독 파일을 직접 수정하면 안 되는 이유

구독형 사용자는 구조적인 모순에 직면합니다: 설정 파일은 서비스 제공자가 생성하며, 구독을 업데이트할 때마다 전체 파일이 다시 다운로드되어 덮어쓰기됩니다 — 안에 수동으로 추가한 규칙, 변경한 포트는 다음 업데이트까지만 유효합니다. 올바른 방법은 "서비스 제공자의 기본 설정"과 "당신 자신의 수정 사항"을 분리해 저장하고, 클라이언트가 로드 시점에 이를 병합해 최종 설정을 만드는 것입니다. 이 메커니즘은 클라이언트마다 이름이 다릅니다: 오버라이드, Override, Merge, 확장 설정 등이지만 원리는 동일합니다.

병합의 기본 문법

병합 설정 자체도 하나의 YAML이며, 바꾸고 싶은 부분만 씁니다. 문법은 두 가지로 나뉩니다: 스칼라와 매핑 필드는 그대로 대체됩니다 — 오버라이드에 mixed-port: 7891을 쓰면 최종 설정의 포트는 7891이 되고, 완전한 dns: 블록을 쓰면 기본 설정의 dns 블록 전체가 대체됩니다. 배열 필드는 앞에 삽입하거나 뒤에 추가할 수 있습니다 — 대부분의 클라이언트는 prepend- 접두사를 기본 배열 맨 앞에 삽입, append- 접두사를 맨 뒤에 추가하는 것으로 관례를 정하고 있으며, 이는 rules에 매우 중요합니다: 앞에 삽입된 규칙은 구독 규칙보다 우선순위가 높고, 뒤에 추가된 규칙은 마무리용으로만 쓰입니다. 전형적인 오버라이드 예:

mixed-port: 7891
log-level: warning

prepend-rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - PROCESS-NAME,steam.exe,DIRECT

append-proxies:
  - name: "SELF-01"
    type: ss
    server: my.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"

스크립트 오버라이드와 proxy-providers

선언형 병합으로 부족한 경우 — 예를 들어 이름으로 노드를 일괄 필터링하거나, 모든 그룹에 특정 멤버를 통일해 삽입하는 경우 — 일부 클라이언트(Verge Rev 등)는 JavaScript 스크립트 오버라이드를 지원합니다: 스크립트가 파싱된 설정 객체를 받아 수정된 객체를 반환하는 방식으로 자유도가 가장 높지만, 오류가 나면 전체 설정 로딩이 실패하므로 조금씩 수정하며 매번 검증해야 합니다. 또 다른 접근은 반대로 가는 것입니다: 서비스 제공자의 전체 설정을 쓰지 않고 proxy-providers로 구독의 노드 부분만 참조하고, 정책 그룹과 규칙은 완전히 직접 구성합니다. 이렇게 하면 구독 업데이트는 노드 풀에만 영향을 주고 메인 설정은 항상 자신의 것으로 유지됩니다. 이 매뉴얼을 다 읽고 자체 규칙 체계를 관리할 의향이 있는 사용자에게 적합합니다:

proxy-providers:
  airport:
    type: http
    url: https://example.com/subscribe?token=xxxx
    path: ./providers/airport.yaml
    interval: 43200
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "PROXY"
    type: select
    use:
      - airport

그룹은 use 필드로 provider를 참조하며(proxies가 아님), 둘은 함께 쓸 수 있습니다. health-check는 provider 내부의 노드도 가용성 탐지에 참여시킵니다.

로드 전: 정적 검증

설정을 다 고쳤다고 바로 재시작해서 운에 맡기지 마십시오. mihomo 커널 실행 파일이 설치된 환경에서는 명령어 하나로 순수 문법 및 의미 검사를 할 수 있으며, 어떤 리스닝도 시작하지 않습니다:

mihomo -d . -t -f config.yaml

-t는 테스트 모드, -d는 작업 디렉터리 지정(GeoIP 데이터 등의 리소스를 여기서 찾음), -f는 검사할 파일 지정입니다. configuration file ... test is successful이 출력되면 통과입니다. 오류가 나면 줄 번호와 원인이 함께 표시되며, 흔한 것으로는 들여쓰기 오류(yaml: line N), 노드 이름 중복(proxy N: name duplicated), 그룹이 존재하지 않는 멤버를 참조(proxy group ... proxy not found), 규칙의 정책 부분 오타 등이 있습니다. GUI 클라이언트도 가져오기 시 동일한 검증을 수행하며, 오류 팝업의 정보는 명령줄과 일치하므로 줄 번호를 따라 파일에서 위치를 찾으면 됩니다.

로드 후: 분기가 예상대로 동작하는지 확인

설정 로딩이 성공했다는 것이 동작이 올바르다는 뜻은 아닙니다. 3단계 검증법: 첫 단계는 로그 확인으로, log-level을 임시로 debug로 올리고 대상 사이트에 접속하면 로그에 이 연결이 매칭된 규칙과 최종 출구가 출력됩니다. 이는 "실제로 어느 규칙을 탔는지" 판단하는 유일한 권위 있는 근거입니다. 두 번째 단계는 연결 패널 확인으로, GUI 클라이언트의 연결 페이지는 활성 연결의 대상, 매칭된 규칙, 출구 그룹을 실시간으로 나열해 전체 트래픽 분포를 관찰하기에 적합합니다. 세 번째 단계는 외부 검증으로, 직결 상태와 프록시 상태에서 각각 IP 확인 서비스에 접속해 출구 주소가 실제로 정책에 따라 바뀌는지 확인합니다. 분기는 정확한데 특정 애플리케이션만 프록시를 타지 않는다면, 애플리케이션이 시스템 프록시를 건너뛰었을 가능성을 먼저 의심해야 합니다 — Windows 스토어 앱의 루프백 제한이 전형적인 사례이며, 해결법은 문서 《Windows 스토어 앱이 프록시를 타지 않는 이유》를 참고하십시오.

고빈도 문제 빠른 조회

증상별로 정리된 더 많은 문답은 자주 묻는 질문 페이지에 있습니다. 설정이 아니라 클라이언트 자체에 문제가 있다고 의심되면 다운로드 페이지에서 다른 클라이언트로 교차 검증할 수 있습니다 — 전체 플랫폼에서 우선 추천하는 것은 Clash Plus이며, 같은 설정이 서로 다른 클라이언트에서 보이는 동작 차이는 종종 문제의 원인 지점을 빠르게 좁히는 데 도움이 됩니다.