배경: Clash Meta는 왜 mihomo로 이름을 바꿨을까요?

Clash Meta를 오랫동안 사용해 오셨다면 2023년 말부터 2024년 초 사이에 일어난 일련의 변화를 기억하실 겁니다. 원조 Clash 프로젝트가 공식적으로 아카이브 처리되어 더 이상 유지보수가 이루어지지 않게 되었고, 커뮤니티 주도로 빠르게 발전해 온 Clash Meta는 활발한 개발 끝에 2024년 mihomo라는 새로운 이름으로 정식 출범하게 되었습니다. 이름만 바뀐 것이 아니라 내부 아키텍처도 대폭 개편되었는데, 주요 변경 사항은 다음과 같습니다:

  • 코어 코드베이스가 독립 저장소로 이전되어 구버전 Clash 코드와 완전히 분리
  • YAML 설정 형식은 하위 호환성을 유지하면서 대거 새로운 필드가 추가됨
  • DNS 모듈 전면 재작성으로 DoH3, QUIC 등 최신 프로토콜 지원
  • 규칙 엔진에 rule-set 외부 규칙 집합 개념이 도입되어 성능이 크게 향상
  • TUN 모드(Mixed Port)의 안정성이 대폭 향상되었으며 IPv6도 지원

구버전 Clash.Meta(v1.x 시절) 설정 파일을 그대로 사용하고 계신 분들에게는 mihomo로의 전환이 단순히 실행 파일만 교체하는 것으로 끝나지 않습니다. 일부 설정 필드가 더 이상 지원되지 않거나 동작 방식이 변경되었기 때문에, 그냥 덮어쓰면 프록시가 작동하지 않거나 시작 자체가 실패할 수 있습니다. 이 가이드에서는 마이그레이션 과정에서 반드시 확인하고 수정해야 할 항목들을 체계적으로 정리해 드립니다.

마이그레이션 전 준비 사항

기존 설정 파일 백업

어떤 변경 작업을 시작하기 전에, 반드시 config.yaml과 커스텀 규칙 파일들을 안전한 곳에 백업해 두세요. mihomo의 설정 파일 기본 경로는 다음과 같습니다:

  • Windows: %USERPROFILE%\.config\mihomo\config.yaml
  • macOS / Linux: ~/.config/mihomo/config.yaml
업그레이드 전에 반드시 설정 파일을 안전한 위치에 복사해 두세요. 마이그레이션 도중 문제가 생기더라도 언제든지 이전 설정으로 돌아가 구버전 코어를 다시 실행할 수 있습니다.

현재 코어 버전 확인

터미널에서 아래 명령어를 실행하면 현재 사용 중인 Clash / Clash.Meta의 버전을 확인할 수 있습니다: 

# For old Clash / Clash.Meta binary
./clash -v

# For mihomo binary
./mihomo -v

출력 결과에 mihomo라는 문자열이 포함되어 있다면 이미 새 코어를 사용하고 있는 것입니다. 이 경우 마이그레이션 섹션은 건너뛰고 신기능 활성화 섹션부터 읽으시면 됩니다.

설정 파일 호환성 점검

mihomo는 대부분의 상황에서 구버전 Clash.Meta의 YAML 형식과 하위 호환성을 유지합니다. 하지만 아래 항목들은 꼼꼼하게 확인해야 합니다:

더 이상 지원되지 않거나 변경된 필드

구버전 필드 / 값 mihomo 대체 방법 비고
clash-for-android 필드 그룹 삭제됨 구버전 CFA 사용자에게만 해당, mihomo는 무시함
external-controller: 0.0.0.0:9090 호환성 유지, 127.0.0.1:9090으로 변경 권장 모든 인터페이스 리슨은 보안 위험이 있음
dns.enhanced-mode: redir-host dns.enhanced-mode: fake-ip 또는 normal redir-host 모드는 deprecated 처리됨
proxy-groups의 type: fallback 계속 지원되나 type: url-test + lazy: true로 변경 권장 동작 방식에 미묘한 차이가 있으니 테스트 필요
rules에 대량의 도메인 규칙을 직접 작성 rule-providers 외부 규칙 집합으로 이전 인라인 규칙이 너무 많으면 시작 속도가 크게 느려짐

TUN 설정 섹션의 변화

기존에 TUN 모드를 사용하고 계셨다면, 구버전 설정과 mihomo 신버전 간에 눈에 띄는 차이가 있습니다. 구버전 설정 예시는 다음과 같습니다: 

# Old Clash.Meta TUN config
tun:
  enable: true
  stack: system
  dns-hijack:
    - 198.18.0.2:53
  auto-route: true
  auto-detect-interface: true

mihomo에서 권장하는 새로운 설정(더 많은 기능을 활성화):

# mihomo recommended TUN config
tun:
  enable: true
  stack: mixed         # mixed mode offers best compatibility
  dns-hijack:
    - any:53           # intercept all DNS queries
  auto-route: true
  auto-detect-interface: true
  strict-route: true   # prevent traffic bypassing TUN
stack: mixed 사용을 적극 권장합니다. system 스택의 안정성과 gvisor 스택의 호환성을 동시에 갖춘 모드로, 현재 mihomo에서 기본 권장 스택입니다.

DNS 설정 섹션의 변화

mihomo의 DNS 모듈은 더 다양한 업스트림 유형을 지원하며, nameserver-policy 필드의 우선순위 로직도 일부 조정되었습니다. 다음 사항들을 중점적으로 확인하세요:

  • enhanced-mode: redir-host 관련 설정을 모두 제거하고 fake-ip로 전환
  • fake-ip-filter를 사용 중이라면, NTP, 게임, P2P 등 fake-ip에 적합하지 않은 도메인이 목록에 포함되어 있는지 확인
  • nameserver에는 신뢰할 수 있는 공개 DNS(예: 1.1.1.1)와 DoH(예: https://8.8.8.8/dns-query)를 최소 하나씩 포함하는 것을 권장
# Recommended DNS section for mihomo (Korean users)
dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "+.lan"
    - "+.local"
    - "time.*.com"
    - "ntp.*.com"
  nameserver:
    - 1.1.1.1
    - 8.8.8.8
  fallback:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fallback-filter:
    geoip: true
    geoip-code: KR

mihomo 신기능 활성화 방법

외부 규칙 집합: rule-providers

rule-providers는 mihomo에서 가장 활용도가 높은 신기능 중 하나입니다. 외부 URL이나 로컬 파일에서 규칙 목록을 불러올 수 있어, 구버전처럼 rules 필드에 수백 개에서 수천 개의 규칙을 직접 작성하던 방식과 비교하면 성능 차이가 상당합니다. 시작 시간이 수 초에서 수십 밀리초 수준으로 단축되고, 메모리 사용량도 크게 줄어듭니다. 

# Define external rule providers
rule-providers:
  reject:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/reject.txt"
    path: ./ruleset/reject.yaml
    interval: 86400
  direct:
    type: http
    behavior: ipcidr
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/cncidr.txt"
    path: ./ruleset/direct.yaml
    interval: 86400

# Reference rule providers in rules section
rules:
  - RULE-SET,reject,REJECT
  - RULE-SET,direct,DIRECT
  - MATCH,Proxy

Sub-Rules: 서브 규칙 그룹

mihomo에는 sub-rules 필드가 새로 추가되어 규칙을 그룹별로 중첩 구성할 수 있게 되었습니다. 메인 규칙 목록이 지나치게 길어지는 문제를 해결하고, 보다 세밀한 트래픽 분기 로직을 구현할 수 있습니다. 예를 들어 지역별로 먼저 그룹화한 뒤 앱 유형별로 세분화하는 식으로 규칙 유지 보수성을 대폭 향상시킬 수 있습니다.

GeoSite 및 GeoIP 데이터베이스 업데이트

mihomo는 기본적으로 GeoIP2와 GeoSite 데이터베이스를 사용합니다. 오랫동안 업데이트하지 않았다면 규칙 매칭 정확도가 떨어질 수 있습니다. 설정 파일에서 자동 업데이트를 지정할 수 있습니다: 

geodata-mode: true
geox-url:
  geoip: "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geoip.dat"
  geosite: "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geosite.dat"
  mmdb: "https://testingcf.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/country.mmdb"

자주 발생하는 마이그레이션 오류와 해결 방법

시작 시 cannot unmarshal 오류가 발생하는 경우

이 유형의 오류는 대부분 YAML 필드의 타입 불일치 또는 더 이상 지원되지 않는 필드 때문에 발생합니다. 해결 방법은 다음과 같습니다:

  1. 오류 메시지에서 line X, column Y가 가리키는 위치를 꼼꼼히 확인합니다
  2. 이 가이드의 deprecated 필드 표와 대조하여 해당 필드를 삭제하거나 교체합니다
  3. 온라인 YAML 검증 도구를 활용해 문법 오류를 미리 걸러냅니다

DNS 순환 조회 / 인터넷 전체 연결 끊김

TUN 모드를 활성화한 후 dns-hijack이나 fake-ip-filter 설정이 올바르지 않으면, DNS 쿼리가 프록시 자체에 의해 가로채여 무한 루프에 빠지는 현상이 발생할 수 있습니다. 다음 단계로 점검해 보세요:

  • dns.enable: true가 설정되어 있는지 확인
  • mihomo의 External Controller 주소(예: 127.0.0.1)를 직접 연결(DIRECT) 목록에 추가
  • fake-ip-filter에 +.local과 +.lan을 추가
문제가 계속된다면 enhanced-mode를 임시로 normal로 바꾸고 재시작해 보세요. 이를 통해 fake-ip와 관련된 문제인지 여부를 빠르게 확인하고 원인을 좁혀나갈 수 있습니다.

TUN 모드에서 권한 부족 오류가 발생하는 경우

Linux / macOS에서는 TUN 디바이스를 생성하려면 관리자 권한이 필요합니다. 권장 해결 방법은 다음과 같습니다:

  • macOS: mihomo 코어를 지원하는 클라이언트를 사용하세요. 권한 요청 절차가 내장되어 있어 수동으로 sudo를 실행할 필요가 없습니다
  • Linux: mihomo 바이너리에 cap_net_admin 권한을 부여하세요: sudo setcap cap_net_admin=ep /usr/local/bin/mihomo
  • Windows: 관리자 권한으로 실행하거나, 자동 권한 상승을 지원하는 GUI 클라이언트를 사용하세요

Rule Provider 다운로드 시간 초과

mihomo를 처음 시작할 때 rule-providers에 설정된 규칙 파일을 원격에서 다운로드해야 합니다. 네트워크 환경이 좋지 않다면 시작 시 타임아웃이 발생할 수 있습니다. 아래 방법으로 해결할 수 있습니다:

  1. rule-providers에 path 로컬 경로를 함께 지정하고, 해당 위치에 규칙 파일을 미리 수동으로 다운로드해 둡니다
  2. 규칙 URL을 jsDelivr CDN 가속 버전으로 교체합니다
  3. timeout 값을 적절히 늘려줍니다(기본값 5초, 최대 30초까지 조정 가능)

마이그레이션 후 검증

설정 수정을 완료하고 mihomo를 재시작한 후, 아래 단계를 통해 마이그레이션이 정상적으로 완료되었는지 확인해 보세요:

  1. mihomo Web UI에 접속합니다(기본 주소: http://127.0.0.1:9090/ui). 코어 버전이 mihomo로 표시되는지 확인하세요
  2. 「프록시」 페이지에서 모든 노드가 정상적으로 로드되었는지 확인합니다
  3. 지연 시간 테스트(Latency Test)를 실행하여 노드가 제대로 연결되는지 확인합니다
  4. TUN 모드를 켜고 해외 사이트에 접속하여 트래픽이 프록시를 통하고 있는지 확인합니다
  5. 국내 주요 사이트에 접속하여 직접 연결(DIRECT)로 처리되는지, 규칙 분기가 정상 동작하는지 확인합니다

위 단계를 모두 통과했다면 마이그레이션 성공입니다! 이제 현재 가장 완성도 높고 활발하게 유지보수되고 있는 Clash 계열 코어를 사용하고 계신 겁니다.

코어만큼 중요한 것: 클라이언트도 함께 업그레이드하세요

코어 마이그레이션을 마치고도 수 년 전의 낡은 GUI 클라이언트를 그대로 사용하는 분들이 적지 않습니다. 하지만 이렇게 되면 mihomo의 신기능을 제대로 활용하기 어렵습니다. 구버전 클라이언트에서 흔히 경험하는 불편함은 다음과 같습니다:

  • rule-providers 시각화 관리 미지원, YAML을 일일이 수동으로 편집해야 함
  • TUN 모드 전환이 번거롭고 경우에 따라 시스템 서비스를 재시작해야 하는 경우도 있음
  • 코어 버전이 고정되어 있어 mihomo의 버그 수정 업데이트를 자동으로 따라갈 수 없음
  • 오래된 UI, 노드 지연 실시간 그래프나 트래픽 통계 같은 현대적인 기능 부재
  • 구독 관리가 조악하고 노드 그룹별 자동 속도 측정 및 최적 선택 기능 없음

지금 사용하시는 클라이언트에서 이런 불편함을 느끼고 계신다면, mihomo 코어와 깊이 통합된 현대적인 클라이언트로 전환하는 것을 고려해 보세요. 저희 Clash 클라이언트는 mihomo 코어에 최적화되어 설계되었으며, 원클릭 코어 업그레이드, 시각적 규칙 관리, TUN 모드 GUI 설정 기능을 내장하고 있어 이 가이드에서 설명한 모든 작업을 YAML을 직접 편집하지 않고도 수행할 수 있습니다.

→ Clash 공식 클라이언트 무료 다운로드 — Windows, macOS, Android, iOS, Linux 전 플랫폼 지원. 다운로드부터 실행까지 10분이면 충분합니다.