먼저 운영체제와 프로세서 아키텍처를 확인한 뒤 설치 파일을 선택하세요. 그래픽 클라이언트는 보통 설정 가져오기, 프록시 그룹 전환, 로그 확인을 한 화면에서 할 수 있어 처음 설치할 때 편리합니다. 명령줄 코어를 사용 중이라면 다운로드 페이지에서 코어 항목을 따로 확인해 데스크톱 설치 프로그램과 혼동하지 않도록 하세요.
운영체제의 ‘정보’ 페이지에서 시스템 종류를 확인하고, 클라이언트에 표시된 프로세서 아키텍처와 맞는지 살펴보세요. 처음 설치한다면 시스템 프록시만 설정해 브라우저 연결을 확인하고, 가상 네트워크 인터페이스는 바로 켜지 않아도 됩니다. 설치 프로그램이나 운영체제에서 권한을 요청하면 설치, 서비스, 네트워크 접근 중 어떤 권한인지 확인하세요. 안내 하나 때문에 방화벽 전체를 끌 필요는 없습니다. 기존 클라이언트를 교체하기 전에는 실행 중인 프로세스를 종료하고 원래 설정을 보관하세요.
‘이 Mac에 관하여’에서 Intel 프로세서와 Apple 칩을 구분한 뒤 알맞은 설치 파일을 선택하세요. 실행할 때 보안 경고가 표시되면 프로젝트의 릴리스 안내에서 설치 요건을 확인하세요. 실행은 되지만 트래픽을 처리하지 못한다면 시스템 프록시 상태와 클라이언트의 네트워크 권한을 점검하세요. 다른 기기로 옮길 때는 설정을 우선 이전하고, 기존 앱의 데이터 폴더를 그대로 복사하지 마세요.
설치 파일을 고를 때는 휴대폰 칩의 홍보 사양이 아니라 기기에 설치된 운영체제가 지원하는 아키텍처를 확인하세요. 처음 연결하면 운영체제에서 VPN 사용을 허용할지 묻습니다. 승인한 뒤 클라이언트가 연결됨 상태인지 확인하세요. 화면을 잠근 뒤에만 문제가 생기면 백그라운드 실행이 제한되는지 살펴보세요. 연결하자마자 끊긴다면 다른 앱이 VPN을 사용 중인지 확인하세요.
다운로드 페이지에서 앱 스토어로 이동한 뒤 운영체제 요구 사항을 먼저 확인하세요. 처음 연결할 때는 안내에 따라 VPN 구성을 허용해야 합니다. 설정 가져오기와 연결 성공은 서로 다른 상태이므로, 설정 목록에 이름이 나타났다고 연결된 것은 아닙니다. 업무용 VPN 설정이 이미 있다면 전환할 수 있는지 확인하세요. 특히 회사에서 관리하는 기기라면 더욱 주의해야 합니다.
데스크톱에서는 배포판, 패키지 형식, 프로세서 아키텍처를 확인한 뒤 그래픽 클라이언트를 선택하세요. 데스크톱 환경마다 시스템 프록시를 처리하는 방식이 다릅니다. 브라우저에서 프록시가 작동해도 터미널 명령이 같은 설정을 사용하는 것은 아닙니다. 서버에서 코어만 실행한다면 설정 파일 경로와 서비스 권한을 따로 확인하고, 실제 용도에 맞게 리스닝 범위를 설정하세요.
두 클라이언트 모두 현재 기기를 지원한다면 설정 가져오기 방법, 유지 관리 상태, 로그 확인 위치를 비교하세요. 로컬 네트워크 접근, 가상 네트워크 인터페이스, 설정 덮어쓰기를 사용할 경우 해당 옵션이 있는지와 코어가 관련 항목을 읽는지도 확인해야 합니다. 오래된 설정 파일을 열기 위해 지원이 종료된 클라이언트를 고려 중이라면, 원본을 반복해서 수정하지 말고 유지 관리 중인 클라이언트에서 복사본을 먼저 테스트하세요.
로컬 리스닝, 트래픽 처리, 규칙 분기는 서로 다른 단계입니다. 포트는 앱이 요청을 전달할 위치를 정하고, 트래픽 처리 방식은 어떤 요청이 코어에 들어갈지 결정하며, 규칙은 코어에 들어온 요청의 경로를 정합니다. 이 세 단계를 구분하면 요청이 코어에 도달하지 않은 것인지, 도달한 뒤 잘못된 경로로 간 것인지 쉽게 확인할 수 있습니다.
규칙 우선순위와 기본 대상
규칙 모드는 위에서 아래로 각 규칙을 확인합니다. 규칙이 일치하면 지정된 대상으로 처리하고, 더 구체적인 규칙을 찾기 위해 계속 내려가지 않습니다. 예시에서는 사설 IP 주소, 예시 도메인, 나머지 트래픽을 차례로 처리합니다. 첫 번째 규칙은 지정된 주소 대역을 직접 연결하고, 두 번째 규칙은 도메인 일치와 차단 결과를 확인하는 데 사용하며, 마지막 규칙은 기본 경로를 지정합니다. 원격 노드가 필요 없으므로 테스트 설정에서 로그를 먼저 확인한 뒤 같은 순서를 실제 설정에 적용할 수 있습니다. 편집할 때는 차단 규칙의 도메인 접미사를 지나치게 넓게 지정하지 않도록 주의하세요.
프록시 그룹은 규칙에서 참조하는 이름과 실제 연결을 처리하는 출구를 분리합니다. 같은 트래픽의 출구를 바꿀 때는 그룹 안에서 선택만 변경하면 되므로 도메인 규칙을 하나씩 수정할 필요가 없습니다. 예시의 수동 선택 그룹에는 직접 연결과 차단만 있으며, 별도의 테스트 설정에서 전환 결과를 확인하기 좋습니다. 일상적으로 사용하는 설정에 옮길 때는 파일에 실제로 있는 노드나 그룹 이름으로 바꾸세요. 자동 속도 측정 그룹에는 별도의 테스트 대상과 간격이 필요합니다. 모바일 기기에서 사용할 때는 추가 탐색으로 기기가 깨어나는 점도 고려하세요.
규칙 대상은 프록시 그룹의 name과 정확히 일치해야 합니다.
전환 결과를 확인할 때는 연결을 새로 만들고, 이미 열려 있는 장시간 연결로 판단하지 마세요.
mode: rule
proxy-groups:
- name: 수동 선택
type: select
proxies:
- DIRECT
- REJECT
rules:
- DOMAIN,example.org,수동 선택
- MATCH,DIRECT
내장 DNS와 앱별 조회 경로
내장 DNS는 코어에 도달한 도메인 조회를 처리하고, nameserver에는 사용할 상위 DNS 서버 주소를 지정합니다. 내장 DNS를 켜도 모든 앱이 이를 사용하는 것은 아닙니다. 브라우저에서 자체 보안 DNS를 사용하거나 운영체제가 네트워크 연결 설정에 따라 별도로 조회할 수 있습니다. 문제를 확인할 때는 먼저 어느 쪽에서 요청을 보냈는지 파악한 뒤 상위 DNS 서버에 연결할 수 있는지 확인하세요. 사내 도메인이 전용 DNS 서버에 의존한다면 기존 설정을 공용 DNS 서버로 바꾸지 않는 것이 좋습니다.
예시에서는 내장 DNS를 활성화했지만 로컬 네트워크에는 DNS 서비스를 공개하지 않습니다.
같은 문제가 발생한 도메인의 조회 결과를 먼저 비교한 뒤 어느 쪽을 바꿀지 결정하세요.
dns:
enable: true
nameserver:
- 223.5.5.5
가상 네트워크 인터페이스와 시스템 라우팅
시스템 프록시만 켜면 해당 설정을 사용하지 않는 앱도 있습니다. TUN을 지원하는 클라이언트는 가상 네트워크 인터페이스와 라우팅을 통해 더 많은 트래픽을 코어로 전달할 수 있지만, 운영체제 권한이 필요하고 프린터, 공유 폴더, 회사 네트워크의 연결 경로가 달라질 수 있습니다. 이 예시는 관련 항목을 지원하는 Mihomo 데스크톱 환경을 대상으로 합니다. 활성화하기 전에 현재 네트워크 상태를 기록해 두세요. 전환 후 로컬 서비스에도 연결할 수 없다면 가상 네트워크 인터페이스를 끄고 다시 확인하세요. 규칙과 DNS 설정을 동시에 바꾸지는 마세요.
auto-route는 자동 라우팅 설정을 활성화합니다.
auto-detect-interface는 출구 네트워크 인터페이스를 자동으로 찾습니다.
tun:
enable: true
stack: system
auto-route: true
auto-detect-interface: true
설정 프로필과 프록시 그룹 선택 저장
클라이언트 화면의 설정 프로필은 보통 로컬 파일과 원격 구독 목록을 뜻합니다. 반면 Mihomo 설정의 profile은 일부 실행 상태를 저장할지 제어하므로 서로 다른 기능입니다. 아래 예시는 수동으로 선택한 프록시 그룹을 저장해 재시작 후에도 선택을 복원합니다. 구독을 업데이트하면서 노드가 삭제되거나 그룹 이름이 바뀌면 기존 선택이 더는 유효하지 않을 수 있습니다. 사용자 규칙을 장기간 유지하려면 클라이언트에 별도의 덮어쓰기 기능이 있는지 확인하세요. 다음 새로고침 때 교체될 파일에만 수정 사항을 남기지 마세요.
메모에 적힌 mixed-port: 7890은 예시일 뿐, 모든 클라이언트에서 같은 포트를 쓰는 것은 아닙니다. 127.0.0.1은 현재 기기를 가리키므로 휴대폰에서 같은 주소를 입력해도 컴퓨터에 연결되지 않습니다. 이 기기에서만 사용할 경우 allow-lan: false를 유지하고, 실제 리스닝 포트는 클라이언트에 표시된 값을 확인하세요. 포트 충돌이 발생하면 해당 포트를 다른 프로그램이 사용 중인지 확인한 뒤 변경하고, 이전 포트를 직접 입력한 앱도 함께 수정하세요.
처음에는 정상적으로 인터넷에 연결되던 상태를 최대한 유지하고 설정을 한 번에 하나씩만 바꾸세요. 먼저 설정을 불러올 수 있는지 확인하고, 다음으로 요청이 코어에 도달하는지 살펴본 뒤, 마지막으로 규칙이 어느 경로로 보내는지 확인합니다. 두 번째 단계에서 문제가 생겨도 구독을 다시 가져올 필요가 없습니다.
01 / config.yaml
설정 가져와 활성화하기
설정 또는 구독 화면에서 기존 로컬 파일이나 구독 주소를 추가하세요. 가져오기가 끝나면 프록시 그룹과 규칙이 표시되는지 확인하고 해당 프로필을 선택해 현재 적용된 설정인지 확인합니다. 다운로드 성공만 표시되고 내용이 불러와지지 않았다면 가져오기 로그에서 형식 오류나 네트워크 오류를 살펴보세요. 구독 주소에는 접근 자격 증명이 포함될 수 있으니 오류를 공유할 때 전체 주소가 보이는 화면을 올리지 마세요.
02 / mode: rule
규칙 모드와 트래픽 처리 방식 선택하기
일상적인 사용에는 규칙 모드를 선택하세요. 전달할 규칙이 올바른 프록시 그룹을 가리키는지 확인한 뒤 그룹에서 사용할 출구를 살펴봅니다. 데스크톱에서는 먼저 시스템 프록시 설정을 따르는 앱으로 테스트하고, 휴대폰에서는 클라이언트의 연결 기능을 사용해 운영체제 권한을 승인하세요. 규칙 모드와 시스템 프록시를 둘 중 하나만 골라야 하는 기능으로 혼동하지 마세요. 규칙 모드는 트래픽 분기 방식을, 시스템 프록시는 요청이 들어오는 경로를 정합니다.
03 / 127.0.0.1
연결 기록과 규칙 일치 결과 확인하기
새 웹 요청을 보낸 뒤 클라이언트의 연결 기록에서 도메인, 일치한 규칙, 출구를 확인하세요. 새 기록이 전혀 없다면 앱이 프록시 경로를 사용하는지 살펴보세요. 기록은 있지만 연결에 실패한다면 프록시 그룹, DNS, 연결 오류를 확인하세요. 명령줄을 테스트할 때는 터미널 프로그램이 읽는 프록시 설정을 따로 확인하고, 브라우저 결과만으로 판단하지 마세요.
네트워크를 복구해야 한다면 방금 활성화한 트래픽 처리 방식을 먼저 끄고 시스템 프록시가 원래 상태로 돌아왔는지 확인하세요. 클라이언트 프로세스를 바로 종료하면 시스템 프록시가 로컬 포트를 계속 가리킬 수 있습니다. 복구한 뒤에는 어떤 설정을 바꾸자 증상이 달라졌는지 기록해 두세요. 다음에는 해당 단계부터 확인하면 되므로 재설치할 필요가 없습니다.
Clash 오픈소스넷은 클라이언트 안내, 설정 예시, 문제 해결 방법을 정리한 독립 자료 사이트입니다. 클라이언트의 릴리스 안내, 유지 관리 상태, 기능 범위는 각 프로젝트의 정보를 확인하세요. 소스 코드를 살펴볼 때는 네트워크 처리를 담당하는 코어와 이를 제어하는 클라이언트 인터페이스를 구분해야 합니다.
프로젝트의 변천: 같은 이름 아래 서로 다른 프로젝트
초기 Clash 프로젝트는 프록시 노드, 프록시 그룹, 분기 규칙을 하나의 설정 파일에서 관리했습니다. 원 프로젝트의 유지 관리는 중단됐지만 설정 구조와 사용 방식은 커뮤니티의 다른 프로젝트에서 이어지고 있습니다. 예전 가이드의 화면, 메뉴 경로, 설정 항목을 현재 클라이언트의 사용법으로 그대로 적용할 수는 없습니다. 오래된 화면은 개념을 이해하는 데 참고하고, 구체적인 조작 방법은 현재 프로젝트의 안내를 확인하세요.
오래된 프로필을 옮길 때는 원본을 보관하고 복사본을 만든 뒤 공통 설정 항목, 노드 유형, 규칙 대상을 비교하세요. 기존 프로필을 불러올 수 있어도 모든 설정이 예전과 같은 방식으로 처리된다는 보장은 없습니다. 먼저 기본 연결을 확인하고 의존성이 큰 기능을 하나씩 복원하는 편이 옮기는 과정에서 파일 전체를 다시 작성하는 것보다 문제를 찾기 쉽습니다.
커뮤니티의 역할: 인터페이스 기능과 트래픽 처리 방식
그래픽 클라이언트는 보통 설정 프로필, 시스템 연동, 로그 표시를 관리합니다. 비슷한 코어를 사용하는 클라이언트라도 트레이 메뉴, 시작 시 자동 실행, 백그라운드 서비스, 설정 덮어쓰기 위치는 다를 수 있습니다. 운영체제 권한이나 설치 화면 문제는 클라이언트 프로젝트 안내에서 먼저 확인하세요. 규칙 처리와 프로토콜 지원은 코어 문서를 참고하는 편이 좋습니다.
공개된 문제 기록을 찾아볼 때는 설명에 나온 운영체제와 재현 조건부터 확인하세요. 같은 오류 문구도 파일 권한, 시스템 네트워크 서비스, 설정 문법 등 원인이 다를 수 있습니다. 문제를 제출할 때는 필요한 설정 항목만 추린 내용, 오류가 발생한 단계, 관련 로그를 제공하세요. 먼저 노드 정보, 구독 주소, 로그에 포함된 개인정보를 삭제해야 합니다.
코어의 계보: Clash.Meta에서 Mihomo까지
Mihomo는 Clash.Meta의 개발을 이어 온 프로젝트 이름입니다. 공개 저장소는 MetaCubeX에서 관리하며 GPL-3.0 라이선스를 적용합니다. 관련 기능을 지원하는 클라이언트는 사용자가 선택한 설정을 코어에 전달하고, 코어는 리스닝, 규칙 매칭, 연결 전달을 처리합니다. 클라이언트가 화면 설정을 최종 설정에 병합할 수도 있으므로 가져온 파일과 코어가 실제로 불러온 내용은 완전히 같지 않을 수 있습니다.
설정 항목의 적용 여부를 확인하려면 저장한 설정과 클라이언트가 제공하는 적용 설정을 비교한 뒤 코어 로그를 확인하세요. 버튼 이름만 보고 내부 상태를 짐작하지 마세요. 예를 들어 시스템 프록시가 켜졌다고 해서 가상 네트워크 인터페이스도 활성화된 것은 아닙니다. 두 설정은 서로 다른 트래픽 경로를 바꿉니다.
업데이트 확인: 앱, 코어, 구독은 각각 따로
프로그램 업그레이드는 클라이언트 자체를 업데이트합니다. 설치 파일에 코어 업데이트가 포함되는지는 프로젝트마다 다릅니다. 구독 새로고침은 설정 내용을 업데이트하고 규칙 집합에는 별도의 갱신 주기가 있을 수 있습니다. 화면에서는 이 작업을 모두 ‘업데이트’라고 부르기도 하지만 바뀌는 대상은 서로 다릅니다. 문제가 생기면 가장 최근에 업데이트한 항목을 기록하고 해당 프로젝트의 변경 사항을 확인하세요.
변경하기 전에 이전에 정상적으로 작동했던 설정을 복사해 두고, 변경 후에는 원래 잘 되던 요청부터 다시 확인하세요. 구독을 새로고침한 뒤 문제가 생겼다면 프록시 그룹과 규칙 참조가 바뀌었는지 살펴보세요. 앱을 업그레이드한 뒤에 문제가 시작됐다면 시스템 권한과 시작 로그를 확인하세요. 연결을 한 번 복구하려고 구독 새로고침, 설정 덮어쓰기, 코어 교체를 동시에 하지 마세요.
Mihomo 소스 코드 보기
MetaCubeX/mihomo 저장소에서 소스 코드, 라이선스, 릴리스 기록을 확인할 수 있습니다. 아래 명령을 실행하려면 먼저 Git을 설치해야 합니다. 소스 코드는 현재 디렉터리의 mihomo 하위 디렉터리에만 가져오며, 클라이언트를 설치하거나 시스템 프록시를 변경하지 않습니다. 실행 가능한 프로그램이 필요하다면 다운로드 페이지에서 운영체제에 맞는 파일을 선택하세요.
git clone https://github.com/MetaCubeX/mihomo.git
127.0.0.1 / 문제 해결 기록
Clash 설치 및 문제 해결 가이드
문제 해결 가이드는 증상별로 나뉘어 있습니다. 프로그램이 열리지 않으면 시작 로그부터 확인하세요. 프로그램은 열리지만 트래픽이 흐르지 않으면 앱과 로컬 포트의 연결을 점검하세요. 특정 앱 하나만 연결되지 않는다면 해당 앱이 사용하는 프록시 설정부터 살펴보세요. 현재 증상과 가장 가까운 가이드를 선택하면 됩니다.