Clash 고급 설정 매뉴얼

설정 기초: 파일 구조와 적용 방식

이후 7개 챕터에서 다루는 모든 내용은 결국 동일한 하나의 YAML 설정 파일로 모입니다. 시작하기 전에 몇 분만 투자해서 커널이 실제로 읽는 설정이 어디서 오는지, 어떤 부분들로 합쳐지는지, 수정 후 적용 여부를 어떻게 확인하는지 정리해 두세요. 이 챕터는 전체의 기반이라, 건너뛰고 바로 설정을 고치면 "고쳤는데 반영이 안 됨" 이나 "구독을 업데이트했더니 커스텀 설정이 전부 사라짐" 같은 상황을 쉽게 겪게 됩니다.

설정 파일의 출처와 계층

실제 사용에서 커널이 로드하는 설정은 보통 하나의 단일 파일이 아니라 세 계층이 합쳐진 결과입니다. 가장 아래층은 구독 서비스에서 받아오는 원본 YAML(노드 목록과 구독 제공 측이 미리 만들어 둔 그룹·규칙 포함), 중간층은 클라이언트(Clash Plus, Clash Verge Rev 등)가 제공하는 로컬 오버라이드(Merge/Script)로, 구독 위에 필드를 추가하거나 대체하는 용도이며, 최상위층은 클라이언트 화면의 스위치 설정(포트, 시스템 프록시, TUN 등)으로 일부 클라이언트는 이 설정들도 최종 설정에 합쳐 넣습니다. 이 계층 구조를 이해하는 이유는 명확합니다. 장기적으로 유지하고 싶은 커스텀 설정은 반드시 오버라이드 계층에 작성해야 하고, 구독 파일을 직접 수정하면 안 됩니다. 구독이 업데이트되면 구독 파일에 직접 넣은 내용은 그대로 덮어써집니다. 오버라이드의 구체적인 방법은 7장에서 설명합니다.

피해 갈 수 없는 몇 가지 전역 필드

다음 필드들은 설정 파일 최상위에 등장하며 이후 챕터에서 계속 참조하므로 먼저 감을 잡아 두세요:

mode 값은 조금 더 설명이 필요합니다. 평소에는 rule(규칙 기반 분기)을 유지해야 합니다. global 은 모든 트래픽을 하나의 정책으로 몰아넣는데, "규칙 자체에 문제가 있는지" 임시로 확인할 때만 적합합니다. direct 는 프록시를 임시로 끄는 것과 같습니다. 세 모드는 모두 클라이언트 화면에서 원클릭 전환이 가능해 파일을 고칠 필요는 없습니다.

수정 후 적용 여부 확인 방법

설정을 수정한 뒤 적용하는 방법은 두 가지입니다. 클라이언트 화면의 "설정 다시 불러오기" 버튼(권장, 현재 작동 상태를 끊지 않음)이나 커널 재시작입니다. 적용 여부를 확인하는 가장 확실한 방법은 로그 페이지를 보는 것입니다. 커널이 시작되거나 다시 불러올 때 리스닝 포트, TUN 상태, 규칙 개수 등을 한 줄씩 출력합니다. 설정에 문법 오류가 있으면 다시 불러오기가 실패하며 로그에 줄 번호가 표시됩니다. 로그 필드가 이해되지 않는다면 이 글을 참고하세요: Clash 실행 로그 읽는 법. YAML 수정 시 한 가지 공통된 조언이 있습니다. 들여쓰기는 반드시 스페이스만 사용하고 Tab 은 쓰지 마세요. YAML 은 들여쓰기에 매우 민감해서, "설정 로드 실패" 라는 오류의 상당수가 실제로는 들여쓰기 오류입니다.

정책 그룹 유형과 실전 활용

정책 그룹(proxy-groups)은 트래픽 분기 체계의 중심입니다. 규칙이 매칭되었을 때 특정 노드를 바로 가리키지 않고 정책 그룹을 가리키며, 이 그룹이 "지금 어떤 노드를 쓸지"를 결정합니다. 구독 서비스는 보통 자체 그룹 구성을 함께 제공하지만, 각 유형의 동작 방식을 이해하면 자신의 사용 습관에 맞춰 자유롭게 재설계할 수 있습니다.

자주 쓰는 4가지 유형의 동작 차이

url-test 와 fallback 의 본질적인 차이를 짚어보면, 전자는 "가장 빠른 것"을 추구해 노드 순위가 바뀌면 전환하고, 후자는 "안정성"을 추구해 목록 앞쪽 노드가 살아 있는 한 절대 전환하지 않습니다. 일상적인 웹 브라우징은 url-test 가 체감이 좋고, 연결 지속성에 민감한 상황(온라인 회의, 장시간 로그인 상태)은 fallback 이 더 적합합니다.

참고할 만한 그룹 설정 예시

proxy-groups:
  - name: 节点选择
    type: select
    proxies: [自动测速, 故障转移, 香港-01, 日本-01, DIRECT]

  - name: 自动测速
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies: [香港-01, 香港-02, 日本-01]

  - name: 故障转移
    type: fallback
    url: https://www.gstatic.com/generate_204
    interval: 300
    proxies: [香港-01, 日本-01, 新加坡-01]

  - name: 下载专用
    type: load-balance
    strategy: consistent-hashing
    url: https://www.gstatic.com/generate_204
    interval: 300
    proxies: [香港-01, 香港-02, 香港-03]

몇 가지 핵심 파라미터를 정리하면, url 은 헬스체크 대상 주소로 관례상 204 상태코드를 반환하는 경량 주소를 사용합니다. interval 은 검사 간격(초)으로 120 이하로 낮추지 않는 것이 좋으며, 너무 자주 측정하면 그 자체로 노드 트래픽을 소모합니다. tolerance 는 url-test 에만 유효하며, 새·기존 최적 노드의 지연 차이가 이 밀리초 값을 초과해야 전환한다는 의미로, 지연이 비슷한 두 노드가 왔다갔다 흔들리는 현상을 효과적으로 억제합니다. load-balance 의 strategy 는 consistent-hashing(같은 목적지 사이트는 항상 같은 노드로, 로그인 상태 유지에 유리)이나 round-robin(연결마다 순환, 더 철저하게 분산)을 선택할 수 있습니다. 그룹에 lazy: true 를 추가하면 사용되지 않을 때 측정을 일시 정지해 트래픽을 더 아낄 수 있습니다.

실전: 진입—기능—지역의 3단 중첩 구조

정책 그룹은 다른 정책 그룹을 참조할 수 있는데, 이는 분기 체계를 설계할 때 가장 유용한 특성입니다. 추천하는 구성 방식은 3단 구조입니다. 최상위는 select 타입의 메인 진입 그룹(평소에는 「자동 측정」에 수동으로 고정), 중간층은 업무별로 나눈 기능 그룹으로 "스트리밍", "AI 서비스", "다운로드 전용" 등이며 각 기능 그룹은 select 타입이고 후보 항목에 지역 그룹과 메인 진입 그룹을 넣습니다. 최하층은 지역별로 묶은 url-test 그룹(홍콩 자동, 일본 자동 등)입니다. 이렇게 하면 평소에는 아무 조작 없이 지나가고, 특정 업무를 임시로 특정 지역에 고정하고 싶을 때 해당 기능 그룹에서 한 번 클릭만 하면 되며 다른 트래픽에는 영향이 없습니다. 규칙이 이 기능 그룹들을 어떻게 가리키는지는 다음 챕터에서 다룹니다.

규칙셋 구독화 관리

수천 개의 DOMAIN-SUFFIX 를 설정 파일의 rules 항목에 그대로 적어 넣으면 유지보수도 업데이트도 어렵습니다. 규칙셋(rule-providers)은 규칙을 독립된 파일로 분리해 구독 방식으로 참조합니다. 메인 설정에는 RULE-SET 한 줄만 남고 규칙 내용은 커널이 주기적으로 원격에서 가져와 로컬에 캐시합니다. 규칙 업데이트가 메인 설정과 분리되는 것은 고급 설정에서 가성비가 가장 높은 개선입니다.

behavior 와 format: 규칙 파일의 세 가지 "체질" 구분하기

format 은 파일 형식을 나타냅니다. yaml 과 text 는 사람이 읽을 수 있는 텍스트이고, mrs 는 mihomo 의 바이너리 형식으로 로드가 빠르고 크기가 작지만 domain, ipcidr 두 behavior 만 지원하며 에디터로 직접 열어 볼 수 없습니다. 다른 사람이 관리하는 규칙 저장소를 참조할 때는 behavior 와 format 이 파일의 실제 내용과 반드시 일치해야 하며, 잘못 지정하면 전체 규칙셋 로드가 실패합니다.

선언과 참조 예시

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

rules:
  - RULE-SET,streaming,流媒体
  - RULE-SET,cn-ip,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,节点选择

interval 은 자동 업데이트 간격(초)으로, 규칙 목록이 자주 바뀌지 않으므로 86400(하루)이면 충분합니다. path 는 로컬 캐시 경로로, 인터넷이 끊긴 상태로 시작해도 커널이 캐시를 바로 사용해 원격을 가져오지 못했다고 해서 부팅이 안 되는 일은 없습니다.

매칭 순서와 no-resolve

rules 항목은 위에서 아래로 순서대로 매칭되며 명중하면 즉시 멈춥니다. 즉 순서가 곧 우선순위입니다. 일반적인 배치 원칙은 이렇습니다. 정확하고 구체적인 업무 대상 규칙은 앞쪽에, GEOIP 같은 IP 규칙은 뒤쪽에 둡니다. IP 규칙을 만났을 때 목표가 여전히 도메인이라면 커널은 소속을 판단하기 위해 먼저 DNS 해석을 한 번 해야 하는데, 이를 앞쪽에 두면 모든 요청의 매칭 속도가 느려집니다. IP 계열 규칙에 no-resolve 접미사를 붙이면 "목표가 IP 가 아니면 이 규칙을 건너뛰고 해석을 유발하지 말라"는 의미로, 해석 오버헤드를 제어하는 흔한 방법입니다. 마지막 줄은 반드시 MATCH 로 마무리해야 하며, 그렇지 않으면 매칭되지 않은 트래픽의 동작을 예측할 수 없습니다.

DNS 설정 최적화

"규칙은 분명히 맞게 적었는데 분기가 이상하다", "웹 페이지를 처음 열 때 유독 느리다" 같은 문제는 대부분 DNS 가 원인입니다. Clash 가 자체 DNS 모듈을 내장하는 이유는 분기 판단이 도메인 해석 결과에 크게 의존하기 때문입니다. 해석이 오염되면 IP 규칙이 오판하고, 해석이 느린 경로를 타면 모든 요청이 그 지연을 기다려야 합니다. 이 챕터에서는 DNS 각 필드의 역할과, 중국 본토/해외 도메인을 분리해 해석하는 표준적인 방법을 정리합니다.

필드 역할 구분: default-nameserver 와 nameserver

가장 혼동하기 쉬운 필드 쌍입니다. default-nameserver 는 오직 한 가지 일만 합니다. nameserver 에 적힌 DoH/DoT 서버 자체의 도메인을 해석하는 것(예를 들어 doh.pub 이라는 도메인 자체도 먼저 IP 로 해석되어야 접속이 가능함)이라서, 반드시 순수 IP 형태의 전통적인 DNS 를 넣어야 합니다. nameserver 가 실제로 평소 쿼리에 사용되는 업스트림이며, 암호화 DNS(DoH/DoT)를 넣는 것을 권장해 평문 쿼리가 경로 상에서 조작되는 것을 막습니다. enhanced-mode 는 해석 결과의 표현 방식(fake-ip 또는 redir-host)을 결정하며 TUN 과 관계가 밀접한데, 자세한 내용은 4장에서 다룹니다.

도메인별로 다른 업스트림 사용: nameserver-policy

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "geosite:cn":
      - https://doh.pub/dns-query
    "geosite:geolocation-!cn":
      - https://dns.cloudflare.com/dns-query
      - https://dns.google/dns-query

nameserver-policy 는 옛날 방식인 fallback + fallback-filter 조합을 대체하는 현대적인 권장 설정입니다. 도메인 소속에 따라 업스트림을 직접 지정합니다. 중국 본토 도메인은 중국 본토 공용 DoH 로 보내 인접 CDN 노드를 받아 속도를 최적화하고, 해외 도메인은 국제 DoH 로 보내 근원부터 오염을 피합니다. geosite: 접두사는 커널에 내장된 도메인 분류 데이터베이스를 참조하는 것으로 직접 도메인 목록을 관리할 필요가 없습니다. 모든 쿼리를 먼저 물어본 뒤 결과를 필터링하는 fallback 방식보다 policy 방식이 경로가 짧고 동작이 훨씬 예측 가능합니다.

흔한 오해와 검증 방법

오해 하나: nameserver 를 전부 해외 DNS 로 채우는 경우입니다. 해외 업스트림이 국내 도메인을 해석하면 해외向 CDN 노드를 반환해 국내 직결 트래픽이 오히려 느려지는데, 이는 "프록시를 켰는데 국내 사이트도 느리다"의 흔한 원인 중 하나입니다. 진단 방법은 속도 저하 점검 체크리스트를 참고하세요. 오해 둘: 브라우저 자체 DoH 를 무시하는 경우입니다. Chrome/Firefox 의 "보안 DNS" 스위치는 클라이언트의 DNS 모듈을 그냥 건너뛰어 fake-ip 와 도메인 규칙을 모두 무효화시킵니다. 브라우저 설정에서 끄거나 도메인 스니핑으로 보완하는 것을 권장합니다. DNS 설정이 예상대로 작동하는지 검증하는 가장 직접적인 방법은 debug 로그를 열어 각 도메인이 실제로 어떤 업스트림을 쓰는지 관찰하는 것이며, 더 많은 해석 관련 문제는 FAQ 페이지의 문제 해결 분류를 참고하세요.

TUN 모드와 Fake-IP

시스템 프록시 모드에서는 "시스템 프록시 설정을 따르는" 애플리케이션만 트래픽을 클라이언트에 넘깁니다. 브라우저는 대체로 따르지만, 상당수의 데스크톱 프로그램, 커맨드라인 도구, 게임 클라이언트는 이 설정을 무시하고 바로 직결합니다. TUN 모드는 가상 네트워크 카드를 만들어 네트워크 계층에서 모든 트래픽을 인수하며, 애플리케이션이 협조하든 안 하든 전부 분기 대상으로 편입시키는 것이 핵심 가치입니다.

TUN 활성화를 위한 최소 설정

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

auto-route 는 시스템 라우팅 테이블을 자동으로 설정해 기본 라우트를 가상 네트워크 카드로 향하게 하고, auto-detect-interface 는 실제 물리 네트워크 카드를 출구로 자동 인식해 트래픽이 가상 네트워크 카드 안에서 맴돌며 루프가 생기는 것을 막습니다. dns-hijack 은 임의의 주소 53번 포트로 향하는 평문 DNS 쿼리를 커널의 DNS 모듈로 가로채 해석 입구를 통일하는데, 이는 fake-ip 가 정상 동작하는 데 매우 중요합니다. 실제 사용에서는 보통 이 부분을 직접 작성할 필요가 없습니다. Clash Plus, Clash Verge Rev 등 클라이언트는 TUN 스위치를 제공해 클라이언트가 동등한 설정을 대신 주입합니다.

stack 의 세 가지 구현 방식

특별한 요구가 없다면 mixed 를 선택하세요. 특정 애플리케이션이 TUN 상태에서 이상 동작을 보이면 stack 을 다른 방식으로 바꿔 시도해 보는 것이 호환성 문제를 진단하는 일반적인 절차입니다.

Fake-IP: 원리와 예외 목록

enhanced-mode: fake-ip 의 동작 방식은 다음과 같습니다. 애플리케이션이 도메인 쿼리를 보내면 DNS 모듈은 실제 해석을 하지 않고 즉시 198.18.0.0/16 예약 대역 안의 "가짜 IP" 를 반환하며 이 가짜 IP 와 도메인의 대응 관계를 기억해 둡니다. 애플리케이션은 가짜 IP 로 연결을 시작하고, 커널은 연결이 들어올 때 도메인을 역으로 조회해 도메인 규칙에 따라 분기하며, 진짜 해석이 필요한 시점에는 출구 쪽에서 완료합니다. 장점은 매우 직접적입니다. 로컬에서 실제 해석을 기다리는 왕복 시간을 절약하고, 규칙 매칭이 오염될 수 있는 IP 가 아니라 신뢰할 수 있는 도메인을 받게 됩니다. 반대로 redir-host 모드는 실제 IP 를 반환해 호환성은 더 "전통적"이지만 해석 대기와 오염 위험이 따르므로 이제는 기본 권장값으로 쓰지 않습니다.

fake-ip 의 대가는, 소수 프로그램이 해석 결과를 연결 이외의 용도(시간 동기화, 로컬 네트워크 탐색, IP 를 서버에 보고)로 사용할 때 가짜 IP 가 오류를 일으킨다는 점입니다. fake-ip-filter 가 바로 이 예외 목록으로, 목록에 있는 도메인은 실제 해석 결과를 반환합니다:

dns:
  fake-ip-filter:
    - "*.lan"
    - "+.local"
    - "time.windows.com"
    - "+.ntp.org"
    - "+.stun.*.*"

이 목록에 넣어야 하는 대표적인 경우는 NTP 시간 동기화 도메인, 로컬 네트워크 mDNS 도메인, STUN/게임 대전처럼 실제 주소 협상이 필요한 서비스입니다. TUN + fake-ip 를 켰을 때만 특정 애플리케이션이 이상해진다면 우선 이 목록에 넣어야 하는지를 의심해 보세요.

도메인 스니핑

분기 규칙은 대부분 도메인을 기준으로 작성되지만, 커널에 도달한 연결에 IP 만 있고 도메인이 없는 경우도 늘 있습니다. 애플리케이션이 자체 DNS 를 내장(예: 브라우저가 DoH 를 켠 경우)해 클라이언트의 해석을 건너뛰거나, 프로그램이 IP 를 코드에 직접 박아 연결하는 경우입니다. 이런 연결은 GEOIP 와 기본 규칙으로만 처리되어 분기 정확도가 크게 떨어집니다. 도메인 스니핑(sniffer)의 역할은 도메인을 "되찾아 오는" 것입니다. TLS 핸드셰이크의 SNI 필드, HTTP 요청의 Host 헤더, QUIC 초기 패킷 같은 평문 메타데이터에서 목표 도메인을 읽어내 규칙 매칭에 다시 활용합니다.

활성화와 포트 범위

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

sniff 아래는 프로토콜별로 스니핑할 포트 범위를 선언합니다. 스니핑은 연결의 앞쪽 몇 개 패킷을 읽어야 하는데, 흔한 포트로 범위를 제한하면 오버헤드를 무시할 수 있는 수준으로 유지할 수 있습니다. 참고로 스니핑이 읽는 것은 프로토콜 핸드셰이크 단계에서 원래 평문으로 전달되는 메타데이터(SNI, Host)일 뿐, 암호화된 내용을 해독하는 것이 아닙니다.

override-destination, force-domain, skip-domain

override-destination 은 도메인을 스니핑한 뒤 그것으로 연결의 목표 주소를 대체할지를 결정합니다. 켜두면 이후 매칭과 아웃바운드가 모두 스니핑된 도메인을 기준으로 이루어져 "가짜 IP 매핑 만료", "애플리케이션이 오래된 IP 로 새 서비스에 연결" 같은 오류를 교정할 수 있어 일반적으로 켜는 것을 권장합니다. force-domain 은 강제 스니핑 목록으로, 목록에 있는 도메인은 이미 해석 기록이 있어도 다시 스니핑해 대조하는데, CDN 도메인과 실제 서비스 도메인이 자주 어긋나는 사이트에 적합합니다. skip-domain 은 건너뛰기 목록으로, 일부 기기 클라우드 서비스(예시의 Mijia)는 TLS 핸드셰이크에 비표준 식별자를 넣는데 스니핑으로 대체되면 오히려 접속이 안 되므로 이런 경우는 제외해 줍니다. 이 세 파라미터를 조합하면 스니핑의 개입 범위를 매우 세밀하게 제어할 수 있습니다.

언제 스니핑을 켜야 하는가

두 가지 신호가 필요성을 알려줍니다. 하나는 로그에 목표가 순수 IP 인 연결이 많이 보이고 결국 GEOIP 나 MATCH 로만 처리되는 경우, 다른 하나는 도메인 규칙을 분명히 적었는데도 일부 애플리케이션 트래픽이 계속 매칭되지 않는 경우입니다. 스니핑을 켠 뒤 로그를 다시 보면 이런 연결에 도메인이 다시 붙어 규칙 매칭 상황이 즉시 개선됩니다. 앞 챕터의 fake-ip 와 함께 쓰면, 스니핑은 브라우저 DoH 가 클라이언트 DNS 를 건너뛴 이후의 마지막 보완 수단이기도 합니다. 참고로 스니핑을 켠 전후에 브라우저에서 인증서 경고가 뜬다면 대부분 서로 관계가 없으며, 구체적인 원인은 이 분석을 참고하세요: Clash 켠 뒤 HTTPS 인증서 오류가 발생하는 원인.

로컬 오버라이드와 다중 구독 병합

1장에서 언급한 원칙을 다시 짚으면, 커스텀 설정은 오버라이드 계층에 작성하고 구독 원문은 건드리지 않습니다. 이번 챕터에서는 두 가지를 자세히 다룹니다. 클라이언트의 오버라이드 기능으로 자신의 수정 사항을 지속시키는 방법, 그리고 여러 구독 서비스의 구독을 하나의 그룹 체계로 병합하는 방법입니다.

로컬 오버라이드: 구독 업데이트 후에도 커스텀 설정이 살아남게 하기

주류 클라이언트(Clash Plus, Clash Verge Rev 등)는 모두 "오버라이드/Override" 기능을 제공하며 흔한 형태는 두 가지입니다. 선언형인 Merge —— YAML 조각을 작성해 두면 클라이언트가 매번 구독을 로드한 뒤 이를 합쳐 넣습니다. 프로그램형인 Script —— 짧은 스크립트 함수를 작성해 해석된 설정 객체를 받아 가공한 뒤 반환합니다. Merge 는 DNS 항목을 추가하거나 커스텀 규칙 몇 줄을 앞에 붙이는 등 구조화된 수정에 적합하고, Script 는 "모든 그룹에 노드를 일괄 삽입", "이름으로 노드 필터링" 처럼 순회 로직이 필요한 상황에 적합합니다. 전형적인 Merge 조각의 예시입니다:

dns:
  enable: true
  enhanced-mode: fake-ip

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

클라이언트마다 Merge 의 병합 방식은 조금씩 다릅니다(전체를 대체할지 항목별로 추가할지, 규칙을 앞에 넣을지 뒤에 넣을지). 처음 사용할 때는 반드시 클라이언트에서 병합 후 최종 설정을 미리 보고 예상과 맞는지 확인한 뒤 저장·적용하세요. 각 클라이언트의 오버라이드 입구 위치는 블로그의 인터페이스 기능 훑어보기를 참고하세요.

proxy-providers: 다중 구독 병합의 올바른 방법

여러 구독 서비스를 동시에 보유하고 있을 때 여러 설정 파일을 왔다갔다 전환하지 마세요. proxy-providers 로 각 구독을 하나의 노드 제공자로 선언한 뒤, 정책 그룹에서 use 필드로 참조하면 모든 노드가 같은 그룹·규칙 체계로 모입니다:

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

proxy-groups:
  - name: 全部节点
    type: select
    use: [airport-a, airport-b]
  - name: 香港自动
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    use: [airport-a, airport-b]
    filter: "(?i)香港|HK|Hong Kong"

filter 는 정규식으로 노드 이름을 걸러내는 것으로, 지역 그룹을 구성할 때 핵심입니다. 두 구독 서비스의 홍콩 노드가 자동으로 같은 "홍콩 자동" 그룹에 모여 속도 경쟁을 벌입니다. use 와 proxies 는 같은 그룹 안에 함께 쓸 수 있어, 수동 노드와 구독 노드를 섞어 써도 문제없습니다.

업데이트 전략과 장애 대응

interval: 43200(12시간)이면 구독 갱신으로는 충분히 부지런합니다. path 캐시는 가져오기가 실패해도 이전 노드 목록을 그대로 쓰도록 보장해, 특정 구독 서비스의 인터페이스가 잠깐 삐끗해도 전체가 멈추지 않게 합니다. health-check 는 모든 provider 에 켜두는 것을 권장합니다. 그렇지 않으면 url-test 그룹이 지연 데이터를 얻지 못해 자동 선택을 완료할 수 없습니다. 또한 provider 의 url 은 커널이 직접 요청을 보내므로, 구독 주소 자체가 프록시를 거쳐야 접속 가능하다면 provider 에 프록시 경로를 설정하거나 먼저 사용 가능한 직결 경로를 확보해야 "닭이 먼저냐 알이 먼저냐" 식의 교착 상태를 피할 수 있습니다.

외부 제어와 관리 패널

커널은 RESTful 제어 인터페이스(external controller)를 자체 내장하고 있으며, 클라이언트 그래픽 화면은 본질적으로 이 인터페이스를 사용하는 하나의 클라이언트일 뿐입니다. 이를 이해하면 다양한 활용이 가능해집니다. 브라우저 패널로 소프트웨어 라우터나 서버에서 돌아가는 순수 커널을 관리하거나, 스크립트로 정책을 주기적으로 전환하거나, 연결 데이터를 자체 모니터링 시스템에 연동할 수 있습니다.

인터페이스 활성화와 접근 제어

external-controller: 127.0.0.1:9090
secret: "your-password"
external-ui: ./ui
external-ui-url: https://example.com/ui.zip

external-controller 가 127.0.0.1 에 리스닝되어 있으면 로컬 기기만 접근할 수 있는데, 이것이 데스크톱 환경의 안전한 기본값입니다. 0.0.0.0:9090 으로 바꿔야 로컬 네트워크의 다른 기기에서 접근할 수 있으며, 이때 secret 은 반드시 설정하고 충분히 복잡해야 합니다. 이 인터페이스는 연결을 읽고, 정책을 바꾸고, 설정을 다시 불러올 수 있어 권한이 클라이언트를 완전히 제어하는 것과 같습니다. 요청 측은 Authorization: Bearer 헤더에 키를 담아 전달합니다.

자주 쓰는 API 몇 가지

# 查看所有策略组与节点状态
curl -H "Authorization: Bearer your-password" http://127.0.0.1:9090/proxies

# 把「节点选择」组切换到指定候选
curl -X PUT -H "Authorization: Bearer your-password" \
  -d '{"name":"香港自动"}' \
  http://127.0.0.1:9090/proxies/节点选择

# 查看当前活动连接
curl -H "Authorization: Bearer your-password" http://127.0.0.1:9090/connections

# 触发指定节点的延迟测试
curl -H "Authorization: Bearer your-password" \
  "http://127.0.0.1:9090/proxies/香港-01/delay?timeout=5000&url=https://www.gstatic.com/generate_204"

/logs 와 /traffic 은 스트리밍 인터페이스로 로그와 실시간 트래픽을 계속 밀어 보내며, 패널에서 스크롤되는 로그와 속도 그래프가 바로 여기서 옵니다. PATCH /configs 는 재시작 없이 mode 전환이나 포트 변경을 할 수 있습니다.

웹 패널: 순수 커널에 얼굴 붙이기

external-ui 는 정적 웹 페이지 디렉터리를 가리키며, 커널이 이를 제어 포트의 /ui 경로 아래에 호스팅합니다. external-ui-url 은 커널이 패널 리소스 패키지를 자동으로 다운로드해 압축을 풀도록 합니다. 커뮤니티에서 자주 쓰는 패널로는 metacubexd, yacd 및 그 파생 버전이 있으며 기능은 대체로 비슷합니다. 그룹 전환, 지연 테스트, 연결 목록, 규칙과 로그 보기 등입니다. 이 방식은 "서버나 라우터에서 순수 mihomo 커널을 돌리는" 상황에 가장 적합합니다. 커널 설치 패키지는 다운로드 페이지의 커널 섹션에서 받을 수 있습니다. 데스크톱 사용자는 보통 필요 없는데, Clash Plus, Clash Verge Rev 등의 클라이언트가 이미 같은 기능을 로컬 화면에 구현해 두었기 때문입니다.