CONFIGURATION REFERENCE

Clash 설정 파일완벽 가이드

YAML 최상위 구조부터 시작해 포트, 실행 모드, DNS, 프록시 노드, 프록시 그룹, 규칙 세트, 오버라이드와 병합을 단계별로 설명합니다. 구독을 가져온 뒤 설정을 확인하거나 mihomo 설정 파일을 직접 관리할 때 유용합니다.

목표가 최초 연결뿐이라면 먼저 시작하기에 따라 구독 가져오기, 모드 선택, 시스템 프록시 설정을 순서대로 완료하세요. 이 페이지에서는 빠른 시작 과정을 반복하지 않고, 설정 파일을 참고용 기술 매뉴얼로 다루며 각 필드를 코어가 어떻게 읽는지와 여러 필드의 조합이 어떤 결과를 만드는지 설명합니다.

클라이언트를 설치해야 한다면 클라이언트 다운로드에서 플랫폼을 선택하세요. 데스크톱과 모바일에서는 Clash Plus를 우선 사용하고, 코어를 직접 실행해야 하는 서버나 라우터에서는 mihomo 코어 패키지를 고려하세요. 실행, 권한 또는 포트 충돌이 발생하면 FAQ클라이언트 시작 충돌 문제 해결도 함께 확인하세요.

1. YAML 구조와 설정 읽기 순서

Clash 설정 파일은 키, 값, 목록, 매핑으로 이루어진 데이터 트리입니다. 최상위에는 일반적으로 포트, 실행 모드, 로그 수준, DNS, 프록시 노드, 프록시 그룹과 규칙이 포함됩니다. 코어는 시작할 때 먼저 YAML 문법을 해석하고 필드 형식을 검증한 다음 수신 포트, DNS 모듈과 아웃바운드 프록시를 초기화하고 마지막으로 규칙을 불러옵니다. 앞 단계의 문법 해석이 실패하면 이후 노드와 규칙은 실행 상태가 되지 않으므로, 문제를 해결할 때는 먼저 파일 전체가 정상적으로 해석되는지 확인한 뒤 특정 규칙의 일치 여부를 살펴봐야 합니다.

YAML은 들여쓰기로 계층을 표현하므로 두 칸 들여쓰기를 일관되게 사용하고 탭을 섞지 않는 것이 좋습니다. 콜론 뒤에는 보통 공백을 하나 둡니다. 목록 항목은 하이픈으로 시작하며, 콜론·샵·중괄호·특수 공백이 포함된 텍스트는 따옴표로 감싸는 편이 안전합니다. 따옴표로 감싸지 않은 샵은 주석을 뜻하며 뒤의 내용은 해석되지 않습니다. 불리언 값은 true 또는 false를 사용하고, 포트 같은 숫자를 따옴표가 붙은 텍스트로 잘못 입력하지 마세요. 클라이언트마다 저장할 때 필드 순서를 다시 정렬할 수 있지만 계층과 형식이 같다면 순서는 대개 최상위 필드의 의미에 영향을 주지 않습니다.

최소 구조 확장하기

이해하기 쉬운 설정은 수신 포트, 모드, 노드, 프록시 그룹, 규칙의 다섯 부분에서 시작할 수 있습니다. 아래 예제는 구조 관계만 보여줍니다. 노드는 먼저 proxies에 정의하고, 프록시 그룹은 노드 이름을 참조하며, 규칙은 마지막으로 트래픽을 프록시 그룹에 전달합니다. 참조 이름은 대소문자, 공백, 기호를 포함해 한 글자도 다르지 않아야 합니다. 규칙이 존재하지 않는 프록시 그룹을 가리키면 코어는 대개 검증 단계에서 대상을 찾을 수 없다고 보고합니다.

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

proxies:
  - name: "example-node"
    type: socks5
    server: 192.0.2.10
    port: 1080

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - example-node
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,수동 선택
  - MATCH,DIRECT

예제의 주소는 문서 설명용이며 실제 연결에는 구독에서 제공한 서버 정보를 사용해야 합니다. 노드를 직접 작성할 때는 먼저 프로토콜 종류와 필수 필드를 확인한 다음 해당 프로토콜 전용 매개변수를 추가하세요. 구독으로 생성된 설정은 DNS, 스니핑, 규칙 세트와 여러 프록시 그룹까지 포함하므로 훨씬 길 수 있습니다. 읽을 때 첫 줄부터 끝까지 무작정 따라가기보다 최상위 키를 찾은 뒤 “규칙 대상 → 프록시 그룹 → 노드” 참조 사슬을 따라가면 됩니다.

앵커, 별칭과 중복 키

YAML의 앵커와 별칭은 매개변수 묶음을 재사용할 때 유용하지만, 모든 클라이언트의 시각적 편집기가 이 문법을 완전히 보존하는 것은 아닙니다. 구독 변환, 그래픽 인터페이스 저장 또는 원격 오버라이드를 거치면 앵커가 일반 필드로 펼쳐질 수 있습니다. 여러 클라이언트에서 설정을 자주 옮겨야 한다면 필드를 직접 명시하는 편이 더 안정적입니다. 또 다른 흔한 문제는 중복 키입니다. 같은 매핑 계층에 mode 또는 dns가 두 번 나타나면 파서가 뒤의 값을 사용할 수도 있고 아예 거부할 수도 있습니다. 덮어쓰기 동작에 의존하지 말고 병합 전에 최상위 중복 키를 제거하세요.

파일 인코딩은 UTF-8을 사용하는 것이 좋습니다. 프록시 그룹과 노드 이름에 한국어를 사용할 수 있지만 외부 스크립트로 설정을 처리할 때는 짧은 영문 이름이 매칭에 편리합니다. 줄바꿈 형식은 일반적으로 해석에 영향을 주지 않지만, 웹페이지나 메신저에서 설정을 복사하면 전각 콜론, 굽은 따옴표, 보이지 않는 공백이 섞이기 쉽습니다. “매핑 값을 여기에 사용할 수 없습니다”와 같은 오류가 보이면 전체 설정을 바로 삭제하지 말고 오류가 난 줄과 그 바로 앞줄의 들여쓰기, 콜론, 따옴표 닫힘을 먼저 확인하세요.

2. 공통 필드, 수신 포트와 실행 모드

공통 필드는 코어가 로컬 또는 LAN 트래픽을 어떻게 받고 실행 정보를 어떻게 출력할지 결정합니다. 가장 흔한 진입점은 mixed-port로, 하나의 포트에서 HTTP와 SOCKS 프록시 요청을 모두 받아 브라우저, 터미널, 시스템 프록시를 함께 사용하기 편합니다. portsocks-port를 따로 설정할 수도 있지만 포트 관리가 복잡해집니다. 클라이언트 화면에 표시되는 “시스템 프록시 포트”는 보통 이 필드에서 가져오므로 파일을 수정한 뒤 그래픽 클라이언트의 자체 설정이 다시 덮어쓰지 않는지도 확인해야 합니다.

allow-lan은 다른 기기가 현재 기기의 프록시 포트로 접속할 수 있는지 제어합니다. false는 단일 기기 사용에 적합하고, true로 설정했다면 bind-address와 함께 사용해 수신 범위를 제한하고 운영체제 방화벽도 확인해야 합니다. LAN 연결을 허용한다고 해서 인증이 자동으로 설정되거나 라우터가 트래픽을 해당 포트로 전달하는 것은 아닙니다. 휴대폰과 컴퓨터에서 각각 클라이언트를 실행하는 정도라면 LAN 수신을 켤 필요가 없습니다.

필드일반적인 값용도 및 주의사항
mixed-port1024~65535 범위의 사용 중이지 않은 포트HTTP와 SOCKS 연결을 동시에 수락하며, 변경 후 시스템 프록시 설정도 함께 확인합니다.
moderuleglobaldirect트래픽을 규칙, 전체 프록시 또는 직접 연결 중 어떤 방식으로 처리할지 결정합니다.
log-levelinfowarningerrordebug평소에는 info를 유지하고, 문제 해결 시 잠시 debug를 활성화한 뒤 완료 후 복원합니다.
ipv6true 또는 false코어 관련 모듈이 IPv6를 처리할지 제어하며, 시스템 네트워크와 DNS 설정의 영향도 받습니다.
external-controller루프백 주소와 포트그래픽 인터페이스나 제어 패널에 제어 인터페이스를 제공하며, 공용 네트워크에 함부로 노출해서는 안 됩니다.

규칙, 전체 및 직접 연결 모드

rule은 일상적으로 가장 많이 사용하는 모드입니다. 코어는 rules를 위에서부터 확인하고 일치하면 해당 프록시 그룹이나 아웃바운드로 연결을 넘깁니다. global은 개별 규칙 판단을 건너뛰고 트래픽을 전체 프록시 정책으로 통일하므로 특정 노드의 사용 가능 여부를 임시로 확인할 때 적합하지만 규칙의 정확성을 판단하는 기준으로는 적절하지 않습니다. direct는 트래픽을 직접 연결해 문제가 프록시 경로에 있는지 로컬 네트워크에 있는지 빠르게 구분할 때 사용할 수 있습니다. 모드 전환은 라우팅 결정만 바꾸며 DNS, 인증서, 권한 또는 시스템 프록시 미활성화 문제를 자동으로 해결하지는 않습니다.

그래픽 클라이언트의 “규칙, 전체, 직접 연결” 버튼은 보통 제어 인터페이스를 통해 실행 상태를 바꾸며 원본 YAML을 반드시 수정하는 것은 아닙니다. 재시작 후 어떤 모드를 사용할지는 클라이언트가 실행 상태를 저장하는지와 설정의 mode에 따라 달라집니다. “재시작하면 모드가 되돌아간다”면 설정 파일, 클라이언트 설정, 구독 업데이트 동작을 함께 확인하세요. 구독은 업데이트 때마다 원본 파일을 교체할 수 있으므로 구독 파일에서 공통 필드를 직접 수정하면 다음 업데이트에서 사라지기 쉽습니다. 클라이언트가 제공하는 오버라이드 기능을 사용하는 편이 좋습니다.

시스템 프록시와 TUN의 경계

수신 포트는 코어가 프록시 요청을 받을 준비가 되었다는 뜻일 뿐, 모든 애플리케이션이 자동으로 트래픽을 그곳으로 보내는 것은 아닙니다. 시스템 프록시는 운영체제가 공개하는 프록시 주소이며 이 설정을 읽는 앱만 사용합니다. TUN 모드는 가상 네트워크 인터페이스를 통해 더 넓은 범위의 IP 트래픽을 가로챕니다. 두 방식은 같은 규칙과 프록시 그룹을 사용할 수 있지만 트래픽 유입 경로가 다릅니다. 가로채기 범위, 호환성 및 문제 해결 차이는 TUN 모드와 시스템 프록시의 작동 방식 비교에서 확인하세요.

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090

위 예제는 제어 인터페이스를 루프백 주소로 제한해 로컬 그래픽 클라이언트가 호출하기에 적합하게 구성했습니다. allow-lanfalse여도 각 수신 주소의 용도를 명확히 이해하는 것이 좋습니다. 포트 충돌이 발생하면 중복 실행 중인 클라이언트를 먼저 종료하거나 포트를 변경한 뒤 시스템 프록시가 새 포트를 가리키는지 확인하세요. YAML만 바꾸고 시스템 프록시를 갱신하지 않으면 코어는 정상적으로 실행되지만 브라우저는 연결하지 못하는 상황이 생깁니다.

3. DNS 설정과 도메인 해석 경로

DNS는 Clash 설정에서 가장 쉽게 오해하는 부분입니다. 도메인에 접속할 때 앱이 직접 해석할 수도 있고 도메인을 프록시 프로토콜에 넘길 수도 있습니다. 시스템 DNS, 브라우저 보안 DNS, Clash DNS 모듈, 원격 프록시가 모두 관여할 수 있습니다. 설정의 dns.enable은 코어 DNS 모듈의 활성화 여부만 제어하며 모든 앱이 해당 모듈로 질의를 보내도록 보장하지 않습니다. 시스템 프록시를 사용할 때도 일부 앱은 자체 해석 경로를 사용합니다. TUN을 사용하면 대체로 통합 가로채기가 쉽지만 DNS 하이재킹과 시스템 권한에도 좌우됩니다.

nameserver는 주요 해석 서버 목록이고 default-nameserver는 DNS 서버 자체의 도메인을 해석해 “해석기를 먼저 해석해야 하는” 순환 의존을 피하는 데 사용합니다. nameserver에 IP를 직접 입력하면 의존성이 줄어듭니다. 암호화 DNS의 도메인을 입력한다면 default-nameserver에 직접 접근 가능한 기본 해석 주소를 제공해야 합니다. fallback과 관련 필터 필드는 복잡한 해석 분기에 적합하지만, 동작 원리를 모른 채 기계적으로 덧붙이면 안 됩니다. 해석 경로가 많아질수록 결과를 예측하기 어려워집니다.

redir-host와 fake-ip

enhanced-mode의 대표적인 값은 redir-hostfake-ip입니다. redir-host는 실제 해석 결과를 유지해 이해하기 쉽지만 투명 프록시 환경에서는 순수 IP 트래픽에서 도메인을 복원하기 어려울 수 있습니다. fake-ip는 도메인에 예약 주소 풀의 임시 주소를 반환하고, 코어가 이를 바탕으로 도메인과 연결을 매핑한 뒤 도메인 규칙을 적용합니다. 실제 대상에 임시 주소로 연결하는 것이 아니라 매핑을 이용해 라우팅하는 방식입니다. fake-ip는 규칙 매칭과 투명 가로채기에 대체로 유리하지만 일부 LAN 서비스, 기기 검색, 게임 플랫폼 또는 실제 IP에 의존하는 앱은 필터 목록에 추가해야 합니다.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 1.1.1.1
    - 8.8.8.8
  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "+.stun.*.*"
    - "+.stun.*.*.*"

예제는 필드 관계만 보여줄 뿐 모든 네트워크 환경에서 같은 해석 서비스를 사용해야 한다는 뜻은 아닙니다. 회사, 학교 또는 가정 네트워크가 내부 도메인에 로컬 DNS를 필요로 할 수 있으므로 LAN 해석 경로를 유지하거나 내부 도메인에 전용 nameserver-policy를 설정해야 합니다. fake-ip-range는 약속된 예약 주소 대역을 사용하고 가정용 LAN, VPN 또는 컨테이너 네트워크가 사용하는 대역과 겹치지 않게 하세요. LAN 기기에 접속할 수 없거나 프린터 검색이 비정상적이거나 게임 로그인이 실패한다면 전체 DNS 모듈을 끄기보다 해당 도메인이 fake-ip-filter에 들어가야 하는지 먼저 확인하세요.

도메인별 해석기 선택

nameserver-policy를 사용하면 특정 도메인이 지정된 해석기를 이용하도록 할 수 있습니다. 예를 들어 내부 도메인은 라우터로, 로컬 도메인은 LAN DNS로, 나머지는 주요 nameserver로 보낼 수 있습니다. 이는 “누가 해석하는가”를 정하는 기능이고, 규칙의 DOMAIN-SUFFIX는 “어디로 연결을 내보내는가”를 정하므로 서로 다른 단계입니다. 해석기 선택이 올바르다고 해서 이후 연결이 반드시 해당 정책을 따르는 것은 아닙니다. 반대로 프록시 규칙이 정확해도 잘못된 주소를 반환한 DNS 결과를 고칠 수는 없습니다.

dns:
  enable: true
  enhanced-mode: fake-ip
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://1.1.1.1/dns-query
  nameserver-policy:
    "+.home.arpa":
      - 192.168.1.1
    "+.internal.example":
      - 192.168.1.1

DNS를 점검할 때는 세 단계로 관찰할 수 있습니다. 먼저 시스템이나 앱이 질의를 어디로 보내는지 확인하고, 다음으로 Clash 로그에서 도메인과 규칙 매칭이 나타나는지 보고, 마지막으로 대상 연결이 어떤 정책을 거쳤는지 확인하세요. 브라우저에서 독립적인 보안 DNS를 사용하면 시스템 설정을 우회할 수 있습니다. 규칙이 IP-CIDR만 포함하는데 연결 로그에는 도메인이 남아 있다면 일치 순서가 예상과 달라질 수도 있습니다. DNS 모드, 규칙, 노드를 동시에 바꾸지 말고 한 번에 하나씩 변경해야 원인을 찾기 쉽습니다.

IPv6와 해석 결과

dns.ipv6는 DNS 모듈이 AAAA 결과를 반환할지 제어하고, 최상위 ipv6는 코어의 IPv6 전반적인 처리를 좌우합니다. 기기 네트워크가 IPv6를 지원하고, 해석기가 IPv6 주소를 반환하며, 프록시 노드에도 해당 기능이 있어야 연결이 원활하게 완료될 수 있습니다. 로컬 IPv6 경로가 불안정하면 앱이 AAAA 주소를 먼저 시도하다 시간 초과를 기다려 프록시 속도가 느려진 것처럼 보일 수 있습니다. 네트워크 조건을 확인한 뒤 활성화 여부를 결정하고, 스위치를 고정된 정답처럼 사용하지 마세요.

4. 프록시 노드 필드와 프로토콜 매개변수

proxies는 정적 노드 목록입니다. 각 항목에는 최소한 이름, 프로토콜 종류, 서버 주소와 포트가 포함되며 나머지 필드는 프로토콜에 따라 달라집니다. 구독에는 보통 완전한 노드가 이미 생성되어 있으므로 직접 관리할 때 이름만 보고 프로토콜 매개변수를 추측하지 마세요. 같은 서버가 여러 프로토콜 진입점을 제공할 수 있지만 인증 방식, 전송 계층과 TLS 설정은 서로 호환되지 않습니다. 코어 검증을 통과했다는 것은 필드 형식을 받아들일 수 있다는 뜻일 뿐 원격 서비스에 실제로 도달할 수 있다는 의미는 아닙니다.

name은 설정 내부에서 사용하는 참조 키이자 클라이언트 프록시 화면에 표시되는 텍스트입니다. 프록시 그룹이 노드를 참조할 때 이 이름을 사용해야 합니다. 이름이 중복되면 선택과 오버라이드가 어려워지므로 가져오는 단계에서 고유하게 유지하세요. server는 도메인이나 IP일 수 있으며 도메인을 사용하면 DNS 해석이 필요합니다. port는 정수여야 합니다. udp, skip-cert-verify, servername 같은 필드는 해당 프로토콜과 전송 조건에서 필요할 때만 사용하고, 한 노드의 매개변수 전체를 다른 프로토콜에 그대로 복사하지 마세요.

SOCKS 및 HTTP 상위 프록시

SOCKS5와 HTTP 노드는 기존 상위 프록시에 연결할 때 자주 사용합니다. 필드가 비교적 단순해 노드 구조를 이해하는 출발점으로 적합합니다. 상위 프록시가 인증을 요구하면 사용자 이름과 비밀번호를 입력하고, 필요하지 않다면 생략하세요. UDP 지원 여부는 프로토콜, 코어, 상위 서비스 세 요소의 기능에 따라 달라집니다. 문서 예제의 주소는 형식 설명용입니다.

proxies:
  - name: "office-socks"
    type: socks5
    server: 192.0.2.20
    port: 1080
    username: "example-user"
    password: "your-password"
    udp: false

  - name: "upstream-http"
    type: http
    server: 192.0.2.30
    port: 8080
    username: "example-user"
    password: "your-password"
    tls: false

비밀번호 같은 민감한 필드는 공개 저장소나 스크린샷에 넣지 않는 것이 좋습니다. 여러 기기에서 설정을 동기화해야 한다면 접근이 통제된 비공개 채널을 사용하고 클라이언트 로그에 전체 인증 정보가 출력되지 않는지 확인하세요. 노드에 연결할 수 없을 때는 먼저 서버와 포트의 네트워크 도달성을 검증하고 인증과 전송 매개변수를 확인하세요. 처음부터 프록시 그룹이나 규칙을 수정하면 노드 문제와 라우팅 문제가 뒤섞입니다.

TLS, SNI와 인증서 검증

TLS를 사용하는 프로토콜은 올바른 서버 이름이 필요한 경우가 많습니다. servername 또는 유사한 SNI 필드는 핸드셰이크에서 원격 서버가 사용할 호스트 이름을 알려주며 server와 다를 수 있습니다. IP로 연결하지만 인증서가 도메인에 발급된 경우 올바른 SNI가 없으면 핸드셰이크가 실패합니다. skip-cert-verify는 인증서 검증을 건너뛰므로 모든 TLS 오류를 처리하는 범용 스위치로 사용해서는 안 됩니다. 시스템 시간, 서버 이름, 인증서 체인과 중간 네트워크를 확인하는 편이 더 적절합니다. 구독 제공자가 이 필드를 명확히 안내한 경우 실제 환경과 함께 판단하세요.

WebSocket, gRPC 등의 전송 계층에는 경로, 호스트 헤더 또는 서비스 이름도 포함될 수 있습니다. YAML 계층은 프로토콜이 요구하는 위치에 배치해야 합니다. 예를 들어 ws-opts 아래에 pathheaders를 둡니다. 필드를 잘못된 계층에 넣으면 일부 파서가 알 수 없는 키를 무시해 설정은 로드되지만 핸드셰이크 매개변수가 빠질 수 있습니다. 이런 경우에는 클라이언트에 노드 이름이 나타나는지만 보지 말고 코어 로그와 프로토콜 필드 설명을 대조하세요.

proxies:
  - name: "example-tls-node"
    type: trojan
    server: edge.example.net
    port: 443
    password: "your-password"
    sni: edge.example.net
    udp: true
    skip-cert-verify: false
    network: ws
    ws-opts:
      path: /gateway
      headers:
        Host: edge.example.net

노드 제공기와 정적 노드의 차이

정적 proxies는 노드를 주 설정에 직접 작성해 단일 파일로 읽기 쉽습니다. proxy-providers는 로컬 파일이나 원격 리소스에서 노드 모음을 불러와 구독 업데이트와 여러 출처의 조합에 적합합니다. 프록시 그룹이 provider를 참조할 때는 use를 사용하고 정적 노드를 참조할 때는 proxies를 사용합니다. 두 방식을 함께 사용할 수 있지만 이름이 같은 노드, 업데이트 주기와 캐시 파일 경로를 주의해야 합니다. 클라이언트의 기본 구독 관리 기능이 보통 이 세부 사항을 처리하므로 일반 사용자가 “더 간결해 보인다”는 이유로 provider로 바꿀 필요는 없습니다.

Windows, macOS, Android, iOS, Linux 그래픽 클라이언트에서는 노드 매개변수를 보통 구독이 관리합니다. 우선 추천하는 Clash Plus와 Clash Verge Rev, FlClash, Clash Nyanpasu, Clash Meta for Android, ClashX Meta 등의 클라이언트는 설정을 표시하는 방식이 다를 수 있지만 기본 참조 관계는 비슷합니다. 플랫폼과 클라이언트의 용도를 비교하려면 클라이언트 비교로 이동하세요. 화면에 표시된 이름만 보고 특정 프로토콜 필드가 반드시 지원된다고 판단하지 마세요.

5. 프록시 그룹 유형과 조합 설계

프록시 그룹은 규칙과 노드 사이에 위치합니다. 규칙이 특정 노드 이름을 직접 작성하지 않고 “수동 선택”, “자동 선택”, “앱별 분기” 같은 프록시 그룹에 트래픽을 넘기면 그룹이 실제 아웃바운드를 결정합니다. 따라서 노드 목록을 업데이트해도 규칙을 다시 작성할 필요가 없고 클라이언트 화면에서 빠르게 전환할 수 있습니다. 프록시 그룹 설계의 핵심은 개수가 아니라 각 계층의 역할을 명확히 하는 것입니다. 최상위는 사용자 선택, 중간 계층은 자동 테스트나 장애 전환, 하위 계층은 노드와 DIRECT를 담당하게 하세요.

select는 가장 직관적인 유형으로 사용자가 선택한 노드나 하위 프록시 그룹을 사용합니다. 더 빠른 노드를 자동으로 고르지는 않습니다. url-test는 지정한 주소로 후보 노드를 주기적으로 테스트하고 결과가 더 적합한 항목을 선택합니다. 테스트는 지정 대상까지의 연결 상태만 반영하며 모든 웹사이트의 실제 체감 품질과 같지는 않습니다. fallback은 가용성을 중시해 현재 후보를 사용할 수 없을 때 다음 항목으로 전환합니다. load-balance는 정책에 따라 여러 노드에 연결을 분배하므로 로그인 세션, 출구 주소의 일관성, 위험 제어 판단에 영향을 줄 수 있어 기본 그룹으로 무작정 활성화하기에는 적합하지 않습니다.

그룹 유형선택 방식적합한 상황주요 한계
select사용자 수동 선택전체 진입점, 지역 선택, 임시 전환노드 품질을 자동으로 판단하지 않음
url-test주기적으로 테스트한 뒤 선택유사 노드의 자동 선택테스트 대상과 실제 서비스가 다를 수 있음
fallback사용할 수 없을 때 순서대로 전환연결 지속성이 중요한 상황전환 후 출구가 바뀔 수 있음
load-balance여러 노드에 연결 분배세션 영향에 대한 이해가 필요한 고급 상황단일 출구 주소를 보장하지 않음

2단 프록시 그룹의 일반적인 구조

실용적인 구조로는 최상위 “프록시 선택”에 select를 사용하고, 그룹 안에 “자동 선택”, 여러 지역 그룹과 DIRECT를 배치하는 방식이 있습니다. “자동 선택”은 다시 url-test를 사용해 구체적인 노드를 참조합니다. 규칙은 모두 최상위 그룹을 가리키므로 안정적으로 직접 제어하려면 노드를 선택하고, 편의성을 원하면 자동 그룹을 선택하면 됩니다. 두 프록시 그룹이 서로를 참조하게 하지 마세요. 순환이 발생합니다. 모든 규칙을 서로 다른 노드에 직접 연결하는 것도 피해야 합니다. 구독 업데이트 후 유지 관리 비용이 급격히 커집니다.

proxy-groups:
  - name: "프록시 선택"
    type: select
    proxies:
      - 자동 선택
      - 수동 노드
      - DIRECT

  - name: "자동 선택"
    type: url-test
    proxies:
      - node-a
      - node-b
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50

  - name: "수동 노드"
    type: select
    proxies:
      - node-a
      - node-b

interval은 테스트 간격을 뜻합니다. 너무 짧으면 요청과 기기 배터리 사용량이 늘고, 너무 길면 네트워크 변화를 제때 반영하지 못합니다. tolerance는 결과가 비슷할 때 잦은 전환을 줄이는 데 사용합니다. 테스트 주소는 안정적이고 응답 본문이 작으며 확인하려는 연결 경로를 대표해야 합니다. 클라이언트 화면의 테스트 결과는 참고 자료일 뿐이며 노드 혼잡, 대상 사이트 경로와 무선 네트워크 변화가 실제 접속에 영향을 줍니다.

filter로 provider 노드 관리하기

노드가 proxy-providers에서 제공된다면 use로 전체 provider를 참조하고 filter로 이름을 필터링할 수 있습니다. 필터는 보통 정규 표현식을 사용하므로 지역명이 약칭, 영문, 기호로 제각각 표시된다면 이를 모두 고려해야 합니다. 필터 결과가 비어 있으면 프록시 그룹에 후보가 사라지므로 변경 후 반드시 검증하세요. 지나치게 포괄적인 표현식을 작성하기보다 실제 노드 이름을 먼저 확인하고 매칭 분기를 단계적으로 늘리는 편이 좋습니다.

proxy-groups:
  - name: "지역 선택"
    type: select
    use:
      - primary-subscription
    filter: "(?i)Hong Kong|HK|홍콩"

  - name: "가용성 우선"
    type: fallback
    use:
      - primary-subscription
    url: "https://www.gstatic.com/generate_204"
    interval: 600

프록시 그룹 이름 자체가 규칙 대상이므로 이름 변경은 구조적인 변경입니다. “프록시”를 “프록시 선택”으로 바꾸었다면 rules, rule-providers의 대상과 다른 프록시 그룹의 참조도 함께 검색해야 합니다. 클라이언트가 이전 선택을 기억할 수 있으며 기존 노드가 사라지거나 그룹 내용이 바뀌면 실행 상태의 선택이 첫 번째 항목으로 돌아갈 수 있습니다. 여러 기기에 설정을 배포할 때는 첫 번째 항목을 우연히 앞에 놓인 단일 노드가 아니라 설명 가능하고 사용 가능한 기본 정책으로 두세요.

DIRECT와 REJECT의 위치

DIRECT는 직접 연결을 뜻하며 LAN, 신뢰할 수 있는 로컬 서비스 또는 로컬 출구를 사용하려는 대상에 적합합니다. REJECT는 연결을 거부하며 차단이 확인된 도메인이나 주소에 사용할 수 있습니다. 둘 다 규칙 대상에 직접 지정하거나 사용자가 임시로 선택하도록 select 그룹에 넣을 수 있습니다. 전체 프록시 그룹에 DIRECT를 넣으면 유연성이 높아지지만 원래 프록시를 사용해야 하는 규칙을 사용자가 일시적으로 직접 연결할 수도 있습니다. 유지 여부는 사용 목적에 따라 결정하세요.

6. 규칙 문법, 매칭 순서와 사용자 지정 규칙

rules는 순서가 있는 목록입니다. 연결이 들어오면 코어는 보통 첫 번째 규칙부터 판단하고 처음 일치한 결과를 즉시 적용하며 뒤의 규칙은 확인하지 않습니다. 따라서 “규칙 내용은 맞는데 효과가 없다”는 문제는 문법 오류가 아니라 앞에 더 포괄적인 규칙이 먼저 일치한 경우가 많습니다. 정확한 도메인, 특정 프로세스 또는 LAN 주소는 앞에 두고 범위가 넓은 도메인 접미사, IP 대역, 지역 규칙은 뒤에 배치하며 남은 트래픽은 마지막에 MATCH로 처리하세요.

기본 규칙은 규칙 유형, 매칭 내용, 대상 정책으로 구성되며 영문 쉼표로 구분합니다. 예를 들어 DOMAIN,api.example.com,프록시 선택은 완전한 도메인만 매칭하고, DOMAIN-SUFFIX,example.com,프록시 선택은 루트 도메인과 하위 도메인까지 포함합니다. DOMAIN-KEYWORD,example,프록시 선택은 범위가 더 넓어 키워드를 포함한 모든 도메인이 매칭될 수 있으므로 주의해야 합니다. 규칙 대상은 프록시 그룹, 노드, DIRECT 또는 REJECT일 수 있습니다.

도메인, IP와 프로세스 규칙

DOMAIN 계열 규칙은 코어가 도메인을 알고 있을 때 가장 명확합니다. IP-CIDR은 IPv4 네트워크 대역에, IP-CIDR6은 IPv6 네트워크 대역에 사용하며 대역은 CIDR 접두사로 표시합니다. IP 규칙은 도메인 해석을 유발할 수 있습니다. 이미 확보한 대상 IP만 사용하고 추가 해석을 원하지 않는다면 코어 지원 방식에 따라 no-resolve를 추가할 수 있습니다. GEOIP는 IP의 소속 지역에 따라 매칭하며 결과는 해당 데이터베이스에 좌우됩니다. PROCESS-NAME과 PROCESS-PATH는 운영체제가 제공하는 프로세스 정보에 의존하므로 플랫폼, 권한, TUN 구현에 따라 다르게 동작하며, 플랫폼을 가리지 않는 유일한 규칙 방식으로 사용하기에는 적합하지 않습니다.

rules:
  - DOMAIN,api.example.com,프록시 선택
  - DOMAIN-SUFFIX,example.org,프록시 선택
  - DOMAIN-KEYWORD,streaming,미디어 서비스
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - PROCESS-NAME,example-app.exe,프록시 선택
  - GEOIP,CN,DIRECT
  - MATCH,누락된 트래픽

위 예제는 순서와 형식만 보여줍니다. LAN 대역은 실제 네트워크에 맞게 조정하고, 프로세스 이름은 시스템 작업 정보에 따라 입력해야 합니다. MATCH는 마지막에 두어 앞에서 처리되지 않은 연결을 매칭하세요. MATCH를 중간에 배치하면 뒤의 규칙은 실행될 기회를 얻지 못합니다. 설정에 MATCH를 여러 개 넣어도 실질적인 의미가 없으므로 명확한 최종 출구 하나만 남기세요.

사용자 지정 규칙 삽입 방법

구독 설정이 업데이트될 때 원본 파일에 직접 추가한 규칙은 대개 덮어써집니다. 더 안정적인 방법은 클라이언트의 오버라이드, 확장 스크립트 또는 규칙 앞에 삽입하는 기능을 사용해 사용자 지정 규칙을 구독 규칙보다 앞에 넣는 것입니다. 앞에 삽입하는 방식은 특정 내부 도메인을 항상 직접 연결하는 것 같은 정확한 예외에 적합합니다. 뒤에 삽입하는 방식은 구독 마지막의 MATCH 전에 실행될 기회가 있는 규칙에만 적합합니다. 구독이 이미 MATCH로 끝난다면 새 규칙을 파일 끝에 단순히 추가해도 적용되지 않습니다.

사용자 지정 규칙을 설계할 때는 먼저 세 가지 질문에 답하세요. 매칭 대상이 도메인인가 IP인가, 대상이 기존 프록시 그룹인가 새 그룹인가, 어떤 기존 규칙을 덮어써야 하는가입니다. 하나의 호스트만 처리한다면 DOMAIN을 우선 사용하고, 한 사이트의 모든 하위 도메인을 처리한다면 DOMAIN-SUFFIX를 사용하세요. 이름 구조가 불안정할 때만 DOMAIN-KEYWORD를 고려하는 것이 좋습니다. 너무 넓은 키워드는 무관한 도메인까지 잘못 매칭할 수 있으며 짧은 단어, 브랜드 약칭, 일반 단어에서 특히 주의해야 합니다.

rules:
  - DOMAIN,printer.home.arpa,DIRECT
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - DOMAIN-SUFFIX,docs.example.net,프록시 선택
  - RULE-SET,private-network,DIRECT
  - RULE-SET,service-list,프록시 선택
  - MATCH,프록시 선택

규칙 매칭 로그 읽기

로그에는 보통 대상 도메인이나 IP, 매칭된 규칙 유형, 선택된 프록시 그룹, 최종 노드가 표시됩니다. 문제를 해결할 때는 재현 가능한 접속을 한 번 실행한 뒤 시간으로 해당 연결을 찾으세요. 규칙 대상은 맞지만 최종 노드가 다르면 프록시 그룹의 현재 선택을 확인합니다. MATCH가 매칭되었다면 예상한 규칙이 로드되었는지, 도메인이 일치하는지, 규칙 세트 업데이트가 성공했는지 앞쪽을 점검하세요. IP 규칙만 보이고 도메인 정보가 없다면 DNS와 스니핑 경로를 확인합니다.

브라우저에서 페이지를 한 번 열어도 메인 사이트, 이미지, 스크립트, 서드파티 API 등 여러 연결이 발생하므로 첫 번째 로그만 보고 전체 페이지의 라우팅을 판단해서는 안 됩니다. 명확한 도메인 하나를 선택해 테스트하거나 개발자 도구에서 실패한 요청의 호스트 이름을 확인하는 편이 좋습니다. 앱은 DNS를 캐시하거나 기존 연결을 유지할 수 있으므로 규칙을 수정한 뒤 새 연결을 만들고 필요하면 앱을 재시작하세요. 기존 세션이 모두 즉시 새 정책으로 전환된다고 가정하지 마세요.

규칙의 유지 관리성

규칙은 LAN, 개인 예외, 서비스 분기, 공용 규칙 세트, 최종 매칭처럼 용도별로 나누고 짧은 주석을 작성하세요. 필드의 의미를 반복하기보다 “왜 존재하는가”를 설명하는 주석이 더 유용합니다. 오랫동안 사용하지 않은 예외는 제때 삭제해야 나중에 여전히 필요한지 판단하기 쉽습니다. 규칙 대상은 자주 바뀌는 노드 이름보다 안정적인 프록시 그룹 이름을 참조하세요. 그러면 구독에서 노드가 추가되거나 삭제되어도 라우팅 계층을 함께 수정할 필요가 없습니다.

7. 규칙 세트, 노드 제공기와 외부 리소스

규칙이 많아지면 모든 내용을 rules에 넣어 주 설정을 유지하기 어려워집니다. rule-providers를 사용하면 로컬 파일이나 원격 주소에서 규칙 모음을 불러오고, 주 규칙에서는 RULE-SET으로 참조할 수 있습니다. 이는 규칙 내용의 구성과 업데이트를 해결하는 기능이지 대상 정책을 자동으로 결정하는 기능은 아닙니다. 같은 규칙 세트를 주 설정에서 서로 다른 프록시 그룹으로 연결할 수도 있습니다. 이와 비슷하게 proxy-providers는 노드 출처를 관리하고 프록시 그룹은 use로 참조합니다.

규칙 제공기에서 흔히 사용하는 동작 유형은 domain, ipcidr, classical입니다. domain은 순수 도메인 규칙에, ipcidr은 주소 대역에, classical은 더 완전한 규칙 표현을 담는 데 적합합니다. behavior는 파일 내용과 일치해야 합니다. DOMAIN-SUFFIX 형식의 클래식 규칙을 순수 domain 데이터로 읽으면 해석이 실패하거나 내용이 매칭되지 않을 수 있습니다. format은 yaml, text, mrs 같은 파일 형식을 설명하며 실제 지원 범위는 사용하는 코어를 기준으로 확인해야 합니다.

원격 규칙 세트의 전체 정의

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

  service-list:
    type: http
    behavior: classical
    format: yaml
    path: ./ruleset/service-list.yaml
    url: "https://rules.example.net/service-list.yaml"
    interval: 86400

rules:
  - RULE-SET,private-network,DIRECT
  - RULE-SET,service-list,프록시 선택
  - MATCH,프록시 선택

type: http는 원격에서 가져온다는 뜻이고, path는 로컬 캐시 위치, interval은 업데이트 간격입니다. 최초 로드에는 네트워크 접속이 필요합니다. 원격 업데이트에 실패하면 코어가 기존 캐시를 계속 사용하려고 하지만, 최초 다운로드에 실패했고 캐시도 없다면 규칙 내용을 가져올 수 없습니다. 경로가 속한 디렉터리에는 쓰기 권한이 필요합니다. 그래픽 클라이언트에서는 상대 경로가 사용자가 현재 터미널을 연 위치가 아니라 클라이언트의 설정 작업 디렉터리로 해석될 수도 있습니다.

원격 주소는 신뢰할 수 있고 지속적으로 관리되는 출처에서 가져와야 합니다. 규칙 업데이트는 트래픽 경로를 바꾸므로 단일 노드보다 영향 범위가 클 수 있습니다. 서드파티 규칙 세트를 사용하기 전에 분류 방식, 업데이트 주기, 기본 대상을 확인하고 이름만 보고 내용을 판단하지 마세요. 회사 내부 도메인이나 개인 예외에는 공용 목록에 등록되기를 기다리기보다 소량의 로컬 우선 규칙을 유지하는 편이 적합합니다.

규칙 세트 파일의 콘텐츠 형식

YAML payload 형식은 보통 payload를 최상위 키로 사용하고 그 아래에 규칙 항목을 둡니다. classical 동작의 항목에는 DOMAIN, DOMAIN-SUFFIX, IP-CIDR 같은 접두사가 포함될 수 있습니다. domain 동작은 일반적으로 도메인 패턴만 저장하고 ipcidr 동작은 네트워크 대역을 저장합니다. 서로 다른 형식을 임의로 섞어서는 안 되며 확장자가 format 선언을 대신할 수도 없습니다.

payload:
  - DOMAIN,api.example.com
  - DOMAIN-SUFFIX,example.org
  - IP-CIDR,203.0.113.0/24,no-resolve

주 설정에서 RULE-SET을 사용할 때 대상 정책은 참조하는 곳에 작성하므로 규칙 세트 내부에는 보통 “프록시 선택” 같은 대상이 다시 들어가지 않습니다. 이렇게 하면 같은 목록을 여러 설정에서 재사용할 수 있습니다. 다운로드한 파일 자체에 이미 세 부분으로 이루어진 완전한 규칙이 있다면 provider의 behavior와 코어 해석 방식이 일치하는지 확인하세요. “규칙 항목의 매개변수 개수가 올바르지 않습니다”라는 오류가 보이면 주 규칙의 프록시 그룹이 아니라 콘텐츠 형식을 먼저 점검해야 합니다.

노드 제공기, 상태 확인과 캐시

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

proxy-groups:
  - name: "구독 노드"
    type: select
    use:
      - primary-subscription
    proxies:
      - DIRECT

provider가 반환하는 내용은 완전한 Clash 설정이 아니라 노드 제공기에 필요한 구조여야 합니다. 완전한 설정 주소를 노드 provider로 직접 사용하면 최상위 구조가 달라 실패할 수 있습니다. 그래픽 클라이언트의 “구독”은 보통 완전한 설정 구독이며 proxy-providers와 같은 개념으로 단순히 볼 수 없습니다. 클라이언트가 이미 완전한 설정 업데이트를 담당한다면 별도로 provider를 중첩하지 말고 기존 클라이언트 흐름을 우선 사용하세요.

상태 확인은 provider의 노드에 테스트를 실행해 자동 그룹이 가용성을 판단하도록 돕지만, 빈도가 너무 높으면 리소스 사용량이 늘어납니다. 모바일 기기에서는 배터리와 백그라운드 제한도 고려해야 합니다. 테스트 실패가 모든 대상에 대해 노드가 사용할 수 없다는 뜻은 아닙니다. 테스트 주소가 차단되었거나 현재 네트워크에서 접근할 수 없는 경우일 수도 있습니다. 하나의 테스트 표시만 보고 노드를 삭제하지 말고 실제 연결 로그와 함께 판단하세요.

업데이트 실패의 단계별 점검

외부 리소스 실패는 다운로드, 쓰기, 해석, 참조의 네 단계로 나눌 수 있습니다. 다운로드 단계에서는 URL, DNS와 현재 아웃바운드를 확인하고, 쓰기 단계에서는 캐시 디렉터리 권한을 확인합니다. 해석 단계에서는 format, behavior와 파일 내용을 대조하고, 참조 단계에서는 RULE-SET 또는 use 이름이 최상위 정의와 일치하는지 확인하세요. 원격 규칙 업데이트도 현재 프록시를 거칠 수 있어 잘못된 분기가 “규칙을 다운로드하려면 규칙이 필요한” 의존성을 만들 수 있습니다. 설정 리소스 도메인에 명확한 경로를 지정하거나 최초 시작 시 사용할 수 있는 기본 연결을 확보하세요.

8. 오버라이드, 병합, 검증과 문제 해결

구독 설정은 주기적으로 업데이트해야 하지만 개인 설정은 오래 유지해야 하므로 오버라이드와 병합이 필요합니다. 구독으로 생성된 YAML을 직접 편집하는 방식은 가장 직관적이지만 업데이트 후 쉽게 교체됩니다. 사용자 지정 내용을 별도의 오버라이드 계층에 두면 “상위 노드와 공용 규칙” 및 “로컬 포트, DNS, 개인 규칙”을 각각 관리할 수 있습니다. 클라이언트마다 오버라이드의 명칭과 기능이 완전히 같지는 않으며 필드 덮어쓰기, 규칙 앞·뒤 삽입, 스크립트 처리, YAML 병합 등을 제공할 수 있습니다. 사용하기 전에 전체 필드를 교체하는지 매핑을 재귀적으로 병합하는지 먼저 확인하세요.

매핑은 키 단위의 재귀 병합에 적합하지만 목록은 가장 쉽게 의미가 엇갈립니다. dns 같은 매핑은 하위 키 하나를 오버라이드해도 다른 하위 키가 남을 수 있습니다. 반면 rules, proxies, proxy-groups 같은 목록은 도구에 따라 전체 교체되거나 앞에 삽입 또는 뒤에 추가될 수 있습니다. 목록이 자동으로 합쳐진다고 착각하면 구독의 기존 규칙이 모두 사라질 수 있고, 교체된다고 생각하면 같은 이름의 프록시 그룹이 두 개 남을 수 있습니다. 클라이언트의 동작 의미를 모르는 상태에서 많은 목록을 한 번에 오버라이드하지 마세요.

안전한 오버라이드 범위

공통 포트, 로그 수준, LAN 스위치와 일부 DNS 하위 항목은 보통 필드 오버라이드에 적합합니다. 개인 도메인 예외는 규칙 앞에 삽입하는 방식이 적합합니다. 새 프록시 그룹을 추가해야 한다면 그룹 정의, 참조 노드 출처, 규칙 대상을 함께 처리하고 하나의 완전한 변경으로 검증하는 것이 좋습니다. 노드 인증 매개변수는 자신의 정적 노드를 관리하는 경우가 아니라면 보통 구독에 맡기세요. 오버라이드 파일은 주 설정보다 짧게 유지하고 상위 설정과 다른 부분만 표현해야 합니다.

# 로컬 오버라이드 예시, 구체적인 병합 문법은 클라이언트에 따름
mixed-port: 7890
log-level: info
allow-lan: false

dns:
  enable: true
  ipv6: false

prepend-rules:
  - DOMAIN,printer.home.arpa,DIRECT
  - DOMAIN-SUFFIX,internal.example,DIRECT

prepend-rules는 표준 주 설정의 최상위 필드가 아니라 일부 오버라이드 도구에서 사용할 수 있는 표현 방식이므로 모든 클라이언트에 그대로 복사할 수 없습니다. 실제로는 클라이언트가 명확히 제공하는 “규칙 앞에 삽입” 기능을 사용해야 합니다. 이 예제의 핵심은 주 설정 필드와 오버라이드 지시어를 구분하는 것입니다. 전자는 코어가 읽고 후자는 클라이언트나 변환 도구가 먼저 처리하며, 처리된 최종 YAML이 코어에 전달됩니다.

병합 후 점검 목록

변경할 때마다 오버라이드 조각만 보지 말고 최종 생성된 설정을 먼저 확인하세요. 최상위에 중복 키가 없는지, 수신 포트가 충돌하지 않는지, DNS 계층이 완전한지, 노드와 프록시 그룹 이름이 고유한지, 모든 참조 대상이 존재하는지, 프록시 그룹에 순환이 없는지, 규칙 끝에 명확한 MATCH가 하나만 있는지 확인합니다. providers를 사용한다면 캐시 경로, 동작 유형과 참조 이름도 점검하세요. 설정 검증을 통과한 뒤 시작하거나 핫 리로드하세요.

문법 계층

들여쓰기, 콜론, 따옴표, 목록과 필드 형식이 모두 해석 가능하고 최상위 중복 키가 없습니다.

참조 계층

규칙 대상, 프록시 그룹 구성원, provider 이름이 한 글자씩 일치하며 순환 참조가 없습니다.

실행 계층

포트를 수신할 수 있고 제어 인터페이스 범위가 명확하며 캐시 디렉터리에 쓸 수 있고 DNS가 기본 해석을 수행합니다.

동작 계층

로그를 통해 규칙 매칭, 정책 선택과 최종 노드가 예상대로인지 확인합니다.

코어로 설정 검증하기

mihomo를 직접 실행하는 사용자는 코어가 제공하는 설정 테스트 매개변수를 사용해 서비스를 시작하기 전에 파일을 점검할 수 있습니다. 설치 방식에 따라 실행 파일 이름과 설정 디렉터리가 다르므로 예제의 실제 경로를 사용하세요. 그래픽 클라이언트도 보통 설정을 가져오거나 전환할 때 검증을 수행하고 로그 페이지에 오류가 난 줄을 표시합니다. 클라이언트 안내가 잘려 보이면 로그 페이지에서 전체 원인을 확인할 수 있습니다.

# 현재 디렉터리에서 config.yaml 검사
mihomo -t -f ./config.yaml

# 설정 작업 디렉터리를 지정한 뒤 검사
mihomo -t -d ./clash-profile -f ./clash-profile/config.yaml

검증 성공은 설정 구조와 알려진 필드가 요구 사항을 충족한다는 뜻일 뿐 원격 노드, 규칙 세트 또는 DNS 서비스가 반드시 정상이라는 의미는 아닙니다. 시작한 뒤 provider 업데이트, 포트 수신과 연결 로그도 관찰해야 합니다. 검증에서 특정 줄의 오류를 알리더라도 실제 원인은 따옴표가 닫히지 않았거나 상위 들여쓰기가 잘못된 것처럼 바로 앞줄에 있을 수 있습니다. 오류가 난 줄의 앞뒤 몇 줄을 먼저 살펴보고 범위를 단계적으로 좁히세요.

일반적인 장애의 처리 순서

“클라이언트가 열리지 않음”은 먼저 권한, 포트 점유, 설정 문법과 코어 파일을 점검하고 시작 충돌 및 강제 종료 해결 단계를 참고하세요. “클라이언트는 시작되지만 모든 연결이 실패함”은 시스템 프록시나 TUN이 실제로 활성화되었는지, 포트가 일치하는지, 노드를 사용할 수 있는지 확인해야 합니다. “일부 웹사이트의 경로가 잘못됨”은 DNS, 규칙 순서와 프록시 그룹의 현재 선택을 중점적으로 살펴보세요. “구독 업데이트 후 사용자 지정 내용이 사라짐”은 상위 파일을 수정했다는 뜻이므로 오버라이드 계층으로 옮겨야 합니다.

포트가 사용 중일 때 무작위 포트를 계속 시도하면서 시스템 프록시 동기화를 잊지 마세요. 먼저 점유 프로세스를 확인하고 중복 실행된 코어를 종료하거나 명확한 새 포트를 정한 뒤 모든 진입점 설정을 함께 변경하세요. 규칙이 매칭되지 않는다고 즉시 더 넓은 DOMAIN-KEYWORD를 추가하지 말고 로그에서 실제 도메인을 먼저 확인합니다. DNS가 비정상일 때 nameserver 변경, fake-ip 비활성화, 규칙 재작성을 동시에 하지 마세요. 한 번에 변수 하나만 바꾸고 되돌릴 수 있는 설정 사본을 보관하세요.

“핫 리로드는 성공했지만 동작이 바뀌지 않음”은 기존 연결, 앱 캐시, 클라이언트 실행 상태의 선택 또는 오버라이드가 다시 실행되지 않은 데서 발생할 수 있습니다. 새 연결을 만들고 최종 설정 파일의 수정 시간과 내용을 확인해 코어가 실제로 대상 파일을 읽는지 점검하세요. 여러 설정을 관리하는 클라이언트에는 현재 설정, 구독 캐시, 실행 시 생성되는 설정의 세 계층이 있는 경우가 많아 잘못된 파일을 편집하는 일이 흔합니다. 클라이언트 설정 페이지에서 현재 활성 항목을 확인한 뒤 로그에서 로드 경로를 보는 것이 디스크에서 파일을 하나씩 추측하는 것보다 확실합니다.

되돌릴 수 있는 유지 관리 절차 만들기

안정적인 유지 관리 절차는 네 단계로 구성됩니다. 정상 작동이 확인된 설정을 저장하고, 하나의 대상만 소폭 수정하며, 먼저 검증한 뒤 로드하고, 로그로 실제 동작을 확인하세요. 수정에 실패하면 잘못된 설정 위에 패치를 계속 덧붙이지 말고 이전의 정상 설정으로 되돌리세요. 개인 규칙, DNS 예외, 프록시 그룹 구조를 각각 문서화하고 수정 이유와 의존 관계를 기록하면 나중에 정리하기 쉽습니다.

구독 업데이트 전후에는 모든 노드를 한 줄씩 비교할 필요 없이 최상위 필드, 프록시 그룹 이름과 규칙 마지막 부분의 구조를 비교하면 됩니다. 상위 설정에 노드가 추가되는 것은 개인 규칙에 대체로 영향을 주지 않지만, 프록시 그룹 이름 변경, provider 이름 변경, 규칙 대상 조정은 오버라이드에 영향을 줍니다. 사용하지 않는 예외와 provider를 정기적으로 삭제하면 향후 업데이트 충돌을 줄일 수 있습니다. 설정의 목표는 필드를 많이 넣는 것이 아니라 각 필드의 역할이 명확하고 모든 참조를 추적할 수 있으며 문제가 생겼을 때 빠르게 되돌릴 수 있도록 하는 것입니다.