MIHOMO / CONFIG.YAML

Clash 고급 설정 가이드

먼저 연결 가로채기, 도메인 조회, 규칙 매칭, 출구 선택을 구분한 다음 해당 설정 항목을 수정하세요. 사용 가이드에서는 최초 설치, 구독 가져오기, 연결 확인을 다룹니다. 이 페이지는 기본 연결이 정상적으로 작동한 뒤 항목별로 설정을 조정하고 문제를 해결할 때 참고하세요. 아직 설치하지 않았다면 클라이언트 다운로드 페이지에서 운영체제에 맞는 패키지를 선택하세요. 해당 플랫폼에서 권장하며 시스템 요구 사항을 충족하는 Clash Plus를 우선 고려하세요. 아래 내용은 mihomo 기본 필드를 기준으로 합니다. 클라이언트에서 특정 필드를 UI로 설정할 수 있는지는 사용하는 코어와 설정 병합 방식에 따라 다릅니다.

프록시 그룹 유형과 출구 선택

프록시 그룹은 ‘규칙에 매칭된 다음 어느 출구로 보낼지’를 결정하며, ‘어떤 트래픽이 이 규칙에 매칭될지’를 정하지는 않습니다. Rule 모드에서는 새 연결이 먼저 rules 순서대로 매칭된 뒤 규칙에 지정된 프록시 그룹으로 전달됩니다. 그룹은 노드, 내장 정책 또는 다른 그룹을 참조할 수 있지만, 참조 대상이 존재해야 하며 순환 참조가 생겨서는 안 됩니다. 예를 들어 업무용 그룹은 기본 출구 그룹을 참조할 수 있지만, 기본 출구 그룹의 후보에 업무용 그룹을 넣으면 안 됩니다. 문제를 해결할 때는 먼저 규칙이 어느 그룹을 가리키는지 확인한 다음 그룹에서 현재 무엇을 선택했는지 살펴보세요.

사용 목적에 맞는 그룹 유형 선택

유형선택 기준사용 사례
select수동으로 선택한 후보 사용고정 출구, 문제 해결 시 변수 분리
url-test탐지 결과에 따라 후보 선택서로 대체 가능한 출구가 여러 개일 때
fallback목록 앞쪽에 있는 사용 가능한 항목 우선주 출구와 대체 출구 지정
load-balance지정한 정책에 따라 연결을 후보에 분배연결마다 다른 출구를 사용해도 되는 경우

안정적인 출구가 필요한 업무에는 select를 사용하세요. 예를 들어 특정 관리 시스템에서 출구 변경을 로그인 이상으로 판단한다면, 다른 노드의 탐지 속도가 더 빠르더라도 자동으로 전환하지 않는 편이 좋습니다. 주·보조 연결에 fallback을 사용할 때는 특정 시점의 속도 측정 결과가 아니라 업무 우선순위에 따라 후보를 입력하세요. 주 연결을 사용할 수 없을 때 새 연결을 대체 연결로 보내는 데 적합합니다. 이미 연결된 장시간 연결은 끊김 없이 이전되지 않으므로 앱에서 다시 연결하거나 로그인해야 할 수 있습니다.

url-test의 url은 탐지 대상이며, interval의 단위는 초, tolerance의 단위는 밀리초입니다. 후보 간 차이가 작을 때 잦은 전환을 줄이는 데 사용합니다. 탐지에 성공했다는 것은 해당 출구에서 테스트 주소에 접속할 수 있다는 뜻일 뿐, 회의나 파일 동기화, 특정 웹사이트도 작동한다는 보장은 아닙니다. 탐지 대상을 정할 때는 모든 후보 출구에서 접근할 수 있는지 확인하세요. 주기적인 탐지는 데이터와 배터리를 소모하므로, 용도가 같은 모든 그룹에서 동일한 노드 목록을 각각 검사할 필요는 없습니다.

load-balance는 하나의 다운로드 작업에 속한 패킷이 아니라 연결을 분배합니다. 여러 연결을 사용하는 앱은 동시에 서로 다른 출구를 쓸 수 있습니다. 해시 방식의 정책을 사용하더라도 외부에 보이는 주소가 고정된다고 보장할 수는 없습니다. 먼저 후보가 모두 허용 가능한 범위인지 확인한 다음, 서로 독립적인 새 연결 두 개로 분배 결과를 확인하세요. 웹 이용이나 로그인 상태를 점검할 때는 고정 출구로 전환해 앱 자체의 세션 문제를 프록시 프로토콜 오류로 오인하지 않도록 하세요.

내장 정책으로 그룹 참조부터 확인

아래는 단독으로 불러올 수 있는 최소 예제입니다. 구독이 없어도 됩니다. 기본은 직접 연결이며, REJECT로 전환하면 example.com과 그 하위 도메인만 차단합니다. 그룹 선택이 적용되는지 확인하기 위한 예제이며 프록시 출구를 구성하지는 않습니다. 기존 클라이언트가 같은 포트를 사용 중이라면 별도 테스트 환경에서 실행하거나 사용 중이지 않은 로컬 포트로 바꾸세요.

mixed-port: 7890
allow-lan: false
mode: rule

proxy-groups:
  - name: ExamplePolicy
    type: select
    proxies:
      - DIRECT
      - REJECT

rules:
  - DOMAIN-SUFFIX,example.com,ExamplePolicy
  - MATCH,DIRECT

테스트 요청은 예제 설정이 수신하는 입구를 통과해야 합니다. 먼저 연결 기록에서 테스트 도메인이 DOMAIN-SUFFIX에 매칭되는지 확인하고, 정책 체인에 ExamplePolicy가 포함되는지 살펴보세요. 정책을 전환한 뒤 관련 앱 연결을 종료하고 같은 요청을 다시 보내세요. 브라우저가 기존 연결 풀을 재사용할 수 있으므로 페이지 새로고침만으로는 새 연결과 기존 연결을 구분하지 못할 수 있습니다. 기록에 요청 자체가 없다면 그룹 이름이나 탐지 매개변수를 수정하지 말고 먼저 연결 가로채기를 점검하세요.

구독을 연결한 뒤 그룹에서 proxies로 특정 노드 이름을 지정하거나 use로 노드 제공자를 참조할 수 있습니다. 전자는 고정 후보가 적을 때, 후자는 구독이 정기적으로 업데이트될 때 적합합니다. 그룹에 이름 필터를 추가했다면 업데이트 후 필터 결과가 비어 있지 않은지 확인하세요. 그룹 이름은 그날 제공업체가 붙인 노드 이름보다 용도를 나타내도록 정하세요. 그러면 구독을 바꿀 때 후보 출처만 조정하면 되고 업무 규칙을 하나씩 수정하지 않아도 됩니다.

설정으로 전환한 뒤 선택 항목이 예상과 다르면 클라이언트가 이전 정책 선택을 저장했는지, 현재 어떤 설정 인스턴스를 읽고 있는지 확인하세요. 목록 순서와 실행 중 선택은 별개이므로 후보의 배치만으로 실제 출구를 판단할 수 없습니다. 적용 전에 명시적으로 매칭되는 도메인, 기본 규칙으로 처리되는 도메인, 대체 출구가 필요한 연결을 각각 테스트하세요. 규칙 순서가 여전히 헷갈린다면 GEOIP, GEOSITE, RULE-SET 분기 설정 실전도 참고하세요.

규칙 세트를 구독으로 관리

도메인이나 네트워크 대역 목록을 별도로 관리해야 한다면 규칙을 rule-providers에 두고 rules에서 RULE-SET으로 참조하세요. 제공자는 규칙 항목을 가져와 파싱하고, 최종 출구는 이를 참조하는 규칙이 결정합니다. 관리자는 기본 설정을 수정하지 않고 목록을 업데이트할 수 있지만, 기본 설정의 참조 이름과 매칭 순서, 출구 이름은 일관되게 유지해야 합니다. 첫 적용은 대상이 명확하고 범위가 제한된 규칙 세트 하나로 시작하세요. 처음부터 모든 업무를 한 출처에 몰아넣지 않는 편이 좋습니다.

매칭 방식과 파일 형식 선택

behavior: domain은 도메인 매칭 항목에, ipcidr은 주소 대역에 사용합니다. classical은 규칙 유형과 매칭 내용을 조합해 대상을 표현합니다. 예를 들어 DOMAIN-SUFFIX,example.org와 같습니다. 클래식 규칙 세트의 항목에는 출구 이름이 포함되지 않으며, 출구는 기본 설정의 RULE-SET 행에 지정합니다. 확장자만 바꿔서는 실제 내용의 형식이 달라지지 않습니다. format: yaml을 사용하면 규칙 파일의 payload 배열에 항목을 담습니다.

원격 출처로 바꾸기 전에 로컬 파일로 매칭을 확인하세요. 아래 예제는 예시 도메인을 DIRECT로 보내고 나머지 연결도 직접 연결하므로, 출구가 같은지만 보지 말고 연결 기록에서 두 규칙을 구분해야 합니다. 규칙 파일은 mihomo 작업 디렉터리의 해당 상대 경로에 두세요. 데스크톱 클라이언트가 실행 설정을 생성할 때 작업 디렉터리는 구독 파일이 있는 위치와 다를 수 있으므로 시작 로그에서 확인하세요.

# config.yaml에 병합합니다. 기존 rules가 있으면 규칙 목록만 합치세요.
rule-providers:
  documentation:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/documentation.yaml

rules:
  - RULE-SET,documentation,DIRECT
  - MATCH,DIRECT
# rules/documentation.yaml
payload:
  - DOMAIN-SUFFIX,example.org
  - DOMAIN-SUFFIX,example.net

원격 업데이트와 규칙 순서

원격으로 관리하려면 제공자의 type을 http로 바꾸고, 관리자가 제공한 규칙 파일 url을 입력하세요. 별도의 로컬 path를 유지하고 interval로 업데이트 간격을 초 단위로 지정합니다. 여러 제공자가 같은 캐시 경로를 공유하게 하지 마세요. 어느 출처가 파일을 썼는지 확인하기 어려워집니다. 업데이트 후에는 실제로 불러온 항목과 업데이트 시간을 확인하세요. 브라우저에서 URL이 열린다고 해서 코어가 예상한 형식의 파일을 받았다는 뜻은 아닙니다. 로그인 페이지나 오류 안내가 반환될 수도 있습니다.

처음 실행할 때 사용할 수 있는 캐시가 없다면 규칙 출처에 네트워크로 접근할 수 있는지 특히 확인해야 합니다. 규칙 파일에 특정 출구로만 접근할 수 있는데, 그 출구가 같은 규칙 세트나 아직 초기화되지 않은 노드에 의존하면 시작 조건이 순환합니다. 먼저 작동 중인 설정에서 규칙을 가져와 검토하거나 로컬 파일로 초기 설정을 구성하세요. 그다음 원격 업데이트가 어느 경로를 통해 접근할지 정하세요. 업데이트 간격을 줄이는 것은 최초 로딩 실패의 해결책이 아닙니다.

규칙은 위에서 아래로 검사하며 처음 매칭된 규칙이 적용됩니다. 도메인이 정확한 예외 규칙과 더 넓은 규칙 세트에 모두 해당하면 순서에 따라 결과가 달라집니다. 업무 예외를 먼저 두고, 범위가 좁은 도메인 세트를 배치한 다음, 넓은 주소 대역이나 지역 규칙을 처리하세요. MATCH는 마지막에 둡니다. 규칙 세트가 업데이트되면 새 항목도 기존 순서에 따라 적용되므로 기본 설정을 수정했는지만 확인해서는 안 됩니다. 각 원격 규칙 세트의 적용 범위를 예측할 수 있어야 합니다.

주소 기반 매칭에서는 DNS 조회가 일으키는 부작용도 고려해야 합니다. 연결에 원래 도메인이 포함되어 있어도 앞에 있는 주소 규칙이 매칭을 위해 조회를 유발하면 원격 DNS나 이후 도메인 규칙의 문제를 파악하기 어려워질 수 있습니다. 이미 알고 있는 대상 주소만 매칭하려면 해당하는 IP 규칙이나 IP 유형 규칙 세트 참조에 no-resolve를 사용할 수 있는지 검토하세요. 이 옵션은 도메인을 자동으로 주소에 매칭하지 않으며, 코어 전체의 DNS를 끄는 것도 아닙니다. 도메인과 IP 주소를 각각 한 번씩 테스트한 뒤 매개변수 추가 여부를 결정하세요.

트래픽이 잘못 분기되면 실패한 연결의 대상, 매칭 규칙, 규칙 세트 이름, 출구를 기록하세요. 더 앞에 있는 규칙에 매칭됐다면 순서나 범위를 수정하세요. 규칙 세트에 매칭되지 않았다면 로딩 상태와 항목 유형, 도메인을 인식할 수 있는지 확인하세요. 올바르게 매칭됐지만 연결이 실패한다면 프록시 그룹과 출구를 점검하세요. 롤백할 때는 마지막으로 작동한 기본 설정과 해당 규칙 파일을 함께 보관하세요. 참조만 복원하고 새 목록은 계속 불러오는 상황을 피해야 합니다.

DNS 업스트림과 조회 경로

DNS 문제를 해결할 때는 먼저 누가 요청을 보냈는지 확인하고, 다음으로 어느 리졸버에 전달됐는지 확인하세요. 앱은 시스템 리졸버를 사용하거나 자체 암호화 DNS를 활성화할 수 있습니다. 코어도 프록시 서버의 도메인을 조회하거나 주소 규칙에 필요한 대상 IP를 알아내려고 DNS 요청을 보낼 수 있습니다. mihomo에 dns 항목을 설정했다고 해서 모든 앱이 이 경로를 사용하는 것은 아닙니다. 조회 경로를 확인할 때는 브라우저, 운영체제, 코어, 업스트림을 각각 구분하세요. 시스템 설정에 표시된 주소로 모든 요청을 설명하려 해서는 안 됩니다.

일반 조회, 업스트림 조회, 노드 도메인 조회 구분

필드역할혼동하기 쉬운 점
default-nameserver도메인으로 지정된 DNS 업스트림의 초기 조회 처리일반 도메인 조회에 우선 사용하는 서버 목록이 아님
nameserver전용 정책이 적용되지 않는 일반 조회 처리업무 연결의 최종 출구는 결정하지 않음
nameserver-policy도메인 등 매칭 조건에 따라 DNS 업스트림 지정DNS 조회에 매칭되며 rules와는 다름
proxy-server-nameserver프록시 노드의 서버 도메인 조회 전용프록시 출구가 연결되기 전에도 접근 가능해야 함

먼저 IP 주소로 직접 접근할 수 있는 업스트림을 사용하면 도메인 기반 업스트림 자체를 조회해야 하는 의존성을 줄일 수 있습니다. 이후 암호화 업스트림이나 도메인 전용 정책을 하나씩 추가하세요. 노드 주소가 도메인인데 그 도메인을 조회하려면 아직 연결되지 않은 노드가 필요한 경우 출구가 만들어지기도 전에 실패합니다. respect-rules를 활성화하기 전에 mihomo 요구 사항에 따라 proxy-server-nameserver를 설정하고, 해당 설정과 하위 출구가 순환 의존성을 만들지 않는지 확인하세요.

아래 예제는 별도 DNS 테스트용으로 루프백 주소에서 수신하고 직접 조회할 수 있는 공개 리졸버를 사용합니다. 시스템 DNS를 변경하거나 이 기기를 LAN DNS 서버로 만들지는 않습니다. redir-host는 확인 과정에서 실제 주소 응답을 살펴보는 데 유용합니다. 예시 업스트림에 네트워크로 접근할 수 있는지 확인하세요. 사내 네트워크에서 내부 리졸버만 허용한다면, 접근할 수 없는 공개 업스트림을 추가하지 말고 관리자가 제공한 주소로 바꾸세요.

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: redir-host
  nameserver:
    - 223.5.5.5
  proxy-server-nameserver:
    - 223.5.5.5
dig @127.0.0.1 -p 1053 example.org A

도메인별 리졸버 지정 후 가로채기 범위 확인

내부 호스트 기록이 조직의 리졸버에만 있다면 nameserver-policy로 해당 도메인 접미사를 내부 업스트림에 전달하고, 그 리졸버로 가는 경로가 올바른 인터페이스를 통하는지 확인하세요. 내부 리졸버와 공개 리졸버를 같은 목록에 넣는다고 내부·외부 조회가 분리되는 것은 아닙니다. 내부 이름이 관계없는 업스트림으로 전송될 수도 있습니다. 검증할 때는 존재하는 내부 레코드 하나와 공개 레코드 하나를 각각 조회하세요. 관리 화면에서 설정이 로드됐다는 것만으로 조회가 올바르다고 판단하지 마세요.

진단할 때는 세 가지 결과를 비교하세요. 코어의 수신 주소에 직접 질의하고, 운영체제 기본 리졸버를 사용해 질의하고, 문제가 발생한 앱에서 연결을 다시 시도합니다. 첫 번째는 수신과 업스트림이 기본적으로 작동하는지 확인합니다. 두 번째는 시스템이 요청을 코어에 전달하는지 보여줍니다. 세 번째는 앱이 자체 조회 방식이나 캐시를 사용하는지 확인하는 데 필요합니다. 세 결과가 다르다고 반드시 문제가 있는 것은 아닙니다. 차이를 예상된 경로로 설명할 수 있는지가 중요합니다. 브라우저 자체의 암호화 DNS는 일반적인 UDP/TCP 53번 포트 요청을 가로채는 것만으로 바꾸기 어려운 경우가 많습니다.

DNS 누수를 확인하기 전에 허용할 조회 경로를 정의하세요. 예를 들어 내부 도메인은 조직 리졸버를 사용하고, 일반 외부 도메인은 지정된 공개 업스트림을 사용하며, 앱의 암호화 조회에는 별도 조건을 적용할 수 있습니다. 테스트 페이지에 표시되는 것은 재귀 조회 체인의 출구일 때가 많아 기기가 직접 연결한 서버 주소와 다를 수 있습니다. 결과가 예상과 다르면 시스템이나 클라이언트의 조회 기록을 함께 확인하고, 제어할 수 있는 요청 하나로 어느 경로인지 확인하세요. 여러 테스트 사이트를 바꿔 가며 같은 결과만 반복해서 확인하지 마세요.

조회 시간 초과와 조회는 성공했지만 응답이 잘못된 경우를 구분해서 처리하세요. 시간 초과라면 수신이 시작됐는지, 업스트림에 도달할 수 있는지, 경로가 코어 자신에게 되돌아오지 않는지 확인하세요. 응답이 잘못됐다면 전용 정책과 캐시, 주소 체계, 앱이 다른 조회 경로를 사용하는지 점검하세요. 특정 앱에서만 실패한다면 해당 앱의 경로를 우선 재현하세요. 설정 항목 간 관계를 확인 중이라면 config.yaml 파일 구조 자세히 보기를 참고해 DNS 항목과 출구 규칙을 서로 바꿔 쓰지 않았는지 확인하세요.

A와 AAAA를 각각 조회해 두 주소 체계를 확인하세요. DNS의 IPv6 응답만 끈다고 모든 앱의 기존 IPv6 연결이나 시스템 경로가 바뀌지는 않습니다. 반대로 인터페이스의 IPv6만 끄는 것도 업스트림 조회 실패의 해결책은 아닙니다. 수정한 뒤에는 같은 입구에서 요청을 다시 보내고 도메인, 조회 유형, 결과를 기록하세요. DNS 업스트림과 TUN, 브라우저 설정을 동시에 변경하면 롤백 후에도 어느 항목이 영향을 줬는지 알기 어렵습니다.

TUN 트래픽 가로채기와 Fake-IP 매핑

TUN은 기기 트래픽 중 어떤 것을 코어로 보낼지 결정하고, Fake-IP는 가로챈 도메인 조회에 코어가 어떻게 응답할지 결정합니다. 함께 사용할 수 있지만 해결하는 문제는 서로 다릅니다. 시스템 프록시는 시스템 설정을 따르는 앱에만 영향을 주는 경우가 많고, TUN은 가상 인터페이스를 통해 더 많은 트래픽을 가로챌 수 있습니다. Fake-IP는 도메인에 매핑 주소를 할당하고, 연결이 같은 코어 인스턴스로 들어오면 도메인을 복원해 도메인 규칙에 따라 판단할 수 있게 합니다. Fake-IP만 켜고 매핑 주소를 사용하는 연결이 코어를 우회하면 조회 결과는 있지만 연결은 실패할 수 있습니다.

인터페이스, DNS 가로채기, 매핑 순서대로 활성화

먼저 기존 설정에서 코어와 출구가 정상인지 확인한 다음 현재 기본 경로와 기존 VPN 또는 가상 네트워크 인터페이스를 기록하세요. 데스크톱 클라이언트는 보통 인터페이스 생성과 경로 변경 권한이 필요합니다. 모바일에서는 운영체제의 VPN 기능으로 트래픽을 가로채므로 클라이언트 자체 옵션을 사용하세요. 데스크톱 YAML을 모바일 설정 안내로 그대로 사용하지 마세요. VPN을 동시에 실행한다면 사용 환경에 따라 어느 쪽이 기본 경로를 담당할지 먼저 정한 뒤 병행 가능 여부를 테스트하세요. 시작 순서에 기대어 작동하기를 바라지 마세요.

아래는 데스크톱 환경용 시작 설정이며, 이미 작동하는 설정에 병합하세요. mixed는 TUN 프로토콜 스택 선택이며 mixed-port와 다릅니다. auto-route는 트래픽 가로채기에 필요한 경로를 설정하고, auto-detect-interface는 출구 인터페이스를 선택합니다. dns-hijack에는 일반 UDP와 TCP DNS 매칭을 각각 지정합니다. 암호화 DNS가 자동으로 코어에서 처리할 수 있는 일반 조회로 바뀌지는 않습니다.

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

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '+.lan'
  nameserver:
    - 223.5.5.5

예제의 필터 항목은 해당 도메인이 Fake-IP를 반환할지 여부만 결정합니다. 실제 환경에 존재하는 내부 이름은 실제 주소를 반환하도록 하고, 전용 조회 정책으로 해당 이름을 확인할 수 있는 업스트림에 전달하세요. 필터 항목만으로 직접 연결 규칙이 추가되거나 실제 주소가 가상 인터페이스를 우회하도록 경로가 만들어지지는 않습니다. 내부 프린터, 파일 공유, 서비스 검색에 문제가 생기면 이름 조회 가능 여부, 대상 주소의 실제 경로, 앱이 사용하는 검색 프로토콜을 각각 확인하세요.

트래픽 경로를 따라 중단 지점 찾기

활성화한 뒤 세 종류의 대상으로 확인하세요. 도메인 규칙을 확인할 수 있는 공개 사이트, 실제로 접근 가능한 로컬 리소스, 시스템 프록시 설정을 따르지 않는 앱입니다. 공개 사이트는 예상한 규칙에 매칭되어야 하고, 로컬 리소스는 필요에 따라 계속 접근 가능해야 하며, 독립 앱의 연결은 코어에서 확인할 수 있어야 합니다. 테스트 전에 해당 앱에서 별도로 설정한 프록시를 끄세요. 다른 로컬 포트로 연결된 뒤 TUN이 트래픽을 가로챘다고 오인할 수 있습니다.

도메인 조회가 매핑 범위의 주소를 반환하는데 연결 목록에 해당 항목이 없다면 대상 주소의 경로와 인터페이스를 확인하세요. 특히 기기에 겹치는 네트워크 대역이 이미 있는지 살펴보세요. 다른 VPN이나 LAN에 연결한 뒤에만 문제가 생긴다면 경로 우선순위와 인터페이스 선택, 주소 대역 충돌을 먼저 의심할 수 있습니다. 연결이 코어에 들어왔지만 도메인을 식별하지 못한다면 매핑을 만든 인스턴스와 연결을 처리하는 인스턴스가 같은지 확인하고 앱에 이전 매핑 응답이 남아 있는지도 살펴보세요.

네트워크 인터페이스를 전환한 뒤에는 자동 선택이 현장 요구와 맞지 않을 수 있습니다. 듀얼 NIC, 외장 네트워크 어댑터, 업무용 VPN을 사용할 때는 전환 전후의 실제 출구를 기록하고 기본 경로가 바뀌었는지 판단하세요. 일부 앱은 기존 인터페이스의 연결을 한동안 유지하므로 이미 연결된 장시간 연결로 확인하는 것은 적절하지 않습니다. 가로채기 범위를 제한해야 한다면 기존 인터페이스에 남겨 둘 네트워크 대역을 먼저 정한 뒤 코어와 플랫폼이 지원하는 경로 설정을 조정하세요. 대상 트래픽과 겹칠 수 있는 대역을 광범위하게 제외하지 마세요.

기기 전체의 네트워크가 끊기면 먼저 클라이언트에서 TUN을 끄고 기본 경로와 DNS 상태가 복구되는지 확인하세요. 복구되지 않으면 경로를 다시 설치하는 잔류 서비스가 있는지, 다른 VPN이 트래픽을 가로챘는지 확인하세요. 기본 네트워크를 복구한 다음 TUN만 따로 켜서 문제를 재현하세요. 테스트 도중 시스템 프록시를 켜고 프로토콜 스택을 전환하고 네트워크 대역까지 동시에 조정하지 마세요. 각 변경은 서로 다른 계층에 작용하므로 한꺼번에 적용하면 실제 장애 지점을 찾기 어렵습니다.

비교를 위해 redir-host로 되돌릴 때는 조회와 연결을 모두 새로 시작해 앱이 앞서 캐시한 Fake-IP를 계속 사용하지 않도록 하세요. 비교 결과에는 DNS 응답이 바뀌었는지, 규칙 매칭이 바뀌었는지, 기본 경로만 바뀌었는지 구체적으로 기록하세요. 특정 플랫폼에서만 가로채기 문제가 발생한다면 먼저 권한과 VPN 상태를 확인한 뒤 자주 묻는 사용 질문을 참고하세요. 다른 플랫폼의 시스템 설정을 그대로 옮겨 적용해서는 안 됩니다.

도메인 스니핑과 매칭 범위

도메인 스니핑은 대상 주소만 있는 연결에 도메인 정보를 보완할 때 사용합니다. 활성화하기 전에 트래픽이 실제로 코어에 들어오고 있는지, 도메인 정보가 없어 규칙이 잘못 매칭되는지 확인하세요. 신뢰할 수 있는 프록시 요청 도메인이나 Fake-IP 매핑이 이미 있다면 보통 도메인으로 직접 매칭할 수 있습니다. 앱이 IP 주소로만 접속하고 프로토콜에도 식별 가능한 이름이 없다면 스니핑을 켜도 사용할 도메인이 생기지는 않습니다.

식별할 프로토콜과 포트 범위 지정

평문 HTTP는 요청 헤더의 호스트 필드에서 도메인을 가져올 수 있습니다. TLS는 핸드셰이크의 SNI에서 도메인을 확인할 수 있고, QUIC는 해당 프로토콜 식별이 필요하며 핸드셰이크 데이터와 실제 네트워크 동작의 영향을 받습니다. 포트는 탐색 범위를 좁힐 뿐 해당 트래픽이 특정 프로토콜이라는 사실을 보장하지 않습니다. 업무용 앱의 사용자 지정 포트를 통째로 스니핑 대상으로 추가하지 마세요. 실패한 트래픽의 프로토콜과 포트를 먼저 확인한 뒤 일부 연결에만 식별을 활성화하세요. TLS 스니핑을 켜도 HTTPS 페이지 내용을 읽는 것은 아니며 인증서를 가져올 필요도 없습니다.

sniffer:
  enable: true
  parse-pure-ip: true
  override-destination: false
  sniff:
    HTTP:
      ports: [80, 8080]
    TLS:
      ports: [443]
    QUIC:
      ports: [443]
  skip-domain:
    - '+.lan'

여기서는 parse-pure-ip로 도메인 정보가 없는 연결도 식별을 시도하도록 하고, override-destination을 끄는 방법을 사용합니다. 스니핑한 도메인으로 원래 연결 대상을 덮어쓰지 않도록 하기 위해서입니다. 이렇게 하면 먼저 규칙에 도움이 되는지 살펴보고 연결 대상 변경이 필요한지 판단할 수 있습니다. 이 설정을 강제적인 해결책으로 간주하지 마세요. 서비스가 고정 주소로 제공된다면 핸드셰이크에 이름이 포함되어 있어도 이름을 다시 조회하지 않고 원래 주소로 연결해야 할 수 있습니다.

skip-domain은 스니핑에 적합하지 않은 것으로 확인된 도메인을 제외하는 설정이지 임의의 주소 대역을 제외하는 항목이 아닙니다. 앱이 IP 주소로 직접 접속하는 경우 코어가 처리하기 전에 이 항목에 매칭할 도메인 이름을 확보하지 못할 수 있습니다. 이와 같은 문제라면 먼저 프로토콜이나 포트 범위를 좁히고, 필요하면 실제 코어가 지원하는 대상 IP 제외 항목을 사용하세요. 존재하지 않는 도메인을 입력해 전체 네트워크 대역이 건너뛰어지길 기대하지 마세요. 도메인 제외 목록과 DNS의 Fake-IP 필터 목록도 같은 설정으로 취급하지 마세요.

연결 기록으로 활성화 전후 비교

테스트 도메인에 대해 위치가 분명한 정확한 규칙을 미리 작성하고, 출구는 결과를 예측할 수 있는 프록시 그룹으로 임시 고정하세요. 스니핑을 끈 상태에서 새 연결을 한 번 만들어 대상 주소와 매칭 규칙을 기록하세요. 그런 다음 스니핑을 켜고 같은 앱에서 다시 연결해 도메인이 표시되는지, 규칙이 바뀌는지, 최종 접속이 성공하는지 확인하세요. 로그에 도메인 이름이 추가됐지만 규칙 경로가 그대로라면 해당 이름의 매칭 조건부터 확인하세요. SNI가 보인다는 사실만으로 도메인 분기가 예상대로 작동한다고 판단해서는 안 됩니다.

하나의 주소에서 여러 사이트를 제공할 수 있습니다. 연결에 표시되는 도메인은 해당 연결에서 확인한 값이어야 하며, 과거에 같은 주소에서 본 다른 도메인을 규칙에 가져다 써서는 안 됩니다. 외부 계층의 도메인을 확인하더라도 핸드셰이크에서 확인한 대상일 뿐 사용자가 최종적으로 접속한 서비스의 호스트와 다를 수 있습니다. 정확한 식별이 필요한 앱에는 원래 요청 도메인을 보존할 수 있는 접속 방식을 우선 사용하거나, 조회와 연결을 모두 제어할 수 있을 때 Fake-IP 매핑을 활용하세요.

암호화된 클라이언트 핸드셰이크는 실제 서버 이름을 숨길 수 있습니다. 일부 TCP·UDP 앱은 처음부터 사용할 수 있는 도메인 정보를 보내지 않습니다. 이 경우 실제 대상 주소와 포트를 기준으로 범위가 명확한 규칙을 만들거나 앱 트래픽을 특정 출구로 보내세요. 스니핑 포트 범위를 계속 넓혀도 전송되지 않은 이름을 복구할 수는 없으며 오식별 가능성만 높아집니다. 이런 상황은 규칙 세트 관리 실패가 아니라 도메인을 관측할 수 없는 경우로 구분하세요.

UDP에서만 문제가 재현된다면 브라우저가 QUIC를 사용할 때 도메인이 식별되는지, 출구가 해당 트래픽을 처리할 수 있는지, 실패 후 앱이 TCP로 전환하는지 구분하세요. 비교 테스트에서는 조건 하나만 바꾸고 전환할 때마다 새 연결을 만드세요. TCP는 성공하고 UDP만 실패한다고 해서 스니핑 모듈 오류라고 단정할 수 없습니다. 출구 프로토콜과 경로, 방화벽도 연결이 성립하기 위한 조건입니다. 반대로 스니핑으로 이름을 확인했더라도 패킷이 출구를 거쳐 성공적으로 전달됐다는 뜻은 아닙니다.

로그를 공유해야 한다면 규칙 유형과 프로토콜, 포트, 문제 발생 순서는 남기고 내부 도메인이나 업무 환경을 드러낼 수 있는 정보는 삭제하세요. 설정이 유효한지 확인한 뒤 테스트로 효과가 입증된 프로토콜과 포트만 유지하세요. 실제 효과가 특정 앱에만 있다면 재현 조건과 롤백 항목을 기록하세요. 이렇게 하면 클라이언트 업데이트나 설정 오버라이드 변경 후 같은 테스트를 통해 식별 기능이 달라진 것인지 원본 트래픽의 접속 방식이 달라진 것인지 판단할 수 있습니다.

로컬 오버라이드와 여러 구독 병합

업데이트되는 구독과 장기간 유지해야 하는 로컬 규칙을 분리하세요. 구독은 변경되는 노드를 관리하고, 로컬 기본 설정은 포트와 프록시 그룹, 규칙 순서, 로그 수준을 관리합니다. 가져온 원격 구독 본문에 필드를 직접 추가하면 다음 업데이트에서 원격 내용으로 되돌아갈 수 있습니다. 클라이언트 오버라이드 기능을 사용하기 전에 적용 범위가 단일 구독인지, 전체 설정인지, 생성 후 실행 설정인지 확인하세요. 목록을 교체하는지 앞에 삽입하는지 등 병합 방식도 파악해야 합니다.

제공자로 노드 출처 분리

mihomo 노드 제공자 형식에 맞는 proxies 파일이라면 proxy-providers로 여러 출처를 조합할 수 있습니다. 전체 구독에는 rules, dns, 자체 프록시 그룹이 포함되는 경우가 많으므로 클라이언트가 이를 자동으로 제공자용 노드 파일로 분리한다고 가정하지 마세요. 가져오기 전에 최상위 구조와 실제 응답 내용을 확인하세요. 클라이언트에서 전체 설정만 가져올 수 있다면 클라이언트가 명시적으로 제공하는 병합 기능을 사용하고 내보낸 최종 설정을 확인하세요. 클라이언트 전용 오버라이드 문법을 코어 기본 필드로 취급하지 마세요.

# 두 파일이 모두 있어야 하며, 각 파일에는 proxies 목록이 포함된 노드 파일이 들어갑니다.
proxy-providers:
  office:
    type: file
    path: ./providers/office.yaml
  personal:
    type: file
    path: ./providers/personal.yaml

proxy-groups:
  - name: Office
    type: select
    use: [office]
  - name: Personal
    type: select
    use: [personal]

rules:
  - DOMAIN-SUFFIX,example.org,Office
  - DOMAIN-SUFFIX,example.net,Personal
  - MATCH,DIRECT

예제에서는 두 출처를 용도별 그룹에 나눠 넣습니다. 도메인은 해당 용도로 사용할 권한이 있고 실제로 적합한 대상으로 바꾼 뒤 각각 연결을 테스트하세요. 목록을 보기 좋게 만들려고 모든 출처를 하나의 자동 선택 그룹에 넣지 마세요. 개인용 출구와 업무용 출구는 접근 범위와 사용 조건이 다른 경우가 많습니다. 혼합하면 같은 사이트가 시점마다 다르게 작동하고 문제 원인을 파악하기도 어려워집니다. 여러 출처에 같은 이름의 노드가 있다면 출처를 안정적으로 식별할 접두사를 이름에 넣고 UI에 표시되는 실제 후보를 확인하세요.

사용 가능한 원격 제공자 주소가 있다면 type: http로 바꾸고 출처마다 url과 로컬 캐시 경로를 지정하세요. interval은 각 출처의 업데이트 주기에 맞춥니다. 구독 링크에 접근 자격 증명이 포함될 수 있으므로 로컬에서 관리하는 설정이나 클라이언트 저장소에 보관하세요. 공개 저장소나 온라인 변환 서비스에 올리거나 스크린샷에 노출하지 마세요. 출처 하나가 실패하면 먼저 어느 용도 그룹에 영향을 주는지 확인하세요. 모든 그룹을 다른 출구로 바꿔 출처 문제를 덮지 마세요.

병합 순서와 최종 적용 파일 확인

맵과 목록은 서로 다른 병합 대상입니다. dns를 오버라이드할 때 어떤 구현은 맵 전체를 교체해 기존 도메인 정책까지 제거할 수 있고, 다른 구현은 필드별로 병합해 기존 업스트림을 남길 수 있습니다. rules 목록을 추가할 때 새 규칙이 기존 MATCH 뒤에 놓이면 매칭되지 않습니다. 편집 전에 전체 교체인지, 앞에 추가하는지, 특정 항목 앞에 삽입하는지 명확히 정하세요. 생성 후에는 편집기에서 저장됐는지만 보지 말고 최종 파일을 확인하세요.

그룹 이름과 규칙 세트 이름을 고정해 여러 설정 항목에서 참조할 때 일관되게 사용하세요. 그룹 이름을 바꾸면 규칙의 출구와 다른 그룹의 참조를 확인하세요. 규칙 제공자 이름을 바꿨다면 RULE-SET과 해당 세트를 사용하는 조회 정책도 확인해야 합니다. 이름이 같은 항목이 있으면 어느 정의를 유지할지 먼저 정하고, 병합기가 중복 키를 우연히 처리하는 방식에 기대지 마세요. YAML을 편집기에서 읽을 수 있어도 코어가 받은 구조는 예상과 다를 수 있습니다.

독립 실행형 mihomo 바이너리를 사용한다면 설정을 불러오기 전에 구문 검사를 실행할 수 있습니다. 아래 명령은 설정과 제공자 상대 경로가 있는 작업 디렉터리로 이동했고 로컬에 코어 명령이 설치된 환경을 전제로 합니다. 클라이언트가 코어를 관리한다면 클라이언트 자체 검사나 로그 기능을 우선 사용하세요. 테스트 파일과 실제로 실행되는 파일이 다르지 않도록 최종 설정을 동일한 코어로 확인하세요.

mihomo -t -d . -f ./config.yaml

설정 검사가 통과됐다는 것은 현재 설정을 코어가 받아들일 수 있다는 뜻일 뿐, 원격 파일에 접근할 수 있거나 모든 그룹에 후보가 있거나 업무 트래픽이 올바르게 분기된다는 보장은 아닙니다. 실제로 불러온 뒤 업무용, 개인용, 기본 처리 연결을 각각 발생시켜 제공자 로딩 상태와 매칭 규칙, 출구를 확인하세요. 구독 새로고침을 한 번 실행한 뒤 같은 테스트를 반복하세요. 새로고침 후에도 로컬 변경 사항과 참조가 유지되어야 오버라이드 위치가 적절하다고 볼 수 있습니다. 테스트 입력과 예상 결과를 로컬 운영 기록에 남겨 두세요.

업데이트 후 그룹 하나만 작동하지 않는다면 해당 출처에서 이름이 바뀌거나 목록이 비었거나 항목 형식이 변경됐는지 확인한 다음 조합 로직을 점검하세요. 모든 그룹에 문제가 생겼다면 잘못된 기본 구독을 불러왔는지, 클라이언트 업데이트로 오버라이드 적용 범위가 달라졌는지 먼저 확인하세요. 롤백할 때는 마지막으로 정상 작동한 기본 설정과 해당 제공자 파일을 복원하고 규칙 대상이 여전히 존재하는지 확인한 뒤 출처를 하나씩 복구하세요. 장기적으로 관리하기 좋은 해결책은 어떤 입력이 바뀌었는지 추적할 수 있는 것이지, 한 번 수동으로 고치고 재현 조건을 잃는 것이 아닙니다.

외부 컨트롤러와 실행 상태

외부 컨트롤러는 코어의 관리 인터페이스이며 프록시 트래픽이 들어오는 포트가 아닙니다. UI는 컨트롤러를 통해 연결과 규칙, 그룹 상태를 읽고 그룹 선택 변경이나 연결 종료, 설정 조정을 수행할 수 있습니다. 컨트롤러 포트는 mixed-port나 DNS 수신 포트와 역할이 다릅니다. 클라이언트 내장 UI로 충분하다면 별도의 수신 포트를 열 필요가 없습니다. 별도 관리 인터페이스가 필요하다면 기본적으로 루프백 주소에 바인딩하고 로컬에만 저장하는 별도의 강력한 인증 키를 사용하세요.

루프백 주소에 바인딩하고 별도 인증 설정

컨트롤러 설정을 최상위 항목에 병합하세요. 클라이언트가 이미 컨트롤 포트를 관리한다면 현재 수신 주소를 확인해 같은 기기의 여러 코어 인스턴스가 포트를 두고 충돌하지 않도록 하세요. 아래 키는 재사용하면 안 된다는 점을 보여 주기 위한 예시일 뿐입니다. 실행 전에 이 기기에서 별도의 무작위 값으로 바꾸세요. allow-lan: false는 일반 프록시 입구의 LAN 사용을 제한하지만 컨트롤러의 루프백 바인딩과 인증 설정을 대신하지는 않습니다.

external-controller: 127.0.0.1:9090
secret: "replace-with-local-random-value"
allow-lan: false

별도 UI가 로컬 정적 리소스로 제공된다면 사용하는 코어의 방식에 맞게 external-ui를 설정하고 신뢰할 수 있으며 이 기기에서 관리하는 UI 디렉터리를 지정하세요. 컨트롤러가 UI를 제공한다면 보통 같은 컨트롤 서비스의 /ui/에서 열 수 있어 브라우저의 교차 출처 문제를 줄일 수 있습니다. UI 파일이 배포되지 않은 경우 컨트롤 API가 정상이라고 해서 UI 경로도 사용할 수 있는 것은 아닙니다. 마찬가지로 UI 페이지가 열린다고 API 인증까지 통과했다는 뜻은 아닙니다. 두 항목을 따로 확인하세요.

아래 명령은 Bash와 curl을 사용할 수 있는 환경에서 실행 중인 코어와 같은 기기에서 인증된 읽기 전용 요청을 보냅니다. 키는 대화형으로 입력하며 명령문이나 스크립트 파일에는 쓰지 않습니다. 실행 전에 셸 추적이 켜져 있지 않은지 확인하고 터미널 녹화 영상이나 요청 헤더를 다른 사람에게 보내지 마세요. 클라이언트 내장 UI를 사용하는 경우 클라이언트가 제공하는 연결 진단으로 명령을 대신할 수 있습니다.

read -rsp '컨트롤러 키: ' controller_secret
printf '\n'
printf 'header = "Authorization: Bearer %s"\n' "$controller_secret" |
  curl --fail --silent --show-error --config - \
    http://127.0.0.1:9090/version
unset controller_secret

UI, 수신 포트, 실제 설정 구분

증상먼저 확인할 항목먼저 변경하지 말 것
연결 거부됨서비스가 실행 중인지, 주소와 포트가 현재 인스턴스와 일치하는지규칙 순서와 DNS
인증되지 않음 응답현재 키와 UI 연결 설정이 일치하는지수신 범위
API는 정상이지만 UI가 비어 있음UI 리소스, 브라우저 보안 제한, UI에 설정된 API 주소코어 출구 정책
UI에 데이터가 표시되지만 예상한 인스턴스가 아님실제 연결 주소, 설정 파일, 백그라운드 서비스 소속모델과 무관한 기타 그룹 매개변수

로컬 인터페이스에서 인증되지 않음 응답이 나오면 먼저 다른 백그라운드 인스턴스에 연결한 것은 아닌지 확인한 뒤 키를 다시 입력하세요. 문제를 해결하려고 인증을 제거하지 마세요. 명령은 접근되지만 브라우저에서 교차 출처 또는 혼합 콘텐츠 오류가 발생한다면 동일 출처의 로컬 UI로 다시 테스트하세요. 웹 스크립트의 보안 제한은 브라우저의 보호 기능입니다. 제한을 끄거나 모든 사이트에 접근을 허용하는 것은 해결책이 아닙니다. 특히 출처를 알 수 없는 UI를 열 때는 이 페이지에 로컬 관리 자격 증명을 입력하지 마세요.

컨트롤러를 모든 인터페이스에 바인딩하거나 포트를 공개 인터넷으로 전달하지 마세요. 원격 관리가 꼭 필요하다면 조직에서 이미 관리하는 보안 원격 데스크톱이나 관리 채널을 사용하고, 기기의 로컬 세션에서 UI를 여는 방식을 우선하세요. 네트워크 입구에 접근 제한이 있어도 컨트롤러 자체 인증은 유지해야 합니다. 여러 사람이 같은 기기를 사용하는 경우 설정 파일의 접근 권한을 제한하세요. 다른 프로세스나 계정이 읽을 수 있는 공유 디렉터리에 키와 일반 프록시 포트를 함께 저장하지 마세요.

업무 문제를 해결할 때는 UI에서 반복해서 선택을 바꾸기보다 상태를 먼저 관찰하세요. 새 연결 하나의 대상과 프로토콜, 매칭 규칙, 실제 정책 경로를 기록한 다음 해당 절에서 변수 하나만 조정하세요. 프록시 그룹을 바꿨다면 테스트 연결을 새로 만드세요. 이전 세션은 기존 출구를 계속 사용할 수 있습니다. UI에서만 적용되고 재시작하면 사라지는 변경 사항은 실행 중 선택인지, 클라이언트가 저장한 기본 설정인지, 로컬 기본 설정에 저장된 변경 사항인지 확인하세요. 이 세 가지는 서로 다릅니다.

로그도 필요한 범위에서만 활성화하세요. 로딩 실패나 도메인 식별 문제를 찾을 때는 잠시 상세도를 높일 수 있습니다. 문제가 재현된 뒤에는 원래 수준으로 되돌려 연결 대상과 개인 사용 기록이 장기간 쌓이지 않도록 하세요. 외부에 도움을 요청할 때는 오류 유형과 민감한 정보를 가린 관련 설정만 공유하면 됩니다. 전체 실행 설정을 넘길 필요는 없습니다. UI에 노드와 규칙이 보인다는 것은 관리 인터페이스에서 상태를 읽을 수 있다는 뜻일 뿐입니다. 프록시가 실제로 작동하는지는 연결 기록과 재현 가능한 요청으로 확인해야 합니다.

마지막 검증은 정해진 순서로 진행하세요. 앱 트래픽이 코어에 들어오는지 확인하고, 필요한 도메인을 조회하거나 식별할 수 있는지 확인한 다음, 예상 규칙에 매칭되는지와 그룹에서 사용 가능한 출구를 선택했는지 확인하세요. 마지막으로 구독을 새로고침하고 설정을 다시 불러온 뒤 핵심 시나리오 하나 이상이 그대로 작동하는지 확인하세요. 기본 연결 자체가 되지 않는다면 사용 가이드로 돌아가 구독 가져오기와 연결을 다시 점검하세요. 시스템 프록시나 권한, 포트 문제라면 자주 묻는 질문부터 확인하세요. 설정 전체를 한 번에 바꿀 필요는 없습니다.

Clash 다운로드