Clash config.yaml 설정 파일 해설: 포트, DNS, proxy-groups, rules

설정의 처리 흐름을 먼저 알아두세요. 앱이 요청을 로컬 포트로 보내면, 코어가 현재 모드에 따라 처리합니다. 규칙 모드에서는 rules가 적용할 정책을 정하고, proxy-groups가 실제 출구를 선택합니다. dns는 도메인 이름을 해석하고, TUN은 트래픽이 코어로 들어오는 방식을 바꿉니다. 서로 연관되어 있지만 같은 기능은 아닙니다.

이 글은 설정 파일에서 흔히 쓰이는 순서에 따라 각 항목을 설명합니다. 기본 항목은 Clash 설정 체계에 적용되지만, TUN, DNS 확장 기능이나 새 프로토콜은 실제 사용하는 코어를 기준으로 확인해야 합니다. Clash Meta는 이후 mihomo라는 이름을 사용하게 되었으며, 클라이언트와 코어의 명칭이 다를 수도 있습니다. 클라이언트 이름이 “Clash”라고 해서 모든 항목을 지원한다고 단정할 수는 없습니다.

1. 수정 전에 설정 파일과 적용 경로 확인하기

config.yaml이 현재 클라이언트에서 불러오는 전체 설정 파일이라고 단정할 수는 없습니다. GUI 클라이언트는 구독 원본, 사용자 설정, 오버라이드 조각, 최종 실행 설정을 각각 저장하기도 합니다. 실행 중 생성된 파일을 직접 수정하면 구독을 전환하거나 클라이언트를 재시작할 때 파일이 다시 생성될 수 있습니다.

클라이언트의 ‘설정’ 또는 ‘Profiles’ 페이지에서 현재 활성화된 항목을 확인하세요. 최근에 가져온 항목만 확인해서는 안 됩니다.
해당 항목의 ‘편집’ 또는 ‘파일 열기’ 기능을 사용하고, 수정 전에 내용을 별도 파일로 저장해 두세요. 버튼 이름은 클라이언트 버전에 따라 다를 수 있습니다.
클라이언트에 ‘오버라이드’, ‘병합’ 또는 Merge 기능이 있는지 확인하세요. 계속 유지할 로컬 규칙은 가능한 한 이 기능을 통해 추가하는 것이 좋습니다.
저장한 뒤 ‘설정 다시 불러오기’를 실행하거나 설정을 다시 활성화하고, 로그에 파싱 오류가 있는지 확인하세요.

먼저 YAML 문법 오류 확인하기

들여쓰기에는 공백을 사용하고 Tab은 쓰지 마세요. 이 글에서는 한 단계에 공백 두 칸을 사용합니다.
키와 값 사이에 공백을 넣으세요. 예를 들어 mode: rule처럼 작성하고 mode:rule처럼 쓰지 마세요.
목록 항목은 - 로 시작해야 합니다. 같은 단계의 노드, 정책 그룹, 규칙은 들여쓰기를 맞추세요.
불리언 값은 true 또는 false로 작성하세요. 특수 문자가 포함된 이름, 비밀번호, 주소는 따옴표로 묶는 것이 좋습니다.

yaml: line 12: mapping values are not allowed in this context 오류가 나타나면 12번째 줄과 바로 윗줄의 콜론, 따옴표, 들여쓰기를 먼저 확인하세요. 아직 네트워크 연결 단계에 도달하지 않은 것이므로 노드를 계속 바꿔도 대개 해결되지 않습니다.

2. 포트와 실행 모드: 요청은 어디로 들어오나

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

mixed-port는 HTTP 프록시와 SOCKS5 프록시 요청을 모두 받습니다. 위 예시에서는 앱의 프록시 서버를 127.0.0.1, 포트를 7890으로 설정할 수 있습니다. 이는 예시 값이므로 클라이언트에 다른 포트가 표시된다면 실제 실행 값을 사용하세요.

항목	용도	헷갈리기 쉬운 점
`port`	HTTP 프록시 수신 포트	DNS 포트나 원격 노드 포트가 아닙니다.
`socks-port`	SOCKS 프록시 수신 포트	앱에서 해당 프록시 프로토콜을 선택해야 합니다.
`mixed-port`	HTTP와 SOCKS가 하나의 포트를 함께 사용합니다.	다른 수신 항목과 같은 주소 및 포트를 중복 지정할 필요가 없습니다.
`external-controller`	컨트롤 인터페이스 수신 주소	클라이언트가 코어를 제어하는 데 사용합니다. 브라우저에 입력하는 프록시 주소가 아닙니다.

mode: rule은 규칙에 따라 트래픽을 분기하고, global은 전역 정책을 사용하며, direct는 직접 연결합니다. rules를 수정해도 변화가 없다면 클라이언트가 아직 ‘전역’ 또는 ‘직접 연결’ 모드인지 먼저 확인하세요.

allow-lan: false는 LAN 기기의 접속을 제한합니다. 같은 네트워크의 다른 기기에서도 사용하려면 수신 주소, 시스템 방화벽, 인증 설정을 함께 확인해야 합니다. 휴대폰에서 프록시를 사용하려고 컨트롤 인터페이스를 공용 네트워크에 직접 노출하지 마세요.

log-level: info는 일상적인 문제 해결을 시작하기에 적합한 수준입니다. debug를 임시로 사용했다면 바로 원래대로 되돌리세요. 로그에 방문한 도메인이 포함될 수 있습니다. 여기서 ipv6: false는 운영체제의 IPv6를 끄는 설정이 아니며 시스템 네트워크 설정을 대신하지 않습니다.

3. dns: 수신, 업스트림, fake-ip의 역할

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query

enable은 코어의 DNS 모듈을 켜고, listen은 DNS 서비스가 수신할 주소를 지정합니다. 127.0.0.1:1053으로 설정하면 로컬 DNS 수신 주소가 생긴다는 뜻일 뿐, 시스템의 모든 DNS 요청이 이 주소로 전송된다는 뜻은 아닙니다. 일반적인 시스템 DNS 설정에서는 1053 같은 사용자 지정 포트를 직접 지정할 수 없는 경우가 많습니다. 클라이언트의 DNS 가로채기나 전달 기능 또는 TUN 설정도 함께 구성해야 합니다.

default-nameserver는 일반적인 보조 서버 목록이 아닙니다

nameserver에 도메인 이름을 사용하는 암호화 DNS 주소가 있으면 코어가 먼저 DNS 서버의 도메인을 해석해야 합니다. default-nameserver는 주로 이 초기 해석을 담당하며, 일반적인 DNS 조회에 사용할 업스트림은 nameserver입니다. 모든 주소를 구분 없이 한 목록에 넣으면 문제 원인을 찾기 어려워집니다.

fake-ip는 매핑 주소를 반환합니다

fake-ip 모드는 도메인에 매핑 주소를 할당해 코어가 연결과 도메인을 연관 지을 수 있도록 합니다. 198.18.0.0/16 범위의 주소가 보여도 곧바로 DNS 오염으로 판단하지 마세요. 이 주소는 내부 매핑용이며 대상 사이트의 실제 공인 IP가 아닙니다.

LAN 서비스, 프린터 또는 특정 앱과 호환되지 않는 문제가 있다면 기존 dns 항목에 정확한 fake-ip-filter 항목을 추가할 수 있습니다. 먼저 문제가 생긴 도메인을 확인한 뒤, 사용하는 코어가 지원하는 일치 문법에 맞춰 추가하세요. 모든 도메인을 필터링하면 전체 DNS 동작이 달라지므로 피해야 합니다.

4. proxies와 proxy-providers: 노드는 어디서 가져오나

proxies는 설정 파일에 직접 작성하는 노드 목록입니다. 각 노드의 type에 따라 필요한 필드가 달라집니다. 흔히 name, server, port를 사용하지만 비밀번호, UUID, TLS, 전송 매개변수는 서버 설정과 일치해야 합니다. 다른 프로토콜의 필드를 그대로 가져다 쓰면 안 됩니다.

proxy-providers는 원격 주소나 로컬 파일에서 노드 목록을 가져오는 제공자를 정의합니다. 아무 구독 링크나 넣으면 반드시 작동하는 것은 아닙니다. 제공자 파일 형식, 구독 응답 내용, 코어의 지원 범위가 서로 맞아야 합니다. rules와 dns가 포함된 전체 설정 파일도 순수 노드 목록처럼 사용할 수 없습니다.

직접 정의한 노드는 proxy-groups의 proxies에서 이름으로 참조합니다.
제공자의 노드는 보통 정책 그룹의 use에서 제공자 이름으로 참조합니다.
이름은 공백, 대소문자, 기호까지 완전히 일치해야 합니다.
구독 주소, 비밀번호, UUID, 컨트롤 인터페이스 키를 공개 스크린샷이나 로그에 포함하지 마세요.

로그에 특정 프록시가 없다고 표시되면 참조 관계부터 확인한 다음 구독이 정상적으로 업데이트되었는지 살펴보세요. 노드를 삭제하거나 이름을 바꾼 뒤에도 기존 정책 그룹이 예전 이름을 참조하면 설정 검사에 실패할 수 있습니다.

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

proxy-groups:
  - name: 수동 선택
    type: select
    proxies:
      - DIRECT
  - name: 기본 출구
    type: select
    proxies:
      - 수동 선택
      - DIRECT

이 예시는 참조 구조만 보여 줍니다. DIRECT는 내장 직접 연결 정책이지 프록시 노드가 아닙니다. 따라서 예시를 그대로 복사해도 원격 프록시를 사용할 수 없습니다. 실제로 사용하려면 설정에 이미 존재하는 노드 이름이나 제공자 참조를 정책 그룹에 넣어야 합니다.

‘기본 출구’ 그룹은 규칙에서 참조할 수 있고, 그룹 안에서는 ‘수동 선택’을 다시 참조할 수 있습니다. 이런 계층 구조를 사용하면 트래픽 규칙과 실제 노드를 분리할 수 있습니다. 규칙은 안정적인 그룹 이름을 계속 가리키게 하고, 노드를 바꿀 때는 프록시 페이지에서 그룹 내 선택만 변경하면 되므로 규칙을 하나씩 수정할 필요가 없습니다.

유형	주요 동작	설정 시 유의 사항
`select`	후보 출구를 수동으로 선택합니다.	후보에는 노드뿐 아니라 다른 정책 그룹도 사용할 수 있습니다.
`url-test`	측정 결과에 따라 출구를 자동으로 선택합니다.	측정 URL, 간격, 전환 허용 오차를 적절하게 설정해야 합니다.
`fallback`	후보 순서에 따라 사용 가능한 출구를 선택합니다.	낮은 지연 시간을 고르는 기능이 아니라 우선순위와 장애 시 대체가 핵심입니다.
`load-balance`	지정한 정책에 따라 연결을 분배합니다.	여러 노드의 대역폭을 하나의 다운로드 연결에 합치는 기능이 아닙니다.

자동 그룹에 표시되는 측정 시간은 측정 대상에 대한 해당 시점의 연결 상태만 보여 줍니다. 모든 사이트의 접속 속도를 뜻하지는 않습니다. 측정 간격도 짧을수록 좋은 것은 아닙니다. 예를 들어 interval: 300은 300초를 뜻하므로 설정 전에 서비스 제공자의 제한과 실제 필요를 확인하세요.

그룹 간 순환 참조도 피해야 합니다. 예를 들어 A 그룹이 B 그룹을 포함하고, B 그룹이 다시 A 그룹을 포함하는 경우입니다. 그룹 계층이 완성된 것처럼 보여도 코어는 유효한 최종 출구를 결정할 수 없습니다.

6. rules: 위에서 아래로 검사하며 처음 일치한 규칙 적용

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
  - MATCH,기본 출구

위 예시는 문법을 설명하기 위해 예약된 예시 도메인을 사용한 것이며, 실제 사용을 권장하는 규칙은 아닙니다. DOMAIN은 특정 도메인 하나와 정확히 일치하고, DOMAIN-SUFFIX는 해당 도메인과 하위 도메인에 일치하며, IP-CIDR은 대상 IP가 속한 네트워크 범위에 일치합니다. 세 번째 필드에는 그룹 이름이나 DIRECT, REJECT 같은 내장 정책을 지정합니다.

MATCH는 마지막 대체 규칙으로 남겨 두세요

MATCH는 앞선 규칙에 일치하지 않은 요청을 처리합니다. 첫 줄에 두면 뒤에 있는 도메인 및 네트워크 범위 규칙은 실행되지 않습니다. 특정 도메인을 직접 연결하려면 파일 맨 아래에 기계적으로 추가하지 말고, 해당 도메인보다 먼저 일치하는 범위가 넓은 규칙 앞에 배치하세요.

no-resolve는 모든 DNS를 끄는 설정이 아닙니다

IP-CIDR 뒤의 no-resolve는 이 IP 규칙의 일치 여부를 판단하기 위해 도메인을 추가로 조회하지 말라는 뜻입니다. 대상 IP를 알고 있다면 IP 기준으로 계속 일치시킬 수 있습니다. DNS 모듈을 비활성화하거나 도메인 해석에 의존하는 앱의 연결 문제를 자동으로 해결하는 설정은 아닙니다.

GEOIP 또는 지역 정보 기반 규칙을 사용한다면 해당 데이터 파일을 사용할 수 있는지, 형식이 코어에서 지원되는지도 확인해야 합니다. 관련 오류는 문제 해결의 GeoIP 점검 안내를 참고하세요. 규칙 세트는 rule-providers의 유형과 콘텐츠 형식, RULE-SET 참조 이름도 함께 확인해야 합니다.

7. TUN과 클라이언트 오버라이드: 설정 파일이 맞아도 트래픽을 가로채는지 확인

TUN은 가상 네트워크 장치를 통한 진입점이지 별도의 프록시 노드 목록이 아닙니다. 다음은 mihomo에서 자주 사용하는 필드 조합입니다. 활성화하기 전에 클라이언트의 서비스 권한, 시스템 라우팅, 다른 VPN의 상태를 확인하세요.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

auto-route는 경로를 자동으로 설정하고 auto-detect-interface는 송신 인터페이스를 자동으로 선택합니다. 운영체제와 코어 버전에 따라 지원 세부 사항이 다릅니다. 가상 네트워크 어댑터를 만들 수 없다면 먼저 클라이언트의 서비스 모드나 권한 부여 절차를 확인하세요. 권한 오류를 해결하려고 DNS 주소를 무작위로 추가하거나 삭제하지 마세요.

dns-hijack 예시는 가로채기 경로로 들어오는 기존 53번 포트 DNS 트래픽을 대상으로 합니다. 모든 암호화 DNS를 가로챈다는 뜻은 아닙니다. 브라우저 내장 DoH, 다른 VPN의 라우팅, 앱 자체의 네트워크 구현에 따라 실제 트래픽 경로가 달라질 수 있습니다.

클라이언트가 mixed-port, mode, dns, tun을 파일 설정 대신 인터페이스 설정으로 덮어쓸 수도 있습니다. 저장한 값이 원래대로 돌아간다면 클라이언트의 ‘실행 설정’ 또는 이에 해당하는 기능을 확인하고, 최종 적용된 내용과 구독 원본을 비교하세요. 여러 파일을 계속 수정하면 어느 단계에서 설정을 덮어쓰는지 파악하기 어려워집니다.

8. 저장 후 검증 순서: 문법, 불러오기, 트래픽, 규칙

먼저 설정을 파싱할 수 있는지 확인하세요. mihomo 명령줄 코어를 사용하는 경우 아래 검사 명령을 실행할 수 있습니다. GUI 클라이언트에서는 우선 자체 설정 검사 기능을 사용하세요.
설정을 다시 불러왔는지 확인하세요. 로그에 이전 오류가 남아 있는지 살펴보고, 수신 포트와 현재 모드도 확인하세요. 파일을 저장하는 것만으로 설정이 자동으로 다시 불러와지지는 않을 수 있습니다.
요청 하나로 진입 경로를 확인하세요. TUN을 끈 상태에서는 로컬 HTTP 프록시를 직접 지정해 테스트할 수 있습니다. 이렇게 하면 시스템 프록시의 활성화 여부까지 한 번에 점검하는 상황을 피할 수 있습니다.
연결 세부 정보를 확인하세요. 대상 도메인, 일치한 규칙, 정책 그룹, 최종 노드를 확인합니다. 그룹 이름이 맞더라도 그룹에서 DIRECT를 선택했다면 직접 연결됩니다.
마지막으로 변경 사항이 유지되는지 테스트하세요. 클라이언트를 재시작한 뒤 구독을 한 번 더 업데이트하고 오버라이드가 유지되는지 확인하세요. 사라진다면 수동으로 다시 입력하지 말고 병합 방식을 수정하세요.

# 설정 파일이 있는 디렉터리에서 실행합니다. mihomo가 명령 검색 경로에 포함되어 있어야 합니다
mihomo -t -f config.yaml

# 로컬 7890 포트의 HTTP 프록시를 명시해 요청을 보냅니다
curl -I --proxy http://127.0.0.1:7890 https://example.com

명령줄 검사는 클라이언트와 같은 버전의 코어로 실행하고 상대 경로 의존성도 확인해야 합니다. 설정 검사를 통과했다는 것은 해당 코어가 설정을 받아들였다는 뜻일 뿐, 노드 접속, 구독 업데이트, 대상 사이트 접속까지 보장하지는 않습니다. 위 curl 요청도 해당 요청의 프록시 경로만 확인하며, 모든 앱의 트래픽이 전달된다는 뜻은 아닙니다.

bind: address already in use 오류가 나타나면 포트를 사용 중인 프로세스를 찾거나 수신 포트와 앱의 프록시 포트를 함께 변경하세요. 노드 연결 시간 초과라면 노드 주소, 네트워크 연결 상태, 서비스 상태를 확인하세요. 연결 시간 초과 문제 해결도 참고할 수 있습니다.

안전하게 수정하려면 한 번에 한 계층만 변경하세요. 포트와 모드부터 확인하고, DNS, 정책 그룹과 규칙 순으로 수정한 뒤 마지막으로 TUN을 통한 트래픽 처리를 검토합니다. 변경할 때마다 정상 작동하는 버전을 남겨 두면 문제가 생겼을 때 되돌릴 수 있습니다. 구독 활성화, 모드 전환, 로컬 포트를 다시 확인하려면 시작하기 안내를 따라 하나씩 점검하세요.