Clash config.yaml 구조와 설정 항목별 설명: 포트부터 rules까지

먼저 커널과 설정 출처 확인하기

config.yaml은 프록시 커널이 읽어 사용하는 설정 파일입니다. 커널은 연결을 만들고 트래픽을 분기하며, 클라이언트는 설정 가져오기, 전환, 로그 확인 기능을 제공합니다. 같은 클라이언트라도 설정을 불러오기 전에 포트를 병합하거나 규칙을 덮어쓸 수 있으므로, 편집한 파일이 실제 적용되는 설정의 전부라고 단정할 수 없습니다.

이 글은 mihomo, 즉 기존 Clash Meta 커널에서 흔히 사용하는 항목을 중심으로 설명합니다. 기존 Clash와 mihomo는 문법을 일부 공유하지만 모든 기능이 호환되는 것은 아닙니다. 특히 TUN, DNS, 최신 프록시 프로토콜은 차이가 있을 수 있습니다. 클라이언트의 ‘정보’ 또는 커널 정보 화면에서 커널 이름과 버전을 확인한 뒤 해당 문서와 대조하세요. 창에 Clash라고 표시된다는 이유만으로 호환성을 판단하지 마세요.

읽을 때는 세 가지 흐름을 따라가세요

• 유입: 포트와 TUN은 트래픽이 커널에 들어오는 방식을 결정합니다.
• 유출: proxies에서 연결을 정의하고, proxy-groups에서 연결을 선택 가능한 프록시 그룹으로 구성합니다.
• 분기: rules는 도메인, IP 등의 조건에 따라 연결을 프록시 그룹이나 내장 동작으로 보냅니다.

파일의 위아래 순서는 주로 읽기 편하도록 정한 것입니다. 최상위 rules가 프록시 그룹을 참조한다고 해서 그룹 바로 아래에 있어야 하는 것은 아닙니다. 중요한 것은 이름이 정확히 일치하는지, 필드 계층이 올바른지, 규칙 목록의 순서가 적절한지입니다.

구조를 확인할 수 있는 전체 config.yaml 예시

아래는 내용을 읽고 로컬에서 테스트할 수 있는 mihomo 설정 예시입니다. 원격 프록시 노드는 없으며, 허용되는 연결은 모두 직접 연결됩니다. 따라서 원격 프록시의 작동 여부를 확인하는 용도로는 사용할 수 없습니다. 연결할 수 없는 예시 서버를 섞지 않고 포트, DNS, 프록시 그룹, 규칙의 관계부터 확인할 수 있도록 구성했습니다.

# 로컬 프록시 진입점
mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1

# 작동 방식 및 로그
mode: rule
log-level: info
ipv6: false

# 로컬 DNS 서버
dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: redir-host
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

# 가상 네트워크 인터페이스 미사용
tun:
  enable: false

# 원격 프록시 노드 없음
proxies: []

# 프록시 그룹에서 내장 직접 연결 동작 참조
proxy-groups:
  - name: "출구 선택"
    type: select
    proxies:
      - DIRECT

# 위에서부터 순서대로 매칭, 마지막 규칙은 기본 처리
rules:
  - 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,출구 선택

example.com은 규칙 예시에 사용하는 예약된 도메인입니다. 두 DNS 서버는 실제 공용 DNS 서비스이지만 모든 네트워크에서 접속할 수 있는 것은 아닙니다. 불러오기 전에 로컬의 7890 및 1053 포트를 다른 프로그램이 사용 중인지도 확인하세요.

YAML은 필드보다 들여쓰기부터 확인하세요

YAML은 들여쓰기로 항목 간의 소속 관계를 나타냅니다. 예시는 모두 공백 두 칸을 사용하며 Tab은 사용하지 않습니다. dns:는 최상위에 쓰고 enable:을 한 단계 들여쓰면 DNS 설정에 속한다는 뜻입니다. 목록의 -는 항목 하나를 나타내고, []는 빈 목록을 뜻합니다.

• 콜론 뒤에는 보통 공백을 하나 둡니다. 예: mode: rule.
• 같은 수준의 필드는 들여쓰기를 동일하게 맞추세요. 최상위 rules:를 프록시 그룹 안으로 들여쓰면 안 됩니다.
• 문자열에 # 같은 특수 문자가 있으면 따옴표로 감싸야 뒷부분이 주석으로 처리되는 것을 막을 수 있습니다.
• 같은 계층에 dns나 rules를 중복 정의하지 마세요. 파서에 따라 중복 키를 거부하거나 그중 하나만 남길 수 있습니다.

포트와 모드: 애플리케이션이 올바른 진입점을 사용하도록 설정하기

mixed-port: 7890은 하나의 포트에서 HTTP 프록시와 SOCKS5 프록시 연결을 모두 받는다는 뜻입니다. 애플리케이션에 프록시를 수동 설정할 때 주소는 127.0.0.1, 포트는 7890으로 입력하고, 프로토콜은 애플리케이션에서 제공하는 옵션에 맞춰 선택하세요. 이 숫자는 설명을 위한 예시이며 모든 클라이언트의 기본값은 아닙니다.

mode: rule이 이 글에서 설명하는 규칙 모드입니다. 전역 모드는 일반적으로 모든 트래픽을 전역 정책으로 보내고, 직접 연결 모드는 프록시를 거치지 않고 연결합니다. 이 두 모드에서는 일반 규칙을 수정해도 기대한 결과가 나오지 않습니다. 클라이언트 화면에서 모드를 덮어쓸 수 있으므로 실제 적용 상태를 확인하세요.

log-level: info는 평소 상태를 살펴보기에 적합합니다. 문제를 찾을 때는 잠시 debug로 바꾼 뒤 재현하고 다시 원래 값으로 되돌리세요. 상세 로그에 접속 도메인 등의 정보가 포함될 수 있으므로 공유하기 전에 민감한 내용을 삭제해야 합니다.

DNS와 TUN: 도메인 이름 해석과 트래픽 가로채기 구분하기

DNS는 도메인 이름을 IP 주소로 조회하는 과정입니다. 이 예시는 커널의 DNS 서비스를 활성화하고 127.0.0.1:1053에서 요청을 받도록 합니다. 그렇다고 운영체제의 모든 DNS 요청이 자동으로 이 서비스에 전달되는 것은 아닙니다. 실제 요청 경로는 시스템 설정, 클라이언트 연동 방식, TUN의 트래픽 가로채기 여부에 따라 달라집니다.

nameserver와 DNS 해석 모드

nameserver는 DNS 조회에 사용할 상위 서버 목록입니다. 예시에 나온 IP 주소는 일반 DNS를 사용하며 암호화된 전송을 제공하지 않습니다. DoH, 즉 HTTPS를 통한 DNS 조회가 필요하다면 현재 커널이 지원하는 형식으로 서버 주소를 설정하고, 연결 경로와 초기 DNS 조회에 필요한 설정도 확인하세요.

enhanced-mode: redir-host는 DNS 조회 시 실제 주소를 반환합니다. 많이 쓰이는 또 다른 모드인 fake-ip는 애플리케이션에 매핑용 가상 주소를 반환하고, 커널이 이를 도메인 이름과 연결합니다. 두 모드는 속도 설정이 아닙니다. 모드를 바꾸면 이전 DNS 캐시와 기존 연결이 테스트 결과에 영향을 줄 수 있으므로, 필요하면 캐시를 지우고 관련 애플리케이션을 다시 시작하세요.

TUN은 별도의 프록시 노드가 아닙니다

TUN은 시스템 라우팅으로 전달된 트래픽을 받는 가상 네트워크 인터페이스입니다. 예시에는 tun.enable: false만 설정되어 있으므로 이 경로를 통한 트래픽 가로채기는 활성화되지 않습니다. 시스템 프록시를 켜는 것과 TUN을 켜는 것은 다릅니다. 시스템 프록시는 주로 시스템 프록시 설정을 따르는 애플리케이션에 적용되고, TUN은 라우팅과 권한이 올바르게 설정되어 있으면 더 많은 트래픽을 받을 수 있습니다.

• 먼저 애플리케이션에 127.0.0.1:7890을 수동으로 설정해 확인하고, 다음으로 시스템 프록시를 테스트한 뒤 마지막에 TUN을 검토하세요.
• TUN을 사용하려면 클라이언트와 운영체제 요구 사항에 따라 관리자 권한, 가상 인터페이스, 라우팅을 설정하세요.
• dns-hijack은 조건에 맞는 DNS 트래픽을 가로채는 기능이지만 모든 암호화 DNS에 적용되는 것은 아닙니다. 애플리케이션에 내장된 DoH는 별도의 경로로 연결될 수 있습니다.
• 예시에서 IPv6를 끈 것은 문제 해결 범위를 좁히기 위해서이며, 모든 네트워크에 영구적으로 적용할 설정은 아닙니다.

proxies와 프록시 그룹: 이름을 따라 출구 확인하기

proxies는 개별 프록시 연결 목록입니다. 실제 노드에는 보통 이름, 프로토콜 유형, 서버, 포트, 인증 정보가 포함되며 프로토콜마다 전용 필드가 다릅니다. 서버 주소와 비밀번호는 실제 서비스 설정에서 확인해야 합니다. 서로 다른 프로토콜의 필드를 조합해 임의로 노드를 만들면 안 됩니다.

이 예시의 proxies: []는 원격 노드가 없음을 명시합니다. 프록시 그룹에서 사용하는 DIRECT는 커널에 내장된 직접 연결 동작이므로 노드 목록에 따로 선언할 필요가 없습니다. 마찬가지로 REJECT는 연결을 거부하는 내장 동작입니다.

select는 항목을 선택할 뿐, 속도를 측정하지 않습니다

proxy-groups는 하나 이상의 연결을 그룹으로 구성합니다. 예시의 type: select는 직접 선택하는 방식이며, 그룹 이름은 “출구 선택”입니다. 실제 노드를 추가할 때는 해당 노드의 정확한 이름을 그룹의 proxies 목록에 넣어야 이 그룹에서 선택할 수 있습니다.

rules의 “출구 선택”
        ↓ 이름이 일치해야 함
proxy-groups에서 name이 “출구 선택”인 그룹
        ↓ 현재 선택된 항목
DIRECT, 즉 목적지에 직접 연결

url-test는 테스트 결과에 따라 출구를 선택하는 프록시 그룹 유형입니다. 적절한 테스트 주소와 간격을 설정해야 합니다. 측정된 지연 시간은 특정 대상까지의 관측값일 뿐 다운로드 속도를 나타내지 않으며, 모든 사이트에 접속할 수 있다는 보장도 없습니다.

구독 설정에는 proxy-providers가 있을 수 있습니다. 이는 파일이나 원격 출처에서 노드 목록을 불러오는 설정입니다. 프록시 그룹은 보통 제공자 이름을 use로 참조하며, 제공자 이름을 개별 노드처럼 proxies에 넣지 않습니다. 이런 설정을 발견하면 출처, 업데이트 경로, 상태 확인 설정도 살펴보세요.

rules: 첫 번째 규칙부터 MATCH까지 확인하기

규칙은 일반적으로 목록 순서대로 검사하며, 먼저 일치한 규칙이 연결의 경로를 결정합니다. 구체적인 조건을 앞에, 포괄적인 조건을 뒤에 두고 마지막에 기본 처리 규칙을 배치하세요. MATCH를 첫 번째에 두면 이후 일반 규칙은 새 연결을 처리할 수 없습니다.

도메인 규칙과 IP 규칙을 구분해서 읽기

DOMAIN은 정확한 도메인과 일치시키고, DOMAIN-SUFFIX는 해당 도메인과 하위 도메인을 모두 포함합니다. 규칙에는 도메인만 입력하고 전체 URL은 입력하지 마세요. 예를 들어 https://example.com/path에는 프로토콜과 경로가 포함되어 있어 도메인 조건으로 바로 사용할 수 없습니다.

IP-CIDR의 CIDR은 접두사 길이로 IP 주소 범위를 나타내는 표기법입니다. 끝에 붙는 no-resolve는 이 IP 규칙을 확인하기 위해 도메인 조회를 새로 시작하지 말라는 뜻입니다. 연결 정보에 대상 IP가 이미 있으면 해당 IP를 기준으로 계속 매칭할 수 있습니다. DNS 전체를 끄는 설정은 아닙니다.

예시에는 자주 사용하는 로컬 주소 대역 중 일부만 있으며, 특수 주소 정책 전체를 다루지는 않습니다. 프린터, 라우터 또는 기업 내부망에 접속할 수 없다면 실제 목적지 주소와 규칙 매칭 기록을 확인하세요. 모든 내부망이 192.168.0.0/16에만 속한다고 가정하지 마세요.

RULE-SET이 나오면 규칙 제공자까지 확인하기

RULE-SET은 rule-providers에 정의된 규칙 모음을 참조하며, 프록시 노드 목록을 참조하는 것은 아닙니다. 제공자 이름, 출처, 형식, behavior 유형을 함께 확인해야 합니다. 다운로드가 성공했다고 해서 현재 설정에 맞는 형식이라는 뜻은 아닙니다.

불러오기 전 점검과 적용 여부 확인

설정이 문법 검사를 통과했다고 해서 네트워크가 기대한 대로 작동하는 것은 아닙니다. ‘설정을 읽을 수 있는가, 포트에서 수신하는가, 규칙에 매칭되는가, 연결되는가’의 네 단계로 나눠 확인하세요. 한 번에 한 곳씩 변경해야 문제가 생겼을 때 이전에 작동하던 상태로 되돌리기 쉽습니다.

1. 파일을 확인합니다. 테스트용 복사본을 UTF-8 인코딩의 config.yaml로 저장하고, 확장자가 .yaml.txt로 바뀌지 않았는지 확인하세요. 들여쓰기, 중복 키, 프록시 그룹 이름도 점검합니다.
2. 커널 설정을 검증합니다. 클라이언트에서 제공하는 검사 기능을 사용하세요. mihomo 명령줄 프로그램이 설치된 환경에서는 아래 테스트 명령을 실행할 수도 있습니다. Windows에서는 현재 디렉터리의 프로그램을 보통 .\mihomo.exe로 지정해야 합니다.
3. 불러온 뒤 로그를 확인합니다. 문법 오류, 프록시 그룹을 찾을 수 없다는 메시지, 포트 사용 중 알림이 없는지 확인하세요. 클라이언트가 설정을 다시 작성한다면 실제로 생성된 설정 내용도 확인해야 합니다.
4. 진입점을 명시해 요청을 보냅니다. 시스템 프록시 스위치나 브라우저 설정으로 인한 간섭을 피하려면 프록시 포트를 직접 지정해 먼저 테스트하세요.
5. 연결 기록을 확인합니다. 테스트 연결에 적용된 규칙, 프록시 그룹, 최종 출구를 확인한 다음 기존 DNS나 TUN 설정을 단계적으로 활성화하세요.

# 설정을 검사합니다. 이 명령은 프록시 서비스를 계속 실행하지 않습니다
mihomo -t -f ./config.yaml

# 설정을 불러오고 커널이 실행된 뒤 로컬 HTTP 프록시 진입점을 테스트합니다
curl --proxy http://127.0.0.1:7890 --head https://example.com

두 번째 명령은 로컬 프록시 진입점에서 예시 사이트까지의 연결을 테스트합니다. 이 예시의 최종 경로는 DIRECT이므로 요청에 성공해도 원격 프록시 노드가 정상이라는 뜻은 아닙니다. Windows에서 터미널이 curl을 다른 명령으로 해석한다면 설치된 curl.exe를 명시해 사용하세요.

이후에도 같은 순서로 확인하면 됩니다. 진입점 설정, 작동 모드, DNS, 트래픽 가로채기, 노드, 프록시 그룹, 규칙 순입니다. 필드별 설명은 사이트의 YAML 매뉴얼에서, 설정 가져오기부터 활성화까지의 절차는 사용 안내에서 확인할 수 있습니다. 문제가 생길 때마다 처음부터 다시 작성하는 것보다 검증된 설정을 한 부 보관해 두는 편이 효율적입니다.