Clash 설정 파일
YAML 및 항목 가이드

1. YAML 구조와 설정 로드

최상위 항목: 객체와 목록 구분하기

Clash 설정은 대개 YAML 맵 하나로 구성됩니다. mixed-port와 mode는 스칼라 항목이고, dns는 중첩 맵이며, proxies, proxy-groups, rules는 목록입니다. 먼저 각 구조를 구분하면 노드를 정책 그룹 안에 넣거나 규칙을 DNS 아래에 두는 계층 오류를 피할 수 있습니다.

들여쓰기로 항목 간 관계를 나타내므로 공백 두 칸으로 통일하고 탭은 사용하지 않는 것이 좋습니다. 목록 항목은 하이픈 뒤에 공백을 넣어 시작하며, 같은 항목의 필드는 들여쓰기를 맞춰야 합니다. 편집기에서 정렬되어 보여도 실제 문자가 다를 수 있으므로 설정을 붙여넣은 뒤 공백 표시 기능으로 확인하세요. 전각 문장 부호도 오류의 원인이 됩니다. 항목 뒤 콜론과 규칙 안 쉼표는 반각 문자를 사용해야 합니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

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

rules:
  - MATCH,Proxy

이 기본 구조는 항목 간 참조 관계를 보여주지만, 실제로는 직접 연결만 가능합니다. 마지막 규칙은 Proxy를 가리키고, 해당 그룹에는 DIRECT만 있습니다. 기본 구조를 확인하기에는 적합하지만 프록시 노드가 자동으로 생성되지는 않습니다. 실제로 사용하려면 서비스 제공자가 준 노드를 추가하거나 제공자로 노드 목록을 불러오세요. 구조 예시를 사용 가능한 구독으로 착각하지 마세요.

문자열, 불리언, 중복 키

포트는 보통 정수로, 스위치 항목은 true 또는 false로 씁니다. 이름과 비밀번호, 특수 문자가 포함된 문자열은 따옴표로 묶을 수 있습니다. 특히 콜론 뒤에 공백이 있거나, 샵 기호가 포함되거나, 불리언처럼 보이는 내용은 따옴표를 쓰는 편이 안전합니다. 큰따옴표 문자열에서는 일부 이스케이프 문자가 해석되므로 백슬래시가 있다면 주의하세요. 확실하지 않다면 서비스 제공자가 준 원본 값을 확인하고 문자를 임의로 바꾸지 마세요.

주석은 문자열 바깥의 샵 기호로 시작하며 수정 이유를 기록할 때 유용하지만, 코어 설정에는 반영되지 않습니다. 같은 최상위 키를 두 번 선언하지 마세요. 예를 들어 앞부분에 dns를 작성하고 파일 끝에 또 다른 dns를 선언하면 안 됩니다. 파서에 따라 오류가 발생하거나 둘 중 하나만 남을 수 있습니다. 필요한 하위 항목을 하나의 객체에 모으세요. 뒤에 쓴 값이 앞의 값을 덮어쓰도록 기대하지 마세요.

YAML을 파싱할 수 있다는 것은 문법이 유효하다는 뜻일 뿐, 현재 코어가 모든 항목을 지원한다는 뜻은 아닙니다. 필드 이름을 잘못 입력하면 기대한 대로 작동하지 않을 수 있고, 존재하는 정책 그룹도 없는 노드를 참조할 수 있습니다. 점검은 텍스트 파싱 여부, 코어의 설정 수용 여부, 연결이 예상한 경로로 처리되는지의 세 단계로 나누세요. 이를 한데 묶어 생각하면 참조 오류를 네트워크 장애로 오인하기 쉽습니다.

설정 출처와 테스트 순서

클라이언트의 구독 원본, 로컬 편집 내용, 오버라이드 결과, 코어에서 실행 중인 설정은 서로 다른 텍스트일 수 있습니다. 문제를 확인하기 전에 현재 활성화된 Profile을 확인하고, 클라이언트가 병합이나 스크립트 처리를 적용하는지도 살펴보세요. UI에 수정 내용이 저장되어 보여도 실행 중인 코어가 다시 로드되었다는 뜻은 아닙니다. 필요한 경우 클라이언트의 다시 로드 기능을 실행한 뒤 로그를 확인하세요.

mihomo를 직접 실행한다면 아래 명령으로 지정한 파일을 검사할 수 있습니다. GUI 클라이언트에서는 설정 검사, 실행 로그, 오류 메시지를 우선 확인하세요. 명령에 지정하는 설정 경로는 테스트할 파일을 가리켜야 하며, 다른 디렉터리에 있는 동명 파일을 가리키면 안 됩니다. 테스트를 통과한 뒤 활성화하고, 유일하게 작동하는 설정을 바로 덮어써서 비교할 자료를 잃지 않도록 하세요.

mihomo -t -f ./config.yaml

한 번에 한 가지 영역만 수정하는 것이 좋습니다. 먼저 기본 구조를 로드하고, 다음으로 노드를 추가한 뒤 정책 그룹을 설정하고, 마지막으로 규칙과 DNS를 조정하세요. 오류가 나면 수십 개 항목을 동시에 바꾸기보다 직전의 정상 파일로 돌아가는 편이 원인을 찾기 쉽습니다. 여러 설정의 이름 지정과 전환 방법은 Profile 및 로컬 설정 관리를 참고하세요.

2. 포트, 모드 및 공통 항목

수신 포트: 프록시 진입 방식 확인

port는 HTTP 프록시 진입점을, socks-port는 SOCKS 진입점을 제공합니다. mixed-port는 하나의 수신 포트에서 HTTP와 SOCKS 요청을 모두 받습니다. 일반적인 데스크톱 사용이라면 목적에 맞는 진입 방식 하나를 명확하게 선택하면 됩니다. 포트 번호는 성능 설정이 아니므로 더 큰 번호로 바꿔도 연결이 빨라지지 않습니다. 실제로 확인할 점은 해당 포트가 사용 중이지 않은지, 앱이 올바른 주소와 포트를 사용하는지입니다.

아래 설정은 로컬 기기에서만 수신하므로 클라이언트의 시스템 프록시 기능과 함께 사용하기 적합합니다. 클라이언트가 이미 포트를 관리한다면 구독 설정의 항목을 직접 수정해도 UI 설정으로 덮어써질 수 있습니다. 포트 충돌이 발생하면 먼저 중복 실행된 클라이언트를 종료하고 백그라운드 서비스를 확인한 뒤 포트를 바꾸세요. 여러 프로그램에서 같은 주소와 포트를 동시에 수신하도록 설정하지 마세요.

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

실행 모드: 트래픽 진입과 아웃바운드 선택 구분하기

mode: rule은 규칙 목록에 따라 정책을 선택하고, global은 전역 정책을 사용하며, direct는 직접 연결을 우선합니다. 모드는 코어에 들어온 연결을 어떻게 처리할지 결정할 뿐, 모든 앱의 트래픽을 자동으로 코어에 전달하지는 않습니다. 시스템 프록시, 앱 내 프록시, TUN은 트래픽 진입 단계에 해당하므로 실행 모드를 바꾸는 것으로 진입 설정을 대신할 수 없습니다.

브라우저는 프록시를 사용하는데 명령줄 도구는 직접 연결한다면, 먼저 해당 도구가 시스템 프록시를 읽는지 또는 환경 변수를 별도로 설정해야 하는지 확인하세요. 반대로 연결이 클라이언트 패널에 표시되지만 잘못된 정책을 따른다면 모드, 규칙, 정책 그룹을 점검해야 합니다. 먼저 연결이 코어에 들어왔는지 확인하고, 그다음 아웃바운드 선택을 살펴보면 문제 범위를 크게 좁힐 수 있습니다.

LAN 공유를 설정하려면 allow-lan, 수신 주소, 운영체제 방화벽, 접속 기기의 프록시 설정을 함께 확인해야 합니다. 허용 스위치만 켠다고 다른 기기가 반드시 연결되는 것은 아닙니다. 공유가 꼭 필요하다면 신뢰할 수 있는 네트워크 범위로 제한하고 적절한 인증을 설정하세요. 문제 해결을 간단히 하려고 프록시 진입점과 관리 인터페이스를 공용 네트워크에 함께 노출하지 마세요.

로그, 선택 항목 저장, 관리 인터페이스

log-level은 보통 info를 사용하고, 일시적인 문제 해결에는 debug로 높인 뒤 확인이 끝나면 원래대로 돌립니다. 상세 로그에는 도메인, 연결 대상, 경로 정보가 포함될 수 있으므로 문의 내용을 공유하기 전에 민감한 정보를 삭제하세요. 경고가 한 번 표시되었다고 클라이언트 전체가 작동하지 않는다고 볼 수는 없습니다. 발생 시점과 대상 연결, 재현 여부를 함께 확인해 영향을 판단하세요.

profile.store-selected는 정책 그룹의 선택 항목을 저장합니다. 선택이 예상대로 복원되는지는 클라이언트가 설정을 전환하는 방식에도 영향을 받습니다. 그룹명이나 노드명을 바꾸면 기존 선택 항목을 찾지 못해 기본 정책으로 돌아갈 수 있습니다. 이때는 클라이언트를 바로 재설치하기보다 구독 갱신으로 이름이 변경되었는지 확인하세요. 주요 정책 그룹의 이름을 안정적으로 유지하면 장기 관리가 수월합니다.

profile:
  store-selected: true

external-controller는 관리 인터페이스이며 브라우저의 웹사이트 접속용 프록시 포트가 아닙니다. 일반 사용자는 네트워크 연결을 위해 이 인터페이스를 열 필요가 없습니다. 패널 연결이 꼭 필요하다면 로컬 주소나 통제된 네트워크에서 수신하도록 하고, 클라이언트 안내에 따라 인증을 설정하세요. 관리 포트를 시스템 프록시에 입력하면 대개 접속 불가 또는 프로토콜 불일치 오류가 발생합니다.

최상위의 ipv6와 DNS 아래에 있는 같은 이름의 항목은 역할이 다릅니다. 전자는 코어의 IPv6 사용에, 후자는 DNS의 AAAA 조회 처리에 관련됩니다. 두 항목 모두 운영체제 네트워크 어댑터의 IPv6 스위치는 아닙니다. 가정용 네트워크, 노드의 출구, 대상 서비스가 IPv6를 지원하는지는 서로 다를 수 있으므로 수정 전에 기존 값을 기록하고 하나씩 테스트하세요. 모든 이상을 IPv6 탓으로 돌리지 마세요.

3. 프록시 노드 항목과 프로토콜별 주의점

기본 항목: 이름은 참조에 사용됩니다

proxies의 각 항목은 하나의 아웃바운드 노드를 나타냅니다. 보통 name, type, server, port를 먼저 확인한 다음 인증 및 전송 항목을 살펴봅니다. 이름은 정책 그룹에서 노드를 참조하는 데 사용하며 서버 도메인이 아닙니다. 노드 이름을 특정 지역으로 바꿔도 출구 위치는 바뀌지 않습니다. 실제 지역과 회선 정보는 서비스 제공자 안내와 연결 결과를 기준으로 확인하세요.

노드 이름은 고유하게 지정하고 정책 그룹과 같은 이름은 피하세요. DIRECT, REJECT처럼 내장된 정책 이름도 사용하지 마세요. 노드를 복사한 뒤 주소만 바꾸고 이름을 그대로 두면 참조가 모호해지거나 설정 로드에 실패할 수 있습니다. 서비스 제공자가 이름을 자주 바꾼다면 특정 노드를 직접 참조하는 그룹은 쉽게 깨질 수 있으므로, 제공자를 연결한 뒤 그룹에서 필터링하는 방법을 고려하세요.

proxies:
  - name: Example-SS
    type: ss
    server: proxy.example.com
    port: 443
    cipher: chacha20-ietf-poly1305
    password: "your-password"
    udp: true

위 Shadowsocks 예시는 항목 간 관계만 보여줍니다. 주소와 비밀번호는 서비스 제공자가 준 값으로 바꿔야 합니다. cipher는 프로토콜 암호화 방식이므로 서버와 일치해야 하며, 이름이 비슷하다는 이유로 임의로 바꾸면 안 됩니다. 서버 포트가 일반 웹사이트 서비스 포트와 같은 것은 아닙니다. 443으로 지정해도 해당 노드가 자동으로 HTTPS를 사용하거나 브라우저에서 바로 열리는 것은 아닙니다.

인증 및 전송: 프로토콜에 맞춰 함께 확인하기

프로토콜마다 인증 항목이 다릅니다. Shadowsocks는 비밀번호와 암호화 방식을 사용하고, Trojan은 비밀번호와 해당 TLS 설정이 필요합니다. VMess와 VLESS에는 보통 사용자 식별자 항목이 있습니다. 한 프로토콜의 항목명을 다른 프로토콜에 그대로 가져다 쓰면 안 됩니다. 인증 오류가 발생하면 원본 구독이나 서비스 제공자 문서로 돌아가 프로토콜 종류, 계정 식별자, 추가 항목을 확인하세요. 인터넷에서 찾은 항목을 무작정 추가하지 마세요.

일부 프로토콜은 전송 방식, 경로, 호스트 헤더, TLS 항목도 지정합니다. 서버 설정과 한 세트로 맞춰야 합니다. WebSocket 경로는 웹사이트의 첫 페이지 경로와 같지 않을 수 있고, HTTP 호스트 헤더도 연결 주소와 다를 수 있습니다. 서버 주소가 브라우저에서 열린다고 해서 프록시 인증까지 올바르다고 볼 수는 없습니다. 웹페이지 접속은 네트워크 조건 중 일부만 확인합니다.

servername은 해당 프로토콜의 TLS 서버 이름으로 주로 사용됩니다. server와 다른 값일 수 있지만, 그 차이는 서버 설정에 근거해야 하며 접속 가능한 도메인을 임의로 넣어서는 안 됩니다. 인증서 오류가 발생하면 기기 시간, 서버 이름, 인증서 체인을 확인하세요. skip-cert-verify를 만능 해결책으로 사용하지 마세요. 중요한 서버 신원 확인 절차를 건너뛰게 됩니다.

UDP, 도메인 조회 및 노드 선택

udp: true는 노드에서 관련 UDP 전달 기능을 허용한다는 뜻이지만, 진입 경로와 서버, 목적지까지의 연결이 모두 지원된다는 보장은 아닙니다. 앱이 UDP를 보내는지, 시스템 프록시가 이를 처리할 수 있는지, 노드 프로토콜이 지원하는지, 서버가 허용하는지 각각 확인해야 합니다. 웹페이지가 잘 열린다고 음성 통화나 게임, 다른 실시간 앱도 반드시 작동하는 것은 아닙니다.

server에 도메인을 지정하면 프록시 연결을 만들기 전에 코어가 노드 도메인을 IP 주소로 조회해야 합니다. 이 조회는 대상 웹사이트에 접속하기 전에 이루어집니다. DNS 설정에서 아직 연결되지 않은 동일한 노드를 통해 조회하도록 하면 의존성 순환이 발생할 수 있습니다. 모든 노드가 한꺼번에 연결되지 않는다면 특정 회선 문제를 보기 전에 노드 도메인 조회가 성공하는지 확인하세요.

지연 시간 테스트에 성공했다는 것은 당시 테스트 요청이 완료되었다는 뜻일 뿐, 모든 대상 사이트나 전송 방식이 정상이라는 의미는 아닙니다. 노드를 고를 때는 안정성, 대상 서비스의 지역, 트래픽 요금 배율, 평소 사용 환경을 함께 고려하세요. 자세한 비교 순서는 프록시 노드 선택 방법을, 테스트 지표의 한계는 지연 시간 테스트와 실제 사용 경험을 참고하세요.

새 설정을 만들 때 모든 프로토콜을 한꺼번에 입력할 필요는 없습니다. 필요한 항목이 갖춰져 있고 유효성을 확인할 수 있는 노드 하나를 먼저 선택해 수동 선택 그룹으로 연결한 뒤, 자동 테스트나 예비 회선을 추가하세요. 클라이언트를 바꾸려면 다운로드 페이지에서 운영체제에 맞는 항목을 선택하세요. Clash Plus를 우선 고려하고, 필요한 프로토콜을 현재 클라이언트의 코어가 지원하는지 확인하세요.

4. 정책 그룹 항목과 선택 로직

select: 수동 선택을 한곳에 모으기

proxy-groups는 노드, 다른 정책 그룹, 내장 정책을 조합해 규칙에서 참조할 수 있는 아웃바운드 진입점을 만듭니다. 규칙에는 변경이 적은 그룹 이름만 적고, 노드 변경은 그룹 안에서 처리하면 반복 수정을 줄일 수 있습니다. 가장 많이 쓰는 select는 사용자가 구성원을 선택하는 방식으로, 일상적인 수동 전환이나 자동 그룹과 직접 연결 사이의 통합 진입점으로 적합합니다.

proxy-groups:
  - name: Proxy
    type: select
    proxies:
      - Auto
      - DIRECT

  - name: Auto
    type: url-test
    use:
      - Main
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

이 예시는 뒤에서 정의하는 Main 노드 제공자를 참조하므로, 제공자 없이 따로 붙여 넣으면 참조가 성립하지 않습니다. Proxy는 전체 진입점이며, 사용자는 자동 그룹과 직접 연결 중 하나를 선택할 수 있습니다. 문제 해결을 쉽게 하려면 그룹 이름에 일반 출구, 업무 서비스, 미디어 서비스처럼 용도를 드러내세요. 알아보기 어려운 기호만 쓰지 마세요.

proxies에는 명시적인 노드나 그룹 이름을 나열하고, use에는 노드 제공자를 연결합니다. 두 항목은 가리키는 대상이 다르므로 제공자 이름을 일반 노드 이름처럼 입력하면 안 됩니다. 그룹 구성원은 설정에 실제로 존재해야 하며 순환 참조를 만들어서는 안 됩니다. A 그룹이 B 그룹을 포함하고 B 그룹이 다시 A 그룹을 포함해도 예비 경로가 생기지 않고 잘못된 구조가 됩니다.

자동 그룹: 검사 조건부터 이해하기

url-test는 테스트 결과를 기준으로 구성원을 선택합니다. url은 테스트 요청 주소, interval은 주기(일반적으로 초), tolerance는 미세한 차이로 잦은 전환이 일어나는 것을 줄이는 설정입니다. 테스트 주소는 안정적이고 응답이 가벼우며 필요한 기본 접속 가능성을 보여줘야 합니다. 계정 정보가 포함되거나 로그인이 필요한 페이지는 사용하지 마세요.

자동 테스트는 계속 다운로드 속도를 재는 기능이 아닙니다. 결과는 테스트 서버 위치, 주소 조회 방식, 연결 재사용, 당시 회선 상태의 영향을 받습니다. 테스트 주소에는 잘 연결되는 노드도 실제 업무 서비스에서는 성능이 좋지 않을 수 있습니다. 그룹 선택이 반복해서 바뀐다면 주기를 무작정 줄이기보다 회선 상태와 테스트 조건을 먼저 확인하고 허용 오차를 적절히 조정하세요.

fallback은 구성원 순서에 따라 사용 가능한 경로를 선택하는 데 중점을 두며, 주 회선과 예비 회선이 명확한 환경에 적합합니다. 다만 주 회선이 테스트 주소에는 연결되지만 특정 서비스에 접속할 수 없는 경우에도 테스트에서 사용 가능하다고 판단할 수 있습니다. 주·예비 정책은 일부 장애의 영향을 줄여줄 뿐, 대상 서비스별 규칙과 접속 가능 여부 확인을 대신하지는 않습니다. 그룹 이름에 절대적인 가용성을 암시하지 마세요.

load-balance는 해당 정책에 따라 연결을 구성원에게 분배합니다. 하나의 다운로드 연결을 여러 노드에 나눠 대역폭을 합치는 기능은 아닙니다. 로그인 상태나 출구 IP 안정성이 중요한 서비스에서는 출구가 자주 바뀌면 추가 인증이 발생할 수 있습니다. 뚜렷한 필요가 없다면 수동 그룹이나 테스트 그룹이 동작을 파악하기 쉽고, 재현 가능한 기본 설정을 만드는 데도 적합합니다.

필터링과 선택 항목 저장: 빈 그룹 방지

제공자에서 노드를 가져올 때 필터 항목으로 구성원 범위를 제한할 수 있습니다. 필터는 보통 정규식을 사용하며 실제 지리적 위치가 아니라 노드 이름을 대상으로 일치 여부를 판단합니다. 서비스 제공자가 이름, 문장 부호, 표기 언어를 바꾸면 기존 필터 결과가 비어 있을 수 있습니다. 적용 전에 클라이언트에서 그룹에 실제 구성원이 있는지 확인하세요. 정규식이 그럴듯해 보인다는 이유만으로 그룹이 사용 가능하다고 판단하지 마세요.

정책 그룹의 중첩 깊이는 적절히 제한하세요. 전체 진입 그룹 아래에 업무 그룹을 두고, 업무 그룹에서 노드를 선택하는 정도면 보통 충분합니다. 여러 자동 그룹을 계속 겹쳐 두면 구조를 이해하기 어려워집니다. 문제를 확인할 때는 규칙 대상, 현재 그룹 선택, 다음 단계 그룹, 최종 노드를 차례로 따라가 실제 아웃바운드를 확인하세요. 가장 바깥 그룹 이름만 보면 내부에서 여전히 직접 연결을 선택한 사실을 놓치기 쉽습니다.

구독을 갱신한 뒤 선택이 바뀌었다면 노드 삭제, 이름 변경, 그룹 구조 재생성, 클라이언트의 선택 저장 방식이 원인일 수 있습니다. 먼저 기존 구성원이 남아 있는지 확인한 다음 profile.store-selected와 클라이언트의 선택 초기화 여부를 살펴보세요. 장기간 안정적으로 참조해야 하는 업무 그룹은 로컬 오버라이드에서 관리할 수 있습니다. 다만 구독 갱신 뒤에도 해당 그룹이 참조하는 구성원이 존재하는지 확인해야 합니다.

특정 그룹만 비정상이고 다른 그룹은 정상이라면 같은 노드를 간단한 수동 그룹에 임시로 넣어 비교하세요. 노드 자체가 작동한다면 문제는 필터, 상태 검사, 그룹 참조에 있을 가능성이 큽니다. 이를 통해 노드 장애와 그룹 선택 로직을 분리할 수 있으므로, 한 업무 그룹을 고치려고 구독 전체의 정책을 다시 작성하지 않아도 됩니다.

5. 규칙 문법과 매칭 순서

위에서 아래로 확인: 구체적인 규칙을 앞에 배치

rules는 순서가 있는 목록으로, 보통 위에서부터 확인해 처음 일치한 규칙의 정책을 적용합니다. 모든 조건을 한꺼번에 계산해 투표하는 방식이 아니므로 구체적인 예외를 범위가 넓은 규칙보다 앞에 둬야 합니다. 사용자 지정 규칙이 적용되지 않는다면 규칙 종류를 바로 바꾸기보다 위쪽에 더 넓은 범위의 규칙이 있는지 먼저 확인하세요.

rules:
  - DOMAIN,api.github.com,Proxy
  - DOMAIN-SUFFIX,github.com,Proxy
  - DOMAIN-KEYWORD,example,Proxy
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

예시의 Proxy는 설정에 정의된 정책 그룹이나 노드여야 합니다. 규칙의 마지막 정책 항목은 자유롭게 적는 메모가 아니므로 실제 이름과 철자, 대소문자, 공백을 일치시켜야 합니다. 편집기의 문장 부호 자동 치환이나 복사 중 들어간 보이지 않는 공백도 참조 오류를 일으킬 수 있습니다. 그룹 이름을 바꿀 때는 모든 규칙과 다른 그룹의 참조도 함께 확인하세요.

도메인 규칙과 IP 주소 규칙의 차이

DOMAIN은 전체 도메인을 일치시키므로 단일 API에 적합합니다. DOMAIN-SUFFIX는 도메인 자체와 하위 도메인을 일치시키므로 같은 서비스의 도메인 묶음에 적합합니다. DOMAIN-KEYWORD는 키워드 기준이라 범위가 더 넓고 관련 없는 대상까지 포함할 수 있습니다. 명확한 도메인으로 표현할 수 있다면 구체적인 규칙을 우선 사용해 나중에 설명하기 어려운 오매칭을 줄이세요.

IP-CIDR와 IP-CIDR6는 IP 주소 대역에 적용됩니다. 도메인이 포함된 연결에 주소가 필요한 규칙을 적용하면 코어가 주소 조회를 시작할 수 있습니다. no-resolve는 해당 IP 규칙만을 위해 도메인을 능동적으로 조회하지 않도록 하는 설정이지, 연결 전체의 DNS 조회를 금지하는 설정은 아닙니다. 연결에 대상 주소가 이미 있다면 해당 규칙과 계속 일치할 수 있습니다.

GEOIP는 IP 주소 데이터베이스를 기준으로 지역을 판별합니다. 결과는 데이터베이스의 내용과 업데이트 상태에 따라 달라지며 웹사이트 운영자의 소재지를 뜻하지 않고 CDN이 매번 선택하는 출구를 정확히 나타내지도 않습니다. 관련 규칙을 활성화하기 전에 코어가 필요한 데이터를 읽을 수 있는지 확인하세요. 도메인이 다른 지역의 IP 주소로 조회될 때 같은 사이트의 경로가 바뀐다면 규칙 오류가 아니라 조회 결과가 원인일 수 있습니다.

MATCH는 기본 규칙으로 보통 목록 맨 끝에 둡니다. 앞에 두면 뒤에 있는 일반 규칙이 연결을 처리할 기회가 없습니다. DIRECT는 직접 연결, REJECT는 연결 거부를 뜻하며, 다른 이름은 보통 노드나 정책 그룹을 가리킵니다. 간결하게 보이도록 업무 예외를 모두 기본 규칙 뒤로 옮기지 마세요. 설정에 규칙이 있어도 실행 중에는 절대 매칭되지 않을 수 있습니다.

규칙 제공자 및 프로세스 매칭의 한계

도메인 목록이 길다면 규칙 제공자에 넣고 RULE-SET으로 참조할 수 있습니다. 기본 설정은 업무별 순서를 명확하게 유지하고, 외부 목록은 구체적인 항목을 관리하도록 나눌 수 있습니다. 규칙 세트도 목록에 지정된 위치에서 매칭됩니다. 목록 내용이 정확하더라도 앞에 기본 규칙이 있으면 규칙 세트가 처리될 기회가 없습니다.

프로세스 규칙은 실행 플랫폼, 프로세스 식별 기능, 트래픽을 가로채는 방식에 따라 달라집니다. 데스크톱 클라이언트에서 인식하는 프로세스 이름도 라우터에서는 인식하지 못할 수 있습니다. 라우터가 받는 것은 다른 기기의 연결이기 때문입니다. 모바일 시스템도 관련 정보를 제한할 수 있습니다. 설정을 다른 플랫폼으로 옮기기 전에 기능의 한계를 확인하고, 프로세스 규칙을 어디서나 사용할 수 있는 도메인 규칙의 대체재로 여기지 마세요.

도메인 규칙을 적용하려면 코어가 도메인 정보를 얻을 수 있어야 합니다. 앱이 IP 주소에 직접 연결하거나 DNS가 코어를 거치지 않는 경우, 일부 암호화된 조회 경로를 사용하는 경우에는 도메인 식별이 어려울 수 있습니다. 스니핑 기능도 조건이 있으며 모든 프로토콜에서 도메인을 복원할 수 있는 것은 아닙니다. 연결에 주소만 표시된다면 키워드 매칭 범위를 무작정 넓히지 말고 DNS와 트래픽 진입 경로부터 확인하세요.

규칙을 확인하려면 연결 패널에서 새로 만든 연결을 찾아 매칭 유형과 내용, 정책 경로, 최종 노드를 확인하세요. 수정 전에 이미 만들어진 장기 연결은 아웃바운드를 다시 선택하지 않을 수 있으므로 필요한 경우 앱 연결을 종료하고 다시 시도하세요. 그래도 해결되지 않으면 문제 해결에서 증상에 맞는 점검 방법을 찾아보세요. 규칙이 적용되지 않는다고만 설명하기보다 성공한 연결과 실패한 연결 기록을 하나씩 준비하면 도움이 됩니다.

6. 구독, 노드 제공자 및 규칙 제공자

전체 구독과 노드 목록은 서로 다른 형식입니다

클라이언트의 원격 Profile은 보통 포트, DNS, 노드, 정책 그룹, 규칙을 포함할 수 있는 전체 설정입니다. proxy-providers는 하나의 기본 설정에서 노드 목록을 가져올 때 사용합니다. 둘 다 URL로 업데이트할 수 있지만 용도가 다릅니다. 전체 설정 URL을 노드 제공자 형식만 받는 곳에 입력하면 다운로드는 되지만 파싱에 실패할 수 있습니다.

먼저 서비스 제공자가 제공한 콘텐츠 형식을 확인한 뒤 적절한 가져오기 기능을 선택하세요. 처음 사용하는 경우 클라이언트의 구독 가져오기로 전체 Profile을 만드는 것을 권장합니다. 기본 설정을 직접 관리해야 할 때만 노드 출처를 제공자로 분리하세요. 클라이언트에서 진행하는 방법은 구독 가져오기 단계를, 형식 변환의 한계는 구독 변환 안내를 참고하세요.

proxy-providers:
  Main:
    type: http
    url: "https://example.com/nodes.yaml"
    path: ./providers/main.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

예시 주소에서는 실제 노드를 제공하지 않습니다. HTTP 노드 제공자는 일반적으로 최상위에 proxies 목록이 있는 YAML을 반환해야 합니다. 웹페이지, 로그인 화면, 오류 메시지로 대신할 수 없습니다. path는 로컬 캐시 경로로 사용되며 보통 코어 작업 디렉터리를 기준으로 해석됩니다. 정확한 동작은 클라이언트의 경로 제한에도 영향을 받습니다. 제공자마다 별도의 캐시 파일을 사용해 서로 덮어쓰지 않도록 하세요.

업데이트 주기와 상태 검사의 역할 구분

제공자의 interval은 노드 목록을 다시 가져오는 주기를 제어하고, 상태 검사에 있는 같은 이름의 항목은 연결 확인 주기를 제어합니다. 둘은 서로 다른 기능입니다. 전자는 새 노드 정보를 가져오는 시점을, 후자는 현재 노드의 접속 가능성을 확인하는 시점을 결정합니다. 상태 검사를 자주 실행해도 구독 정보가 더 빨리 갱신되지는 않습니다. 오히려 요청이 늘고 모바일 기기의 배터리가 더 빨리 소모될 수 있습니다.

업데이트가 실패하면 가져오기 경로를 따라 차례로 확인하세요. URL이 만료되었는지, 다시 인증해야 하는지, 현재 네트워크에서 접속 가능한지, 서버가 어떤 내용을 반환하는지, 콘텐츠가 YAML 구조에 맞는지 살펴봅니다. 브라우저에서 URL이 열려도 계정 페이지가 표시되는 것은 아닌지 확인하세요. 쿼리 매개변수에 바로 사용할 수 있는 인증 정보가 포함되는 경우가 많으므로 전체 구독 URL을 공개된 문의에 붙여 넣지 마세요.

로컬 캐시가 유효하다면 원격 업데이트 실패가 기존 노드에 바로 영향을 주지 않을 수 있습니다. 하지만 클라이언트의 캐시 정책과 재시작 동작은 다를 수 있으므로 이를 보장으로 여기면 안 됩니다. 문제를 확인할 때는 작동 중인 설정을 먼저 보존하고 캐시와 이전 Profile을 동시에 삭제하지 마세요. 오류 유형별 안내는 구독 업데이트 실패 및 자동 업데이트 주기를 참고하세요.

규칙 제공자: 파일 형식과 동작 맞추기

rule-providers는 매칭 조건을 관리하며 프록시 노드를 관리하는 항목이 아닙니다. behavior는 콘텐츠가 도메인, IP 주소, 클래식 규칙 형식 중 무엇인지 지정하고, format은 파일 형식을 나타냅니다. 실제 파일에 맞춰 두 항목을 설정해야 합니다. 확장자가 YAML이라는 이유만으로 규칙 동작도 같다고 볼 수 없습니다. 기본 규칙에서 사용할 정책 대상은 RULE-SET 참조에 지정하면 같은 목록을 서로 다른 아웃바운드에 활용하기 편리합니다.

rule-providers:
  Work:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/work.yaml

rules:
  - RULE-SET,Work,Proxy
  - MATCH,DIRECT

위의 rules는 규칙 순서 예시이므로 기존 목록에 합쳐야 합니다. 파일 끝에 같은 항목을 다시 선언하지 마세요. 도메인 동작을 사용하는 목록이라면 해당 파일을 아래 구조로 작성할 수 있습니다. 실제로 저장하기 전에 클라이언트가 상대 경로의 파일을 읽을 수 있는지 확인하세요. 작업 디렉터리에 직접 접근하기 어려운 모바일 클라이언트에서는 클라이언트가 제공하는 로컬 규칙이나 오버라이드 기능을 사용하는 편이 낫습니다.

payload:
  - "+.github.com"
  - "example.com"

제공자를 분리하면 관리 책임도 나뉩니다. 기본 설정은 그룹과 순서를, 노드 출처는 회선 정보를, 규칙 출처는 매칭 범위를 관리합니다. 로컬 수정은 해당 내용을 관리하는 영역에 반영하세요. 장기간 유지해야 하는 사용자 지정 도메인을 원격 갱신으로 교체될 캐시 파일에만 임시로 작성하면 다음 업데이트 때 사라질 수 있습니다.

여러 출처를 함께 사용하는 설정이라면 제공자별 용도와 형식, 참조하는 그룹을 기록해 두는 것이 좋습니다. 새 출처를 추가한 뒤에는 먼저 로드에 성공했는지, 다음으로 그룹에 구성원이 표시되는지, 마지막으로 연결이 되는지 확인하세요. 이렇게 하면 다운로드 실패, 형식 오류, 필터 결과 없음, 노드 사용 불가를 분리해 구독 URL 하나에 모든 문제를 돌리지 않을 수 있습니다.

7. DNS, Fake-IP, TUN 함께 사용하기

DNS: 이름 조회 경로부터 파악하기

dns는 코어 자체의 이름 조회 방식을 제어하지만, 해당 조회 경로로 들어온 요청에만 영향을 줍니다. 브라우저가 내장 암호화 DNS를 사용할 수도 있고, 앱이 별도의 리졸버를 지정하거나 운영체제에 캐시가 남아 있을 수도 있습니다. 설정에 새 상위 DNS 주소를 입력해도 모든 프로그램이 즉시 이를 사용하는 것은 아닙니다. 문제를 확인하기 전에 조회가 어디서 시작되어 누가 최종 응답을 반환하는지 파악하세요.

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

이 예시는 흔히 쓰는 항목의 관계를 보여줄 뿐, 모든 네트워크에 맞는 단일 설정은 아닙니다. listen은 수신 진입점을 만드는 항목이며, 설정에 있다고 해서 시스템이 DNS 요청을 자동으로 보내지는 않습니다. 로컬의 높은 포트에서 수신하더라도 라우터가 다른 기기에 DNS 서비스를 제공하는 것은 아닙니다. 클라이언트의 트래픽 가로채기 기능, 시스템 설정, 로컬 권한을 각각 확인해야 합니다.

default-nameserver는 DNS 상위 서버 자체의 도메인을 조회할 때 주로 사용하고, nameserver는 일반 조회 경로를 제공합니다. proxy-server-nameserver는 노드 도메인에 사용할 리졸버를 지정할 수 있습니다. 이런 역할을 이해하는 것이 공용 DNS를 여러 개 늘어놓는 것보다 중요합니다. 노드 연결 전에 필요한 조회는 독립적으로 작동하는 경로를 사용해야 합니다. 아직 연결되지 않은 동일한 프록시에 조회를 의존하지 마세요.

Fake-IP: 매핑 주소와 최종 목적지 구분

fake-ip는 도메인에 매핑 주소를 할당하고, 코어가 이 매핑을 이용해 대상 도메인을 복원한 뒤 연결을 처리합니다. 반환 주소가 설정된 매핑 대역에 속한다고 해서 웹사이트의 DNS 조회 오류로 판단할 필요는 없습니다. 이후 연결도 매핑 정보를 식별할 수 있는 코어를 통과해야 합니다. 조회는 코어를 거쳤는데 연결은 코어를 우회하면 앱이 일반 네트워크에서 직접 접근할 수 없는 매핑 주소에 접속하려 할 수 있습니다.

fake-ip-filter를 사용하면 특정 도메인에는 매핑 주소를 사용하지 않도록 설정할 수 있습니다. LAN 기기 검색이나 실제 주소가 필요한 일부 앱은 별도 처리가 필요할 수 있지만, 처음부터 범위를 넓게 추가하는 것은 피하세요. 예외 범위가 넓을수록 도메인 매핑에서 얻을 수 있는 식별 정보가 줄어듭니다. 먼저 문제가 발생한 구체적인 도메인을 찾고 필요한 최소 범위만 추가한 뒤 앱을 다시 테스트하세요.

조회 모드를 바꿔도 이전 DNS 캐시와 기존 연결 때문에 결과가 그대로인 것처럼 보일 수 있습니다. 먼저 대상 앱을 다시 실행하고, 운영체제나 클라이언트에서 제공하는 방법으로 캐시를 비워 보세요. 상위 DNS, 매핑 모드, 스니핑, 규칙을 한꺼번에 수정하면 어떤 변경이 연결을 개선하거나 망가뜨렸는지 판단하기 어렵습니다. LAN 이름은 라우터와 로컬 DNS 환경도 확인해야 합니다.

TUN: 트래픽 가로채기에는 라우팅과 권한도 필요

TUN은 가상 네트워크 장치로 트래픽을 받아 시스템 프록시를 사용하지 않는 일부 앱도 처리할 수 있습니다. 하지만 규칙과 노드를 대신하지 않으며 모든 시스템 환경에서 바로 활성화할 수 있는 것도 아닙니다. 데스크톱에서는 서비스나 높은 권한이 필요할 수 있고, 모바일 시스템은 시스템 네트워크 확장 인터페이스를 사용하며, 라우터에서는 게이트웨이와 전달 경로를 고려해야 합니다. 구체적인 활성화 방법은 현재 클라이언트 UI를 기준으로 확인하세요.

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

아래 항목은 일반적인 데스크톱 환경을 위한 예시입니다. 적용하기 전에 플랫폼에서 지원하는지 확인하세요. auto-route는 트래픽을 가로채는 데 필요한 경로를 설정하고, auto-detect-interface는 아웃바운드 인터페이스를 찾는 데 사용됩니다. 네트워크 어댑터가 여러 개 있거나 가상 머신, 다른 VPN, 컨테이너 네트워크를 사용하는 경우 자동 판단이 기대와 다를 수 있습니다. 연결이 끊기면 먼저 TUN을 끄고 기본 상태로 복구한 뒤 시스템 경로와 인터페이스 선택을 확인하세요.

dns-hijack는 일치하는 일반 DNS 트래픽을 대상으로 하며 모든 HTTPS 암호화 조회를 자동으로 식별하거나 수정하지는 않습니다. 브라우저가 자체 암호화 DNS 경로를 사용한다면 해당 동작이 트래픽 분배 요구와 맞는지 별도로 확인하세요. TUN과 시스템 프록시를 함께 사용할 때는 클라이언트가 자체 트래픽의 루프백을 어떻게 방지하는지도 확인해야 합니다. 출처와 동작을 모르는 트래픽 가로채기 규칙을 여러 겹으로 수동 추가하지 마세요.

문제 해결은 직접 연결 네트워크를 테스트한 뒤 일반 프록시 진입점을 확인하고, TUN을 활성화한 다음 DNS와 도메인 규칙을 점검하는 순서가 좋습니다. TUN을 켰을 때만 문제가 생긴다면 권한, 라우팅, 인터페이스, 다른 네트워크 소프트웨어와의 충돌을 중점적으로 확인하세요. 특정 도메인만 이상하다면 조회와 규칙을 확인합니다. 단계별로 테스트하면 처음부터 DNS 설정 전체를 다시 작성하는 것보다 원인을 명확히 찾기 쉽습니다.

8. 오버라이드, 병합 및 안전한 설정 관리

구독 원본과 최종 실행 설정 구분하기

원격 구독을 업데이트하면 설정 내용이 다시 생성되거나 교체되는 경우가 많습니다. 구독 원본에 규칙을 직접 추가하면 다음 업데이트 전까지만 유지될 수 있습니다. 계속 유지해야 하는 포트, 업무별 분기, DNS 조정은 클라이언트가 지원하는 오버라이드, 병합, 스크립트 기능에 추가하세요. 먼저 기능이 어떤 Profile에 적용되는지 확인한 뒤 수정 위치를 정해야 다른 설정에 의도치 않은 영향을 주지 않습니다.

클라이언트마다 ‘병합’의 정의가 완전히 같지는 않습니다. 맵은 필드별로 재귀 병합할 수 있지만 목록은 전체 교체될 수도 있고, 앞에 추가하거나 뒤에 붙이는 기능을 지원할 수도 있습니다. 스크립트가 병합 후 결과를 다시 바꾸기도 합니다. 이름이 같은 오버라이드 기능이라고 동작까지 같다고 가정하지 마세요. 입력창 내용만 보고 적용 여부를 판단하기보다 작은 규모로 테스트해 최종 설정을 확인하는 것이 가장 확실합니다.

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

예를 들어 업무 도메인을 특정 그룹으로 먼저 보내려면 해당 규칙을 범위가 넓은 규칙 앞에 배치해야 합니다. 파일 끝에 텍스트를 덧붙이는 것만으로는 해결되지 않습니다. 오버라이드가 뒤에 추가하는 방식만 지원하고 구독에 MATCH가 이미 있다면 새 규칙은 매칭되지 않을 수 있습니다. 앞에 추가하는 기능이나 규칙 삽입 기능을 사용하고 최종 설정에서 위치를 확인하세요.

항목 간 참조: 병합 후 연결 관계 다시 확인하기

정책 그룹을 새로 추가할 때는 참조하는 노드, 제공자, 다른 그룹이 실제로 존재하는지 함께 확인해야 합니다. 로컬 그룹 이름을 유지해도 구성원이 계속 유효하다는 보장은 없습니다. 원격 구독에서 노드명이나 제공자명이 바뀔 수 있습니다. 장기간 사용할 업무 규칙은 안정적인 로컬 업무 그룹을 가리키고, 해당 그룹에서 구조가 명확한 출처를 참조하도록 하면 규칙과 원격 노드 이름의 직접 연결을 줄일 수 있습니다.

DNS를 덮어쓸 때는 하위 항목만 바꾸는지 DNS 객체 전체를 다시 만드는지 확인하세요. 상위 DNS만 바꾸려다가 수신 주소, 매핑 모드, 필터 목록까지 사라지면 연결 동작이 함께 바뀔 수 있습니다. 수정 전에 기존 항목을 기록하고, 수정 후 최종 결과와 대조하세요. 다른 설정의 DNS 블록 전체를 가져오는 것을 매개변수 하나만 수정하는 작업으로 여기지 마세요.

경로 항목도 다시 확인해야 합니다. 원본 구독의 상대 경로와 클라이언트 오버라이드 파일의 디렉터리, 코어 실행 디렉터리는 서로 다를 수 있습니다. 다른 기기로 옮기면 파일 제공자와 캐시 경로가 작동하지 않을 수도 있습니다. 파일을 찾을 수 없다는 오류가 발생하면 먼저 작업 디렉터리와 클라이언트가 접근하도록 허용한 위치를 확인하세요. 경로 문제를 덮기 위해 디렉터리 권한을 무작정 넓히지 마세요.

검증 절차: 저장, 로드, 연결, 복구

수정할 때마다 어떤 항목을 바꿨는지, 어떤 연결에 영향을 주려는지, 어떤 대상으로 확인할지, 실패하면 어느 파일로 복구할지 간단히 기록하는 것이 좋습니다. 복잡한 기록은 필요 없지만 일주일 뒤에도 수정 이유를 이해할 수 있어야 합니다. 문제 해결을 위해 임시로 켠 스위치도 표시하고 작업이 끝나면 되돌리세요. 상세 로그, 특수 DNS 예외, 임시 직접 연결 규칙이 계속 남지 않도록 관리해야 합니다.

작업 순서는 네 단계로 정해두면 좋습니다. 먼저 현재 정상 작동하는 설정을 백업하고, 다음으로 문법과 코어 검사를 실행합니다. 이후 적용 후 로드 로그를 확인하고, 마지막으로 새 연결을 만들어 매칭 결과를 확인하세요. 설정 로드 성공은 중간 단계이므로 실제 사용 환경에서도 검증해야 합니다. 반대로 웹사이트가 잠시 열린다고 새 규칙이 적용되었다고 볼 수도 없습니다. 기존 연결이 계속 사용되고 있을 수 있습니다.

테스트할 때는 가능한 한 다른 조건을 그대로 유지하세요. 같은 대상, 같은 진입점, 같은 노드를 사용해 한 가지 변수만 수정 전후로 비교합니다. 구독을 갱신하고 노드를 바꾸고 모드를 전환하고 TUN을 켜는 일을 한꺼번에 하면 결과가 좋아져도 원인을 알 수 없습니다. 안정적인 설정의 가치는 항목을 계속 늘리는 데 있지 않고, 이후의 변경 결과를 설명할 수 있다는 데 있습니다.

복구도 미리 계획해 두어야 하는 일반적인 절차입니다. 최근의 정상 Profile과 오버라이드 내용, 필요한 클라이언트 설정을 보관하세요. 복구 후 다시 로드하고 시스템 프록시나 TUN 상태가 원래대로인지 확인해야 합니다. 백업 파일에는 노드 및 구독 정보가 포함되므로 안전한 위치에 보관하세요. 도움을 요청할 때는 필요한 부분만 추려서 민감한 정보를 삭제한 뒤 오류 내용과 함께 전달하면 됩니다.

설정을 오래 관리하려면 각 항목의 역할을 명확히 나누세요. 구독은 노드 출처를 관리하고, 로컬 오버라이드는 개인 설정을 유지하며, 정책 그룹은 아웃바운드를 구성하고, 규칙은 경로를 선택합니다. DNS와 트래픽 진입 설정은 연결 정보가 올바른 경로로 들어가도록 합니다. 처음 설정할 때는 빠른 시작 가이드를 우선 참고하세요. 장기간 사용하면서 이 페이지의 섹션을 하나씩 확장하면 되며, 처음부터 모든 기능을 켤 필요는 없습니다.