정책 그룹은 트래픽이 나갈 경로를 정하고, 규칙은 어떤 연결이 해당 경로를 사용할지 결정합니다. 먼저 이 두 단계의 분기 설정을 확인하고, DNS가 예상한 결과를 반환하는지와 트래픽이 커널에 전달되는지도 살펴보세요.
config.yaml
정책 그룹 이름과 출구 선택
규칙이 정책 그룹을 가리키도록 설정하면 도메인 목록을 다시 작성하지 않고도 출구를 바꿀 수 있습니다. select는 사용자가 구성원을 선택하고, url-test는 연결 테스트 결과에 따라 구성원을 고르며, fallback은 목록 앞쪽부터 사용 가능한 구성원을 우선 선택합니다. 예제에서는 내장 정책을 사용해 참조 관계를 설명합니다. 구독을 연결한 뒤에는 그룹 이름과 구성원 이름을 확인하고, 연결 기록에서 규칙에 일치한 그룹과 최종 출구를 확인하세요. 클라이언트 화면에 일부 필드가 표시되지 않을 수 있으므로 문제를 진단할 때는 실제 적용된 설정을 기준으로 살펴보세요.
도메인 목록을 기본 설정에서 분리하면 규칙 내용을 독립적으로 관리하면서 출구 선택은 rules에 둘 수 있습니다. 이 예제는 로컬 파일을 불러옵니다. 파일 내용은 domain 동작 방식과 YAML 형식에 맞아야 하며, 파일 경로는 커널 설정 디렉터리에서 확인해야 합니다. HTTP 규칙 세트로 바꿀 경우에는 업데이트 주기도 설정하세요. 규칙은 위에서 아래 순서로 적용됩니다. 앞쪽의 직접 연결 규칙이 먼저 일치하면 뒤의 규칙은 실행되지 않습니다. 트래픽이 잘못 분기되면 규칙 세트가 로드됐는지 먼저 확인한 다음 항목 순서를 살펴보세요.
커널 DNS를 활성화했다면 먼저 연결 가능한 기본 업스트림을 설정하고, 별도 DNS 응답이 필요한 도메인에만 nameserver-policy를 지정하세요. 이 정책은 어디에 질의할지를 정하는 설정이지 연결 출구를 지정하는 설정은 아닙니다. 일부 사이트가 열리지 않으면 DNS 조회 실패와 연결 실패를 구분하세요. 클라이언트 로그와 시스템 DNS 조회 결과를 비교하고, 브라우저가 별도의 DNS를 사용하는지도 확인해야 합니다. 예제에는 일반적인 업스트림을 사용했으며, 실제 환경에서는 네트워크 연결 상태와 관리 정책에 맞춰 선택하세요.
TUN은 가상 네트워크 어댑터로 트래픽을 받아 시스템 프록시 설정을 따르지 않는 앱에 적합합니다. Fake-IP는 주소 매핑을 통해 커널이 도메인 정보를 유지하도록 합니다. 두 기능은 서로 다른 문제를 해결합니다. 예제는 라우트를 자동으로 설정하고 일반 DNS 포트로 향하는 트래픽을 커널에 전달합니다. 활성화하기 전에 시스템 권한, 기본 네트워크 어댑터, 기존 VPN의 라우트를 확인하세요. 로컬 네트워크 서비스에 문제가 생기면 여러 설정을 한꺼번에 바꾸지 말고 라우트와 DNS 예외를 하나씩 점검하세요.
일부 앱은 연결을 요청할 때 대상 IP만 전달해 도메인 규칙이 적용되지 않을 수 있습니다. 스니핑은 지원되는 프로토콜의 메타데이터에서 도메인을 보완하지만, 연결 상태에 따라 읽을 수 있는 정보가 달라 결과를 보장하지 않습니다. 예제는 지정된 포트의 TLS 트래픽만 검사하며 원래 대상 주소를 유지합니다. 문제를 진단할 때는 같은 연결에서 스니핑을 켜기 전과 후의 도메인 및 규칙 기록을 비교하세요. 변화가 없다면 포트 범위, 프로토콜 유형, 기존 DNS 매핑을 확인하세요.
오래 유지할 수정 사항을 원격 구독이 생성한 파일에만 넣지 마세요. 다음에 새로고침하면 덮어써질 수 있습니다. 출처별로 프록시 제공자를 따로 정의한 다음 같은 정책 그룹에서 참조할 수 있습니다. 예제는 두 개의 로컬 제공자 파일로 구조를 설명합니다. 병합한 뒤에는 이름 충돌, 그룹 구성원, 규칙 우선순위를 확인하세요. 클라이언트에 별도의 오버라이드 기능이 있다면 기존 설정을 대체하는지 추가하는지도 확인해야 합니다. 오버라이드 스크립트의 실행 진입점과 순서는 클라이언트마다 다르며, 커널 공통 인터페이스가 아닙니다.
컨트롤 인터페이스는 호환되는 패널이 연결 정보를 읽고 정책을 전환하는 데 사용합니다. 앱으로 트래픽을 전달하는 혼합 포트와는 다릅니다. 로컬에서만 관리한다면 컨트롤 인터페이스를 루프백 주소에 바인딩하고 별도의 인증 정보를 설정하는 것이 좋습니다. allow-lan은 프록시 진입점을 제어하는 설정으로, 컨트롤 인터페이스 자체의 수신 범위를 제한하지는 않습니다. 패널이 열리지 않으면 컨트롤 포트, 프로세스의 수신 상태, 인증 설정 순으로 확인하세요. 프록시 포트를 바꾸거나 수신 범위를 넓힐 필요는 없습니다.
먼저 운영체제와 프로세서 아키텍처를 확인한 다음 클라이언트를 비교하세요. 그래픽 클라이언트는 화면에서 설정을 관리하기 편리합니다. mihomo를 단독으로 실행하려면 설정 디렉터리, 프로세스 관리, 시스템 네트워크 설정을 직접 다뤄야 합니다. 기존 클라이언트를 교체할 때는 로컬 오버라이드와 정책 그룹 선택을 저장한 뒤 이전 클라이언트를 종료하세요. 포트 충돌이 발생하면 구독의 포트를 바꿔 우회하기보다 기존 프로세스가 종료됐는지 먼저 확인하세요.
그래픽 인터페이스를 주로 사용하고 앱별 프록시 동작을 확인하려는 데스크톱 환경에 적합합니다. 시스템의 ‘정보’ 화면에서 프로세서 아키텍처를 확인하고 다운로드 페이지의 패키지 유형과 비교하세요. 처음 연결할 때는 시스템 프록시를 켜고 브라우저로 먼저 테스트하면 됩니다. 대상 앱이 시스템 프록시를 사용하지 않을 때만 TUN을 고려하세요. 업그레이드 전에는 기존 클라이언트를 종료하고 백그라운드 서비스도 중지됐는지 확인하세요. 클라이언트를 종료한 뒤에도 브라우저에서 인터넷에 연결할 수 없다면 시스템 프록시가 로컬 포트를 가리키는 설정을 남겼는지 확인하세요. 회사 기기의 관리자 권한과 방화벽 설정은 기기 관리 정책을 따라야 합니다.
‘이 Mac에 관하여’에서 칩 정보를 확인해 Apple Silicon과 Intel을 구분하세요. 시스템 화면이나 기기 출시 연도로 추측하지 말고 다운로드 페이지에 실제로 표시된 아키텍처를 기준으로 선택해야 합니다. 메뉴 막대에서 프록시를 전환한다면 시스템 네트워크 설정에서 프록시 상태를 다시 확인할 수 있습니다. 실행 직후 종료된다면 설치 패키지의 아키텍처와 시스템 요구 사항을 먼저 확인하세요. 일부 앱에서만 연결되지 않는다면 앱 자체의 프록시 설정부터 점검하세요. 기존 설정을 옮길 때는 구독 주소, 로컬 파일, 정책 선택을 각각 확인하세요. 새 클라이언트가 다른 클라이언트의 작업 디렉터리를 자동으로 읽는다고 가정하지 마세요.
기기 아키텍처에 맞는 APK를 선택하세요. 다운로드 페이지에 범용 패키지가 있다면 아키텍처를 잘못 고를 가능성을 줄일 수 있습니다. 처음 연결할 때는 보통 시스템 VPN 요청을 승인해야 합니다. 기기에 다른 VPN이 이미 설치되어 있다면 현재 어떤 앱이 연결을 설정할 수 있는지 먼저 확인하세요. 기본 배터리 설정으로 화면이 켜져 있을 때와 잠금 상태일 때 모두 테스트한 뒤 백그라운드 권한 조정 여부를 결정하세요. 화면을 잠근 뒤 끊기는 문제와 Wi-Fi 전환 후 끊기는 문제는 원인이 다를 수 있습니다. 전자는 프로세스가 일시 중지됐는지, 후자는 새 네트워크에서 시스템 VPN이 다시 연결됐는지 확인하세요.
다운로드 페이지에서 클라이언트의 App Store 페이지로 이동해 시스템 요구 사항을 먼저 확인하세요. 설치 후 앱 안내에 따라 VPN 구성을 추가하고 기존 구독을 가져오면 됩니다. 데스크톱에서는 가져올 수 있는 구독이 모바일에서만 가져오지 못한다면 서버 주소를 바로 수정하지 말고 클라이언트가 지원하는 설정 형식과 필드를 먼저 확인하세요. Wi-Fi와 모바일 데이터를 각각 사용해 특정 네트워크에서만 문제가 발생하는지 테스트할 수 있습니다. 회사나 학교에서 관리하는 기기는 관리 정책에 따라 VPN 설정이 제한될 수 있으므로 허용된 사용 범위를 먼저 확인하세요.
데스크톱에서는 배포판의 패키지 관리 방식과 프로세서 아키텍처를 기준으로 설치 파일을 선택하세요. 데스크톱 프록시 설정이 터미널에 자동으로 적용되지 않을 수 있으므로 명령줄 도구가 해당 프록시 환경 변수를 읽는지 별도로 확인해야 합니다. 서버나 라우터에서는 커널을 단독으로 실행하고 설정 디렉터리, 실행 사용자, 로그 위치를 명시하는 편이 적합합니다. 시작에 실패하면 패키지 비호환, 의존성 누락, 서비스 권한 부족을 먼저 구분하고, 연결에 실패하면 수신 주소와 라우트를 확인하세요. 두 문제는 점검 방법이 다르므로 테스트를 위해 방화벽과 시스템 라우트를 동시에 바꿀 필요는 없습니다.
먼저 정상적으로 시작되는 설정을 하나 보관한 뒤 분기 규칙과 네트워크 트래픽 처리 방식을 단계적으로 바꾸세요. 한 번에 설정 하나만 변경하고 같은 대상을 테스트해 어떤 설정이 영향을 줬는지 확인하세요.
설정 가져와 적용하기
설치 후 ‘설정’ 또는 ‘구독’ 화면에서 URL로 기존 구독을 가져오거나 로컬 YAML 파일을 불러오세요. 목록에 새 항목이 나타나면 직접 선택해 적용됐는지 확인해야 합니다. 설정 이름이 보인다고 해서 항목이 저장된 것일 뿐, 커널이 정상적으로 불러왔다는 뜻은 아닙니다. 적용에 실패하면 오류에 표시된 필드나 줄 번호를 확인하고 들여쓰기, 참조 이름, 클라이언트가 지원하는 필드를 점검하세요. 다른 사람에게 도움을 요청할 때는 관련 필드와 오류 내용만 공유하고, 구독 주소나 전체 설정을 공개 게시판에 올리지 마세요.
규칙 모드와 트래픽 처리 방식 선택
실행 모드를 ‘규칙’으로 설정해 설정 파일에 정의된 분기 로직을 유지하세요. 데스크톱에서는 먼저 시스템 프록시를 켜고 이를 지원하는 앱으로 테스트하고, 모바일에서는 시스템 안내에 따라 VPN 연결을 설정하세요. 대상 프로그램의 연결이 목록에 나타나지 않을 때는 앱 자체 프록시나 TUN을 고려하세요. 시스템 프록시는 앱의 요청을 클라이언트로 전달할지 결정하고, 실행 모드는 커널이 받은 요청을 어떻게 처리할지 정합니다. 두 설정은 서로 대체할 수 없습니다. 기기에 다른 네트워크 트래픽 처리 도구가 있다면 구독 문제로 오인하지 않도록 기존 도구를 중지한 뒤 테스트하세요.
연결 기록으로 규칙 적용 확인
직접 연결되어야 하는 대상과 프록시를 사용해야 하는 대상을 하나씩 골라 새 요청을 보내세요. 연결 기록에서 대상 도메인, 일치한 규칙, 최종 출구를 확인하고 페이지가 열리는지만으로 분기 결과를 판단하지 마세요. 기록은 있지만 출구가 잘못됐다면 규칙 순서와 정책 그룹의 현재 구성원을 먼저 확인하세요. 기록이 없다면 앱의 연결이 클라이언트에 전달됐는지 확인해야 합니다. 규칙을 바꾼 뒤에는 새 연결을 만들어 비교하세요. 앱이 기존 연결을 재사용하면 변경 전 결과가 계속 보일 수 있습니다.
원본 Clash의 유지 관리가 중단된 뒤 관련 클라이언트와 커널 프로젝트는 각자의 저장소에서 계속 발전했습니다. mihomo는 Clash.Meta 포크에서 시작했으며 익숙한 규칙, 정책 그룹, YAML 설정 구조를 사용하지만 자체 필드와 동작 방식도 발전시켜 왔습니다. 이름에 Clash가 포함됐다고 해서 같은 관리자가 유지하거나 같은 일정으로 릴리스하는 프로젝트는 아닙니다. 오래된 가이드를 참고할 때는 원본 커널, 후속 포크, 그래픽 클라이언트 중 무엇을 다루는지 먼저 확인하세요. 특히 설치 방법, 서비스 모드, DNS 설정의 차이에 유의해야 합니다.
보관된 클라이언트의 설정을 옮길 때는 먼저 복사본을 가져온 뒤 커널 시작 로그와 클라이언트가 생성한 실제 설정을 확인하세요. 이전 필드를 읽을 수 있다고 해서 기존 네트워크 동작까지 그대로 유지되는 것은 아닙니다. 시스템 권한, 라우트, DNS 기본값도 달라질 수 있습니다.
클라이언트와 커널의 역할
mihomo는 실행 설정을 해석하고 연결을 받아 규칙을 적용한 뒤 출구를 선택합니다. Clash Verge Rev와 FlClash 같은 그래픽 클라이언트는 이를 바탕으로 설정 관리, 메뉴 전환, 연결 정보를 제공합니다. 트레이 메뉴, 구독 업데이트 메뉴, 오버라이드 편집기는 보통 인터페이스 계층의 기능입니다. 규칙 적용 실패나 모듈 초기화 오류는 커널 로그에서 확인해야 합니다. 두 인터페이스에 모두 ‘시스템 프록시’ 스위치가 있더라도 시스템 설정을 관리하는 방식은 다를 수 있습니다. 문제를 진단할 때는 먼저 어느 계층의 문제인지 확인하세요. 인터페이스 문제를 해결하려고 YAML 전체를 다시 작성할 필요는 없습니다.
같은 구독이 클라이언트마다 다르게 동작한다면 각 클라이언트에 적용된 로컬 오버라이드와 활성화된 프록시 진입점을 확인하세요. 적용된 설정을 내보낼 수 있다면 관련 필드를 나란히 비교하는 편이 전체 설정 화면을 대조하는 것보다 차이를 찾기 쉽습니다.
저장소, 이슈 및 문제 담당 범위
상위 저장소에서 소스 코드, 변경 사항, 공개 이슈를 확인할 수 있습니다. 설정 문제는 오류 문구나 필드 이름으로 먼저 검색하세요. 특정 클라이언트의 설치 프로그램만 시작되지 않는다면 해당 클라이언트의 릴리스 기록과 이슈부터 살펴보세요. 문제를 제보할 때는 시스템 아키텍처, 트래픽 처리 방식, 재현 절차, 실제 결과를 적어야 합니다. 최소 설정으로 재현하면 필드 간 관계, 네트워크 환경, 인터페이스 설정 중 원인을 구분하는 데 도움이 됩니다. 구독 내용을 전부 첨부할 필요는 없습니다. 이 사이트는 클라이언트 다운로드 경로와 중국어 문서를 제공합니다. 프로젝트의 기능과 유지 관리 상태는 각 프로젝트의 상위 저장소 기록을 기준으로 확인하세요.
특정 네트워크에 연결했을 때만 같은 문제가 발생한다면 언제부터 재현됐는지와 원래 네트워크로 돌아갔을 때 해결되는지도 함께 알려주세요. 유지 관리자가 환경 제한과 꾸준히 재현되는 소프트웨어 회귀를 구분하는 데 도움이 됩니다.
변경 사항을 확인한 뒤 업데이트
그래픽 클라이언트와 mihomo 커널은 서로 다른 일정으로 릴리스됩니다. 인터페이스가 업데이트되어도 커널은 그대로일 수 있으며, 커널만 따로 교체하면 클라이언트에서 지원하지 않을 수도 있습니다. 설치 전에 정식 릴리스와 사전 릴리스를 구분하고 패키지의 운영체제와 아키텍처를 확인한 다음 DNS, TUN, 권한, 설정 마이그레이션 관련 변경 사항을 읽어보세요. 업데이트 후에는 기존 설정으로 시작, 구독 로드, 직접 연결, 프록시 출구를 확인하세요. 문제가 생기면 되돌리거나 변경 사항을 하나씩 확인할 수 있도록 기존 설정과 업데이트 전 정상 작동 기록을 보관하세요.
클라이언트 업데이트와 동시에 규칙 세트를 바꾸거나, 업스트림 DNS를 다시 설정하거나, 새 모드를 활성화할 필요는 없습니다. 업데이트와 설정 변경을 나눠 진행하면 네트워크 문제가 생겼을 때 어느 단계를 되돌려야 하는지 쉽게 파악할 수 있습니다.
mihomo 소스 코드 가져오기
이 명령은 소스 코드를 살펴보기 위한 것입니다. 기존 클라이언트를 설치하려면 다운로드 페이지를 이용하고, 커널을 빌드하려면 저장소 안내에 따라 환경을 준비하세요.