Clash 설정 파일 가이드
YAML 구조, 공통 설정, DNS, 노드, 프록시 그룹, 트래픽 분기 규칙 및 오버라이드 병합
처음 설치하고 구독을 가져온 뒤 연결을 확인하려면 먼저 사용 가이드를 따라 해 보세요. 이 페이지에서는 가져오기 이후 설정을 항목별로 살펴봅니다. 각 필드가 어느 계층에 속하는지, 수정하면 어떤 연결 경로에 영향을 주는지, 실행 결과로 설정을 어떻게 확인하는지 알아봅니다. 예제는 Mihomo가 지원하는 필드를 중심으로 하며, 모든 구형 Clash 코어와 GUI 클라이언트에서 같은 구문을 지원한다는 뜻은 아닙니다. 아래에 적힌 포트, 모드, 스위치는 예시 값입니다. 기기에서 실제로 적용된 값을 확인하려면 예제를 기본값으로 간주하지 말고 현재 적용 중인 설정을 살펴보세요.
YAML 구조 한눈에 보기: 진입점, 출구 및 참조
최상위 키와 내부 계층
mixed-port, mode, dns, proxies, proxy-groups, rules는 각각 용도가 다른 최상위 키입니다. 포트는 앱 요청이 코어로 전달되는 방식을 정의하고, 프록시는 사용할 원격 출구를 정의합니다. 프록시 그룹은 출구를 묶고, 규칙은 요청을 그룹이나 특정 프록시 또는 내장 동작으로 보냅니다. DNS 설정은 도메인 이름을 해석하는 경로를 담당합니다. 파일에서 최상위 블록을 어떤 순서로 작성하든 규칙 실행 순서는 대개 달라지지 않지만, 목록 안의 순서는 설정의 의미를 좌우할 수 있습니다. 특히 규칙 목록을 알파벳순으로 다시 정렬하면 안 됩니다.
파일을 읽을 때는 먼저 들여쓰기를, 다음으로 하이픈을 확인하세요. 콜론 왼쪽은 키, 오른쪽은 값입니다. dns: 아래에 두 칸 들여쓴 enable은 하위 키입니다. 문서에서 쓰는 dns.enable은 필드 경로를 편하게 나타낸 표기일 뿐이며, 보통 점이 포함된 최상위 키로 그대로 작성하면 안 됩니다. 목록 항목은 하이픈과 공백으로 시작합니다. 노드와 프록시 그룹은 여러 키로 구성된 맵 항목인 경우가 많고, 규칙 목록은 보통 한 줄에 문자열 하나씩 작성합니다. 계층이 비슷해 보여도 파싱된 자료형까지 같은 것은 아닙니다. 규칙 항목 앞의 하이픈을 빼면 목록이 아니라 문자열 하나로 처리될 수 있습니다.
독립적으로 검증할 수 있는 기준 설정부터 시작하세요
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxy-groups:
- name: Local
type: select
proxies:
- DIRECT
- REJECT
rules:
- DOMAIN-SUFFIX,example.com,Local
- MATCH,DIRECT
이 설정은 내장 동작만 사용하므로 원격 노드나 구독이 필요하지 않습니다. 로컬 테스트 설정으로 저장해 불러오세요. 프록시 그룹에서 먼저 DIRECT를 선택하고, 다음에는 REJECT를 선택한 뒤 매번 같은 프록시 진입점을 통해 example.com에 새 연결을 만듭니다. 예상 결과는 규칙이 계속 Local을 가리키고 최종 동작만 선택에 따라 바뀌는 것입니다. 나머지 주소는 마지막 MATCH 규칙에 따라 직접 연결됩니다. 이 테스트는 진입점, 규칙, 프록시 그룹의 참조 관계를 확인하기 위한 것으로, 공개 사이트가 항상 접속 가능한지만으로 판단하지 마세요. 브라우저에 남은 이전 페이지보다 연결 기록과 규칙 매칭 결과가 더 유용합니다.
구독 설정을 디버깅할 때는 먼저 참조 관계를 그려 보세요. 앱이 로컬 진입점에 연결되고, 코어가 규칙을 확인해 대상을 정한 뒤, 그 대상이 노드나 다른 그룹을 참조할 수 있습니다. 노드 서버 주소를 시스템 프록시 주소로 착각하거나 프록시 그룹 이름을 프로토콜 종류로 오해하지 마세요. 예를 들어 Local을 Local-Test로 바꾸면 규칙의 세 번째 항목도 함께 바꿔야 합니다. GUI에서 설정 파일 제목만 수정해도 YAML의 참조 이름이 자동으로 바뀌지는 않습니다.
파싱 성공이 올바른 연결 경로를 보장하지는 않습니다
들여쓰기에는 탭이 아닌 공백을 사용하세요. 같은 맵 안에 같은 이름의 키를 중복해서 쓰지 마세요. 로더에 따라 오류가 나거나 뒤의 정의만 남을 수 있습니다. 배열과 맵은 원래 자료형을 유지하고, 불리언 값은 true 또는 false, 포트는 정수로 작성해야 합니다. 숫자나 불리언처럼 보이거나 YAML 구조로 해석될 수 있는 기호가 포함된 문자열은 따옴표로 감싸 자료형을 명확히 하세요. #은 위치에 따라 주석을 시작하므로, 값을 실수로 바꾸지 않도록 설명은 별도 줄에 작성하세요.
저장한 뒤 세 단계로 확인하세요. 먼저 YAML 파싱 여부, 다음으로 코어가 설정을 불러오는지, 마지막으로 요청이 실제로 어떤 경로를 거치는지 확인합니다. 일반 YAML 검사기는 들여쓰기 오류를 찾을 수 있지만, 존재하지 않는 그룹 이름까지 알아내지는 못할 수 있습니다. 코어가 설정을 불러왔더라도 클라이언트가 방금 편집한 파일을 사용 중이라는 보장은 없습니다. 앞의 두 단계는 정상인데 트래픽 동작이 바뀌지 않았다면 설정이 선택되어 있는지, 다시 불러왔는지, 패널의 실행 모드가 파일 값을 덮어쓰는지 확인하세요. 실행 가능한 기준 설정을 하나 보관하고 이후에는 한 번에 한 종류만 수정하면, 문제가 생겼을 때 원인을 쉽게 찾을 수 있습니다.
공통 설정: mixed-port, 리슨 범위 및 실행 모드
먼저 앱이 어떤 진입점으로 연결되는지 확인하세요
mixed-port: 7890은 하나의 로컬 포트에서 HTTP와 SOCKS 프록시를 모두 제공한다는 뜻입니다. port는 HTTP 전용 포트, socks-port는 SOCKS 전용 포트이므로 혼합 진입점을 쓰려고 세 필드를 모두 입력할 필요는 없습니다. 앱 설정에 서버와 포트를 입력하는 칸이 따로 있다면, 로컬에서 사용할 때는 구독 서버 주소가 아니라 루프백 주소와 실제 적용된 포트를 입력하는 것이 일반적입니다. HTTP와 SOCKS 중 무엇을 선택할지는 앱에서 사용하는 프로토콜과 일치해야 합니다. 포트 숫자만 맞춘다고 프로토콜 선택 오류가 해결되지는 않습니다.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
| 필드 | 기능 | 수정 후 확인할 항목 |
|---|---|---|
mixed-port | HTTP와 SOCKS를 함께 제공하는 진입점입니다. | 시스템 프록시와 앱 포트가 이전 값을 가리키는지 확인하세요. |
allow-lan | 다른 기기의 프록시 접속을 허용할지 설정합니다. | 실제 리슨 주소, 접속 범위, 방화벽을 확인하세요. |
mode | 규칙, 전역 또는 직접 연결 모드를 선택합니다. | 현재 GUI 값과 새 연결 경로를 확인하세요. |
log-level | 코어 로그의 상세 수준을 조정합니다. | 이번 다시 불러오기나 연결 기록이 표시되는지 확인하세요. |
포트를 바꾸기 전에 이전 포트를 어떤 프로세스가 사용 중인지 확인하세요. 코어 로그에 주소가 이미 사용 중이라고 나오면 다른 클라이언트가 백그라운드에서 실행 중이거나 클라이언트가 코어를 두 번 실행했을 가능성이 큽니다. 시스템 프록시만 임의의 빈 포트로 지정하지 마세요. 코어가 먼저 정상적으로 리슨하는지 확인한 뒤 시스템 프록시와 앱 설정을 함께 바꿔야 합니다. 반대로 코어가 정상적으로 리슨하는데 브라우저가 직접 연결한다면 브라우저의 프록시 사용 여부, 예외 목록, 해당 주소가 시스템에서 직접 연결로 지정되어 있는지 확인하세요. 시스템 프록시는 해당 설정을 따르는 프로그램에 진입점을 제공할 뿐, 모든 앱의 트래픽을 자동으로 가로채지는 않습니다.
리슨 범위와 트래픽 가로채기는 별개의 설정입니다
allow-lan: false는 이 기기에서만 사용할 때 적합합니다. 신뢰할 수 있는 같은 네트워크의 기기에서 접속해야 하는 경우에만 LAN 접속을 켜고, 코어가 지원하는 리슨 주소와 인증, 호스트 방화벽으로 범위를 제한하세요. 클라이언트 제어 인터페이스와 프록시 진입점은 서로 다른 기능입니다. 프록시를 열기 위해 관리 인터페이스까지 LAN에 공개할 필요는 없습니다. 다른 기기에서는 이 컴퓨터의 루프백 주소로 접속할 수 없습니다. 테스트할 때 대상 컴퓨터의 LAN 주소를 확인하고 네트워크에서 기기 간 통신을 차단하지 않는지도 살펴보세요. 테스트가 끝나면 임시로 열어 둔 진입점을 닫으세요.
TUN은 HTTP 프록시를 앱에 입력하는 방식과 달리 가상 네트워크 어댑터, 라우팅, 플랫폼 권한을 사용하는 별도의 트래픽 경로입니다. 지원 여부는 플랫폼, 코어, 클라이언트 구현에 따라 달라집니다. 시스템 프록시는 정상인데 TUN만 작동하지 않으면 가상 어댑터 생성 여부, 기존 VPN이나 라우팅 설정과의 충돌, DNS 가로채기 상태를 차례로 확인하세요. 포트, 라우팅, DNS를 한꺼번에 바꿔 가며 테스트하면 복구되더라도 실제 원인을 알 수 없습니다.
mode는 코어에 들어온 트래픽의 처리 방식을 정합니다
rule은 규칙에 따라 트래픽을 처리하고, global은 전역 정책에서 선택한 출구를 사용하며, direct는 코어로 들어온 연결을 직접 연결합니다. 전역 모드로 바꿔도 코어에 연결되지 않은 앱에 진입점이 생기지는 않으며, 직접 연결 모드라고 해서 시스템 프록시 설정이 해제되는 것도 아닙니다. 전역 모드를 비교 테스트에 사용할 때는 전역 그룹에서 원하는 출구가 선택되어 있는지 확인하고, 같은 대상에 새 연결을 만들어 비교한 뒤 규칙 모드로 돌아가세요. 동작 차이는 규칙·전역·직접 연결 모드 비교에서 확인할 수 있습니다.
플랫폼별 클라이언트는 별도의 포트, 로그 수준, 모드를 저장했다가 시작할 때 실행 설정에 다시 기록할 수 있습니다. YAML을 직접 수정했는데 값이 원래대로 돌아온다면 바로 재설치하지 말고 GUI 설정이 관여하는지 확인하세요. 현재 클라이언트에 원하는 항목을 조정할 메뉴가 없다면 다운로드 페이지에서 플랫폼별 옵션을 확인할 수 있습니다. 해당 플랫폼에 설치 항목이 있다면 Clash Plus도 살펴보세요. Linux는 해당 플랫폼의 다운로드 목록을 참고하세요. 클라이언트를 바꾸기 전에 실행 가능한 설정을 저장하고, 두 인스턴스가 같은 진입점을 동시에 차지하지 않도록 하세요.
DNS 설정: 강화 모드, 업스트림 및 실제 조회 경로
dns.enable과 enhanced-mode
dns.enable: true는 설정 파일의 DNS 모듈을 활성화하고, enhanced-mode: fake-ip는 강화 모드를 지정합니다. 모듈을 켰다고 해서 시스템과 모든 앱의 DNS 요청이 자동으로 이 모듈에 전달되는 것은 아닙니다. 시스템 프록시, TUN, 앱 자체의 암호화 DNS, LAN 포워딩은 서로 다른 경로를 사용할 수 있습니다. 예상과 다른 DNS 조회가 발생하는지 확인하려면 먼저 어느 기기와 앱에서 어떤 방식으로 트래픽을 처리하는지 분명히 한 뒤 해당 조회가 실제로 어느 리졸버에 전달됐는지 확인해야 합니다. 공용 리졸버 이름 하나만 보고 로컬에서 직접 조회했는지 원격에서 조회했는지 판단할 수는 없습니다.
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- 'localhost'
- '+.lan'
nameserver:
- system
여기서 system은 해당 구문을 지원하는 Mihomo에서 시스템 리졸버를 업스트림 예제로 사용하는 설정이며, 별도의 공용 DNS를 지정하지 않습니다. 시스템 리졸버가 이미 다른 구성 요소를 통해 전달된다면 같은 조회가 코어로 되돌아가 루프가 생기지 않는지 먼저 확인하세요. 이 예제에는 별도의 DNS 리슨 주소도 없습니다. 코어를 명시적인 DNS 서버로 사용하려면 리슨 주소와 방화벽 범위를 별도로 점검해야 합니다. enable: true만 보고 특정 주소에서 서비스가 열렸다고 판단하면 안 됩니다.
fake-ip 모드에서는 코어가 도메인에 대응하는 가상 주소를 반환하고, 이후 연결이 코어를 통과할 때 매핑을 이용해 원래 대상을 찾을 수 있습니다. 테스트에서 해당 주소 대역이 보인다고 해서 웹사이트의 실제 주소가 그 값으로 바뀐 것은 아닙니다. 앱이 가상 주소를 보관하고 후속 연결이 코어에 전달되지 않거나, 코어를 재시작하면서 매핑이 사라지면 이름은 조회되지만 연결은 실패할 수 있습니다. 비교 테스트에서는 새 연결을 만들고 앱과 운영체제에 남아 있는 이전 결과도 제외하세요. redir-host는 실제 조회 결과를 반환하는 방식입니다. 모드 전환이 모든 DNS 문제를 해결하는 것은 아닙니다.
일반 조회, 예외 및 노드 주소 조회 구분하기
nameserver는 일반 업스트림 목록이고, nameserver-policy는 특정 도메인에 별도의 조회 경로를 지정합니다. proxy-server-nameserver를 지원하는 코어에서는 프록시 서버 도메인 조회도 별도로 설정할 수 있습니다. 노드 서버를 도메인으로 지정한 경우 이 구분이 중요합니다. 도메인을 조회하려면 아직 실행되지 않은 같은 프록시에 먼저 연결해야 한다면 의존성 루프가 생깁니다. 설정을 바꾸기 전에 도메인 이름을 사용하는 업스트림, 해당 업스트림의 초기 연결 방법, 노드 서버 자체를 조회하는 리졸버를 정리하세요. 모든 종류의 조회를 생각 없이 같은 경로로 보내지 마세요.
fake-ip-filter는 가상 주소를 반환하는 방식을 처리하며, 접속 권한이나 프록시 분기 규칙을 설정하는 항목이 아닙니다. 특정 LAN 서비스 도메인을 예외에 추가하면 앱이 실제 주소를 읽어야 하는 문제를 해결할 수 있습니다. 다만 해당 실제 주소에 접속할 수 있는지는 업스트림이 이를 알고 있는지, 로컬에 적절한 경로가 있는지, 규칙이 어떤 출구를 선택하는지에 달려 있습니다. 문제를 확인할 때는 먼저 네트워크에서 해당 서비스의 조회 기록을 사용할 수 있는지 확인하고 예외 범위를 좁히세요. 모든 도메인에 포괄적인 예외를 적용하면 강화 모드 전체의 동작이 달라져 어떤 앱에 특수 처리가 필요한지 나중에 파악하기 어렵습니다.
DNS 누수 여부를 확인하는 방법
먼저 기대하는 동작을 정하세요. 예를 들어 내부 도메인은 지정한 사내 리졸버로 보내고, 특정 앱의 공용 도메인 조회는 현재 네트워크의 기본 경로로 보내지 않는 식입니다. 그런 다음 같은 앱으로 반복 테스트하면서 코어가 해당 도메인을 받았는지, 설정한 업스트림을 사용했는지, 앱 자체의 보안 DNS가 켜져 있는지 확인하세요. 브라우저 테스트 페이지는 브라우저가 보낸 조회만 보여줄 뿐 시스템 전체를 대표하지 않습니다. 명령줄 도구도 서버를 직접 지정하면 실제 앱 경로를 우회할 수 있습니다. 비교할 때는 프록시 모드, TUN 상태, 조회 결과를 함께 기록해 서로 다른 환경의 결과를 혼동하지 않도록 하세요.
프록시 노드 필드: 프로토콜, 주소 및 전송 설정
name은 참조 이름, server는 연결 주소입니다
proxies는 노드를 직접 나열하는 목록입니다. 노드의 name은 프록시 그룹과 규칙에서 참조하고, type은 코어가 나머지 필드를 어떤 프로토콜로 해석할지 정하며, server와 port는 프록시 서버가 실제로 리슨하는 위치를 나타냅니다. GUI에서 노드에 아이콘, 별칭, 메모를 표시할 수 있지만 실제 연결에는 적용 중인 설정의 필드가 사용됩니다. 서버 포트와 로컬 mixed-port는 서로 다른 연결 구간이므로 숫자가 같아도 자동으로 연결되지는 않습니다. 한 설정 안에서 이름이 겹치지 않도록 하고 기존 그룹 이름이나 내장 동작 이름도 피하세요.
proxies:
- name: Local-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
proxy-groups:
- name: Route
type: select
proxies:
- Local-SOCKS
- DIRECT
rules:
- MATCH,Route
이 항목을 최소 기준 설정에 추가하면 이미 실행 중인 로컬 SOCKS5 서비스를 참조할 수 있습니다. 해당 서비스까지 생성해 주는 것은 아닙니다. 루프백 주소의 1080 포트에서 별도 프로그램이 리슨하지 않는다면 Local-SOCKS를 선택했을 때 연결이 실패하는 것이 정상입니다. 해당 주소가 같은 코어 인스턴스의 프록시 진입점을 가리키게 하면 자기 자신을 참조하는 구조가 됩니다. DIRECT를 선택해 프록시 업스트림이 문제인지 비교해 보세요. 이 예제를 사용하는 앱의 요청은 별도로 설정한 로컬 코어 진입점으로 보내야 합니다. 노드의 업스트림 주소와 진입점 주소를 혼동하지 마세요.
프로토콜 전용 옵션은 서로 바꿔 쓸 수 없습니다
노드마다 인증 필드와 전송 설정이 다릅니다. HTTP나 SOCKS5는 사용자 인증을 사용할 수 있고, 다른 유형은 해당 프로토콜 전용 식별자, 암호화 설정, 핸드셰이크 매개변수가 필요할 수 있습니다. 값은 서버 또는 구독에서 제공한 원본 설정을 사용하세요. 다른 유형의 노드 필드를 통째로 복사하거나 type만 다른 프로토콜로 바꿔도 코어와 서버의 핸드셰이크가 일치하지 않습니다. 가져오기 도구로 설정을 변환할 때는 정수, 불리언, 중첩 맵, 문자열이 원래 자료형을 유지하는지도 확인하세요.
TLS를 사용하는 노드는 연결 주소와 인증서의 신원도 고려해야 합니다. 주소는 연결할 서버를 지정하고, 서버 이름 등의 매개변수는 TLS 핸드셰이크에 사용될 수 있습니다. 일부 프록시 앞단 서비스는 전송 계층 외부의 호스트 이름이나 요청 경로를 기준으로 트래픽을 전달하기도 합니다. 세 값이 우연히 같을 수는 있지만 같은 필드는 아닙니다. 인증서 오류가 발생하면 인증서 검증을 끄는 것을 장기적인 해결책으로 삼지 말고 시스템 시각, 노드에서 요구하는 서버 이름, 실제 제공되는 인증서를 확인하세요. 연결은 되었지만 서버가 요청을 거부한다면 경로, 인증 정보, 서버의 프로토콜 지원 여부를 확인하세요.
가져오기 문제와 연결 문제를 나눠서 확인하세요
노드가 GUI에 전혀 표시되지 않으면 먼저 설정이 로드됐는지, 구독 업데이트가 성공했는지, 그룹이 해당 소스를 참조하는지, 필터 조건이 노드를 제외했는지 확인하세요. 노드는 보이지만 사용할 수 없다면 노드 서버의 도메인 조회, 대상 포트 접속, 프로토콜 핸드셰이크, 실제 서비스 요청을 각각 점검하세요. GUI의 테스트 결과는 특정 요청 한 번을 관찰한 것일 뿐 인증 실패, 주소 접근 불가, 특정 전송 방식 미지원의 원인을 단독으로 설명하지 못합니다. 여러 노드를 계속 바꾸기보다 노드 로드 전후의 로그를 확인하면 첫 번째 이상 지점을 찾기 쉽습니다.
구독은 proxy-providers를 통해 노드를 제공할 수도 있습니다. 이때 최상위 proxies에 모든 항목이 나열되지 않을 수 있으며, 그룹은 보통 use로 소스를 참조합니다. 소스 이름과 노드 이름은 서로 다른 참조 단계입니다. 구독을 업데이트한 뒤 노드가 사라졌다면 소스가 로드되지 않았는지, 필터 조건에 걸렸는지, 상위 제공자가 이름을 바꿨는지 먼저 확인하세요. 그룹 구성원의 업데이트 전후 차이를 기록하고 인증 정보가 포함된 전체 설정을 공개 채널에 올리지 마세요. 모든 노드가 동시에 실패한다면 노드 시간 초과 문제 해결 체크리스트를 참고해 구독, 시각, 진입점, 시스템 네트워크 등 공통 원인부터 확인하세요.
프록시 그룹 필드: select, url-test 및 fallback
그룹의 역할을 먼저 정한 뒤 유형을 선택하세요
proxy-groups는 프록시 그룹 목록입니다. select는 사용자가 선택하므로 수동 비교나 고정 출구에 적합합니다. url-test는 지정한 주소의 테스트 결과로 구성원을 고르고, fallback은 구성원 순서로 우선순위를 정해 사용 가능한 항목 중 앞에 있는 것을 선택합니다. 자동 그룹은 여러 연결을 하나로 합쳐 속도를 높이는 기능이 아닙니다. 특정 출구를 우선 사용하고 실패하면 예비 출구로 전환하려는 목적이라면, 탐지 지연 시간을 조정해 우선순위를 흉내 내기보다 fallback을 사용하는 편이 명확합니다.
proxy-groups:
- name: Manual
type: select
proxies:
- DIRECT
- REJECT
- name: Probe
type: url-test
proxies:
- DIRECT
url: 'https://example.com/'
interval: 300
tolerance: 50
- name: Preferred
type: fallback
proxies:
- Manual
- DIRECT
url: 'https://example.com/'
interval: 300
rules:
- DOMAIN-SUFFIX,example.com,Preferred
- MATCH,Manual
이 예제는 원격 구독에 의존하지 않도록 구성했습니다. Probe에는 구성원이 하나뿐이므로 탐지 설정을 확인하는 용도이며 실제 노드 비교는 하지 않습니다. Preferred는 그룹 참조와 구성원 순서를 보여줍니다. 실제로 사용할 때는 내장 동작 대신 존재 여부를 확인한 노드를 넣고, 각 후보가 도달할 수 있으며 주기적으로 요청해도 괜찮은 가벼운 테스트 주소를 선택하세요. 예제의 interval: 300은 초 단위 테스트 간격이고, tolerance: 50은 자동 지연 시간 비교의 허용 오차를 밀리초 단위로 지정해 작은 차이로 인한 잦은 전환을 줄입니다. 저장한 뒤 코어가 그룹을 실제로 어떻게 처리하는지 확인하고, GUI에 한 번 표시된 숫자만으로 전환 시점을 판단하지 마세요.
숫자만 보지 말고 테스트 조건도 확인하세요
탐지 경로는 설정된 테스트 주소까지만 확인합니다. 이 과정의 DNS 조회, 연결, 핸드셰이크, 응답은 실제 서비스 주소와 다를 수 있습니다. 가벼운 테스트에는 빠르게 응답하면서 장시간 다운로드에서는 처리량이 제한되는 출구도 있고, 테스트 도메인에 접속할 수 없어 자동 선택에서 제외되는 경우도 있습니다. 비교할 때는 먼저 같은 주소로 다시 테스트하고, 다음에는 실제 서비스 요청을 비교하세요. 측정의 한계를 더 알아보려면 지연 시간 측정값과 실제 인터넷 속도를 참고하세요.
테스트 주소가 설정된 그룹과 프록시 소스 자체의 상태 점검은 설정이나 실행 시점이 다를 수 있습니다. 소스의 상태가 정상이라고 해서 이를 참조하는 그룹도 완전히 같은 조건으로 구성원을 선택한다고 볼 수는 없습니다. 문제를 확인할 때 GUI에 표시된 항목이 노드 수동 테스트인지, 그룹 탐지인지, 소스 상태 점검인지 구분하고 각 항목의 주소와 간격을 확인하세요. 탐지를 너무 자주 실행하면 네트워크 요청이 늘고 모바일 기기에서는 깨우기 비용도 커질 수 있습니다. 문제 해결을 위해 일시적으로 수동 테스트를 사용할 수는 있지만, 장기 탐지 빈도를 높이는 것은 연결 문제의 해결책이 아닙니다.
참조 관계와 선택 상태 저장을 확인하세요
proxies는 프록시 그룹 안에서는 구성원 이름을 뜻하며, 최상위에서 노드를 정의하는 같은 이름의 필드와는 다릅니다. 구성원에는 내장 동작, 노드 이름, 참조 가능한 그룹을 넣을 수 있습니다. use에는 프록시 소스 이름을 나열합니다. 그룹끼리 순환 참조하지 않도록 하세요. 그룹이 비어 있다면 소스가 로드되었는지, 필터 조건으로 구성원이 모두 제외되었는지, 프런트엔드가 현재 설정을 표시하는지 확인하세요. 여러 단계로 그룹을 중첩하면 수동 선택과 자동 정책을 분리할 수 있지만, 계층이 너무 많으면 GUI에는 상위 그룹 이름만 표시될 수 있습니다. 연결 경로를 확인할 때는 최종 출구까지 차례로 따라가세요.
다시 불러온 뒤에도 이전에 선택한 구성원이 계속 선택되어 있다고 해서 YAML 순서가 반영되지 않았다는 뜻은 아닙니다. 프런트엔드나 코어 설정에서 선택 상태를 저장할 수 있습니다. 순서나 자동 전환을 확인하려면 현재 수동 선택값을 기록하고 기존 연결이 아닌 새 연결로 테스트하세요. 기존 장시간 연결은 그룹 선택을 바꿔도 즉시 다른 경로로 옮겨가지 않는 경우가 많습니다. 그룹 이름, 참조 관계, 사용 가능 여부가 모두 정상인데도 잘못된 경로를 사용한다면 규칙이 해당 그룹과 일치하는지 확인하세요. 더 앞선 규칙이 다른 정책으로 보냈다면 현재 그룹의 순서를 바꿔도 결과는 달라지지 않습니다.
규칙 구문: 첫 번째로 일치하는 항목부터 최종 처리까지
위에서 아래로 확인하며, 더 정확한 규칙이라고 자동으로 앞당겨지지 않습니다
rules는 규칙 목록입니다. 일반적인 항목은 유형, 매칭 값, 대상 순으로 구성되며 유형에 따라 추가 매개변수가 붙을 수 있습니다. DOMAIN은 정확한 도메인을, DOMAIN-SUFFIX는 지정한 도메인과 하위 도메인을, IP-CIDR은 주소 대역을 매칭합니다. GEOIP는 해당 지역 데이터를 사용합니다. MATCH에는 매칭 값이 필요하지 않으며 보통 마지막에 둡니다. 코어는 위에서부터 확인해 처음 조건에 맞는 항목을 선택합니다. 포괄적인 규칙을 예외보다 앞에 두면 뒤의 예외가 더 정확하더라도 실행되지 않습니다.
rules:
- DOMAIN,blocked.example.com,REJECT
- DOMAIN-SUFFIX,example.com,DIRECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- MATCH,DIRECT
이 부분을 기준 설정에 적용하면 도메인 정보가 확인되는 새 요청은 blocked.example.com에 대해 첫 번째 규칙과 일치합니다. 같은 접미사를 가진 다른 요청은 두 번째 규칙과 일치할 수 있습니다. 마지막 직접 연결 규칙은 원격 노드가 없는 환경에서도 테스트할 수 있도록 둔 것이며, 실제 운영 설정에서 기본적으로 직접 연결해야 한다는 뜻은 아닙니다. 대상을 사용자 정의 정책으로 바꾸려면 같은 설정 안에 해당 노드나 그룹을 먼저 정의하세요. 예제의 주소 대역은 흔히 쓰이는 사설 주소 일부만 포함하므로 로컬 주소나 사설 네트워크 전체 목록으로 오해하지 마세요.
| 유형 | 판단 기준 | 놓치기 쉬운 조건 |
|---|---|---|
DOMAIN | 정확한 도메인입니다. | 요청의 도메인이 코어에 전달되지 않을 수 있습니다. |
DOMAIN-SUFFIX | 도메인 접미사입니다. | 더 구체적인 예외를 앞에 두는 것이 일반적입니다. |
IP-CIDR | 목적지 주소 대역입니다. | 도메인 조회가 필요할 수 있으며 주소 계열도 구분해야 합니다. |
GEOIP | 목적지 IP에 해당하는 지역 데이터입니다. | 도메인 접미사로 지역을 판별하는 방식이 아닙니다. |
MATCH | 앞선 규칙에 일치하지 않은 요청입니다. | 너무 앞에 두면 뒤의 규칙이 적용되지 않습니다. |
도메인 정보와 목적지 주소가 항상 함께 있는 것은 아닙니다
규칙은 코어에 들어오고 필요한 정보를 갖춘 트래픽에만 적용됩니다. 앱이 주소에 직접 연결하면 코어가 그 주소에 대응하는 원래 도메인을 모를 수 있습니다. 시스템 프록시를 사용하는 앱은 호스트 이름을 프록시에 전달할 수도 있고, 먼저 조회한 뒤 주소를 전달할 수도 있습니다. 도메인 스니핑을 사용하는 환경에서 도메인을 복원할 수 있는지는 프로토콜과 실제로 확인 가능한 데이터에 따라 달라집니다. 도메인 규칙이 적용되지 않는다면 접미사 범위를 무작정 넓히기보다 연결 기록의 호스트명이나 주소 필드를 먼저 확인하세요.
no-resolve를 사용하면 해당 주소 규칙이 이번 매칭을 위해 추가 조회를 수행하지 않도록 할 수 있습니다. 이미 사용할 수 있는 목적지 주소가 있다면 그 주소로 계속 판단합니다. 이 설정은 DNS를 전역으로 끄는 스위치가 아니며, 도메인을 주소 대역에 억지로 일치시키지도 않습니다. 도메인이 아직 조회되지 않았고 비교할 주소도 없다면 해당 규칙을 건너뛰고 다음 항목으로 넘어갈 수 있습니다. GEOIP를 사용할 때는 코어에서 필요한 데이터를 사용할 수 있는지, 실제 목적지가 기대한 분류에 속하는지도 확인하세요. 사이트가 여러 주소를 사용하거나 서로 다른 네트워크를 통해 서비스될 수 있으므로, 사이트가 어느 지역에 속한다는 직감만으로 매칭 기록을 대신할 수는 없습니다.
규칙 세트도 의존성이 있는 설정 항목으로 다루세요
rule-providers는 외부 규칙 세트를 제공하고, RULE-SET은 기본 규칙 목록에서 해당 이름을 참조합니다. 데이터 형식과 규칙 분류가 사용하는 코어 및 규칙 세트의 실제 내용과 맞아야 합니다. 파일 확장자만 보고 판단하지 마세요. 가져온 뒤 소스가 로드되었는지, 기본 목록에서 참조가 어느 위치에 있는지 확인하세요. 같은 규칙 세트라도 구체적인 예외의 앞뒤 중 어디에 두는지에 따라 결과가 달라질 수 있습니다. 소스를 새로고침하면 규칙 적용 범위가 바뀔 수 있으므로 특정 도메인을 조사할 때는 GUI의 두 날짜 상태만 비교하지 말고 실제로 일치한 규칙과 소스를 기록하세요.
웹페이지는 보통 여러 연결을 생성합니다. 기본 페이지, 로그인, 이미지, API가 각각 다른 도메인을 사용할 수 있으며, 기본 도메인에 적용된 정책이 모두 같은 출구를 사용하도록 만들지는 않습니다. 페이지 일부가 로드되지 않는다면 실패한 요청을 찾아 규칙 모드에서 같은 도메인의 새 연결을 확인하고 일치한 규칙, 정책 이름, 최종 출구를 살펴보세요. 실패한 항목이 현재 설정에 아예 없다면 먼저 클라이언트가 사용하는 병합 결과를 확인하세요. 기존 연결, 캐시, 모드 전환도 파일 내용과 다른 결과처럼 보이게 할 수 있습니다.
오버라이드 및 병합: 구독 원본부터 실제 실행 설정까지
구독, 오버라이드, 실행 복사본 구분하기
구독 원본은 상위에서 제공하는 입력이고, 오버라이드는 로컬에서 유지하는 수정 사항이며, 실행 복사본은 클라이언트 설정과 병합 작업을 거쳐 코어에 전달되는 결과입니다. ‘수정했는데 사라졌다’는 문제는 지속적으로 보관되는 오버라이드가 아니라 구독 새로고침으로 덮어쓰는 캐시나 실행 복사본을 편집했을 때 자주 발생합니다. 시작하기 전에 GUI의 편집 메뉴가 어느 계층에 속하는지 확인하고, 수정 전 실행 가능한 로컬 복사본을 보관하세요. 프런트엔드에서 병합 결과를 내보낼 수 없다면 최소한 활성화한 설정, 오버라이드 메뉴, 적용 범위, 로드 로그를 기록해 미리보기와 실제 실행 상태를 혼동하지 않도록 하세요.
스칼라, 맵, 목록은 같은 방식으로 해석하면 안 됩니다. 스칼라는 보통 값을 바꾸는 방식입니다. 예를 들어 모드 문자열을 다른 값으로 바꿉니다. 맵은 키별로 병합되거나 통째로 교체될 수 있습니다. 예를 들어 dns.enable만 중첩 설정에 적었을 때 기존 업스트림이 유지되는지는 병합기에 따라 다릅니다. 목록은 교체, 앞에 추가, 뒤에 추가를 구분해야 합니다. 모두 ‘항목을 하나 추가’하는 것처럼 보여도 첫 번째 일치 항목을 사용하는 규칙 시스템에서는 결과가 달라집니다. 현재 클라이언트가 해당 문법을 실제로 지원할 때만 prepend-rules 같은 오버라이드 키를 사용하세요. 모든 코어가 인식하는 일반 최상위 필드가 아닙니다.
병합기 동작을 짐작하지 말고 병합 결과에서 순서를 확인하세요
구독에 규칙 두 개가 있고 정확한 예외 하나를 추가한다고 가정해 보겠습니다. 아래는 입력과 목표 결과를 보여주는 예시이며, 모든 클라이언트가 같은 오버라이드 형식을 쓴다고 가정하지 않습니다. 편집기에서 규칙을 앞에 추가할 수 있다면 예외를 하나 입력하고 결과를 확인하세요. 배열 전체를 교체하는 기능만 있다면 완성된 목록을 제출해야 하며, 이후 구독이 업데이트될 때 목록을 직접 관리해야 합니다. 어느 방식을 쓰든 마지막 기본 처리 규칙은 유지해야 합니다.
# 구독 원본의 규칙
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- MATCH,DIRECT
# 예상되는 병합 결과
rules:
- DOMAIN,blocked.example.com,REJECT
- DOMAIN-SUFFIX,example.com,DIRECT
- MATCH,DIRECT
편집기가 예외를 목록 끝에 추가하면 기본 처리 규칙에 막힙니다. 접미사 규칙 다음이면서 기본 처리 규칙 앞에 넣어도 접미사 규칙에 먼저 일치합니다. 그룹 정의도 오버라이드해야 한다면 병합기가 이름으로 특정 항목을 수정하는지, 그룹 목록 전체를 교체하는지 확인하세요. 목록 전체를 교체하는 방식에서는 같은 이름의 그룹 하나만 제출해도 해당 그룹만 갱신되는 것이 아닐 수 있습니다. 다른 그룹이 모두 사라지고 기존 규칙은 여전히 그 그룹을 참조할 수 있습니다. 먼저 필드 하나만 시험해 병합 전후의 차이를 확인한 다음 더 큰 로컬 수정 사항을 관리하는 방법을 정하세요.
되돌릴 수 있는 순서로 검증하고 복구하세요
규칙, DNS, 진입점 변경을 각각 따로 저장하면 어느 계층에서 문제가 생겼는지 찾기 쉽습니다. 먼저 오버라이드 없이 실행되는지 확인하고, 항목 하나씩 활성화해 코어가 다시 로드되는지 확인하세요. 영향을 받아야 하는 연결 하나와 그대로여야 하는 연결 하나를 비교한 뒤 구독을 직접 새로고침해 결과를 다시 확인합니다. 상위 제공자가 그룹 이름을 바꿨는지, 소스가 없는지, DNS 하위 키가 통째로 교체됐는지, 프런트엔드가 포트를 자동으로 다시 기록했는지 특히 살펴보세요. 이런 문제는 처음 저장할 때는 드러나지 않고 구독 업데이트나 클라이언트 재시작 후에 나타날 수 있습니다.
시작 단계에서 실패하면 최근 오버라이드를 먼저 끄고 정상 작동이 확인된 설정을 다시 불러온 다음, 위치를 찾는 데 도움이 되는 첫 번째 명확한 오류를 보관하세요. 코어는 시작되지만 연결에 문제가 있다면 현재 모드, 앱 진입점, 일치한 규칙을 비교해 여러 구성 요소가 동시에 네트워크 설정을 바꾸고 있지 않은지 확인하세요. 클라이언트를 종료하려면 먼저 클라이언트가 설정한 시스템 프록시를 복원하고 현재 네트워크에서 앱이 예상대로 직접 연결되는지 확인하세요. 처음 설정을 가져오고 활성화하는 자세한 방법은 사용 가이드를 참고하세요. 코어와 프런트엔드의 차이가 익숙하지 않다면 용어집도 확인해 보세요.
오버라이드를 수정했는데도 패널에 이전 값이 표시되는 이유는 무엇인가요?
패널에 표시된 값이 구독 원본인지, 클라이언트 자체 설정인지, 코어의 현재 실행 값인지 먼저 구분하세요. 그런 다음 오버라이드가 활성화되어 현재 설정에 적용되는지, 병합 오류가 없는지, 클라이언트를 다시 불러왔는지 확인하세요.
문제가 오버라이드 때문인지 구독 때문인지 어떻게 확인하나요?
같은 클라이언트와 네트워크에서 오버라이드를 잠시 끄고 원본 구독을 다시 불러온 뒤 새 연결을 만드세요. 문제가 해결되면 오버라이드를 하나씩 다시 활성화하며 결과를 비교하세요. 계속 문제가 발생한다면 구독 업데이트, 진입점, 코어 로그부터 확인하세요.