CONFIG.YAML / 필드 가이드
Clash 설정 파일 필드 레퍼런스
YAML 로드부터 규칙 적용까지: 필드 유형, 참조 관계, 적용 범위.
사용 가이드에서는 첫 가져오기와 연결 확인을 다룹니다. 이 페이지에서는 필드별 작성법과 문제 해결 기준을 찾아볼 수 있습니다. 사용할 설정이 아직 없다면 먼저 가이드의 단계를 따라 해 보세요. 포트, 이름 해석, 트래픽 라우팅에 문제가 생기면 아래 목차에서 해당 항목을 찾으면 됩니다. 이 문서는 mihomo를 기준으로 하며, 클라이언트 화면의 옵션과 오버라이드 방식은 실제 제품에 따라 다를 수 있습니다.
01 YAML / STRUCTURE
YAML 구조, 필드 유형 및 참조 관계
최상위 필드부터 확인하고 트래픽 흐름을 따라가기
Clash 설정 파일의 최상위 구조는 매핑이지, 파일의 줄 번호 순서대로 실행되는 명령 목록이 아닙니다. 최상위 필드는 진입점으로 생각하면 됩니다. 포트와 작동 모드는 요청이 커널에 들어오는 방식을 정하고, DNS 섹션은 내장 리졸버의 응답 방식을 지정합니다. 노드 섹션은 연결 방법을 정의하고, 프록시 그룹은 선택할 수 있는 출구를 나열하며, 규칙 섹션은 연결을 어느 출구로 보낼지 결정합니다. 규칙 섹션을 파일 맨 앞으로 옮겨도 커널 초기화보다 먼저 실행되지는 않습니다. 반면 같은 목록에서 규칙 항목의 순서를 바꾸면 최종 라우팅 결과가 달라질 수 있습니다. 따라서 두 파일을 비교할 때는 최상위 필드의 위치와 목록 항목 간 순서를 구분해야 합니다.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups:
- name: 수동 출구
type: select
proxies:
- DIRECT
rules:
- DOMAIN-SUFFIX,example.org,수동 출구
- MATCH,DIRECT
이 완전한 예시에는 원격 노드가 없으므로 파일 로드와 로컬 진입점을 먼저 확인하기 좋습니다. 규칙이 대상 도메인과 일치하면 연결은 먼저 「수동 출구」 그룹으로 전달됩니다. 그룹에는 DIRECT만 있고, 그 외 요청도 마지막 규칙에서 DIRECT로 처리됩니다. 이 설정으로 테스트했을 때 웹페이지가 열린다면 DIRECT 경로가 작동한다는 뜻일 뿐, 프록시 서버에 연결되었다는 의미는 아닙니다. 특정 규칙이 실제로 적용됐는지 확인하려면 페이지가 열리는지만으로 판단하지 말고 클라이언트의 새 연결 기록도 함께 살펴보세요. 다른 프록시 프로그램이 예시 포트를 사용 중이라면 비어 있는 포트를 선택한 뒤 테스트 앱도 같은 포트에 연결해야 합니다.
같은 이름의 필드라도 계층을 구분하기
같은 키도 계층에 따라 의미가 다를 수 있습니다. 최상위의 proxies는 노드 객체 목록이고, 프록시 그룹 안의 proxies는 구성원 이름 목록입니다. 전자는 각 항목에 여러 속성을 작성하고, 후자는 이름 하나씩 작성합니다. 노드 객체를 그룹 구성원 아래에 잘못 들여쓰기하면 문서 자체는 유효한 YAML이더라도 커널이 필드 유형 오류로 로드를 거부할 수 있습니다. 그룹 이름을 바꾼 뒤에는 해당 그룹을 참조하는 다른 그룹과 규칙도 찾아 수정해야 합니다. 정의만 바꾸고 참조를 그대로 두면 이전에는 로드되던 문서가 적용되지 않을 수 있습니다.
| 필드 | 데이터 형태 | 편집할 때 확인할 사항 |
|---|---|---|
mixed-port | 정수 | 클라이언트의 실제 진입점과 일치하는가 |
dns | 매핑 | 각 키가 같은 부모 키 아래에 들여쓰기되어 있는가 |
proxy-groups | 객체 목록 | 이름과 모든 구성원을 참조할 수 있는가 |
rules | 문자열 목록 | 목록 순서가 매칭 우선순위에 맞는가 |
문법, 설정 검증, 실행 결과를 나눠서 확인하기
문법 오류는 먼저 들여쓰기, 따옴표, 목록 표시를 확인하고 필드 오류는 유형과 참조 관계를 살펴보세요. 탭 대신 공백으로 들여쓰고, 같은 부모 키 아래의 필드는 같은 수준에 맞춥니다. 목록 항목의 하이픈 뒤에는 공백을 둡니다. 주석으로 해석될 수 있는 샵 기호나 콜론 뒤에 공백이 있는 값은 문자열 범위를 명확히 하도록 따옴표로 감싸세요. 포트와 불리언 값은 해당 유형을 유지하고, 원래 문자열이어야 하는 값에만 필요한 경우 따옴표를 사용합니다. 서식이 있는 텍스트를 복사했다면 전각 콜론과 곡선 따옴표도 확인하세요. 비슷해 보여도 YAML 문법 기호를 대신할 수 없습니다.
설정 오류에 표시된 줄 번호는 파서가 문제를 발견한 위치이지, 처음 잘못 작성한 줄이라고 단정할 수는 없습니다. 특정 줄에서 키가 없다는 오류가 나오면 앞 항목의 따옴표가 닫히지 않았는지, 하위 항목의 들여쓰기가 한 단계 빠졌는지 먼저 확인하세요. YAML 파싱을 통과한 다음에는 최상위 키 중복, 이름 충돌, 존재하지 않는 참조를 점검합니다. 같은 매핑에 규칙 키가 두 번 있다고 해서 커널이 두 목록을 합치는 것은 아닙니다. 파서에 따라 하나를 거부하거나 덮어쓸 수 있으므로 같은 계층의 키는 한 곳에만 두세요.
마지막으로 실제 적용 중인 파일에 수정 사항이 반영됐는지 실행 결과로 확인하세요. 클라이언트에 다운로드된 구독 복사본이 보여도 현재 로드된 파일은 다른 로컬 설정일 수 있습니다. 새 설정의 검증에 실패해 이전 설정을 계속 사용할 수도 있습니다. 현재 설정 이름과 적용 시각, 새 연결 하나의 매칭 결과를 기록해 예상과 비교하세요. 기존 연결은 생성 당시의 출구를 계속 사용할 수 있으므로 설정을 바꾼 뒤에는 요청을 새로 보내야 합니다. 파일이나 구독을 처음 가져올 때는 설정 가져오기 단계에 따라 현재 활성 항목을 확인한 뒤 필드 문제를 살펴보세요.
02 INBOUND / MODE
공통 필드: 포트, 리스닝, 작동 모드
앱이 어느 로컬 진입점에 연결되는지 먼저 확인하기
진입 포트는 앱과 커널 사이의 연결을 뜻하며 프록시 서버의 포트가 아닙니다. port는 HTTP 프록시, socks-port는 SOCKS 프록시, mixed-port는 하나의 포트에서 두 종류의 인바운드 프로토콜을 받습니다. 처음 문제를 해결할 때는 진입점을 하나만 남겨두는 편이 원인을 찾기 쉽습니다. 브라우저나 시스템 프록시가 HTTP를 사용한다면 주소와 포트가 HTTP 또는 혼합 진입점과 일치해야 합니다. SOCKS를 지원하는 프로그램에서만 해당 SOCKS 설정을 사용하세요. 앱에 자동 설정 주소와 별도의 수동 프록시가 모두 저장되어 있다면 실제로 어느 설정을 사용하는지 먼저 확인하세요.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
예시에서는 혼합 진입점을 로컬에서만 사용하도록 설정했습니다. 클라이언트의 시스템 프록시 기능은 보통 시스템이 커널 주소를 가리키도록 설정할 뿐, 모든 프로그램이 이를 따르게 하지는 않습니다. 일부 앱은 자체 네트워크 설정을 사용하고, 서비스는 환경 변수에서 프록시 주소를 읽기도 하며, 자체 연결 방식을 사용하는 프로그램도 있습니다. 특정 프로그램이 프록시를 통하는지 확인하려면 새 요청을 별도로 보내고 클라이언트의 연결 화면에 해당 대상이 표시되는지 확인하세요. 연결 기록조차 없다면 그룹을 계속 바꾸기보다 앱의 프록시 설정, 시스템 예외 목록, 리스닝 포트를 먼저 살펴보세요.
같은 리스닝 포트의 충돌을 확인한 뒤 접근 범위를 조정하기
같은 주소의 같은 포트를 여러 동종 리스너에 임의로 할당할 수는 없습니다. 설정에서 HTTP 진입점과 혼합 진입점에 같은 포트를 지정하거나 두 클라이언트가 같은 포트를 동시에 사용하면 바인딩에 실패할 수 있습니다. 시작 로그에 주소 사용 중 오류가 나타나면 혼합 진입점, 컨트롤 인터페이스, 내장 DNS 중 어떤 리스너가 실패했는지 확인하세요. 노드 포트를 무작정 바꾸지 마세요. 포트를 점유한 쪽을 확인한 뒤 사용하지 않는 리스너를 끄거나 이 설정에 빈 포트를 지정하고, 운영체제와 앱에 저장된 프록시 주소도 함께 바꾸세요.
로컬에서만 사용할 경우 allow-lan: false를 유지하면 됩니다. LAN 공유가 꼭 필요하다면 허용 범위와 리스닝 주소, 방화벽 규칙을 별도로 확인하고 신뢰할 수 있는 네트워크에서 접속 출처를 검증하세요. 또한 external-controller와 프록시 진입점을 구분해야 합니다. 전자는 대시보드나 프로그램이 커널을 관리하는 데 사용하고, 후자는 프록시 요청을 받습니다. UI가 컨트롤 인터페이스에 연결된다는 것은 관리 채널에 접근할 수 있다는 뜻일 뿐, 서비스 포트의 리스닝이 정상이라는 의미는 아닙니다. 공용 네트워크나 접속 범위를 확신할 수 없는 환경에서는 관리 및 프록시 진입점을 로컬 전용으로 유지하는 편이 경계를 관리하기 쉽습니다.
모드는 규칙 목록 사용 여부를 정할 뿐, 커널에 들어오는 연결을 결정하지 않습니다
규칙 모드에서는 규칙 목록에 따라 커널에 들어온 연결의 출구를 정합니다. 전역 모드에서는 전역 정책에서 선택한 출구를 사용하며 일반 규칙을 하나씩 매칭하지 않습니다. DIRECT 모드에서는 커널에 들어온 일반 프록시 트래픽을 직접 연결합니다. 세 모드는 커널 내부의 처리 경로를 바꿀 뿐, 앱의 프록시 사용을 자동으로 켜거나 끄지는 않습니다. 문제를 해결할 때는 잠시 모드를 바꿔 비교해 볼 수 있습니다. 같은 요청이 DIRECT에서는 성공하고 지정한 출구에서는 실패한다면 출구와 그 출구에 필요한 이름 해석을 먼저 확인하세요. 규칙 모드에서만 잘못된 출구로 간다면 매칭된 규칙과 그룹 선택을 다시 살펴보세요. 테스트가 끝나면 원래 모드로 되돌려 규칙이 계속 적용 중이라고 오해하지 않도록 하세요.
로그 수준은 명확한 문제를 해결하는 데 필요한 만큼만 설정하세요. 평소에는 시작 실패를 확인할 수 있는 수준으로 유지하고, 연결 문제를 살펴볼 때만 상세도를 잠시 높여 테스트 범위를 줄입니다. 한 번에 대상 하나만 열고 시각을 기록해 시작 오류, 인바운드 연결, 도메인 이름 해석, 아웃바운드 연결을 구분하세요. 경로가 정상인데도 페이지가 느리다면 첫 연결 수립과 기존 연결의 후속 전송도 나눠 살펴봐야 합니다. 로그 한 줄만 보고 포트를 원인으로 단정하지 마세요. 로그를 외부에 공유하기 전에 구독 주소, 내부 호스트 이름, 계정 관련 필드를 삭제하고 오류 유형과 필요한 포트 정보만 남기세요.
03 DNS / RESOLUTION
DNS 설정: 업스트림, 부트스트랩 DNS, Fake IP
쿼리를 시작한 주체부터 확인하기
dns.enable은 커널 DNS 모듈을 활성화하는 설정이지, 시스템 전체의 DNS를 바꾸는 설정은 아닙니다. 앱이 먼저 운영체제에 질의한 뒤 주소를 프록시 진입점으로 전달할 수도 있고, 대상 도메인을 커널에 직접 넘겨 처리할 수도 있습니다. 자체 암호화 DNS를 사용해 시스템 기본 경로를 우회하는 앱도 있습니다. 문제를 해결할 때는 「어떤 구성 요소가 질의했는지」와 「어느 리졸버가 응답했는지」를 따로 기록하세요. 일반 웹페이지가 열린다고 해서 모든 앱이 같은 업스트림을 사용한다고 볼 수는 없습니다. 마찬가지로 질의에서 주소를 받았다고 해서 해당 주소로 연결이 성공한 것도 아닙니다.
dns:
enable: true
enhanced-mode: redir-host
default-nameserver:
- 1.1.1.1
nameserver:
- https://cloudflare-dns.com/dns-query
proxy-server-nameserver:
- 1.1.1.1
예시는 redir-host 모드로 실제 주소를 반환하고, 일반 쿼리에는 암호화 DNS를 사용하며, 부트스트랩 업스트림과 노드 이름 해석용 업스트림을 명시적으로 구분합니다. 이 설정을 사용하려면 로컬에서 예시 리졸버에 접근할 수 있어야 합니다. 관리형 네트워크에서는 관리자가 허용하고 현재 연결 경로에서 접근할 수 있는 업스트림으로 바꾸세요. default-nameserver는 주로 DNS 서비스 자체가 도메인 이름으로 지정된 경우 부트스트랩에 사용됩니다. 암호화 쿼리 주소를 도메인으로 지정하면서, 아직 연결되지 않은 암호화 쿼리로 그 도메인을 해석하려 하면 순환 참조가 생길 수 있습니다. 독립적으로 접근 가능한 숫자 주소를 부트스트랩에 사용하면 주 DNS 경로와 이 문제를 분리할 수 있습니다.
일반 도메인과 노드 도메인의 해석 경로는 다를 수 있습니다
nameserver는 기본 DNS 업스트림이고, nameserver-policy는 지정한 도메인에 다른 업스트림을 선택할 수 있습니다. proxy-server-nameserver는 프록시 노드 서버의 도메인을 해석할 때 사용합니다. 노드 주소를 숫자 주소 대신 도메인으로 지정하면 커널은 연결을 수립하기 전에 해당 주소를 알아내야 합니다. 이 도메인을 해석하는 쿼리가 아직 연결되지 않은 노드를 거치도록 설정되어 있으면 첫 연결이 멈출 수 있습니다. 이런 문제를 진단할 때는 먼저 노드 도메인이 독립된 해석 경로를 통해 해석되는지 확인한 다음, 결과 주소로 연결할 수 있는지 확인하세요. 일반 업스트림만 반복해서 바꾸면 노드 이름 해석 문제를 놓치기 쉽습니다.
내부 서비스는 명확한 도메인 범위로 지정해 해석하고, 회사 내부 도메인을 공용 리졸버에 맡겨 확인하지 마세요. 내부와 외부 업스트림은 같은 이름에 서로 다른 결과를 줄 수 있습니다. 공용 업스트림에서 레코드를 찾지 못했다고 해서 내부 레코드가 없는 것은 아닙니다. 도메인 정책을 바꾼 뒤에는 내부 도메인 하나와 외부 도메인 하나를 각각 테스트하고 반환 주소가 예상과 일치하는지 기록하세요. 네트워크를 바꾸면 이전에 접근 가능했던 내부 DNS에 연결되지 않을 수 있습니다. 내부와 외부 이름이 모두 실패한다면 업스트림을 한꺼번에 바꾸기보다 작동하는 최소 설정으로 되돌린 뒤 라우팅 정책을 하나씩 추가하세요.
Fake IP는 매핑 주소이지 실제 서비스 주소가 아닙니다
fake-ip 모드에서는 질의한 쪽에 합성 주소를 반환합니다. 커널이 이 주소로 들어오는 연결을 받으면 매핑 정보를 이용해 원래 도메인을 복원합니다. 이 경로가 작동하려면 합성 주소를 받은 앱의 연결이 해당 매핑을 관리하는 커널로 돌아와야 합니다. 요청이 이 가로채기 범위 밖으로 나가거나 설정 변경 전 주소가 시스템 캐시에 남아 있으면 앱은 일반적인 방식으로 라우팅할 수 없는 주소를 받을 수 있습니다. 로컬 기기 검색이나 내부 서비스에 문제가 생기면 먼저 합성 주소가 적합한 경로인지 확인하세요. 필요하다면 fake-ip-filter를 사용해 해당 이름만 실제 레코드로 반환하고 모든 도메인을 예외로 넣지는 마세요.
강화 모드를 바꾼 뒤에는 같은 앱에서 쿼리와 연결을 다시 보내 캐시가 차이를 가리지 않도록 하세요. 다음 세 가지를 따로 확인하면 됩니다. 쿼리에 응답이 왔는지, 연결이 대상 도메인과 올바르게 연결됐는지, 규칙이 예상한 출구를 선택했는지 확인하세요. 첫 번째 단계가 실패하면 업스트림 접근성을, 두 번째 단계가 실패하면 앱의 이름 해석 경로와 가로채기 범위를 확인합니다. 세 번째 단계에서만 실패할 때 규칙 순서를 살펴보세요. 로그에 이름 해석 시간 초과가 먼저 표시되고 웹페이지에서 연결 실패가 뒤따른다면 이는 후속 증상일 뿐입니다. 노드나 시스템 프록시도 의심된다면 노드 연결 시간 초과 단계별 문제 해결을 참고해 범위를 좁히세요.
04 PROXIES / OUTBOUND
프록시 노드 필드와 연결 경계
노드 표시 이름과 연결 매개변수 구분하기
노드는 하나의 아웃바운드 연결에 필요한 매개변수 모음입니다. name은 설정에서 참조하는 이름이고, type은 프로토콜을 선택하며, server와 port는 실제 연결 주소를 지정합니다. 노드 이름은 알아보기 쉬운 문자열로 정할 수 있지만 프록시 그룹의 참조와 일치해야 하고, 다른 출구 이름과 겹치지 않아야 합니다. 표시 이름을 바꿔도 원격 서버는 바뀌지 않으며 연결 실패도 해결되지 않습니다. 반대로 원격 매개변수를 바꾸고 이름을 유지하면 프록시 그룹은 대개 기존 이름을 계속 참조합니다. 설정을 수정하기 전에 표시 이름을 바꾸는 것인지 실제 연결 조건을 바꾸는 것인지 먼저 확인하세요.
proxies:
- name: 로컬 테스트 출구
type: socks5
server: 127.0.0.1
port: 1081
udp: false
proxy-groups:
- name: 노드 확인
type: select
proxies:
- 로컬 테스트 출구
- DIRECT
rules:
- DOMAIN-SUFFIX,example.org,노드 확인
- MATCH,DIRECT
이 예시는 이미 실행 중인 별도의 로컬 SOCKS5 서비스가 예시 포트에서 연결을 받아야 합니다. 내장 노드가 아니며 서비스를 직접 실행하지도 않습니다. 로컬에 해당 서비스가 없다면 비교용으로 DIRECT를 유지하거나, 허용된 프록시로 노드를 바꾸세요. 서버 포트를 이 설정의 혼합 진입 포트로 지정하면 아웃바운드가 인바운드로 되돌아가므로 독립적인 테스트 경로가 되지 않습니다. 설정을 적용한 뒤 그룹에서 테스트 출구를 직접 선택하고 예시 도메인에 접속하세요. 그룹에 저장된 DIRECT 선택을 노드가 정상 작동하는 것으로 착각하지 않도록 주의해야 합니다.
프로토콜, 전송 방식, 인증 정보를 각각 확인하기
프로토콜마다 필요한 추가 필드를 이름만 보고 추측할 수는 없습니다. 일부 프로토콜은 사용자 이름과 비밀번호를 사용하고, 다른 프로토콜은 전용 식별 정보가 필요합니다. 전송 계층에서 TLS를 활성화하는 경우도 있고 서버와 일치하는 전송 옵션이 추가로 필요한 경우도 있습니다. 먼저 노드 제공처의 필드 목록에 따라 프로토콜을 설정한 다음 주소, 인증 방식, 전송 매개변수를 확인하세요. 서버까지 기본 연결이 된다는 것은 주소와 포트에 접근 가능하다는 뜻일 뿐 인증에 성공했다는 의미는 아닙니다. 로그에 핸드셰이크나 인증 오류가 표시된다면 검증을 끄기보다 이름, 시간, 서버 인증서 설정을 확인하세요.
연결 주소와 인증서에 맞는 서버 이름은 서로 다를 수 있습니다. 서버에서 특정 이름을 요구한다면 해당 프로토콜이 지원하는 필드에 입력하세요. 노드 표시 이름을 핸드셰이크 이름으로 사용하면 안 됩니다. 마찬가지로 전송 옵션의 경로는 구독 주소와 다릅니다. 구독 주소는 전체 설정을 가져오는 데 사용하고, 경로는 노드 연결 매개변수에 속하므로 수정 범위가 다릅니다. 출처를 확인할 때는 정상적으로 가져온 뒤의 실제 설정을 살펴보고, 공유 링크의 인코딩된 문자열을 해당 형식을 지원하지 않는 필드에 그대로 붙여넣지 마세요. 여러 설정을 비교할 때는 같은 프로토콜의 동일한 유형 필드끼리 비교해야 합니다.
단일 출구로 네트워크 문제와 선택 오류 구분하기
UDP는 별도로 테스트해야 합니다. 필드에서 UDP를 허용한다는 것은 해당 아웃바운드에서 커널이 어떻게 동작하는지를 나타낼 뿐, 프록시 서버와 하위 전송 계층, 대상 앱이 모두 같은 트래픽을 지원한다는 뜻은 아닙니다. 웹페이지가 TCP로 열린다고 해서 음성이나 실시간 앱도 정상 작동한다는 보장은 없습니다. 반대로 UDP 테스트 실패만으로 노드 전체가 고장 났다고 판단하면 정상적인 웹 연결까지 잘못 건드릴 수 있습니다. 먼저 수동 그룹 하나로 기본 아웃바운드를 확인한 다음, 실제로 UDP를 사용하는 앱에서 새 연결 기록을 살펴보세요. 프로토콜, 대상, 적용된 규칙, 선택한 출구를 각각 기록하고 웹 속도 테스트 한 번으로 전체 경로를 판단하지 마세요.
노드 로드가 실패하면 재현 가능한 최소 객체 하나를 먼저 남겨두세요. 그룹은 보이지만 특정 연결이 실패한다면 오류가 발생한 단계에 따라 매개변수를 확인합니다. 이름 해석 실패는 노드 도메인과 관련될 수 있고, 연결 거부는 포트나 서비스 상태를 가리키는 경우가 많으며, 핸드셰이크 시간 초과는 경로나 전송 매개변수 때문일 수도 있습니다. 증상만으로 원인을 하나로 단정할 수는 없습니다. 노드를 정리하기 전에 해당 이름이 여러 프록시 그룹이나 규칙에서 사용되는지 검색하세요. 클라이언트에 필요한 커널이 포함되어 있는지 먼저 확인하려면 다운로드 센터에서 플랫폼별 추천 항목인 Clash Plus를 살펴보고, 해당 제품이 실제로 지원하는 필드를 확인하세요.
05 PROXY-GROUPS / SELECTION
프록시 그룹 유형, 구성원, 상태 확인
프록시 그룹은 출구를 관리하며 규칙 매칭을 대신하지 않습니다
규칙은 연결을 출구나 프록시 그룹에 전달하고, 그룹은 구성원 중 실제 출구를 선택합니다. 규칙은 제대로 매칭됐는데 연결 경로가 잘못됐다면 매칭된 그룹 이름과 그룹 안에서 현재 선택된 항목을 함께 확인하세요. 먼저 수동 그룹 하나에서 실제 노드를 확인한 다음 자동 그룹을 추가하는 편이 좋습니다. 처음부터 여러 자동 그룹을 중첩하면 상태 확인 결과, 테스트 결과, 사용자 선택이 모두 작동에 영향을 미쳐 연결이 특정 노드에 도달한 이유를 파악하기 어려워집니다. 그룹 이름은 「업무 연결」이나 「백업 출구」처럼 용도를 나타내는 이름이 좋습니다. 업데이트 후 쉽게 바뀔 노드 이름을 그룹 이름으로 사용하지 마세요.
proxy-groups:
- name: 자동 출구
type: url-test
proxies:
- 로컬 테스트 출구
url: 'https://example.org/'
interval: 300
tolerance: 50
- name: 수동 진입
type: select
proxies:
- 자동 출구
- DIRECT
이 내용은 최상위 프록시 그룹 목록 전체를 교체하는 용도로 사용해야 합니다. 기존 파일에 같은 이름의 최상위 키를 하나 더 추가하면 안 됩니다. 노드는 앞 장의 설정을 사용합니다. 앞 장의 규칙도 함께 쓴다면 규칙의 「노드 확인」을 「수동 진입」으로 바꾸세요. 문법을 보여주기 위해 노드 하나만 넣었으므로 후보 간 전환은 일어나지 않습니다. 테스트 URL은 예시용입니다. 실제 배포에서는 가볍고 안정적이며 예상 응답이 분명하고 모든 후보 경로에서 접속할 수 있는 주소를 선택하세요. 자동 그룹의 테스트는 이 주소로 요청을 보내는 것이며 테스트 컴퓨터에서 노드 서버까지의 편도 지연 시간을 측정하는 것이 아닙니다. 다른 서비스의 성능을 보장하지도 않습니다.
전환 목표에 맞춰 그룹 유형 선택하기
| 유형 | 선택 기준 | 사용 사례 |
|---|---|---|
select | 사용자 선택 | 경로를 직접 지정하거나 고정 출구 문제 해결 |
url-test | 테스트 결과와 허용 오차 | 후보별 테스트 응답 비교 |
fallback | 구성원 순서와 가용성 | 주 출구를 우선 사용하고 실패하면 백업으로 전환 |
load-balance | 부하 분산 정책 | 여러 사용 가능한 구성원에 연결 분산 |
주 출구를 고정해야 한다면 우선순위를 표현하는 fallback을 사용하세요. 가장 빠른 노드를 선택하는 기능으로 생각하면 안 됩니다. 테스트 결과를 비교하려면 url-test의 허용 오차를 사용해 작은 차이로 출구가 자주 바뀌는 것을 방지하세요. tolerance는 밀리초 단위이고 interval은 초 단위로 설정합니다. 테스트 간격이 너무 짧으면 테스트 트래픽이 늘고, 너무 길면 변화를 늦게 감지할 수 있습니다. 시간대별 실제 변동을 확인한 뒤 두 필드를 조정하고, 한 번의 테스트 결과만으로 그룹 전체를 급하게 다시 작성할 필요는 없습니다.
load-balance는 연결을 분산할 뿐, 단일 다운로드 요청을 여러 노드로 나누지 않습니다. 출구 유지가 필요한 서비스는 출구 변경에 민감할 수 있으므로 다른 연결과 순환 정책을 공유하기보다 고정 그룹으로 따로 보내는 편이 좋습니다. 여러 방식 중에서 선택해야 한다면 주 출구 우선순위, 연결 지속성, 균등 분배 중 무엇을 유지할지 먼저 정한 뒤 자동 프록시 그룹 유형과 필드 비교를 참고하세요. 그룹을 바꾸기 전후에 같은 대상으로 새 연결을 여러 번 시도해 관찰하세요. 이미 수립된 연결은 전환 성공 여부를 확인하는 기준으로 적절하지 않습니다.
그룹 참조는 단방향으로 구성하기
그룹에 다른 그룹을 포함할 수 있지만 직접 또는 간접적으로 자기 자신을 참조해서는 안 됩니다. 규칙에서 사용할 진입 그룹 하나가 하위 자동 그룹을 참조하고, 자동 그룹이 노드를 참조하는 구조가 점검하기 쉽습니다. 프록시 제공자를 통해 구성원을 가져오는 경우 그룹의 use에는 개별 노드 이름이 아니라 제공자 이름을 지정합니다. 그룹을 시작한 뒤 선택할 구성원이 없다면 먼저 로컬 정의와 참조가 존재하는지 확인하고, 제공자가 정상적으로 로드됐는지와 필터 조건이 모든 구성원을 제외하지 않았는지 살펴보세요. 그다음에야 테스트 실패를 고려하세요. 정의는 있지만 구성원이 없는 상황과 구성원은 있으나 모두 접근할 수 없는 상황은 서로 다릅니다.
자동 그룹 문제를 판단할 때는 같은 후보와 같은 대상 주소를 독립된 수동 그룹에서 먼저 사용해 보세요. 수동 연결도 실패한다면 노드 경로를 우선 점검해야 합니다. 실제 서비스는 정상인데 테스트만 실패한다면 대상 사이트가 테스트 주소를 제한하는지, 해당 출구에서 예상과 다른 응답을 반환하는지, 테스트가 실행됐는지 확인하세요. 일부 클라이언트는 수동 그룹의 이전 선택을 저장하므로 YAML을 바꿔도 화면에서 첫 번째 항목으로 자동 전환되지 않을 수 있습니다. 설정의 후보 순서와 실제 선택 항목, 테스트 시각을 매번 기록해야 설정 변경과 클라이언트에 남은 실행 상태를 구분할 수 있습니다.
06 RULES / MATCH ORDER
규칙 문법, 매칭 순서, 기본 규칙
좁은 범위부터 매칭한 뒤 넓은 범위로 확장하기
규칙 모드에서는 목록을 위에서 아래로 처리하며 가장 먼저 일치하는 규칙이 출구를 결정합니다. 정확한 도메인 규칙은 해당 도메인을 포함하는 접미사 규칙보다 앞에, 좁은 IP 대역은 이를 포함하는 넓은 대역보다 앞에 배치하세요. 설정의 목표는 규칙을 많이 추가하는 것이 아니라 범위와 우선순위를 설명할 수 있게 하는 것입니다. 규칙을 추가하기 전에 같은 대상을 포함하는 넓은 규칙이 앞에 있는지 확인하세요. 있다면 새 예외를 그 규칙보다 위에 둬야 합니다. 마지막 기본 규칙 뒤에 예외를 추가하면 설정이 로드되더라도 원하는 라우팅 결과를 얻을 수 없습니다.
mode: rule
proxy-groups:
- name: 문서 출구
type: select
proxies:
- DIRECT
rules:
- DOMAIN,upload.example.org,DIRECT
- DOMAIN-SUFFIX,example.org,문서 출구
- IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
- MATCH,DIRECT
예시의 첫 번째 규칙은 업로드 하위 도메인만 매칭하고, 두 번째 규칙은 예시의 기본 도메인과 하위 도메인을 모두 처리합니다. 세 번째 규칙은 IP 대역 매칭 문법을 보여주며, 예시에 사용된 대역은 문서용으로 예약된 주소입니다. 마지막 규칙은 앞선 조건에 일치하지 않은 연결을 처리합니다. 예시 그룹에는 DIRECT 구성원만 있으므로 앞의 두 규칙이 어떻게 다른지 보려면 연결 기록에서 규칙이나 정책 경로를 확인해야 합니다. MATCH에는 도메인이나 IP 대역 매개변수가 없고 출구만 지정합니다. 이 문법에서는 쉼표가 포함된 규칙 전체가 YAML 목록의 항목 하나입니다. 조건과 정책을 여러 하이픈으로 나눠 서로 다른 항목으로 작성하지 마세요.
대상 도메인, 연결 주소, 데이터 출처를 각각 확인하기
도메인 규칙이 적용되려면 커널이 대상 도메인을 확인하거나 복원할 수 있어야 합니다. 앱이 도메인 정보 없이 숫자 주소만 전달하면 도메인 규칙은 매칭되지 않습니다. IP-CIDR은 주소 범위를 기준으로 판단합니다. 도메인만 있는 대상을 처리할 때 일부 IP 유형 규칙은 이름 해석을 유발할 수 있습니다. 지원되는 규칙 유형에는 no-resolve를 추가해 해당 매칭을 위해 별도 조회를 시작하지 않도록 할 수 있습니다. 대상 주소를 알고 있다면 주소를 기준으로 판단할 수 있습니다. 이 옵션을 추가했다면 도메인과 숫자 주소를 각각 테스트하세요. 그렇지 않으면 「이름을 해석하지 않아 판단할 수 없음」을 대역 문법 오류로 오해하기 쉽습니다.
GEOIP는 지리 정보 IP 데이터베이스를 사용하며 도메인 접미사로 지역을 추측하지 않습니다. RULE-SET은 rule-providers에 정의된 컬렉션을 참조합니다. 주소 데이터베이스가 업데이트되면 같은 주소의 분류가 달라질 수 있습니다. 컬렉션도 자체적인 동작 유형과 데이터 형식을 사용하므로 파일을 내려받았다고 해서 커널이 규칙을 정상적으로 읽었다는 뜻은 아닙니다. 두 조건을 실제 규칙 목록에 넣기 전에 현재 설정에서 데이터가 로드됐는지 확인하고, 적용 대상과 비대상 주소를 각각 테스트하세요. 업데이트 실패, 노드 문제, 라우팅 불일치의 흔한 원인은 문제 해결 FAQ에서 먼저 확인할 수 있습니다.
정상 사례, 반례, 기본 규칙으로 순서 확인하기
한 번의 검증에서 최소 세 가지 대상을 다뤄야 합니다. 정확한 예외에 매칭되어야 하는 대상, 더 넓은 조건에 매칭되어야 하는 같은 유형의 대상, 앞선 규칙에 매칭되지 않아 기본 규칙으로 가야 하는 대상입니다. 각 대상의 예상 규칙과 출구를 기록한 뒤 새 연결을 만드세요. 정확한 대상이 넓은 규칙에 먼저 매칭된다면 위아래 순서를 확인합니다. 두 도메인 모두 기본 규칙으로 간다면 대상 값과 도메인 인식 여부, 규칙 모드 사용 여부를 확인하세요. 규칙은 맞지만 출구가 다르다면 그룹의 구성원을 살펴보세요. 웹사이트는 여러 하위 도메인과 타사 리소스를 동시에 요청할 수 있으므로 주소 표시줄의 기본 도메인을 페이지의 유일한 대상으로 간주하지 말고 각 연결을 확인해야 합니다.
기본 규칙을 바꾸기 전에 분류되지 않은 트래픽을 어떻게 처리할지 먼저 정하세요. DIRECT를 기본 규칙으로 사용하면 알려진 규칙의 영향을 분리해 설정을 먼저 검증하기 좋습니다. 실제 사용에서는 네트워크와 서비스 요구에 맞는 명확한 기본 출구를 선택하고, 자주 쓰는 앱이 해당 경로에서 어떻게 동작하는지 확인하세요. 변경 사항을 저장할 때 어떤 규칙이 이동으로 인해 먼저 매칭되게 됐는지도 기록하세요. 나중에 임시 예외를 삭제할 때 원래 대체했던 경로를 알 수 있어 기억에 의존하지 않고 정리할 수 있습니다. 자주 업데이트되는 외부 규칙 모음에는 반복 검증할 수 있는 대상을 한두 개 남겨두고 업데이트 후 같은 순서로 다시 확인하세요.
07 OVERRIDES / EFFECTIVE CONFIG
설정 오버라이드, 병합, 롤백
원본 구독, 로컬 변경 사항, 최종 적용 설정을 분리해 저장하기
수정 사항이 적용되지 않을 때는 편집기의 구독 복사본만 보지 말고 커널이 실제로 로드한 설정을 비교해야 합니다. 클라이언트는 기본 구독을 가져온 뒤 로컬 오버라이드를 병합하고, 마지막으로 UI 설정에 따라 실행 매개변수를 추가할 수 있습니다. 오버라이드 파일은 모든 클라이언트가 공통으로 사용하는 커널 문법이 아닙니다. 제품이 전체 교체, 키 단위 병합, 목록 추가, 스크립트 처리 중 어떤 방식을 지원하는지 먼저 확인하세요. 제품이 해당 기능을 제공하지 않는다면 YAML에 병합 지시문을 직접 추가해도 커널이 자동으로 실행하지 않습니다.
수정되지 않은 구독 원본을 보관하고 검증용 로컬 설정을 별도로 저장하세요. 진입점만 바꾸려면 아래 YAML을 변경 목록으로 사용하거나 매핑 방식 오버라이드를 지원하는 클라이언트의 규칙에 따라 적용할 수 있습니다. 이 조각만 원본 설정의 대체 파일로 사용하면 안 됩니다. 원래 노드와 그룹, 규칙은 이 설정과 함께 로드되지 않습니다. 먼저 이 두 항목을 적용하고 실제 리스닝이 예상과 일치하는지 확인한 뒤 DNS나 규칙을 수정하세요. 여러 변경 사항을 나눠 적용하면 문제가 발생했을 때 어떤 변경으로 동작이 달라졌는지 확인할 수 있습니다.
mixed-port: 7891
allow-lan: false
병합하기 전에 값의 형태부터 확인하기
포트는 스칼라이므로 값을 바꾼 뒤 보통 해당 포트를 사용하는 앱만 함께 수정하면 됩니다. DNS 섹션은 중첩 매핑으로, 도구에 따라 하위 키별로 병합하거나 기존 섹션 전체를 새 섹션으로 덮어쓸 수 있습니다. 따라서 강화 모드만 바꿨는데도 기존 업스트림이나 내부 도메인 정책이 사라질 수 있습니다. 생성 결과에 기존 필드가 남아 있는지 확인하고, 원래 정상적으로 해석되던 내부 대상을 다시 테스트하세요. 삭제 의미를 확인하기 위해 빈 값을 사용하지 마세요. 필드 누락, 빈 목록, YAML의 null 값은 서로 다른 상태이며 클라이언트와 커널이 각각 다르게 처리할 수도 있습니다.
목록은 교체됐는지, 앞에 삽입됐는지, 뒤에 추가됐는지도 확인해야 합니다. 특히 규칙 목록은 병합 후 항목이 모두 남아 있어도 순서가 올바르다는 보장이 없습니다. 아래는 기존 규칙을 유지하는 최소 결과 예시입니다. 첫 번째 항목은 새 예외이고 두 번째와 기본 규칙은 원본 설정에서 가져옵니다. 도구가 전체 목록 교체만 지원한다면 유지할 기존 항목까지 최종 목록에 포함하세요. 앞에 삽입하는 기능을 지원한다면 새 항목만 제출해 기존 규칙이 중복으로 들어가지 않게 하세요. 예외는 실제로 존재하는 출구를 참조해야 합니다. 두 YAML을 각각 읽을 수 있다고 해서 병합한 뒤에도 반드시 로드된다고 볼 수는 없습니다.
rules:
- DOMAIN,status.example.org,DIRECT
- DOMAIN-SUFFIX,example.org,문서 출구
- MATCH,DIRECT
로드 테스트로 구조를 확인하고 롤백으로 복구 절차를 점검하기
mihomo를 독립적으로 사용하고 로컬에 실행 파일이 있다면 테스트 모드로 로드할 설정 전체를 확인할 수 있습니다. 클라이언트 환경에서는 클라이언트가 제공하는 검증 기능을 우선 사용하세요. 별도로 명령줄을 사용한다면 작업 디렉터리와 필요한 규칙 리소스를 실제 배포 환경과 맞춰야 합니다. 그렇지 않으면 외부 리소스 관련 오류는 테스트 환경 차이만 반영할 수 있습니다. 테스트가 통과해도 설정을 다시 로드하고 리스닝, 도메인 해석, 새 연결의 출구를 확인해야 합니다. 정적 테스트만으로 원격 노드나 DNS 서비스에 접근할 수 있다고 보장할 수 없으며 운영체제 프록시의 연결 검증도 대신하지 않습니다.
mihomo -t -f ./config.yaml
구독 업데이트 전후에는 이름과 순서가 바뀌었는지 확인하세요. 업데이트로 노드가 삭제되거나 이름이 바뀌고, 프록시 그룹 구성원이 다른 항목으로 교체될 수 있습니다. 로컬 오버라이드가 노드 이름을 기준으로 연결되어 있다면 업데이트 후 참조 대상을 찾지 못할 수 있습니다. 프록시 그룹이 제공자에서 후보를 가져오고 필터 조건을 적용한다면 필터 결과도 다시 점검해야 합니다. 여러 기기에서 설정을 재사용하려면 노드, 그룹, 규칙은 공통 영역으로 두고 리스닝 포트 같은 환경별 설정은 각 기기의 로컬 계층에 두는 편이 좋습니다. 자세한 장단점은 여러 기기 간 설정 동기화 방식 비교를 참고하세요.
백업은 업데이트 전 원본 파일, 로컬 오버라이드, 롤백에 사용할 최종 적용 설정을 구분할 수 있어야 합니다. 변경할 때마다 수정 목적과 영향 범위, 검증 결과를 짧게 기록하세요. 예를 들어 「리스닝 포트를 변경하고 브라우저에서 새 포트로 연결을 확인함」과 같이 작성할 수 있습니다. 최종 설정에 계정 정보가 포함되어 있다면 접근을 제한하고 원본 파일을 공개 문의에 그대로 첨부하지 마세요. 구독 업데이트와 로컬 변경이 같은 날 발생했더라도 알려진 정상 경로를 먼저 복구한 뒤 변경 기록을 따라가며 차이가 생긴 단계를 찾을 수 있습니다.