Clash, Clash Meta, mihomo와 클라이언트부터 구분하기
기존 Clash는 일반적으로 Dreamacro 프로젝트가 배포한 Clash 코어를 가리킵니다. YAML 설정을 읽어 HTTP, SOCKS 또는 mixed 수신 포트를 만들고, 프록시 그룹과 규칙에 따라 연결 경로를 결정합니다. Clash Meta는 이 설정 방식을 기반으로 확장된 코어 분기로, 이후 mihomo라는 프로젝트명을 사용하게 되었습니다. 실제로 마이그레이션할 때는 “Clash Meta 설정”과 “mihomo 설정”을 같은 기술 계열의 서로 다른 단계로 이해할 수 있지만, 모든 버전이 완전히 호환된다고 단정해서는 안 됩니다.
Clash Verge Rev, FlClash 같은 그래픽 클라이언트는 설정 가져오기, 시스템 프록시 전환, 로그 표시 및 코어 관리를 담당합니다. 프로토콜, DNS, 규칙과 TUN 인계는 mihomo 코어가 실행합니다. 구독 서비스는 노드와 정책 설정을 제공합니다. 이 세 가지는 각각 화면 계층, 실행 계층, 설정 출처에 해당하므로 문제를 진단할 때는 먼저 오류가 어느 계층에서 발생했는지 확인해야 합니다.
현재 실행 중인 코어를 명령줄에서 확인하기
명령줄로 배포했다면 먼저 버전을 조회하세요. 빌드마다 추가 출력 정보는 다를 수 있지만, 결과에서 mihomo 이름, 버전, 대상 운영체제와 프로세서 아키텍처를 확인할 수 있어야 합니다.
mihomo -v예를 들어 어떤 시스템에서는 Mihomo Meta v1.19.3 linux amd64가 표시될 수 있습니다. 여기서 v1.19.3은 버전 정보를 읽는 방법을 설명하기 위한 예시일 뿐, 모든 기능에 적용되는 공통 최소 요구 사항은 아닙니다. 프로토콜, 설정 필드와 기본 동작은 릴리스 버전에 따라 달라지므로, 마이그레이션 전에는 현재 바이너리의 버전 정보와 해당 릴리스 안내를 기준으로 확인해야 합니다.
시스템에 아직 clash라는 이름의 기존 실행 파일을 사용하고 있다면 clash -v도 한 번 실행하세요. 새 파일의 이름만 기존 이름으로 바꾼다고 해서 기존 코어가 mihomo로 업그레이드되는 것은 아닙니다. 판단 기준은 파일명이 아니라 프로그램 출력과 실제 프로세스 경로여야 합니다.
프로토콜과 규칙 지원에서 실제로 달라지는 점
기존 Clash는 Shadowsocks, VMess, Trojan, HTTP, SOCKS5 등 일반적인 프록시 유형을 지원하며 DIRECT, REJECT, 프록시 그룹, 규칙 모드와 기본 DNS 기능을 제공합니다. mihomo는 이러한 설정 구조를 이어받으면서 VLESS, Reality, Hysteria2, TUIC, WireGuard 등의 기능을 추가하거나 확장했습니다. 특정 프로토콜을 사용할 수 있는지는 코어 버전, 구독 생성 방식, 서버 매개변수가 완전한지에 따라 달라집니다.
| 점검 항목 | 기존 Clash의 일반적인 기능 | mihomo 마이그레이션 시 중점 사항 |
|---|---|---|
| 프록시 프로토콜 | SS, VMess, Trojan, HTTP, SOCKS5 등 | 이를 바탕으로 VLESS, Reality, Hysteria2, TUIC, WireGuard 등의 필드 확인 |
| 규칙 유형 | DOMAIN, DOMAIN-SUFFIX, IP-CIDR, GEOIP, MATCH 등 | GEOSITE, RULE-SET, 논리 규칙과 프로세스 규칙의 버전 지원 여부를 추가로 확인 |
| DNS | 기본 nameserver, fallback, fake-ip 등 | nameserver-policy, 프록시 노드 도메인의 해석 경로와 세분화된 분기 제어 추가 |
| 트래픽 인계 | 시스템 프록시 및 일부 투명 프록시 환경 | TUN stack, 자동 라우팅, 인터페이스 식별과 DNS 가로채기를 중점적으로 확인 |
| 데이터 세트 | GEOIP 및 규칙 파일 | geodata 형식, 다운로드 출처, 업데이트 시점과 규칙 이름 확인 |
프로토콜 이름이 같아도 매개변수를 그대로 재사용할 수 있는 것은 아닙니다
마이그레이션에서 가장 흔한 오판은 “구독에 노드가 보이니 반드시 연결된다”는 생각입니다. 클라이언트가 YAML을 성공적으로 해석했다는 것은 설정 형식을 대체로 읽을 수 있다는 뜻일 뿐, 핸드셰이크 매개변수가 올바르다는 의미는 아닙니다. 예를 들어 VLESS Reality에는 보통 서버 이름, 공개 키, 짧은 ID, 클라이언트 지문과 흐름 제어 매개변수가 필요합니다. Hysteria2는 서버 주소, 인증 정보, TLS 서버 이름과 인증서 검증 설정을 확인해야 합니다. 필드가 빠져도 노드가 목록에 표시될 수 있지만, 연결 로그는 핸드셰이크 단계에서 실패합니다.
- 처음에는 확실히 작동하는 노드 하나를 선택하고, 자동 속도 측정 그룹을 통한 간접 테스트는 피하세요.
- 로그 수준을 일시적으로
debug로 설정하고 대상 연결을 한 번 완료한 뒤 핸드셰이크 오류를 즉시 확인하세요. - 시간 초과, DNS 해석 실패, TLS 이름 불일치와 인증 실패를 구분하세요. 각각 해결 방향이 다릅니다.
- 구독 변환기가 필드를 바꿀 수 있으므로 필요하면 구독 원본과 클라이언트가 저장한 설정을 대조하세요.
규칙은 여전히 위에서부터 순서대로 실행됩니다
mihomo도 규칙 모드의 핵심 원칙은 바꾸지 않았습니다. 위에서 아래로 평가하며, 처음 일치하는 규칙이 연결 경로를 결정합니다. 마이그레이션 후 “모든 트래픽이 프록시로 연결되거나” “특정 도메인이 직접 연결되지 않는” 문제가 생기면 먼저 규칙 순서를 확인하세요. 노드를 계속 바꾸는 것이 우선은 아닙니다.
mode: rule
rules:
- DOMAIN-SUFFIX,example.org,DIRECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- DOMAIN,blocked.example,REJECT
- MATCH,PROXY여기서 PROXY는 설정에 이미 정의된 정책 그룹이어야 하며, 코어에 내장된 출구가 아닙니다. no-resolve는 이 IP 규칙을 매칭할 때 도메인을 적극적으로 IP로 해석하지 않는다는 뜻이지, 모든 DNS를 끈다는 의미는 아닙니다. 기존 설정에 PROXY라는 정책 그룹이 없다면 테스트 단계에서 참조 오류를 먼저 표시해야 하며, 연결 단계까지 기다려서는 안 됩니다.
DNS 설정이 마이그레이션에서 위험도가 높은 이유
기존 Clash 설정을 mihomo로 옮긴 뒤 프록시 노드가 연결되더라도 웹페이지가 느리게 열리거나, 로컬 네트워크 도메인이 작동하지 않거나, 중국 본토와 해외의 해석 결과가 예상과 다르거나, TUN을 켠 후 DNS가 전혀 작동하지 않을 수 있습니다. 이런 문제는 대개 프로토콜 비호환이 아니라 시스템 DNS, mihomo DNS, 프록시 노드 도메인 해석과 fake-ip 매핑 사이에 잘못된 경로가 생겨서 발생합니다.
fake-ip와 redir-host 이해하기
enhanced-mode: fake-ip는 먼저 애플리케이션에 예약 주소를 반환한 뒤, 코어가 도메인 매핑을 저장하고 연결을 인계할 때 실제 대상 주소로 복원합니다. 흔히 사용하는 주소 풀은 198.18.0.1/16입니다. 도메인 규칙으로 처리해야 하는 환경에 적합하지만, 로컬 네트워크 검색, 프린터, 일부 게임 플랫폼 또는 인증서와 주소를 직접 검증하는 애플리케이션은 필터 목록에 추가해야 할 수 있습니다.
redir-host는 실제 주소를 먼저 해석한 뒤 연결을 처리하는 방식에 가깝습니다. fake-ip가 로컬 네트워크 애플리케이션에 미치는 영향은 줄어들지만, 도메인 규칙 매칭, 해석 지연과 캐시 동작은 달라집니다. 마이그레이션할 때 특정 템플릿이 fake-ip를 사용한다는 이유만으로 기존 설정을 덮어쓰지 말고, 현재 인계 방식과 애플리케이션 요구 사항을 먼저 확인하세요.
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
- 1.1.1.1
fake-ip-filter:
- "*.lan"
- "localhost.ptlogin2.qq.com"이 예시는 DNS 수신을 127.0.0.1:1053으로 제한해 포트와 수신 주소의 관계를 설명합니다. TUN의 DNS 가로채기로 요청을 인계한다면 설정을 클라이언트가 생성한 TUN 구간과 함께 맞춰야 합니다. 1053 포트는 필수값이 아니며 운영체제의 DNS를 자동으로 변경하지도 않습니다.
프록시 노드 도메인은 별도로 고려해야 합니다
프록시 서버 주소 자체가 도메인으로 입력되어 있다면 코어는 프록시 연결을 수립하기 전에 해당 도메인을 먼저 해석해야 합니다. 이 해석 요청이 아직 연결되지 않은 프록시로 다시 전달되면 시작 단계에서 순환이 발생할 수 있습니다. mihomo 설정에서는 proxy-server-nameserver로 프록시 노드 도메인을 해석할 서버를 지정하고, nameserver-policy로 특정 도메인의 해석 경로를 선택할 수 있습니다.
dns:
enable: true
enhanced-mode: fake-ip
nameserver:
- https://dns.alidns.com/dns-query
proxy-server-nameserver:
- 223.5.5.5
nameserver-policy:
"geosite:cn":
- https://dns.alidns.com/dns-query이 설정은 필드 간 관계만 보여 주며 완전한 프록시, 정책 그룹과 규칙 정의는 포함하지 않습니다. 암호화된 DNS를 사용할 때는 해당 도메인이 초기 해석을 완료할 수 있는지도 확인해야 합니다. 마이그레이션 후 로그에 DNS 시간 초과가 계속 나타나면 먼저 일반 IP DNS로 기본 경로를 검증한 다음 DoH, 정책 기반 해석과 규칙 연동을 하나씩 복원하세요. 여러 변수를 한꺼번에 바꾸지 않는 것이 좋습니다.
TUN 모드 마이그레이션 시 권한, 라우팅과 인터페이스 확인
시스템 프록시는 시스템 프록시 설정을 읽는 애플리케이션에만 영향을 줍니다. 터미널 명령, 게임, 가상 머신과 일부 업데이트 프로그램은 시스템 프록시를 우회할 수 있으므로, mihomo로 마이그레이션할 때 TUN을 함께 활성화하는 사용자가 많습니다. TUN은 가상 네트워크 인터페이스를 만들고 라우팅을 변경해 더 넓은 범위를 처리하지만, 운영체제 권한과 라우팅 설정에 더 크게 의존합니다.
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53stack의 사용 가능한 값과 동작은 현재 mihomo 버전에 따라 확인해야 하며, 흔히 system, gvisor, mixed를 선택합니다. 마이그레이션할 때는 먼저 클라이언트 기본값을 유지하고 로그를 보며 호환성 문제를 처리하세요. 라우터용 템플릿을 데스크톱 시스템에 그대로 복사하면 인터페이스 이름, 라우팅 테이블 또는 DNS 가로채기 방식까지 함께 적용되어 네트워크가 끊길 수 있습니다.
순서대로 TUN 문제 범위 좁히기
- TUN을 끄고 mixed 포트만 활성화해 프록시 노드 자체가 작동하는지 확인하세요.
- 수신 포트를 확인하세요. 일반적인 예시는
mixed-port: 7890이며, 브라우저에서 HTTP와 SOCKS5 프록시를 일시적으로127.0.0.1:7890으로 설정할 수 있습니다. - TUN을 활성화한 뒤 클라이언트에 가상 인터페이스 생성과 라우팅 변경에 필요한 권한이 부여되었는지 확인하세요.
- VPN, 가상 머신 네트워크, 게임 가속기 또는 다른 투명 프록시가 동시에 실행 중인지 확인하세요.
- IP와 도메인을 각각 테스트하세요. IP에는 연결되지만 도메인이 실패한다면 먼저 DNS 설정을 다시 확인하세요.
- 로컬 네트워크 장치에 접속해 사설 주소 규칙이 최종 규칙보다 앞에 있는지 확인하세요.
Windows에서는 일반적으로 클라이언트가 권한 요청을 처리합니다. macOS에서는 VPN 구성이나 네트워크 확장 승인 과정이 필요할 수 있습니다. Linux 서비스 배포에서는 서비스 사용자, 네트워크 권한과 라우팅 작업 권한을 확인해야 합니다. 이러한 과정은 클라이언트마다 다르게 구성되어 있으므로, 특정 클라이언트의 메뉴 스위치를 mihomo 코어의 공통 설정 필드로 간주해서는 안 됩니다.
기존 설정을 mihomo로 옮기는 재현 가능한 단계
1단계: 기존 파일과 실행 정보 보존
현재 config.yaml, 규칙 세트, 로컬 오버라이드와 클라이언트 설정 디렉터리를 복사하고, 기존 코어 버전, 시스템 프록시 포트, 제어 포트, TUN 상태 및 정상 작동하는 노드를 기록하세요. 구독 주소는 공개 로그나 스크린샷에 남기지 않아야 합니다. 클라이언트에서 여러 설정을 지원한다면 실제 적용 중인 파일이 무엇인지 명확히 확인해 선택되지 않은 파일을 수정하는 일이 없도록 하세요.
2단계: 먼저 정적 설정 테스트
mihomo는 서비스 시작 전에 YAML 문법, 정책 그룹 참조와 일부 필드 오류를 확인할 수 있는 설정 테스트 매개변수를 제공합니다. 설정 파일이 현재 디렉터리에 있다고 가정하면 다음 명령을 실행할 수 있습니다.
mihomo -t -f config.yaml테스트 통과는 코어가 설정을 불러올 수 있다는 뜻일 뿐, 모든 노드가 연결되거나 원격 규칙 세트를 반드시 내려받을 수 있다는 의미는 아닙니다. 테스트가 실패하면 첫 번째 오류부터 수정하세요. 뒤따르는 오류는 앞선 들여쓰기나 필드 구조 문제로 연쇄적으로 발생했을 수 있습니다.
3단계: 최소 설정으로 수신 포트 확인
마이그레이션할 때는 프록시 하나, 정책 그룹 하나와 소수의 규칙만 일시적으로 남기고 mixed 포트를 7890, 제어 인터페이스를 127.0.0.1:9090으로 제한할 수 있습니다. 외부 제어 인터페이스를 활성화했다면 접근 키도 설정하고, 클라이언트에 입력한 주소, 포트와 키가 일치하는지 확인하세요.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
secret: "change-this-local-secret"여기서 키는 예시 값이므로 실제 설정에서는 교체해야 합니다. 제어 포트는 관리 화면에서 상태를 읽고 정책을 전환할 때만 사용하며 웹 프록시 트래픽을 전달하지 않습니다. 브라우저 프록시를 9090으로 지정해도 올바르게 작동하지 않습니다.
4단계: 규칙 세트, DNS와 TUN을 차례로 복원
“노드 연결 → 정책 그룹 → 로컬 규칙 → 원격 규칙 세트 → DNS → TUN” 순서로 복원하는 것이 좋습니다. 각 계층을 추가할 때마다 도메인 접속, IP 접속, 로컬 네트워크 접속과 로그를 확인하세요. 이렇게 하면 문제가 발생해도 한 단계만 되돌리면 됩니다.
- 규칙 제공자:
behavior, 파일 형식, 업데이트 간격과 참조 이름을 확인하세요. - 지리 데이터: GEOIP, GEOSITE 데이터 파일을 현재 코어가 읽을 수 있는지 확인하세요.
- 정책 그룹: 규칙 대상 이름과
proxy-groups이름이 완전히 일치하는지 확인하세요. - 구독 오버라이드: 클라이언트가 구독을 갱신할 때 로컬 DNS 또는 TUN 설정을 덮어쓰는지 확인하세요.
- 로컬 네트워크: 다른 장치의 연결이 필요할 때만
allow-lan을 활성화하고 수신 주소와 방화벽을 설정하세요.
일반적인 마이그레이션 증상과 점검 항목
| 증상 | 우선 확인할 항목 | 확인 방법 |
|---|---|---|
| 설정을 시작할 수 없음 | YAML 들여쓰기, 알 수 없는 구조, 정책 그룹 참조 | mihomo -t -f config.yaml을 실행하고 첫 번째 오류부터 수정하세요 |
| 노드는 표시되지만 연결 시간 초과 | 서버 주소 해석, 포트, 방화벽, 프로토콜 매개변수 | debug 로그를 확인해 DNS, TCP, TLS와 인증 단계의 문제를 구분하세요 |
| 브라우저는 정상인데 터미널은 실패 | 터미널이 시스템 프록시를 읽지 않음 | HTTP_PROXY, HTTPS_PROXY 또는 ALL_PROXY를 일시적으로 설정한 뒤 다시 테스트하세요 |
| TUN을 켠 후 도메인 접속 실패 | DNS 수신, 가로채기 규칙, 포트 충돌 | 대상 IP와 도메인을 각각 테스트하고 53, 1053 등의 포트 사용 여부를 확인하세요 |
| 로컬 네트워크 장치에 연결할 수 없음 | 사설 주소 규칙, TUN 자동 라우팅, 인터페이스 식별 | RFC 1918 주소 대역이 MATCH보다 먼저 DIRECT로 처리되는지 확인하세요 |
| 구독 업데이트 후 설정이 원래대로 돌아감 | 구독 내용과 로컬 오버라이드의 우선순위 | 업데이트 전후의 저장된 설정을 대조하고 DNS와 TUN을 오버라이드 계층으로 옮기세요 |
터미널에서 테스트할 때는 프록시를 명시적으로 지정해 “터미널이 시스템 프록시를 읽지 않는다”는 문제를 코어 오류로 오인하지 않도록 하세요. 예를 들어 mixed 포트가 7890이면 SOCKS5를 지원하는 도구를 socks5h://127.0.0.1:7890에 연결할 수 있습니다. 이 방식은 프록시 측에서 도메인을 해석하므로 mihomo의 도메인 규칙 경로를 확인하는 데 더 적합합니다.
마이그레이션 완료 후 검수 기준
마이그레이션 완료 여부를 클라이언트 트레이 아이콘 색상만으로 판단해서는 안 됩니다. 최소한 다음을 확인해야 합니다. 설정 테스트 통과, 선택한 노드 연결 성공, DIRECT와 프록시 규칙의 정상 매칭, REJECT 규칙의 실제 차단, DNS의 지속적인 시간 초과 여부, 시스템 프록시와 TUN 적용 범위가 예상과 일치하는지, 구독 업데이트 후 로컬 오버라이드가 유지되는지 확인하세요.
- 현재 mihomo 버전과 클라이언트 버전을 기록해 이후 업그레이드 시 비교할 수 있도록 하세요.
- 로그에서 직접 연결 요청 하나, 프록시 연결 요청 하나와 거부 요청 하나의 규칙 매칭 결과를 확인하세요.
- 시스템 프록시를 끈 뒤에도 TUN이 예상대로 트래픽을 인계하는지 확인하고, TUN을 끈 뒤에는 mixed 포트를 독립적으로 사용할 수 있는지 확인하세요.
- 구독을 한 번 업데이트하고 설정을 다시 불러온 뒤 정책 그룹 이름, DNS와 규칙 제공자가 덮어써지지 않았는지 확인하세요.
- 클라이언트나 시스템을 재시작해 코어, 설정과 권한 상태가 정상적으로 복원되는지 확인하세요.