고급 설정

Clash config.yaml 설정 파일 구조 총정리: 포트, DNS, 프록시부터 규칙까지

설정 파일을 위에서부터 살펴보며 포트, 실행 모드, DNS, 프록시, 프록시 그룹, 규칙 제공자와 규칙의 역할 및 자주 하는 설정 실수를 설명합니다.

포트와 실행 모드: 먼저 트래픽이 들어오는 지점 확인

설정이 적용됐는지 확인하려면 먼저 앱이 어느 포트로 연결되는지 확인한 뒤, 코어가 트래픽을 어떻게 분기하는지 살펴보세요. 아래 예시는 mihomo 기준입니다. 구버전 Clash와 mihomo는 지원하는 필드가 다르며, 클라이언트 버전이 코어 버전과 같다는 보장도 없습니다. 단독 실행 환경에서는 mihomo -v로 코어 버전을 확인하고, GUI 클라이언트에서는 표시된 코어 정보를 기준으로 확인하세요.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

mixed-port는 HTTP와 SOCKS 프록시 연결을 모두 받습니다. 이 예시대로 앱을 설정할 때는 프록시 주소에 127.0.0.1, 포트에 7890을 입력하고, 프로토콜은 앱이 지원하는 항목을 선택하세요. port와 socks-port를 따로 설정했다면 각각 HTTP와 SOCKS에 해당합니다. DNS 수신 포트나 컨트롤 인터페이스 포트를 앱의 프록시 항목에 입력하지 마세요. 7890은 예시 값이며 모든 클라이언트에서 고정으로 사용하는 포트가 아닙니다.

시스템 프록시가 켜져 있는지, 앱이 시스템 프록시 설정을 따르는지는 설정 파일과 별개의 문제입니다. TUN은 가상 네트워크 인터페이스를 통해 라우팅 조건에 해당하는 트래픽을 처리하며, 설정은 별도의 최상위 tun 섹션에 있습니다. mixed-port를 수정해도 TUN이 켜지지는 않습니다. TUN을 켠 뒤에도 브라우저에서 웹페이지가 열린다는 이유만으로 특정 앱의 트래픽 경로를 판단할 수는 없습니다.

DNS: 수신 주소, 업스트림 서버, Fake-IP 구분하기

dns는 최상위 맵입니다. enable은 코어의 DNS 기능을 켜고, listen은 코어가 DNS 쿼리를 받는 주소를 지정하며, nameserver에는 이름을 조회할 업스트림 서버를 나열합니다. 아래 예시는 로컬 테스트용으로 루프백 주소의 1053 포트를 사용해, 수신 주소가 LAN으로 노출되지 않도록 합니다.

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - localhost
    - '*.lan'

기본 필터 모드에서는 fake-ip-filter와 일치하는 도메인에 Fake-IP를 반환하지 않습니다. 그렇다고 해당 도메인을 업스트림에서 반드시 조회할 수 있다거나 연결이 직접 연결된다는 뜻은 아닙니다. Fake-IP는 연결을 도메인과 다시 연결할 수 있도록 코어가 사용하는 주소 매핑입니다. 프록시 사용 여부는 실행 모드와 규칙에 따라 결정됩니다. 와일드카드 항목 '*.lan'은 앞의 별표가 YAML 별칭 문법으로 해석되지 않도록 따옴표로 감싸야 합니다.

nslookup -port=1053 example.com 127.0.0.1을 실행해 수신 포트를 따로 확인할 수 있습니다. 이 예시에서는 필터링되지 않은 A 레코드 쿼리에 설정된 대역의 Fake-IP가 반환됩니다. 이는 쿼리가 코어에 도달해 응답을 받았다는 것만 확인할 뿐, 시스템 DNS가 전환됐거나 대상 사이트에 연결할 수 있다는 뜻은 아닙니다. 직접 조회는 성공했는데 앱에서 다르게 동작한다면 앱 내장 암호화 DNS, 시스템 캐시, TUN 사용 시 DNS 가로채기 설정을 확인하세요.

proxies와 proxy-groups: 노드 정의와 정책 선택 분리하기

최상위 proxies는 아웃바운드 노드 목록입니다. 각 항목에는 보통 name, type, server, port가 포함되며, 나머지 매개변수는 프로토콜에 따라 달라집니다. 노드의 port는 원격 서버를 가리키며 로컬의 mixed-port와는 관계가 없습니다. 구독 URL을 노드의 server에 입력하지 마세요. 클라이언트가 구독 정보를 완성된 설정으로 변환할 수 있으며, mihomo의 proxy-providers는 설정에 따라 노드 모음을 불러오는 기능입니다.

최상위 proxy-groups는 정책 그룹을 정의합니다. 그룹 안의 proxies는 후보 항목의 이름 목록이지 노드 객체 목록이 아닙니다. 노드 프로바이더에서 후보 항목을 가져올 때는 그룹의 use에 프로바이더 이름을 지정하세요. 먼저 내장 아웃바운드만 포함한 그룹으로 참조 관계를 확인하면 노드 인증 정보를 입력하지 않아도 됩니다.

proxy-groups:
  - name: Lab-Select
    type: select
    proxies:
      - DIRECT
      - REJECT

select 그룹은 현재 선택된 항목을 사용합니다. 규칙이 Lab-Select와 일치했을 때 현재 선택이 DIRECT면 직접 연결하고, REJECT면 거부합니다. 테스트하기 전에 클라이언트에서 그룹 내 선택 항목을 확인하세요. 화면에 이전 선택이 복원될 수 있습니다. 노드를 그룹에 추가할 때는 노드의 전체 name을 복사하고 대소문자, 공백, 문장 부호가 일치하는지 확인하세요. 정책 그룹 이름을 바꿨다면 해당 그룹을 참조하는 규칙도 함께 수정해야 합니다.

rule-providers: 규칙 집합을 정의해도 트래픽이 분기되는 것은 아닙니다

rule-providers는 매칭 조건을 제공할 뿐 아웃바운드 노드를 제공하지 않습니다. 여기에 규칙 집합을 선언하면 이름과 내용이 연결될 뿐입니다. 실제로 사용하려면 rules에 RULE-SET을 추가하고, 규칙이 일치했을 때 사용할 아웃바운드를 지정해야 합니다. 먼저 인라인 규칙 집합으로 확인하면 다운로드나 캐시 문제를 배제할 수 있습니다.

rule-providers:
  lab-domains:
    type: inline
    behavior: domain
    payload:
      - '+.example.org'

HTTP 프로바이더를 사용하려면 type: http, url, 로컬 캐시 path, 업데이트 주기 interval을 별도로 설정하세요. interval: 86400은 단위가 초이며 24시간을 뜻합니다. format은 리소스의 실제 형식과 일치해야 합니다. 로그인 페이지를 반환하는 링크를 규칙 파일로 사용할 수 없고, 확장자를 바꾼다고 텍스트가 MRS 형식으로 변환되는 것도 아닙니다. GUI 클라이언트의 코어 작업 디렉터리는 원본 구독 파일이 있는 디렉터리와 다를 수 있습니다. 캐시를 찾을 때는 먼저 작업 디렉터리를 확인한 다음 상대 경로를 점검하세요.

rules: 구체성 순서가 아니라 목록 순서대로 매칭

아래 목록을 앞의 설정에 이어 붙이세요. rules, rule-providers, proxy-groups, dns는 모두 최상위 키이므로 서로 들여쓰지 않습니다. 코어는 규칙을 위에서부터 확인하고, 처음 일치한 규칙에 지정된 정책을 사용합니다. 더 구체적인 도메인 조건을 자동으로 앞쪽으로 옮기지는 않습니다.

rules:
  - DOMAIN,example.org,DIRECT
  - RULE-SET,lab-domains,Lab-Select
  - MATCH,DIRECT

연결 대상 도메인을 코어가 확인할 수 있다면 example.org는 첫 번째 줄과 일치하고, www.example.org는 규칙 집합과 일치해 Lab-Select로 전달됩니다. 규칙 집합 줄을 완전한 도메인 규칙보다 앞에 두면 루트 도메인도 규칙 집합에 먼저 잡힙니다. MATCH를 앞에 두면 뒤에 있는 규칙은 매칭될 기회가 없습니다. 테스트할 때는 Lab-Select에서 REJECT를 선택하고 연결 로그에서 하위 도메인 요청이 예상한 규칙과 일치하는지 확인하세요. 예시 사이트에서 실제 웹페이지가 열리는지는 판단 기준으로 삼지 마세요.

설정 오류와 트래픽 분기 문제: 파싱, 로드, 연결 단계별 점검

  1. 먼저 YAML 문법과 참조를 확인하세요. 들여쓰기에는 공백을 사용하고 같은 수준의 키를 맞춰 정렬하세요. 목록 항목에는 하이픈을, 맵 항목에는 키와 값을 사용합니다. 규칙을 추가한다고 최상위 rules를 다시 만들지 말고 기존 목록에 추가하세요. 단독 실행 환경이라면 설정 디렉터리에서 mihomo -t -f config.yaml로 설정을 테스트할 수 있습니다. 클라이언트가 별도의 작업 디렉터리를 사용한다면 실제 디렉터리와 설정 파일을 기준으로 테스트하세요. 첫 번째 오류 메시지를 확인한 뒤 구조를 먼저 수정하고 이름을 점검하세요.
  2. 실제로 적용된 설정을 테스트하는지 확인하세요. GUI 클라이언트는 구독, 재정의 설정, 로컬 환경설정을 합친 뒤 코어에 전달할 수 있습니다. 원본 파일이 테스트를 통과해도 실행 중인 설정에 같은 규칙이 포함됐다는 뜻은 아닙니다. 현재 활성화된 설정과 클라이언트에서 확인할 수 있는 병합 결과를 살펴보세요. 다시 불러온 뒤 모드, 포트, 정책 그룹 선택을 확인합니다.
  3. 먼저 연결 포트를 확인한 다음 아웃바운드 경로를 추적하세요. 이 문서의 포트 예시는 curl --proxy http://127.0.0.1:7890 https://example.org/ 명령으로 테스트할 수 있습니다. 프록시 포트에 연결할 수 없다면 먼저 리스너가 실행 중인지, 포트가 다른 프로세스에 사용 중인지 확인하세요. 연결이 로그에 표시되면 대상 도메인, 일치한 규칙, 최종 아웃바운드를 확인합니다. 규칙은 제대로 일치했는데 요청이 실패한다면 DNS 업스트림, 선택된 아웃바운드 또는 대상 서비스를 점검하세요.

한 번에 하나의 설정만 바꾸세요. 먼저 DIRECT, REJECT와 서로 구분되는 도메인 조건 두 개로 규칙을 확인한 다음 구독 노드와 원격 규칙 집합을 단계적으로 적용하세요. 이렇게 하면 문제가 생겼을 때 로컬 연결 지점, 설정 병합, 규칙 데이터, 특정 아웃바운드 중 어디에서 발생했는지 구분하기 쉽습니다.

Clash 다운로드