Clash 설정 파일 구조 완전 해설: YAML 각 섹션 필드의 역할과 작성법

설정 파일 개요: YAML 문법 기초와 최상위 구조

Clash와 Clash Meta(mihomo 코어)의 설정 파일은 모두 하나의 YAML 텍스트로, 보통 config.yaml이라는 이름을 사용합니다. 구독 링크 뒤에 있는 것도 사실 같은 형식의 파일이며, 클라이언트가 다운로드한 뒤 로컬 디렉터리에 저장해 파싱·로드합니다. 전체 파일은 최상위 키로 구성되며, 자주 보이는 최상위 키로는 port, socks-port, mixed-port, allow-lan, mode, log-level, dns, proxies, proxy-groups, rules, 그리고 Meta 코어에서만 지원하는 tun이 있습니다. 이 키들은 같은 들여쓰기 단계에 있으며 서로를 포함하지 않고, 순서 자체는 이론상 파싱에 영향을 주지 않지만, 점검을 쉽게 하기 위해 대부분의 설정은 실행 관련 파라미터를 앞쪽에, 규칙을 맨 뒤에 두는 습관을 따릅니다.

YAML은 들여쓰기로 계층 관계를 표현하며 탭 키는 인식하지 않고 공백만 인식합니다. 같은 계층의 들여쓰기 공백 수는 완전히 동일해야 합니다. 문자열은 대부분 따옴표가 필요 없지만, 값에 콜론이나 샵 기호가 포함되거나 숫자로 시작하면서 문자열로 처리해야 하는 경우에는 영문 따옴표를 붙여야 합니다. 목록 항목은 하이픈과 공백으로 시작하고, 딕셔너리 항목은 콜론과 공백으로 키와 값을 구분합니다. 이 규칙들은 단순해 보이지만 이후 등장하는 거의 모든 오류의 근원이므로, 설정을 수정하기 전에 확실히 익혀 두는 것이 좋습니다.

기본 실행 섹션: 포트, 로컬 네트워크, 실행 모드

설정 파일 맨 위쪽에는 보통 클라이언트 자체의 동작을 제어하는 필드들이 모여 있으며, 리스닝 포트와 로컬 네트워크 기기 접속 허용 여부, 트래픽 처리 모드를 결정합니다.

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

• port: HTTP 프록시 리스닝 포트로, 시스템 프록시 설정에 입력하는 값이 바로 이것입니다.
• socks-port: SOCKS5 프록시 포트로, 일부 명령줄 도구나 게임 클라이언트는 이 프로토콜을 별도로 설정해야 합니다.
• mixed-port: 같은 포트로 HTTP와 SOCKS5 요청을 동시에 받는 포트로, 요즘 GUI 클라이언트는 대부분 이 포트 하나만 사용하며 port/socks-port는 둘 중 하나만 남겨도 됩니다.
• allow-lan: 같은 로컬 네트워크의 다른 기기가 본 기기의 프록시를 통해 인터넷에 접속하는 것을 허용할지 여부로, 기본값은 false이며 스마트폰이나 태블릿에 프록시를 공유할 때는 true로 바꿔야 합니다.
• mode: 핵심 동작 모드로, rule은 규칙에 따라 트래픽을 분산하는 가장 많이 쓰이는 방식이며, global은 전체 트래픽이 같은 노드를 사용하고, direct는 프록시를 전혀 사용하지 않는 방식으로 임시 디버깅에만 사용합니다.
• log-level: 로그 상세 수준으로, 문제를 파악할 때는 임시로 debug로 바꿀 수 있으며 평소에는 info나 warning을 유지해 로그 패널에 정보가 너무 많이 쌓이는 것을 피하는 것이 좋습니다.

DNS 섹션: 필드 의미와 자주 쓰는 값

dns 섹션은 도메인 해석 방식을 제어합니다. 제대로 설정하면 도메인 유출과 해석 지연을 줄일 수 있고, 잘못 설정하면 웹페이지가 열리지 않거나 잘못된 주소로 해석되는 문제가 생기기 쉽습니다. 자주 쓰는 예시는 다음과 같습니다.

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.example-provider.net/dns-query
    - tls://dot.example-provider.net:853
  fallback:
    - https://fallback-doh.example-provider.net/dns-query
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"

• enable: 내장 DNS 서버가 해석을 담당하도록 활성화할지 여부로, 끄면 시스템 자체의 DNS 설정으로 되돌아갑니다.
• default-nameserver: nameserver에 적힌 DoH/DoT 주소 자체의 도메인을 해석하는 데 쓰이며, 반드시 순수 IP만 입력해야 하고 다시 도메인을 입력하면 "서버의 도메인을 해석하기 위해 서버가 필요한" 순환 문제가 생깁니다.
• nameserver: 실제로 일상적인 도메인을 해석하는 데 쓰이는 서버 목록으로, 전통적인 UDP 주소를 지원하며 https://로 시작하는 DoH와 tls://로 시작하는 DoT도 지원합니다. 암호화된 해석은 통신사에 의한 하이재킹 가능성을 줄여줍니다.
• fallback: nameserver가 특정 도메인이 오염되었을 가능성이 있다고 판단할 때 대신 사용하는 대체 해석 목록으로, 보통 fallback-filter와 함께 사용합니다.
• enhanced-mode: 향상 모드로, fake-ip는 도메인에 가상의 내부망 주소를 할당한 뒤 출구에서 실제 도메인으로 복원하는 방식이며 호환성이 좋아 대부분 클라이언트의 기본값입니다. redir-host는 좀 더 오래된 호환 방식으로 지금은 잘 추천되지 않습니다.
• fake-ip-filter: fake-ip 처리에서 제외할 도메인 목록으로, 로컬 네트워크 기기명이나 회사 내부망 도메인 등을 이 목록에 추가하는 것을 권장합니다. 추가하지 않으면 내부망 서비스에 접속할 수 없는 문제가 생길 수 있습니다.

proxies 섹션: 노드 필드 작성법

proxies는 목록이며, 각 항목이 사용 가능한 프록시 노드 하나를 나타냅니다. 자주 쓰는 프로토콜로는 ss(Shadowsocks), vmess, trojan, 그리고 Meta 코어에서 추가로 지원하는 hysteria2가 있습니다. 필드는 프로토콜마다 조금씩 다르지만 모두 이름, 서버 주소, 포트라는 세 가지 기본 정보를 포함합니다.

proxies:
  - name: "예시-홍콩-01"
    type: ss
    server: node1.example-relay.net
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

  - name: "예시-일본-01"
    type: vmess
    server: node2.example-relay.net
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /path
      headers:
        Host: node2.example-relay.net

• name: 클라이언트 화면에 표시되는 노드 이름으로, 이후 proxy-groups에서 노드를 참조할 때 이 이름으로 매칭됩니다. 이름을 바꾼 뒤에는 그룹 내 참조가 여전히 맞는지 확인해야 합니다.
• type: 프로토콜 종류로, 이후 어떤 추가 필드가 필요한지를 결정합니다.
• server / port: 노드 서버 주소와 포트로, 구독 제공처가 제공하는 정보에서 그대로 가져옵니다.
• udp: 해당 노드에서 UDP 포워딩을 활성화할지 여부로, 게임 온라인 플레이와 일부 음성 통화는 UDP에 의존하므로 클라이언트가 지원한다면 켜두는 것을 권장합니다.
• tls / network / ws-opts: 전송 계층 및 TLS 관련 설정으로, WebSocket 경로나 위장 도메인 등을 다룹니다. 보통 구독 제공처가 제시한 값을 그대로 사용하면 되며, 직접 수정하기 전에 원본 파일을 백업해 두는 것이 좋습니다.

대부분의 사용자는 이 섹션 전체를 직접 작성할 필요가 없습니다. 구독 링크가 갱신되면 클라이언트가 이 부분을 자동으로 다시 생성하며, 수동 편집은 주로 로컬에서 자체 구축한 노드를 단독으로 디버깅하거나 특정 필드의 잘못된 값을 임시로 고칠 때 사용합니다.

proxy-groups 섹션: 그룹 유형과 작성법

proxy-groups는 노드가 어떻게 분류되어 표시되는지, 그리고 전환·속도 측정의 동작 방식을 결정합니다. 각 그룹은 최소한 name, type, proxies 세 가지 항목을 가져야 합니다.

proxy-groups:
  - name: "자동 선택"
    type: url-test
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50
    proxies:
      - "예시-홍콩-01"
      - "예시-일본-01"

  - name: "노드 선택"
    type: select
    proxies:
      - "자동 선택"
      - "예시-홍콩-01"
      - "예시-일본-01"
      - DIRECT

  - name: "장애 시 전환"
    type: fallback
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    proxies:
      - "예시-홍콩-01"
      - "예시-일본-01"

• select: 수동 선택형 그룹으로, 화면에는 드롭다운 목록으로 표시되며 사용자가 직접 전환하도록 가장 바깥쪽에 두기 적합합니다.
• url-test: 자동 속도 측정형 그룹으로, interval에 설정된 주기(초 단위)마다 url에 접속해 지연 시간을 측정하고 지연이 가장 낮으면서 tolerance 허용 범위보다 나은 노드를 자동으로 선택합니다.
• fallback: 장애 시 전환형 그룹으로, 목록 순서대로 시도하다가 현재 노드가 사용 불가능해지면 다음 노드로 자동 전환합니다. 속도보다 안정성을 중시하는 상황에 적합합니다.
• load-balance: 부하 분산형 그룹으로, 전략에 따라 요청을 여러 노드에 나눠 배분합니다. 여러 노드의 대역폭을 합치는 상황에 적합합니다.

그룹의 proxies 목록에는 구체적인 노드 이름을 넣을 수도 있고 다른 그룹의 이름을 넣을 수도 있으며, 내장 전략인 DIRECT(직결)나 REJECT(거부)를 넣을 수도 있습니다. 이것이 "노드 선택" 그룹 안에 "자동 선택" 그룹을 중첩시키는 흔한 작성법이기도 합니다.

rules 섹션: 규칙 문법과 매칭 순서

rules 섹션은 트래픽 분산이 실제로 적용되는 곳으로, 각 줄은 "규칙 유형, 매칭 대상, 목표 전략" 형식으로 고정되어 있으며 위에서 아래로 순서대로 매칭됩니다. 첫 번째로 일치하는 규칙에서 멈추고 그 뒤의 규칙은 더 이상 적용되지 않으므로 순서가 매우 중요합니다.

rules:
  - DOMAIN-SUFFIX,example-streaming.com,노드 선택
  - DOMAIN-KEYWORD,example-ads,REJECT
  - DOMAIN,api.example-tool.dev,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

• DOMAIN / DOMAIN-SUFFIX / DOMAIN-KEYWORD: 각각 정확히 일치, 도메인 접미사 일치, 도메인에 포함된 키워드 일치를 의미하며, 접미사 일치가 가장 많이 쓰입니다. 규칙 하나로 한 도메인의 모든 하위 도메인을 커버할 수 있습니다.
• IP-CIDR / IP-CIDR6: IP 구간으로 매칭하며, 로컬 네트워크 주소나 내부망 주소를 직접 통과시킬 때 자주 사용합니다. no-resolve는 도메인에 대한 추가 해석을 하지 않고 목적지 IP만으로 판단한다는 의미로, 불필요한 DNS 조회를 줄일 수 있습니다.
• GEOIP: 목적지 IP가 속한 국가나 지역으로 매칭하며, GEOIP,CN,DIRECT는 거의 모든 설정에서 남겨두는 규칙으로 중국 본토 주소는 직결시켜 프록시로 인한 불필요한 우회를 줄여줍니다.
• MATCH: 최종 처리 규칙으로 맨 마지막 줄에 두며, 앞의 모든 규칙에 매칭되지 않은 트래픽을 어떻게 처리할지를 나타냅니다. 이 줄을 빠뜨리면 매칭되지 않은 트래픽의 처리 방향이 불확실해집니다.

규칙에 등장하는 전략 이름은 proxy-groups의 name과 완전히 동일해야 합니다. 대소문자, 전각/반각 문자까지도 일치해야 하며, 이는 초보자가 가장 쉽게 놓치는 부분입니다. 그룹이 분명히 존재하는데도 규칙에서 전략이 존재하지 않는다는 오류가 나온다면, 대부분 이름을 한 글자 잘못 입력한 경우입니다.

자주 발생하는 들여쓰기·문법 오류 점검

설정 파일을 직접 수정했는데 오류가 난다면 90% 이상은 들여쓰기나 구두점 문제입니다. 다음 순서로 점검해 보세요.

1. 탭과 공백을 섞어 쓰지 않았는지 확인합니다. 텍스트 편집기로 탭을 공백 2개 또는 4개로 통일해서 바꾸고 전체 파일에서 일관되게 유지하는 것을 권장합니다.
2. 같은 계층의 목록 항목이 정렬되어 있는지 확인합니다. 예를 들어 proxies 아래 각 - name: 앞의 공백 수가 반드시 같아야 합니다.
3. 문자열에 따옴표가 필요한지 확인합니다. UUID나 비밀번호에 콜론이 포함되거나 숫자로 시작하는 문자열은 영문 큰따옴표로 통일해서 감싸는 것이 좋습니다. 그렇지 않으면 YAML이 문자열이 아닌 다른 타입으로 해석할 수 있습니다.
4. 규칙 줄의 쉼표가 전각(한자권) 쉼표로 잘못 입력되지 않았는지 확인합니다. 전각 쉼표는 YAML에서 구분자로 인식되지 않아 규칙 전체가 무효화되거나 오류가 발생합니다.
5. 어느 줄이 문제인지 바로 찾기 어렵다면, 설정을 구간별로 주석 처리한 뒤 하나씩 되돌리면서 오류 범위를 빠르게 좁힐 수 있습니다.

수정 후 검증하는 방법

설정을 저장한 뒤 대부분의 클라이언트는 화면에서 바로 "설정 다시 불러오기"를 지원하므로 프로그램 전체를 재시작할 필요가 없습니다. 불러오기에 실패하면 클라이언트는 보통 로그 패널이나 팝업으로 구체적으로 오류가 난 줄 번호를 알려주며, 위의 점검 순서를 따라가면 대부분 문제를 찾을 수 있습니다. 불러오기에 성공한 뒤에는 다음 항목으로 수정 사항이 실제로 적용되었는지 확인하는 것을 권장합니다.

• 프록시 화면에서 목표 그룹 아래의 노드 목록이 방금 편집한 내용과 일치하는지 확인합니다.
• 로그 화면으로 전환해 로그 레벨을 debug로 올린 뒤 테스트용 도메인에 접속해 예상한 규칙과 전략이 적용되는지 관찰합니다.
• 명령줄 도구로 잘 알려진 확인용 주소에 접속해 반환된 출구 정보가 예상 노드와 일치하는지 확인한 뒤, 로그 레벨을 다시 평소 사용하는 info로 되돌립니다.