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

Clash 설정 파일 구조 완전 분석: port·proxies부터 rules까지 전체 필드

config.yaml을 받았지만 손대기가 무섭다면? 이 글에서는 로드 순서대로 공통 필드, 프록시 목록, 정책 그룹, 규칙 섹션의 문법과 작성법을 하나씩 정리했습니다.

설정 파일 로드 순서와 전체 구조

Clash와 Clash Meta(커널명 mihomo)가 읽어들이는 것은 모두 YAML 형식의 텍스트 파일로, 흔히 config.yaml이라는 이름을 사용합니다. 클라이언트가 시작되거나 구독을 전환할 때 전체 파일을 한 번에 파싱해서 메모리 상의 객체로 만든 뒤 각 섹션 이름에 따라 순서대로 적용하며, "읽으면서 바로 적용되는" 식의 순서 의존성은 없습니다. 다만 읽고 문제를 찾을 때는 아래 순서로 이해하는 것이 가장 효율적입니다:

  1. 공통 필드: 포트, 실행 모드, 로그 레벨, 외부 컨트롤러 등, 클라이언트 자체가 어떻게 동작할지를 결정합니다.
  2. dns 섹션: 도메인 해석 동작으로, 이후 규칙 매칭이 도메인 기준인지 해석된 IP 기준인지에 영향을 줍니다.
  3. proxies 섹션: 노드 목록으로, 각 항목이 하나의 사용 가능한 프록시 서버를 설명합니다.
  4. proxy-groups 섹션: 노드 목록을 정책 그룹으로 묶어, "어떤 노드를 선택할지"를 사용자에게 어떻게 보여줄지 결정합니다.
  5. rules 섹션: 트래픽 매칭 규칙으로, "이 연결이 어떤 정책 그룹을 거칠지"를 결정합니다.

구독 링크로 전달되는 설정 파일도 본질적으로는 같은 필드 구성이며, 구독 제공처의 서버에서 생성될 뿐입니다. 직접 설정을 수정하기 전에는 원본 파일을 백업해두는 것이 좋습니다. 필드를 잘못 고치면 가볍게는 클라이언트가 로드를 거부하고, 심하면 규칙이 무효화되어 전체 트래픽이 직접 연결되거나 하나의 노드로만 몰릴 수 있습니다.

YAML은 들여쓰기에 매우 민감합니다. 항상 스페이스 2칸으로 들여쓰고 Tab을 섞어 쓰지 말며, 콜론 뒤에는 반드시 공백 하나를 두고, 목록 항목은 하이픈과 공백으로 시작해야 합니다. 이 규칙들을 지키지 않는 것이 초보자가 설정 파일을 망가뜨리는 가장 흔한 원인입니다.

공통 필드: port, mode, log-level과 외부 제어

파일 맨 위쪽에는 보통 들여쓰기가 필요 없는 최상위 필드들이 모여 있으며, 클라이언트 자체의 동작 방식을 제어합니다:

port: 7890
socks-port: 7891
redir-port: 7892
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
secret: ""
  • port / socks-port: 각각 HTTP 프록시 포트와 SOCKS5 프록시 포트를 개방하며, 시스템이나 브라우저에서 필요에 맞게 하나를 선택해 설정합니다.
  • mixed-port: 하나의 포트가 HTTP와 SOCKS5 요청을 동시에 받으며, 요즘 클라이언트 UI는 대부분 이 포트 하나만 기본으로 노출해 시스템 프록시 설정을 단순화합니다.
  • allow-lan: 같은 로컬 네트워크 내 다른 기기가 이 기기의 프록시를 통해 접속하도록 허용할지 여부이며, 휴대폰이 로컬 네트워크 공유로 인터넷을 쓸 때는 켜야 합니다.
  • mode: 핵심 동작 모드로, rule은 rules 섹션에 따라 분기 매칭함을, global은 모든 트래픽이 하나의 정책 그룹을 거침을, direct는 프록시를 거치지 않고 전부 직접 연결함을 의미합니다.
  • log-level: 로그의 상세 정도로, 문제를 조사할 때는 일시적으로 debug로 바꿀 수 있으며, 평상시에는 info나 warning을 유지해 로그 파일이 빠르게 커지는 것을 막는 것이 좋습니다.
  • external-controller: RESTful API의 수신 주소를 여는 필드로, secret 키와 함께 사용되며 클라이언트 GUI와 서드파티 패널이 이 인터페이스를 통해 상태를 읽고 노드를 전환합니다.

이 필드들은 대부분 기본값이 있고, GUI에서는 보통 화면상의 토글로 YAML의 값을 덮어쓰지만, 구독 링크로 생성된 설정 파일은 여전히 YAML 필드가 기준이 되며 충돌 시에는 클라이언트가 실제로 로드한 결과를 판단 기준으로 삼습니다.

proxies 섹션: 각 노드를 어떻게 기술하는가

proxies는 목록 형태이며, 목록의 각 항목이 하나의 사용 가능한 노드에 대응합니다. 필드는 프로토콜 종류에 따라 다르지만 공통 필드는 동일합니다:

proxies:
  - name: "HK-01"
    type: ss
    server: 1.2.3.4
    port: 8443
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

  - name: "SG-Trojan"
    type: trojan
    server: example.com
    port: 443
    password: "your-password"
    sni: example.com
    skip-cert-verify: false

주요 공통 필드 설명:

  • name: 노드의 표시 이름으로, 정책 그룹에서 이 이름으로 노드를 참조합니다. 이름이 중복되면 참조가 모호해질 수 있으니 고유하게 유지하는 것이 좋습니다.
  • type: 프로토콜 종류로, 흔히 ss(Shadowsocks), ssr, vmess, trojan, hysteria2 등이 있으며, 프로토콜마다 필요한 전용 필드가 다릅니다.
  • server / port: 노드의 서버 주소와 포트로, 접속 목적지에 직접 영향을 줍니다.
  • udp: 해당 노드가 UDP 트래픽을 전달할 수 있는지 여부로, 게임과 일부 실시간 앱은 UDP에 의존하기 때문에 꺼두면 이런 트래픽이 실패하거나 강제로 직접 연결될 수 있습니다.
  • skip-cert-verify: TLS 인증서 검증을 건너뛸지 여부로, 자체 서명 인증서를 쓰는 경우에만 켜야 하며 일반적인 노드는 꺼두는 것이 더 안전합니다.

노드를 직접 작성할 때 가장 흔한 실수는 비밀번호에 콜론이나 특수 문자가 포함되어 있는데 따옴표로 감싸지 않는 것입니다. YAML 파서는 콜론을 새로운 키-값 구분자로 인식하므로, 비밀번호는 항상 쌍따옴표로 감싸는 것이 좋습니다.

proxy-groups 섹션: 정책 그룹 문법과 주요 타입

proxy-groups는 proxies의 노드들을 규칙에서 참조 가능한 그룹으로 묶습니다. 주요 타입은 다음과 같습니다:

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

  - name: "수동 전환"
    type: select
    proxies:
      - 자동 선택
      - HK-01
      - SG-Trojan
      - DIRECT

  - name: "장애 조치"
    type: fallback
    proxies:
      - HK-01
      - SG-Trojan
    url: "http://www.gstatic.com/generate_204"
    interval: 300
  • select: 수동 전환 그룹으로, 화면에 드롭다운 목록이 표시되며 사용자가 클릭한 것을 사용합니다. 가장 바깥쪽에 두어 사용자에게 최종 선택권을 주기에 적합합니다.
  • url-test: 자동 속도 측정 그룹으로, interval초 간격으로 그룹 내 노드를 탐지해 지연이 가장 낮은 노드를 자동으로 선택합니다.
  • fallback: 장애 조치 그룹으로, 목록 순서대로 시도해 처음으로 연결 가능한 노드를 우선 사용하고, 이전 노드가 실패해야 다음으로 넘어갑니다.
  • load-balance: 로드 밸런싱 그룹으로, 정책에 따라 연결을 여러 노드에 분산시키며 노드 수가 많고 성능이 비슷한 상황에 적합합니다.

정책 그룹의 proxies 목록에는 노드 이름 외에 다른 정책 그룹의 이름을 넣을 수도 있고, 내장 정책인 DIRECT나 REJECT를 넣을 수도 있으며 각각 직접 연결과 연결 거부를 의미합니다. 그룹끼리는 서로 참조하며 중첩할 수 있지만 순환 참조가 생기면 안 되며, 그럴 경우 클라이언트가 로드 시 오류를 냅니다.

rules 섹션: 매칭 문법과 우선순위

rules는 위에서 아래로 순서대로 매칭되는 목록으로, 첫 번째로 일치한 규칙이 즉시 적용되고 그 아래는 더 이상 비교하지 않습니다. 따라서 규칙의 순서 자체가 우선순위입니다:

rules:
  - DOMAIN-SUFFIX,openai.com,자동 선택
  - DOMAIN-KEYWORD,google,자동 선택
  - DOMAIN,ads.example.com,REJECT
  - 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 파라미터와 함께 써서 DNS 해석을 건너뛰고 연결 목적지의 IP 값 자체로 판단합니다.
  • GEOIP: IP가 속한 국가나 지역으로 매칭하며, GEOIP,CN,DIRECT는 중국 본토 직접 연결에 흔히 쓰이는 작성법입니다.
  • PROCESS-NAME: 연결을 시작한 프로세스 이름으로 매칭하며, 데스크톱에서 앱 단위 분기를 할 때 자주 사용됩니다.
  • MATCH: 최종 처리 규칙으로 목록 맨 마지막에 두며, 앞의 모든 규칙에 걸리지 않은 트래픽이 이 규칙을 따릅니다. 거의 모든 설정 파일에는 마지막에 MATCH가 하나 필요하며, 없으면 매칭되지 않은 트래픽의 처리 방향이 불명확해집니다.

규칙에서 참조하는 정책 그룹 이름은 proxy-groups의 name과 완전히 일치해야 하며 대소문자, 공백까지 맞아야 합니다. 그렇지 않으면 클라이언트가 로드할 때 보통 "정의되지 않은 정책을 참조했다" 같은 오류를 내며 전체 설정의 적용을 거부합니다.

DNS 해석 방식은 IP 계열 규칙이 제대로 동작하는지에 영향을 줍니다. fake-ip 모드를 켜면 규칙 매칭 단계에서 얻는 연결 목적지가 가상 IP이므로 IP-CIDR 계열 규칙이 예상대로 동작하지 않기 쉽습니다. 이럴 때는 보통 특정 도메인에 대해 DNS 모드를 실제 해석으로 전환해야 하며, 구체적인 판단 로직은 본 사이트의 DNS 관련 글에서 자세히 다룹니다.

흔한 오류와 문제 해결 방법

설정 파일을 직접 수정한 뒤 클라이언트가 적용되지 않거나 바로 오류가 나면 다음 방향으로 확인해볼 수 있습니다:

  1. 먼저 온라인 YAML 검증 도구나 텍스트 에디터의 문법 강조 기능으로 들여쓰기와 콜론 뒤 공백을 확인합니다. 대부분의 "로드 실패"는 로직 문제가 아니라 형식 문제입니다.
  2. proxy-groups에서 참조한 노드 이름과 proxies의 name이 완전히 일치하는지 확인합니다. 복사해서 붙여 넣을 때 공백이 추가되거나 전각 문자가 섞이기 가장 쉽습니다.
  3. rules에서 참조한 정책 그룹 이름이 proxy-groups에 실제로 존재하는지 확인합니다. 규칙을 추가할 때 정책 그룹 이름을 잘못 옮기는 경우가 자주 발생합니다.
  4. log-level을 임시로 debug로 바꾸고 클라이언트를 재시작해 로그 출력을 확인합니다. 연결 실패에 대한 구체적인 오류 메시지가 보통 어느 부분의 설정이 문제인지 알려줍니다.
  5. 구독 제공처가 생성한 설정 자체에 문제가 있다고 의심될 때는 클라이언트에서 원본 구독 내용을 확인해 자신이 이해한 필드와 하나씩 대조해보는 것이 좋으며, 곧바로 클라이언트 자체를 의심하지 않는 것이 좋습니다.

이 다섯 개 섹션의 구조와 로드 순서를 이해하면 이후 구독 제공처가 준 복잡한 설정 파일을 마주하거나 직접 분기 규칙을 하나 추가하고 싶을 때도, 대부분 해당 섹션의 문법을 그대로 따라 수정할 수 있어 전체 파일을 처음부터 다시 쓸 필요가 없습니다.

NEXT STAGE

설치 파일을 받고 다음 단계로

Windows, macOS, Android, iOS, Linux 설치 파일과 설정 절차를 모두 사이트에서 준비해두었습니다.

▶Clash 다운로드 가이드 보기
▶클라이언트 다운로드