오픈소스 프로젝트mihomo 생태계

Clash 오픈소스클라이언트 다운로드

운영체제에 맞는 클라이언트를 선택하고 mihomo 설정 예제를 참고해 구독을 가져온 뒤 규칙 분기를 설정하세요. 필요에 따라 DNS와 네트워크 트래픽 처리 방식도 조정할 수 있습니다.

  • 설치 파일 선택
  • YAML 예제
  • 중국어 문서
config.yaml 설정 발췌
mixed-port: 7890mode: ruledns:  enable: true  enhanced-mode: fake-iprules:  - GEOIP,CN,DIRECT  - MATCH,Proxy
커널 mihomo
오픈소스 저장소와 릴리스 기록 보기

MIHOMO / CONFIG SCENES

설정 조각으로 관련 문서 찾기

고급 설정 가이드 보기

CONFIG REFERENCE

mihomo 설정
및 동작 방식

정책 그룹은 트래픽이 나갈 경로를 정하고, 규칙은 어떤 연결이 해당 경로를 사용할지 결정합니다. 먼저 이 두 단계의 분기 설정을 확인하고, DNS가 예상한 결과를 반환하는지와 트래픽이 커널에 전달되는지도 살펴보세요.

config.yaml

정책 그룹 이름과 출구 선택

규칙이 정책 그룹을 가리키도록 설정하면 도메인 목록을 다시 작성하지 않고도 출구를 바꿀 수 있습니다. select는 사용자가 구성원을 선택하고, url-test는 연결 테스트 결과에 따라 구성원을 고르며, fallback은 목록 앞쪽부터 사용 가능한 구성원을 우선 선택합니다. 예제에서는 내장 정책을 사용해 참조 관계를 설명합니다. 구독을 연결한 뒤에는 그룹 이름과 구성원 이름을 확인하고, 연결 기록에서 규칙에 일치한 그룹과 최종 출구를 확인하세요. 클라이언트 화면에 일부 필드가 표시되지 않을 수 있으므로 문제를 진단할 때는 실제 적용된 설정을 기준으로 살펴보세요.

proxy-groups:
  - name: Proxy
    type: select
    proxies: [DIRECT, REJECT]
rules:
  - MATCH,Proxy
정책 그룹 유형과 활용 예제 보기

PLATFORM PACKAGES

플랫폼별 Clash 클라이언트 선택

먼저 운영체제와 프로세서 아키텍처를 확인한 다음 클라이언트를 비교하세요. 그래픽 클라이언트는 화면에서 설정을 관리하기 편리합니다. mihomo를 단독으로 실행하려면 설정 디렉터리, 프로세스 관리, 시스템 네트워크 설정을 직접 다뤄야 합니다. 기존 클라이언트를 교체할 때는 로컬 오버라이드와 정책 그룹 선택을 저장한 뒤 이전 클라이언트를 종료하세요. 포트 충돌이 발생하면 구독의 포트를 바꿔 우회하기보다 기존 프로세스가 종료됐는지 먼저 확인하세요.

Windows

그래픽 인터페이스를 주로 사용하고 앱별 프록시 동작을 확인하려는 데스크톱 환경에 적합합니다. 시스템의 ‘정보’ 화면에서 프로세서 아키텍처를 확인하고 다운로드 페이지의 패키지 유형과 비교하세요. 처음 연결할 때는 시스템 프록시를 켜고 브라우저로 먼저 테스트하면 됩니다. 대상 앱이 시스템 프록시를 사용하지 않을 때만 TUN을 고려하세요. 업그레이드 전에는 기존 클라이언트를 종료하고 백그라운드 서비스도 중지됐는지 확인하세요. 클라이언트를 종료한 뒤에도 브라우저에서 인터넷에 연결할 수 없다면 시스템 프록시가 로컬 포트를 가리키는 설정을 남겼는지 확인하세요. 회사 기기의 관리자 권한과 방화벽 설정은 기기 관리 정책을 따라야 합니다.

다운로드 페이지로 이동

macOS

‘이 Mac에 관하여’에서 칩 정보를 확인해 Apple Silicon과 Intel을 구분하세요. 시스템 화면이나 기기 출시 연도로 추측하지 말고 다운로드 페이지에 실제로 표시된 아키텍처를 기준으로 선택해야 합니다. 메뉴 막대에서 프록시를 전환한다면 시스템 네트워크 설정에서 프록시 상태를 다시 확인할 수 있습니다. 실행 직후 종료된다면 설치 패키지의 아키텍처와 시스템 요구 사항을 먼저 확인하세요. 일부 앱에서만 연결되지 않는다면 앱 자체의 프록시 설정부터 점검하세요. 기존 설정을 옮길 때는 구독 주소, 로컬 파일, 정책 선택을 각각 확인하세요. 새 클라이언트가 다른 클라이언트의 작업 디렉터리를 자동으로 읽는다고 가정하지 마세요.

다운로드 페이지로 이동

Android

기기 아키텍처에 맞는 APK를 선택하세요. 다운로드 페이지에 범용 패키지가 있다면 아키텍처를 잘못 고를 가능성을 줄일 수 있습니다. 처음 연결할 때는 보통 시스템 VPN 요청을 승인해야 합니다. 기기에 다른 VPN이 이미 설치되어 있다면 현재 어떤 앱이 연결을 설정할 수 있는지 먼저 확인하세요. 기본 배터리 설정으로 화면이 켜져 있을 때와 잠금 상태일 때 모두 테스트한 뒤 백그라운드 권한 조정 여부를 결정하세요. 화면을 잠근 뒤 끊기는 문제와 Wi-Fi 전환 후 끊기는 문제는 원인이 다를 수 있습니다. 전자는 프로세스가 일시 중지됐는지, 후자는 새 네트워크에서 시스템 VPN이 다시 연결됐는지 확인하세요.

다운로드 페이지로 이동

iOS

다운로드 페이지에서 클라이언트의 App Store 페이지로 이동해 시스템 요구 사항을 먼저 확인하세요. 설치 후 앱 안내에 따라 VPN 구성을 추가하고 기존 구독을 가져오면 됩니다. 데스크톱에서는 가져올 수 있는 구독이 모바일에서만 가져오지 못한다면 서버 주소를 바로 수정하지 말고 클라이언트가 지원하는 설정 형식과 필드를 먼저 확인하세요. Wi-Fi와 모바일 데이터를 각각 사용해 특정 네트워크에서만 문제가 발생하는지 테스트할 수 있습니다. 회사나 학교에서 관리하는 기기는 관리 정책에 따라 VPN 설정이 제한될 수 있으므로 허용된 사용 범위를 먼저 확인하세요.

다운로드 페이지로 이동

Linux

데스크톱에서는 배포판의 패키지 관리 방식과 프로세서 아키텍처를 기준으로 설치 파일을 선택하세요. 데스크톱 프록시 설정이 터미널에 자동으로 적용되지 않을 수 있으므로 명령줄 도구가 해당 프록시 환경 변수를 읽는지 별도로 확인해야 합니다. 서버나 라우터에서는 커널을 단독으로 실행하고 설정 디렉터리, 실행 사용자, 로그 위치를 명시하는 편이 적합합니다. 시작에 실패하면 패키지 비호환, 의존성 누락, 서비스 권한 부족을 먼저 구분하고, 연결에 실패하면 수신 주소와 라우트를 확인하세요. 두 문제는 점검 방법이 다르므로 테스트를 위해 방화벽과 시스템 라우트를 동시에 바꿀 필요는 없습니다.

다운로드 페이지로 이동

모든 클라이언트 보기 →

FIRST CONNECTION

Clash 첫 연결: 가져오기, 트래픽 처리, 확인

먼저 정상적으로 시작되는 설정을 하나 보관한 뒤 분기 규칙과 네트워크 트래픽 처리 방식을 단계적으로 바꾸세요. 한 번에 설정 하나만 변경하고 같은 대상을 테스트해 어떤 설정이 영향을 줬는지 확인하세요.

  1. 설정 가져와 적용하기

    설치 후 ‘설정’ 또는 ‘구독’ 화면에서 URL로 기존 구독을 가져오거나 로컬 YAML 파일을 불러오세요. 목록에 새 항목이 나타나면 직접 선택해 적용됐는지 확인해야 합니다. 설정 이름이 보인다고 해서 항목이 저장된 것일 뿐, 커널이 정상적으로 불러왔다는 뜻은 아닙니다. 적용에 실패하면 오류에 표시된 필드나 줄 번호를 확인하고 들여쓰기, 참조 이름, 클라이언트가 지원하는 필드를 점검하세요. 다른 사람에게 도움을 요청할 때는 관련 필드와 오류 내용만 공유하고, 구독 주소나 전체 설정을 공개 게시판에 올리지 마세요.

  2. 규칙 모드와 트래픽 처리 방식 선택

    실행 모드를 ‘규칙’으로 설정해 설정 파일에 정의된 분기 로직을 유지하세요. 데스크톱에서는 먼저 시스템 프록시를 켜고 이를 지원하는 앱으로 테스트하고, 모바일에서는 시스템 안내에 따라 VPN 연결을 설정하세요. 대상 프로그램의 연결이 목록에 나타나지 않을 때는 앱 자체 프록시나 TUN을 고려하세요. 시스템 프록시는 앱의 요청을 클라이언트로 전달할지 결정하고, 실행 모드는 커널이 받은 요청을 어떻게 처리할지 정합니다. 두 설정은 서로 대체할 수 없습니다. 기기에 다른 네트워크 트래픽 처리 도구가 있다면 구독 문제로 오인하지 않도록 기존 도구를 중지한 뒤 테스트하세요.

  3. 연결 기록으로 규칙 적용 확인

    직접 연결되어야 하는 대상과 프록시를 사용해야 하는 대상을 하나씩 골라 새 요청을 보내세요. 연결 기록에서 대상 도메인, 일치한 규칙, 최종 출구를 확인하고 페이지가 열리는지만으로 분기 결과를 판단하지 마세요. 기록은 있지만 출구가 잘못됐다면 규칙 순서와 정책 그룹의 현재 구성원을 먼저 확인하세요. 기록이 없다면 앱의 연결이 클라이언트에 전달됐는지 확인해야 합니다. 규칙을 바꾼 뒤에는 새 연결을 만들어 비교하세요. 앱이 기존 연결을 재사용하면 변경 전 결과가 계속 보일 수 있습니다.

전체 가이드 보기 →

SOURCE / RELEASES

mihomo 소스 코드 및 릴리스 기록

원본 Clash와 후속 포크

원본 Clash의 유지 관리가 중단된 뒤 관련 클라이언트와 커널 프로젝트는 각자의 저장소에서 계속 발전했습니다. mihomo는 Clash.Meta 포크에서 시작했으며 익숙한 규칙, 정책 그룹, YAML 설정 구조를 사용하지만 자체 필드와 동작 방식도 발전시켜 왔습니다. 이름에 Clash가 포함됐다고 해서 같은 관리자가 유지하거나 같은 일정으로 릴리스하는 프로젝트는 아닙니다. 오래된 가이드를 참고할 때는 원본 커널, 후속 포크, 그래픽 클라이언트 중 무엇을 다루는지 먼저 확인하세요. 특히 설치 방법, 서비스 모드, DNS 설정의 차이에 유의해야 합니다.

보관된 클라이언트의 설정을 옮길 때는 먼저 복사본을 가져온 뒤 커널 시작 로그와 클라이언트가 생성한 실제 설정을 확인하세요. 이전 필드를 읽을 수 있다고 해서 기존 네트워크 동작까지 그대로 유지되는 것은 아닙니다. 시스템 권한, 라우트, DNS 기본값도 달라질 수 있습니다.

클라이언트와 커널의 역할

mihomo는 실행 설정을 해석하고 연결을 받아 규칙을 적용한 뒤 출구를 선택합니다. Clash Verge Rev와 FlClash 같은 그래픽 클라이언트는 이를 바탕으로 설정 관리, 메뉴 전환, 연결 정보를 제공합니다. 트레이 메뉴, 구독 업데이트 메뉴, 오버라이드 편집기는 보통 인터페이스 계층의 기능입니다. 규칙 적용 실패나 모듈 초기화 오류는 커널 로그에서 확인해야 합니다. 두 인터페이스에 모두 ‘시스템 프록시’ 스위치가 있더라도 시스템 설정을 관리하는 방식은 다를 수 있습니다. 문제를 진단할 때는 먼저 어느 계층의 문제인지 확인하세요. 인터페이스 문제를 해결하려고 YAML 전체를 다시 작성할 필요는 없습니다.

같은 구독이 클라이언트마다 다르게 동작한다면 각 클라이언트에 적용된 로컬 오버라이드와 활성화된 프록시 진입점을 확인하세요. 적용된 설정을 내보낼 수 있다면 관련 필드를 나란히 비교하는 편이 전체 설정 화면을 대조하는 것보다 차이를 찾기 쉽습니다.

저장소, 이슈 및 문제 담당 범위

상위 저장소에서 소스 코드, 변경 사항, 공개 이슈를 확인할 수 있습니다. 설정 문제는 오류 문구나 필드 이름으로 먼저 검색하세요. 특정 클라이언트의 설치 프로그램만 시작되지 않는다면 해당 클라이언트의 릴리스 기록과 이슈부터 살펴보세요. 문제를 제보할 때는 시스템 아키텍처, 트래픽 처리 방식, 재현 절차, 실제 결과를 적어야 합니다. 최소 설정으로 재현하면 필드 간 관계, 네트워크 환경, 인터페이스 설정 중 원인을 구분하는 데 도움이 됩니다. 구독 내용을 전부 첨부할 필요는 없습니다. 이 사이트는 클라이언트 다운로드 경로와 중국어 문서를 제공합니다. 프로젝트의 기능과 유지 관리 상태는 각 프로젝트의 상위 저장소 기록을 기준으로 확인하세요.

특정 네트워크에 연결했을 때만 같은 문제가 발생한다면 언제부터 재현됐는지와 원래 네트워크로 돌아갔을 때 해결되는지도 함께 알려주세요. 유지 관리자가 환경 제한과 꾸준히 재현되는 소프트웨어 회귀를 구분하는 데 도움이 됩니다.

변경 사항을 확인한 뒤 업데이트

그래픽 클라이언트와 mihomo 커널은 서로 다른 일정으로 릴리스됩니다. 인터페이스가 업데이트되어도 커널은 그대로일 수 있으며, 커널만 따로 교체하면 클라이언트에서 지원하지 않을 수도 있습니다. 설치 전에 정식 릴리스와 사전 릴리스를 구분하고 패키지의 운영체제와 아키텍처를 확인한 다음 DNS, TUN, 권한, 설정 마이그레이션 관련 변경 사항을 읽어보세요. 업데이트 후에는 기존 설정으로 시작, 구독 로드, 직접 연결, 프록시 출구를 확인하세요. 문제가 생기면 되돌리거나 변경 사항을 하나씩 확인할 수 있도록 기존 설정과 업데이트 전 정상 작동 기록을 보관하세요.

클라이언트 업데이트와 동시에 규칙 세트를 바꾸거나, 업스트림 DNS를 다시 설정하거나, 새 모드를 활성화할 필요는 없습니다. 업데이트와 설정 변경을 나눠 진행하면 네트워크 문제가 생겼을 때 어느 단계를 되돌려야 하는지 쉽게 파악할 수 있습니다.

mihomo 소스 코드 가져오기

이 명령은 소스 코드를 살펴보기 위한 것입니다. 기존 클라이언트를 설치하려면 다운로드 페이지를 이용하고, 커널을 빌드하려면 저장소 안내에 따라 환경을 준비하세요.

git clone https://github.com/MetaCubeX/mihomo.git

TECHNICAL NOTES

최신 설정 및 플랫폼 가이드

전체 글 보기 →

Clash 다운로드