Clash config.yaml 설정 방법: proxies·proxy-groups·rules 작성 가이드

먼저 코어를 확인하고 설정의 참조 관계를 살펴보세요

설정은 세 단계로 구성됩니다. 노드가 연결 출구를 정의하고, 정책 그룹이 출구를 묶으며, 규칙이 연결을 어느 출구로 보낼지 결정합니다.proxies는 규칙 목록이 아니며, proxy-groups를 설정해도 모든 연결이 자동으로 프록시를 이용하는 것은 아닙니다. 클라이언트가 연결을 처리하고 해당 규칙과 일치해야 설정한 경로가 적용됩니다.

Clash는 설정 생태계를 통칭하는 말로 자주 쓰이지만, 코어마다 지원하는 항목이 다릅니다. 이 문서의 전체 예제는 mihomo, 즉 기존 Clash.Meta 코어를 기준으로 합니다. 인라인 규칙 모음 등의 문법은 모든 구형 Clash 코어에서 지원되는 것이 아닙니다. 먼저 클라이언트의 ‘정보’ 또는 코어 정보 페이지에서 코어 이름을 확인한 다음 해당 코어의 설정 문서를 참고하세요.

proxies: 개별 노드의 프로토콜, 서버, 포트, 인증 정보를 저장합니다.
proxy-groups: 노드 이름이나 다른 그룹 이름을 참조해 연결 출구를 선택 가능한 정책으로 구성합니다.
rule-providers: 파일, HTTP 또는 인라인 목록을 통해 재사용할 규칙 모음을 정의합니다.
rules: 연결을 순서대로 매칭하고 DIRECT, REJECT 또는 정책 그룹으로 보냅니다.

불러올 수 있는 config.yaml 구조 예제

아래는 mihomo 설정 전체 예제입니다. 원격 프록시 노드는 포함하지 않으며 기본 출구는 DIRECT입니다. 설정 로드, 정책 그룹 선택, 규칙 매칭을 확인하기 위한 예제로, 프록시 연결을 제공하는 설정은 아닙니다. 구조가 정상적으로 로드되는 것을 확인한 뒤 서비스 제공업체가 발급한 실제 노드를 추가하세요.

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

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

proxies: []

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - DIRECT
      - REJECT

rule-providers:
  local-demo:
    type: inline
    behavior: classical
    payload:
      - DOMAIN-SUFFIX,example.org

rules:
  - DOMAIN,example.com,DIRECT
  - RULE-SET,local-demo,DIRECT
  - 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,수동 선택

읽는 순서와 실제 적용 순서는 다릅니다

최상위 항목은 사람이 읽기 쉽도록 ‘공통 설정 → DNS → 노드 → 정책 그룹 → 규칙 모음 → 규칙’ 순으로 배치했습니다. 반드시 이 순서로 작성해야 하는 것은 아닙니다. 실제 결과에 직접 영향을 주는 것은 rules 목록의 순서와 정책 그룹의 초기 선택 항목입니다. 참조하는 이름은 공백, 대소문자, 한글을 포함해 완전히 일치해야 합니다.

YAML은 공백으로 들여쓰며 탭은 사용하지 않습니다. 이 문서에서는 각 단계에 공백 2개를 사용하고, 목록 항목은 하이픈 뒤에 공백을 둡니다. 특수 문자가 포함된 이름이나 비밀번호는 따옴표로 묶는 것이 좋습니다. 숫자로만 된 비밀번호도 문자열로 입력해야 파싱 후 자료형이 바뀌지 않습니다.

공통 설정: 포트, 작동 모드, 트래픽 처리 범위

항목	예제 값	설명
`mixed-port`	`7890`	하나의 수신 포트에서 HTTP와 SOCKS 프록시 연결을 모두 받습니다.
`allow-lan`	`false`	로컬 네트워크 기기에는 공개되지 않아 로컬 환경에서 설정을 익히기 좋습니다.
`mode`	`rule`	rules에 따라 트래픽을 분기합니다. 전역 모드에서는 규칙별로 출구를 지정하지 않습니다.
`log-level`	`info`	일반적인 작동 정보를 기록합니다. 문제를 확인할 때는 잠시 debug로 바꿀 수 있습니다.
`ipv6`	`false`	이 예제는 코어의 IPv6 지원을 끕니다. 시스템 전체의 IPv6를 끄는 것은 아닙니다.

mixed-port: 7890은 코어가 해당 포트에서 프록시 서비스를 제공하도록 준비한다는 뜻입니다. 시스템과 모든 앱이 이미 이 포트를 사용한다는 의미는 아닙니다. 앱에 따라 시스템 프록시 설정을 따르기도 하고 무시하기도 합니다. TUN은 가상 네트워크 인터페이스를 통해 더 많은 트래픽을 처리하지만, 사용 가능 여부는 시스템 권한, 라우팅, 클라이언트 구현에 따라 달라집니다.

이 문서에서는 TUN을 활성화하지 않습니다. 테스트할 앱의 HTTP 프록시를 127.0.0.1:7890으로 설정하면 프록시 입구를 확인할 수 있습니다. 포트를 다른 프로그램이 사용 중이면 로그에 보통 address already in use가 표시됩니다. 해당 프로그램을 종료하거나 설정과 앱의 프록시 포트를 함께 변경하세요. 예를 들어 둘 다 7891로 설정합니다.

dns: DNS 응답과 규칙 매칭은 어떻게 연동될까

dns 항목은 코어의 도메인 이름 해석을 관리합니다. 예제에서는 fake-ip를 활성화하고 198.18.0.1/16을 가상 주소 풀로 사용합니다. 이 주소는 도메인 매핑용이며 웹사이트의 실제 서버 주소가 아닙니다. 코어가 매핑 정보를 보관하므로 이후 연결에서 도메인을 복원해 도메인 규칙 매칭에 활용할 수 있습니다.

1053은 수신 포트이며 상위 DNS 주소가 아닙니다

listen: 127.0.0.1:1053은 로컬 DNS 서비스의 수신 주소입니다. nameserver에 지정된 두 IP가 상위 DNS 서버입니다. 이 예제는 구성을 쉽게 확인할 수 있도록 일반 DNS를 사용합니다. 상위 DNS를 선택할 때는 현재 네트워크에서의 접속 가능성과 개인정보 보호 요구사항도 고려하세요. 특정 공용 DNS가 모든 네트워크에 적합한 것은 아닙니다.

dns.enable을 켜는 것만으로 시스템의 모든 DNS 요청이 코어로 전달되지는 않습니다.
시스템 DNS 설정에는 보통 127.0.0.1:1053처럼 사용자 지정 포트가 포함된 주소를 직접 입력할 수 없습니다. 트래픽을 처리하려면 클라이언트 설정이나 로컬 포워딩이 필요합니다.
TUN의 DNS 하이재킹은 별도의 설정입니다. DNS를 적용하려고 다른 운영체제의 TUN 설정을 그대로 복사하지 마세요.
앱에 내장된 암호화 DNS가 도메인 해석 경로를 바꿀 수 있습니다. 도메인 규칙이 적용되지 않는다면 브라우저의 보안 DNS 설정과 실제 연결 기록도 함께 확인하세요.

이 예제에는 fake-ip-filter가 없습니다. 가상 주소를 사용하기 어려운 로컬 네트워크 서비스나 앱이 있다면 로그를 확인해 해당 도메인을 필터 목록에 추가한 뒤 연결을 새로 만들어 테스트하세요. 범위가 지나치게 넓은 와일드카드를 넣으면 많은 연결의 DNS 처리 방식이 달라질 수 있으니 주의하세요.

proxies: 노드 매개변수는 서버 설정과 일치해야 합니다

proxies: []는 노드 목록이 비어 있다는 뜻입니다. 노드를 추가하려면 이 항목을 목록으로 바꾸세요. 아래는 Shadowsocks 설정 항목의 예시일 뿐입니다. 192.0.2.10은 문서용 주소이고 비밀번호도 예시 문자열이므로 실제 접속에 사용할 수 없습니다. 실제 매개변수는 구독 정보나 서비스 제공업체의 관리 페이지에서 확인하세요. 서버 주소만 바꾸고 나머지 항목을 그대로 두면 안 됩니다.

proxies:
  - name: "SS-예시"
    type: ss
    server: 192.0.2.10
    port: 8388
    cipher: aes-128-gcm
    password: "demo-only-not-a-real-password"
    udp: true

name은 이후 정책 그룹에서 참조할 식별자입니다. server와 port는 원격 서버를 가리키며, cipher와 password는 서버 설정과 일치해야 합니다. 여기의 8388은 원격 포트로, 로컬 포트 7890과는 다른 값입니다.

udp: true는 해당 노드에서 관련 UDP 기능을 사용할 수 있도록 설정합니다. 전체 연결 경로에서 UDP가 지원된다는 보장은 없습니다. 서버, 프로토콜, 트래픽 처리 방식, 대상 네트워크가 모두 결과에 영향을 줄 수 있습니다. 프로토콜마다 설정 항목이 다르므로 VMess, VLESS, Trojan 매개변수를 type: ss에 넣어서는 안 됩니다.

노드 이름은 중복되지 않게 설정하세요

지역과 용도를 조합하는 등 쉽게 구분할 수 있는 짧은 이름을 사용하고, 이름이 서로 겹치지 않도록 하세요. 구독 업데이트 후 노드 이름이 바뀌면 수동으로 작성한 정책 그룹의 기존 이름이 더 이상 유효하지 않을 수 있습니다. 노드가 많다면 proxy-providers를 이용해 노드 출처를 관리할 수도 있습니다. 이 기능은 노드를 관리하므로 매칭 조건을 관리하는 rule-providers와 혼동하지 마세요.

proxy-groups: 노드를 규칙에서 사용할 정책으로 구성하기

실제 노드를 proxies에 추가한 뒤에는 정책 그룹에도 넣어야 합니다. 아래 그룹은 앞 절에서 정의한 노드 이름을 참조합니다. 유효한 노드 매개변수로 바꿔야 해당 항목을 선택해 정상적으로 연결할 수 있습니다.

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - "SS-예시"
      - DIRECT

select는 수동 선택 그룹입니다. 클라이언트의 ‘프록시’ 또는 정책 그룹 화면에 표시되는 경우가 많으며, 구성원 중 하나를 선택해 연결 출구를 지정할 수 있습니다. 처음 로드할 때 이전에 선택한 항목이 없으면 대개 목록의 첫 번째 항목이 사용됩니다. 선택 상태 저장 기능이 켜져 있으면 다시 로드한 뒤에도 첫 번째 항목이 아니라 이전 선택이 복원될 수 있습니다.

그룹 유형	선택 기준	사용 시 참고 사항
`select`	사용자가 직접 구성원 선택	먼저 노드를 테스트한 뒤 특정 출구를 고정해 사용할 때 적합합니다.
`url-test`	테스트 URL에 대한 측정 결과	측정된 지연 시간은 모든 웹사이트의 다운로드 속도와 같지 않습니다.
`fallback`	구성원 순서대로 사용 가능한 항목 선택	주·대기 전환에 적합하며, 항상 지연 시간이 가장 낮은 항목을 선택하는 방식은 아닙니다.
`load-balance`	설정된 정책에 따라 연결 분배	하나의 다운로드 연결에 여러 대역폭을 단순 합산하는 방식은 아닙니다.

정책 그룹은 다른 정책 그룹을 참조할 수도 있지만 순환 참조를 만들면 안 됩니다. 예를 들어 ‘일상 출구’가 ‘수동 선택’을 참조하는 것은 괜찮지만, 두 그룹이 서로를 참조하는 구성은 피하세요. proxy not found와 같은 오류가 발생하면 이름이 정확한지, 참조 대상이 실제로 존재하는지부터 확인하세요.

rule-providers와 rules: 규칙 모음 정의와 매칭 순서

전체 예제의 local-demo는 인라인 규칙 모음이며, behavior: classical은 규칙 유형을 포함한 형식을 사용한다는 뜻입니다. 여기에 포함된 DOMAIN-SUFFIX,example.org는 example.org뿐 아니라 하위 도메인에도 적용됩니다. 규칙 모음은 매칭 조건만 저장합니다. 실제 연결 출구는 rules의 RULE-SET,local-demo,DIRECT에서 지정합니다.

규칙 모음의 세 가지 동작 유형을 섞어 쓰지 마세요

classical: DOMAIN-SUFFIX,example.org처럼 규칙 유형을 포함한 항목을 사용합니다.
domain: 항목은 도메인 또는 지원되는 도메인 매칭 표현식입니다. classical 형식의 전체 행을 그대로 사용하면 안 됩니다.
ipcidr: 항목은 192.168.0.0/16과 같은 IP 대역입니다.

type: http로 바꾸는 경우 실제로 접속할 수 있는 url도 설정하고, 사용 형식에 맞춰 캐시 경로와 업데이트 간격 등의 항목을 지정해야 합니다. 예를 들어 interval: 86400은 86400초, 즉 24시간을 뜻합니다. 원격 콘텐츠는 선언한 동작 유형과 형식에 맞아야 합니다. 다운로드에 성공했다고 해서 콘텐츠를 반드시 파싱할 수 있는 것은 아닙니다.

rules는 위에서 아래로 확인하며 처음 일치한 규칙을 적용합니다

예제의 첫 번째 행은 example.com과 정확히 일치할 때 직접 연결합니다. 두 번째 행에서는 규칙 모음을 참조하고, 이어서 몇 개의 로컬 네트워크 대역을 처리한 뒤 MATCH,수동 선택으로 나머지를 처리합니다. MATCH는 앞에서 처리되지 않은 연결에 적용되므로 마지막에 둬야 합니다. 첫 행에 배치하면 이후 규칙은 매칭될 기회가 없습니다.

rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,수동 선택
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,수동 선택

DOMAIN은 도메인 전체 일치, DOMAIN-SUFFIX는 도메인 접미사 일치입니다. 두 유형을 혼용하지 마세요. IP 규칙 뒤의 no-resolve는 해당 규칙을 확인하기 위해 도메인을 별도로 조회하지 않는다는 뜻입니다. 연결에 대상 IP가 이미 포함되어 있다면 해당 IP로 규칙을 매칭할 수 있습니다. 이 옵션은 DNS 전체를 비활성화하지 않으며, 해당 네트워크 대역을 직접 연결로 강제하는 기능도 아닙니다.

또한 규칙에 GEOIP 또는 GEOSITE를 넣으면 관련 지리 데이터가 필요합니다. 이 문서의 최소 예제에는 두 유형의 규칙을 일부러 제외해 최초 로드 시 데이터 파일 누락이나 업데이트 실패가 발생하지 않도록 했습니다.

저장·검증·로드: 세 단계로 오류 찾기

1단계: 코어로 문법과 참조 확인

mihomo를 별도로 설치했다면 설정 파일이 있는 디렉터리에서 아래 명령을 실행할 수 있습니다. Windows PowerShell에서는 현재 디렉터리에 있는 프로그램을 보통 .\mihomo.exe로 실행합니다. 실제 실행 파일 이름은 사용하는 환경에 따라 다를 수 있습니다.

mihomo -t -f ./config.yaml

# Windows PowerShell
.\mihomo.exe -t -f .\config.yaml

검사를 통과했다는 것은 현재 코어에서 설정을 읽을 수 있다는 뜻일 뿐, 노드가 온라인 상태이거나 비밀번호가 맞거나 DNS에 연결된다는 의미는 아닙니다. 명령줄 검사에서는 통과했지만 클라이언트에서 실패한다면 두 환경의 코어와 설정 파일이 같은지, 클라이언트에 다른 설정이 추가로 적용되는지 확인하세요.

2단계: 로드한 뒤 실제 적용 값 확인

클라이언트의 ‘설정’ 페이지에서 로컬 YAML을 가져와 해당 설정을 선택하세요. 화면에 ‘편집’ 메뉴가 있다면 내용을 수정하고 저장한 뒤 다시 로드합니다.
‘프록시’ 페이지에서 ‘수동 선택’ 그룹을 찾아 구성원이 있는지 확인하세요. 실제 노드를 추가하기 전에는 DIRECT를 유지합니다.
작동 모드를 ‘규칙’으로 설정하고 실제 혼합 포트가 7890인지 확인하세요. 클라이언트마다 메뉴 이름이 조금씩 다를 수 있습니다.
프록시 입구를 명시적으로 거치는 요청으로 테스트한 뒤 ‘연결’과 ‘로그’ 페이지를 확인하세요. 브라우저에서 웹페이지가 열리는지만 확인해서는 안 됩니다.

curl -I --proxy http://127.0.0.1:7890 https://example.com

# Windows에서는 별칭 차이를 피하기 위해 curl.exe 사용
curl.exe -I --proxy http://127.0.0.1:7890 https://example.com

예제대로라면 이 요청은 DOMAIN,example.com,DIRECT와 일치해야 합니다. HTTP 응답을 받을 수 있는지는 로컬 네트워크 상태에도 달려 있습니다. 규칙이 제대로 적용되는지 확인하려면 연결 세부 정보에 표시된 규칙과 최종 출구를 먼저 살펴보세요. 이 명령으로 확인할 수 있는 것은 HTTP 프록시 입구이며 TUN이나 시스템 DNS 처리 여부는 확인할 수 없습니다.

3단계: 오류 유형에 따라 확인하고 한 번에 하나씩 수정

증상	먼저 확인할 항목	다음 조치
YAML 파싱 오류	들여쓰기, 탭, 콜론, 따옴표	오류가 표시된 행과 바로 위 행을 확인한 뒤 설정 검사를 다시 실행합니다.
노드 또는 정책을 찾을 수 없음	그룹 이름과 노드 이름이 정확히 일치하는지	정의된 곳에서 이름을 복사해 입력 오류를 방지합니다.
수신 포트 오류	7890 또는 1053을 다른 프로그램이 사용 중인지	충돌하는 프로그램을 종료하거나 양쪽 설정의 포트를 함께 변경합니다.
규칙이 적용되지 않음	규칙 모드인지, 연결이 코어를 통과하는지	앞쪽에 있는 규칙을 확인하고 기존 연결을 종료한 뒤 다시 테스트합니다.
규칙은 맞지만 연결 시간 초과	선택한 노드, 인증 정보, 대상 네트워크	노드 하나를 고정해 테스트하여 규칙 문제와 연결 경로 문제를 구분합니다.