config.yaml / 필드 가이드
Clash 설정 파일 가이드
처음 구독을 가져오고 모드를 선택해 연결을 확인한다면 시작하기 튜토리얼부터 살펴보세요. 튜토리얼에서는 연결 방법을, 이 가이드에서는 연결 후 설정을 읽고 수정하는 법과 변경 결과를 확인하는 위치를 다룹니다.
예제는 Mihomo를 기준으로 합니다. 클라이언트 화면의 기능 이름이 YAML 키와 일치하지 않을 수 있으며, 구형 코어에서는 같은 옵션을 지원하지 않을 수도 있습니다. 별도 로드가 가능하다고 명시된 예제를 제외한 코드는 해당 필드만 보여 줍니다. 기존 설정에서 해당 위치에 넣어 사용하세요.
config.yaml / 01
YAML 구조와 설정 파일 진입점
최상위 키, 매핑, 리스트
설정 파일의 최상위에는 키와 값이 모여 있습니다. 같은 단계에 있는 mixed-port, mode, rules는 각각 다른 역할을 하며, 대개 작성 순서는 의미에 영향을 주지 않습니다. 하지만 rules 아래에는 순서가 중요한 규칙 목록이 있으므로 첫 번째 규칙과 마지막 규칙을 임의로 바꾸면 안 됩니다. 먼저 현재 부분이 매핑인지 리스트인지 파악한 다음, 복사한 몇 줄을 어디에 넣을지 판단하세요. dns: true처럼 여러 설정을 하나의 스위치로 축약하면 YAML 파싱은 되더라도 코어가 기대하는 구조와 다릅니다.
일반적으로 한 단계 들여쓸 때 공백 두 칸을 사용하고 탭은 쓰지 않습니다. 아래 파일은 단독으로 불러올 수 있습니다. 혼합 포트 하나만 열고 모든 요청은 직결 처리하므로 상위 노드가 필요하지 않습니다. 불러오기 전에 로컬 포트를 다른 인스턴스가 사용 중인지 확인하세요. 앱이 연결되는지 확인하는 용도로는 쓸 수 있지만 원격 노드 테스트에는 적합하지 않습니다. DNS 설정을 추가하려면 최상위에 dns를 넣으세요. 마지막 규칙 아래에 이어서 들여쓰면 안 됩니다.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
하이픈으로 시작하는 각 항목은 리스트의 한 요소입니다. 노드 리스트의 요소는 여러 줄로 구성될 수 있습니다. 첫 줄에 이름을 쓰고 다음 줄에 유형, 서버, 포트를 들여써서 적습니다. 규칙 리스트의 요소는 보통 한 줄 문자열입니다. 특히 헷갈리기 쉬운 부분은 프록시 그룹 아래의 proxies입니다. 여기에 적는 것은 후보 이름이지 서버 주소가 포함된 노드 정의가 아닙니다. 키 이름이 같아도 위치에 따라 데이터 구조가 다르므로 서로 대체할 수 없습니다.
스칼라 유형과 중복 키
포트는 정수, 스위치는 불리언, 이름과 서버 주소는 문자열로 작성합니다. 숫자처럼 보이는 값을 이름으로 쓰려면 따옴표로 감싸고, 이를 참조하는 곳에서도 문자열로 취급하세요. 일반 문자열에 공백 뒤 콜론이 있거나 주석 시작으로 해석될 수 있는 샵 기호가 있으면 값 전체를 따옴표로 감싸세요. 규칙 문자열은 보통 따옴표가 필요하지 않습니다. 편집기가 문장부호를 다른 구조로 해석한다면 쉼표로 나뉜 각 필드가 아니라 규칙 한 줄 전체를 따옴표로 감싸세요.
같은 파일의 최상위에 같은 이름의 키를 두 번 쓰지 마세요. 기존 rules가 있는 파일 끝에 rules를 다시 붙여도 원래 목록에 항목이 추가되는 것은 아닙니다. 일부 파서는 중복 키 오류를 내고, 다른 파서는 둘 중 하나만 남길 수 있습니다. 이런 문제를 점검할 때는 먼저 해당 키가 두 번 등장하는지 확인한 다음, 위쪽의 몇 줄을 더 살펴 실제 계층을 파악하세요. 편집기가 들여쓰기 오류를 표시하더라도 실제 원인은 이전 줄에 콜론이 빠졌거나 더 앞쪽의 리스트가 제대로 끝나지 않은 것일 수 있습니다.
원본 구독 설정에서 실행 설정까지
GUI 클라이언트에서는 가져온 설정, 오버라이드 설정, 실행 설정이 서로 다른 파일인 경우가 많습니다. 가져온 설정은 구독을 새로고침할 때 다시 생성될 수 있고, 오버라이드에는 로컬 변경 사항이 저장되며, 실행 설정이 코어에 전달됩니다. 필드가 적용됐는지 확인하려면 먼저 현재 선택된 프로필을 확인한 뒤 클라이언트에서 실행 설정을 미리 보거나 내보낼 수 있는지 살펴보세요. 처음 다운로드한 파일만 열어 보면 구독에서 제공한 내용은 알 수 있지만, 현재 실제로 사용 중인 설정인지는 확인할 수 없습니다.
독립 실행형 Mihomo를 사용한다면 코어가 실행되는 작업 환경에서 설정 후보 파일을 확인할 수 있습니다. 상대 경로, 외부 규칙 파일, 작업 디렉터리는 실제 실행 환경과 최대한 일치시켜야 합니다. 원격 프로바이더가 포함된 설정은 검사할 때도 파일이나 네트워크에 의존할 수 있습니다. 아래 명령은 GUI 클라이언트의 프로필을 바꾸지 않으며, 포트를 바인딩할 수 있는지 또는 외부 네트워크에 반드시 연결되는지도 확인하지 않습니다. 먼저 앞의 최소 설정으로 형식 오류를 제외하고, 실제 후보 파일로 참조 경로를 확인한 다음 실행하세요.
mihomo -t -f ./config.yaml
127.0.0.1 / 02
수신 대기 포트, 실행 모드, 제어 인터페이스
로컬 접속 포트와 상위 서버 포트를 구분하세요
브라우저나 터미널은 127.0.0.1:7890처럼 로컬 수신 주소에 연결하고, 코어는 노드 정의에 지정된 서버 주소와 포트에 연결합니다. 두 포트 번호가 우연히 같을 수는 있지만 서로 연결된 것은 아닙니다. 로컬 수신 포트를 바꾸면 시스템 프록시나 앱 프록시 설정도 바꿔야 합니다. 노드 포트를 바꿔도 로컬 앱은 보통 수정할 필요가 없습니다. '연결이 거부됨' 오류가 나타나면 먼저 로그의 주소가 로컬인지 노드 주소인지 확인한 뒤 해당 필드를 점검하세요.
| 필드 | 용도 | 확인할 항목 |
|---|---|---|
mixed-port | 하나의 포트에서 HTTP 및 SOCKS 프록시 연결을 모두 수신 | 시스템 프록시와 SOCKS를 지원하는 앱이 각 프로토콜로 접속 |
port | HTTP 프록시 전용 수신 포트 | 앱에 설정할 HTTP 프록시 주소 |
socks-port | SOCKS 프록시 전용 수신 포트 | 앱에 설정할 SOCKS 프록시 주소 |
allow-lan | 로컬 네트워크 기기의 프록시 접속 허용 여부 | 수신 주소, 시스템 방화벽, 실제 접속 위치 |
external-controller | 코어의 외부 관리 인터페이스 | 클라이언트 대시보드나 로컬 관리 도구용이며 앱 프록시 접속 주소가 아닙니다 |
로컬 기기에서만 사용할 때는 allow-lan: false를 유지하세요. 루프백 주소는 연결을 시도하는 기기 자신을 가리키므로 휴대폰에 127.0.0.1을 입력해도 컴퓨터에 연결되지 않습니다. 신뢰할 수 있는 로컬 네트워크에서 공유해야 할 때만 allow-lan, bind-address, 방화벽을 확인하세요. 필요한 기기에만 접근을 허용하고 수신 포트를 공용 인터넷에 노출하지 마세요. 컴퓨터의 브라우저가 연결되는지만 확인하는 상황이라면 로컬 네트워크 접근을 허용할 필요가 없습니다.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
개별 규칙보다 먼저 확인할 모드
rule 모드는 규칙 목록으로 목적지를 선택합니다. global 모드는 전역 정책에서 현재 선택된 항목을 사용하며, 특정 원격 노드를 반드시 사용한다는 뜻은 아닙니다. direct 모드는 코어에 들어오는 트래픽을 직결 처리하지만, 수신 포트를 닫거나 시스템 프록시를 해제하는 것은 아닙니다. 모드를 바꾼 뒤에는 새 연결을 시작해 보세요. 기존 장기 연결은 새 모드로 즉시 다시 연결되지 않을 수 있습니다. 채팅, 동기화, 다운로드 앱이 백그라운드에서 연결을 유지한다면 연결 세부 정보에서 기존 연결인지 새 연결인지 먼저 구분하세요.
GUI 클라이언트는 관리 인터페이스를 통해 실행 모드를 바꿀 수 있습니다. 따라서 파일에 mode: rule이라고 적혀 있어도 1분 전에 화면에서 선택한 전역 모드가 초기화됐다고 볼 수는 없습니다. 규칙이 적용되지 않는 문제를 진단하려면 먼저 화면에서 현재 모드와 프로필을 확인한 뒤 규칙을 살펴보세요. 세 가지 모드를 비교해 보고 싶다면 규칙·전역·직결 모드의 차이를 참고하세요. 모드 전환을 영구적인 해결책으로 여기지 마세요.
먼저 프록시 연결을 확인한 뒤 관리 인터페이스 점검
시스템 프록시는 운영체제나 클라이언트가 설정하며, 해당 설정을 읽는 프로그램만 이를 사용합니다. 터미널은 명령마다 프록시를 지정해야 할 수 있고, 일부 브라우저는 확장 프로그램이나 자체 설정을 우선할 수 있습니다. 아래 명령을 실행한 다음 연결 기록에서 같은 시각의 목적지를 찾아보세요. 응답이 오면 지정한 프록시를 사용한 해당 요청이 완료됐다는 뜻일 뿐, 터미널의 모든 명령이 프록시를 사용한다는 의미는 아닙니다. 명령에서 로컬 연결 거부 오류가 나면 포트와 프로세스를 확인한 뒤 브라우저와 터미널을 나눠 점검하는 방법에 따라 범위를 좁히세요.
curl -I --proxy http://127.0.0.1:7890 https://example.com/
관리 인터페이스는 별도의 경로입니다. GUI 클라이언트가 코어를 관리하고 있다면 설정을 시험한다는 이유로 클라이언트가 관리하는 제어 주소나 인증 값을 임의로 바꾸지 마세요. 코어를 직접 실행하고 외부 제어가 필요하다면 루프백 주소에 바인딩하고 관리 도구의 요구에 따라 로컬 인증을 설정하세요. 포트 충돌이 나면 프록시 포트와 관리 포트를 각각 확인하고, 한쪽을 바꾼 뒤에는 해당 포트를 사용하는 호출 측 설정도 함께 바꾸세요. 로그 수준을 일시적으로 높이면 진단에 도움이 되지만, 점검이 끝나면 평소 수준으로 되돌리는 것이 좋습니다. 설정 일부를 공유하기 전에는 사설 주소, 구독 주소, 인증 정보를 삭제하세요.
proxies / 03
프록시 노드 필드와 외부 노드 소스
이름, 프로토콜, 원격 주소, 포트
proxies는 코어에서 사용할 아웃바운드 노드를 정의합니다. name은 프록시 그룹이나 규칙에서 참조하는 이름이고, type은 사용할 프로토콜을 지정합니다. server와 port는 해당 프로토콜 서버의 위치를 가리킵니다. 서버 필드에는 호스트 이름이나 주소만 입력하고 프로토콜 접두사, 경로, 별도의 포트 정보는 넣지 마세요. 이름은 짧고 중복되지 않게 지정하며 DIRECT, REJECT 같은 내장 대상 이름은 사용하지 마세요.
아래는 SOCKS5 아웃바운드 정의 예제입니다. 같은 기기에서 독립 SOCKS5 서버가 실제로 1080 포트를 수신하고, 해당 서버가 로컬 무인증 접속을 허용할 때만 전달 테스트에 사용할 수 있습니다. 이 주소는 공개적으로 사용할 수 있는 노드가 아닙니다. 앞 장에서 다룬 Clash 혼합 포트로 바꾸면 아웃바운드 트래픽이 같은 코어로 되돌아갈 수 있습니다. 이 코드를 최소 설정에 합친 뒤에는 테스트 규칙이나 프록시 그룹에서 노드를 참조해야 합니다. 노드만 정의해도 MATCH,DIRECT의 동작은 바뀌지 않습니다.
proxies:
- name: 로컬 업스트림
type: socks5
server: 127.0.0.1
port: 1080
udp: false
프로토콜을 바꾸려면 유형뿐 아니라 관련 매개변수 전체를 바꿔야 하는 경우가 많습니다. TLS 노드를 예로 들면 서버 주소는 연결을 설정할 곳이고, 서버 이름은 핸드셰이크나 인증서 확인에 사용될 수 있어 둘이 다를 수 있습니다. 추가 전송 방식도 서버 설정과 일치해야 합니다. 포트가 443이라는 이유만으로 TLS나 특정 전송 옵션을 더해서는 안 됩니다. 필드 이름이 확실하지 않다면 현재 코어에서 지원하는 프로토콜 문서와 서버 측에서 제공한 매개변수를 확인하세요. 다른 프로토콜의 인증 항목을 그대로 가져오지 마세요.
노드 목록과 프록시 그룹의 참조 관계
노드 이름을 바꾸면 그룹의 후보 목록, 해당 노드를 직접 가리키는 규칙, 클라이언트에 저장된 수동 선택 항목도 함께 확인해야 합니다. 새 이름이 이전 이름과 공백 하나만 달라도 기존 참조가 자동으로 이어지지 않습니다. 서로 다른 소스에서 같은 이름의 노드를 제공하면 로그에 표시된 노드를 잘못 파악하기 쉽습니다. 소스에서 이름을 구분하거나 현재 코어가 명시적으로 지원하는 프로바이더 이름 오버라이드 기능을 사용한 뒤 최종 후보 목록을 확인하는 편이 안전합니다.
노드가 많거나 소스별로 따로 업데이트하고 싶다면 proxy-providers로 소스 이름을 지정하고 그룹에서 use로 불러올 수 있습니다. 아래는 해당 상대 경로를 읽을 수 있는 Mihomo 작업 디렉터리에서 사용하는 파일형 프로바이더 예제입니다. 대상 파일이 미리 있어야 하며, 파일 내용은 앞의 예제처럼 완전한 proxies 매핑으로 작성할 수 있습니다. 노드 정의는 외부 파일에서 관리하고 기본 설정에는 같은 이름의 노드를 다시 정의하지 마세요. 프로바이더 이름은 노드 이름이므로 소스 이름을 규칙 대상으로 직접 지정할 수 없습니다.
proxy-providers:
office-socks:
type: file
path: ./providers/office-socks.yaml
proxy-groups:
- name: 업무용 출구
type: select
use:
- office-socks
proxies:
- DIRECT
설정 로드 오류와 연결 오류를 구분하세요
프로바이더가 그룹에 나타나지 않으면 먼저 참조 이름, 파일 경로, 로드 로그를 확인하세요. 파일은 보이지만 읽을 수 없다면 파일 내용의 구조가 프로바이더 유형과 맞지 않는 경우가 많습니다. 구독 웹페이지, 일반 노드 공유 문자열, 오류 응답을 YAML 파일처럼 사용했을 수 있습니다. 노드가 표시되고 선택도 가능하다면 이제 연결 단계에서 문제를 찾아야 합니다. 서버 도메인 확인, 대상 포트 연결, 핸드셰이크 또는 인증 실패 순으로 점검한 뒤 웹 요청과 테스트 요청의 차이를 비교하세요.
같은 노드로 웹페이지를 열 수 있다고 해서 모든 앱의 전송 방식을 지원하는 것은 아닙니다. udp: true를 설정해도 상위 서버에 UDP 기능이 새로 생기지 않습니다. 전달 가능 여부는 프로토콜, 서버, 클라이언트 연결 방식에 따라 달라집니다. 게임이나 음성 통화는 안 되는데 일반 웹은 된다면 먼저 문제가 발생한 트래픽이 실제로 코어에 들어오는지, 어떤 전송 유형인지 확인한 뒤 규칙에서 어떤 출구를 선택했는지 살펴보세요. 다른 클라이언트와 비교하려면 클라이언트 페이지에서 Clash Plus와 다른 플랫폼용 옵션을 확인하고 운영체제와 필요한 기능에 맞춰 선택하세요.
proxy-groups / 04
프록시 그룹, 후보 노드, 테스트 방식
프록시 그룹은 규칙과 출구 사이의 중간 단계입니다
프록시 그룹은 서버를 직접 지정하지 않습니다. 규칙이 트래픽을 그룹에 전달하면 그룹이 노드, 직결 또는 다른 그룹을 선택합니다. 이렇게 하면 규칙마다 현재 사용하는 서버를 일일이 지정하지 않아도 됩니다. 예를 들어 업무 도메인을 '업무용 출구' 그룹으로 보내면 직결이 필요할 때 그룹 안에서 선택만 바꾸면 됩니다. 같은 그룹을 사용하는 다른 주소에도 변경 사항이 적용됩니다. 특정 도메인 하나만 바꾸려는 경우에는 그룹 전체를 전환하지 말고 그 도메인에 더 구체적인 규칙이 필요한지 확인하세요.
select는 수동 선택 방식입니다. 아래 코드를 사용하려면 기본 설정에 앞 장의 '로컬 업스트림' 노드가 이미 정의되어 있어야 합니다. 로컬 라우팅을 확인할 때는 먼저 DIRECT를 선택해 요청이 실제로 어떻게 처리되는지 기록한 다음 업스트림을 선택하고 같은 요청을 다시 보내세요. 후보 목록에 노드가 보인다고 해서 선택된 것은 아닙니다. 클라이언트가 이전 선택을 기억하고 있을 수도 있으므로 YAML 목록의 첫 항목이 현재 출구라고 단정하지 마세요.
proxy-groups:
- name: 업무용 출구
type: select
proxies:
- DIRECT
- 로컬 업스트림
속도 테스트, 장애 조치, 부하 분산
url-test는 후보 노드에서 지정된 테스트 주소로 요청을 보내고 결과에 따라 출구를 자동 선택합니다. fallback은 순서대로 지정된 후보 중 사용 가능한 항목을 선택하는 데 중점을 둡니다. 가장 먼저 쓸 회선이 원래 더 멀지만 연결이 끊길 때만 예비 회선을 쓰려면 지연 시간 한 번으로 전환하는 대신 장애 조치를 사용하세요. load-balance는 후보 간 연결을 분산합니다. 다운로드 한 번을 여러 회선에 나눠 전송한다는 뜻이 아니며, 로그인 세션의 출구가 중요한 서비스에 검증 없이 적용해서도 안 됩니다.
아래 예제는 직결과 로컬 업스트림으로 자동 테스트를 보여 줍니다. 실제로 특정 유형의 출구를 반드시 사용해야 하는 서비스라면 테스트 결과를 보기 좋게 만들려고 직결을 자동 후보에 넣지 마세요. interval은 초 단위 테스트 간격입니다. 이 그룹에서 tolerance는 지연 시간 차이를 어느 정도 허용해 작은 변화에도 후보가 자주 바뀌는 일을 줄입니다. 테스트 주소는 안정적이고 모든 후보에서 접근할 수 있어야 하며 실제 용도를 잘 반영해야 합니다. 예제 사이트에 접속할 수 있어도 업무 도메인이 같은 출구에서 작동한다는 보장은 없습니다.
proxy-groups:
- name: 연결 테스트
type: url-test
proxies:
- 로컬 업스트림
- DIRECT
url: https://example.com/
interval: 300
tolerance: 50
자동 선택 그룹이 항상 같은 회선을 고른다면 다른 후보의 측정 지연이 큰지, 테스트 시간 초과가 발생하는지, 생성된 그룹에서 빠졌는지 확인하세요. 테스트 요청이 대상 사이트의 속도 제한에 걸리거나 특정 출구에서 예상과 다른 페이지를 받을 수도 있습니다. 특히 모바일 기기에서는 테스트 간격을 몇 초로 줄이지 마세요. 테스트 부하만 늘고 원인을 파악하지 못할 수 있습니다. 문제가 있는 후보 하나를 직접 테스트한 뒤 연결 로그, 현재 선택 항목, 실제 서비스 요청을 비교하세요. 세 항목은 서로 다른 상황을 보여 줍니다.
그룹 중첩과 선택 상태
상위 그룹에 자동 그룹을 넣으면 '용도를 수동으로 선택한 뒤 회선을 자동 선택'하는 구조를 만들 수 있지만 참조가 자기 자신으로 되돌아와서는 안 됩니다. 예를 들어 '업무용 출구'가 '연결 테스트'를 후보로 사용한다면 테스트 그룹에 다시 '업무용 출구'를 넣지 마세요. 로그를 확인할 때는 규칙 대상에서 바깥 그룹, 안쪽 그룹을 거쳐 실제 노드까지 따라가세요. 그룹이 지나치게 여러 겹이면 한 겹 더 추가하기보다 현재 선택을 설명할 수 있을 만큼 단순하게 유지하는 편이 관리하기 쉽습니다.
Mihomo의 profile.store-selected를 사용하면 프록시 그룹 선택을 저장할 수 있습니다. 실제 복원 결과는 클라이언트 프로필 ID, 캐시 디렉터리, 그룹 및 노드 이름에도 영향을 받습니다. 아래 코드는 최상위에 병합하는 설정이며 키 이름은 단수형입니다. 구독을 새로고침한 뒤 원래 노드가 삭제되거나 이름이 바뀌면 저장된 선택으로도 더는 존재하지 않는 후보를 복원할 수 없습니다. 설정을 전환한 뒤에는 몇 번씩 바꿔 보며 추측하기보다 저장된 선택이 아직 후보 목록에 있는지 확인하세요.
profile:
store-selected: true
DIRECT / 05
규칙 문법, 매칭 순서, 기본 대상
첫 번째로 일치하는 규칙부터 확인하세요
규칙 모드에서는 위에서 아래로 규칙을 확인합니다. 일치하는 규칙을 찾으면 지정된 대상으로 트래픽을 보내며, 더 구체적으로 작성된 다음 규칙을 자동으로 찾지 않습니다. 도메인 예외는 해당 도메인을 포함하는 접미사 규칙보다 위에 두고, 특정 IP 예외는 해당 주소가 포함된 네트워크 규칙보다 위에 두세요. '특정 사이트가 항상 잘못된 경로로 간다'면 파일에 도메인이 적혀 있는지만 검색하지 말고 같은 요청에 처음 일치한 규칙부터 확인하세요.
이 예제에서는 '업무용 출구' 프록시 그룹이 이미 정의되어 있다고 가정합니다. DOMAIN은 전체 도메인을 정확히 일치시키고 DOMAIN-SUFFIX는 해당 도메인과 하위 도메인을 일치시킵니다. 따라서 첫 번째 규칙에서 www.example.com을 접미사 규칙과 분리합니다. IP-CIDR은 IPv4 네트워크 대역을 확인하며, 아래 예제에서는 흔히 사용하는 사설 네트워크 세 범위와 로컬 루프백 대역을 직결로 보냅니다. 마지막 MATCH는 앞선 규칙이 모두 일치하지 않을 때 사용하는 기본 규칙입니다. 예제에서는 직결을 지정했지만 실제 기본 대상은 사용 목적에 맞게 선택하세요.
rules:
- DOMAIN,www.example.com,DIRECT
- DOMAIN-SUFFIX,example.com,업무용 출구
- IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
- IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
- IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- MATCH,DIRECT
no-resolve는 클라이언트 전체의 DNS를 끄는 옵션이 아닙니다. 이 IP 규칙을 적용하기 위해 도메인을 추가로 조회하지 않도록 하는 기능입니다. 연결 대상 IP가 이미 있으면 IP를 기준으로 규칙을 확인할 수 있습니다. 따라서 내부 도메인이 사설 IP로 해석되더라도 이 규칙과 일치하지 않을 수 있습니다. 직결해야 하는 도메인을 알고 있다면 사설 대역 규칙이 모든 접속 방식에서 같은 결과를 내리라 기대하지 말고, 앞쪽에 정확한 도메인 규칙이나 적절한 도메인 접미사 규칙을 추가하세요.
주소, 도메인, 실제 확인된 대상
규칙에서 확인할 수 있는 대상은 앱이 코어에 전달한 정보에 따라 달라집니다. 한 앱은 도메인을 프록시에 전달하지만 다른 앱은 미리 DNS 조회를 마친 뒤 IP만 전달할 수 있습니다. 브라우저 주소창에 도메인이 표시된다는 이유만으로 규칙에서 도메인을 확인할 수 있다고 단정하지 마세요. IPv4 네트워크 규칙으로 IPv6 목적지를 처리할 수도 없습니다. 두 주소 체계를 함께 사용하는 환경이라면 연결 세부 정보에서 주소 유형별 실제 목적지를 확인한 뒤 필요한 규칙을 추가하세요. 문제를 진단하는 유일한 방법으로 한쪽 주소 체계를 끄지 마세요.
한 페이지에서도 여러 목적지에 요청을 보냅니다. 기본 페이지가 직결된다고 해서 글꼴, 이미지, 로그인, API 요청도 직결되는 것은 아닙니다. 변경을 확인할 때는 목적지가 분명한 요청 하나를 사용해 규칙 로그와 비교하고, 시간을 맞춘 뒤 기존 연결을 정리하세요. 클라이언트에서 일치한 규칙과 프록시 그룹 경로를 표시한다면 '목적지, 일치 규칙, 그룹, 실제 출구' 순서로 기록하세요. 이렇게 하면 규칙이 잘못 일치했는지, 그룹에서 잘못된 후보를 선택했는지, 라우팅은 정상인데 대상 서비스가 응답하지 않는지 구분할 수 있습니다.
긴 도메인 목록은 프로바이더로 분리
여러 도메인이 같은 출구를 사용한다면 rule-providers로 목록을 관리하고 기본 규칙에는 목록을 넣을 위치와 대상을 지정할 수 있습니다. 아래 로컬 파일은 domain 형식이므로 도메인 항목만 적고 쉼표로 구분된 완전한 규칙은 넣지 않습니다. 기본 설정에서는 RULE-SET으로 목록을 한 번 매칭합니다. 목록은 조건만 제공하고 대상은 기본 설정에서 지정합니다. 규칙 유형과 조건을 모두 옮기려면 코어가 지원하는 classical 형식으로 정리해야 합니다. 정책 대상이 포함된 규칙 한 줄 전체를 그대로 복사할 수는 없습니다.
rule-providers:
office-domains:
type: file
behavior: domain
format: yaml
path: ./rules/office-domains.yaml
rules:
- RULE-SET,office-domains,업무용 출구
- MATCH,DIRECT
# ./rules/office-domains.yaml
payload:
- 'example.com'
- 'www.example.com'
목록을 파일로 나눌지보다 큰 목록에서 예외 규칙을 어디에 둘지가 더 중요합니다. 예외 항목을 먼저 직결 처리해야 한다면 이를 포함하는 RULE-SET보다 위에 두세요. 기본 규칙 뒤에 규칙 세트를 넣으면 매칭될 기회가 없습니다. REJECT를 사용할 때도 먼저 접속이 필요하지 않은 정확한 도메인 하나로 동작을 확인하세요. 차단 규칙이 일치하면 화면에서는 네트워크 오류와 비슷하게 보일 수 있으므로 프록시 모드를 계속 전환하기보다 연결 기록을 확인하는 편이 낫습니다.
dns / 06
DNS 업스트림, 가상 IP, TUN 연결
먼저 DNS 조회를 처리하는 주체를 확인하세요
코어의 dns는 코어 자체의 DNS 처리 방식을 제어합니다. 업스트림을 설정해도 운영체제, 브라우저, 모든 앱이 자동으로 코어에 DNS 조회를 맡기는 것은 아닙니다. 브라우저가 자체 암호화 DNS를 사용하거나 앱이 연결을 프록시에 전달하기 전에 DNS 조회를 끝낼 수 있고, 시스템에 이전 캐시가 남아 있을 수도 있습니다. '코어에 업스트림을 입력했는데 다른 결과가 나온다'면 먼저 테스트가 시스템 DNS 리졸버에 직접 질의하는지, 코어의 DNS 수신 포트에 질의하는지, 프록시가 앱 대신 도메인을 처리하는지 확인하세요.
아래 예제는 조회 경로를 구분할 수 있도록 루프백 주소의 비표준 포트에서 DNS를 수신합니다. 활성화한 뒤 dig를 사용할 수 있는 환경에서 해당 포트로 직접 조회할 수 있습니다. 예제의 업스트림은 공개 DNS 서비스이므로 현재 네트워크에서 접속할 수 있어야 합니다. 조직 내부의 사설 도메인에는 보통 조직에서 제공하는 DNS 서버가 필요합니다. 한 번 응답을 받았다는 사실은 해당 경로에서 응답을 받았다는 것만 보여 줍니다. 브라우저가 이 서버를 사용한다거나 모든 앱에 적합한 결과를 돌려준다는 뜻은 아닙니다.
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: redir-host
nameserver:
- 223.5.5.5
dig @127.0.0.1 -p 1053 example.com A
서비스 도메인과 노드 도메인을 나눠 확인하세요
nameserver는 일반 조회에 사용할 업스트림 목록입니다. 특정 도메인 그룹을 별도로 처리해야 할 때 Mihomo의 nameserver-policy로 해당 도메인의 업스트림을 지정할 수 있습니다. 먼저 지정한 도메인에 이 업스트림이 실제로 응답할 수 있는지 확인한 뒤 필요한 범위만 매칭하세요. 조직 내부 도메인을 공용 DNS로 보내면 조회 결과를 받지 못할 수 있습니다. 공용 업스트림을 계속 추가해 재시도하기보다 직결 상태에서 시스템이 어떤 DNS 서버를 사용하는지 확인하세요.
업스트림 자체를 도메인 이름으로 지정했다면 DNS 서버를 찾는 방법도 고려해야 합니다. default-nameserver는 DNS 서버의 도메인 이름을 조회하고, proxy-server-nameserver는 프록시 노드 서버의 도메인 이름을 조회합니다. 이 설정으로 노드 연결에 필요한 사전 조회와 일반 조회를 분리할 수 있습니다. 진단할 때는 의존성이 서로 순환하는지 특히 주의하세요. DNS 서버에 접속하려면 먼저 노드에 연결해야 하는데 노드 주소를 찾으려면 그 DNS 서버가 필요한 상황이 생길 수 있습니다. 독립적으로 동작하는 DNS 경로를 먼저 복구한 다음, 규칙에 따라 DNS 출구를 선택하는 설정을 하나씩 되돌리세요.
가상 IP는 서버의 실제 주소가 아닙니다
fake-ip 모드에서는 코어가 도메인에 가상 IP를 응답할 수 있습니다. 이후 해당 연결이 코어에 들어오면 매핑을 통해 원래 도메인을 찾습니다. 로그에 198.18.0.0/16 범위의 주소가 표시되어도 공용 웹사이트가 그 주소로 옮겨 간 것은 아닙니다. 아래는 별도의 대체 설정입니다. 앞에서 작성한 dns 블록 뒤에 이어 붙여 중복 키를 만들지 마세요. 실제 DNS 결과가 필요하고 호환성 문제가 확인된 내부 도메인에 한해 fake-ip-filter를 사용하세요.
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- '+.lan'
nameserver:
- 223.5.5.5
DNS 모드를 전환했는데 앱이 이전 캐시를 유지하고 있다면 기존 가상 IP로 계속 연결을 시도할 수 있습니다. 먼저 영향을 받는 앱에서 DNS 조회를 다시 시작한 다음 DNS 응답과 연결 로그를 비교하세요. 같은 환경에서 해당 주소 대역을 테스트나 내부 라우팅에 사용하고 있다면 주소 충돌 여부도 확인하세요. DNS 조회 실패, 응답은 받았지만 코어에 연결되지 않는 경우, 코어에 연결됐지만 출구가 잘못된 경우는 서로 다른 문제입니다. 업스트림, 규칙, 포트를 한꺼번에 바꿀 필요는 없습니다.
TUN은 트래픽을 연결하며 라우팅 규칙을 대신하지 않습니다
TUN은 가상 인터페이스로 트래픽을 연결합니다. 앱에 프록시 포트를 직접 입력하는 것과는 다릅니다. 활성화하기 전에 클라이언트가 인터페이스를 만들고 라우팅을 설정할 권한이 있는지 확인하세요. 같은 트래픽을 가로채는 다른 연결 도구는 먼저 꺼서 기준 상태를 비교하세요. 아래 설정은 자동 라우팅을 활성화하고 조건에 맞는 일반 DNS 조회를 코어로 전달합니다. 앱 자체의 암호화 DNS 요청을 일반 조회로 바꾸지는 않습니다. 클라이언트가 이미 TUN 매개변수를 관리한다면 생성된 실행 설정을 먼저 확인하고 설정을 중복으로 추가하지 마세요.
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53
스위치를 켰는데 대상 연결이 보이지 않는다면 인터페이스가 생성됐는지, 시스템 경로가 인터페이스를 가리키는지, 플랫폼에서 앱 트래픽을 제외했는지 확인하세요. 로그에 연결이 이미 나타난다면 규칙이나 DNS를 점검하고 가상 네트워크 어댑터를 계속 껐다 켜지 마세요. 로컬 인쇄, 파일 공유, 업무 연결에 문제가 생기면 먼저 TUN을 꺼서 복구한 뒤 단일 목적지로 테스트해 라우팅 연결과 이름 조회 중 어디서 달라졌는지 확인하세요.
config.yaml / 07
구독 오버라이드, 필드 병합, 복구
업데이트되는 소스와 로컬 변경을 분리하세요
구독은 업데이트되는 노드와 규칙을 제공하고, 로컬 오버라이드는 포트, 자주 쓰는 예외, 로컬 환경에 맞는 DNS 설정을 관리합니다. 새로고침할 때마다 덮어쓰이는 원본 파일을 매번 직접 수정하는 것은 권장하지 않습니다. 클라이언트에서 오버라이드를 지원한다면 전체 프로필에 적용되는지 특정 프로필에만 적용되는지 먼저 확인한 뒤 유지해야 할 필드를 설정하세요. 관련 기능이 없다면 로컬 프로필로 복사해 시험할 수 있습니다. 변경 사항은 유지되지만 해당 복사본에는 다음 구독 내용이 자동으로 반영되지 않습니다.
클라이언트마다 같은 오버라이드 문법을 사용한다고 가정하지 마세요. 일부 편집 기능은 완전한 Mihomo YAML을 받고, 일부는 클라이언트 전용 병합 명령을 사용하며, 다른 기능은 화면에서 제한된 필드만 수정할 수 있습니다. 기능 이름이 '병합'이더라도 스칼라 값이 교체되는지 유지되는지, 매핑이 키별로 병합되는지, 리스트가 전체 교체되는지 각각 확인해야 합니다. 코어가 알 수 없는 확장 키가 표시된다면 노드 문제를 의심하기 전에 오버라이드 파일을 코어 설정으로 직접 선택했는지 확인하세요.
스칼라, 매핑, 순서가 있는 리스트를 각각 비교하세요
포트는 스칼라이므로 최종 설정에는 값이 하나만 남습니다. dns는 매핑이며 도구에 따라 한 키만 바꾸기도 하고 블록 전체를 교체하기도 합니다. 원래 설정에 nameserver가 있는데 enable만 오버라이드한 뒤 실행 설정에서 업스트림이 사라졌다면 하위 키만 남기는 방식으로 병합된 것이 아닙니다. 매핑이 복잡한 프로필에서는 현재 적용된 값을 먼저 내보낸 뒤 도구의 실제 동작에 따라 매핑 전체를 제출해야 하는지 판단하세요.
규칙과 프록시 그룹은 모두 리스트지만 비교할 때 확인할 내용은 다릅니다. 규칙은 순서가 우선순위를 결정하고, 프록시 그룹은 이름과 후보 참조 관계가 중요합니다. 원래 프로필에 '업무용 출구'가 정의되어 있고 아래 첫 번째 규칙 목록이 사용 중이라고 가정해 보세요. www.example.com 하나만 직결하려면 두 번째 목록이 최종적으로 필요한 결과입니다. 두 예제는 모두 일반적인 코어 YAML이며 병합 결과를 확인하기 위한 것입니다. 어떤 클라이언트에서나 공통으로 사용할 수 있는 오버라이드 명령은 아닙니다. 추가 방식으로 규칙을 MATCH 뒤에 붙이면 파일은 불러올 수 있어도 예외는 적용되지 않습니다.
rules:
- DOMAIN-SUFFIX,example.com,업무용 출구
- MATCH,DIRECT
rules:
- DOMAIN,www.example.com,DIRECT
- DOMAIN-SUFFIX,example.com,업무용 출구
- MATCH,DIRECT
업데이트 후 같은 이름의 프록시 그룹이 두 개 나타나면 앞에 있는 그룹 하나만 남기고 끝내지 마세요. 리스트를 잘못 이어 붙였는지 확인한 다음 각 그룹의 기존 후보가 어디에서 왔는지 살펴보세요. 이름 기준으로 그룹 하나를 교체해야 할 수도 있고 특정 그룹의 후보만 수정하면 될 수도 있습니다. 노드 프로바이더 경로를 오버라이드 디렉터리에서 실행 디렉터리로 옮겼다면 경로를 해석하는 위치도 달라질 수 있습니다. 상대 경로는 코어가 실제로 사용하는 작업 디렉터리를 기준으로 확인하세요.
파싱, 연결, 매칭 순서로 확인
변경 전에 실행 가능한 설정을 따로 저장하고 현재 프로필과 모드를 기록하세요. 변경한 뒤에는 생성된 파일에 대상 필드가 있는지 확인한 다음 불러와 파싱 오류와 포트 충돌 알림이 없는지 살펴보세요. 정상적으로 시작되면 같은 연결 방식으로 직결되어야 하는 목적지와 프록시 그룹을 사용해야 하는 목적지 두 개만 비교하고 일치한 규칙과 출구를 확인하세요. 두 결과가 모두 예상대로라면 구독을 한 번 수동으로 업데이트한 뒤 생성 파일을 다시 확인해 변경 사항이 업데이트 후에도 유지되는지 점검하세요.
새 설정을 불러오자마자 앱이 종료되거나 시스템 네트워크가 끊기면 마지막으로 적용한 오버라이드를 되돌리고 정상 작동이 확인된 프로필을 복원하세요. 시스템 프록시나 TUN이 종료된 코어를 계속 가리키지 않는지도 확인하세요. 복구가 끝나면 최소 변경 하나만 다시 적용하고 의미 있는 첫 오류를 보존하세요. 포트, DNS, 전체 규칙 목록을 한 번에 바꾸기보다 어느 단계에서 문제가 생겼는지 먼저 확인하는 편이 낫습니다. 로그를 바탕으로 계속 점검하려면 시작 직후 종료될 때 해결 방법과 자주 발생하는 문제 해결을 참고하세요.