고급 설정 2026-05-08 예상 읽기 9분

Clash 설정 파일 YAML 구조 단계별 해설: 포트 설정부터 rules 규칙까지

완전한 Clash 설정은 공통 필드, DNS, proxies, proxy-groups, rules 등의 단락으로 구성됩니다. 본문은 위에서 아래로 순서를 따라 각 필드의 역할, 자주 쓰는 값, 실수하기 쉬운 들여쓰기 형식 문제를 설명합니다.

설정 파일의 기본 구조와 로드 방식

Clash 계열 클라이언트(원조 Clash, Clash Meta, 그 분기 커널인 mihomo 포함)가 읽는 핵심 설정은 YAML 형식의 텍스트이며 보통 config.yaml이라는 이름으로 저장됩니다. 구독 링크로 자동 다운로드되든, 로컬 파일을 수동으로 불러오든, 클라이언트는 결국 이 텍스트를 구조화된 데이터로 파싱한 뒤 그 안에 선언된 포트, 프록시 노드, 정책 그룹, 규칙을 순서대로 초기화합니다. 이 파일의 단락 구성을 이해하는 것이 "규칙이 적용되지 않는다", "노드 그룹이 비어 보인다" 같은 문제를 진단하는 전제 조건입니다.

설정 파일은 관례상 위에서 아래로 다섯 개의 큰 단락으로 나뉩니다: 공통 실행 파라미터, DNS 해석 설정, proxies 노드 목록, proxy-groups 정책 그룹, rules 규칙표. 단락 사이에 강제적인 순서 요구는 없으며 커널은 줄 번호가 아니라 필드명으로 매칭하지만, 대부분의 구독 생성 도구와 주류 템플릿이 이 순서를 따르므로 본문도 이 순서로 설명하여 실제 파일과 대조하며 확인하기 쉽게 했습니다.

YAML은 중괄호나 종료 태그 없이 들여쓰기로 계층 관계를 표현하는 형식입니다. 즉 같은 단락 안에서는 하위 필드의 들여쓰기 공백 수가 완전히 일치해야 하며 Tab 문자를 공백 대신 쓸 수 없습니다. 초보자가 설정을 수동으로 수정할 때 가장 자주 걸려드는 부분이며, 이는 뒤에서 별도 절로 다시 다룹니다.

공통 필드: 포트, 모드, 로그 레벨

파일 최상단에는 보통 어떤 중첩 구조에도 속하지 않는 독립적인 키-값 쌍이 모여 있으며, 흔히 아래와 같습니다:

port: 7890
socks-port: 7891
mixed-port: 7890
allow-lan: true
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
secret: ""

각 필드의 역할은 다음과 같습니다:

  • port / socks-port: 각각 HTTP 프록시 포트와 SOCKS5 프록시 포트를 선언하며, 시스템이나 앱에서 프록시를 수동 설정할 때 구체적인 숫자가 필요합니다.
  • mixed-port: 하나의 포트로 HTTP와 SOCKS5 프로토콜을 동시에 혼합 수신할 수 있으며, 이를 설정하면 위 두 항목은 생략할 수 있습니다. 대부분의 그래픽 클라이언트는 기본적으로 이 항목만 사용합니다.
  • allow-lan: 같은 로컬 네트워크의 다른 기기가 본 기기의 프록시 포트를 통해 접속하도록 허용할지 여부이며, 휴대폰이나 태블릿이 같은 컴퓨터의 프록시를 공유할 때 켜야 합니다.
  • mode: 전역 실행 모드로, 흔한 값은 rule(규칙표에 따라 분기), global(모든 트래픽이 같은 프록시로), direct(모든 트래픽이 프록시 없이 직접 연결)입니다. 일상적으로는 rule을 선택하고, 문제를 진단할 때만 임시로 다른 두 모드로 전환해 단일 변수 테스트를 합니다.
  • log-level: 로그의 상세 정도로 값은 silent, error, warning, info, debug입니다. 연결 실패를 진단할 때 임시로 debug로 올리면 더 완전한 핸드셰이크 과정을 볼 수 있습니다.
  • external-controller: 외부 관리 패널(내장 Dashboard 등)이 호출할 수 있는 API 주소와 포트로, 그래픽 클라이언트는 대부분 관리 화면을 이미 내장하고 있어 일반 사용자는 건드릴 필요가 없습니다.
  • secret: 위 API에 접근하는 인증 비밀번호로, 비워두면 비밀번호 없음을 뜻합니다. 본 기기에서만 사용한다면 비워도 되지만 로컬 네트워크에 개방한다면 설정을 권장합니다.

또한 TUN 모드 관련 필드도 이 단락에 있습니다:

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

TUN 모드는 Clash가 가상 네트워크 카드를 만들어 시스템 네트워크 계층에서 전역 트래픽을 넘겨받도록 하며, 더 이상 앱마다 HTTP/SOCKS 프록시를 하나씩 설정할 필요가 없어 프록시 설정을 지원하지 않는 앱이나 시스템 레벨 트래픽을 처리할 때 자주 쓰입니다. stack은 가상 네트워크 카드가 사용할 프로토콜 스택 구현을 결정하며, system은 시스템 자체 기능에 의존해 호환성이 좋고, gvisor는 사용자 공간 구현으로 일부 플랫폼에서 더 안정적인 성능을 냅니다. TUN 모드를 켜려면 보통 클라이언트를 관리자 또는 root 권한으로 실행해야 하며, 이는 프록시 포트 설정과는 별개의 트래픽 인계 메커니즘입니다.

DNS 단락 상세 설명

DNS 단락은 도메인 해석 요청을 어떻게 처리할지 결정하며 분기 정확도와 해석 속도에 직접 영향을 줍니다. 가장 쉽게 간과되면서도 가장 문제가 자주 생기는 부분입니다:

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - tls://dns.google
  fallback:
    - https://1.1.1.1/dns-query
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
  • default-nameserver: 아래 nameserver, fallback 필드에 적힌 DoH/DoT 서버 도메인 자체를 해석하는 데 쓰이며, 반드시 순수 IP 주소여야 하고 또 다른 도메인 해석을 거쳐서는 안 됩니다. 그러지 않으면 순환 종속이 발생합니다.
  • nameserver: 일반 도메인을 실제로 해석하는 서버 목록으로, 전통적인 UDP, DoH(https://), DoT(tls://) 등 여러 프로토콜 접두사를 지원합니다.
  • fallback: 규칙상 어떤 도메인이 프록시를 거쳐야 한다고 판단될 때 쓰이는 보조 해석 서버로, 보통 해외 또는 암호화된 해석 서비스를 적어 오염을 피합니다.
  • fake-ip-range: fake-ip 모드를 켜면 도메인에 임시로 부여되는 가상 IP 대역입니다. 클라이언트가 이 가상 IP를 받으면 커널이 연결을 맺을 때 실제 목적지로 복원하는데, 이는 도메인 단위로 매칭하는 규칙과 IP 계층 전달 사이를 잇는 다리 역할을 합니다.
  • fake-ip-filter: fake-ip를 쓰지 않고 실제 IP를 그대로 반환할 도메인을 선언합니다. 로컬 네트워크 기기 탐색, 라이브 방송 채팅 등 실제 IP에 의존하는 기능에서 흔히 필요하며, 빠뜨리면 해당 기능이 오작동합니다.

DNS 설정 오류의 전형적인 증상은 규칙표는 완전히 맞아 보이는데 특정 사이트가 계속 잘못된 출구로 나가거나, 연결은 되지만 자주 타임아웃되는 경우입니다. 이런 문제는 대개 규칙을 잘못 쓴 게 아니라 도메인 해석 단계에서 이미 예상과 다른 결과를 받은 것이므로, DNS 단락을 먼저 보고 rules 단락을 보는 순서로 진단하는 것을 권합니다.

proxies와 proxy-groups 단락: 노드와 정책 그룹의 관계

proxies는 목록이며, 각 항목이 프로토콜 종류, 서버 주소, 포트, 암호화 방식 등 연결 파라미터를 담은 구체적인 프록시 노드 하나를 기술합니다. 예:

proxies:
  - name: "HK-01"
    type: ss
    server: example-hk.example.com
    port: 8443
    cipher: aes-256-gcm
    password: "your-password"
  - name: "SG-02"
    type: vmess
    server: example-sg.example.com
    port: 443
    uuid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    alterId: 0
    cipher: auto

흔한 type 값으로는 ss(Shadowsocks), vmess, trojan, socks5, http 등이 있으며 프로토콜마다 요구하는 필드가 조금씩 다릅니다. 필수 필드가 빠지면 해당 노드는 클라이언트에서 사용 불가로 표시되거나 아예 로드에서 건너뜁니다. 이 부분이 구독 링크에서 온 것이라면 보통 수동으로 작성할 필요가 없이 구독 제공자가 생성하며, 노드를 직접 추가할 때만 필드명이 프로토콜과 맞는지 하나씩 대조해야 합니다.

proxy-groups 단락은 위에 나열된 노드들을 규칙에서 호출할 수 있는 "정책 그룹"으로 묶습니다. 규칙표가 참조하는 것은 개별 노드 이름이 아니라 정책 그룹 이름이므로, 출구를 바꿀 때는 정책 그룹 내부만 조정하면 되고 규칙표를 고칠 필요가 없습니다. 흔한 정책 그룹 유형:

type 값동작 설명대표적인 용도
select여러 노드/하위 정책 그룹 중 수동으로 전환, 자동 판단 없음일상적인 수동 선택
url-test지정한 URL로 주기적으로 속도를 측정해 지연이 가장 낮은 노드를 자동 선택자동 최적 선택
fallback목록 순서대로 가용성을 탐지, 첫 노드가 실패해야 다음 노드로 전환주/보조 장애 대응
load-balance해시 또는 라운드로빈 방식으로 여러 노드에 연결을 분산다중 노드 부하 분산
 
proxy-groups:
  - name: "자동 선택"
    type: url-test
    proxies:
      - HK-01
      - SG-02
    url: "http://www.gstatic.com/generate_204"
    interval: 300
  - name: "수동 선택"
    type: select
    proxies:
      - 자동 선택
      - HK-01
      - SG-02
      - DIRECT

정책 그룹은 서로 중첩 참조할 수 있습니다(위 예시에서 "수동 선택"이 "자동 선택"을 하나의 선택 항목으로 포함하듯). 다만 순환 참조는 있어서는 안 되며, 그럴 경우 커널이 설정을 로드할 때 바로 오류를 내고 시작을 거부합니다.

rules 규칙 단락: 작성 순서와 매칭 로직

rules 단락은 위에서 아래로 순서대로 매칭되는 목록입니다. 커널은 각 네트워크 요청을 순서대로 하나씩 규칙과 대조하며, 처음 매칭되는 규칙을 만나면 즉시 해당 정책을 실행하고 더 이상 아래로 대조하지 않습니다. 즉 규칙의 배열 순서 자체가 로직의 일부이며, 순서를 잘못 쓰면 뒤쪽의 더 정확한 규칙이 영원히 기회를 얻지 못합니다.

rules:
  - DOMAIN-SUFFIX,google.com,자동 선택
  - DOMAIN-KEYWORD,github,자동 선택
  - DOMAIN,ad.example.com,REJECT
  - GEOIP,CN,DIRECT
  - MATCH,수동 선택

흔한 매칭 타입으로는 DOMAIN(정확한 도메인), DOMAIN-SUFFIX(도메인 접미사, 하위 도메인까지 함께 매칭), DOMAIN-KEYWORD(도메인에 키워드가 포함되면 매칭), IP-CIDR(IP 대역으로 매칭), GEOIP(IP가 속한 국가/지역 데이터베이스로 매칭), MATCH(최종 기본 규칙, 마지막 줄에 두어 앞의 어떤 규칙에도 걸리지 않은 요청을 모두 처리)가 있습니다. MATCH 기본 줄이 빠지는 것은 설정 파일에서 흔한 실수로, 일부 요청이 대응 정책을 찾지 못하고 예측할 수 없는 기본 동작으로 흘러가게 만듭니다.

규칙 오른쪽에 적는 목표는 반드시 proxy-groups에 이미 정의된 정책 그룹 이름이거나, 내장된 DIRECT(직접 연결), REJECT(연결 거부, 광고 도메인 차단에 자주 쓰임)여야 합니다. 정책 그룹 이름은 대소문자를 구분하며, 규칙표에 선언되지 않은 빈 정책 그룹을 참조해서는 안 됩니다. 그럴 경우도 로드 단계에서 오류가 납니다.

주의 NOTICE 규칙 세트(rule-provider)가 참조하는 원격 규칙 파일도 본질적으로 위의 몇 가지 매칭 타입으로 한 줄씩 구성되어 있으며, 다만 별도로 저장되고 주기적으로 업데이트될 수 있다는 점이 다릅니다. RULE-SET 타입 규칙을 쓰기 전에는 rule-providers 단락에서 해당 규칙 세트의 출처 주소와 로컬 캐시 경로를 먼저 선언해야 하며, 그러지 않으면 규칙표를 로드할 때 존재하지 않는 규칙 세트를 참조해 실패합니다.

흔한 들여쓰기 오류와 진단 방법

YAML은 들여쓰기 요구가 대부분의 설정 형식보다 엄격합니다. 아래 몇 가지 문제가 설정 파일을 수동으로 편집할 때 가장 자주 발생합니다:

  1. 동일 레벨 필드의 들여쓰기 공백 수가 일치하지 않음

    같은 목록 아래의 여러 항목은 앞의 공백 수가 완전히 같아야 합니다. 단 한 칸만 차이가 나도 커널은 계층 오류로 판단해 오류가 난 그 줄만 건너뛰는 게 아니라 파일 전체 로드를 거부합니다.

  2. Tab과 공백을 섞어 씀

    대부분의 텍스트 에디터는 기본적으로 Tab으로 들여쓰기하지만 YAML 표준은 Tab 문자를 받아들이지 않습니다. "Tab을 공백으로 변환" 기능을 지원하는 에디터를 쓰고, 한 단계 들여쓰기를 공백 두 칸으로 통일하는 것을 권합니다.

  3. 콜론 뒤에 공백이 없음

    YAML의 키-값 쌍은 콜론 뒤에 공백 하나를 두고 값을 써야 합니다. 예를 들어 name:HK-01처럼 공백이 없으면 잘못된 키 이름으로 해석되므로 name: HK-01처럼 써야 합니다.

  4. 문자열에 인용부호를 붙이지 않아 타입이 잘못 판단됨

    비밀번호, UUID 등의 필드가 숫자로 시작하거나 특수 기호를 포함한다면 명시적으로 이중 인용부호를 붙이는 것을 권합니다. 그러지 않으면 문자열이 아니라 숫자나 불리언으로 해석되어 연결 인증에 실패할 수 있습니다.

이런 문제를 진단하는 가장 직접적인 방법은 수정한 설정 파일을 아무 온라인 YAML 문법 검사 도구에 넣어 들여쓰기 검사를 먼저 돌려보고, 문법상 문제가 없는지 확인한 뒤 클라이언트에 로드시키는 것입니다. 클라이언트 시작 로그(또는 log-level을 debug로 바꾼 뒤의 출력)도 대개 로드 실패의 구체적인 줄 번호를 명확히 알려주므로, 줄 번호로 위치를 찾는 것이 단락별로 눈으로 하나씩 확인하는 것보다 효율적입니다. 설정 파일을 수정하기 전에는 원본 파일을 백업해 두는 것을 권하며, 수정 후 클라이언트가 정상적으로 로드하지 못하면 바로 백업본으로 되돌려 진단에 시간을 오래 쓰다가 네트워크가 오래 끊기는 상황을 피할 수 있습니다.

클라이언트 다운로드