Clash config.yaml 설정 가이드: 포트·DNS·proxy-groups·rules 구조

1. 설정 파일 출처와 커널, YAML 구조부터 확인하기

config.yaml은 흔히 쓰이는 설정 파일 이름일 뿐, 모든 클라이언트가 이 파일을 사용하는 것은 아닙니다. 구독에서 내려받은 설정, 로컬 설정, 클라이언트가 생성한 실행 설정은 서로 다른 위치에 저장될 수 있습니다. 편집하기 전에 클라이언트의 설정 목록에서 현재 활성화된 항목을 확인하고 실제 실행 설정을 살펴보세요. 비활성 파일을 수정해도 현재 연결에는 영향을 주지 않습니다.

Clash는 프록시 설정 체계이며, Clash Meta는 이후 mihomo라는 이름을 사용합니다. 여러 기본 항목은 공통으로 쓸 수 있지만, 지원 프로토콜과 DNS 옵션, TUN 설정은 커널과 버전에 따라 달라집니다. 이 글에서는 먼저 공통 구조를 설명하고 mihomo 확장 항목은 따로 표시합니다. 클라이언트마다 화면에 표시되는 이름이 다르므로, 앱 아이콘만 보고 현재 커널을 판단할 수는 없습니다.

YAML을 읽을 때 먼저 볼 세 가지

들여쓰기는 항목의 소속을 나타냅니다. 이 글에서는 Tab 대신 공백 2칸을 사용합니다. 최상위의 dns, proxies, rules는 같은 위치에서 시작합니다.
콜론으로 키와 값을 구분합니다. mode: rule처럼 작성하고, 전각 콜론은 사용하지 마세요. 줄 맨 앞의 -는 목록 항목을 나타냅니다.
이름은 참조 관계를 만듭니다. 규칙에서 지정한 정책 그룹이 실제로 있어야 합니다. 그룹 안에서 참조하는 노드나 다른 그룹도 존재해야 합니다.

2. 포트와 모드: 트래픽이 커널로 들어오는 방식 정하기

파일 앞부분에는 보통 수신 포트, 실행 모드, 로그 수준이 설정됩니다. 포트는 요청을 받아들이고, 모드는 요청이 들어온 뒤 어떤 출구로 보낼지 결정합니다. 두 과정은 별개입니다. 규칙이 올바르더라도 앱에서 트래픽을 클라이언트로 보내지 않으면 예상한 프록시 연결이 이루어지지 않습니다.

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

항목	예시 의미	확인할 점
`mixed-port`	7890에서 HTTP와 SOCKS 프록시 요청을 모두 수신	앱에 입력한 포트가 일치하고 다른 프로세스가 사용 중이지 않아야 합니다
`allow-lan`	false는 다른 LAN 기기의 접속을 허용하지 않는다는 뜻입니다	공유할 때는 수신 주소와 방화벽도 확인하세요
`mode`	rule은 규칙 목록에 따라 연결을 매칭합니다	전체 모드에서는 rules의 매칭 순서를 확인할 수 없습니다
`log-level`	info는 일반적인 실행 정보를 출력합니다	임시로 문제를 진단할 때는 debug로 바꾸고, 완료 후 원래대로 되돌리세요
`ipv6`	false는 커널의 해당 IPv6 지원 기능을 끕니다	운영체제의 모든 IPv6 트래픽을 차단한다는 뜻은 아닙니다

mixed-port, port, socks-port 중 무엇을 선택할까요?

port는 HTTP 프록시 포트이고 socks-port는 SOCKS 프록시 포트입니다. 하나의 포트로 통합하려면 mixed-port를 사용할 수 있습니다. 예를 들어 앱에 HTTP 프록시로 127.0.0.1:7890을 입력했다면 커널은 7890 포트에서 해당 요청을 수신해야 합니다. 서로 다른 수신 항목에 같은 주소와 포트를 지정하지 마세요.

mode: rule은 규칙에 따라 트래픽을 분기하고, global은 전역 정책을 사용하며, direct는 직접 연결합니다. 모드를 바꿔도 브라우저의 시스템 프록시 설정은 자동으로 변경되지 않습니다. 처음 연결을 확인할 때는 시스템 프록시를 먼저 사용하고, 기본 연결이 확인된 뒤 TUN을 켜세요. 그래야 여러 진입 경로를 동시에 점검하는 일을 피할 수 있습니다.

external-controller: 127.0.0.1:9090은 보통 제어 API의 수신 주소이며, 인터넷 연결용 프록시 포트가 아닙니다. 브라우저 프록시 설정에 9090을 입력하지 말고, 편의를 위해 제어 인터페이스를 인터넷에 공개하지도 마세요.

3. dns: DNS 서버, 수신 주소, fake-ip 구분하기

dns는 커널로 전달된 도메인 조회 요청을 처리하는 방식을 정합니다. 아래 예시는 redir-host를 기준으로 기본 구조를 설명합니다. 두 IP는 예시용 DNS 서버이며 모든 네트워크에서 사용할 수 있는 것은 아닙니다. 사용하기 전에 현재 네트워크에서 접속 가능한지 확인하고 DNS 요청의 개인정보 보호도 고려하세요.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: redir-host
  nameserver:
    - 223.5.5.5
    - 119.29.29.29

enable: true는 커널의 DNS 기능을 켜지만, 시스템의 모든 DNS 요청을 자동으로 커널에 전달하지는 않습니다.
listen은 로컬 DNS 수신 주소를 지정합니다. 예시는 1053 포트를 사용하며, 시스템에서 흔히 쓰는 53 포트가 아닙니다. 별도의 전달 설정이 없으면 시스템은 이 포트에 자동으로 질의하지 않습니다.
nameserver는 업스트림 DNS 서버 목록입니다. 일반 DNS는 보통 53 포트를 사용하며, DoH와 DoT는 각 프로토콜에 맞는 주소를 사용합니다.
dns.ipv6: false는 해당 DNS 모듈이 AAAA 질의를 처리하는 방식을 제어합니다. 운영체제 수준의 IPv6 방화벽 설정은 아닙니다.

fake-ip 주소가 198.18로 시작하는 이유는 무엇인가요?

enhanced-mode: fake-ip를 사용하면 도메인에 매핑 주소를 할당하고, 커널이 연결을 원래 도메인과 연결합니다. 설정에서 자주 보이는 fake-ip-range: 198.18.0.1/16은 이러한 매핑에 쓰이며 웹사이트 서버의 실제 공인 IP 주소가 아닙니다. 따라서 이 대역이 보인다고 해서 DNS가 오염됐다고 단정할 수는 없습니다.

일부 LAN 서비스나 기기 검색 기능, 실제 DNS 주소에 의존하는 프로그램은 예외 설정이 필요할 수 있습니다. 실제 문제가 확인된 경우에만 fake-ip-filter를 설정하고, 범위가 넓은 도메인을 한꺼번에 많이 추가하지 마세요. redir-host와 fake-ip는 동작 방식이 다르므로 전환한 뒤에는 새 연결을 만들어 테스트해야 합니다.

mihomo에서 노드 도메인 해석 시 따로 확인할 점

프록시 서버 주소도 도메인 이름일 수 있습니다. mihomo의 proxy-server-nameserver 같은 항목으로 노드 도메인의 해석 방식을 지정할 수 있습니다. 업스트림 DoH 주소 자체가 도메인이라면 초기 해석에 default-nameserver가 필요할 수도 있습니다. 노드 도메인을 해석하려면 프록시가 필요하고, 프록시를 연결하려면 그 도메인의 해석이 필요한 순환 의존성이 생길 수 있습니다. 실행 후 모든 노드가 시간 초과된다면 규칙만 바꾸지 말고 먼저 로그에서 도메인 해석 오류를 확인하세요.

4. proxies: 노드 설정은 구독 링크와 다릅니다

proxies는 노드 정의 목록입니다. 노드에는 보통 name, type, server, port가 있으며, 나머지 인증 및 전송 항목은 프로토콜에 따라 달라집니다. 노드 이름은 정책 그룹에서 참조하고, 서버 포트는 원격 서버의 포트입니다. 로컬의 7890 포트와 혼동하지 마세요.

이 글에서는 서버 주소나 비밀번호를 임의로 만들지 않습니다. 구조를 이해할 때는 proxies: []로 노드 목록을 비워 두고 정책 그룹에서 내장 출구인 DIRECT를 참조할 수 있습니다. 이 설정은 직접 연결을 이용한 트래픽 분기를 보여줄 뿐, 프록시 서비스를 제공하지는 않습니다. 실제 프록시를 사용하려면 서비스 제공업체가 전달한 노드 설정을 현재 커널이 지원하는 형식으로 추가해야 합니다.

구독 주소는 어디에 입력하나요?

전체 설정 구독: 클라이언트의 구독 또는 설정 화면에서 가져오세요. 내려받은 내용에는 노드, 정책 그룹, 규칙이 이미 포함되어 있을 수 있습니다.
노드 목록 구독: 지원되는 proxy-providers 기능으로 불러온 뒤 정책 그룹에서 use로 참조할 수 있습니다.
단일 노드 공유 링크: 클라이언트에서 인식하거나 변환해야 합니다. YAML 노드 객체처럼 proxies에 바로 붙여 넣을 수는 없습니다.

일반 웹페이지, 로그인 화면, 만료 안내 페이지는 노드 목록이 아닙니다. 가져온 뒤 파싱 오류가 발생하면 들여쓰기를 계속 바꾸기 전에 응답 내용을 먼저 확인하세요. 전체 설정과 provider용 노드 목록 형식도 구분해야 합니다. 파일 확장자가 모두 YAML이라고 해서 내부 구조까지 서로 바꿔 쓸 수 있는 것은 아닙니다.

proxy-providers에서 흔히 쓰는 interval: 3600은 리소스를 3600초마다 갱신한다는 뜻입니다. 정책 그룹의 상태 검사에서 interval: 300은 300초마다 검사한다는 뜻입니다. 두 설정은 용도가 다르며 지연 시간 기준이 아닙니다. 전체 구독을 갱신하는 클라이언트 설정을 대신하지도 않습니다.

5. proxy-groups: 노드를 선택 가능한 출구로 구성하기

규칙은 보통 정책 그룹을 지정하고, 정책 그룹에서 노드나 다른 출구를 선택합니다. 이렇게 구성하면 노드를 바꿀 때 규칙을 하나씩 수정할 필요가 없습니다. 아래 예시의 그룹 이름은 ‘출구 선택’이며, 참조 관계를 확인하기 위해 내장 직접 연결 출구만 포함합니다.

proxies: []

proxy-groups:
  - name: 출구 선택
    type: select
    proxies:
      - DIRECT

자주 쓰이는 정책 그룹 세 가지 비교

유형	선택 방식	사용 시 유의점
`select`	사용자가 그룹 안에서 출구를 직접 선택	먼저 노드를 고정한 뒤 규칙과 연결 상태를 점검하기 좋습니다
`url-test`	테스트 결과에 따라 지연 시간이 짧은 출구를 자동 선택	테스트 URL의 응답 시간은 다운로드 속도와 다릅니다
`fallback`	목록 순서에 따라 사용 가능한 출구 선택	우선순위는 목록 순서로 정해지며 지연 시간이 가장 짧은 순서가 아닙니다

url-test와 fallback에는 보통 테스트 주소와 검사 간격 등의 설정도 필요합니다. 테스트 주소에 현재 네트워크에서 접속할 수 있어야 합니다. 테스트 사이트에 문제가 생기면 정상 노드 여러 개가 동시에 사용할 수 없는 것으로 표시될 수도 있습니다. 한 번의 지연 시간 테스트만으로 노드를 삭제하지 마세요.

그룹 이름과 노드 이름은 중복되지 않도록 명확하게 정하세요. 규칙이 ‘출구 선택’을 참조한다고 가정하면, 이름을 ‘프록시 출구’로 바꿀 때 규칙도 함께 수정해야 합니다. 그룹을 계층적으로 구성할 수는 있지만 A가 B를 참조하고 B가 다시 A를 참조해서는 안 됩니다. 순환 참조가 생기면 출구를 올바르게 선택할 수 없습니다.

6. rules: 위에서부터 매칭하고 MATCH는 마지막에 배치하기

규칙 모드에서는 보통 목록 순서대로 연결을 검사하고, 처음 일치하는 규칙의 정책을 적용합니다. 더 구체적인 규칙이 자동으로 우선되는 방식은 아닙니다. 범위가 넓은 규칙을 앞에 두면 뒤에 있는 세부 규칙은 실행되지 않을 수 있습니다. 명확한 예외를 먼저 두고, 범위 규칙을 이어 배치한 다음, 마지막에 기본 처리 규칙을 두면 확인하기 쉽습니다.

rules:
  - DOMAIN,example.com,출구 선택
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,출구 선택

DOMAIN은 도메인 이름을 정확히 일치시킵니다. 예시는 example.com만 매칭하며 모든 하위 도메인을 자동으로 포함하지 않습니다.
DOMAIN-SUFFIX는 해당 도메인과 하위 도메인을 매칭합니다. 예시에는 example.org와 www.example.org가 포함됩니다.
IP-CIDR은 대상 IP 대역을 매칭합니다. 예시에는 자주 쓰이는 사설 IPv4 주소 대역 세 가지가 나열되어 있으며, 특수 용도 주소 전체 목록은 아닙니다.
no-resolve는 이 IP 규칙과 일치시키기 위해 도메인을 별도로 조회하지 말라는 뜻입니다. 연결 전체의 DNS를 끄는 설정은 아닙니다.
MATCH는 앞선 규칙에 일치하지 않은 연결을 처리하는 기본 규칙이므로 목록 맨 마지막에 배치해야 합니다.

GEOIP, RULE-SET, 규칙 provider

GEOIP,CN,DIRECT는 IP 지리 데이터베이스를 기준으로 매칭하며 도메인 문자열로 지역을 판단하지 않습니다. 데이터베이스가 없거나 업데이트에 실패한 경우, 또는 해석 결과 IP의 지역이 달라진 경우 결과에 영향을 줄 수 있습니다. 데이터베이스 오류가 발생하면 문제 해결 가이드의 GEOIP 점검 항목을 참고하세요.

RULE-SET은 rule-providers에 정의된 규칙 모음을 참조합니다. 노드를 저장하는 proxy-providers와는 다른 기능입니다. 사용하기 전에 규칙 모음의 형식과 동작 유형, 현재 커널의 지원 여부를 확인하세요. 규칙 모음을 가져온 뒤에도 rules에 참조 항목을 추가해야 합니다. 리소스를 정의하는 것만으로 매칭에 사용되지는 않습니다.

7. 최소 설정을 만든 뒤 TUN과 구독 노드를 단계적으로 추가하기

앞에서 살펴본 기본 항목을 조합한 로컬 학습용 설정입니다. 프록시 서버는 포함하지 않으며 모든 출구가 최종적으로 직접 연결됩니다. YAML 구조와 포트 수신, 정책 참조를 확인하는 용도입니다. 클라이언트가 포트나 DNS를 자동으로 덮어쓸 수 있으므로 실행 설정과 로그를 기준으로 확인하세요.

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

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: redir-host
  nameserver:
    - 223.5.5.5
    - 119.29.29.29

proxies: []

proxy-groups:
  - name: 출구 선택
    type: select
    proxies:
      - DIRECT

rules:
  - DOMAIN,example.com,출구 선택
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,출구 선택

TUN을 바로 추가하지 않은 이유는 무엇인가요?

TUN은 트래픽이 들어오는 또 다른 경로이지 프록시 노드가 아니며, 규칙을 자동으로 올바르게 만드는 스위치도 아닙니다. mihomo에서 흔히 쓰는 설정 항목은 tun.enable, stack, auto-route, dns-hijack 등이지만 실제 동작은 운영체제, 서비스 권한, 네트워크 인터페이스와 라우팅 환경에도 영향을 받습니다. 플랫폼이 확인되지 않은 TUN 설정을 모든 기기에 그대로 복사해서는 안 됩니다.

먼저 ‘앱 프록시 → 7890 → 규칙 → 출구’ 경로가 정상인지 확인한 다음 클라이언트가 지원하는 방식으로 TUN을 켜세요. TUN을 켠 뒤 인터넷이 끊기면 proxies를 바로 다시 작성하기보다 라우팅, DNS 처리, 다른 VPN과의 충돌을 먼저 확인하세요. 기본 설정 방법은 입문 가이드의 TUN 모드 설명을 참고하세요.

8. 저장해도 적용되지 않을 때: 구문, 참조, 실행 상태 점검하기

현재 활성화된 설정을 편집했는지 확인하세요. 설정 목록에서 활성 항목과 업데이트 시간을 확인한 뒤 다시 불러오세요. 클라이언트에 같은 이름의 파일이 여러 개 저장되어 있을 수 있습니다.
구문 오류가 난 줄을 확인하세요. yaml: line 관련 메시지가 표시되면 해당 줄뿐 아니라 앞줄의 콜론, 따옴표, 목록 기호, 들여쓰기도 확인하세요. 특수문자가 포함된 비밀번호는 YAML 문자열 규칙에 맞게 따옴표로 묶어야 합니다.
최상위 키가 중복되지 않았는지 확인하세요. 파일 끝에 두 번째 dns:나 rules:를 추가하지 마세요. 중복 키는 파싱 오류가 나거나 파서에 따라 기존 값이 덮어써질 수 있습니다.
출구 참조를 확인하세요. 프록시나 정책이 없다는 메시지가 나오면 그룹 이름과 노드 이름, 대소문자를 한 글자씩 대조하세요. YAML 파싱에 성공했다고 참조 관계까지 올바른 것은 아닙니다.
수신 포트와 진입 경로를 확인하세요. address already in use가 표시되면 7890이나 DNS 수신 포트를 다른 프로세스가 사용 중인지 확인하세요. 시스템 프록시 주소를 바꾸는 것은 포트 충돌의 해결책이 아닙니다.
실제로 어떤 규칙이 적용됐는지 확인하세요. rule 모드로 실행 중인지 확인하고 새 연결에서 규칙 상세 정보를 살펴보세요. 앱이 시스템 프록시를 우회한다면 먼저 진입 경로를 설정하거나 필요에 따라 TUN을 사용하세요.

커널에 내장된 설정 검사 기능 사용하기

mihomo 명령줄을 직접 사용할 수 있다면 설정 파일이 있는 디렉터리에서 아래 명령을 실행하세요. 설정 검사에서 외부 리소스나 데이터베이스를 읽어야 할 수도 있으므로 실제 실행과 같은 작업 디렉터리와 리소스 환경을 사용해야 합니다.

mihomo -t -f config.yaml

검사를 통과했다는 것은 커널이 설정을 받아들였다는 뜻일 뿐, 노드 인증 정보가 유효하거나 모든 업스트림에 연결할 수 있고 웹사이트가 예상한 출구를 사용한다는 뜻은 아닙니다. 다음으로 연결 로그를 확인하세요. 문제를 해결할 때는 한 번에 한 부분만 바꾸고 변경 전후의 오류 메시지를 기록하는 편이 DNS, 규칙, TUN을 동시에 바꾸는 것보다 원인을 찾기 쉽습니다.

설정을 이해하려면 ‘진입 포트 → 도메인 해석 → 규칙 매칭 → 정책 그룹 → 최종 출구’ 순서로 각 단계를 확인하면 됩니다. 규칙 문제 해결 방법은 config.yaml 설정 점검을 참고하세요. 클라이언트를 바꿀 때는 새 클라이언트가 사용하는 커널과 지원하는 설정 항목을 먼저 확인한 뒤 설정을 옮기세요.