CONFIG.YAML / MIHOMO

Clash 설정 파일 가이드

이 페이지는 필드와 설정 처리 순서에 따라 구성되어 있어 mihomo 커널에서 사용하는 YAML 설정을 찾아보기 좋습니다. 처음 설치하거나 구독을 가져오고 연결을 시작하려면 먼저 사용 가이드를 확인하세요. 필드 충돌, 규칙 미적용, 구독 업데이트 후 로컬 수정 내용이 덮어쓰이는 문제가 발생하면 이 페이지에서 해당 항목을 찾아보세요.

Clash 생태계에는 다양한 커널과 클라이언트 구현이 있습니다. 아래 예시는 mihomo 필드의 의미를 기준으로 합니다. 화면에 표시되는 이름, 오버라이드 메뉴, 일부 고급 기능은 사용하는 클라이언트에 따라 다를 수 있습니다. 예시에 나오는 예약 도메인, 문서 주소, 데모 비밀번호는 실제 서비스 정보에 맞게 바꿔야 합니다.

YAML 구조와 설정 진입점

설정 파일은 수신 대기 지점, 이름 확인 방식, 사용 가능한 아웃바운드와 트래픽 분기 순서를 정의합니다. YAML 파싱에 성공했다는 것은 형식이 올바르다는 뜻일 뿐, 노드에 연결할 수 있거나 현재 커널이 모든 필드를 지원한다는 뜻은 아닙니다. 문제를 해결할 때는 문법 오류, 필드 의미 오류, 실행 환경 오류를 차례로 구분하세요. 네트워크 시간 초과를 들여쓰기 문제로 보거나, 프록시 그룹 이름 오류를 구독 문제로 오해하지 않도록 주의해야 합니다.

최상위 매핑과 중첩 구조

자주 쓰는 최상위 필드로는 mixed-port, mode, dns, proxies, proxy-groups, rules가 있습니다. 최상위 키는 줄 맨 앞에서 시작하고 하위 필드는 일정한 공백 수만큼 들여씁니다. 보통 공백 두 칸으로 통일하며 탭은 사용할 수 없습니다. 목록 항목은 하이픈과 공백으로 시작합니다. 같은 노드의 이름, 프로토콜, 주소, 포트는 하나의 목록 항목에 함께 있어야 합니다.

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

proxies: []

proxy-groups:
  - name: 기본 출구
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,기본 출구

위 설정은 직접 연결을 확인하기 위한 최소 구성으로, 원격 프록시 서비스는 포함되어 있지 않습니다. 수신 대기, 그룹 참조, 규칙 로드 절차가 정상인지 확인하는 데 사용할 수 있지만 원격 노드의 연결 가능 여부를 판단할 수는 없습니다. proxies: []는 노드 목록이 비어 있다는 뜻입니다. 프록시 그룹은 내장 아웃바운드 DIRECT를 참조하고, 마지막 규칙은 이미 정의한 그룹 이름을 참조합니다. 실제 노드를 추가하려면 먼저 노드를 등록한 다음 그룹에 이름을 추가하세요.

문자열, 목록, 불리언 값

포트나 간격 같은 숫자에는 보통 따옴표를 붙이지 않으며, 스위치에는 true 또는 false를 사용합니다. 노드 비밀번호, 특수 문자가 포함된 이름, 규칙 문자열, URL은 따옴표로 감싸면 콜론이나 샵 기호, 파서별 차이로 인한 모호함을 줄일 수 있습니다. 샵 기호는 위치에 따라 주석을 나타내므로 비밀번호에 샵이 들어 있다면 문자열로 명시하는 편이 안전합니다. 작은따옴표 문자열 안의 작은따옴표는 두 번 써야 하며, 큰따옴표 안의 백슬래시는 이스케이프 문자로 처리될 수 있습니다.

블록 목록과 인라인 목록은 모두 유효한 YAML 문법이지만, 긴 설정을 관리할 때는 블록 목록이 항목별로 검토하기 더 쉽습니다. 노드는 중괄호 형식으로 작성할 수도 있지만 필드가 많다면 여러 줄로 펼쳐 쓰는 것을 권장합니다. 줄 수를 줄이려고 여러 스타일을 섞지 마세요. 키와 구분자 사이에 전각 콜론, 전각 쉼표, 웹페이지에서 복사된 줄 바꿈 없는 공백이 들어가지 않도록 주의하세요.

파일 위치와 실제 적용 설정

클라이언트 화면의 구독 원문, 편집기의 로컬 파일, 커널이 최종적으로 불러오는 설정은 서로 다른 객체일 수 있습니다. 구독을 업데이트한 뒤 클라이언트가 수신 대기 포트, 컨트롤 인터페이스, 오버라이드 규칙을 추가할 수도 있습니다. 파일을 살펴보기 전에 현재 활성 설정 이름과 업데이트 시간을 확인하고 병합 스크립트가 있는지 살펴보세요. 그런 다음 클라이언트의 실행 설정 보기 메뉴에서 최종 결과를 확인하세요.

같은 계층에 동일한 키를 중복 정의하지 마세요. 일부 파서는 중복 키를 거부하고, 다른 파서는 나중 값을 남길 수 있어 결과를 예측하기 어렵습니다. 규칙을 추가할 때는 기존 목록을 수정하거나 클라이언트가 명확히 지원하는 병합 기능을 사용하세요. 파일 맨 끝에 rules를 다시 작성하면 안 됩니다. 설정끼리 복사해 붙여넣는 것만으로 의미가 자동 병합되는 것도 아닙니다.

파일은 UTF-8 인코딩으로 저장하고 확장자가 실제로 .yaml인지, 또는 클라이언트가 지원하는 형식인지 확인하세요. 숨겨진 텍스트 확장자가 추가된 경우도 주의해야 합니다. 파싱 오류가 발생하면 로그에 표시된 줄과 바로 앞 목록 항목을 먼저 살펴보세요. 이전 줄의 따옴표가 닫히지 않았거나 들여쓰기가 바뀌었거나 목록 항목이 제대로 끝나지 않은 경우가 많습니다.

포트, 모드, 트래픽 가로채기 범위

수신 포트는 애플리케이션이 연결을 전달할 위치를 정하고, 실행 모드는 커널이 아웃바운드를 선택하는 방식을 정합니다. 시스템 프록시와 TUN은 트래픽이 커널에 들어오는 경로를 결정합니다. 서로 연관되어 있지만 서로를 대신할 수는 없습니다. mode만 바꿔도 모든 앱이 자동으로 프록시를 사용하는 것은 아닙니다. 시스템 프록시를 켜더라도 해당 설정을 읽지 않는 프로그램의 트래픽이 커널로 들어온다고 보장할 수 없습니다.

HTTP, SOCKS, 혼합 포트

port는 HTTP 프록시 수신에, socks-port는 SOCKS 프록시 수신에 사용합니다. mixed-port는 하나의 포트에서 HTTP와 SOCKS 요청을 모두 받습니다. 일반적인 데스크톱 환경에서는 혼합 포트만 사용해도 충분합니다. 앱마다 별도 설정이 꼭 필요할 때 독립 수신 포트를 추가하세요. 같은 주소에서 여러 수신 서비스가 동일한 포트를 사용하면 포트 충돌이 발생합니다.

mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false
필드용도변경 후 확인 사항
mixed-portHTTP와 SOCKS 공용 수신앱에 입력하는 프록시 포트
allow-lanLAN에서 프록시에 접속할 수 있는지 여부수신 주소와 방화벽 범위
mode규칙, 전역 또는 직접 연결 모드실제 적용된 모드와 그룹 선택
log-level로그 상세 수준문제를 재현한 뒤 일반 수준으로 복원

포트가 사용 중이면 먼저 해당 포트를 점유한 프로세스가 이전 클라이언트, 다른 프록시 도구, 시스템 서비스 중 무엇인지 확인하세요. 정체를 모르는 프로세스를 바로 종료하지 마세요. 포트를 변경한 뒤에는 시스템 프록시, 브라우저 확장 프로그램, 터미널 환경 변수, 앱에 직접 입력한 프록시 주소도 함께 수정해야 합니다. 자세한 내용은 7890 포트 충돌 확인 및 mixed-port 변경 방법을 참고하세요.

규칙 모드와 전역 모드

rule은 규칙 목록을 위에서 아래로 확인해 매칭하며, 일반적인 사용 환경의 기본 모드로 적합합니다. global은 전역 정책을 사용해 아웃바운드를 선택하므로 임시 연결 테스트에 유용합니다. direct는 직접 연결을 사용합니다. 모드를 바꾸면 이미 커널에 들어온 연결의 처리 방식만 달라지며 운영체제의 라우팅 방식은 바뀌지 않습니다. 클라이언트 화면의 모드 버튼이 파일의 필드를 덮어쓸 수도 있으니 실행 상태를 기준으로 확인하세요.

LAN 공유를 켜려면 LAN 연결을 허용하고, 실제 네트워크 환경에 맞는 인터페이스 주소를 수신 주소에 포함해야 합니다. 예를 들어 bind-address: "*"를 사용할 수 있습니다. 이 설정은 프록시 서비스에 접근할 수 있는 범위를 넓히므로 방화벽에서 허용할 출발지를 제한하고, 필요한 경우 프록시 인증을 설정하세요. 포트를 공인 인터넷에 노출하지 않도록 주의해야 합니다. 다른 기기에 호스트 IP를 프록시 주소로 입력하는 것만으로 수신이 자동으로 열리지는 않습니다.

시스템 프록시와 TUN

시스템 프록시는 운영체제의 프록시 설정을 따르는 앱에 적용됩니다. 적용 범위가 명확해 첫 연결을 확인하는 방법으로 적합합니다. TUN은 가상 네트워크 인터페이스로 트래픽을 가로채며 관리자 권한, 라우팅 변경, DNS 설정이 필요할 수 있습니다. 앱에서 이미 프록시를 설정한 상태로 TUN까지 켜면 트래픽이 중복으로 가로채일 수 있습니다. 현재 상태를 기록한 뒤 한 번에 한 가지 가로채기 방식만 변경하세요.

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

이 TUN 설정은 필드 간 관계를 보여 주기 위한 예시이며 원격 관리 서버에서 바로 활성화하면 안 됩니다. 자동 라우팅이 원격 세션, 컨테이너 네트워크, 기업 VPN에 영향을 줄 수 있습니다. dns-hijack은 가로채기 범위에 들어오는 특정 DNS 트래픽을 처리합니다. 암호화된 DNS까지 모두 가로챈다는 뜻은 아니며, 실제 동작은 시스템 라우팅, 앱 동작, 커널 지원 여부에 따라 달라집니다.

최상위 ipv6와 DNS의 같은 이름 필드는 적용 범위가 다릅니다. 한쪽만 끄고 기기의 모든 IPv6 트래픽이 차단되었다고 가정할 수 없습니다. IPv6를 사용해야 한다면 상위 네트워크, 노드 지원, 가로채기 라우팅을 모두 확인하세요. 자세한 비교는 TUN 모드와 시스템 프록시의 작동 방식을 참고하세요.

DNS 확인과 주소 매핑

DNS 설정은 분기와 향상 모드를 논의하기 전에 먼저 독립적으로 시작될 수 있는 조회 경로를 갖춰야 합니다. 요청 시간 초과가 반드시 노드 문제인 것은 아닙니다. DNS 서버에 연결할 수 없거나 암호화 DNS 도메인의 초기 조회가 불가능하거나 노드 서버 도메인의 조회가 순환 참조를 일으키면 연결을 시작하기도 전에 실패할 수 있습니다. 문제를 해결할 때는 대상 도메인 조회, 프록시 서버 조회, DNS 서비스 자체의 도메인 조회를 구분하세요.

주요 필드와 시작 단계

enable은 내장 DNS를 켜고, listen은 수신 주소를 지정합니다. 앱이 해당 수신 주소로 실제 요청을 보내거나 요청이 내장 DNS로 가로채여야 설정이 적용됩니다. default-nameserver는 암호화 DNS 서비스 도메인을 조회할 때 초기 DNS로 사용할 수 있습니다. 커널이 지원하는 IP 형식의 상위 DNS 서버를 지정해 아직 연결되지 않은 도메인에 의존하는 상황을 피하세요.

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:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "localhost"

이 예시는 로컬 수신, 초기 조회, 노드 도메인 조회의 역할 분담을 보여 줍니다. 나열된 상위 DNS 서버가 현재 네트워크에 적합한지는 직접 테스트해야 합니다. 1053은 운영체제의 기본 DNS 포트가 아니므로 설정 파일에 적는 것만으로 모든 시스템 요청이 자동으로 전달되지는 않습니다. 표준 포트로 바꾸려면 권한, 기존 서비스의 포트 점유 여부, 시스템에서 DNS 주소를 지정하는 방식도 확인하세요.

fake-ip와 실제 주소 조회

fake-ip는 도메인에 매핑 주소를 할당합니다. 커널은 이를 통해 도메인 정보를 유지하고 연결을 설정할 때 실제 아웃바운드를 선택합니다. 도메인 기반 분기에 유용하지만, 일부 LAN 검색 기능이나 주소 비교, 실제 IP만 허용하는 프로그램에는 예외가 필요할 수 있습니다. 예시의 네트워크 대역은 내부 매핑용이며 원격 프록시 서버 주소가 아닙니다. 다른 기기의 게이트웨이로 직접 사용해서도 안 됩니다.

fake-ip-filter는 지정한 도메인이 매핑 절차를 우회하도록 합니다. 매칭 규칙은 현재 커널 문서에서 확인하고 라우팅 규칙의 DOMAIN-SUFFIX 문법과 혼동하지 마세요. 호환성 문제가 발생하면 해당 도메인에만 좁은 범위의 예외를 추가한 뒤 앱이 정상화되는지 확인하세요. 모든 도메인을 제외하면 선택한 향상 모드의 본래 기능이 사라집니다.

redir-host는 실제 조회 주소를 반환하므로 실제 IP에 의존하는 일부 앱에서 유용합니다. 다만 도메인과 IP의 연결 관계는 캐시, 앱 자체 조회, 요청 경로의 영향을 받을 수 있습니다. 두 모드의 차이는 속도 순위가 아닙니다. 트래픽 가로채기 방식과 앱 호환성에 맞춰 선택하세요. 모드를 바꾼 뒤에는 연결을 새로 만들고 운영체제와 앱에 남아 있는 DNS 캐시도 처리해야 합니다.

도메인별 상위 DNS 선택

nameserver-policy는 지정한 도메인에 사용할 DNS 서버를 선택합니다. 기업 내부 도메인은 기업 DNS가 필요한 경우가 많아 공용 DNS에 맡길 수 없습니다. LAN 기기 이름도 라우터에서만 조회할 수 있습니다. 아래 예시는 예약 도메인으로 구조를 보여 줍니다. 내부 주소는 현재 네트워크에서 실제로 사용할 수 있고 연결 가능한 DNS 서버 주소로 바꿔야 합니다.

dns:
  nameserver-policy:
    "+.corp.example":
      - 192.168.50.1

이 설정은 기존 dns 매핑에 병합해야 하며, 최상위 DNS 선언을 하나 더 만드는 것이 아닙니다. respect-rules를 설정해 DNS 연결이 라우팅 규칙을 따르게 할 때는 순환 의존성을 특히 주의하고 프록시 서버 도메인의 조회 경로를 명확히 지정해야 합니다. 초기 조회와 아웃바운드 의존성을 확인하기 전에는 모든 DNS 요청을 프록시 그룹으로 보내지 마세요.

일반 앱은 정상인데 보안 DNS를 사용하는 브라우저에서 문제가 다르게 나타난다면 브라우저가 자체 암호화 DNS를 직접 사용하는지 확인하세요. 이 경로는 예상한 시스템 DNS 설정을 우회할 수 있습니다. 먼저 테스트 앱 하나에서 조회 경로를 확인한 다음 앱 설정이나 가로채기 정책을 조정하세요. 여러 변수를 한꺼번에 변경하지 마세요.

프록시 노드와 프로토콜 필드

proxies는 사용할 수 있는 원격 아웃바운드를 정의하지만, 언제 어떤 노드를 선택할지는 지정하지 않습니다. 노드마다 고유한 이름, 올바른 프로토콜 유형, 서버 주소, 프로토콜에서 요구하는 인증 및 전송 매개변수가 필요합니다. 서버 주소와 비밀번호가 맞아도 설정이 완성된 것은 아닙니다. 전송 방식, TLS, 서버 이름, 경로가 일치하지 않으면 핸드셰이크가 실패할 수 있습니다.

기본 필드와 이름 참조

name은 설정 내부에서 참조하는 식별자이자 프록시 그룹과 화면에 표시되는 이름입니다. 중복되지 않도록 하고 안정적으로 유지하세요. server에는 서버 IP나 도메인을 입력하며 경로가 포함된 웹페이지 URL을 입력하면 안 됩니다. port에는 서버의 수신 포트를 입력하며 로컬 혼합 포트를 입력하는 것이 아닙니다. type은 나머지 필드의 해석 방식을 결정하므로 유형만 바꿔 한 프로토콜을 다른 프로토콜로 변환할 수는 없습니다.

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: proxy.example.net
    port: 443
    password: "your-password"
    sni: proxy.example.net
    skip-cert-verify: false
    udp: true

예시 도메인과 비밀번호는 필드 구조를 보여 주기 위한 값이며 실제 연결에 사용할 수 없습니다. Shadowsocks의 cipher와 비밀번호는 서버 설정과 일치해야 합니다. Trojan의 비밀번호, 서버 이름, 인증서 설정도 서버와 맞아야 합니다. 클라이언트 이름만 보고 프로토콜 매개변수를 추측하지 말고 서비스 제공업체의 연결 정보나 호환 구독을 기준으로 설정하세요.

필드확인할 항목
server / port원격 주소와 서버 수신 포트
password / uuid프로토콜에 맞는 인증 정보(서로 대체 불가)
sni / servername프로토콜 필드에 맞는 TLS 서버 이름
network / ws-opts전송 유형과 관련 경로 및 요청 헤더
udp노드 프로토콜, 원격 서버, 네트워크 경로의 호환 여부

TLS와 전송 매개변수

TLS 서버 이름은 연결 주소와 다를 수 있지만 서버 배포 및 인증서 요구사항과 일치해야 합니다. 프로토콜에 따라 sni 또는 servername을 사용할 수 있으므로 무조건 같은 이름으로 바꾸면 안 됩니다. 인증서 오류가 발생하면 먼저 기기 시간, 도메인 철자, 인증서 적용 범위, 서버 설정을 확인하세요. 인증서 검증을 끄면 신원 확인 기능이 약해지므로 일반적인 해결 방법으로 사용해서는 안 됩니다.

WebSocket 노드는 특정 경로와 Host 요청 헤더를 요구할 수 있고, gRPC 노드는 서비스 이름을 요구할 수 있습니다. 이런 매개변수는 임의로 조정하는 옵션이 아니라 핸드셰이크의 일부입니다. 노드 정보에 전송 방식이 명시되어 있다면 해당 중첩 옵션도 함께 확인하세요. 다른 노드의 경로를 복사하면 주소와 비밀번호가 같아도 요청이 거부될 수 있습니다.

프로토콜 호환성과 단계별 문제 해결

mihomo와 초기 Clash 커널은 지원하는 프로토콜과 확장 필드가 완전히 같지 않습니다. 한 클라이언트에서 구독을 가져올 수 있어도 다른 커널에서 모든 노드를 인식한다는 뜻은 아닙니다. 사용할 커널의 기능을 먼저 확인하고, 클라이언트가 해당 필드를 보존해 올바르게 전달하는지도 확인하세요. 클라이언트가 필요하면 클라이언트 다운로드 페이지를 방문하세요. 처음 설정하는 사용자라면 Clash Plus부터 살펴보는 것이 좋습니다.

문제 해결은 도메인 조회, TCP 또는 UDP 연결 가능 여부, 프로토콜 핸드셰이크, 인증, 대상 요청 순서로 진행하세요. 조회에 실패하면 DNS를, 연결이 거부되면 포트와 서버 상태를, TLS 오류가 나면 이름과 인증서를, 인증 실패 시에는 비밀번호나 식별 정보를 확인하세요. 매번 노드 전체를 삭제하고 다시 만들면 문제를 찾는 데 필요한 로그 단서를 잃기 쉽습니다.

udp: true는 해당 노드가 UDP를 처리하도록 허용할 뿐, 모든 트래픽 가로채기 방식에서 UDP를 자동 지원하지는 않습니다. HTTP 프록시를 통해 앱이 보내는 요청과 TUN이 받는 UDP 데이터의 경로는 다릅니다. 서버, 프로토콜 구현, 네트워크 방화벽도 트래픽을 제한할 수 있습니다. 테스트할 때는 웹페이지 연결 성공 여부만 보는 대신 앱이 실제로 어떤 프로토콜을 사용하는지 먼저 확인하세요.

프록시 그룹 유형과 선택 로직

proxy-groups는 노드를 선택 가능한 아웃바운드 집합으로 구성합니다. 규칙은 보통 변하지 않는 그룹 이름을 가리키고, 그룹에서 실제 노드를 결정합니다. 이렇게 하면 구독 업데이트 후 규칙을 하나씩 수정하지 않아도 됩니다. 프록시 그룹을 이해할 때는 수동 선택, 상태 점검, 실제 요청을 구분하세요. 테스트에 성공해도 모든 대상에 정상적으로 접속할 수 있다는 뜻은 아닙니다.

수동 선택과 자동 선택

select는 수동으로 선택하는 방식으로, 최상위 출구나 용도가 명확한 경우에 적합합니다. url-test는 주기적인 테스트 결과를 바탕으로 후보를 선택하며, tolerance는 미세한 차이로 인한 잦은 전환을 줄이는 데 사용할 수 있습니다. fallback은 목록의 우선순위에 따라 사용 가능한 항목을 선택하며 테스트 시간이 가장 짧은 항목을 우선하지 않습니다. 기본으로 사용할 경로를 고정해야 한다면 이 우선순위 차이를 먼저 고려하세요.

proxy-groups:
  - name: 자동 선택
    type: url-test
    proxies:
      - SS 예시
      - Trojan 예시
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true

  - name: 장애 조치
    type: fallback
    proxies:
      - SS 예시
      - Trojan 예시
    url: https://www.gstatic.com/generate_204
    interval: 300

  - name: 기본 출구
    type: select
    proxies:
      - 자동 선택
      - 장애 조치
      - DIRECT

이 예시는 앞 장에서 정의한 노드 이름을 참조합니다. 노드를 가져오지 않았다면 먼저 추가하거나 이미 있는 이름으로 바꾸세요. 테스트 URL은 실행 중 상태를 확인하기 위한 대상이지 페이지가 사용하는 리소스가 아닙니다. 현재 네트워크와 각 아웃바운드에서 적절한지 확인하세요. 대상마다 응답 방식이 다르므로 테스트 주소를 바꾸면 기존 테스트 결과를 직접 비교할 수 없습니다.

점검 간격과 사용 가능 여부의 의미

interval은 보통 초 단위이며, 자동 테스트 그룹의 tolerance는 일반적으로 전환 허용 오차를 밀리초 단위로 나타냅니다. 간격을 줄이면 점검 요청과 네트워크 활동이 늘어날 뿐 업무 트래픽의 안정성이 반드시 좋아지지는 않습니다. 모바일 기기에서는 백그라운드 실행과 배터리 사용량도 고려해야 합니다. 적절한 간격으로 먼저 관찰하고 필요한 장애 복구 조건에 맞춰 조정하세요. 모든 값을 무조건 작게 설정하지 마세요.

lazy는 지원 여부에 따라 사용하지 않는 그룹의 능동 점검을 줄일 수 있습니다. 따라서 화면을 막 열었을 때 새 점검 결과가 없다고 해서 노드가 고장 난 것은 아닙니다. 그룹 점검, 리소스 제공자 상태 확인, 사용자가 실행하는 노드 속도 측정은 서로 다른 방식으로 동작할 수 있습니다. 결과를 볼 때는 점검 대상, 마지막 실행 시간, 테스트 주소를 확인해 한 곳의 결과를 전체 상태로 오해하지 않도록 하세요.

유형선택 기준사용 범위
select사용자가 직접 선택선택한 항목이 작동하지 않으면 직접 처리하거나 자동 그룹을 참조해야 함
url-test테스트 결과와 전환 허용 오차테스트 대상이 모든 서비스 대상을 대표하지는 않음
fallback후보 순서와 사용 가능 여부목록 순서가 우선 항목과 대체 항목을 나타냄
load-balance선택한 부하 분산 방식여러 연결을 분산하며 단일 연결의 대역폭을 합치지는 않음

부하 분산과 중첩 참조

load-balance는 여러 연결을 분산하며 선택한 방식에 따라 대상 일관성을 유지하거나 후보 아웃바운드를 번갈아 사용합니다. 다운로드 연결 하나를 여러 경로로 나눠 속도를 합산하는 기능은 아닙니다. 출발지 주소에 민감한 로그인, 결제, 장시간 연결 서비스는 출구가 자주 바뀌면 추가 인증을 요구할 수 있습니다. 안정적인 그룹이나 별도 규칙을 사용하세요.

프록시 그룹은 다른 그룹을 참조할 수 있지만 구조는 단순하게 유지하고 순환 참조를 만들지 마세요. 예를 들어 기본 출구는 자동 선택 그룹을 참조할 수 있지만, 자동 선택 그룹이 다시 기본 출구를 참조해서는 안 됩니다. 그룹 이름을 노드 이름과 똑같이 지정하는 것도 피하세요. 설정 검토와 로그 확인이 어려워질 수 있습니다. 이름을 바꾼 뒤에는 규칙, 중첩 그룹, 오버라이드 스크립트에 남은 이전 참조도 함께 찾아 수정하세요.

화면에 이전 수동 선택이 계속 남아 있다면 클라이언트가 그룹 선택 상태를 저장하는지, 설정의 profile.store-selected가 상태 복원에 관여하는지 확인하세요. 파일의 첫 번째 후보가 현재 선택된 항목과 반드시 같지는 않습니다. 유형별 상세 비교와 설정 방법은 url-test, fallback, load-balance 설정 가이드를 참고하세요.

규칙 순서와 매칭 문법

rules는 보통 위에서 아래 순서로 매칭하며 가장 먼저 일치한 규칙이 아웃바운드를 결정합니다. 설정이 올바른데도 다른 경로를 이용한다면 대상 규칙이 존재하는지만 확인하지 말고 앞에 있는 광범위한 규칙부터 살펴보세요. 마지막 기본 규칙으로는 보통 MATCH를 사용합니다. 앞선 규칙에 일치하지 않은 요청을 모두 처리하므로 목록 중간에 두면 뒤의 일반 규칙은 실행되지 않습니다.

도메인 규칙과 주소 규칙

DOMAIN은 지정한 도메인과 일치하고, DOMAIN-SUFFIX는 해당 도메인과 하위 도메인에 일치하며, DOMAIN-KEYWORD는 도메인에 포함된 키워드로 매칭합니다. 키워드 규칙은 범위가 넓으므로 이미 알고 있는 도메인 목록을 대신하는 용도로는 적합하지 않습니다. 규칙의 대상에는 내장 아웃바운드, 노드 이름, 프록시 그룹 이름을 사용할 수 있습니다. 나중에 경로를 바꾸더라도 분기 로직을 수정하지 않도록 그룹 이름을 사용하는 것이 일반적입니다.

rules:
  - DOMAIN,router.lan,DIRECT
  - DOMAIN-SUFFIX,example.com,기본 출구
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - MATCH,기본 출구

예시는 몇 가지 일반적인 사설 주소 대역을 직접 연결로 보내고 나머지 요청은 기본 출구로 보냅니다. 모든 기기에 적용할 수 있는 완전한 LAN 규칙은 아닙니다. 기업 네트워크, 가상 네트워크 대역, 특수 라우팅에는 추가 설정이 필요할 수 있습니다. example.com은 예시 도메인입니다. 실제 분기 설정은 대상과 관련 도메인을 확인하며 단계적으로 추가하고, 범위가 넓은 키워드 규칙을 그대로 복사하지 마세요.

no-resolve와 도메인 정보

no-resolve는 주소 유형 규칙이 매칭을 위해 도메인 조회를 능동적으로 시작하지 않도록 합니다. 연결에 사용할 수 있는 대상 IP가 이미 포함되어 있다면 해당 주소 규칙에 계속 일치할 수 있습니다. DNS를 차단하는 옵션은 아닙니다. 도메인 요청에서 이 옵션을 사용할지에 따라 매칭 절차와 조회 비용이 달라지므로 모든 규칙에 붙이는 고정 접미사처럼 취급하지 마세요.

GEOIP는 주소 데이터베이스를 이용해 대상 IP의 지역을 판단하고, GEOSITE는 해당 도메인 분류 데이터와 커널 지원에 의존합니다. 데이터베이스의 분류가 서비스의 실제 운영 지역과 일치하는 것은 아니며 사이트의 모든 관련 도메인이 같은 분류에 포함된다고 보장할 수도 없습니다. 관련 데이터를 설정에서 참조한다면 파일 존재 여부, 적절한 출처, 업데이트 성공 여부를 확인하세요. 필드가 허용되었다는 사실만으로 데이터가 로드되었다고 판단하면 안 됩니다.

프로세스 규칙과 트래픽 가로채기 범위

프로세스 이름이나 경로를 기준으로 규칙을 적용하려면 현재 플랫폼과 트래픽 가로채기 방식에서 프로세스 정보를 제공해야 합니다. 라우터는 보통 LAN의 다른 기기에서 요청을 보낸 앱이 무엇인지 확인할 수 없습니다. 일부 모바일 운영체제에도 권한 제한이 있습니다. 이런 규칙을 사용하기 전에 연결 세부정보에서 프로세스 필드를 확인하고 이름과 전체 경로 중 무엇을 매칭할지 판단하세요. 앱 창 제목만 보고 값을 입력하지 마세요.

규칙은 이미 커널에 들어온 요청만 처리할 수 있습니다. 프로그램의 연결 기록이 전혀 없다면 도메인 규칙을 계속 추가하기보다 먼저 시스템 프록시, 앱 프록시 설정, TUN 라우팅을 확인하세요. 목록에 요청이 보인다면 대상 도메인, 대상 IP, 적용된 규칙, 최종 아웃바운드를 차례로 확인하세요. 노드를 계속 바꾸는 것보다 이 네 가지를 따라가며 원인을 찾는 편이 효과적입니다.

증상먼저 확인할 항목확인 방법
특정 규칙이 계속 적용되지 않음앞에 있는 광범위한 규칙 또는 먼저 나온 MATCH연결 세부정보에서 적용된 규칙 확인
도메인 규칙이 IP 요청에 적용되지 않음요청에 도메인 정보가 남아 있는지앱이 IP를 직접 사용하는지 도메인으로 요청하는지 구분
규칙을 바꿨는데 기존 페이지가 이전 출구를 계속 사용연결 재사용, 장시간 연결, 앱 캐시새 연결을 만든 뒤 다시 확인

규칙을 최소 범위로 검증하기

규칙을 검증할 때는 먼저 도메인 하나와 명확한 아웃바운드로 범위를 좁히고 적용 여부를 확인한 뒤 접미사나 규칙 세트로 확대하세요. 웹페이지는 정적 리소스, API, 인증 도메인에 동시에 요청하는 경우가 많습니다. 기본 도메인만 프록시로 보내면 일부 리소스가 다른 출구를 이용할 수 있습니다. 연결 기록을 확인해 필요한 관련 도메인을 추가하고, 알 수 없는 도메인을 모두 하나의 광범위한 규칙에 넣지 마세요.

규칙을 수정한 뒤 설정을 다시 불러오고 새 테스트 연결을 만드세요. 기존 HTTP 연결 재사용, 다운로드 작업, 실시간 통신 세션은 이전 아웃바운드를 계속 사용할 수 있으므로 새 규칙을 검증하는 유일한 기준으로 삼기 어렵습니다. 자주 발생하는 연결 문제는 FAQ 문제 해결에서 확인하세요. 트래픽 가로채기 방법은 사용 가이드의 순서를 따르세요.

리소스 제공자와 업데이트 방식

리소스 제공자는 자주 바뀌는 노드나 규칙을 기본 설정에서 분리해 주 설정 파일의 구조를 안정적으로 유지합니다. proxy-providers는 노드 리소스를 관리하고 rule-providers는 규칙 리소스를 관리합니다. 콘텐츠 형식과 참조 위치는 서로 다릅니다. 제공자 다운로드에 성공했다는 것은 파일을 가져왔다는 뜻일 뿐입니다. 콘텐츠 형식이 올바른지, 그룹이나 규칙에서 참조하는지, 현재 설정에서 실제로 적용되는지 확인해야 합니다.

노드 리소스와 구독 형식

노드 제공자에서 사용하는 YAML 리소스는 일반적으로 proxies를 기본 구조로 사용합니다. 전체 Clash 설정 파일, 개별 노드 리소스, Base64로 인코딩된 노드 링크 목록은 서로 다른 형식입니다. 일부 클라이언트에서 가져오기 변환을 지원하더라도 커널의 HTTP 제공자가 같은 원본 콘텐츠를 바로 파싱할 수 있다는 뜻은 아닙니다. 가져오기 전에 구독 URL, 로컬 YAML, Base64 형식 안내에서 리소스 유형을 확인하세요.

proxy-providers:
  원격 노드:
    type: http
    url: "https://subscription.example.com/nodes.yaml"
    path: ./providers/nodes.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

proxy-groups:
  - name: 구독 노드 선택
    type: select
    use:
      - 원격 노드

예시 주소는 서비스 제공업체가 제공하는 호환 리소스로 바꿔야 합니다. path는 로컬 캐시 위치를 뜻합니다. 상대 경로는 보통 커널 작업 디렉터리나 클라이언트가 지정한 데이터 디렉터리를 기준으로 하며 웹페이지 디렉터리를 기준으로 하지 않습니다. 디렉터리에 쓰기 권한이 없거나 여러 제공자가 같은 경로를 사용하면 업데이트나 캐시에 문제가 생길 수 있습니다. 리소스마다 파일 이름을 따로 지정하면 덮어쓰기와 문제 해결을 줄일 수 있습니다.

바깥쪽 interval은 리소스 업데이트 주기를, health-check.interval은 노드 점검 주기를 제어합니다. 보통 둘 다 초 단위지만 용도는 다릅니다. 구독이 업데이트되지 않았다고 상태 점검이 실행되지 않은 것은 아니며, 상태 점검에 성공했다고 구독 내용이 새로 고쳐진 것도 아닙니다. 화면에서 업데이트 시간과 점검 결과를 각각 확인하고 하나로 다른 하나를 추정하지 마세요.

규칙 리소스와 behavior

규칙 제공자는 콘텐츠 형식, format, behavior가 서로 맞아야 합니다. domain은 도메인 목록에, ipcidr은 주소 대역 목록에, classical은 규칙 유형이 포함된 항목에 적합합니다. 아무 파일에나 맞추려고 behavior 이름만 바꾸지 마세요. 실제 콘텐츠가 다르면 올바르게 변환하거나 그 형식에 맞는 설정을 선택해야 합니다.

rule-providers:
  로컬 직접 연결:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/local-direct.yaml

rules:
  - RULE-SET,로컬 직접 연결,DIRECT
  - MATCH,기본 출구

해당 local-direct.yaml에는 매칭 조건만 넣고 각 항목에 아웃바운드를 반복해서 지정하지 않습니다. 아웃바운드는 기본 설정의 RULE-SET 행에서 지정합니다. 아래 파일은 classical YAML의 기본 구조를 보여 주며 선언한 경로에 실제로 저장해야 합니다. 규칙 세트 내부의 순서와 기본 설정에서 참조하는 위치를 모두 명확하게 유지하세요.

payload:
  - DOMAIN,router.lan
  - IP-CIDR,192.168.0.0/16,no-resolve

업데이트 의존성과 오프라인 캐시

원격 리소스를 업데이트하려면 이름 조회와 네트워크 경로도 정상적으로 작동해야 합니다. 첫 실행 때 리소스 다운로드에 아직 확보하지 못한 노드가 필요하면 시작 의존성이 순환될 수 있습니다. 연결 가능한 업데이트 경로나 유효한 캐시를 보존하고 클라이언트와 커널의 지원 여부에 맞춰 다운로드 경로를 설정하세요. 원격 리소스에 접근할 수 있는지 확인하기 전에 사용할 수 있는 유일한 로컬 노드와 캐시 파일을 삭제하지 마세요.

업데이트에 실패하면 HTTP 상태 코드, 응답 콘텐츠 유형, 파싱 오류, 로컬 파일 쓰기 권한을 각각 확인하세요. 서버가 로그인 페이지나 오류 페이지를 반환하면 파일은 다운로드되더라도 유효한 노드나 규칙 리소스가 아닐 수 있습니다. 구독 링크에는 접근 정보가 들어 있을 수 있으므로 신뢰할 수 있는 클라이언트나 관리되는 환경에서만 사용하고, 출처를 알 수 없는 온라인 변환 서비스에 제출하지 마세요.

오버라이드, 병합, 적용 여부 확인

구독은 원격 콘텐츠를 제공하고 오버라이드는 로컬 설정을 유지하도록 분리하는 것이 좋습니다. 구독에서 생성한 파일을 직접 수정하면 다음 업데이트 때 변경 내용이 사라질 수 있습니다. 완전히 독립된 로컬 설정으로 복사하면 노드 변경을 직접 관리해야 합니다. 구독에서 관리할 필드와 로컬 설정이 맡을 필드를 구분한 다음 최종 실행 설정이 예상대로 적용되었는지 확인하세요.

필드 소유권과 병합 순서

클라이언트는 구독을 읽은 다음 화면 설정을 병합하고 마지막으로 규칙 패치나 스크립트를 실행할 수 있습니다. 구체적인 순서는 클라이언트마다 다릅니다. 모든 클라이언트가 같은 오버라이드 파일을 지원한다고 가정하거나 다른 클라이언트의 스크립트 문법을 YAML에 그대로 넣지 마세요. Clash Plus, Clash Verge Rev 등의 설정 메뉴는 실제 화면에서 확인해야 합니다. 커널 자체가 모든 클라이언트의 병합 확장을 해석하는 것은 아닙니다.

스칼라, 매핑, 목록은 각각 다르게 처리해야 합니다. 포트 같은 스칼라 값은 보통 나중 값으로 바뀝니다. DNS 매핑은 키 단위로 병합되거나 전체가 교체될 수 있습니다. 규칙과 프록시 그룹 목록은 덮어쓰기, 추가, 앞쪽 삽입 방식으로 처리될 수 있습니다. 병합 도구가 명확히 보장하지 않는 한 배열이 자동으로 중복 제거된다고 추정하지 마세요. 같은 이름의 노드가 이름을 기준으로 안전하게 합쳐진다고 생각해서도 안 됩니다.

설정 객체일반적인 위험확인할 사항
수신 포트화면 설정이 파일 값을 덮어씀실제 수신 포트와 시스템 프록시 설정 일치 여부
DNS 매핑부분 패치로 다른 키가 손실됨조회 경로에 필요한 모든 필드 유지
규칙 목록MATCH 뒤에 추가됨사용자 지정 규칙이 유효한 매칭 위치에 있는지
노드와 프록시 그룹이름이 중복되거나 삭제된 객체를 참조함이름이 고유하고 참조가 모두 유효한지

우선 규칙과 안정적인 참조

사용자 지정 규칙은 일반적으로 파일 끝에 추가하지 말고 구독의 기본 규칙보다 앞에 삽입해야 합니다. 클라이언트에서 우선 규칙 메뉴를 제공한다면 아래 두 줄로 LAN 직접 연결 의도를 표현할 수 있습니다. 이 항목들은 규칙 목록의 구성 요소이지 범용 오버라이드 파일 형식은 아닙니다. 바깥쪽 구조는 현재 클라이언트의 병합 방식에 맞춰 작성해야 합니다.

- DOMAIN,router.lan,DIRECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

로컬 규칙은 가능한 한 안정적인 그룹 이름을 참조하세요. 구독 업데이트로 그룹이 삭제되거나 이름이 바뀌면 기존 규칙이 로드되지 않을 수 있습니다. 자주 바뀌는 노드 이름을 규칙에 직접 지정하면 관리 부담이 커집니다. 로컬에서 고정된 진입점을 유지해야 한다면 클라이언트가 지원하는 오버라이드 계층에서 자체 그룹을 만들고 구독 제공자를 참조하세요. 단, 제공자 이름에도 안정적인 출처가 있는지 확인해야 합니다.

저장, 확인, 다시 불러오기

수정을 적용하기 전에 현재 정상 작동하는 설정과 오버라이드 설정을 복사해 보관하세요. 한 번에 하나의 기능 영역만 수정합니다. 예를 들어 먼저 포트를 변경하고 확인한 다음 DNS를 조정하세요. 커널 명령줄 환경을 사용할 수 있다면 테스트 모드로 설정을 검증할 수 있습니다. 데스크톱 클라이언트에도 자체 검사 기능이 있을 수 있습니다. 아래 명령을 실행할 때는 작업 디렉터리가 리소스 상대 경로의 실제 기준 디렉터리와 일치해야 합니다.

mihomo -t -d ./profile -f ./profile/config.yaml

테스트를 통과했다는 것은 현재 테스트 환경에서 설정을 받아들일 수 있다는 뜻일 뿐, 모든 원격 서비스에 연결되거나 클라이언트 실행 중 필드가 덮어쓰이지 않는다는 뜻은 아닙니다. 외부 리소스에 의존한다면 파일 위치와 사용 가능 여부를 확인하세요. 그런 다음 클라이언트에서 설정을 다시 불러오고 시작 로그에서 포트 수신, DNS 초기화, 제공자 로드 오류를 확인한 뒤 새 업무 연결을 만들어 보세요.

롤백과 문제 기록

설정을 다시 불러오는 데 실패해도 클라이언트는 이전 설정을 계속 사용하고 있을 수 있습니다. 화면에서 인터넷에 연결된다고 해서 새 파일이 적용되었다는 뜻은 아닙니다. 오류 알림과 현재 활성 상태를 확인하세요. 원인을 파악하기 어렵다면 최근에 정상 작동했던 복사본으로 되돌린 뒤 변경 사항을 하나씩 다시 적용하세요. TUN, 시스템 프록시, DNS를 변경했다면 롤백 과정에서 시스템 설정도 복원되었는지 확인해야 합니다. 파일만 되돌리고 네트워크 가로채기 설정은 새 상태로 남을 수 있습니다.

효과적인 문제 기록에는 사용 중인 클라이언트와 커널 이름, 트래픽 가로채기 방식, 문제가 발생한 필드 일부, 로그에서 처음 나타난 관련 오류, 재현 전후의 변경 사항이 포함되어야 합니다. 단순히 연결이 안 된다고만 적지 말고 민감한 구독 전체를 제출하지도 마세요. 일반적인 문제는 FAQ를 먼저 확인하세요. 설치와 가져오기 절차를 다시 확인해야 한다면 빠른 시작 가이드로 돌아가면 됩니다. 문제 해결을 위해 전체 환경을 반복해서 재설치할 필요는 없습니다.