오픈 소스 커널 · YAML 설정 항목별 안내

Clash 설정 가이드Ubuntu 및 전 플랫폼 클라이언트

Clash 다운로드 설정 가이드 보기

클라이언트 선택부터 config.yaml 항목까지, 설정 구조에 따라 mihomo 커널을 이해해 보세요.

  • 중국어 문서
  • 규칙 기반 라우팅
  • Ubuntu 배포
Windows Android iOS macOS Linux

설정 문법과 오픈 소스 커널 생태계

PLATFORM / CLIENT

운영체제별 다운로드

먼저 운영체제를 선택한 뒤 프로세서 아키텍처를 확인하세요. 데스크톱 앱, 모바일 네트워크 확장 기능, 명령줄 커널은 설치 방법이 서로 다르지만 설정 원리는 참고할 수 있습니다.

Windows

데스크톱에서 처음 사용한다면 Clash Plus를 살펴보고, 필요에 따라 Clash Verge Rev나 FlClash 등과 비교해 보세요. 설정을 가져온 뒤 시스템 프록시를 켜면 해당 설정을 따르는 앱이 로컬 포트에 연결됩니다. 더 많은 앱의 트래픽을 처리해야 한다면 TUN 모드와 필요한 권한을 확인하세요.

설치 전에 시스템 정보에서 프로세서 아키텍처를 확인하세요. 이전 클라이언트가 백그라운드에서 실행 중이라면 먼저 종료하고 프록시 포트를 점검해 커널 두 개가 동시에 포트를 열지 않도록 하세요. 스토어 앱의 접속 문제는 루프백 제한 때문일 수도 있습니다. 브라우저에서 페이지가 열리는지만으로 모든 앱의 연결 상태를 판단할 수는 없습니다.

다운로드 Windows 클라이언트

macOS

Apple Silicon 또는 Intel 프로세서에 맞는 설치 파일을 선택하고 Clash Plus, Clash Verge Rev, FlClash부터 비교해 보세요. 메뉴 막대의 스위치는 보통 시스템 프록시를 제어합니다. 커널이 현재 설정을 읽었는지는 설정 화면과 로그에서 각각 확인해야 합니다.

처음 실행할 때는 시스템 안내에 따라 필요한 권한을 부여하세요. 네트워크 확장 권한과 일반 앱 실행 권한은 서로 다릅니다. 다른 클라이언트로 전환하기 전에는 기존 클라이언트의 프록시와 백그라운드 서비스를 먼저 끄세요. ClashX Meta 보관 페이지는 호환성 참고용으로 활용하고, 장기간 사용할 클라이언트는 현재도 유지 관리되는 프로젝트를 우선 고려하세요.

다운로드 macOS 클라이언트

Android

Clash Plus, Clash Meta for Android, FlClash, Surfboard 중에서 선택하고 각 앱이 지원하는 설정 형식을 확인하세요. 대부분의 모바일 클라이언트는 시스템 VPN 인터페이스로 트래픽을 처리합니다. 처음 연결할 때 시스템 권한을 허용해야 하며, 일반적으로 한 번에 하나의 VPN 서비스만 트래픽을 처리할 수 있습니다.

백그라운드 연결이 끊기면 먼저 배터리 최적화와 앱의 백그라운드 실행 제한을 확인한 다음 구독과 DNS를 점검하세요. 앱별 라우팅은 클라이언트 설정의 영향을 받을 수 있습니다. YAML에 규칙이 있어도 처리 대상에서 제외된 앱에는 해당 규칙이 적용되지 않습니다. 문제를 찾을 때는 두 설정을 함께 확인하세요.

다운로드 Android 클라이언트

iOS

다운로드 페이지에서 Clash Plus의 App Store 링크와 공식 사이트 clashplus.io를 확인할 수 있습니다. 설치 후 앱이 지원하는 설정을 가져오고 시스템 안내에 따라 VPN 구성을 추가하세요. 데스크톱의 포트, 서비스 관리, 권한 설정을 휴대폰에 그대로 적용할 수는 없습니다. 앱에서 제공하는 설정을 기준으로 사용하세요.

설정을 가져왔다는 것은 앱이 해당 설정을 받아들였다는 뜻일 뿐, 모든 프로토콜 항목이 동일하게 구현되었다는 의미는 아닙니다. 특정 연결만 실패하면 노드 유형과 클라이언트 호환성을 확인한 다음 정책 그룹 선택을 점검하세요. 시스템 네트워크 전환, 주문형 연결, 백그라운드 동작도 영향을 줄 수 있으므로 각각 따로 기록하고 여러 설정을 한꺼번에 바꾸지 마세요.

다운로드 iOS 클라이언트

Linux / Ubuntu

Ubuntu 데스크톱에서는 Clash Verge Rev와 FlClash를 살펴보고 배포판과 패키지 형식에 맞춰 설치할 수 있습니다. 서버나 라우터에서는 mihomo를 별도로 배포할 수 있습니다. GUI 클라이언트는 트레이, 설정 관리, 시스템 통합을 담당하며, 독립 커널은 작업 디렉터리와 설정 파일 경로, 서비스 실행 방식을 직접 지정해야 합니다.

GNOME 시스템 프록시는 해당 설정을 따르는 데스크톱 앱에 주로 적용되며, 터미널 프로그램은 프록시 환경 변수를 별도로 설정해야 할 수 있습니다. systemd를 사용할 때는 서비스 계정의 설정 파일 읽기 권한, 포트 바인딩 실패 여부가 로그에 표시되는지, TUN에 필요한 권한이 있는지 확인하세요. 모든 프로그램을 관리자 권한으로 실행하는 방식으로 해결하려 해서는 안 됩니다.

다운로드 Linux 클라이언트
전체 클라이언트 보기 →

CONFIG / FIELD NOTES

config.yaml 설정 섹션 둘러보기

요청 수신, 도메인 조회, 연결 경로 선택, 규칙 매칭 순서로 살펴보세요. 아래 예시는 항목 간 관계만 보여 주며, 사용할 수 있는 노드가 포함된 완전한 설정 파일은 아닙니다.

YAML은 들여쓰기로 계층을 표현하므로 항목 이름뿐 아니라 위치도 중요합니다. 수정 전에 현재 파일을 백업하고 한 번에 한 종류의 설정만 변경한 다음, 클라이언트의 설정 검사나 커널 테스트로 문법을 확인하세요. 화면에 표시된 설정 이름, 디스크에 저장된 구독 파일, 실행 중 병합된 설정은 서로 다를 수 있습니다. 문제를 찾을 때는 실제로 불러온 내용을 기준으로 확인하세요.

왼쪽의 general은 기본 항목을 구분하기 위해 이 가이드에서 붙인 이름이며, 파일에 입력해야 하는 최상위 키가 아닙니다. 다른 탭은 실제 설정 섹션을 가리킵니다. 여러 예제를 그대로 합치기보다 각 섹션의 역할을 먼저 이해한 뒤 필요한 항목을 추가하면 충돌을 찾기 쉽습니다. 클라이언트별 기본값과 덮어쓰기 방식은 각 앱의 안내를 확인하세요.

general

포트, 모드, 로그

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

기본 항목은 커널이 요청을 받는 방식을 결정합니다. mixed-port는 HTTP와 SOCKS5가 함께 사용하는 포트이므로 값을 변경하면 프록시 주소를 직접 입력한 앱도 함께 수정해야 합니다. allow-lan은 로컬 네트워크 연결 허용 여부를 설정하며, 개인용 컴퓨터에서는 보통 끄고 시작합니다. mode를 rule로 설정해야 규칙 기반 라우팅이 적용됩니다. 로그 수준은 우선 info로 두고 문제가 생기면 필요한 만큼 자세한 수준으로 높이세요. 이 항목은 YAML 최상위에 작성해야 합니다. 바깥에 general을 추가하면 커널이 예상한 방식으로 설정을 읽지 못합니다.

가이드에서 자세히 보기 →

OPEN SOURCE / CONTEXT

Clash 생태계와 mihomo 커널

클라이언트 이름을 외우는 것보다 각 소프트웨어의 관계를 이해하는 편이 중요합니다. 오픈 소스 저장소에서 코드, 릴리스 노트, 문제 논의를 확인할 수 있으며, 실제 지원 기능은 사용 중인 커널을 기준으로 확인해야 합니다.

원본 Clash, Meta, mihomo의 관계

Clash는 YAML 중심의 설정 방식을 발전시켜 왔습니다. 요청 수신부는 앱의 연결을 받고, 노드는 사용 가능한 연결 경로를 설명하며, 정책 그룹은 노드를 구성하고, 규칙은 연결 경로를 결정합니다. Clash Meta는 이를 바탕으로 프로토콜과 네트워크 기능을 확장했고, 이후 프로젝트는 mihomo라는 이름으로 계속 발전했습니다. 따라서 가이드에서 Clash Meta와 mihomo는 역사적으로 연결되어 있지만, 이름에 Clash가 들어간 모든 소프트웨어가 같은 기능을 제공한다는 뜻은 아닙니다. 낯선 항목을 발견하면 구독을 반복해서 다시 가져오기보다 먼저 실행 중인 커널 이름을 확인하고 해당 문서를 찾아보세요.

원본 Clash의 주요 공개 구현은 이미 유지 관리가 중단되어 예전 가이드의 기본값, 프로토콜 목록, 설치 방법이 현재 클라이언트에 맞지 않을 수 있습니다. 이전할 때는 사용 중인 프로토콜, DNS 모드, 규칙 세트, 로컬 덮어쓰기 설정을 기록하고 새 환경의 지원 여부를 항목별로 확인하세요. 기본 YAML 구조를 읽을 수 있다는 것만으로 호환성이 보장되지는 않습니다. 노드 전송 매개변수, 규칙 제공자 동작, 운영체제 통합 방식도 다를 수 있습니다. 이전 설정을 백업해 두면 마이그레이션과 문제 해결 때 비교 기준으로 활용할 수 있습니다.

GUI와 네트워크 처리의 역할 구분

데스크톱 클라이언트는 보통 구독 가져오기, 설정 전환, 트레이 메뉴, 자동 실행, 시스템 프록시 켜기·끄기를 담당하고, 커널은 설정을 해석해 실제 연결을 처리합니다. 화면에 실행 중으로 표시되어도 대상 앱이 프록시 경로를 이용한다는 보장은 없으며, 커널이 정상 작동해도 시스템 프록시와 DNS가 제대로 연결되었다는 뜻은 아닙니다. Ubuntu에서는 특히 GNOME 데스크톱 프록시, 터미널 환경 변수, TUN 라우팅을 구분해야 합니다. 각각 적용 범위가 다르므로 대상 앱에 맞는 경로를 선택하면 중복 처리와 라우팅 충돌을 줄일 수 있습니다.

명령줄로 직접 배포하는 방식은 독립 실행, 서비스 관리, 원격 유지 관리가 필요한 경우에 적합하지만 GUI가 대신해 주던 작업을 직접 처리해야 합니다. 설정 파일 경로, 서비스 실행 계정, 로그 확인 방법, 장애 시 중지 방법을 미리 정하세요. systemd의 작업 디렉터리는 상대 경로에 영향을 주며, 접근 권한에 따라 규칙 파일을 읽지 못할 수도 있습니다. 먼저 포그라운드에서 커널이 설정을 불러오는지 확인한 다음 백그라운드 서비스를 구성하면 설정 오류와 서비스 관리 오류를 구분해 찾기 쉽습니다.

업데이트, 구독, 사용자 규칙

클라이언트 업데이트, 커널 업데이트, 구독 업데이트는 서로 다른 작업입니다. 클라이언트 업데이트는 인터페이스와 시스템 통합 방식을 바꿀 수 있고, 커널 업데이트는 설정 항목의 동작에 변화를 줄 수 있으며, 구독 업데이트는 보통 노드와 규칙 내용을 갱신합니다. 변경하기 전에 무엇을 업데이트할지 확인하고 기존 설정을 기록하세요. 설정 병합을 지원하는 클라이언트에서는 개인 규칙을 별도의 덮어쓰기 계층에 두는 편이 다운로드한 구독 파일을 직접 수정하는 것보다 관리하기 쉽습니다. 다만 병합 순서를 확인해 다른 설정에서 개인 DNS 설정을 덮어쓰지 않도록 해야 합니다.

오픈 소스 라이선스는 코드의 사용 및 배포 조건을 정하며, 클라이언트마다 라이선스나 배포 방식이 완전히 같다는 의미는 아닙니다. 이 사이트는 설정 안내와 다운로드 링크를 정리하며 각 프로젝트의 릴리스 안내를 대신하지 않습니다. 문제 논의를 살펴볼 때는 제목이 비슷한지만 보지 말고 운영체제, 커널 유형, 재현 절차를 우선 비교하세요. 로그와 설정을 공유하기 전에 구독 주소, 인증 정보, 개인 네트워크 정보를 삭제하세요. 항목 구조와 오류가 발생한 상황만 남겨도 기술 논의에는 대개 충분합니다.

연결 문제를 단계별로 확인하기

앱에 가까운 단계부터 확인하세요. 앱이 시스템 프록시, 수동 프록시, TUN 중 어떤 방식을 사용하는지 살펴본 다음 로컬 포트와 커널이 정상인지 확인합니다. 이어서 규칙 매칭, 정책 그룹의 현재 선택, 노드 연결 상태, 마지막으로 DNS와 대상 서비스를 점검하세요. 브라우저에서 페이지가 열린다는 사실은 해당 접속 경로가 작동한다는 것만 보여 줄 뿐, 다른 프로그램이나 프로토콜까지 검증해 주지는 않습니다. 한 번에 변수 하나만 바꾸고 변경 전후 로그를 남기면 현상과 설정 사이의 원인을 명확히 파악할 수 있습니다.

DNS 문제는 특히 도메인 조회 실패와 조회는 성공했지만 연결에 실패한 경우를 구분해야 합니다. 전자는 요청 경로, 상위 DNS 서버 연결 상태, 조회 모드를 살펴보고, 후자는 규칙과 연결 경로, 대상 주소까지 확인해야 합니다. HTTPS 인증서 경고도 무조건 프록시 탓으로 돌릴 수 없습니다. 시스템 시간, 인증서 체인, 패킷 분석 도구, 대상 서비스가 모두 원인일 수 있습니다. 페이지를 열기 위해 인증서 검증을 끄지 말고 오류 메시지를 보존한 채 단계별로 확인하세요. 프로토콜별 차이와 커널 선택은 프로토콜 참고 자료에서 확인하고, 단계별 설정은 입문 가이드부터 시작하세요.

NOTES / TROUBLESHOOTING

최근 설정 가이드

실제로 나타난 오류를 바탕으로 원인을 찾아보세요. 먼저 문제가 발생한 단계를 확인한 뒤 설정을 바꿀지 결정하는 것이 좋습니다.

문제 해결

프록시를 켠 뒤 웹페이지에서 인증서 오류가 발생할 때: HTTPS 인증서 오류 원인과 해결 방법

시스템 시간 오류, 중간자 패킷 캡처 도구, 노드에 의한 가로채기, DNS 오염 등 인증서 경고의 원인을 정리하고 Clash 및 프록시와의 관련 여부, 해결 방법을 설명합니다.

인증서 오류의 유형을 기록하고 대상 사이트 자체의 문제와 연결 경로에서 발생한 개입을 구분하세요. 이상을 감추려고 보안 검증을 끄지 마세요.

문제 해결

Clash 실행 시 포트 사용 중 오류: 점유 프로세스 확인과 mixed-port 변경 방법

Windows, macOS, Linux에서 netstat, lsof, ss로 7890 등의 포트를 점유한 프로세스를 찾고, 포트 변경 후 시스템 프록시와 브라우저 설정도 함께 바꾸는 방법을 설명합니다.

먼저 포트를 점유한 프로세스가 이전 클라이언트나 백그라운드 서비스인지 확인한 뒤 프로세스를 중지할지 포트를 바꿀지 결정하세요. YAML만 수정하고 앱에 설정된 이전 프록시 주소를 그대로 두면 연결은 계속 실패합니다.

플랫폼 배포

Ubuntu에 mihomo 커널 배포하기: 데스크톱 클라이언트와 순수 명령줄 systemd 설정

Ubuntu 데스크톱 GUI 클라이언트 설치와 서버의 순수 명령줄 배포를 각각 안내합니다. 바이너리 배치, config.yaml 경로, systemd 서비스 파일, TUN에 필요한 권한 설정을 다룹니다.

데스크톱 인터페이스가 필요한지에 따라 방식을 선택하고, 포그라운드 설정 테스트와 서비스 시작, 자동 실행을 각각 확인하세요. 작업 디렉터리와 권한 문제를 한꺼번에 다루지 않도록 분리해 점검할 수 있습니다.

모든 글 보기 →