Clash 설정 파일 레퍼런스

1. YAML 구조 개요

Clash 설정 파일은 일반적으로 config.yaml을 진입점으로 사용합니다. 서로 독립된 스위치의 나열이 아니라 계층형 매핑 구조입니다. 최상위 필드는 수신 포트, 실행 모드와 네트워크 기능을 결정하고, proxies는 사용 가능한 프록시를 정의합니다. proxy-groups는 프록시를 수동 선택, 자동 테스트 또는 장애 조치가 가능한 정책으로 묶으며, rules는 각 요청을 특정 정책 그룹으로 연결합니다. 개별 필드를 외우는 것보다 이 참조 관계를 이해하는 것이 중요합니다. 존재하지 않는 정책 그룹을 가리키는 규칙이나 정의되지 않은 노드를 참조하는 정책 그룹은 설정 로드 실패 또는 예기치 않은 결과를 일으킬 수 있습니다.

들여쓰기, 시퀀스와 매핑

YAML은 공백으로 계층을 표현합니다. 두 칸 들여쓰기를 일관되게 사용하고 탭은 섞지 않는 것이 좋습니다. 콜론 왼쪽은 키, 오른쪽은 값이며, 하이픈으로 시작하는 항목은 시퀀스입니다. dns 뒤에 들여쓴 필드는 DNS 매핑에 속하고, rules 아래의 각 하이픈 행은 하나의 규칙입니다. 문자열은 보통 따옴표 없이 작성할 수 있지만 콜론, 해시, 쉼표가 포함되거나 불리언으로 해석될 수 있는 값에는 따옴표를 쓰는 편이 안전합니다. 주석은 해시로 시작하며 읽기 위한 내용일 뿐 실행에는 포함되지 않습니다.

# 최상위 매핑
mixed-port: 7890
mode: rule
log-level: info

# 중첩 매핑
dns:
  enable: true
  listen: 0.0.0.0:1053

# 객체 시퀀스
proxies:
  - name: "예시 노드"
    type: socks5
    server: 127.0.0.1
    port: 1080

# 문자열 시퀀스
rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,노드 선택

위 예시는 문법 관계를 보여 주기 위한 것이며, 반드시 로컬 SOCKS 노드를 사용해야 한다는 뜻은 아닙니다. 실제 구독에는 일반적으로 완성된 proxies 또는 proxy-providers가 포함됩니다. 수동으로 편집할 때는 정책 그룹이 노드 이름으로 참조하므로 노드 이름의 정확한 표기를 유지해야 합니다. 이름 안의 공백은 유효한 문자지만 앞뒤 공백은 눈으로 발견하기 어려운 차이를 만들 수 있습니다. 따라서 노드 이름과 정책 그룹 이름은 큰따옴표로 감싸고 끝에 공백을 남기지 않는 것이 좋습니다.

최소 구성과 로드 순서

규칙 모드에서 사용할 완전한 설정에는 최소한 수신 진입점, 사용 가능한 출구, 정책 그룹과 최종 대체 규칙이 필요합니다. 파서는 먼저 YAML을 읽고 필드 타입과 참조 관계를 확인한 다음 수신 포트, DNS 모듈과 프록시 그룹을 생성합니다. YAML 파싱에 성공했다고 실행 로직까지 올바른 것은 아닙니다. 예를 들어 mode: rule을 활성화했지만 규칙 끝에 MATCH가 없으면 매칭되지 않은 트래픽의 처리 방향이 불분명해질 수 있습니다. 노드만 정의하고 정책 그룹에 넣지 않은 경우에도 규칙에서 통일된 정책 이름으로 전환할 수 없습니다.

mixed-port: 7890
mode: rule
allow-lan: false

proxies:
  - name: "로컬 테스트"
    type: socks5
    server: 127.0.0.1
    port: 1080

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "로컬 테스트"
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - MATCH,노드 선택

구조를 확인할 때는 “규칙 대상 → 정책 그룹 → 노드 또는 다른 정책 그룹” 순서로 단계별로 추적하세요. 각 이름이 실제로 존재해야 하며 의미 없는 순환 참조도 없어야 합니다. 편집기가 YAML 문법 검사를 지원한다면 들여쓰기와 중복 키를 미리 발견할 수 있습니다. 클라이언트 로그는 지원되지 않는 필드, 포트 충돌, 프록시 제공자 다운로드 실패 같은 실행 중 문제를 확인하는 데 더 적합합니다. 구체적인 오류는 문제 해결의 설정 로드 항목도 참고하세요.

2. 포트, 모드와 일반 필드

일반 필드는 클라이언트가 시스템 트래픽을 수신하는 방식과 프록시 프로토콜 세부 사항에 들어가기 전의 기본 동작을 결정합니다. 그래픽 클라이언트는 대개 화면에서 이 값을 관리하므로 수동 수정 전에 오버라이드 기능을 사용하는지 확인하세요. 그렇지 않으면 시작할 때 화면 설정이 파일의 값을 덮어쓸 수 있습니다. 가장 흔한 진입점은 mixed-port입니다. 하나의 포트에서 HTTP와 SOCKS5 요청을 모두 받아 브라우저, 명령줄 도구와 시스템 프록시를 통합 설정하기 좋습니다.

규칙·전체·직접 연결 모드

rule 모드는 rules를 위에서 아래로 매칭하므로 장기 사용에 적합합니다. global 모드는 모든 트래픽을 전체 정책 그룹으로 보내 특정 출구를 임시로 테스트할 때 사용합니다. direct 모드는 트래픽을 직접 연결하여 문제가 프록시 경로에서 발생했는지 확인하는 데 유용합니다. 모드는 전체 동작을 제어하는 스위치일 뿐 기존 규칙을 삭제하지 않습니다. 규칙 모드로 돌아오면 규칙은 원래 순서대로 다시 적용됩니다. 세 모드의 사용 사례는 규칙·전체·직접 연결 프록시 모드 선택 가이드에서 계속 확인할 수 있습니다.

로컬 네트워크 수신과 제어 인터페이스

allow-lan을 활성화해도 다른 기기의 접속 가능 여부는 수신 주소, 방화벽과 네트워크 환경에 따라 달라집니다. 필드를 true로 바꾸는 것만으로 연결이 보장되지는 않습니다. 이 기기에서만 사용할 경우 비활성 상태를 유지하세요. 신뢰할 수 있는 동일 로컬 네트워크의 기기에 프록시를 제공해야 할 때는 수신 주소를 명시하고 시스템 방화벽을 확인합니다. 제어 인터페이스인 external-controller는 그래픽 화면이나 외부 패널에서 코어를 관리할 때 사용하며 프록시 포트와 역할이 다릅니다. 제어 포트를 시스템 프록시 포트로 입력해서는 안 됩니다.

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false

external-controller: 127.0.0.1:9090
secret: "your-controller-secret"

log-level의 일반적인 값에는 silent, error, warning, info, debug가 있습니다. 평소에는 info면 충분합니다. 연결 설정, DNS 조회 또는 규칙 매칭 문제를 확인할 때만 잠시 debug로 전환하고 완료 후 되돌려 로그가 빠르게 늘어나지 않도록 하세요. ipv6 활성화 여부는 로컬 네트워크, DNS 응답과 프록시 노드의 지원 여부를 기준으로 결정해야 합니다. 안정적인 IPv6 경로가 없는데 DNS가 IPv6 주소를 반환하면 앱이 연결할 수 없는 주소를 먼저 시도해 최초 연결이 느려질 수 있습니다.

그래픽 클라이언트의 “시스템 프록시”는 보통 운영체제의 프록시 주소를 Clash 수신 포트로 지정하는 기능입니다. 반면 “TUN 모드”는 가상 네트워크 장치를 통해 더 넓은 범위의 트래픽을 가로챕니다. 두 기능은 같은 필드가 아닙니다. 브라우저와 시스템 프록시를 지원하는 소프트웨어만 사용한다면 시스템 프록시로 충분한 경우가 많습니다. 게임, 명령줄 프로그램 또는 시스템 프록시를 읽지 않는 앱까지 분기하려면 TUN을 검토하세요. TUN 설정에는 권한, 라우팅과 DNS 하이재킹도 관련되므로 스위치 하나만으로 성공 여부를 판단할 수 없습니다.

3. DNS 설정과 해석 경로

DNS 설정은 도메인을 먼저 누가 해석하는지, 어떤 형태의 주소를 반환하는지, 규칙 엔진이 적절한 단계에서 도메인 정보를 얻을 수 있는지를 결정합니다. “웹페이지가 가끔 열리지 않는” 문제나 “규칙은 맞는 것 같은데 잘못된 정책으로 연결되는” 문제는 프록시 노드 장애가 아니라 DNS 요청이 클라이언트를 우회하거나 해석 결과가 캐시에 오염되었거나 fake-ip가 특정 로컬 네트워크 기기와 호환되지 않아서 발생할 수 있습니다. 문제를 확인할 때는 앱의 조회 요청, Clash의 조회 수신, 상위 해석기의 응답과 연결 설정을 네 단계로 나누어 관찰하세요.

기본 필드와 상위 서버

dns:
  enable: true
  listen: 0.0.0.0: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
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query

default-nameserver는 주로 DoH, DoT 같은 상위 서버 자체의 도메인을 해석하는 데 사용합니다. 따라서 “DNS 서버의 도메인을 해석하려면 먼저 그 DNS 서버에 접속해야 하는” 순환을 피하기 위해 직접 접근 가능한 IP 주소를 입력하는 경우가 많습니다. nameserver는 주요 해석 경로로 일반 UDP 주소나 지원되는 암호화 DNS 주소를 사용할 수 있습니다. fallback의 참여 여부와 결과 필터링 방식은 코어의 기능과 이후 필드에 따라 달라집니다. 상위 서버를 무작정 많이 추가하지 마세요. 출처가 많을수록 각 응답의 출처를 판단하기 어렵고 결과가 일치하지 않을 가능성도 커집니다.

fake-ip와 redir-host

fake-ip 모드에서는 실제 주소를 앱에 즉시 전달하지 않고 예약된 주소 범위에서 매핑 주소를 할당합니다. 앱이 이 주소로 연결하면 코어가 원래 도메인을 복원한 뒤 규칙을 매칭하고 실제로 해석합니다. 도메인 정보를 더 많이 유지할 수 있어 규칙 매칭이 안정적인 편입니다. 대신 실제 로컬 네트워크 주소, 로컬 네트워크 검색 또는 특수한 DNS 동작에 의존하는 소프트웨어는 필터 목록에 추가해야 할 수 있습니다. redir-host는 전통적인 해석 흐름에 가까워 호환 방식이 직관적이지만 일부 연결 단계에서는 IP 정보만 남을 수 있습니다.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "time.*.gov"
    - "+.stun.*.*"
    - "localhost.ptlogin2.qq.com"

필터 항목은 많을수록 좋은 것이 아닙니다. 실제 주소가 필요한 도메인 유형을 확인한 경우에만 추가하고 이유를 기록하세요. 로컬 네트워크 프린터, 화면 전송 또는 라우터 관리 도메인에 문제가 생기면 먼저 로그에서 조회 도메인을 확인한 뒤 정확한 접미사를 추가해 검증합니다. 긴 필터 목록을 한꺼번에 복사하면 실제 호환 지점을 가리고, 도메인 규칙으로 처리할 수 있었던 요청이 다른 해석 경로로 빠질 수 있습니다.

도메인별 해석기 지정

nameserver-policy를 지원하는 코어는 도메인 집합에 따라 상위 서버를 선택할 수 있습니다. 로컬 네트워크 도메인은 라우터로, 특정 지역 도메인은 해당 해석기로 보내거나 규칙 집합과 DNS 정책을 일치시키는 데 적합합니다. 키의 매칭 방식은 코어 버전과 기능에 따라 다르므로 설정을 옮길 때는 소수의 도메인으로 먼저 테스트하세요. 모든 기존 문법이 그대로 작동한다고 가정해서는 안 됩니다.

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
    "+.internal.example":
      - 192.168.1.1

DNS가 적용되는지 판단할 때 웹페이지가 최종적으로 열리는지만 확인해서는 안 됩니다. 클라이언트 로그에서 해당 도메인 조회가 발생했는지, 어떤 DNS 정책이 매칭됐는지, 연결 단계에서 도메인과 IP 중 무엇을 사용했는지, 시스템이 다른 네트워크 어댑터의 DNS로 직접 요청을 보내고 있지는 않은지 확인해야 합니다. TUN을 활성화했다면 DNS 하이재킹 설정과 시스템 권한도 점검하세요. 변경 후에는 운영체제와 브라우저 캐시를 비운 다음 새 도메인이나 시크릿 창에서 테스트해 이전 응답이 결론에 영향을 주지 않도록 합니다.

4. 프록시 노드 필드

proxies는 정적 노드 목록입니다. 각 시퀀스 항목에는 최소한 이름, 프로토콜 유형, 서버 주소, 포트와 해당 프로토콜에 필요한 인증 매개변수가 포함되어야 합니다. 구독 생성기는 보통 이 부분을 이미 완성하므로 수동 관리는 로컬 테스트, 고정 출구 또는 필드 구조를 이해할 때 적합합니다. 노드마다 프로토콜과 필드 구성이 다르므로 type만 바꿔 한 프로토콜의 노드를 다른 프로토콜로 변환할 수 없습니다. 서비스 제공자가 안내한 인증 정보, 전송 계층 설정과 TLS 매개변수는 하나의 묶음으로 확인해야 합니다.

공통 필드와 이름 참조

노드 이름은 화면에 표시하기 위한 값일 뿐 아니라 설정 내부의 기본 키이기도 합니다. 두 노드의 이름이 같으면 클라이언트가 로드를 거부하거나 정책 그룹의 참조 결과를 판단하기 어려워질 수 있습니다. 이름에 지역, 회선 용도와 프로토콜 힌트를 포함할 수 있지만 자주 바뀌는 데이터를 넣어서는 안 됩니다. 구독이 갱신될 때마다 정책 그룹의 고정 참조가 끊길 수 있기 때문입니다. 더 안정적인 방법은 프록시 제공자가 필터를 통해 정책 그룹에 동적으로 노드를 추가하도록 하는 것입니다.

SOCKS5와 HTTP 예시

proxies:
  - name: "로컬 SOCKS"
    type: socks5
    server: 127.0.0.1
    port: 1080
    username: "user"
    password: "your-password"
    udp: true

  - name: "사무실 HTTP 프록시"
    type: http
    server: proxy.example.com
    port: 8080
    username: "user"
    password: "your-password"
    tls: false

인증 필드는 서버의 실제 요구 사항에 맞춰 입력해야 합니다. 사용자 이름과 비밀번호가 필요 없는 서비스라면 빈 필드를 남겨 둘 필요가 없습니다. tls는 HTTP 프록시 서버까지의 연결에 TLS를 사용할지 여부를 뜻하며, 프록시를 통해 접속하는 대상 웹사이트가 HTTPS인지와는 다릅니다. 서버 주소가 도메인이라면 시작할 때 DNS에도 의존합니다. 따라서 모든 정책 그룹에서 같은 도메인 기반 노드를 사용할 수 없다면 노드를 하나씩 수정하기보다 노드 서버 도메인의 해석 경로를 확인하세요.

TLS, SNI와 전송 매개변수

TLS를 사용하는 프로토콜은 서버 이름 검증도 관련되는 경우가 많습니다. 설정의 servername 또는 유사한 필드는 핸드셰이크에 사용할 서버 이름을 지정하며 서버 인증서와 배포 설정에 맞아야 합니다. 인증서 검증을 건너뛰는 것은 보안 경계를 바꾸므로 연결 실패의 장기적인 해결책으로 사용해서는 안 됩니다. 시스템 시간, 도메인 해석, 서버 이름, 인증서 체인과 전송 매개변수를 순서대로 확인한 뒤 테스트 환경의 특수 인증서인지 판단하세요.

WebSocket, gRPC 등의 전송 방식에는 보통 경로, Host 또는 서비스 이름도 포함됩니다. 이는 서버 라우팅의 일부이므로 문자 하나만 빠져도 포트에는 연결되지만 핸드셰이크가 실패할 수 있습니다. 구독을 가져온 뒤 일부 노드만 작동하지 않는다면 원본 노드 정보와 전송 필드를 대조하세요. 모든 노드가 동시에 작동하지 않는다면 로컬 네트워크, 시스템 시간, DNS, 구독 만료 여부와 코어 로그를 우선 확인해야 합니다.

클라이언트 선택에 따라 사용할 수 있는 필드도 달라집니다. Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu 같은 그래픽 클라이언트는 서로 다른 코어 또는 오버라이드 화면을 사용할 수 있습니다. 유지 관리가 중단된 Clash for Windows와 ClashX Meta는 새로운 필드 지원 범위가 제한적일 수 있습니다. mihomo 환경에서 가져온 설정이라고 해서 구형 클라이언트가 모든 필드를 인식한다고 가정해서는 안 됩니다. 클라이언트를 바꾸려면 다운로드 페이지에서 플랫폼별 선택지를 확인하세요.

5. 정책 그룹과 선택 로직

정책 그룹은 규칙과 실제 노드 사이의 중간 계층입니다. 규칙은 특정 노드를 직접 가리키기보다 “노드 선택”, “스트리밍”, “다운로드 직접 연결”처럼 용도가 안정적인 정책 그룹을 가리키는 편이 좋습니다. 그러면 노드가 갱신되거나 구독 이름이 바뀌거나 출구를 임시로 전환할 때 전체 규칙을 다시 작성할 필요가 없습니다. 정책 그룹에는 노드뿐 아니라 다른 정책 그룹과 내장 대상 DIRECT, REJECT도 포함할 수 있습니다. 설계할 때 순환 참조를 피하고 가장 하위 단계가 실제 노드 또는 내장 대상에 도달하도록 해야 합니다.

select: 수동 선택

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "자동 선택"
      - "장애 조치"
      - "로컬 SOCKS"
      - DIRECT

select는 능동적으로 테스트하거나 전환하지 않고 사용자가 현재 선택한 항목을 유지합니다. 규칙의 통일된 진입점이나 지역을 직접 지정해야 하는 경우에 적합합니다. 자동 테스트 그룹을 수동 선택 그룹 안에 넣으면 자동 선택과 수동 제어를 함께 사용할 수 있습니다. 그래픽 클라이언트가 저장하는 선택 상태는 YAML과 별도로 관리될 수 있습니다. 다시 가져오거나 설정을 정리하거나 정책 그룹 이름을 바꾸면 첫 번째 항목으로 돌아갈 수 있으므로 첫 항목은 임시 문제 해결용이 아니라 합리적인 기본 정책이어야 합니다.

url-test: 테스트 결과에 따른 선택

  - name: "자동 선택"
    type: url-test
    proxies:
      - "로컬 SOCKS"
      - "예비 노드"
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50
    lazy: true

url-test는 지정한 주소로 주기적으로 테스트를 보내고 결과에 따라 사용 가능한 노드를 선택합니다. 테스트 결과는 노드에서 테스트 대상까지의 연결 상태를 보여 줄 뿐 모든 웹사이트의 실제 속도와 같지는 않습니다. interval이 너무 짧으면 불필요한 요청이 늘고, 너무 길면 회선 변화를 제때 반영하지 못합니다. tolerance는 작은 수치 변동으로 인한 잦은 전환을 줄일 수 있습니다. lazy를 활성화하면 사용하지 않는 정책 그룹의 능동 테스트를 줄일 수 있습니다. 테스트 주소는 안정적이고 응답 본문이 작으며 주요 사용 환경과 어느 정도 관련성이 있어야 합니다.

fallback과 load-balance

  - name: "장애 조치"
    type: fallback
    proxies:
      - "주 노드"
      - "예비 노드"
    url: "https://www.gstatic.com/generate_204"
    interval: 300

  - name: "연결 분산"
    type: load-balance
    strategy: consistent-hashing
    proxies:
      - "노드 A"
      - "노드 B"
    url: "https://www.gstatic.com/generate_204"
    interval: 300

fallback은 목록 우선순위에 따라 사용 가능한 첫 번째 노드를 선택하므로 명확한 주·예비 관계에 적합합니다. 단순히 수치가 가장 낮은 노드를 선택하는 방식은 아닙니다. load-balance는 여러 연결을 여러 노드에 분산하므로 여러 출구를 허용할 수 있는 작업에 적합하지만, 계정 로그인, 세션 고정 또는 접속 주소에 민감한 웹사이트에는 출구가 자주 바뀌어 적합하지 않을 수 있습니다. consistent-hashing은 같은 대상이 비교적 안정적인 노드에 매핑되도록 하는 방식이지만 단일 연결의 대역폭을 합산하는 기능으로 이해해서는 안 됩니다.

정책 그룹의 계층 설계

유지 관리하기 쉬운 구조는 보통 세 계층으로 나눕니다. 하위 계층은 정적 노드 또는 프록시 제공자가 출구를 제공하고, 중간 계층은 지역·용도·테스트 방식별로 구성하며, 최상위 계층은 규칙에서 안정적으로 참조할 진입점을 제공합니다. 예를 들어 “홍콩 노드”는 구독에서 이름을 필터링하고, “자동 선택”은 여러 지역 그룹을 참조하며, “노드 선택”은 자동 선택과 수동 지역 그룹을 함께 포함합니다. 실제 규칙은 “노드 선택”, “스트리밍” 같은 최상위 그룹만 가리킵니다. 구독이 바뀌어도 필터와 중간 계층만 관리하면 됩니다.

proxy-groups:
  - name: "홍콩 노드"
    type: select
    use:
      - provider-main
    filter: "(?i)홍콩|홍콩|HK"

  - name: "노드 선택"
    type: select
    proxies:
      - "홍콩 노드"
      - "자동 선택"
      - DIRECT

정규식 필터는 넓은 범위에서 시작해 점차 좁히며 검증해야 합니다. 노드 이름은 구독 제공자가 정하므로 이모지, 고정 공백 또는 복잡한 접두사·접미사에 지나치게 의존하면 안정성이 떨어집니다. 정책 그룹이 비어 있다면 먼저 프록시 제공자가 정상적으로 갱신되었는지 확인한 다음 필터 표현식을 점검하세요. 필터를 바로 삭제하고 모든 노드를 장기간 사용하는 것은 피해야 합니다. 테스트용, 만료 안내 또는 특수 용도의 항목이 운영 정책에 섞일 수 있습니다.

6. 규칙 문법, 순서와 최종 대체

rules는 위에서 아래 순서로 매칭하며 일반적으로 첫 번째로 일치한 규칙에서 검사를 멈춥니다. 따라서 규칙은 유형과 매개변수뿐 아니라 위치도 올바르게 작성해야 합니다. 정확한 도메인은 넓은 접미사 규칙보다 앞에 두고, 특정 직접 연결 또는 거부 항목은 더 넓은 범위를 포괄하는 집합보다 앞에 배치한 뒤 마지막에 MATCH로 대체 처리합니다. 규칙 대상은 존재하는 정책 그룹, 노드 또는 내장 대상이어야 합니다.

도메인 규칙의 범위 차이

DOMAIN은 지정한 전체 도메인만 매칭하므로 API 도메인이나 예외 처리가 필요한 단일 호스트에 적합합니다. DOMAIN-SUFFIX는 루트 도메인과 하위 도메인을 모두 포함해 웹사이트 분기에 자주 사용됩니다. DOMAIN-KEYWORD는 범위가 더 넓어 키워드가 짧으면 관련 없는 도메인까지 매칭될 수 있으므로 배치에 주의해야 합니다. api.example.com은 직접 연결하고 나머지 example.com은 프록시로 보내려면 정확한 규칙을 접미사 규칙보다 앞에 작성해야 합니다.

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,노드 선택
  - DOMAIN-KEYWORD,stream,스트리밍
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

IP 규칙과 no-resolve

IP 규칙은 연결 대상 주소를 매칭하는 데 사용됩니다. 일부 코어는 IP 유형 규칙을 처리할 때 도메인에 대응하는 최종 주소를 확인하기 위해 해석을 수행할 수 있습니다. no-resolve를 추가하면 해당 규칙이 도메인을 능동적으로 해석하지 않도록 할 수 있어 로컬 네트워크 대역처럼 이미 존재하는 IP만 처리하면 되는 규칙에 적합합니다. 모든 규칙의 속도를 높이는 범용 매개변수도 아니며 이 매개변수를 지원하지 않는 규칙 유형 뒤에 추가해서도 안 됩니다. 사용 전 현재 코어의 규칙 해석 동작을 확인하세요.

GEOIP는 로컬 지리 데이터베이스에 의존하며 도메인 자체의 속성이 아니라 대상 IP를 기준으로 매칭합니다. 데이터베이스의 존재와 갱신 상태, DNS가 반환하는 주소에 따라 결과가 달라집니다. 더 세밀한 도메인 분류가 필요하다면 GEOIP에만 의존하지 말고 규칙 집합이나 geosite 기능과 조합하세요. 중국 본토와 해외 트래픽 분기의 전체 작성법과 검증 과정은 Clash 중국 본토·해외 분기 규칙 설정 실전에서 확인할 수 있습니다.

PROCESS와 포트 규칙

데스크톱 환경의 일부 코어는 프로세스 이름, 프로세스 경로 또는 대상 포트로 매칭할 수 있습니다. 프로세스 규칙은 운영체제 권한과 코어의 프로세스 정보 수집 능력에 의존하므로 플랫폼이 달라지면 같은 동작이 보장되지 않습니다. 포트 규칙은 포트만 설명할 뿐 앱의 신원을 나타내지 않으며 여러 프로토콜이 같은 포트를 사용할 수 있습니다. 작성 전에 요구 사항이 “특정 앱을 지정 정책으로 보낼지” 또는 “특정 포트에 접속하는 모든 연결을 지정 정책으로 보낼지”를 먼저 구분해야 합니다.

rules:
  - PROCESS-NAME,curl,DIRECT
  - DST-PORT,22,노드 선택
  - DOMAIN-SUFFIX,example.net,노드 선택
  - MATCH,노드 선택

규칙은 가급적 “예외, 로컬 네트워크, 서비스 분류, 지역 분류, 최종 대체”로 나누고 각 구간 위에 짧은 주석을 작성하세요. 규칙을 조금씩 수정할 때마다 즉시 다시 로드하고 검증하는 편이 수천 줄을 한꺼번에 추가한 뒤 문제를 찾는 것보다 안정적입니다. 거부 규칙도 용도를 명확히 해야 합니다. REJECT는 매칭된 연결을 즉시 종료하므로 넓은 접미사를 잘못 작성하면 관련 로그인, 정적 리소스와 API가 함께 작동하지 않을 수 있습니다.

7. 프록시 제공자와 규칙 집합

프록시 제공자인 proxy-providers는 외부 파일이나 구독 주소에서 노드를 로드하고, 규칙 제공자인 rule-providers는 재사용 가능한 규칙을 로드합니다. 둘 다 “자주 바뀌는 내용을 주 설정에 대량으로 넣지 않는다”는 문제를 해결하지만 데이터 형식과 참조 위치가 다릅니다. 프록시 제공자는 정책 그룹에서 use로 가져오고, 규칙 제공자는 RULE-SET 규칙으로 참조합니다. 노드 구독을 규칙 제공자로 입력하거나 규칙 파일을 프록시 제공자로 입력하면 파싱에 실패합니다.

프록시 제공자 설정

proxy-providers:
  provider-main:
    type: http
    url: "https://subscription.example.com/clash.yaml"
    path: ./providers/provider-main.yaml
    interval: 3600
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 600

proxy-groups:
  - name: "구독 노드"
    type: select
    use:
      - provider-main
    filter: "(?i)홍콩|싱가포르|일본|HK|SG|JP"

type: http는 원격 주소에서 업데이트한다는 뜻이고, path는 다운로드 후 저장할 로컬 캐시 위치이며, interval은 업데이트 주기입니다. 업데이트에 성공했다고 모든 노드를 사용할 수 있는 것은 아니므로 상태 확인을 별도로 설정할 수 있습니다. 상태 확인 주소와 주기는 적절한 범위로 유지하세요. 구독 노드가 많을 때 지나치게 자주 확인하면 많은 연결이 동시에 생성됩니다. 구독에 특수 요청 헤더가 필요하다면 일부 코어에서 관련 필드를 설정할 수 있지만 구독 서비스의 요구 사항에 맞춰 입력하고 민감한 인증 정보는 공개 설정에 포함하지 마세요.

정책 그룹의 use는 하나 이상의 프록시 제공자를 참조하고 filter, exclude-filter 등의 기능으로 노드를 필터링할 수 있습니다. 필터 표현식은 보통 정규식입니다. 먼저 클라이언트에 표시되는 실제 노드 이름으로 좁은 범위를 검증한 뒤 키워드를 확장하세요. 한국어·영어 지역명, 약어와 대소문자는 조합 표현식으로 처리할 수 있습니다. 필터 결과가 비어 있으면 정책 그룹이 출구를 제공하지 못하며 로그에 해당 제공자나 정책 그룹 문제가 표시되는 경우가 많습니다.

규칙 제공자 설정

rule-providers:
  private:
    type: http
    behavior: domain
    format: yaml
    url: "https://rules.example.com/private.yaml"
    path: ./ruleset/private.yaml
    interval: 86400

  local-network:
    type: file
    behavior: ipcidr
    format: text
    path: ./ruleset/local-network.txt

rules:
  - RULE-SET,private,DIRECT
  - RULE-SET,local-network,DIRECT,no-resolve
  - MATCH,노드 선택

behavior는 집합 내 규칙의 동작 유형을 설명하며 도메인, IP 대역과 클래식 규칙 등이 일반적입니다. 원격 파일의 내용과 일치해야 합니다. format은 파일이 YAML, 텍스트 또는 코어가 지원하는 다른 형식인지 지정합니다. 확장자만 바꾼다고 내용 형식이 바뀌지는 않으므로 로드에 실패하면 파일을 열어 실제 구조를 확인해야 합니다. 원격 규칙 집합도 path에 캐시되므로 경로는 서로 다르게 지정해 두 제공자가 같은 파일에 쓰지 않도록 하세요.

도메인 동작을 정의하는 YAML 규칙 파일은 부하 목록 구조로 작성할 수 있습니다:

payload:
  - "example.com"
  - "+.example.org"
  - "full:api.example.net"

코어와 규칙 프로젝트에 따라 접두사의 의미가 다를 수 있으므로 서드파티 집합을 사용할 때는 해당 설명을 기준으로 해야 합니다. 규칙을 완전히 통제해야 한다면 중요한 항목만 소량 직접 관리하고 대규모 공개 분류는 보조로 사용하세요. 외부 집합이 많을수록 업데이트 경로가 복잡해집니다. 원격 주소를 사용할 수 없을 때 로컬 캐시의 존재 여부가 시작 결과에 영향을 줍니다. 중요한 설정은 부가 집합 하나의 일시적인 업데이트 실패에도 핵심 직접 연결, 프록시와 최종 대체 로직이 명확하게 유지되도록 구성해야 합니다.

업데이트와 영속성의 경계

주 설정, 프록시 제공자 캐시와 규칙 제공자 캐시는 별도로 관리해야 합니다. 클라이언트가 구독을 업데이트할 때 주 설정을 다시 쓸 수 있지만 로컬 오버라이드를 반드시 삭제하는 것은 아닙니다. 설정 디렉터리를 바꾸면 이전 캐시를 더 이상 읽지 않을 수도 있습니다. “구독은 분명 갱신됐는데 노드 목록이 바뀌지 않는” 문제를 확인할 때는 현재 활성 설정, 제공자 업데이트 시간, 실제 캐시 경로와 정책 그룹이 참조하는 provider 이름이 서로 일치하는지 확인하세요.

Linux 데스크톱 환경에서는 mihomo 코어를 직접 실행하는 경우가 많아 설정 디렉터리와 서비스 사용자 권한이 제공자 캐시 쓰기에 직접 영향을 줍니다. systemd로 배포할 때는 서비스 사용자가 설정 디렉터리를 읽을 수 있도록 하고 providers, ruleset 등의 캐시 디렉터리에는 필요한 쓰기 권한을 부여해야 합니다. 관련 배포 과정은 Linux 명령줄에서 Clash 코어 배포하기에서 확인할 수 있습니다.

8. 오버라이드, 병합, 검증과 복원

구독 설정은 업데이트 때마다 다시 생성되므로 구독 본문을 직접 수정하면 다음 업데이트에서 변경 내용이 사라지는 경우가 많습니다. 그래서 그래픽 클라이언트는 보통 오버라이드, 병합 또는 스크립트 처리 기능을 제공합니다. 구독은 노드와 기본 설정을 담당하고, 로컬 오버라이드는 포트, DNS, 정책 그룹 보완과 사용자 지정 규칙을 담당합니다. 클라이언트마다 “병합”의 정의는 완전히 같지 않습니다. 키를 덮어쓰는 경우도 있고 배열에 추가하는 경우도 있으며 지정 위치에 규칙을 삽입할 수 있는 경우도 있습니다. 클라이언트를 바꿀 때는 작은 설정으로 먼저 병합 결과를 검증하세요.

매핑 덮어쓰기와 배열 처리

mode, mixed-port 같은 스칼라 필드는 나중에 로드된 값이 앞선 값을 덮어쓰는 경우가 많습니다. dns 같은 매핑은 계층별로 병합될 수도 있고 전체가 교체될 수도 있습니다. rules, proxies, proxy-groups 같은 배열은 추가, 앞에 삽입, 교체에 따라 결과가 완전히 달라집니다. 특히 규칙 배열에서 사용자 지정 예외를 구독의 MATCH 뒤에 추가하면 절대 매칭될 수 없습니다.

# 로컬 오버라이드 예시, 구체적인 진입점은 클라이언트에 따름
mixed-port: 7890
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*.lan"
    - "*.local"

오버라이드를 작성하기 전에 목표가 “구독 필드 교체”인지 “구독 필드 보완”인지 명확히 하세요. 포트와 로그 수준은 보통 덮어쓰기에 적합하고, 사용자 지정 규칙은 규칙 배열 앞에 삽입해야 하는 경우가 많습니다. 로컬 정책 그룹은 추가하되 최종 설정에 해당 그룹이 참조하는 provider가 존재하는지 확인해야 합니다. 오버라이드 파일 자체만 보지 말고 클라이언트가 병합 후 코어에 전달하는 최종 설정을 확인하세요. “오버라이드 자체는 맞아 보이지만 최종 순서가 다른” 상황에서 많은 문제가 발생합니다.

규칙 앞 삽입과 정책 그룹 보완

회사 내부 도메인을 직접 연결해야 한다고 가정해 보겠습니다. 사용자 지정 규칙은 넓은 프록시 규칙과 MATCH보다 앞에 있어야 합니다. 클라이언트에 prepend, append 같은 별도 영역이 있다면 앞 삽입 영역에 배치하세요. 정책 그룹을 추가할 때는 구독에 이미 존재하는 그룹과 이름이 겹치지 않는지도 확인해야 합니다. 같은 이름의 객체를 어떻게 덮어쓰는지는 구현에 따라 다르며 원래 그룹의 전체 내용이 교체될 수도 있습니다. 의미가 분명하고 충돌 가능성이 낮은 이름을 사용한 뒤 병합 후 참조 관계를 확인하는 것이 안전합니다.

# 기대하는 최종 규칙 순서
rules:
  - DOMAIN-SUFFIX,corp.example,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - RULE-SET,applications,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

단계별 검증

복잡한 설정을 수정할 때 DNS, 정책 그룹과 전체 규칙을 동시에 바꾸지 마세요. 1단계에서는 YAML 로드 여부만 확인하고, 2단계에서는 수신 포트와 제어 인터페이스가 시작되는지 확인합니다. 3단계에서는 DNS 조회가 코어로 들어오는지 확인하고, 4단계에서는 정책 그룹에 실제로 사용 가능한 노드가 있는지 점검합니다. 5단계에서는 소수의 도메인으로 규칙 매칭을 확인한 뒤 마지막에 대규모 규칙 집합을 가져옵니다. 단계마다 변수 하나만 늘리면 오류 범위를 좁힐 수 있습니다.

1. 기준선 저장: 정상적으로 시작되고 연결되는 현재 설정을 보관하고 현재 활성 설정 이름을 기록합니다.
2. 문법 확인: 들여쓰기, 콜론, 따옴표와 배열 구조를 확인하고 편집기가 표시한 중복 키를 중점적으로 살펴봅니다.
3. 로그 확인: 먼저 명확한 첫 오류를 처리하세요. 이후 오류는 앞선 오류가 연쇄적으로 일으킨 결과일 수 있습니다.
4. 참조 확인: 규칙 대상, 정책 그룹 이름, 노드 이름, provider 이름과 로컬 경로를 하나씩 확인합니다.
5. 동작 검증: 웹페이지 속도만으로 판단하지 말고 로그에서 실제 매칭 규칙과 최종 정책을 확인합니다.

일반적인 오류 분기

“설정 파일 형식 오류”가 나타나면 먼저 들여쓰기, 탭, 닫히지 않은 따옴표와 콜론 뒤 공백을 확인하세요. “프록시 그룹을 찾을 수 없음”이 나타나면 이름의 대소문자, 전각·반각 기호와 끝 공백을 확인합니다. “provider 업데이트 실패”가 나타나면 주소 접근 가능 여부, 캐시 디렉터리 권한과 파일 형식을 점검하세요. “포트 수신 실패”가 나타나면 다른 클라이언트나 이전 코어 프로세스가 사용 중인지 확인합니다. “규칙이 계속 매칭되지 않음”이 나타나면 현재 모드, 규칙 순서, 연결 재사용 여부와 로그에서 도메인과 IP 중 무엇을 받았는지 확인하세요.

설정은 로드되지만 모든 노드에 연결할 수 없다면 일시적으로 DIRECT를 사용해 로컬 네트워크를 확인한 뒤 정적 노드 하나를 테스트하고 마지막에 정책 그룹을 복원하세요. 특정 유형의 웹사이트만 이상하다면 클라이언트를 재설치하기보다 규칙 로그와 DNS 조회부터 확인합니다. TUN을 활성화한 뒤에만 문제가 발생한다면 시스템 권한, 가상 네트워크 어댑터, 라우팅 테이블, 방화벽과 DNS 하이재킹을 추가로 점검해야 합니다. Android 백그라운드 실행은 VpnService 권한과 배터리 절전 정책의 영향도 받으므로 Android VpnService와 배터리 절전 예외 설정을 참고하세요.

최종 설정은 세 가지를 충족해야 합니다. 진입점이 명확해 모든 앱이 어느 포트에 연결할지 알 수 있어야 하고, 참조가 닫혀 모든 규칙이 정책 그룹을 따라 실제 출구를 찾아야 하며, 업데이트가 통제되어 구독 변경이 로컬 핵심 로직을 덮어쓰지 않아야 합니다. 이 세 가지를 충족한 뒤 지역 그룹, DNS 정책과 대규모 규칙 집합을 세분화하세요. 설정의 복잡성은 필드 수가 아니라 명확한 요구 사항을 위해 존재해야 합니다. 여전히 분류하기 어려운 문제는 문제 해결에서 확인하고, 가져오기와 연결의 기본 흐름을 다시 진행하려면 Clash 설정 튜토리얼로 돌아가 단계별로 점검하세요.