Clash config.yaml 항목별 해설: 포트, DNS, proxies와 rules 작성법
전체 설정 파일을 순서대로 살펴보며 mixed-port, dns, proxies, proxy-groups, rule-providers, rules의 역할과 자주 쓰는 작성법을 설명합니다.
전체 예제로 설정 항목 간 참조 관계 살펴보기
이 예제는 인라인 규칙 집합을 지원하는 mihomo(구 Clash Meta)를 기준으로 작성했습니다. 도메인 규칙과 명시적 프록시 요청으로 트래픽 분기를 확인하며, 구독 업데이트나 TUN은 사용하지 않습니다. Clash 원본도 같은 이름의 일부 필드를 인식하지만, 이 파일을 모든 코어에서 사용할 수 있는 설정으로 간주하지 마세요. 특히 규칙 집합 유형을 지원하는지 먼저 확인해야 합니다.
mixed-port: 7890
allow-lan: false
mode: rule
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
nameserver:
- 223.5.5.5
proxies:
- name: "로컬 SOCKS5"
type: socks5
server: 127.0.0.1
port: 1080
proxy-groups:
- name: "업무용 프록시"
type: select
proxies:
- DIRECT
- "로컬 SOCKS5"
rule-providers:
office-domains:
type: inline
behavior: domain
payload:
- "+.example.org"
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- RULE-SET,office-domains,업무용 프록시
- MATCH,DIRECT
요청이 mixed-port로 들어오면 코어는 규칙 모드에서 rules를 위에서부터 차례로 확인합니다. office-domains와 일치하면 「업무용 프록시」로 전달된 다음, 해당 그룹에서 현재 선택된 출구를 사용합니다. 최종 출구로 DIRECT를 선택해도 규칙은 정책 그룹과 일치할 수 있습니다. 트래픽 분기가 올바른지 판단하려면 일치한 규칙과 실제 출구를 모두 확인해야 합니다.
mixed-port: 로컬 연결 포트와 업스트림 포트 구분하기
mixed-port: 7890을 설정하면 코어가 하나의 로컬 포트에서 HTTP 프록시와 SOCKS5 프록시 연결을 모두 받습니다. 앱에는 127.0.0.1:7890을 입력합니다. 반면 proxies의 1080은 코어가 예시 노드를 선택한 뒤 연결하는 업스트림 포트입니다. 하나는 앱이 코어에 연결하는 포트이고, 다른 하나는 코어가 업스트림에 연결하는 포트이므로 서로 바꿔 쓸 수 없습니다.
allow-lan: false는 로컬 기기에서 사용하는 설정입니다. 수신 포트를 지정해도 운영체제의 프록시 설정이 자동으로 켜지지는 않습니다. 특정 앱만 테스트하려면 먼저 앱에서 포트에 직접 연결하세요. 시스템 프록시를 따르지 않는 앱도 연결해야 한다면 TUN 사용을 별도로 검토하세요. TUN은 가상 네트워크 인터페이스를 통해 라우팅 설정에 해당하는 트래픽을 처리하며, 앱이 직접 7890에 연결하는 방식과는 진입 경로가 다릅니다.
포트가 이미 사용 중일 때 변경할 항목
로그에 address already in use가 표시되면 먼저 코어 인스턴스가 두 개 실행 중인지 확인하세요. 포트를 7891로 변경하려면 브라우저 프록시나 터미널 매개변수 등에 수동으로 입력한 포트도 모두 7891로 바꿔야 합니다. 데스크톱 클라이언트가 설정 파일의 포트를 덮어쓸 수 있으므로, 진단할 때는 시작 로그에 표시된 실제 수신 포트를 기준으로 확인하세요.
dns: 업스트림 DNS와 fake-ip의 차이
dns.enable: true는 코어의 DNS 모듈을 활성화하며, nameserver는 일반적인 도메인 조회에 사용할 업스트림 DNS를 지정합니다. 이 예제에서는 IP 주소가 223.5.5.5인 일반 DNS 서비스를 사용합니다. 실행 전에 현재 네트워크에서 접속할 수 있는지, 사용 중인 네트워크의 DNS 요구 사항에 맞는지 확인하세요. 이 항목만 수정해도 운영체제나 브라우저의 모든 DNS 요청이 코어를 거치는 것은 아닙니다. 브라우저 자체의 보안 DNS, 앱에서 지정한 프록시, TUN의 DNS 처리 여부는 각각 따로 확인해야 합니다.
enhanced-mode: fake-ip에서는 조건에 맞는 도메인의 A 레코드 조회에 코어가 임시 매핑 주소를 반환할 수 있습니다. 198.18.0.0/16 범위의 주소가 보이더라도 웹사이트가 해당 네트워크에 배포되어 있다는 뜻은 아닙니다. 이후 연결도 같은 코어를 거쳐야 매핑된 주소에서 원래 도메인을 확인할 수 있습니다. HTTPS 사이트에 HTTP 프록시로 접속하는 경우 앱은 보통 CONNECT 요청에 대상 호스트 이름을 전달하므로, 도메인 규칙에 일치시키기 위해 먼저 fake IP를 확인할 필요는 없습니다.
fake-ip 사용 후 로컬 네트워크 서비스에 접속할 수 없을 때
먼저 해당 도메인의 DNS 조회가 코어를 거치는지 확인한 다음, 같은 앱의 연결도 코어를 통과하는지 살펴보세요. 앱이 매핑 주소를 받았지만 코어를 우회해 연결한다면 nameserver만 바꿔서는 보통 해결되지 않습니다. 서비스에서 실제 주소가 필요하다고 확인되면 기존 dns 항목에 fake-ip-filter를 추가해 printer.home.arpa처럼 특정 도메인을 제외할 수 있습니다. 업스트림 DNS가 이 로컬 도메인을 조회할 수 있는지도 확인하세요. 필터는 응답 주소의 반환 방식을 바꿀 뿐, 공용 DNS에 로컬 네트워크 기록을 추가하지는 않습니다.
proxies와 proxy-groups: 노드와 정책 그룹 분리 관리
최상위 proxies는 업스트림에 연결하는 데 필요한 매개변수를 정의합니다. 각 노드에는 이름, 프로토콜, 서버, 포트가 있으며 나머지 항목은 프로토콜에 따라 달라집니다. 예제에서는 type: socks5를 사용합니다. 다른 프로토콜로 바꿀 때 type만 수정하고 기존 필드를 그대로 두면 안 됩니다. 노드가 구독에서 제공되는 경우 구독이 완성된 설정 파일을 생성하는지, 아니면 클라이언트가 proxy-providers로 노드 목록을 불러오는지 먼저 확인하세요.
proxy-groups는 라우팅에 사용할 수 있는 출구를 정의합니다. 그룹 안의 proxies에는 이름만 나열하며 서버 주소를 다시 입력하지 않습니다. DIRECT는 기본 제공되는 직접 연결 정책입니다. 「업무용 프록시」는 select 유형이므로 클라이언트에서 직접 선택하며, 속도 측정 결과에 따라 노드가 자동으로 바뀌지 않습니다. 노드가 이름이 지정된 proxy-providers에서 제공된다면 정책 그룹에서 use로 제공자를 참조할 수 있습니다. 제공자 이름을 노드 이름으로 잘못 입력하지 마세요.
이름을 변경할 때는 참조 관계를 따라 확인하세요. 노드 「로컬 SOCKS5」의 이름을 바꾸면 그룹의 구성원 목록도 수정해야 합니다. 그룹 「업무용 프록시」의 이름을 바꾸면 규칙의 대상도 수정해야 합니다. 이름에 공백 하나만 추가되어도 서로 다른 이름으로 처리됩니다. 주기적으로 갱신되는 구독이라면 클라이언트의 덮어쓰기 또는 병합 기능으로 로컬 변경 사항을 보존하는 것이 좋습니다. 구독 캐시를 직접 수정하면 다음 업데이트 때 변경 사항이 덮어써질 수 있습니다.
rule-providers와 rules: 규칙 집합을 정의하고 출구 지정하기
rule-providers는 규칙 집합을 정의하며, 그 자체로 트래픽 출구를 지정하지는 않습니다. 예제의 office-domains는 behavior: domain을 사용해 +.example.org로 루트 도메인과 하위 도메인을 모두 포함합니다. 정책 연결은 RULE-SET,office-domains,업무용 프록시에서 이루어집니다. 규칙 집합만 정의하고 이 참조 규칙을 작성하지 않으면 요청은 해당 규칙 집합으로 매칭되지 않습니다.
| behavior | 항목 예시 | 용도 |
|---|---|---|
domain | +.example.org | 지정한 도메인과 모든 하위 도메인에 일치합니다. |
ipcidr | 192.0.2.0/24 | 대상 IP 대역에 일치합니다. 여기서는 문서용 예시 대역을 사용합니다. |
classical | DOMAIN-SUFFIX,example.org | 규칙 유형은 유지하고 항목 뒤에 정책 그룹 이름을 추가하지 않습니다. |
규칙 집합을 로컬 파일로 분리하려면 type을 file로 바꾸고 format: yaml과 path: ./rules/office.yaml을 지정한 뒤, 기존 payload 전체를 해당 YAML 파일로 옮기세요. 상대 경로는 코어의 작업 디렉터리를 기준으로 하므로 클라이언트 화면에 표시된 구독 파일과 같은 디렉터리라고 가정하면 안 됩니다. 원격 업데이트에는 type: http를 사용하고 url과 초 단위의 interval을 설정하세요. 파일 형식과 behavior도 서로 일치해야 합니다.
규칙 우선순위는 목록 순서로 결정됩니다
규칙 모드에서는 코어가 rules를 위에서부터 확인하고 처음 일치한 규칙의 정책을 적용합니다. status.example.org를 항상 직접 연결하려면 DOMAIN,status.example.org,DIRECT를 해당 RULE-SET보다 앞에 배치하세요. 뒤에 두면 더 넓은 범위의 규칙 집합이 먼저 일치해 예외 규칙이 적용되지 않습니다. MATCH는 모든 요청에 적용되는 기본 규칙이므로 반드시 마지막에 두세요. 이 규칙의 정책을 특정 그룹으로 바꾸면 앞선 규칙에 일치하지 않은 모든 요청의 처리 방식이 바뀝니다.
설정 확인: 파일 로드, 연결 진입점, 규칙 일치 순서로 점검
- 파일을 불러올 수 있는지 확인합니다. 들여쓰기에는 공백을 사용하고 같은 단계의 키를 나란히 맞추세요.
dns처럼 기존 항목을 수정할 때는 원래 항목에 내용을 합치고, 최상위에 같은 이름의 키를 중복으로 만들지 마세요. 별도의 mihomo 명령줄 도구가 있다면 예제 파일이 있는 디렉터리에서mihomo -t -f ./config.yaml을 실행할 수 있습니다. 검증을 통과했다는 것은 설정을 읽고 검사할 수 있다는 뜻일 뿐, 업스트림 연결까지 확인된 것은 아닙니다. - 요청이 올바른 코어로 들어가는지 확인합니다. 설정을 불러오고 모드가 규칙으로 되어 있는지 확인한 다음, 「업무용 프록시」에서
DIRECT를 선택하세요. 아래 명령은7890을 명시적으로 사용하므로 운영체제의 프록시 설정이나 브라우저 확장 프로그램이 테스트에 영향을 주지 않습니다. 로컬 포트 연결이 즉시 거부되면 DNS를 바꾸기 전에 먼저 포트가 수신 대기 중인지 확인하세요. - 두 대상의 규칙 일치 기록을 비교합니다. 클라이언트의 연결 기록을 확인하고, 필요하면 로그에서 도메인을 검색하세요.
example.org는office-domains에 일치한 뒤 「업무용 프록시」에서 선택한 직접 연결을 사용해야 합니다.example.com은 첫 번째 도메인 접미사 규칙에 바로 일치해야 합니다. 두 사이트가 모두 열리더라도 규칙이 올바르다고 단정할 수는 없습니다. 마지막의MATCH,DIRECT만으로도 요청을 직접 연결할 수 있기 때문입니다.
curl --noproxy "" --proxy http://127.0.0.1:7890 --max-time 10 -I https://example.org/
curl --noproxy "" --proxy http://127.0.0.1:7890 --max-time 10 -I https://example.com/
위 명령은 일반적인 Unix 셸에서 사용할 수 있습니다. Windows PowerShell에서는 curl.exe를 호출하고 빈 문자열 인수가 프로그램에 전달되는지 확인하세요. 여기서 --noproxy ""는 환경 변수에 설정되어 있을 수 있는 우회 목록을 비우며, --max-time 10은 요청 하나의 전체 제한 시간을 10초로 설정합니다.
정책 그룹에는 올바르게 일치하지만 「로컬 SOCKS5」로 전환한 뒤에만 실패한다면 1080 포트에서 서비스가 수신 대기 중인지 확인하고 업스트림 프로토콜과 인증 매개변수도 점검하세요. 요청이 여전히 기본 규칙으로 처리된다면 현재 적용된 설정, 도메인이 코어에 전달되는 방식, 앞선 규칙에서 먼저 가로채는지 확인하세요. 한 번에 한 항목만 바꾸고 같은 도메인으로 다시 테스트해야 변경 효과를 판단할 수 있습니다.