Clash 설정 파일
참고 가이드

01 · YAML 구조와 설정 진입점

Clash 설정 파일은 일반적으로 YAML 형식입니다. 줄마다 실행되는 스크립트가 아니라 계층 구조를 가진 데이터입니다. 최상위 키는 코어의 동작을 지정하고, 중첩된 매핑에는 기능별 매개변수가, 목록에는 여러 노드·정책 그룹·규칙이 담깁니다. 읽을 때는 먼저 왼쪽 경계에 맞춰진 필드를 찾고, 아래쪽에서 해당 필드에 속한 내용을 확인하세요. 줄이 가까이 있다는 이유만으로 서로 종속된다고 판단하면 안 됩니다.

매핑, 목록, 들여쓰기

매핑은 콜론으로 키와 값을 구분하며, 콜론 뒤에는 보통 공백을 하나 둡니다. 목록 항목은 하이픈으로 시작합니다. 들여쓰기는 공백만 사용하고 탭은 섞지 마세요. 이 문서에서는 관리하기 쉬운 관례로 두 칸 들여쓰기를 사용합니다. 들여쓰기 폭은 필드 이름의 일부가 아닙니다. 같은 계층의 항목은 줄을 맞추세요. 특히 노드 목록의 두 번째 노드와 첫 번째 노드에 포함된 추가 매개변수를 구분해야 합니다.

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

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

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

여기서 proxy-groups는 목록이며, 첫 번째 항목에는 이름, 유형, 선택 가능한 출구가 들어갑니다. 그 안의 proxies도 목록입니다. 최상위 proxies는 프록시 노드 정의를 뜻하지만, 그룹 내부의 같은 필드는 어떤 출구를 참조할지 나타냅니다. 의미는 계층에 따라 달라집니다. 그룹 내부 참조를 최상위에 잘못 배치하면 텍스트가 파싱되더라도 유형 또는 참조 오류가 발생할 수 있습니다.

문자열, 불리언, 중복 키

포트는 보통 정수로, 스위치 값은 true 또는 false로 작성합니다. 비밀번호, 도메인, 노드 이름 등은 문자열로 처리합니다. 샵 기호나 콜론 뒤 공백처럼 해석이 모호해질 수 있는 내용은 따옴표로 감싸는 편이 좋습니다. 샵 기호는 위치에 따라 주석으로 처리되므로 따옴표로 감싸지 않은 비밀번호가 잘릴 수 있습니다. 큰따옴표는 이스케이프 문자를 처리합니다. 일반 텍스트에는 역슬래시로 인한 혼동을 줄일 수 있도록 작은따옴표를 우선 사용하세요.

같은 매핑에서 동일한 키를 중복 정의하지 마세요. 예를 들어 파일 앞부분에 dns를 작성하고 끝부분에 다시 dns를 추가해도 두 블록이 반드시 병합되는 것은 아닙니다. 파서는 중복 키를 거부하거나 그중 하나만 남길 수 있습니다. 하위 필드를 추가하려면 기존 블록으로 돌아가 수정하세요. 목록은 여러 줄로 작성하거나 대괄호 형식으로 쓸 수 있지만, 문제를 찾을 때는 여러 줄로 쓰는 편이 소속 관계를 파악하기 쉽습니다.

원본 파일과 실행 파일의 차이

데스크톱 클라이언트에는 구독 원본, 편집용 사본, 오버라이드 규칙, 코어에 전달되는 실행 설정이 함께 존재하는 경우가 많습니다. 편집기에서 저장에 성공했다는 것은 해당 파일에 변경 사항이 기록됐다는 뜻일 뿐입니다. 실제 적용 여부는 클라이언트가 그 파일을 사용하는지, 이후 생성 과정에서 수정 사항이 덮어쓰이지 않는지에 달려 있습니다. 문제를 해결할 때는 먼저 현재 활성화된 설정 이름을 확인하고 실행 설정이나 코어 로그를 살펴보세요. 선택되지 않은 사본을 계속 수정하는 일을 피할 수 있습니다.

명령줄에서 mihomo를 실행한다면 mihomo -t -f ./config.yaml로 설정을 검사할 수 있습니다. 명령에 사용하는 실행 파일 이름과 경로는 실제 설치 위치에 맞게 조정하세요. 테스트 통과는 주로 구조와 일부 참조가 허용됐다는 뜻입니다. 원격 서버에 연결할 수 있다거나 모든 규칙이 기대대로 작동한다는 뜻은 아닙니다. 클라이언트 내장 테스트와 터미널 명령이 서로 다른 코어를 사용할 수도 있으니 실제로 불러오는 설정을 확인하세요.

복구할 수 있는 기준 설정을 마련해 두는 것이 중요합니다. 원본 파일을 보관하고, 매번 한 기능 블록만 수정하며 변경 목적을 기록하세요. 오류가 생기면 이번 변경을 되돌린 다음 항목별로 다시 추가하세요. DNS, TUN, 규칙 순서를 한꺼번에 조정하면 연결 실패의 원인이 무엇인지 파악하기 어렵습니다. 처음 구독을 가져오는 것이 목적이라면 먼저 구독 가져오기 안내를 따라 설정한 뒤, 다시 돌아와 설정을 확장하세요.

02 · 포트, 모드, 공통 설정

공통 설정은 코어가 연결을 받는 방식, 연결 진입점을 공개할 대상, 출구 선택 모드를 제어합니다. 최상위 설정이므로 파일의 앞이나 뒤에 적는다고 의미가 달라지지는 않습니다. 처음 조정할 때는 수신 범위를 최소화하고 이 기기의 앱만 프록시를 사용하도록 설정하세요. 연결이 정상인지 확인한 다음 로컬 네트워크 접근, 제어 인터페이스, 기타 접속 방식을 검토하세요. 기능을 더 많이 켤수록 문제 해결 시 확인해야 할 경계도 늘어납니다.

프록시 포트와 수신 주소

port는 HTTP 프록시 진입점을 제공하고, socks-port는 SOCKS 진입점을 제공합니다. mixed-port는 한 포트에서 두 유형의 프록시 요청을 모두 받습니다. 일반적인 데스크톱 사용이라면 혼합 포트 하나부터 설정해도 됩니다. 포트 값은 정해진 답이 아닙니다. 이 기기에서 실제로 사용 가능한 포트인지, 앱에 설정한 프록시 주소와 일치하는지 확인하세요. 값을 다른 숫자로 바꿔도 기존 주소가 새 포트로 자동 변경되지는 않습니다.

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
ipv6: false

위 예제는 이 기기에서 사용하는 설정입니다. 앱에 프록시 주소를 직접 입력한다면 주소에는 127.0.0.1, 포트에는 해당 값을 사용하세요. 주소가 이미 사용 중이라는 오류가 나면 두 번째 클라이언트나 다른 코어 프로세스가 실행 중인지 먼저 확인한 뒤, 충돌하는 프로그램을 종료할지 포트를 바꿀지 결정하세요. 계속 재시작하는 것만으로는 포트 충돌을 해결하기 어렵고, 백그라운드 프로세스만 더 구분하기 어려워질 수 있습니다.

allow-lan과 bind-address는 함께 살펴봐야 합니다. 첫 번째는 로컬 네트워크 접근을 허용할지, 두 번째는 어떤 주소에서 수신할지를 지정합니다. 운영체제 방화벽의 영향도 받습니다. 로컬 네트워크 허용만 켠다고 다른 기기에서 반드시 접속할 수 있는 것은 아닙니다. 공유가 꼭 필요하다면 적절한 인증과 접근 범위도 설정해 신뢰할 수 있는 네트워크에서만 사용해야 할 프록시 진입점이 공용 네트워크에 노출되지 않도록 하세요.

규칙, 전역, 직접 연결 모드

mode: rule은 규칙 목록에 따라 출구를 선택합니다. 전역 모드에서는 전역으로 선택한 출구를 사용하고, 직접 연결 모드에서는 일반 프록시 규칙에 따라 원격 프록시를 선택하지 않습니다. 전역 모드라고 해서 기기의 모든 트래픽을 가로채는 것은 아닙니다. 코어에 들어온 연결에만 영향을 줍니다. 시스템 프록시를 설정하지 않았거나 앱별 프록시를 별도로 구성하지 않았고 TUN으로도 가로채지 않은 프로그램은 코어를 전혀 거치지 않을 수 있습니다.

클라이언트 인터페이스의 모드 버튼은 제어 인터페이스를 통해 실행 상태를 즉시 바꿀 수 있지만, 원본 파일의 mode 값은 그대로일 수 있습니다. 따라서 파일을 수정했는데도 인터페이스가 전역 모드로 표시된다면 클라이언트가 이전 선택을 복원했는지, 별도의 설정 항목이 우선 적용되는지 확인하세요. 규칙이 적용되지 않는 문제를 해결하기 전에 실제 실행 모드가 규칙 모드인지 확인하세요. 잘못된 전제에서 전체 규칙 목록을 조정하는 일을 피할 수 있습니다.

로그, 제어 인터페이스, 상태 유지

log-level은 보통 info를 사용하고, 세부 내용을 확인할 때만 잠시 debug로 높입니다. 상세 로그에는 접속한 도메인, 노드 이름, 로컬 주소가 포함될 수 있으므로 공유 전에 민감한 내용을 삭제하세요. 제어 인터페이스와 프록시 포트의 용도는 다릅니다. 전자는 코어를 관리하고 후자는 앱 연결을 전달합니다. 브라우저의 HTTP 프록시 설정에 관리 포트를 입력하지 말고, 연결 문제를 해결하려고 관리 인터페이스의 수신 범위를 넓히지도 마세요.

제어 인터페이스가 필요하다면 루프백 주소로 제한하고 충분히 강력한 secret을 설정하세요. 실제 키는 본인 기기에만 보관해야 합니다. 일부 클라이언트는 이 필드를 직접 생성하고 관리하므로 수동 오버라이드로 인해 인터페이스가 코어에 연결되지 않을 수 있습니다. 클라이언트 설정과 코어 파일에 모두 관련된 옵션은 클라이언트가 제공하는 설정 화면을 우선 사용하고, 실행 설정에서 결과를 확인하세요.

상태 유지 설정도 관찰 결과에 영향을 줍니다. 예를 들어 정책 그룹 선택 상태 저장을 켜면 설정을 다시 불러올 때 목록의 첫 번째 노드가 아니라 이전에 선택한 노드가 복원될 수 있습니다. 적용 여부를 판단하려면 실행 모드, 정책 그룹의 현재 선택, 연결 기록을 함께 확인하세요. 파일에서 가장 위에 있는 이름만 봐서는 안 됩니다. 포트 충돌이나 남아 있는 시스템 프록시 문제는 도움말 센터에서도 확인할 수 있습니다.

03 · DNS, Fake-IP, 해석 경로

DNS 설정은 도메인을 주소로 변환하는 방식을 정하며, 규칙 매칭에 사용할 도메인 정보를 코어가 보존할 수 있는지에도 영향을 줍니다. 다음 세 가지를 구분해야 합니다. 앱이 누구에게 질의를 보내는지, 코어가 받은 질의를 어떤 상위 DNS 서버로 전달하는지, 원격 노드에 연결할 때 노드 서버의 도메인을 누가 해석하는지입니다. 세 경로는 서로 다를 수 있으므로 브라우저가 웹사이트 주소를 확인했다고 해서 프록시 서버 도메인도 정상적으로 해석됐다고 볼 수는 없습니다.

기본 필드와 상위 DNS 서버의 역할

dns.enable은 내장 DNS를 활성화하고 listen은 수신 주소와 포트를 지정합니다. 수신이 정상적으로 시작됐다고 해서 운영체제가 이를 사용하기 시작한 것은 아닙니다. 클라이언트나 시스템 네트워크 설정에서 질의를 해당 진입점으로 보내야 합니다. 이 문서의 예제는 시스템의 기존 DNS 서비스와 구분하기 쉽도록 루프백 주소의 일반 포트를 사용합니다. 실제 사용 포트는 트래픽 가로채기 방식과 권한 조건에 따라 결정하세요.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - '*.lan'
    - '*.local'

nameserver는 일반적인 상위 DNS 서버이며 일반 DNS나 지원되는 암호화 DNS 주소를 설정할 수 있습니다. 암호화 DNS 서버가 도메인 이름을 사용한다면 코어가 먼저 해당 주소를 알아야 하며, default-nameserver가 이 초기 해석을 담당할 수 있습니다. 아직 구축되지 않은 동일한 연결에 의존해야만 접근할 수 있는 주소를 초기 해석 서버로 지정하면, 프록시 연결과 DNS 해석 중 무엇이 먼저인지 순환 의존성이 생길 수 있습니다.

proxy-server-nameserver는 프록시 서버 도메인을 해석하는 설정으로, 노드 주소 해석과 일반 웹 페이지 해석을 분리할 때 유용합니다. 설정한 뒤에도 현재 네트워크에서 해당 DNS 서버에 접근할 수 있어야 합니다. 로그에 노드 서버를 해석할 수 없다고 표시되면 노드 도메인과 이곳의 상위 DNS 서버부터 확인하세요. 웹 도메인 필터 목록에 항목을 무작정 추가하지 마세요. 해석 대상에 따라 수정해야 할 위치가 다릅니다.

Fake-IP와 실제 주소 해석

Fake-IP 모드에서는 도메인에 예약 주소를 할당하고 코어에 도메인과 주소의 매핑을 저장합니다. 앱이 해당 주소로 연결하면 코어가 도메인을 찾아 규칙에 따라 출구를 선택할 수 있습니다. 이 예약 주소는 원격 웹사이트의 실제 공인 주소가 아닙니다. 해당 주소가 보인다고 웹사이트 DNS가 잘못 수정됐다는 뜻은 아닙니다. 이 원리를 이해하면 정상적인 매핑 현상을 비정상적인 해석으로 오해하지 않을 수 있습니다.

반면 redir-host는 앱에 실제로 해석된 주소를 반환하는 방식에 더 가깝습니다. 다만 도메인 정보를 온전히 연결할 수 있는지는 연결이 코어에 들어오는 경로와 다른 식별 방식에도 달려 있습니다. 모든 환경에 동일하게 적용할 수 있는 우열은 없습니다. 일부 로컬 네트워크 서비스, 실제 주소를 이용해 기기를 찾는 앱, 특수한 네트워크 검사 로직은 실제 주소 응답이 필요할 수 있습니다. 이 경우 모든 상위 DNS 서버를 일괄 변경하기보다 필요한 항목을 따로 조정하세요.

필터, 트래픽 분기, 문제 해결

확인된 문제를 해결하는 데 필요한 필터 항목만 추가하세요. 예제의 로컬 네트워크 접미사는 일반적인 방법일 뿐 모든 네트워크에 적합한 것은 아닙니다. 라우터에서 자체 내부 도메인을 사용한다면 해당 도메인에 응답할 수 있는 로컬 DNS 서버로 질의가 전달되도록 해야 합니다. 내부 도메인을 필터에 추가한다고 공용 DNS가 해당 레코드를 자동으로 알아내지는 않습니다. 문제를 찾을 때는 필터 결과와 실제 사용된 상위 DNS 서버를 함께 확인하세요.

도메인별로 상위 DNS 서버를 지정하려면 nameserver-policy를 살펴볼 수 있습니다. DNS 연결에 라우팅 규칙을 적용하려면 respect-rules와 노드 도메인 해석 설정을 함께 검토하세요. 이 설정은 질의 결과뿐 아니라 DNS 트래픽의 경로도 바꿉니다. 사용 전에 의존 관계를 정리하고, 특히 프록시 연결에 필요한 DNS 해석이 아직 구축되지 않은 프록시 연결에 다시 의존하지 않도록 주의하세요.

DNS를 테스트할 때는 먼저 ‘응답이 없음’, ‘주소는 반환되지만 연결 실패’, ‘특정 앱만 실패’를 구분하세요. 첫 번째는 수신, 트래픽 가로채기, 상위 DNS 서버 연결을 확인합니다. 두 번째는 규칙, 출구, IPv6를 추가로 살펴봅니다. 세 번째는 앱 캐시, 내장 암호화 DNS, 시스템 DNS를 우회하는 경로를 확인하세요. 주소 매핑 방식을 바꾼 뒤에도 기존 연결과 캐시는 이전 결과를 계속 사용할 수 있으므로 새 연결을 만들어 다시 테스트하세요.

최상위 ipv6와 dns.ipv6는 서로 다른 설정입니다. 각각 코어 전반의 IPv6 동작과 DNS의 IPv6 응답 처리를 다룹니다. 하나를 끈다고 시스템의 모든 IPv6 트래픽이 적절히 처리되는 것은 아닙니다. 예약 주소 매핑과 필터 범위에 대한 자세한 내용은 Fake-IP 모드 상세 설명을 참고한 뒤 실제 네트워크에 맞게 설정하세요.

04 · 프록시 노드 필드와 제공자

프록시 노드 정의는 코어가 원격 서버에 연결하는 방식을 설명합니다. 노드와 정책 그룹은 다릅니다. 노드에는 프로토콜, 서버, 인증 매개변수가 들어가고 정책 그룹은 출구를 모아 선택합니다. 노드 설정이 문법 검사에 통과해도 인증 정보가 맞지 않거나 서버에 접근할 수 없거나 전송 매개변수가 잘못되면 연결되지 않을 수 있습니다. 문제를 찾을 때는 복잡한 정책 그룹에 넣기 전에 개별 노드가 작동하는지 먼저 확인하세요. 선택 로직이 판단을 방해하지 않도록 할 수 있습니다.

이름, 프로토콜, 서버 매개변수

일반적인 공통 필드로는 name, type, server, port가 있습니다. 이름은 그룹과 규칙에서 참조하므로 알아보기 쉽고 고유하게 정하세요. 프로토콜 유형은 서버와 일치해야 합니다. 서버 값은 주소나 도메인일 수 있으며 포트는 원격 서비스가 실제로 수신하는 포트여야 합니다. 로컬 혼합 프록시 포트와 원격 노드 포트는 서로 다른 양쪽의 포트입니다. 값이 다르다고 억지로 같게 바꾸지 마세요.

proxies:
  - name: SS-DEMO
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: 'your-password'
    udp: true

이 예제는 필드 형식을 보여주기 위한 것으로, 도메인과 비밀번호는 설명용 가짜 값이며 원격 연결에 바로 사용할 수 없습니다. 실제 매개변수는 사용할 권한이 있는 서버 설정을 기준으로 해야 합니다. 웹 페이지에 접속할 수 있다고 프록시 포트도 작동한다고 추측하지 말고, HTTPS에 흔히 쓰이는 포트라는 이유만으로 TLS를 임의로 추가하지 마세요. 암호화 방식, 비밀번호, 프로토콜 유형은 서로 맞아야 합니다. 필드 하나만 잘못돼도 시간 초과나 핸드셰이크 실패가 발생할 수 있습니다.

필드 지원 범위는 클라이언트 이름만으로 결정되지 않으며 실제 코어에 따라 달라집니다. 같은 인터페이스를 제공하는 제품도 빌드에 따라 지원하는 코어 기능이 다를 수 있습니다. 오래된 설정의 프로토콜이 최신 예제와 호환되지 않을 수도 있습니다. 알 수 없는 프로토콜이나 필드가 나오면 설정을 바꾸기 전에 현재 실행 중인 코어와 문서를 확인하세요. 버전별 차이는 mihomo와 원본 버전의 기능 차이를 참고하세요.

TLS, 전송 계층, UDP

TLS를 사용하는 프로토콜에서는 서버 주소, 인증서 검증 이름, 전송 계층의 호스트 필드가 각각 다른 역할을 할 수 있습니다. servername은 일반적으로 TLS 핸드셰이크의 이름과 관련이 있고, WebSocket 경로와 요청 헤더는 전송 계층에 속합니다. 구독 설정에 있는 모든 도메인을 같은 값으로 바꾸거나, 어떤 필드가 중복돼 보인다는 이유만으로 삭제해서는 안 됩니다. 서버의 실제 설정에 맞춰 하나씩 확인하세요.

인증서 검증 건너뛰기를 일반적인 해결책으로 사용하지 마세요. 인증서 오류가 나면 먼저 기기 시간, 서버 이름, 인증서 유효성, 잘못된 포트에 연결했는지 확인하세요. 검증을 끄면 보안 경계가 달라지고 잘못된 서버나 설정 불일치가 일시적으로 가려질 수 있습니다. 구체적인 테스트 환경과 위험을 이해하는 경우에만 이런 설정을 검토하고, 일상적인 설정에서는 적절한 검증 절차를 유지하세요.

udp: true는 해당 노드가 관련 UDP 요청을 처리하도록 허용한다는 뜻입니다. 서버, 프로토콜 구현, 전체 네트워크 경로가 모두 UDP를 지원한다는 보장은 없습니다. HTTP 프록시를 통한 일반 브라우저 요청으로 UDP를 테스트할 수도 없습니다. 음성 통화, 게임, 일부 DNS 요청에 문제가 있다면 스위치가 켜져 있는지만 보지 말고 앱이 코어에 연결되는 방식, 노드의 전송 지원 여부, 서버 방화벽의 허용 여부를 확인하세요.

프록시 제공자와 상태 확인

proxy-providers를 사용하면 노드 목록을 주 설정 파일에서 분리할 수 있습니다. 파일 제공자는 로컬 파일을 읽고, HTTP 제공자는 지정한 주소에서 내용을 가져옵니다. 주 설정의 정책 그룹에서는 use로 제공자를 참조합니다. 이 방식으로 노드를 업데이트할 때 전체 규칙을 수정하지 않아도 됩니다. 다만 제공자 파일에는 자체 구조가 필요하므로, 모드·규칙·DNS가 포함된 전체 구독을 모든 제공자 형식에 그대로 사용할 수는 없습니다.

proxy-providers:
  local-nodes:
    type: file
    path: ./providers/local-nodes.yaml

proxy-groups:
  - name: PROXY
    type: select
    use:
      - local-nodes

위 예제는 실제로 존재하는 로컬 파일을 사용합니다. 파일에는 proxies 목록과 유효한 노드가 포함돼야 합니다. 상대 경로는 코어의 작업 디렉터리를 기준으로 해석되며 편집기에서 현재 열려 있는 파일의 디렉터리와 다를 수 있습니다. 로그에 파일을 찾을 수 없다고 나오면 클라이언트의 작업 디렉터리와 접근 권한을 먼저 확인한 뒤 경로를 수정하세요. 경로 문제를 감추려고 모든 노드를 주 설정에 직접 복사할 필요는 없습니다.

상태 확인 기능은 선택된 출구에서 접속할 테스트 주소가 필요합니다. 측정 결과는 해당 경로에서 테스트 대상에 접속했을 때의 상태를 나타낼 뿐 인터넷 전체의 품질을 보장하지 않습니다. 실패 원인은 대상 제한, DNS, 시간 초과, 노드 문제일 수 있습니다. 구독 주소에는 접속 인증 정보가 포함되는 경우가 많으므로 전체 링크를 공개 로그나 스크린샷에 올리지 마세요. 설정을 공유할 때는 구조를 유지하고 비밀번호, 구독 매개변수 등 식별 정보를 바꾸세요.

05 · 정책 그룹, 참조, 선택 상태

정책 그룹은 여러 출구를 규칙에서 참조할 수 있는 하나의 이름으로 묶습니다. 규칙이 연결을 그룹으로 보내면 그룹은 현재 선택이나 테스트 로직에 따라 실제 노드를 결정합니다. 그룹 이름이 PROXY라고 해서 반드시 원격 프록시를 사용하는 것은 아닙니다. 이름이 DIRECT인 사용자 정의 그룹도 내장 직접 연결 출구와 혼동하지 마세요. 이름의 문자 그대로의 의미를 추측하기보다 참조 관계를 기준으로 동작을 판단해야 합니다.

수동 선택과 전체 참조

select는 사용자가 직접 선택하는 그룹으로, 선택권을 사용자에게 맡길 때 적합합니다. 그룹의 proxies에는 기존 노드, 다른 그룹, 지원되는 내장 출구를 나열할 수 있으며 use는 제공자를 참조합니다. 이름은 완전히 일치해야 하므로 공백, 대소문자, 한글 문장부호를 확인하세요. 노드 이름을 바꿀 때는 모든 참조 위치도 함께 확인해야 합니다. 파일 문법은 올바르지만 코어가 대상을 찾지 못하는 오류가 생길 수 있습니다.

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

  - name: MEDIA
    type: select
    proxies:
      - PROXY
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,MEDIA
  - MATCH,PROXY

이 예제는 구조를 보여주기 위해 직접 연결과 그룹 간 참조만 사용하며 실제 프록시 노드는 포함하지 않습니다. 예시 도메인에 접속하면 먼저 MEDIA 그룹으로 전달됩니다. MEDIA에서 PROXY를 선택했다면 PROXY의 현재 선택된 출구를 계속 사용합니다. 그룹은 계층적으로 구성할 수 있지만 순환 참조는 피해야 합니다. 예를 들어 A 그룹이 B 그룹을 참조하고 B 그룹이 다시 A 그룹을 참조하면 출구 결정 경로가 끊깁니다. 이를 양방향 대체 설정으로 사용할 수는 없습니다.

자동 테스트와 장애 조치

url-test는 테스트 결과에 따라 출구를 선택하며 자동 선택에 주로 사용합니다. fallback은 후보 순서에 따라 사용 가능한 항목을 찾는 데 중점을 둡니다. load-balance는 지원되는 방식에 따라 연결을 분산합니다. 서로 같은 기능을 하는 세 가지 표기법이 아닙니다. 우선순위를 안정적으로 유지하려면 테스트 결과를 계속 따라가는 것보다 장애 조치 그룹이 동작을 설명하기 쉽습니다. 업무별 출구를 수동으로 고정하고 싶다면 바깥에 선택 그룹을 추가할 수 있습니다.

자동 그룹에는 테스트 주소와 검사 간격 등의 설정이 필요한 경우가 많습니다. 네트워크 환경에 맞는 주소를 선택하고 예상한 응답이 안정적으로 돌아오는지 확인하세요. 테스트 결과는 해당 대상까지의 경로만 보여주며 모든 서비스의 속도 순위로 볼 수는 없습니다. 일부 노드는 테스트 사이트에는 빠르게 연결되더라도 장시간 연결, 스트리밍 등 다른 대상에는 적합하지 않을 수 있습니다. 자동 테스트 결과와 실제 서비스 사용 경험을 함께 고려하세요.

검사 간격은 짧을수록 좋은 것이 아닙니다. 너무 짧으면 요청이 늘고 기기가 자주 깨어날 수 있으므로 특히 모바일 기기에서는 백그라운드 제한을 고려해야 합니다. 일부 검사 방식은 필요할 때만 확인할 수 있어 오래 사용하지 않은 그룹의 결과가 계속 갱신되지 않을 수도 있습니다. 검사 상태가 오래된 것처럼 보이면 노드에 문제가 있다고 판단하기 전에 해당 그룹에서 실제로 검사가 실행됐는지 확인하세요.

선택 상태 유지와 업무별 그룹

미디어, 개발 도구 등 용도별 그룹을 만들고 각 규칙에서 해당 그룹을 참조할 수 있습니다. 이렇게 계층을 나누면 ‘어떤 요청이 어떤 종류인지’와 ‘해당 요청이 어떤 출구를 사용할지’를 분리할 수 있어 노드가 바뀌어도 모든 도메인 규칙을 다시 작성할 필요가 없습니다. 그룹을 지나치게 세분화하면 사용자가 관리할 선택 상태가 많아지고, 연결 하나를 확인할 때 여러 단계의 참조를 거쳐야 하므로 오히려 구조가 복잡해집니다.

profile:
  store-selected: true

선택 상태를 저장하면 재시작이나 다시 불러오기 후 이전 상태가 복원될 수 있습니다. 노드 순서를 바꿔도 현재 선택이 달라지지 않을 수 있으며 그룹 이름을 바꾸면 이전 상태와 연결되지 않을 수도 있습니다. 새로운 기본 순서를 테스트할 때는 저장된 상태와 클라이언트가 별도로 보관하는 선택값을 함께 확인하세요. 노드를 첫 번째 항목으로 옮기기만 하면 설치된 모든 클라이언트가 다음번에 그 노드를 사용한다고 기대해서는 안 됩니다.

정책 그룹 표시가 이상하다면 이름 정의, 참조 출처, 후보 목록, 현재 선택 순서로 확인하는 것이 좋습니다. 제공자가 아직 로드되지 않으면 후보 목록이 불완전할 수 있고 필터 조건이 너무 엄격하면 노드가 모두 제외될 수도 있습니다. 그룹이 비어 있다면 제공자 업데이트 로그와 필터 표현식부터 확인하세요. 규칙의 대상을 다른 그룹으로 바로 바꾸면 원본 문제를 해결하지 않은 채 우회하게 됩니다.

‘현재 선택된 항목이 있음’과 ‘현재 선택된 항목에 연결할 수 있음’도 구분해야 합니다. 수동 그룹에 이미 사용할 수 없는 노드가 남아 있을 수 있고, 자동 그룹은 후보를 모두 사용할 수 없으면 정상적인 연결을 제공하지 못할 수 있습니다. 그룹 구조에 문제가 없다면 개별 노드의 연결 로그로 돌아가 서버, 프로토콜, DNS를 확인하세요. 클라이언트 인터페이스 차이를 고려한 설정 관리 방식은 선택 가이드를 참고하세요.

06 · 규칙 문법, 순서, 규칙 세트

규칙 모드에서는 연결이 규칙 목록을 위에서 아래로 따라가며, 일반적으로 처음 일치한 규칙이 대상 출구를 결정합니다. 여러 규칙의 결과를 모아 투표하거나 뒤쪽의 더 구체적인 규칙을 자동으로 우선 적용하지 않습니다. 따라서 설정을 읽을 때는 먼저 순서를 확인한 다음 각 표현식이 올바른지 살펴보세요. 범위가 가장 넓은 기본 규칙을 맨 위에 놓으면 뒤에 있는 대부분의 규칙은 적용되지 않습니다.

도메인, 주소, 최종 대체 규칙

DOMAIN은 지정한 도메인과 일치하고, DOMAIN-SUFFIX는 도메인과 하위 도메인에 일치하며, DOMAIN-KEYWORD는 키워드로 판별합니다. 도메인 접미사 규칙은 범위가 넓은 키워드 규칙보다 적용 범위를 제어하기 쉽습니다. 도메인 규칙은 호스트 이름을 대상으로 하며 전체 웹 주소와 일치하지 않습니다. 도메인 필드에 프로토콜 접두사, 경로, 쿼리 매개변수를 넣지 마세요. 올바른 URL을 복사한 것처럼 보여도 실제로는 일치하지 않을 수 있습니다.

rules:
  - DOMAIN,router.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,PROXY

여기서는 정확한 도메인 직접 연결 규칙이 접미사 프록시 규칙보다 앞에 있어 예외로 적용됩니다. 로컬 네트워크 대역은 실제 네트워크에 맞춰 추가하세요. 예제는 모든 주소 범위를 포함하지 않으며 완전한 네트워크 경계 설계를 대신할 수도 없습니다. MATCH에는 일치 조건이 없으며 나머지 연결에 적용되는 기본 규칙입니다. 뒤에 오는 필드는 출구 이름입니다. 해당 이름이 존재하지 않으면 기본 규칙도 정상적으로 동작하지 않습니다.

주소 규칙은 도메인 대상을 판별하기 위해 DNS 해석이 필요할 수 있습니다. no-resolve는 해당 주소 규칙을 위해 도메인 해석을 새로 시작하지 않도록 합니다. DNS 전체를 끄거나 연결에 해석 과정이 전혀 없었다는 뜻은 아닙니다. 연결 대상이 이미 주소라면 주소 기준으로 계속 매칭할 수 있습니다. 디버깅할 때는 로그의 도메인과 대상 주소를 함께 확인해 코어가 어떤 정보를 받았는지 파악하세요.

프로세스 규칙과 코어로 들어오는 경로

일부 환경에서는 프로세스 이름이나 경로로 매칭할 수 있지만 프로세스 정보를 가져올 수 있는지는 운영체제, 권한, 연결 방식에 따라 달라집니다. 다른 기기에서 로컬 네트워크를 통해 들어온 연결은 이 기기의 연결과 달리 원격 앱 프로세스에 연결하기 어려운 경우가 많습니다. 규칙이 적용되지 않으면 이름을 계속 추가하기 전에 프로세스 식별 조건이 성립하는지 확인하세요. 메타데이터가 없는 문제를 비슷한 프로세스 규칙을 늘려 해결하려고 하지 마세요.

코어에 들어오지 않은 연결은 규칙으로 처리할 수 없습니다. 시스템 프록시를 무시하는 프로그램은 정확한 프로세스 규칙을 작성해도 매칭될 기회가 전혀 없을 수 있습니다. 먼저 연결 기록에 요청이 나타나는지 확인하세요. 기록이 없다면 앱의 프록시 설정이나 TUN 가로채기 경로를 살펴보세요. 기록은 있지만 대상 그룹이 잘못됐다면 현재 모드, 규칙 순서, 도메인 정보를 확인하세요. 이렇게 하면 트래픽 진입 문제와 규칙 표현 문제를 구분할 수 있습니다.

규칙 제공자와 형식 맞추기

rule-providers는 규칙 내용을 별도 파일이나 원격 리소스에 두고, 주 규칙 목록에서 RULE-SET으로 참조합니다. behavior는 도메인, 주소 대역, 클래식 규칙 등 콘텐츠의 의미를 나타내고 format은 파일 형식을 지정합니다. 두 값 모두 실제 리소스와 일치해야 합니다. 일반 웹 페이지, 전체 설정 파일, 규칙 목록은 파일 확장자만 보고 서로 바꿔 사용할 수 없습니다.

rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,DIRECT
  - MATCH,PROXY

해당 도메인 규칙 파일은 아래와 같은 구조로 작성할 수 있습니다. 파일 내용과 주 설정의 제공자 정의가 함께 로드 여부를 결정합니다. 리소스 내용을 보지 않고 주 파일만 확인하면 형식이 일치하지 않는 문제를 놓치기 쉽습니다. 파일 경로도 코어의 작업 디렉터리를 기준으로 하므로, 처음 사용할 때는 리소스가 존재하고 읽을 수 있으며 실제로 로드됐는지 확인한 뒤 도메인 매칭을 테스트하세요.

payload:
  - '+.example.com'
  - 'router.example.net'

구독 업데이트와 규칙 세트 업데이트는 별개의 경로입니다. 노드가 새로고침됐다고 규칙 리소스도 정상적으로 업데이트된 것은 아닙니다. 이전 캐시가 계속 사용될 수 있습니다. 일부 웹사이트 유형에서만 트래픽 분기가 이상하다면 해당 제공자의 로드 로그를 먼저 확인한 다음 특정 도메인 하나의 매칭 결과를 추적하세요. 키워드 범위를 계속 넓혀 리소스 문제를 대신 해결하지 마세요. 알아차리기 어려운 오매칭이 생길 수 있습니다.

최종 검증에는 새 연결을 사용하세요. 이미 연결된 장시간 연결은 기존 출구를 계속 사용할 수 있고 브라우저의 연결 재사용으로 규칙 수정이 적용되지 않은 것처럼 보일 수도 있습니다. 테스트할 도메인을 하나 정하고 관련된 이전 연결을 종료한 뒤 다시 접속해 매칭 규칙, 정책 그룹, 최종 노드를 확인하세요. 로그 필드 확인 방법은 실행 로그로 문제 찾기에서 볼 수 있습니다.

07 · TUN, 라우팅, 트래픽 가로채기 범위

TUN은 가상 네트워크 인터페이스를 통해 라우팅 조건에 맞는 트래픽을 코어로 전달하므로 시스템 프록시 설정을 따르지 않는 앱을 처리하는 데 유용합니다. TUN과 규칙 모드는 서로 다른 계층을 다룹니다. TUN은 트래픽이 어떻게 들어오는지 결정하고 규칙은 들어온 뒤 어디로 나갈지 결정합니다. TUN을 켠다고 모든 요청이 원격 프록시를 사용하는 것은 아닙니다. 규칙에 따라 로컬 네트워크나 특정 서비스를 DIRECT로 보내거나 특정 연결을 차단할 수도 있습니다.

기본 구조와 권한 조건

데스크톱 시스템에서는 일반적으로 관리자 권한, 서비스 모드, 해당 네트워크 권한이 필요합니다. 모바일 시스템은 플랫폼에서 제공하는 VPN 인터페이스를 통해 트래픽을 가로챕니다. 그래픽 스위치 제공 여부와 서비스 자동 설치 여부는 플랫폼마다 다릅니다. 활성화에 실패하면 먼저 가상 인터페이스와 권한 관련 로그를 확인하세요. 인터페이스의 스위치가 켜져 있다는 이유만으로 트래픽이 TUN에 들어갔다고 판단할 수는 없습니다.

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

이것은 흔히 사용하는 필드 조합이지 모든 기기에 그대로 쓸 수 있는 완성 설정은 아닙니다. auto-route는 관련 경로를 자동으로 설정하고 auto-detect-interface는 출구 인터페이스를 선택하는 데 도움을 줍니다. 여러 네트워크 어댑터, 원격 데스크톱, 컨테이너, 다른 터널이 함께 있으면 자동 설정이 예상과 다를 수 있습니다. 라우팅을 수정하기 전에 복구 방법을 마련하세요. 특히 유일한 원격 연결에서 검증되지 않은 트래픽 가로채기 설정을 바로 시험하지 마세요.

네트워크 스택, DNS 가로채기, 실제 동작

stack은 코어 지원 범위에 따라 system, gvisor, mixed 등의 구현을 선택할 수 있습니다. 시스템 호환성, 처리 방식, 리소스 사용량에 차이가 있습니다. mixed는 혼합 처리 방식을 사용한다는 뜻이지 ‘더 새롭고 더 빠르다’는 표시가 아닙니다. 먼저 클라이언트 권장값을 사용하고 호환성 문제가 확인된 경우에만 조정하세요. 스택, 라우팅, DNS 모드를 동시에 바꾸면 결과를 비교하기 어려워집니다.

dns-hijack은 조건에 맞는 일반 DNS 요청을 코어의 DNS 처리로 전달합니다. 예제의 포트 조건이 모든 암호화 DNS를 찾아 리디렉션할 수 있다는 뜻은 아닙니다. 앱이 HTTPS로 보내는 질의는 일반 웹 연결과 같은 전송 진입점을 사용하므로 일반 DNS 포트만으로 처리할 수 없습니다. 브라우저 자체의 해석 기능도 도메인 정보가 보이는 방식에 영향을 줄 수 있습니다. 테스트할 때는 앱이 어떤 DNS 경로를 사용하는지 확인하세요.

TUN을 켠 뒤에도 내장 DNS가 올바르게 작동해야 합니다. 질의는 가로챘지만 사용할 수 있는 상위 DNS 서버가 없으면 앱이 대규모로 해석을 기다리는 현상이 나타날 수 있습니다. 질의가 예상 경로를 우회하면 일부 도메인 규칙에 필요한 정보가 누락될 수도 있습니다. 따라서 가상 인터페이스, 라우팅, DNS, 노드, 규칙 순서로 점검하세요. Fake-IP와 실제 주소 모드만 반복해서 전환하지 마세요.

로컬 네트워크, 다른 터널, 문제 해결

로컬 네트워크 접근에는 라우팅과 트래픽 분기 설정이 모두 영향을 줍니다. 사설 네트워크 대역에 DIRECT 규칙을 추가하면 이미 코어에 들어온 연결의 출구만 결정할 뿐, 모든 시스템 라우팅 충돌이 해결되는 것은 아닙니다. TUN을 켠 뒤 프린터, 공유 폴더, 내부 관리 페이지가 작동하지 않으면 설정을 켜기 전후의 라우팅, 대상 주소, 연결 기록을 비교한 다음 적절한 경로 제외를 검토하세요. 모든 트래픽을 바로 허용하지는 마세요.

기업 VPN이나 다른 네트워크 터널과 함께 사용할 때 기본 경로, DNS, 인터페이스 우선순위가 서로 영향을 줄 수 있습니다. 가장 효과적인 기준 테스트는 트래픽 가로채기 기능을 한 번에 하나만 사용해 DNS 해석과 대상 접속을 각각 확인하는 것입니다. 단독으로 정상 작동하는지 확인한 뒤 경로를 어떻게 나눌지 검토하세요. 모든 네트워크 인터페이스를 제외하거나 전부 가로채지 마세요. 이런 극단적인 변경은 코어가 자체 출구 연결을 구축하지 못하게 할 수 있습니다.

TUN을 종료한 뒤에도 네트워크에 문제가 있으면 클라이언트가 인터페이스, 라우팅, 시스템 프록시를 정상적으로 정리했는지 확인하고 다른 네트워크 도구가 실행 중인지 살펴보세요. 먼저 클라이언트에서 해당 설정을 복원한 뒤 정상적으로 종료하세요. 알 수 없는 시스템 경로를 바로 삭제하지 마세요. 활성화 절차, 권한, 네트워크 스택에 대한 자세한 내용은 TUN 모드 설정 가이드를 참고하세요.

08 · 오버라이드, 병합, 설정 검증

구독 설정은 주기적으로 업데이트해야 하지만 로컬 포트, DNS, 개인 트래픽 분기 규칙은 계속 유지하고 싶을 수 있습니다. 오버라이드 기능은 원본 설정과 별도로 이런 차이를 저장한 다음 클라이언트가 실행 설정을 생성하도록 합니다. YAML 자체에 공통으로 정해진 기능은 아니며 클라이언트마다 병합 순서, 목록 처리, 스크립트 지원 방식이 다를 수 있습니다. 따라서 특정 인터페이스 버튼 이름을 외우기보다 최종 결과를 확인하는 것이 중요합니다.

교체, 재귀 병합, 추가 구분

단일 스칼라 필드를 오버라이드하는 방법은 대체로 간단합니다. 예를 들어 mixed-port를 바꾸는 경우입니다. 매핑은 재귀적으로 병합되거나 통째로 교체될 수 있습니다. 목록은 클라이언트별 차이가 더 커서 원래 목록을 덮어쓰거나 끝에 추가하거나 전용 기능으로 앞에 삽입할 수 있습니다. 두 파일에 모두 rules가 있다고 해서 클라이언트가 양쪽의 모든 규칙을 자동으로 유지한다고 가정하지 마세요.

# 오버라이드 예제: 구체적인 병합 방식은 클라이언트에 따라 다름
mixed-port: 7890

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

profile:
  store-selected: true

클라이언트가 dns 블록 전체를 교체한다면 위 예제로 인해 구독 원본의 상위 DNS 서버가 사라질 수 있습니다. 재귀 병합을 사용한다면 명시되지 않은 하위 필드가 유지될 수도 있습니다. 이 텍스트만으로는 두 결과 중 어느 쪽인지 알 수 없습니다. 저장한 뒤 실행 설정을 열어 상위 DNS 서버, 수신 주소, 필터 목록이 제대로 유지됐는지 확인하고 DNS를 테스트하세요. 병합 방식이 확실하지 않다면 복구 가능한 테스트 사본으로 먼저 확인하세요.

규칙 위치와 구독 업데이트

개인 예외 규칙은 일반적으로 범위가 넓은 규칙보다 앞에, 특히 최종 대체 규칙보다 앞에 있어야 합니다. 클라이언트가 새 규칙을 기존 MATCH 뒤에 추가하기만 하면 파일에 규칙이 있어도 매칭될 기회가 거의 없습니다. 따라서 설정 화면의 ‘규칙 앞에 추가’, ‘규칙 뒤에 추가’, ‘규칙 교체’를 서로 바꿔 사용할 수 없습니다. 원하는 우선순위에 맞춰 선택해야 합니다.

구독 원본 파일을 직접 수정하면 다음 업데이트 때 덮어써질 수 있습니다. 노드 출처, 서비스별 규칙, 로컬 환경 설정을 계층별로 관리하고 클라이언트가 명시적으로 지원하는 오버라이드나 설정 조합 기능을 사용하는 편이 안전합니다. 클라이언트가 필요한 기능을 지원하지 않는다면 수동 설정으로 따로 저장하고 직접 관리하는 부담을 감수하세요. 자동 업데이트에 의존하면서 수동 변경은 영구히 유지된다고 가정하지 마세요.

노드 이름과 정책 그룹 이름이 바뀌는 것도 업데이트 위험 요인입니다. 개인 규칙이 구독의 특정 그룹 이름을 참조하는데 업데이트 후 그룹 이름이 바뀌면 개인 규칙은 그대로여도 작동하지 않습니다. 직접 관리하는 안정적인 업무별 그룹을 사용하고 업데이트되는 노드 출처는 그 그룹에서 참조하세요. 업데이트 후 사용자 지정 대상이 모두 여전히 존재하는지 확인하세요. 클라이언트에 구독 새로고침 성공이라고 표시되는지만 확인해서는 안 됩니다.

실행 설정으로 검증 절차 완성

전체 검증은 네 단계로 나뉩니다. 파일 파싱, 참조 확인, 외부 리소스 로드, 연결 동작 확인입니다. 앞의 두 단계는 설정 검사 기능으로 확인할 수 있고, 세 번째는 제공자와 노드 관련 로그를 살펴봅니다. 네 번째는 실제 요청과 연결 기록을 확인해야 합니다. 어느 한 단계의 성공도 다른 단계를 대신하지 않습니다. 테스트 명령이 성공해도 서버 인증 정보가 유효하거나 규칙이 예상한 출구를 선택한다는 뜻은 아닙니다.

mihomo -t -f ./config.yaml

클라이언트가 생성한 실행 파일은 가능하면 클라이언트에서 실제 사용하는 코어로 검사하세요. 별도로 설치한 명령줄 도구는 지원 필드가 다를 수 있어 로컬 테스트 결과와 인터페이스의 동작이 일치하지 않을 수 있습니다. 실행 파일에 자동 생성된 제어 주소, 인터페이스 이름, 캐시 경로가 포함될 수도 있으므로 구분하지 않고 다른 기기에 복사하지 마세요. 다른 환경으로 옮길 때는 필요한 설정 로직만 가져간 뒤 새 환경에서 다시 생성하세요.

변경 기록과 안전한 공유

변경할 때마다 세 가지를 기록하세요. 변경 이유, 수정한 계층, 적용 여부를 확인하는 방법입니다. 설명 없는 사본을 많이 보관하기보다 복구 가능한 이전 설정을 남겨두는 편이 유용합니다. 문제가 생기면 최근에 정상 작동한 상태로 되돌린 뒤 변경 사항을 하나씩 다시 적용하세요. 클라이언트 업데이트와 규칙 조정을 동시에 했다면 따로 검증해 코어 차이와 설정 오류가 뒤섞이지 않도록 하세요.

도움을 요청할 때는 오류 발생 시간, 간략화한 관련 설정, 실제 실행 모드, 재현 절차를 제공하고 구독 인증 정보, 비밀번호, 관리 키는 바꿔서 공유하세요. 공개 스크린샷에서는 노드 메모, 내부 네트워크 주소, 접속 기록도 확인해야 합니다. 설치, 가져오기, 연결 과정을 다시 확인하려면 사용 가이드로 돌아가세요. 흔한 오류 유형을 확인하려면 도움말 센터를 참고하세요. 문제가 생길 때마다 전체 설정을 새로 작성할 필요는 없습니다.