Clash YAML 설정 파일 구조 해설: port·dns·proxies부터 rules까지

파일 종류부터 확인하기: 설정 파일, 구독, 클라이언트 설정

Clash 설정 파일은 보통 YAML 텍스트이며, 파일명은 config.yaml인 경우가 많습니다. 로컬 수신 포트와 DNS, 프록시 노드, 정책 그룹, 트래픽 분기 규칙을 정의하며, 클라이언트가 파일을 읽은 뒤 사용하는 코어가 각 항목을 해석합니다. 구독 링크는 설정을 가져오는 한 가지 방법입니다. 클라이언트가 링크에 요청을 보내고 응답 내용을 저장한 다음, 지정된 주기에 따라 업데이트합니다. 구독 주소 자체는 proxies 노드가 아니며, rules에 규칙으로 직접 넣을 수도 없습니다.

먼저 클라이언트에서 현재 선택된 Profile이 무엇인지 확인한 뒤 수정 여부를 결정하세요. 클라이언트에 설정을 여러 개 저장할 수 있지만, 보통 실행 중에는 선택된 설정 하나만 사용합니다. 구독으로 생성된 파일을 직접 수정하면 다음 업데이트 때 변경 사항이 덮어써질 수 있습니다. 수정 내용을 계속 유지하려면 클라이언트의 오버라이드 기능을 사용하거나 직접 관리할 수 있는 로컬 설정 파일을 사용하세요. 오버라이드 메뉴는 클라이언트마다 다르므로 저장하기 전에 원본 파일과 구독 복사본 중 어느 쪽에 적용되는지 확인해야 합니다.

수정하기 전에 원본 설정 파일을 복사해 두세요. 수정한 뒤에는 YAML 파일을 클라이언트에서 불러올 수 있는지 확인하고, 정책 그룹과 규칙이 예상대로 작동하는지도 점검하세요. 설정을 가져오는 데 성공하는 것과 요청이 올바른 경로로 나가는 것은 별개입니다.

기본 항목: port, mixed-port, 실행 모드

최상위 항목은 줄 맨 앞에서 시작합니다. port는 로컬 HTTP 프록시 수신 포트이고, socks-port는 로컬 SOCKS5 프록시 수신 포트입니다. mixed-port는 하나의 포트에서 HTTP와 SOCKS5 프록시 연결을 모두 받습니다. 아래 예시에서는 혼합 포트 7890을 사용합니다. 수동 프록시 설정을 지원하는 앱에 127.0.0.1:7890을 입력하면 됩니다. 이 포트는 기기에서 연결을 받는 입구이며 원격 노드의 포트가 아닙니다.

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

allow-lan: false는 다른 기기가 로컬 네트워크를 통해 이 기기의 프록시를 사용하지 못하게 한다는 뜻입니다. 프록시를 공유하려면 클라이언트의 수신 주소와 시스템 권한, 연결된 네트워크도 확인해야 합니다. 스위치 하나만 바꾸는 것으로는 충분하지 않습니다. mode: rule은 rules에 따라 트래픽을 보냅니다. global은 보통 모든 요청을 선택된 정책으로 보내고, direct는 프록시를 거치지 않고 연결합니다. 모드 전환은 문제를 진단할 때 유용하지만, 올바른 규칙과 노드 설정을 대신하지는 않습니다.

iPhone에서는 ‘로컬 프록시 포트’와 ‘시스템 트래픽 처리’를 구분해야 합니다. 클라이언트에서 VPN 구성을 만들거나 TUN을 활성화하면 시스템 네트워크 확장을 통해 일부 트래픽이 코어로 전달될 수 있으므로, 모든 앱에 7890을 수동으로 입력할 필요는 없습니다. 어떤 요청이 처리되는지는 클라이언트와 시스템 권한, 네트워크 설정에 따라 달라집니다. 설정 파일의 tun 항목을 모든 iOS 클라이언트가 지원하는 것도 아닙니다. 데스크톱용 TUN 예제를 휴대폰 설정에 그대로 붙여 넣지 마세요.

DNS 항목: DNS 응답이 규칙 판정에 반영되는 방식

dns는 중첩 객체입니다. enable은 코어의 DNS 기능을 켜고 끄며, nameserver에는 상위 DNS 서버를 지정합니다. fake-ip를 사용하면 코어가 해당 도메인에 예약된 IP 주소를 응답하고, 도메인과 IP 주소의 매핑을 관리합니다. 이후 연결이 이 매핑과 일치하면 코어는 원래 도메인을 확인해 도메인 규칙을 적용할 수 있습니다. 웹사이트의 실제 주소를 예약된 주소로 영구 변경하는 기능은 아닙니다.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
  fake-ip-filter:
    - "*.lan"

198.18.0.1/16은 예시에 사용된 Fake-IP 주소 대역이며, 직접 접속할 수 있는 웹사이트 주소가 아닙니다. fake-ip-filter를 사용하면 특정 도메인이 Fake-IP 매핑을 거치지 않도록 설정할 수 있습니다. 로컬 네트워크 기기 이름이 작동하지 않거나 실제 DNS 응답에 의존하는 서비스에 문제가 생기면, 먼저 해당 도메인만 대상으로 시험한 뒤 필터에 추가할지 결정하세요. 필터 범위가 넓을수록 어떤 설정이 결과를 바꿨는지 파악하기 어려워집니다. 상위 DNS 서버는 실제 네트워크 환경에 맞춰 선택해야 합니다. 서버에 연결할 수 없으면 프록시 노드에 연결하기도 전에 웹페이지가 DNS 조회 단계에서 멈출 수 있습니다.

‘도메인 규칙이 적용되지 않는다’면 먼저 요청에 규칙 매칭에 필요한 도메인 정보가 남아 있는지, 클라이언트가 이 설정의 DNS를 사용하는지 확인하세요. 일부 앱은 IP 주소로 직접 연결하거나 자체 DNS 조회 방식을 사용합니다. nameserver만 바꿔도 모든 요청이 DOMAIN-SUFFIX 규칙과 일치하는 것은 아닙니다. Fake-IP와 redir-host의 차이를 더 알아보려면 기술 참고 자료에서 현재 클라이언트가 지원하는 항목을 확인하세요.

proxies와 proxy-groups: 노드와 선택 그룹은 따로 설정하기

proxies는 개별 프록시 노드 목록입니다. 각 항목에는 프로토콜에 맞는 이름과 유형, 서버 주소, 포트가 필요합니다. 인증, 암호화, 전송 방식 항목은 프로토콜에 따라 달라집니다. 아래 예시는 구조를 보여주기 위해 문서용 도메인 proxy.example.net을 사용하므로 실제로 연결할 수 있는 노드 주소가 아닙니다. 실제 설정에는 서비스 제공자가 안내한 값을 사용하고, 노드 이름만 보고 프로토콜을 추측하지 마세요.

proxies:
  - name: "직접 설정한 SOCKS5"
    type: socks5
    server: proxy.example.net
    port: 1080

proxy-groups:
  - name: "노드 선택"
    type: select
    proxies:
      - "직접 설정한 SOCKS5"
      - DIRECT

proxies라는 이름이 두 번 나오지만 계층이 다릅니다. 줄 맨 앞의 proxies는 노드를 정의하고, proxy-groups 항목 아래 들여쓴 proxies는 해당 정책 그룹에서 선택할 수 있는 출구를 나열합니다. select는 직접 선택하는 그룹이며, 클라이언트의 정책 화면에 선택 항목이 표시되는 경우가 많습니다. DIRECT는 내장된 직접 연결 대상이므로 같은 이름의 프록시 노드를 따로 만들 필요가 없습니다. 그룹 이름과 노드 이름은 참조에 사용되므로 규칙에 적을 때 완전히 일치해야 합니다.

구독 설정에서는 proxy-providers로 노드를 가져온 다음 정책 그룹에서 provider를 참조하기도 합니다. 이는 노드를 최상위 proxies에 하나씩 직접 나열하는 방식과 다릅니다. ‘노드 목록이 비어 있음’ 문제를 확인할 때는 구독이 업데이트됐는지, provider가 정책 그룹에서 참조되는지, 현재 Profile이 방금 업데이트한 설정인지 각각 살펴보세요. 정책 그룹의 선택 목록이 비어 있다고 해서 바로 DNS 문제라고 판단하지 마세요.

rules: 위에서부터 순서대로 매칭, 출구도 반드시 존재해야 함

rules는 순서가 있는 목록입니다. 코어는 보통 위에서 아래로 규칙을 확인하고, 일치하는 항목을 찾으면 해당 항목에 지정된 출구를 사용합니다. 따라서 범위가 좁은 도메인 규칙은 일반적으로 범위가 넓은 지역 규칙보다 앞에 두고, 기본 규칙은 마지막에 둡니다. 아래 예시의 노드 선택은 앞에서 정의한 정책 그룹 이름과 일치해야 합니다.

rules:
  - DOMAIN-SUFFIX,example.org,노드 선택
  - GEOIP,CN,DIRECT
  - MATCH,노드 선택

DOMAIN-SUFFIX는 지정한 도메인과 그 하위 도메인을 매칭합니다. GEOIP,CN,DIRECT는 대상 IP의 지리 정보로 판단하는 규칙이며, ‘이 앱은 중국 본토 앱이다’라는 조건과는 다릅니다. MATCH는 앞선 규칙에 일치하지 않은 요청에 적용됩니다. MATCH를 첫 줄에 두면 보통 뒤쪽 규칙은 확인되지 않습니다. 범위가 넓은 규칙을 앞에 두어도 더 구체적인 도메인 규칙이 가려질 수 있습니다.

규칙에 일치했는데도 페이지가 열리지 않는다고 해서 규칙 문법이 반드시 잘못된 것은 아닙니다. 먼저 클라이언트의 연결 기록에서 요청이 어떤 규칙에 일치했고 어떤 정책 그룹으로 전달됐는지 확인한 다음, 그룹에서 노드와 DIRECT 중 무엇을 선택했는지 살펴보세요. 대상에 IP 주소로 직접 연결하면 도메인 규칙의 매칭 조건이 없을 수 있습니다. REJECT를 사용하면 프록시를 시도하는 대신 요청이 차단됩니다. 관련 용어의 차이는 용어집에서 확인하세요.

들여쓰기, 순서, 저장: 한 번에 하나씩 수정하기

YAML은 들여쓰기로 계층을 표현합니다. 최상위의 dns:, proxies:, proxy-groups:, rules:는 모두 줄 맨 앞에서 시작합니다. 그 아래 객체의 항목은 더 들여쓰고, 목록 항목은 하이픈과 공백으로 표시합니다. 공백만 사용하고 탭은 섞지 않는 것이 좋습니다. 콜론이나 샵 기호가 포함되거나 앞뒤에 공백이 있는 이름은 YAML 문법으로 해석되지 않도록 따옴표로 감쌀 수 있습니다. 대소문자도 중요합니다. DIRECT와 직접 지정한 Direct는 서로 다른 참조입니다.

증상	우선 확인할 항목	해결 방법
설정을 불러올 수 없음	오류가 난 줄 주변의 들여쓰기, 콜론, 목록 하이픈	가장 최근 변경을 되돌린 뒤 항목을 하나씩 추가
규칙에서 참조한 대상을 찾을 수 없음	규칙 끝의 이름과 정책 그룹 이름	이름을 일치시키고 대소문자 확인
정책 그룹에서 선택할 노드가 없음	그룹 안의 노드 이름 또는 provider 참조	노드가 불러와졌는지 확인한 뒤 그룹의 선택 목록 점검
수정 사항이 다시 원래대로 돌아감	현재 Profile의 출처와 구독 업데이트 기록	변경 내용이 유지되는 오버라이드나 로컬 설정 사용

안전하게 수정하려면 먼저 원본 파일을 백업하고, 한 번에 항목 하나 또는 규칙 하나만 바꾸세요. 저장한 뒤 클라이언트에서 설정을 다시 불러오고, 파싱 오류가 없는지 확인한 다음, 목적이 분명한 도메인으로 연결 기록을 점검합니다. 예를 들어 DOMAIN-SUFFIX,example.org,노드 선택을 수정했다면 해당 도메인 범위의 요청을 테스트하고 기록에 예상한 정책 그룹이 표시되는지 확인하세요. 한 항목을 확인한 뒤 다음 항목을 수정하면 문제가 생겼을 때 원인을 빠르게 찾을 수 있습니다.

YAML 파싱에 성공해도 현재 코어가 모든 항목을 인식한다는 뜻은 아닙니다. Clash, Clash Meta(mihomo), 각 클라이언트에서 지원하는 설정 항목은 완전히 같지 않습니다. 다른 기기에서 설정을 복사했다면 먼저 클라이언트가 사용하는 코어와 지원 범위를 확인하세요. iPhone에서는 특히 시스템 네트워크 확장 권한, Profile 선택, 설정 문법, 실제 트래픽 출구를 각각 나눠 점검해야 합니다. 이 네 가지를 차례로 확인하면 파일 전체를 한꺼번에 바꾸는 것보다 문제를 쉽게 찾을 수 있습니다.