YAML 가이드 / 설정 파일 참고

Clash YAML 설정 가이드

필드별 의미와 트래픽별 적용 위치를 확인하세요. 먼저 구독 원본, 클라이언트 오버라이드, 커널이 실제로 불러온 설정을 구분한 뒤 포트, DNS, 규칙을 수정하세요.

처음 설치하거나 구독을 가져오는 중이라면 먼저 사용 가이드에 따라 연결을 설정하세요. 이미 실행 중이며 설정값을 이해하거나 충돌 원인을 찾으려면 이 페이지를 참고하세요. 예제는 mihomo에서 흔히 쓰는 문법을 기준으로 하며, 구형 Clash 커널에서는 일부 필드를 지원하지 않을 수 있습니다. 클라이언트는 다운로드 센터에서 선택할 수 있습니다. Windows, macOS, Android, iOS에서는 Clash Plus를 먼저 살펴보고, Linux에서는 Clash Verge Rev 등의 옵션을 확인하세요.

필드 설명 복사 가능한 YAML 실행 설정 문제 해결

1. YAML 구조와 설정 파일 위치

먼저 수정할 파일이 무엇인지 확인하세요

편집기에서 저장에 성공했다고 해서 커널이 새 설정을 사용하는 것은 아닙니다. GUI 클라이언트는 보통 구독에서 내려받은 원본 파일, 사용자가 작성한 오버라이드 조각, 이를 병합해 커널에 전달하는 실행 파일을 구분합니다. 구독을 업데이트하면 원본 파일이 다시 생성되므로 그 안의 규칙을 직접 수정하면 다음 업데이트 때 사라질 수 있습니다. 실행 파일을 수정해도 클라이언트 시작 과정에서 덮어쓸 수 있습니다. 먼저 설정 화면에서 현재 활성 항목을 확인한 뒤 설정 미리보기, 실행 설정 또는 설정 내보내기 메뉴에서 최종 필드값을 점검하세요.

이 페이지의 예제는 용도별로 나눠 둔 것이므로 모든 조각을 그대로 이어 붙이지 마세요. YAML 문서의 최상위 구조는 매핑이어야 합니다. dns, proxies, proxy-groups, rules는 서로 다른 키입니다. 같은 레벨에 dns를 두 번 적어도 자동으로 병합되지 않습니다. 파서가 오류를 내거나 뒤에 나온 값만 남길 수 있습니다. 실제로 편집할 때는 기존 섹션을 찾아 그 안에서 수정하세요. 아래 최소 설정은 구조와 로컬 리스너만 확인하기 위한 것으로, 모든 트래픽을 직접 연결하며 사용할 수 있는 프록시 노드는 포함하지 않습니다.

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

proxies: []
proxy-groups: []

rules:
  - MATCH,DIRECT

들여쓰기, 목록, 문자열의 기본 규칙

들여쓰기는 항목 간의 관계를 결정합니다. 두 칸 공백으로 통일하고 탭 문자는 사용하지 마세요. 콜론 뒤에 공백을 두면 키와 값이 구분되고, 하이픈 뒤에 공백을 두면 목록 항목이 됩니다. rules 아래의 각 규칙은 문자열 목록 항목이며, proxies 아래의 각 노드는 보통 여러 필드가 있는 매핑입니다. 노드의 name, type, server는 같은 들여쓰기 단계에 있어야 합니다. port를 한 단계 더 들여쓰면 포트가 바뀌는 것이 아니라 파싱 오류가 날 수 있습니다.

해시 기호나 콜론 뒤 공백처럼 특수한 조합이 포함된 문자열은 따옴표로 감싸는 것이 좋습니다. 비밀번호와 식별자는 문자열로 지정해야 순수 숫자가 숫자형으로 처리되거나 앞자리 0이 사라지는 일을 막을 수 있습니다. 작은따옴표는 역슬래시가 포함된 일반 문자열을 보존할 때 편리하고, 큰따옴표는 이스케이프 시퀀스를 해석합니다. 문자열에 큰따옴표를 넣을 때는 반드시 올바르게 이스케이프하세요. 메신저에서 전각 콜론, 곡선 따옴표, 보이지 않는 들여쓰기가 포함된 설정을 복사하지 마세요. 겉모습이 비슷해도 파싱 결과는 다를 수 있습니다.

proxies:
  - name: "예제 노드"
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "수동 선택"
    type: select
    proxies:
      - "예제 노드"
      - DIRECT

rules:
  - MATCH,수동 선택

빈 값, 불리언, 참조 관계

false는 불리언이고 "false"는 문자열입니다. 커널이 타입을 자동으로 바로잡아 줄 것이라고 기대하지 마세요. []는 빈 목록, {}는 빈 매핑이며, 키 뒤에 아무것도 쓰지 않으면 보통 빈 값이 됩니다. 이 셋은 서로 바꿔 쓸 수 없습니다. 노드 이름, 프록시 그룹 이름, 규칙 대상은 서로 참조하므로 이름을 일관되게 정하고 중복을 피하세요. 규칙은 쉼표로 매개변수를 구분하므로 이름에 쉼표를 넣지 마세요. 한글 이름을 사용해도 되지만 참조하는 곳의 표기는 완전히 일치해야 합니다.

설정을 확인할 때는 두 단계로 나눠 보세요. YAML 파싱에 성공했다는 것은 문법 구조가 올바르다는 뜻일 뿐입니다. 커널까지 설정을 불러와야 필드 타입, 프로토콜 지원, 이름 참조가 기본적으로 유효한지 확인할 수 있습니다. 설정을 불러오는 데 성공해도 원격 주소, 비밀번호, 규칙의 의도까지 올바르다는 보장은 없습니다. 복잡한 앵커, 병합 키, 템플릿 문법을 한꺼번에 도입하면 클라이언트마다 파싱 방식이 다른 문제가 커질 수 있습니다. 먼저 일반 매핑과 목록으로 동작을 확인한 뒤 중복을 줄이세요. 커널 종류가 불분명하면 화면에 표시된 이름만으로 호환성을 판단하지 말고 클라이언트 정보 화면이나 시작 로그를 확인하세요.

2. 공통 필드: 리스닝 포트와 프록시 모드

포트는 트래픽을 받는 역할만 하며 회선 속도와는 무관합니다

mixed-port는 하나의 리스닝 포트에서 HTTP와 SOCKS 프록시 요청을 모두 받으므로 브라우저와 명령줄 도구가 같은 주소를 사용하기 좋습니다. port는 HTTP 전용 프록시 포트이고 socks-port는 SOCKS 전용 포트입니다. 둘 다 반드시 설정해야 하는 것은 아닙니다. 일반적인 데스크톱 사용에서는 혼합 포트 하나만 유지하면 여러 리스닝 주소로 인한 혼란을 줄일 수 있습니다. 포트 번호는 로컬 서비스 주소의 일부일 뿐이므로 숫자를 바꿔도 원격 프록시 회선이 빨라지지는 않습니다.

필드	기능	확인 사항
`mixed-port`	HTTP와 SOCKS 공용 진입점	클라이언트와 앱의 포트가 일치하는지 확인
`port`	HTTP 전용 프록시 진입점	다른 리스너가 같은 포트를 사용하지 않는지 확인
`socks-port`	SOCKS 전용 프록시 진입점	앱이 SOCKS 프로토콜을 사용하는지 확인
`allow-lan`	로컬 네트워크 접속 허용 여부	바인딩 주소와 방화벽도 확인
`mode`	트래픽 라우팅 모드 선택	시스템 프록시가 켜졌다는 뜻은 아님
`log-level`	로그 상세 수준 설정	문제 해결 후 일반 수준으로 복원

포트를 바꾼 뒤에는 설정을 다시 불러오고 새 리스너가 생성됐는지 확인하세요. 그런 다음 시스템 프록시, 브라우저 수동 프록시 또는 터미널 환경 변수에도 새 값을 반영해야 합니다. 기존 환경 변수는 YAML을 바꿔도 자동으로 업데이트되지 않으며, 이미 열려 있는 터미널에는 이전 설정이 남아 있을 수 있습니다. 데스크톱 클라이언트에서는 화면의 포트 옵션이 파일 값을 덮어쓸 수 있으므로 실행 설정과 리스닝 로그를 기준으로 확인하세요. 포트 충돌이 나면 프로세스를 찾아 다른 클라이언트 인스턴스인지 확인하세요. 어떤 프로세스인지 모르는 시스템 프로세스를 포트를 비우려고 강제 종료하지 마세요.

mixed-port: 7891
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false

규칙, 전역, 직접 연결 모드의 차이

mode: rule은 규칙 목록에 따라 출구를 결정하는 모드로, 일반적인 분기 라우팅에 적합합니다. global은 커널에 들어온 트래픽을 전역 정책으로 처리합니다. 이 경우에도 전역 정책에서 어떤 출구를 선택했는지 확인해야 합니다. direct는 직접 연결을 선택합니다. 여기서 중요한 것은 커널에 들어온 트래픽입니다. 시스템 프록시를 설정하지 않았거나 명시적 프록시를 사용하지 않고 TUN에도 연결되지 않은 앱은 전역 모드로 바꿔도 자동으로 프록시를 거치지 않습니다. 모드 설정과 트래픽 진입점은 별개의 설정입니다.

모드를 바꿔 비교해 보는 것은 좋지만, 규칙 오류를 가리는 용도로 사용해서는 안 됩니다. 규칙 모드에서는 실패하고 전역 모드에서는 성공한다면 규칙 일치 여부, 그룹 선택, DNS를 확인해야 합니다. 전역 모드로 계속 두는 것으로 문제 해결을 끝내지 마세요. 두 모드 모두 실패하면 노드, 인증, 리스너, 네트워크 연결부터 확인하세요. 기존 장기 연결은 이전 출구를 계속 사용할 수 있으므로 모드를 바꾼 뒤 새 연결로 테스트해야 합니다. 차이는 문제 해결 가이드의 프록시 모드 설명을 참고하세요. 모드 전환을 회선 최적화로 오해하지 마세요.

로컬 네트워크 리스너와 관리 인터페이스는 따로 관리하세요

allow-lan: false는 로컬 기기에서만 프록시를 사용할 때 적합합니다. 다른 기기에도 프록시를 제공하려면 로컬 네트워크 접속 허용뿐 아니라 bind-address, 호스트 방화벽, 무선 네트워크 격리, 기기 접속 주소도 확인해야 합니다. 다른 기기에는 클라이언트가 실행 중인 컴퓨터의 로컬 네트워크 주소를 입력해야 하며, 해당 기기 자신의 루프백 주소를 입력하면 안 됩니다. 리스닝을 열면 접근 가능한 범위가 넓어집니다. 신뢰할 수 있는 네트워크에서만 설정하고 인증이나 접근 제어를 적용하세요. 공용 네트워크에 포트를 그대로 노출하지 마세요.

external-controller는 관리 인터페이스이지 브라우저의 프록시 주소가 아닙니다. 시스템 프록시 주소에 제어 포트를 입력해도 정상적인 프록시 연결이 되지 않습니다. 관리 인터페이스는 가급적 루프백 주소에 바인딩하고, 원격 접속이 필요하면 인증과 네트워크 경계를 별도로 설계하세요. log-level: debug는 문제를 찾을 때 잠시 사용할 수 있지만 로그가 많아집니다. 로그를 공유하기 전에 구독 주소와 인증 정보를 가리세요. ipv6는 주소 처리와 관련된 옵션이지 네트워크 자체의 IPv6 연결을 대신하지 않습니다. 환경을 확인하기 전에는 이 옵션과 DNS 설정을 여러 개 동시에 바꾸지 마세요.

프로세스를 찾아 포트를 바꾸는 자세한 순서는 7890 포트 점유 문제 해결을 참고하세요. 중요한 것은 새 번호를 고르는 일이 아니라 리스닝 주소, 진입 프로토콜, 앱 설정이 서로 일치하는지 확인하고 새 요청으로 변경 사항이 적용됐는지 검증하는 것입니다.

3. DNS: 조회 경로와 fake-ip

커널 DNS와 시스템 DNS를 먼저 구분하세요

DNS 설정은 서버 주소 하나만 입력한다고 끝나지 않습니다. 세 가지를 함께 확인해야 합니다. 누가 도메인을 커널에 전달하는지, 커널이 어떤 업스트림에서 실제 주소를 가져오는지, 응답이 이후 연결에 어떻게 사용되는지입니다. dns.enable은 내장 DNS 서비스를 켜고 listen은 리스닝 위치를 지정하지만, 시스템의 모든 요청이 자동으로 이곳을 거치는 것은 아닙니다. 시스템 DNS, 브라우저의 보안 DNS, 앱 자체 DNS 조회, TUN 가로채기가 동시에 작동할 수 있습니다. 설정에 DNS가 적혀 있다는 사실만으로 대상 요청이 실제로 해당 DNS를 거쳤다고 볼 수 없습니다.

아래는 흔히 사용하는 fake-ip 구조입니다. 개별로 검증하기 쉽도록 높은 번호의 로컬 포트에서 리스닝합니다. 완전한 투명 프록시 설정은 아니며 시스템 리졸버를 자동으로 바꾸지도 않습니다. default-nameserver는 업스트림 DNS 서버의 도메인 이름을 해석하는 데 쓰므로 직접 연결할 수 있는 IP 주소 형식의 리졸버를 선택하세요. nameserver는 일반 도메인 조회를 처리합니다. 예제의 업스트림은 현재 네트워크에서 연결 가능해야 합니다. 네트워크 환경에 맞게 바꾸고, 특정 주소 조합이 모든 지역에서 통한다고 가정하지 마세요.

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

fake-ip는 DNS 실패를 뜻하지 않으며 암호화 기능도 아닙니다

enhanced-mode: fake-ip는 조회 결과로 가상 주소를 할당하고 도메인과 주소의 매핑을 유지해 이후 연결에서도 도메인 정보를 활용하기 쉽게 합니다. 198.18로 시작하는 결과가 보인다고 해서 반드시 이상이 있는 것은 아닙니다. 중요한 것은 가상 주소로 향하는 연결도 동일한 프록시 경로에서 처리되는지입니다. DNS가 fake-ip를 반환했는데 이후 트래픽이 커널을 우회해 직접 전송되면 연결이 성립하지 않는 경우가 많습니다. 따라서 DNS 조회 경로와 연결 경로가 함께 구성되어야 합니다. 시스템에 DNS 서버만 따로 지정해서 해결할 수는 없습니다.

fake-ip-filter는 특정 도메인에 가상 주소를 할당하지 않도록 하는 옵션으로, 실제 주소가 필요한 로컬 네트워크 서비스에 주로 사용합니다. 공용 도메인을 대량으로 필터에 추가하면 도메인 매핑의 장점을 잃고 문제 해결도 복잡해집니다. redir-host는 실제 조회 결과를 반환하는 별도의 동작 방식일 뿐, 본질적으로 더 빠르거나 안전한 것은 아닙니다. 호환성 문제가 있다면 한 번에 한 가지씩 비교하세요. 먼저 영향을 받는 도메인, 앱, 접속 경로를 기록한 뒤 예외가 필요한지 결정하세요.

nameserver, fallback, 도메인별 DNS

fallback은 단순히 두 번째 순서의 DNS 서버를 뜻하지 않습니다. 설정하면 커널이 fallback-filter 등의 조건을 바탕으로 어느 쪽 결과를 쓸지 판단합니다. 도메인, 주소 범위, 지리 정보와 관련된 옵션의 실제 동작은 사용 중인 커널 문서를 확인하세요. 필터 조건을 이해하지 않은 채 fallback 설정만 복사하면 조회량이 늘거나 원래 사용할 수 있던 결과가 바뀔 수 있습니다. 먼저 연결 가능한 업스트림 하나로 기본 DNS 조회를 확인한 뒤 근거를 바탕으로 분기 설정을 추가하세요. 처음부터 공용 DNS 서버를 여러 개 겹쳐 쓰지 마세요.

mihomo의 nameserver-policy는 도메인별로 DNS 서버를 지정할 수 있어 사내 도메인을 로컬 DNS에 맡길 때 유용합니다. 프록시 서버 자체의 도메인 조회에는 proxy-server-nameserver도 관련될 수 있습니다. 프록시 연결을 시작하기도 전에 그 프록시를 통해 DNS를 조회하는 순환 문제를 막기 위한 설정입니다. 암호화 DNS는 해당 DNS 조회의 전송만 보호하며 서비스 트래픽을 자동으로 프록시로 보내지는 않습니다. 라우팅 규칙 적용 여부와 업스트림 연결 방식은 사용 중인 커널에서 지원하는 필드를 하나씩 확인하세요.

dns:
  enable: true
  listen: "127.0.0.1:1053"
  enhanced-mode: fake-ip
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "+.home.arpa":
      - 192.168.1.1
  proxy-server-nameserver:
    - 223.5.5.5

위 예제는 별도의 DNS 섹션을 보여 줍니다. 192.168.1.1은 실제 로컬 DNS 서버 주소로 바꾸세요. 앞의 예제와 함께 붙여 최상위 DNS 섹션을 두 개 만들지 마세요. TUN의 dns-hijack은 tun 아래에 두며 dns 섹션에 속하지 않습니다. 보통 앱이 직접 보내는 HTTPS DNS까지 가로챌 수는 없습니다. 문제를 찾을 때는 커널 리스너, 시스템 DNS, 브라우저 동작을 따로 테스트하세요. 이전 결과가 영향을 주지 않도록 캐시를 비우거나 새 연결을 사용하세요.

4. 프록시 노드: 프로토콜 필드와 제공자

공통 필드가 같아도 프로토콜별 매개변수는 다릅니다

proxies는 로컬 노드 정의 목록입니다. 가장 흔한 공통 필드는 name, type, server, port입니다. 이름은 프록시 그룹에서 참조하고, 유형은 프로토콜 처리 방식을 결정하며, 서버와 포트는 연결 대상을 지정합니다. server에는 보통 도메인이나 IP만 입력하고 https://, 경로, 구독 쿼리 매개변수는 포함하지 않습니다. 노드의 포트는 원격 서버 포트이므로 로컬 mixed-port와 같을 필요가 없습니다. 두 값을 서로 복사하지 마세요.

프로토콜별 매개변수는 서비스 제공자가 안내한 값을 사용해야 합니다. Shadowsocks는 암호화 방식과 비밀번호가 일치해야 하고, Trojan은 보통 비밀번호와 TLS 관련 설정이 필요합니다. VMess와 VLESS에는 각각 해당 프로토콜의 식별자와 전송 설정이 필요합니다. type만 다른 프로토콜로 바꾼다고 기존 노드가 계속 작동하는 것은 아닙니다. 전송 계층도 맞아야 합니다. WebSocket 경로, 요청 헤더, gRPC 서비스 이름 등은 서버에서 해당 전송 방식으로 설정한 경우에만 의미가 있습니다. 필드를 더 적는다고 호환성이 높아지지는 않습니다.

proxies:
  - name: "예제 SS"
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

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

TLS 이름과 UDP 지원은 옵션 하나로 해결되지 않습니다

sni는 TLS 핸드셰이크에 사용하는 이름으로, 연결 주소와 같을 수도 있고 서비스 제공자가 별도로 지정할 수도 있습니다. 인증서 오류가 나면 먼저 기기 시간, 서버 이름, 인증서 유효 기간, 중간에 연결이 바뀌었는지 확인하세요. 일반적인 해결 방법으로 skip-cert-verify를 true로 바꾸면 안 됩니다. 인증서 검증을 유지해야 이름 불일치 등의 문제가 명확히 드러납니다. TCP 연결조차 성립하지 않았다면 SNI나 인증서 옵션을 바꿔도 주소에 연결할 수 없는 문제는 해결되지 않습니다.

udp: true는 설정에서 해당 기능을 허용한다는 뜻일 뿐, 서버, 프로토콜, 회선, 앱의 진입 경로가 모두 UDP를 지원한다는 의미는 아닙니다. 브라우저에서는 웹페이지가 열리지만 게임이나 음성 통화가 실패한다면 실제 전송 방식과 트래픽 처리 경로를 확인하세요. 반대로 속도 측정이 시간 초과됐다고 해서 모든 서비스가 실패한다고 단정할 수도 없습니다. 테스트 대상, 요청 방식, 노드 라우팅이 다를 수 있습니다. 핸드셰이크 실패, 인증 실패, 원격 연결 실패를 구분해 살펴보고 모든 오류를 노드 장애로 뭉뚱그리지 마세요.

proxy-providers로 노드 모음을 불러옵니다

proxy-providers는 노드 모음을 커널에 불러오는 설정이며, 프록시 그룹은 use로 제공자를 참조합니다. HTTP 제공자의 url은 리소스 주소, path는 캐시 위치, interval은 보통 초 단위의 갱신 간격입니다. 제공자 리소스는 완전한 클라이언트 구독과 같은 형식이 아닙니다. 일반적인 노드 제공자 파일에는 proxies 목록이 있어야 합니다. 응답이 웹 로그인 페이지나 다른 형식이라면 확장자만 바꿔도 유효한 YAML이 되지 않습니다.

proxy-providers:
  remote-nodes:
    type: http
    url: "https://example.com/proxies.yaml?token=xxxx"
    path: ./providers/remote-nodes.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "구독 선택"
    type: select
    use:
      - remote-nodes

예제 주소는 구조를 보여 주기 위한 것이므로 실제 제공자 리소스로 바꾸세요. 클라이언트 설정 화면에서 구독을 이미 관리하고 있다면 보통 업데이트 방식을 따로 작성할 필요가 없습니다. 서비스 제공자가 완전한 설정 파일, 노드 목록, URI 모음 중 무엇을 제공하는지 확인한 뒤 알맞은 방식으로 가져오세요. 캐시의 상대 경로는 커널 작업 디렉터리를 기준으로 해석되므로 편집기에서 연 파일의 폴더와 다를 수 있습니다. 업데이트가 실패하면 YAML을 이리저리 옮기기보다 클라이언트 데이터 폴더와 권한을 확인하세요.

인증 정보는 민감한 정보입니다. 스크린샷이나 도움 요청용 로그에는 도메인, 오류 유형, 필요한 필드만 남기고 전체 구독 링크는 공개하지 마세요. 노드 이름이 업데이트되면 직접 입력한 프록시 그룹 참조가 깨질 수 있습니다. 제공자 참조를 쓰면 노드를 일일이 관리할 필요가 줄지만, 필터 조건과 사용 가능한 노드가 없는 경우는 여전히 처리해야 합니다. 구독 다운로드 성공은 리소스를 가져왔다는 뜻일 뿐, 노드 연결을 검증한 것이 아니며 해당 리소스의 모든 프로토콜을 현재 커널에서 지원한다는 보장도 아닙니다.

5. 프록시 그룹: 수동 선택, 지연 테스트, 장애 전환

먼저 참조 관계를 명확히 설정하세요

프록시 그룹은 규칙과 실제 출구 사이에서 선택을 담당합니다. 규칙은 그룹을 지정하고, 그룹에는 노드, 다른 그룹, 내장 대상이 포함될 수 있습니다. 덕분에 노드를 바꿀 때마다 도메인 규칙을 수정하지 않아도 됩니다. 가장 단순한 select는 수동 선택 방식이므로 먼저 사용 가능한 회선을 확인하기 좋습니다. 그룹의 proxies에는 서버 주소가 아니라 노드 또는 그룹 이름을 적습니다. use에는 제공자 이름을 적습니다. 둘은 참조하는 대상이 다르므로 이름을 한 글자만 틀려도 설정을 불러오지 못할 수 있습니다.

용도와 동작 방식을 구분해 이름을 정하세요. 예를 들어 ‘일반 출구’는 트래픽이 들어오는 그룹을, ‘자동 지연 테스트’는 선택 방식을 나타냅니다. 일반 규칙은 첫 번째 그룹을 지정하고, 그 그룹에서 테스트 그룹, 예비 그룹, 개별 노드를 선택하게 하면 됩니다. 그룹이 자기 자신을 포함하거나 여러 그룹이 서로를 순환 참조하지 않도록 하세요. 내장 대상과 같은 이름이나 노드 이름과 겹치는 그룹명도 피하세요. 복잡하게 중첩해 설정을 불러올 수는 있어도 관리가 어려워집니다. 계층이 단순할수록 실제 출구를 파악하기 쉽습니다.

proxies:
  - name: "회선 A"
    type: ss
    server: a.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
  - name: "회선 B"
    type: ss
    server: b.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "일반 출구"
    type: select
    proxies:
      - "자동 지연 테스트"
      - "예비 전환"
      - "회선 A"
      - "회선 B"
      - DIRECT

  - name: "자동 지연 테스트"
    type: url-test
    proxies:
      - "회선 A"
      - "회선 B"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: "예비 전환"
    type: fallback
    proxies:
      - "회선 A"
      - "회선 B"
    url: https://www.gstatic.com/generate_204
    interval: 300

rules:
  - MATCH,일반 출구

자동 지연 테스트는 테스트 요청 결과만 보여 줍니다

url-test는 테스트 결과에 따라 출구를 선택합니다. url은 확인 대상 주소, interval은 테스트 간격, tolerance는 작은 차이로 선택이 자주 바뀌는 것을 줄이는 값이며 보통 밀리초 단위입니다. 테스트 간격을 너무 짧게 설정하지 마세요. 특히 모바일 기기나 노드가 많을 때 요청이 잦으면 네트워크와 배터리 소모가 늘어납니다. 응답이 안정적이고 예상 결과가 분명한 주소를 선택하세요. 로그인이 필요하거나 복잡하게 리디렉션되거나 특정 회선에서 접근이 제한되는 페이지는 피하는 것이 좋습니다.

노드 지연 시간은 한 번의 테스트 요청에서 관측한 값일 뿐, 동영상 전송량이나 다운로드 속도, 모든 사이트의 응답 시간을 나타내지는 않습니다. 테스트 주소에 연결할 수 있어도 실제 서비스는 지역, 계정, 서비스 정책에 따라 제한될 수 있습니다. 노드의 숫자가 낮게 나왔다면 실제 서비스에서도 확인하세요. 테스트 결과만으로 전체 규칙을 결정하지 마세요. 그룹에 DIRECT가 포함돼 있다면 의도도 점검해야 합니다. 자동 지연 테스트가 직접 연결과 프록시 사이에서 경쟁하면 예상과 전혀 다른 출구가 선택될 수 있습니다.

fallback과 로드 밸런싱은 각각 적용 범위가 다릅니다

fallback은 보통 목록 순서에 따라 사용할 수 있는 항목을 선택하며, 핵심은 최저 지연 경로 탐색이 아니라 장애 전환입니다. 앞쪽 노드가 복구된 뒤 새 연결을 어디로 보낼지는 커널 구현과 현재 상태를 확인해야 합니다. 끊어진 TCP 세션을 다른 노드로 옮겨 주지는 않으므로 진행 중인 다운로드는 다시 연결해야 할 수 있습니다. ‘주 회선과 예비 회선’으로 이해하는 편이 좋습니다. 자동 복구가 서비스 중단을 완전히 막아 준다고 생각하지 마세요.

load-balance는 여러 출구로 연결을 나눠 보내며, 분배 방식은 설정에 따라 달라집니다. 여러 회선의 대역폭을 합쳐 하나의 연결 속도를 높여 주는 기능은 아닙니다. 출구 IP 변경에 민감한 서비스에서는 재인증이 필요하거나 세션 오류가 발생할 수 있으므로 안정적인 그룹에 고정하는 것이 좋습니다. 처음 설정을 만들 때는 수동 그룹으로 검증한 다음 자동 기능을 추가하세요. 노드를 수동 선택해도 실패할 때 노드나 진입 경로를 살펴보세요. 그때 지연 테스트 허용 오차를 바꾸는 것은 해결책이 아닙니다.

클라이언트가 그룹의 마지막 선택을 저장할 수 있으므로 설정을 다시 불러와도 목록 첫 항목으로 돌아간다고 보장할 수 없습니다. profile.store-selected 등의 설정, GUI의 상태 저장 방식, 그룹 이름 변경이 복원 동작에 영향을 줄 수 있습니다. 문제를 찾을 때는 YAML 순서만 보지 말고 현재 선택된 항목을 확인하세요. 제공자를 통해 노드를 업데이트하는 경우 필터링 후 사용할 수 있는 항목이 남는지도 살펴보세요. 자동 그룹이 비어 있는 문제, 이름 참조 누락, 모든 테스트 실패는 서로 다른 원인이므로 각각 해결해야 합니다.

6. 분기 규칙: 일치 순서와 규칙 제공자

규칙은 위에서부터 확인하며, 처음 일치한 항목에서 결정됩니다

규칙 모드에서는 일반 규칙을 목록 순서대로 확인하고, 처음 일치한 규칙의 대상이 이후 출구를 결정합니다. 가장 흔한 실수는 문법보다 배치 순서입니다. 넓은 범위의 규칙을 앞에 두면 뒤에 있는 정밀한 예외 규칙이 실행되지 않습니다. MATCH는 마지막에 사용하는 기본 규칙이므로 일반 규칙 목록의 끝에 두세요. 웹사이트 예외를 추가할 때는 규칙 대상이 존재하는지, 그룹에서 올바른 항목을 선택했는지 함께 확인하고 새 연결로 규칙이 적용되는지 살펴보세요. 목록에 도메인이 있다고 해서 해당 규칙이 실제로 적용됐다는 뜻은 아닙니다.

DOMAIN은 도메인 이름을 정확히 일치시키고, DOMAIN-SUFFIX는 도메인과 하위 도메인을 일치시키며, DOMAIN-KEYWORD는 도메인에 포함된 키워드를 찾습니다. 특정 사이트를 직접 연결하려면 짧은 키워드만 쓰기보다 정확한 도메인이나 접미사를 사용하세요. 관련 없는 도메인까지 영향을 줄 수 있습니다. 규칙에는 보통 URL의 프로토콜, 경로, 페이지 매개변수를 적지 않습니다. 같은 사이트에서 여러 리소스 도메인을 사용할 수 있으므로 기본 페이지가 직접 연결된다고 이미지, 로그인, API 요청도 같은 경로를 쓴다고 볼 수 없습니다.

rules:
  - DOMAIN,printer.home.arpa,DIRECT
  - DOMAIN-SUFFIX,home.arpa,DIRECT
  - DOMAIN-SUFFIX,example.org,일반 출구
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,일반 출구

IP 규칙과 no-resolve의 실제 의미

IP-CIDR은 목적지 주소가 속한 네트워크 대역으로 일치 여부를 판단하므로 로컬 네트워크나 명확한 주소 범위에 적합합니다. no-resolve는 해당 규칙이 도메인 조회를 직접 유발하지 않도록 하는 옵션이지, 연결에서 DNS를 전부 차단한다는 뜻은 아닙니다. 요청에 목적지 IP가 이미 있으면 규칙을 적용할 수 있습니다. 도메인만 있고 아직 조회되지 않았다면 이 규칙을 건너뛰고 다음 규칙으로 넘어갈 수 있습니다. 모든 IP 규칙에 이 옵션을 넣기 전에 조회를 줄이려는 것인지, 조회 결과로 출구를 결정하려는 것인지 확인하세요.

GEOIP는 해당 주소 데이터베이스에 의존하고 GEOSITE는 도메인 분류 데이터와 관련되므로 커널 지원 및 리소스 설정을 확인해야 합니다. 실시간으로 서버의 물리적 위치를 판단하는 도구는 아니며 데이터베이스 업데이트와 공유 IP로 인해 결과가 달라질 수 있습니다. 특정 서비스 하나가 잘못 분기되면 분류 방식을 크게 바꾸기보다 정확한 규칙으로 예외를 추가하는 편이 안정적입니다. 사내 네트워크나 여러 로컬 네트워크가 있다면 편의를 위해 모든 사설 주소를 범위가 지나치게 넓은 공용 예외 규칙 하나에 넣지 마세요.

rule-providers의 형식은 behavior와 맞아야 합니다

규칙 제공자를 사용하면 긴 목록을 별도 리소스로 분리하고 기본 설정에서 RULE-SET으로 참조할 수 있습니다. behavior: domain은 도메인 목록, ipcidr은 네트워크 대역, classical은 규칙 유형과 매개변수 형식에 적합합니다. 리소스 내용은 format과도 일치해야 합니다. 일반 텍스트 목록을 payload가 있는 YAML로 취급하거나 바이너리 리소스를 텍스트로 읽을 수는 없습니다. 다운로드는 성공했지만 파싱에 실패한다면 네트워크 문제로 판단하기 전에 형식과 응답 내용을 확인하세요.

rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,DIRECT
  - MATCH,일반 출구

해당하는 local-domains.yaml 파일은 아래처럼 작성할 수 있습니다. 먼저 파일을 만들고 커널에 읽기 권한이 있는지 확인하세요. 상대 경로는 실행 디렉터리를 기준으로 합니다. 기본 설정의 대상인 ‘일반 출구’는 프록시 그룹에 정의되어 있어야 합니다. 규칙 제공자 파일에는 일치시킬 내용만 저장하고 각 줄에 정책 이름을 반복해서 적지 마세요. 파일마다 역할을 명확히 나누면 모든 파일에 출구 설정을 섞는 것보다 관리하기 쉽습니다.

payload:
  - "+.home.arpa"
  - "printer.example.com"

mihomo의 프로세스 이름 규칙 등은 운영체제, 권한, 진입 방식에 따라서도 동작이 달라집니다. 한 플랫폼에서 프로세스를 식별한다고 다른 플랫폼에서도 같은 방식으로 사용할 수 있는 것은 아닙니다. 앱이 직접 도메인을 조회한 뒤 IP로 연결하면 도메인 기반 규칙에 필요한 정보가 없을 수도 있습니다. 문제를 찾을 때는 연결 정보에서 도메인, 대상 IP, 적용된 규칙, 실제 경로를 확인하세요. 먼저 입력 정보가 충분한지 판단한 뒤 DNS, 트래픽 처리 방식, 규칙 순서 중 무엇을 조정할지 결정하세요.

7. 오버라이드와 병합: 구독 업데이트 유지하기

커널 설정과 클라이언트의 가공 과정을 구분하세요

오버라이드는 모든 클라이언트에서 동일하게 동작하는 YAML 표준이 아닙니다. 커널은 최종 설정을 읽지만 GUI 클라이언트는 설정을 읽기 전에 전역 옵션, 구독별 옵션, 병합 조각, 스크립트를 적용할 수 있습니다. Clash Plus, Clash Verge Rev, FlClash 등은 메뉴 위치와 적용 우선순위가 다르므로 한 클라이언트의 설정을 다른 클라이언트에 그대로 적용할 수 없습니다. 먼저 사용 중인 클라이언트의 오버라이드 안내를 확인하고 모든 구독에 적용되는지 특정 설정에만 적용되는지 살펴보세요. 최종 생성된 파일의 필드값이 예상과 다르면 구독 원본을 계속 수정하기보다 가공 과정을 확인해야 합니다.

일반적인 병합 방식에는 스칼라 값 덮어쓰기, 매핑 재귀 병합, 목록 대체가 있지만 이를 반드시 따르는 공통 규칙은 없습니다. 예를 들어 오버라이드 조각에 dns.nameserver만 적었을 때 어떤 도구는 기존 DNS의 다른 키를 보존하지만, 다른 도구는 섹션 전체를 바꿀 수 있습니다. rules, proxies 같은 목록은 특히 주의해야 합니다. 규칙 하나만 담은 목록을 패치로 넣으면 전체 규칙 목록이 대체될 수 있습니다. ‘병합’이라고 해서 반드시 목록에 추가된다고 생각하지 마세요.

# 일반 YAML 병합 조각을 지원하는 클라이언트에만 적용됩니다.
# 매핑과 목록의 병합 방식은 클라이언트에서 확인해야 합니다.
mixed-port: 7891
allow-lan: false
log-level: info

dns:
  enable: true
  ipv6: false

규칙 목록의 앞에 추가, 뒤에 추가, 전체 대체

로컬 규칙을 추가하려면 임의의 비공개 필드를 추측하기보다 클라이언트가 제공하는 규칙 앞에 추가 또는 뒤에 추가 기능을 먼저 사용하세요. 앞에 추가하면 우선 적용해야 하는 도메인 예외에 적합합니다. 뒤에 추가할 때는 기존 목록에 MATCH가 있는지 확인하세요. 그 뒤에 보통 규칙을 추가해도 적용되지 않습니다. 도구가 목록 전체를 대체한다면 기존 규칙과 기본 규칙을 유지해야 하며 구독 규칙 업데이트가 동기화되지 않을 수 있다는 점도 고려하세요. 어떤 방식을 쓸지는 구독이 규칙을 얼마나 제어하도록 할지에 따라 결정해야 합니다.

노드와 프록시 그룹에도 참조 관계가 있습니다. 노드를 삭제하면서 기존 그룹 참조를 남기면 대상을 찾지 못합니다. 새 그룹 이름으로 바꾸고 규칙은 수정하지 않아도 참조가 깨집니다. 먼저 최종 이름을 정한 다음 노드, 그룹, 규칙의 참조를 함께 수정하세요. 특정 웹사이트의 출구만 고정하려면 보통 정확한 규칙 하나를 추가해 기존 그룹을 참조하면 됩니다. 노드 목록 전체를 관리할 필요는 없습니다. 변경 범위가 작을수록 이후 구독 업데이트와 충돌할 가능성이 줄어듭니다.

YAML 앵커와 병합 키는 파서가 지원하는 범위 안에서 구조를 재사용하는 기능일 뿐, 파일 간 오버라이드를 자동으로 제공하지 않으며 목록 추가용 문법도 아닙니다. 편집기 미리보기에서 정상이어도 클라이언트의 파싱 방식이 다를 수 있습니다. 스크립트 오버라이드는 더 유연하지만 클라이언트가 정한 함수 진입점, 실행 순서, 오류 처리 방식도 고려해야 합니다. 모든 클라이언트가 지원한다고 가정한 스크립트 템플릿은 이 페이지에서 제공하지 않습니다. 명확한 인터페이스 안내가 없다면 출처가 불분명한 스크립트를 복사하기보다 일반 필드를 오버라이드하는 편이 검증하기 쉽습니다.

되돌릴 수 있도록 설정을 계층별로 관리하세요

관리 항목을 세 계층으로 나눌 수 있습니다. 구독 계층은 노드와 서비스 제공자의 규칙을, 로컬 계층은 포트, 신뢰할 수 있는 로컬 네트워크 예외, 개인 설정을, 임시 계층은 문제 해결용 변경만 담당하게 하세요. 임시 설정이 효과가 있으면 적절한 영구 계층으로 정리하고 중복 키를 제거하세요. 각 오버라이드 조각에는 용도를 적고 수정 전 실행 가능한 백업을 보관하세요. 화면 옵션, 전역 오버라이드, 구독별 오버라이드에서 같은 포트를 동시에 설정하면 한 곳만 바꿨을 때 ‘저장했는데 변한 것이 없다’고 느낄 수 있습니다.

파일이 저장됐는지만 봐서는 오버라이드를 검증할 수 없습니다. 현재 구독을 다시 불러오고 병합된 설정에서 대상 키를 찾으세요. 다음으로 그룹과 규칙 참조가 있는지 확인한 뒤 새 요청으로 규칙 적용 여부를 살펴보세요. 구독을 직접 업데이트해 변경 사항이 유지되는지도 확인해야 합니다. 이 과정에서 설정을 올바른 위치에 저장했는지 검증할 수 있습니다. 업데이트 후 변경 사항이 사라지면 매번 다시 수정하지 말고 클라이언트가 지원하는 로컬 계층으로 옮기세요. 다른 구독으로 바꿀 때 적용 범위도 확인해 전역 규칙이 특정 구독에만 있는 그룹을 참조하는 일이 없도록 하세요.

여러 사람이 함께 관리하거나 여러 기기에서 설정을 유지한다면 ‘필드, 출처, 최종값, 검증 방법’을 기록하세요. 클라이언트 화면은 바뀔 수 있으므로 메뉴를 누르는 순서만 적기보다 최종 구조를 기록하는 편이 업그레이드, 이전, 재설치 후 설정을 복구하기 쉽습니다. 업데이트 후 갑자기 실행할 수 없다면 최근 추가한 오버라이드와 참조 관계부터 다시 확인한 뒤 문제 해결 페이지에서 원인을 차례로 찾으세요.

8. 검증과 문제 해결: 설정 불러오기부터 실제 요청까지

먼저 파싱과 커널 검사를 통과하세요

검증 순서는 문법, 커널 설정 불러오기, 포트 리스닝, 노드 연결, 규칙 적용, 실제 앱 순으로 고정하세요. 단계마다 입력과 결과가 분명해집니다. 시작에 실패하면 가장 최근에 정상 작동한 설정으로 먼저 되돌리고 문제가 있는 파일에 수정을 계속 덧붙이지 마세요. 명령줄에서 테스트하기 전에는 현재 클라이언트에서 사용하는 커널을 호출하는지 확인하세요. 시스템에 설치된 다른 구형 실행 파일은 새 필드를 지원하지 않을 수 있으므로 그 테스트 결과가 클라이언트의 실제 동작을 그대로 보여 주지는 않습니다.

# 설정 파일이 있는 디렉터리에서 실행하고, 명령 이름은 로컬 설치 방식에 맞게 조정하세요.
mihomo -t -d . -f ./config.yaml

-f는 파일을, -d는 작업 디렉터리를 지정합니다. 테스트에서 제공자 캐시나 관련 리소스를 읽어야 할 수 있습니다. 명령이 성공했다면 현재 환경에서 설정을 기본적으로 불러올 수 있다는 뜻입니다. 원격 노드와 모든 규칙 리소스가 정상이라는 의미는 아닙니다. 클라이언트에 별도 명령줄 도구가 없다면 설정 검사와 로그 화면에서 같은 수준의 검증을 할 수 있습니다. 테스트 명령 하나를 실행하려고 커널 파일을 관리되지 않는 폴더에 복사하거나 별도의 상시 실행 인스턴스를 띄우지 마세요.

파싱 오류에는 보통 줄 번호가 표시되지만 실제 원인은 앞줄의 문자열 따옴표 누락, 목록 항목 누락, 들여쓰기 단계 변경일 수 있습니다. 오류 줄 주변의 매핑 전체를 확인하고 필요하면 최소 구조로 돌아가 한 부분씩 추가하세요. 이름을 찾을 수 없다면 노드, 그룹, 규칙의 참조를 확인해야 합니다. 오류가 난 줄을 지우는 것으로 해결되지 않습니다. 지원하지 않는 필드라면 커널 종류와 해당 필드를 사용할 수 있는 위치를 확인하세요. 권한이나 리소스 읽기 오류는 작업 디렉터리를 점검해야 하며 YAML 들여쓰기를 바꿀 문제는 아닙니다.

명시적 프록시로 시스템 트래픽 처리 문제를 분리하세요

커널이 정상적으로 시작되면 먼저 명시적 프록시로 새 요청을 보내 시스템 프록시와 TUN을 잠시 제외하고 확인하세요. 아래 명령은 해당 옵션을 지원하는 curl에서 사용할 수 있습니다. Windows에서는 명령 별칭 차이를 피하기 위해 curl.exe를 명시적으로 사용하세요. 포트는 실제 리스닝 값으로 바꾸고 테스트 주소는 현재 환경에서 연결할 수 있는 대상으로 선택하세요. 요청 한 번이 실패해도 해당 경로에 문제가 있다는 뜻일 뿐, 모든 프록시 기능이 작동하지 않는다는 의미는 아닙니다.

curl --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/
curl --proxy socks5h://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/

socks5h는 도메인 조회를 프록시 측에 맡기므로 클라이언트에서 먼저 조회한 뒤 연결하는 테스트와 경로가 다릅니다. 한 방식은 성공하고 다른 방식은 실패한다면 모든 노드를 바로 바꾸지 말고 DNS 조회와 진입 프로토콜을 비교하세요. 명시적 프록시는 성공하지만 브라우저에서 실패한다면 시스템 프록시, 브라우저 확장 프로그램, 별도의 보안 DNS, 기존 연결을 먼저 확인하세요. TUN을 사용하는 경우에는 시스템 라우팅, 권한, 다른 네트워크 제어 프로그램도 확인해 두 도구가 동시에 진입점을 차지하지 않도록 하세요.

증상별로 필요한 정보만 수집하세요

증상	먼저 확인할 항목	다음 단계
불러오자마자 실패	들여쓰기, 타입, 참조 이름	실행 중인 커널로 설정 검사
연결 거부됨	리스닝 주소와 실제 포트	커널 프로세스가 실행 중인지 확인
도메인 조회 실패	조회 경로와 업스트림 연결 상태	시스템 DNS와 커널 DNS 구분
특정 노드만 실패	프로토콜, 인증, 핸드셰이크 로그	수동으로 전환해 비교
예상과 다른 출구 사용	규칙 적용 결과와 그룹 선택	새 연결로 다시 검증
구독 업데이트 후 작동하지 않음	오버라이드 위치와 목록 병합 방식	최종 실행 설정 확인

도움을 요청할 때는 운영체제, 클라이언트 이름, 커널 종류, 문제가 발생한 단계, 민감 정보를 가린 관련 로그를 제공하세요. 명시적 프록시가 성공하는지, 규칙 모드와 전역 모드에서 차이가 있는지, 특정 대상 하나만 실패하는지도 알려 주세요. 이런 정보가 ‘시간 초과’ 화면을 올리는 것보다 문제를 찾는 데 도움이 됩니다. debug 로그를 대량으로 올리지 마세요. 오류 전후의 관련 기록만 추리고 인증 정보를 가린 다음 각 테스트에서 어떤 값을 바꿨는지 설명하세요. 오류가 안정적으로 재현돼야 수정이 효과가 있는지 판단하기 쉽습니다.

마지막으로 회귀 테스트를 진행하세요. 클라이언트를 다시 시작해 리스너가 복구됐는지 확인하고, 구독을 업데이트해 로컬 오버라이드가 유지되는지 확인하세요. 네트워크를 바꾼 뒤 대상 서비스에 다시 연결해 DNS 캐시와 그룹 선택도 살펴보세요. 문제 해결이 끝나면 로그 수준을 일반 설정으로 되돌리고 임시로 완화한 옵션과 중복 규칙을 제거하세요. 설정을 많이 추가하는 것이 목표가 아니라 각 필드의 용도를 설명할 수 있고 변경 결과를 검증할 수 있어야 합니다. 연결 과정을 다시 정리하려면 사용 가이드를 참고하고, 클라이언트를 바꾸려면 다운로드 센터의 운영체제 및 아키텍처 옵션을 확인하세요.