Windows
시스템의 기기 정보에서 프로세서 아키텍처를 확인하세요. 일반적인 Intel 및 AMD PC에는 x64 패키지를 사용하고, ARM 프로세서 기기는 해당 클라이언트가 지원하는 빌드가 있는지 확인해야 합니다. 설치 후 설정을 가져온 다음 시스템 프록시를 켜세요. 테스트는 통과했는데 특정 앱만 프록시를 사용하지 않는다면, 앱이 시스템 설정을 따르는지 확인하세요. 구독을 먼저 바꾸지는 마세요.
다운로드 페이지로 이동오픈 소스 코어 · 설정 문서 지속 업데이트
운영체제에 맞는 호환 클라이언트를 선택하고, YAML 예제로 mihomo의 포트와 DNS, 트래픽 분기 규칙을 알아보세요.
01 Downloads
먼저 운영체제를 확인한 다음 설치 파일 아키텍처를 선택하세요. 데스크톱에서는 GUI 클라이언트와 독립 실행형 코어를 구분해야 합니다. 처음이라면 GUI 클라이언트부터 시작하면 됩니다.
시스템의 기기 정보에서 프로세서 아키텍처를 확인하세요. 일반적인 Intel 및 AMD PC에는 x64 패키지를 사용하고, ARM 프로세서 기기는 해당 클라이언트가 지원하는 빌드가 있는지 확인해야 합니다. 설치 후 설정을 가져온 다음 시스템 프록시를 켜세요. 테스트는 통과했는데 특정 앱만 프록시를 사용하지 않는다면, 앱이 시스템 설정을 따르는지 확인하세요. 구독을 먼저 바꾸지는 마세요.
다운로드 페이지로 이동‘이 Mac에 관하여’에서 칩 또는 프로세서를 확인한 뒤 Apple Silicon 또는 Intel용 패키지를 선택하세요. 메뉴 막대 상태로 클라이언트 실행 여부는 알 수 있지만, 모든 앱의 연결이 프록시를 거치는지는 확인할 수 없습니다. 설정을 바꾼 뒤 연결 기록에서 현재 요청을 확인하세요. 테스트를 마치고 종료할 때는 시스템 프록시 설정이 복구됐는지도 확인하세요.
다운로드 페이지로 이동기기가 지원하는 앱 아키텍처에 맞춰 설치 파일을 선택하세요. 프로세서가 64비트인지 여부만으로 판단하지 마세요. 처음 실행할 때는 시스템 VPN 연결 요청을 허용해야 할 수 있습니다. 백그라운드로 전환한 뒤 연결이 끊기면 클라이언트 실행 상태와 시스템 배터리 관리 설정을 먼저 확인하세요. 업무용 프로필이나 다른 VPN이 설치된 기기라면 현재 연결을 관리하는 앱도 확인해야 합니다.
다운로드 페이지로 이동다운로드 페이지에서 App Store로 이동해 호환 클라이언트와 시스템 요구 사항을 확인하세요. 설정을 가져온 뒤 시스템 안내에 따라 VPN 구성을 추가하도록 허용하고, 클라이언트로 돌아와 현재 선택된 설정을 확인하세요. 데스크톱에서 저장한 YAML은 이전 작업의 출발점으로 쓸 수 있지만, 로컬 파일 경로와 프록시 모드 이름, 고급 필드는 그대로 사용할 수 없을 수 있습니다.
다운로드 페이지로 이동데스크톱 클라이언트는 배포판에서 지원하는 패키지 형식과 프로세서 아키텍처를 기준으로 선택하세요. 설치 전에 시스템 패키지 관리자가 사용하는 형식을 확인하고, 같은 아키텍처라도 형식이 다르면 서로 바꿔 쓸 수 있다고 가정하지 마세요. 터미널 명령과 GUI 앱의 프록시 설정은 서로 독립적일 수 있습니다. 터미널에서만 요청을 보낸다면 해당 프로그램이 실제로 읽는 프록시 설정부터 확인하세요.
다운로드 페이지로 이동02 Config Reference
먼저 인바운드, 아웃바운드, 매칭 조건을 구분하세요. 필드를 클릭하면 참고할 예제를 볼 수 있습니다. 예제는 설정의 일부 구조를 설명하며, 구독과 노드를 포함한 완성 파일은 아닙니다.
혼합 포트는 로컬 앱의 HTTP 및 SOCKS 프록시 연결을 모두 받습니다. 앱이 코어에 접속할 때 사용하는 포트이지, 원격 노드의 포트가 아닙니다. 현재 기기에서만 사용할 때는 먼저 LAN 연결을 끄고 앱에 입력한 주소와 포트를 확인하세요. 포트가 이미 사용 중이라면 해당 프로세스를 찾아 코어와 앱의 설정을 함께 변경하세요. 한쪽만 바꾸면 요청이 코어에 도달하지 않아 연결 로그에 규칙 매칭 기록도 남지 않을 수 있습니다.
먼저 요청이 코어의 DNS 모듈에 도달하는지 확인한 다음 적절한 확인 모드를 선택하세요. fake-ip는 매핑 주소를 먼저 반환하고, 코어가 이후 연결에서 도메인을 식별하도록 합니다. 그렇다고 시스템의 모든 DNS 요청이 자동으로 코어에 전달되는 것은 아닙니다. 문제를 확인할 때는 브라우저의 보안 DNS, 시스템 DNS 확인, 코어 DNS 확인을 구분하세요. 특정 도메인에서만 매핑 주소와 호환되지 않는 문제가 생길 때 해당 도메인의 필터 항목을 점검하고, 서비스 하나 때문에 전체 DNS 설정을 바꾸지는 마세요.
mixed-port: 7890
allow-lan: false
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
규칙 모드에서는 위에서 아래로 규칙을 확인하며, 먼저 일치한 규칙이 지정한 아웃바운드로 요청을 처리합니다. 도메인 접미사 규칙은 같은 접미사를 공유하는 도메인에 적용되고, 지역 규칙에는 해당 지리 데이터가 필요합니다. 구체적인 예외 규칙을 더 넓은 범위의 규칙보다 앞에 두고, 조건이 없는 MATCH는 맨 마지막에 배치하세요. 트래픽이 잘못 전달되면 연결 기록에서 실제로 매칭된 규칙을 확인한 뒤 규칙 대상과 현재 정책을 점검하세요. 규칙이 올바르더라도 그룹에서 다른 아웃바운드를 선택하면 결과가 달라질 수 있습니다.
url-test는 테스트 주소의 연결 상태와 응답 시간을 비교해 아웃바운드 후보를 선택합니다. 허용 오차를 설정하면 잦은 전환을 줄일 수 있습니다. 이 테스트는 하나의 테스트 경로만 확인하며, 모든 트래픽이 같은 경로를 이용한다는 뜻은 아닙니다. fallback은 지정한 우선순위에 따라 사용 가능한 항목을 고를 때, load-balance는 연결을 분산할 때 적합합니다. 예제의 두 노드 이름은 같은 설정 파일에 정의되어 있어야 합니다. 테스트 주소도 해당 네트워크에서 검증된 적절한 주소로 바꾸세요.
mode: rule
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- GEOIP,LAN,DIRECT,no-resolve
- MATCH,DIRECT
proxy-groups:
- name: 자동 속도 테스트
type: url-test
proxies: [노드 A, 노드 B]
url: https://example.com/
interval: 300
tolerance: 50
proxies는 코어가 원격 노드에 연결하는 방식을 정의하고, 노드의 type에 따라 나머지 필드의 해석 방식이 결정됩니다. 아래 SOCKS5 예제의 주소는 문서용 예약 대역에서 가져온 것으로, 실제 사용할 수 있는 노드 주소가 아닙니다. 원격 port를 시스템의 로컬 프록시 포트에 입력하거나, 한 프로토콜의 전송 옵션을 다른 프로토콜에 그대로 가져오지 마세요. 가져오기 중 알 수 없는 필드 오류가 나면 클라이언트 이름만 보지 말고 실행 중인 코어와 노드 프로토콜을 확인하세요.
먼저 일반 로그로 시작, 설정 로드, 연결 처리를 확인한 뒤 필요할 때만 잠시 디버그 로그를 켜세요. 설정을 편집하고 저장해도 코어가 다시 로드됐다는 뜻은 아닙니다. 클라이언트의 오버라이드 설정이 로그 수준을 바꿀 수도 있습니다. 문제를 재현하기 전에 현재 설정 이름을 기록하고, 같은 앱에서 요청을 한 번 보낸 뒤 연결 기록과 실제 시각을 대조하세요. 다른 사람에게 점검을 요청하기 전에는 구독 주소와 노드 인증 정보, 공개하기 곤란한 도메인을 삭제하세요. 확인이 끝나면 기존 로그 수준으로 되돌리세요.
proxies:
- name: 문서 예제
type: socks5
server: 192.0.2.10
port: 1080
log-level: info
설정 읽는 순서: 먼저 mixed-port, mode 같은 최상위 필드를 확인하세요. 다음으로 proxies에 정의된 아웃바운드를 살펴보고, 마지막으로 proxy-groups와 rules가 각 이름을 어떻게 참조하는지 확인합니다. 정책 그룹 이름도 참조 관계의 일부입니다. 이름을 바꾸면 중첩된 그룹 참조와 규칙 끝의 대상도 함께 바꿔야 합니다. YAML 문법은 유효해도 코어가 설정을 로드하지 못할 수 있습니다.
수정할 위치: 구독 원본, 로컬 오버라이드, 클라이언트가 생성한 최종 설정은 서로 다른 파일입니다. 업데이트 후 수정 사항이 사라졌다면 먼저 어느 계층을 편집했는지 확인하세요. 일부 수정 사항을 계속 유지하려면 클라이언트가 지원하는 오버라이드 계층에 넣고, 목록 항목이 추가되는지 교체되는지도 확인해야 합니다. 특히 rules 전체를 교체하면 기존 예외가 사라질 수 있고, MATCH 뒤에 규칙을 추가하면 해당 규칙이 매칭되지 않을 수 있습니다. 전체 문법은 설정 필드 레퍼런스에서 확인하세요.
03 Quick Start
처음 사용할 때는 설정 선택, 트래픽 연결, 요청 테스트 세 가지만 진행하세요. 기본 흐름을 먼저 확인한 뒤 DNS나 규칙을 수정하세요.
클라이언트의 설정 페이지에서 구독 링크나 로컬 YAML을 가져오세요. 업데이트가 완료되면 해당 설정을 선택하고 프록시 페이지에서 정책 그룹을 펼칠 수 있는지 확인합니다. 파일 이름만 보인다면 설정 항목이 저장된 것이고, 그룹과 구성원까지 보이면 정상적으로 로드됐을 가능성이 높습니다. 가져오기 오류가 나면 오류가 표시된 줄과 필드 이름, 다운로드 안내부터 확인하세요. 같은 구독을 연달아 다시 추가할 필요는 없습니다.
config.yaml · 설정 가져오기
도메인이나 주소에 따라 트래픽을 분기하려면 규칙 모드를 선택하고 정책 그룹에서 현재 아웃바운드를 확인하세요. 데스크톱에서는 클라이언트 안내에 따라 시스템 프록시를 켜고, 모바일에서는 안내에 따라 VPN 연결을 설정합니다. 연결 방식과 정책 그룹을 동시에 바꾸지 마세요. 결과가 달라져도 어느 설정이 영향을 줬는지 알기 어렵습니다. 다른 프록시가 실행 중이라면 이번에 사용할 연결 경로부터 확인하세요.
mode: rule · 시스템 프록시
자주 쓰는 앱에서 페이지를 다시 열고 연결 기록에서 해당 도메인, 매칭된 규칙, 아웃바운드를 확인하세요. 기록이 없다면 앱이 현재 연결 경로를 사용하는지 확인합니다. 기록은 있지만 요청에 실패했다면 DNS, 정책, 노드 상태를 확인하세요. 페이지 캐시와 기존 연결이 판단에 영향을 줄 수 있으므로 새 요청을 보내세요. 테스트가 한 번 성공한 뒤 사용자 설정을 하나씩 복원하세요.
요청 대상 → 매칭 규칙 → 실제 아웃바운드
설치 및 연결 관련 문제는 Clash 자주 묻는 질문에서 확인하세요.
04 Project Sources
소스 코드, 클라이언트, 구독은 서로 다른 프로젝트나 서비스에서 제공합니다. 문제가 생기면 먼저 담당 주체를 확인한 뒤 해당 문서와 릴리스 노트, 이슈 기록을 살펴보세요.
Clash 생태계의 설정 파일은 노드 정의, 정책 그룹 구성, 규칙에 따른 아웃바운드 선택 등 여러 공통 개념을 사용합니다. mihomo는 Clash.Meta의 개발 흐름을 이어받아 이 구조에 기능을 더했습니다. 기존 가이드의 일반적인 설정은 참고 자료로 활용할 수 있지만, 특정 프로토콜이나 DNS 필드, 규칙 유형은 현재 실행 중인 코어를 기준으로 확인해야 합니다. 화면에 같은 이름이 표시된다고 해서 클라이언트마다 해당 필드를 동일하게 해석한다고 단정할 수는 없습니다. 오래된 설정 파일을 옮길 때는 최소한의 설정부터 시험한 다음 고급 옵션을 단계별로 복원하세요.
mihomo 소스 코드 저장소는 공개되어 있으며 GPL-3.0 라이선스를 따릅니다. 필드의 의미나 동작 방식을 확인하려면 저장소의 관련 코드와 변경 기록, 알려진 이슈를 먼저 살펴보세요. 트레이 메뉴, 구독 업데이트 버튼, 기기 권한과 관련된 문제라면 보통 코어 저장소가 아니라 해당 클라이언트의 자료를 확인해야 합니다. 라이선스와 소스 기록은 각 프로젝트의 배포 및 이용 허가에 관한 정보입니다. 구독 서비스의 이용 조건을 대신하지 않으며, 한 프로젝트의 라이선스로 다른 클라이언트나 규칙 데이터의 이용 조건을 추정해서도 안 됩니다.
클라이언트가 설정을 가져와 정리하면 코어가 최종 설정을 읽고 실제 연결을 처리합니다. 구독 가져오기 실패는 설정 수신 단계, 지원되지 않는 필드는 로드 단계, 규칙이 매칭됐는데 연결되지 않는 문제는 실행 단계에 해당합니다. 문제 해결은 어느 단계에서 멈췄는지 먼저 파악한 뒤 구독 응답, 로드 오류, 연결 로그를 확인하세요. 재현 과정을 공유할 때는 필드 구조와 오류 유형을 남기고 실제 노드 주소 대신 문서용 주소를 사용하세요. 문제를 설명하면서도 구독에 접근할 수 있는 링크를 공개하지 않을 수 있습니다.
클라이언트를 업그레이드하면 화면 구성이나 함께 제공되는 코어가 바뀔 수 있습니다. 구독 새로고침은 보통 설정을 다시 가져오는 작업이며, 지리 데이터베이스나 규칙 세트 업데이트는 별도의 경로입니다. 변경 원인을 찾을 때는 가장 최근에 실행한 업데이트 종류를 기록하고, 업데이트 전 정상 작동하던 로컬 설정을 보관하세요. 구독 업데이트 후에만 문제가 생겼다면 최종 규칙 순서나 노드 필드를 비교하세요. 지역 매칭이 달라졌다면 현재 데이터 출처와 업데이트 시각, 정상적으로 로드됐는지 확인합니다. 한 번에 한 종류만 변경한 뒤 같은 앱에서 같은 대상을 다시 테스트하세요.
05 Field Notes
설정 레퍼런스는 필드별로, 사용 팁은 작업별로 찾아볼 수 있습니다. 아래 글에서는 기기 간 동기화, 모바일 가져오기, 클라이언트 화면을 다룹니다.
컴퓨터와 휴대폰 간 Clash 설정 동기화 방법을 비교합니다. 구독 링크 직접 사용, 오버라이드 파일, WebDAV 백업, 비공개 Git 저장소를 살펴보고 각각의 관리 부담과 주의 사항을 정리합니다.
iOS에서 Clash 설정을 지원하는 클라이언트를 App Store에서 받고, 구독 링크나 YAML 파일을 가져온 뒤 VPN 프로파일을 활성화해 처음 연결하는 방법을 안내합니다.
화면 순서에 따라 프록시 페이지의 그룹과 속도 테스트, 설정 페이지의 구독과 전환, 로그 페이지의 수준 필터를 설명합니다. 처음 사용하는 사람도 버튼과 상태 표시의 의미를 빠르게 이해할 수 있습니다.