설정 심화 예상 읽기 시간 14분

Clash 설정 파일 구조 해설: 포트 설정부터 프록시 그룹까지 YAML 한눈에 이해하기

설정 순서에 따라 기본 설정, 프록시 노드, 프록시 그룹, 규칙 제공자와 DNS 항목을 살펴보고 필드 간 참조 관계를 설명합니다.

YAML Structure

YAML의 계층과 데이터 유형부터 이해하기

Clash 설정 파일은 보통 YAML을 사용합니다. 읽을 때 특정 노드 이름만 검색하기보다 먼저 들여쓰기가 나타내는 부모·자식 관계를 확인해야 합니다. 최상위 필드는 일반적으로 proxies, proxy-groups, rules, dns 같은 주요 설정 항목입니다. 안쪽으로 들여쓴 필드는 상위 객체에 속합니다. 목록 항목은 하이픈으로 시작하며, 같은 들여쓰기 깊이의 항목은 서로 나란한 요소입니다.

mode: rule
log-level: info

proxies:
  - name: "예시 노드"
    type: ss
    server: example.com
    port: 443

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "예시 노드"
      - DIRECT

이 설정에는 스칼라 필드 두 개, 노드 목록 하나, 프록시 그룹 목록 하나가 포함되어 있습니다. name, type, server는 목록 안의 동일한 노드 객체에 속하고, 프록시 그룹의 proxies는 이름 목록입니다. 목록에 있는 “예시 노드”는 다른 위치에서 같은 이름으로 정의되어 있어야 합니다.

YAML은 들여쓰기에 민감하므로 공백을 통일해 사용하고 탭은 피하는 것이 좋습니다. 콜론, 샵, 특수 기호가 포함되었거나 불리언으로 해석될 수 있는 이름은 따옴표로 감쌀 수 있습니다. 주석은 #으로 시작하며 설명에만 사용되고 코어 실행에는 영향을 주지 않습니다. 설정 필드명은 코어가 지원하는 표기법을 사용해야 합니다. 중국어 표시 이름을 바꿔도 필드의 의미는 달라지지 않지만 이름 참조에는 영향을 줍니다.

General Settings

기본 설정, 동작 모드와 수신 포트

파일 앞부분에는 포트, LAN 접근, 동작 모드, 로그 수준, 컨트롤 인터페이스가 자주 등장합니다. 이러한 필드는 프로그램이 트래픽을 수신하는 방식과 클라이언트 UI가 코어에 연결하는 방식을 결정하지만, 특정 도메인이 최종적으로 어떤 노드를 사용할지는 결정하지 않습니다.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "독립적인 컨트롤 키를 설정하세요"

포트 필드 구분하기

  • port는 일반적으로 HTTP 프록시 수신 포트를 의미합니다.
  • socks-port는 SOCKS5 프록시 수신 포트를 의미합니다.
  • mixed-port는 하나의 포트에서 HTTP와 SOCKS 트래픽을 모두 수신하며, 데스크톱 클라이언트에서 자주 사용됩니다.
  • redir-port와 tproxy-port는 특정 투명 프록시 방식에 사용되며, 실제 사용 가능 여부는 운영체제와 네트워크 규칙에 따라 달라집니다.

여러 수신 포트가 로컬 컴퓨터의 다른 프로그램이 사용 중인 포트와 충돌해서는 안 됩니다. 데스크톱 클라이언트는 보통 UI 설정에서 포트를 관리하므로, 구독에서 생성된 YAML을 직접 수정한 뒤에는 클라이언트에 설정을 덮어쓰는 옵션이 있는지도 확인해야 합니다.

mode: rule은 rules를 위에서부터 순서대로 매칭합니다. global은 일반적으로 모든 트래픽을 전역 정책으로 보내고, direct는 직접 연결합니다. UI의 “규칙, 전역, 직접 연결” 전환은 실행 중 모드를 변경할 수 있으며, 원본 구독 파일에 다시 저장되지 않을 수도 있습니다.

allow-lan은 LAN 기기가 수신 포트에 접근할 수 있는지 제어합니다. 활성화한 뒤에는 bind-address, 시스템 방화벽, 실제 네트워크 경계를 함께 고려해 접근을 제한해야 합니다. external-controller는 컨트롤 인터페이스 주소입니다. 그래픽 클라이언트는 이를 통해 연결, 정책, 로그 상태를 읽습니다. 로컬 컴퓨터가 아닌 주소에서 인터페이스에 접근해야 한다면 secret을 설정하고 접근 가능한 범위를 제한하세요.

Proxy Sources

프록시 노드와 프록시 제공자

proxies에는 정적으로 정의한 노드가 저장됩니다. 각 노드에는 최소한 고유 이름, 프로토콜 유형, 서버 주소, 포트와 해당 프로토콜에 필요한 인증 필드가 포함되어야 합니다. 프로토콜마다 필요한 매개변수는 서로 다릅니다. Shadowsocks에는 일반적으로 cipher와 password가 사용되고, Trojan에는 비밀번호와 TLS 관련 설정이 자주 쓰이며, VMess와 VLESS에는 각각 고유한 인증, 전송, 암호화 필드가 있습니다.

proxies:
  - name: "Tokyo-A"
    type: trojan
    server: edge.example.com
    port: 443
    password: "example-password"
    sni: edge.example.com
    udp: true

server는 연결 대상이고 sni는 TLS 핸드셰이크에 사용되는 서버 이름입니다. 두 값은 같을 수도 있고, 서비스 설정에 따라 별도로 지정될 수도 있습니다. 연결에 실패했다고 TLS 필드를 임의로 바꾸거나 삭제해서는 안 됩니다. 프로토콜 매개변수는 구독 제공자가 제공한 유효한 설정과 최신 mihomo 문서를 기준으로 확인하세요.

노드가 많을 때는 proxy-providers로 외부 노드 모음을 가져오는 경우가 많습니다. 제공자는 지정된 소스에서 노드를 읽고 일정에 따라 업데이트하며, 프록시 그룹은 use로 이를 참조합니다. 이렇게 하면 “노드가 어디에서 오는가”와 “노드를 어떻게 선택에 활용하는가”를 분리할 수 있습니다.

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

primary는 제공자 키이며, 뒤에서 프록시 그룹이 이를 참조합니다. path는 로컬 캐시 위치를 지정하고 interval은 업데이트 주기를 의미합니다. 헬스 체크는 지정된 조건에서 노드의 연결 가능성이나 지연 시간을 확인할 뿐, 실제 서비스 웹사이트의 접속 가능성을 보장하지 않으며 인증 매개변수를 자동으로 수정하지도 않습니다.

Policy Groups

프록시 그룹이 노드와 규칙을 연결하는 방식

proxy-groups는 전체 설정의 조정 계층입니다. 규칙은 보통 특정 서버 주소를 직접 지정하지 않고 트래픽을 프록시 그룹으로 보냅니다. 프록시 그룹은 다시 노드, 내장 정책 또는 다른 프록시 그룹을 선택합니다. 이 계층을 이해해야 UI에 여러 단계의 선택 항목이 나타나는 이유를 설명할 수 있습니다.

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "자동 선택"
      - "Tokyo-A"
      - DIRECT

  - name: "자동 선택"
    type: url-test
    use:
      - primary
    url: "https://www.gstatic.com/generate_204"
    interval: 300

  - name: "미디어 서비스"
    type: select
    proxies:
      - "노드 선택"
      - DIRECT

첫 번째 그룹은 select를 사용하며, 사용자가 UI에서 구성원을 선택합니다. 두 번째 그룹은 url-test를 사용해 제공자 primary의 노드 중 테스트 결과에 따라 선택합니다. 세 번째 그룹은 서버를 직접 나열하지 않고 “노드 선택”을 참조하므로, 참조 관계를 따라 최종 출구 노드를 결정합니다.

proxies는 정적 노드, 내장 정책 또는 다른 프록시 그룹을 나열하는 데 사용하고, use는 proxy-providers를 참조하는 데 사용합니다. 둘 다 구성원 출처를 만들 수 있지만 객체 유형은 다릅니다. 흔한 오류는 제공자 이름을 proxies에 넣거나 노드 이름을 use에 적는 것입니다.

자주 사용하는 프록시 그룹 유형

select
수동 선택 메뉴를 제공하며, 전체 출구, 애플리케이션별 분류, 고정 정책이 필요한 경우에 적합합니다.
url-test
지정한 테스트 주소와 주기로 구성원을 확인하고, 일반적으로 테스트 결과가 더 좋은 노드를 선택합니다.
fallback
구성원을 순서대로 확인하며, 앞선 구성원을 사용할 수 없을 때 다음 구성원으로 전환합니다.
load-balance
설정한 정책에 따라 여러 구성원 사이에 연결을 분배하며, 적합성은 서비스 세션의 특성에 따라 달라집니다.

DIRECT, REJECT 등은 내장 정책이므로 proxies에 정의할 필요가 없습니다. 사용자 지정 이름은 대소문자, 공백, 기호를 포함해 완전히 일치해야 합니다. 프록시 그룹은 서로 중첩할 수 있지만 순환 참조를 만들면 안 됩니다. 코어가 명확한 출구를 결정할 수 없기 때문입니다.

Routing Rules

규칙 매칭 순서와 규칙 세트 참조

rules는 트래픽을 어떤 정책으로 보낼지 결정합니다. 규칙 모드에서는 코어가 일반적으로 위에서 아래로 확인하며, 하나의 규칙이 매칭되면 다음 규칙은 검사하지 않습니다. 따라서 구체적인 도메인과 명확한 네트워크 대역은 더 포괄적인 규칙보다 앞에 두고, 최종 대체 규칙은 마지막에 배치해야 합니다.

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.net,노드 선택
  - DOMAIN-KEYWORD,media,미디어 서비스
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

DOMAIN은 완전한 도메인명을 매칭하고, DOMAIN-SUFFIX는 지정한 도메인과 하위 도메인을 매칭하며, DOMAIN-KEYWORD는 도메인에 포함된 키워드로 매칭합니다. IP-CIDR은 대상 IPv4 네트워크 대역을 기준으로 판단하고, IPv6에는 해당 IPv6 규칙 유형을 사용할 수 있습니다. GEOIP은 지리 데이터베이스를 바탕으로 IP의 소속 지역을 판단합니다. MATCH는 최종 대체 규칙이므로 규칙의 마지막에 배치해야 합니다.

규칙의 마지막 항목은 보통 “노드 선택”, “미디어 서비스”, DIRECT, REJECT와 같은 대상 정책 이름입니다. 대상 이름이 proxy-groups에 존재하지 않으면 규칙 문법이 완전해 보여도 로드 단계에서 오류가 발생하거나 예상대로 작동하지 않습니다.

많은 규칙은 rule-providers에 넣을 수 있습니다. 규칙 제공자는 소스, 캐시 경로, 동작 유형, 업데이트 주기를 정의하고, 주 규칙 영역에서는 RULE-SET으로 호출합니다.

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

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

behavior는 규칙 세트의 매칭 형태를 설명하며, 일반적인 값으로 domain, ipcidr, classical이 있습니다. 실제 규칙 파일의 내용은 지정한 동작 유형과 일치해야 합니다. classical은 비교적 완전한 클래식 규칙 표현식을 담을 수 있고, domain과 ipcidr은 각각 해당 유형의 데이터 모음에 초점을 둡니다.

DNS Pipeline

DNS 항목이 도메인 해석에 관여하는 방식

DNS 설정은 서버 주소 두 개를 입력하는 것만으로 끝나지 않습니다. 도메인 해석 방식, 도메인과 IP 사이의 규칙 연결, TUN 환경에서 트래픽이 코어로 안정적으로 들어오는지에 영향을 줍니다. mihomo에서 자주 사용하는 필드에는 활성화 상태, 수신 주소, 해석 모드, 기본 해석기, 주요 해석기, 보조 해석기, 도메인별 분할 라우팅을 위한 네임서버 정책이 있습니다.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"

default-nameserver는 DoH 또는 DoT 서버 자체의 도메인을 해석하는 데 주로 사용하므로, 일반적으로 직접 접근할 수 있는 IP 주소 기반 해석기를 지정합니다. nameserver는 주요 질의 출처입니다. fallback의 참여 여부와 결과 필터링 방식은 현재 코어 버전과 관련 필터 설정에 따라 달라집니다.

enhanced-mode: fake-ip는 애플리케이션에 예약 주소 범위의 매핑 주소를 반환하고, 코어는 이를 통해 도메인 정보를 유지한 채 후속 전달을 처리합니다. 도메인 규칙 판단에는 유리하지만 일부 LAN 서비스, 기기 검색, 게임 플랫폼 또는 실제 주소에 의존하는 프로그램은 fake-ip-filter에 추가해야 할 수 있습니다. 또 다른 일반적인 모드는 redir-host이며 처리 경로가 다릅니다. 구체적인 선택은 운영체제, 클라이언트 구현, 애플리케이션 호환성을 함께 고려해야 합니다.

DNS 오류가 항상 “도메인을 확인할 수 없음”으로 나타나는 것은 아닙니다. 브라우저가 이미 결과를 받았지만 잘못된 규칙 때문에 연결이 사용할 수 없는 정책으로 전달되는 경우도 있습니다. 또는 시스템 DNS, 브라우저 보안 DNS, 코어 DNS가 동시에 존재해 실제 질의가 예상한 경로를 거치지 않을 수도 있습니다. 문제를 해결할 때는 애플리케이션 요청 진입점, DNS 수신 상태, 해석 로그, 최종 규칙 매칭을 각각 확인해야 합니다.

Traffic Capture

TUN 모드와 시스템 프록시의 설정 범위

시스템 프록시는 운영체제의 프록시 설정을 따르는 애플리케이션에만 영향을 줍니다. 일부 명령줄 도구, 게임, 독립 네트워크 스택을 사용하는 프로그램, UDP 트래픽은 시스템 프록시를 우회할 수 있습니다. TUN 모드는 가상 네트워크 인터페이스로 더 많은 시스템 트래픽을 수신한 뒤 DNS, 규칙, 프록시 그룹에 전달합니다.

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

stack은 TUN 네트워크 스택 구현을 결정하며, 사용 가능한 값과 권장 설정은 플랫폼과 mihomo 버전에 따라 달라집니다. auto-route는 라우팅을 자동으로 구성하고, auto-detect-interface는 기본 네트워크 인터페이스를 식별합니다. TUN을 활성화하려면 일반적으로 해당 운영체제 권한이 필요하며, 클라이언트가 서비스 모드나 보조 구성 요소를 통해 권한 작업을 처리할 수 있습니다.

TUN은 트래픽 진입점일 뿐 규칙이나 프록시 그룹을 대신하지 않습니다. 트래픽이 코어로 들어온 뒤에도 도메인 해석, 스니핑 설정, 규칙 매칭, 정책 선택을 거쳐야 합니다. TUN을 켠 후 LAN 기기에 접근할 수 없다면 모든 분할 라우팅 규칙을 삭제하기보다 사설 네트워크 대역의 직접 연결 규칙, 라우팅 제외 설정, DNS 하이재킹 범위를 확인하세요.

시스템 프록시와 TUN은 클라이언트에서 통합 관리할 수 있습니다. 실제 사용 중에는 네트워크를 가로채는 도구를 여러 개 동시에 실행하지 않도록 하고, 절전 모드 해제, 네트워크 전환, VPN 인터페이스 변경 후 기본 라우팅이 갱신되었는지도 확인해야 합니다. TUN을 끈 뒤에도 네트워크가 비정상이라면 클라이언트가 시스템 프록시와 라우팅 상태를 복원했는지 점검하세요.

Validation

설정 수정 후 검증 및 문제 해결 절차

설정 파일이 텍스트 편집기에서 열린다고 해서 코어가 로드할 수 있다는 뜻은 아닙니다. 안정적으로 수정하려면 한 번에 하나의 논리 단위만 변경하고 복구 가능한 버전을 남겨 두세요. 클라이언트에서 설정 검사, 코어 로그, 오버라이드 미리보기를 제공한다면 특정 조각만 확인하지 말고 병합 후 최종 YAML을 먼저 점검해야 합니다.

  1. YAML 구조 확인: 들여쓰기, 목록 하이픈, 따옴표, 콜론 위치가 올바른지 확인하고 주요 최상위 필드가 중복으로 덮어쓰이지 않았는지 점검합니다.
  2. 이름 참조 확인: 규칙 대상, 프록시 그룹 구성원, use 제공자 이름, RULE-SET 이름을 하나씩 대조합니다.
  3. 외부 리소스 확인: 프록시 제공자와 규칙 제공자가 업데이트되는지, 로컬 캐시 경로에 쓰기 권한이 있는지, 다운로드한 내용의 형식이 선언과 일치하는지 확인합니다.
  4. 실행 로그 확인: 로드 오류는 보통 필드나 객체 이름을 알려 줍니다. 연결 오류는 DNS, 규칙 매칭, 노드 핸드셰이크 정보를 함께 살펴 판단해야 합니다.
  5. 최소 단위 테스트: 먼저 DIRECT를 테스트하고, 다음으로 정적 노드 하나, 그 후 프록시 그룹과 규칙 세트를 테스트해 문제 범위를 단계적으로 좁힙니다.

자주 발생하는 오류

  • 프록시 그룹이 이름이 변경되었거나 구독 업데이트로 삭제된 노드를 참조하고 있습니다.
  • 규칙이 존재하지 않는 프록시 그룹을 가리키거나 이름에 불필요한 공백이 포함되어 있습니다.
  • proxy-providers는 정의했지만 프록시 그룹에서 use로 가져오지 않았습니다.
  • RULE-SET 이름과 rule-providers의 키 이름이 일치하지 않습니다.
  • 포괄적인 규칙이 구체적인 규칙보다 앞에 있어 뒤의 규칙이 매칭될 기회를 잃습니다.
  • DNS 수신 포트가 충돌하거나 애플리케이션 요청이 코어가 관리하는 해석 경로로 들어오지 않습니다.
  • 구독 캐시를 직접 편집해 업데이트 후 사용자 지정 내용이 새로운 구독 결과로 교체됩니다.

전체 설정은 하나의 참조 체인으로 이해할 수 있습니다. 애플리케이션 트래픽은 시스템 프록시, 투명 프록시 또는 TUN을 통해 먼저 코어로 들어옵니다. DNS 항목이 도메인을 해석하고, rules와 규칙 제공자가 대상 정책을 결정합니다. proxy-groups는 정적 노드나 프록시 제공자에서 출구를 선택하고, 최종적으로 구체적인 프로토콜 노드가 연결을 수립합니다. 이 흐름에 따라 읽으면 필드를 하나씩 외우는 것보다 설정의 끊어진 지점을 쉽게 찾을 수 있습니다.

Clash 다운로드