고급 설정 예상 읽기 시간 9분

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

config.yaml을 위에서 아래로 각 단락의 역할을 정리: 포트·모드, dns, proxies, proxy-groups, rules. 자주 나오는 들여쓰기 오류와 필드 오타 함정도 짚어봅니다.

Clash와 Clash Meta(mihomo)의 핵심 설정 파일은 모두 하나의 YAML 문서이며, 보통 config.yaml이라는 이름을 씁니다. 이 파일은 여러 개의 최상위 단락으로 구성되며, 각 단락은 각자 한 가지 역할만 담당합니다—포트와 실행 모드, DNS 해석 방식, 노드 목록, 정책 그룹, 분기 규칙. 이 단락들의 순서와 필드 의미를 이해하는 것이 어떤 "만능 설정"을 외우는 것보다 훨씬 유용합니다. 구독에서 받은 원격 설정은 수동으로 대조하거나 로컬 설정과 병합해야 하는 경우가 많은데, 구조를 이해하지 못하면 들여쓰기 하나를 잘못 고쳐서 파일 전체가 무효화되기 쉽습니다. 이 글은 파일 위에서 아래 순서대로 각 단락을 분해하고, 각 부분마다 실제로 겪었던 함정을 정리합니다.

일반 설정 단락: 포트, 모드, LAN 허용

파일 맨 위쪽에는 보통 클라이언트 자체의 동작을 정의하는, 특정 노드와 무관한 키-값 쌍들이 나열됩니다. 흔히 보이는 필드는 다음과 같습니다:

port: 7890
socks-port: 7891
redir-port: 7892
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

port는 HTTP 프록시 포트, socks-port는 SOCKS5 프록시 포트로 서로 영향을 주지 않으며, 둘 다 켜도 되고 하나만 남겨도 됩니다. redir-port는 투명 프록시 시나리오에 쓰이며 일반 데스크톱 사용자는 거의 필요하지 않습니다. allow-lan은 같은 네트워크의 다른 기기가 이 기기의 IP를 통해 프록시를 사용할 수 있는지를 결정하는데, 휴대폰이나 라우터에 인터넷을 공유하려면 true로 바꿔야 하며 동시에 방화벽에서 해당 포트를 열어줘야 합니다.

mode는 세 가지 값을 가집니다: rule은 규칙 단락에 따라 분기, global은 모든 트래픽을 특정 노드로 강제 전송(노드 자체의 연결 가능 여부를 점검할 때 주로 사용), direct는 프록시를 전혀 쓰지 않고 전부 직결하는 방식입니다. 일상 사용에서는 rule을 유지하고, 노드 연결을 임시로 테스트할 때만 global로 바꾸며, 테스트가 끝나면 반드시 되돌려야 합니다. 그렇지 않으면 "규칙을 분명히 설정했는데 전부 프록시로 나간다"는 오해가 생깁니다. external-controller를 켜면 클라이언트가 로컬 API 포트를 노출하여 대시보드 패널이나 서드파티 도구가 실행 상태를 읽을 수 있게 되는데, 이 기능이 필요 없다면 비워두거나 해당 행을 삭제해도 됩니다.

dns 단락: 해석 방식이 분기 정확도를 결정한다

dns 단락은 도메인 해석 동작을 제어하며, 잘못 작성하면 규칙 분기의 정확도에 직접 영향을 줍니다. 특히 TUN 모드를 활성화한 경우 더 그렇습니다. 흔히 볼 수 있는 예시입니다:

dns:
  enable: true
  ipv6: false
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.pub/dns-query
    - tls://dns.rubyfish.cn:853
  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에 적힌 DoH/DoT 주소 자체의 도메인을 해석하는 데 쓰이는 서버로, 반드시 순수 IP만 입력해야 하며 다시 도메인 주소를 넣으면 안 됩니다. 그렇지 않으면 "해석 서버의 도메인을 또 해석해야 하는" 순환 종속이 발생해 시작 시 오류가 납니다. nameserver는 실제로 외부에 해석 서비스를 제공하는 서버 목록이고, fallback은 nameserver의 결과가 오염됐을 가능성이 있을 때 활성화되는 백업 목록으로, 보통 fallback-filter와 함께 지리적 위치나 반환된 IP 대역으로 판단합니다.

fake-ip-range는 TUN 모드와 함께 쓰이며, 클라이언트가 도메인에 가짜 IP 대역 내의 주소를 할당하고, 트래픽 레벨에서 실제 도메인을 복원해 규칙에 매칭시킵니다. 이렇게 하면 전역 프록시 모드에서도 도메인 기반 분기 규칙이 여전히 유효하게 작동합니다. fake-ip-filter에 나열된 도메인(내부망 도메인, LAN 기기 이름 등)은 가짜 IP를 할당받지 않고 실제 DNS 해석을 거치는데, 이 항목을 잘못 쓰면 LAN 기기(NAS, 프린터, 라우터 관리 페이지)에 갑자기 접속이 안 되는 결과로 나타나는 경우가 흔합니다.

주의: TUN 모드를 쓸 계획이 없거나 fake-ip의 영향 범위가 확실하지 않다면 dns 단락 전체를 기본값으로 두거나 구독 제공자가 준 설정을 그대로 사용하고, 필드를 함부로 줄이지 않는 것이 좋습니다. DNS 설정 오류는 "일부 사이트는 열리는데 일부는 안 열린다"는 식으로 나타나는 경우가 많아 원인 파악에 시간이 걸립니다.

proxies 단락: 노드 목록 필드 규칙

proxies는 배열이며 각 항목이 하나의 노드를 설명하고, 프로토콜 종류에 따라 필드가 다릅니다. 가장 흔한 ss(Shadowsocks)와 vmess를 예로 들면:

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example-node.invalid
    port: 8443
    cipher: aes-256-gcm
    password: "your-password-here"

  - name: "SG-02"
    type: vmess
    server: sg02.example-node.invalid
    port: 443
    uuid: 00000000-0000-0000-0000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ws

자주 실수하는 몇 가지 지점입니다: name은 사람이 보는 식별자이며, proxy-groups가 노드를 참조할 때 이 이름으로 정확히 매칭합니다. 이름을 바꾼 뒤 proxy-groups 안의 참조를 함께 고치지 않으면 그 노드가 정책 그룹에서 "사라진" 것처럼 됩니다. type은 이 항목의 이후 필드를 어떻게 해석할지 결정하는데, 오타(예: vmess를 vmes로 씀)가 나면 해당 노드 전체가 무시됩니다. 대부분 클라이언트는 오류를 내지 않고 그냥 노드 목록에서 하나가 빠진 상태가 되어 원인 파악이 쉽게 간과됩니다. password, uuid는 영문 인용부호로 감싸는 것이 좋습니다. 특히 비밀번호에 :, # 등 YAML 특수 문자가 들어 있으면 인용부호 없이 쓰면 다른 구조로 해석되어 해당 노드 전체가 무효화됩니다.

노드가 구독 링크로 자동 생성된 경우 proxies 단락은 보통 수동으로 편집할 필요가 없으며, 클라이언트가 구독을 가져올 때 자동으로 채워줍니다. 직접 서버를 구축했거나 노드를 하나씩 수동으로 추가할 때만 이 단락을 직접 고치게 됩니다.

proxy-groups 단락: 노드를 선택 가능한 정책 그룹으로 묶기

proxy-groups는 사용자가 클라이언트 화면에서 보고 전환할 수 있는 옵션과, 규칙 단락이 최종적으로 참조하는 분기 출구를 결정합니다. 가장 많이 쓰는 세 가지 타입입니다:

proxy-groups:
  - name: "자동 선택"
    type: url-test
    proxies:
      - HK-01
      - SG-02
    url: "http://www.gstatic.com/generate_204"
    interval: 300

  - name: "장애 조치"
    type: fallback
    proxies:
      - HK-01
      - SG-02
    url: "http://www.gstatic.com/generate_204"
    interval: 300

  - name: "노드 선택"
    type: select
    proxies:
      - 자동 선택
      - HK-01
      - SG-02
      - DIRECT

url-test는 지연 시간을 기준으로 현재 가장 빠른 노드를 자동으로 선택하고, fallback은 목록 순서대로 첫 번째로 사용 가능한 노드를 우선 사용하며, select는 수동 선택으로 사용자가 클라이언트 화면에서 직접 클릭해 고를 수 있게 합니다. 주의할 점은 select 타입의 proxies 목록에서 다른 정책 그룹의 이름(위 예시의 "자동 선택")을 직접 참조할 수 있다는 것으로, 정책 그룹을 중첩하는 흔한 방식이며 "자동 측정"을 "노드 선택" 안의 옵션 하나로 포장하기 편리합니다. proxies 목록의 이름은 proxies 단락의 name 또는 다른 정책 그룹의 name과 완전히 일치해야 하며, 대소문자와 전각/반각 문자까지 정확히 맞아야 합니다. 한 글자만 틀려도 해당 정책 그룹이 시작 시 오류를 내거나 해당 옵션이 조용히 사라집니다.

interval은 측정 간격으로 단위는 초이며, 값이 너무 작으면 측정 빈도가 늘어나 트래픽과 배터리를 더 소모합니다. url은 연결 확인 전용 검사 주소를 쓰는 것이 좋고, 일반 웹사이트 주소를 넣으면 측정 결과가 그 사이트 자체의 응답 속도에 영향을 받을 수 있습니다.

rules 단락: 분기 규칙의 매칭 순서와 작성법

rules는 파일의 마지막 단락이며, 위에서 아래로 한 줄씩 매칭하다가 처음 매칭되는 순간 멈추는 단락입니다. 순서 오류가 가장 흔하면서도 스스로 발견하기 가장 어려운 문제입니다. 기본 문법은 다음과 같습니다:

rules:
  - DOMAIN-SUFFIX,google.com,노드 선택
  - DOMAIN-KEYWORD,github,노드 선택
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

각 줄은 「매칭 유형, 매칭 내용, 출구 정책 그룹」의 세 부분으로 이루어지며, 일부 유형은 선택적인 네 번째 파라미터를 붙일 수 있습니다(예: no-resolve는 이 규칙에 대해 DNS 해석을 하지 않는다는 뜻으로, IP 대역 규칙에서 효율을 높이기 위해 자주 씁니다). DOMAIN-SUFFIX는 도메인과 그 하위 도메인을 매칭하고, DOMAIN-KEYWORD는 도메인에 포함된 키워드를 매칭하며, IP-CIDR은 IP 대역을 매칭하고, GEOIP는 IP가 속한 국가/지역을 매칭하며, MATCH는 최종 기본 규칙으로 전체 rules 단락의 맨 마지막 줄에 놓여야 하고 "위 어떤 규칙에도 매칭되지 않으면 여기로"를 의미합니다.

순서대로 매칭되는 방식이기 때문에, 폭넓은 규칙(예를 들어 GEOIP,CN,DIRECT)을 구체적인 규칙보다 앞에 쓰면 뒤에 나오는 특정 도메인용 규칙은 절대 트리거되지 않으며, "특정 사이트에 프록시를 설정했는데 실제로는 적용되지 않는다"는 증상으로 나타납니다. 올바른 순서는 구체적인 도메인/앱 규칙을 먼저 쓰고, 그다음 광범위한 지역/IP 대역 규칙을 쓰고, 마지막에 MATCH로 마무리하는 것입니다.

권장: 규칙 수가 많을 때는 규칙 세트를 원격 규칙 세트(rule-providers)로 분리해 참조하면 수동으로 작성하는 줄 수를 줄이고 일괄 업데이트도 편해집니다. 자세한 작성법은 클라이언트에 내장된 예시 설정이나 공식 문서의 rule-providers 단락 설명을 참고하세요.

흔한 들여쓰기 오류와 필드 오타 함정

YAML은 들여쓰기에 매우 민감하며, 실제 사용 중 반복적으로 나타나는 오류는 다음과 같습니다:

  • 공백과 탭 혼용: YAML 규격은 탭 들여쓰기를 허용하지 않으며, 텍스트 편집기가 들여쓰기를 자동으로 탭으로 바꿔버리면 클라이언트가 시작 시 바로 문법 오류를 냅니다. "탭을 공백으로 대체"하는 편집기로 설정 파일을 여는 것이 좋습니다.
  • 같은 레벨 필드의 들여쓰기 불일치: 같은 배열 항목 내부의 필드는 반드시 같은 열에 엄격히 맞춰야 하며, 공백 하나만 더 들어가도 하위 레벨로 해석되어 해당 필드가 무시되거나 노드 전체 해석이 실패할 수 있습니다.
  • 인용부호 없는 문자열로 인한 타입 오판: 비밀번호나 UUID에 YAML이 특수 기호로 처리하는 문자(콜론, 井자, 대괄호)가 들어 있으면 반드시 인용부호로 감싸야 하며, 그렇지 않으면 해석 결과가 예상과 달라집니다.
  • 필드명 오타는 오류를 내지 않는다: 대부분의 클라이언트는 알 수 없는 필드에 대해 "무시"로 대응하며 "오류"를 내지 않습니다. 예를 들어 allow-lan을 allow_lan으로 잘못 쓰면 설정 파일은 여전히 정상적으로 로드되지만 이 설정만 조용히 무효화됩니다. 원인 파악 시 놓치기 쉬우므로, 핵심 필드를 수정한 뒤에는 클라이언트 로그를 다시 확인하거나 공식 예시로 필드명을 대조하는 것이 좋습니다.
  • proxy-groups가 참조하는 노드 이름이 존재하지 않음: 노드 이름을 바꾸거나 삭제한 뒤 참조를 함께 업데이트하지 않으면 정책 그룹에 옵션이 하나 빠지거나 로드 자체가 실패할 수 있습니다. proxies 단락을 수정한 뒤에는 전체 텍스트 검색으로 해당 노드 이름의 proxy-groups 내 참조도 함께 갱신됐는지 확인하는 것이 좋습니다.

이 단락 구조와 흔한 함정을 설정 파일과 대조해서 한 번 훑어보면, "구독은 가져왔는데 규칙이 적용되지 않는다", "포트를 바꿨는데 효과가 없다" 같은 대부분의 문제를 찾아낼 수 있습니다. 수동으로 수정한 뒤 클라이언트가 시작되지 않는다면, 가장 최근에 고친 단락의 들여쓰기를 먼저 확인하고, 그다음 필드명이 공식 문서와 일치하는지 확인하세요. 보통 문제는 이 두 가지 원인 중 하나에서 나옵니다.

클라이언트 다운로드