MANUAL · 설치 총정리

Clash 전 플랫폼 설치 설정 총정리

5개 플랫폼, 플랫폼당 한 장씩. 다운로드, 설치, 구독 가져오기부터 시스템 프록시와 TUN 모드, 각 플랫폼 특유의 함정까지 참고 매뉴얼 방식으로 구성했습니다. 앞의 두 장은 공통 준비 작업과 프록시 모드 원리를, 마지막 장은 설정 문제 해결을 다룹니다.

CH 01–08 · 총 8장 · 필요한 장부터 바로 찾아보세요

이 페이지는 사용 가이드와 역할이 다릅니다. 사용 가이드는 최단 경로로, 그대로 따라 하면 10여 분 안에 첫 연결을 완료할 수 있습니다. 이 페이지는 시스템 매뉴얼로, 각 플랫폼의 전체 흐름과 원리, 알려진 문제까지 빠짐없이 정리해 설치 과정에서 언제든 참고할 수 있도록 했습니다. Clash를 처음 접한다면 먼저 사용 가이드를 한 번 따라 해 보고, 막히는 부분이 있을 때 이 페이지의 해당 장으로 돌아오는 것을 권장합니다. 모든 클라이언트의 설치 파일 입구는 클라이언트 다운로드 페이지에 통합되어 있으며, 이 페이지 본문은 절차만 설명하고 다운로드 직접 링크는 두지 않습니다.

CH 01준비 작업: 설치 전에 챙겨야 할 것들

필요한 세 가지

첫째는 구독 링크입니다. Clash 클라이언트 자체는 트래픽을 조율하는 도구일 뿐이며, 노드 정보는 구독 제공처가 내려줍니다. 구독 링크는 HTTPS 주소로, 서비스 제공처가 사용자 패널에서 제공합니다. 설치를 시작하기 전에 이 링크를 확실히 준비하고, 완전하게 복사했는지 확인하세요 — 링크가 잘리는 것이 가져오기 실패의 가장 큰 원인이며, 자세한 내용은 구독 파싱 실패 자가 점검 체크리스트를 참고하세요.

둘째는 사용 중인 기기에 맞는 클라이언트입니다. 같은 구독을 여러 기기, 여러 플랫폼에서 사용할 수 있지만 플랫폼마다 클라이언트가 다르며, 다음 절의 표에서 선택 기준을 안내합니다. 셋째는 몇 분간 방해받지 않는 시간입니다. 설치 자체는 빠르며, 대부분의 시간은 첫 인증과 연결 확인에 쓰입니다.

클라이언트 선택 기준

플랫폼별로 사용 가능한 클라이언트와 추천 순서는 다음과 같으며, 다운로드 페이지와 동일합니다. Clash Plus는 데스크톱과 모바일을 모두 지원해 전 플랫폼 1순위이며, 나머지 클라이언트는 플랫폼별로 강점이 다릅니다.

플랫폼1순위2순위설명
WindowsClash PlusClash Verge Rev / FlClash / Clash NyanpasuClash for Windows는 유지 보수가 종료되어 보관용으로만 남아 있습니다
macOSClash PlusClash Verge Rev / FlClashClashX Meta는 유지 보수가 종료되어 보관용으로만 남아 있습니다
AndroidClash PlusClash Meta for Android / FlClash / Surfboard모두 직접 설치하는 APK 패키지입니다
iOSClash PlusApp Store로 배포되며, iOS 다운로드 영역 참고
LinuxClash Verge RevFlClashGUI 없는 서버는 Mihomo 코어를 직접 배포합니다

선택 원칙: 한 기기에는 클라이언트 하나만 설치하면 됩니다. 여러 클라이언트를 동시에 실행하면 포트와 시스템 프록시 설정을 서로 놓고 다투게 되며, 문제 해결 시 가장 먼저 배제해야 할 상황입니다. 유지 보수가 종료된 클라이언트는 신규 설치를 권장하지 않으며, 기존 사용자의 이전 경로는 다운로드 페이지의 해당 카드에 안내되어 있습니다.

기초 용어 빠른 정리

이후 여러 번 등장할 용어를 먼저 통일해 두겠습니다. 코어: 실제로 트래픽을 처리하는 핵심 프로그램으로, 현재 주요 클라이언트에 내장된 것은 Mihomo 코어이며 그래픽 인터페이스는 그 껍데기일 뿐입니다. 노드: 사용 가능한 프록시 경로 하나. 정책 그룹: 여러 노드를 하나로 묶고 선택 로직(예: 자동 속도 측정, 장애 전환)을 정의한 것. 규칙: 특정 요청이 어느 정책 그룹으로 갈지 판단하는 매칭 조건. 이 네 가지의 관계와 더 많은 개념은 용어집을 참고하고, 정책 그룹의 세 가지 유형에 대한 자세한 설명은 정책 그룹 유형 상세 설명을 참고하세요.

주의: 구독 링크는 계정 자격 증명과 동일합니다. 공개 그룹에 올리거나 스크린샷으로 유출하지 마세요. 유출되면 누구나 이를 이용해 노드를 가져오고 트래픽을 소모할 수 있습니다.

CH 02프록시 모드: 시스템 프록시와 TUN의 차이

5개 플랫폼의 설정 과정에서 모두 '시스템 프록시'와 'TUN 모드'라는 두 스위치를 만나게 됩니다. 이 장에서 먼저 원리를 짚고, 이후 각 플랫폼 장에서는 조작 위치만 설명합니다.

시스템 프록시의 동작 방식

시스템 프록시를 켜면 클라이언트가 자신이 리스닝하는 로컬 포트(기본값 7890)를 운영체제의 프록시 설정에 기록합니다. 시스템 프록시 설정을 따르는 브라우저 등의 애플리케이션은 요청을 먼저 이 포트로 보내고, Clash가 규칙에 따라 분배합니다. 장점은 특수 권한이 필요 없고 스위치를 켜면 즉시 적용된다는 점이며, 한계는 '시스템 프록시를 따르려는' 애플리케이션에만 적용된다는 점입니다 — 일부 명령줄 도구, 게임, 백그라운드 서비스는 직접 네트워크에 연결해 이 단계를 건너뜁니다.

TUN 모드의 동작 방식

TUN 모드는 시스템 안에 가상 네트워크 카드를 만들고 기본 라우팅을 그쪽으로 지정합니다. 시스템 프록시를 따르는지 여부와 무관하게 모든 애플리케이션의 트래픽이 이 가상 네트워크 카드를 거쳐 Clash로 들어옵니다. 대가는 더 높은 권한이 필요하다는 점입니다: Windows에서는 시스템 서비스를 설치하고 관리자 권한으로 승인해야 하고, macOS에서는 시스템 확장 프로그램을 허용해야 하며, Android와 iOS에서는 VPN 권한 요청 창으로 나타납니다. TUN과 시스템 프록시는 둘 중 하나만 사용하면 되며, 동시에 켜도 효과가 중첩되지는 않습니다.

비교 항목시스템 프록시TUN 모드
적용 범위시스템 프록시 설정을 따르는 애플리케이션모든 애플리케이션과 시스템 프로세스
권한 요구사항일반 사용자 권한관리자 / 시스템 확장 / VPN 권한
대표 시나리오일상적인 브라우저 접속명령줄 도구, 게임, 프록시 설정을 따르지 않는 앱
종료 후 잔여물비정상 종료 시 프록시 설정이 남을 수 있음서비스 종료와 함께 가상 네트워크 카드도 제거됨

규칙, 글로벌, 직접 연결

위 두 스위치와 별개로 작동하는 것이 아웃바운드 모드입니다: 규칙 모드는 규칙 구간을 순서대로 매칭해 일치하는 대로 처리하며 평소에는 이 모드를 권장합니다. 글로벌 모드는 모든 트래픽이 같은 정책 그룹으로 가며, '규칙이 매칭되지 않는 것인지' 확인할 때만 임시로 사용합니다. 직접 연결 모드는 모든 트래픽이 프록시를 거치지 않습니다. 문제 해결 시 자주 쓰는 방법은 일시적으로 글로벌로 전환하는 것입니다. 글로벌에서는 되는데 규칙 모드에서 안 된다면 문제는 규칙 구간에 있는 것으로 좁혀집니다. 설정 파일 각 구간의 의미는 YAML 구조 단계별 해설을 참고하세요.

CH 03Windows: 설치, 구독, 서비스 모드

다운로드와 설치

다운로드 페이지 Windows 영역에서 설치 파일을 받으세요. 1순위는 Clash Plus이고, 2순위는 Clash Verge Rev, FlClash, Clash Nyanpasu입니다. 설치 파일은 표준 설치 마법사 형태로, 기본값 그대로 진행하면 됩니다. 설치 경로는 기본값을 유지하는 것이 좋으며, 한글이나 공백이 포함된 깊은 하위 폴더에 두지 마세요. 일부 구성 요소는 경로에 민감합니다.

처음 실행할 때 Windows에서 파란색 SmartScreen 알림이 뜰 수 있습니다. 이는 다운로드 출처가 비교적 새로운 실행 파일에 대한 시스템의 일반적인 차단으로, '추가 정보' → '실행'을 누르면 계속 진행됩니다. 일부 보안 소프트웨어는 프록시 프로그램의 가상 네트워크 카드 드라이버를 민감한 동작으로 보고할 수 있는데, 설치 폴더를 신뢰 영역에 추가하면 되며 보안 소프트웨어를 끌 필요는 없습니다.

구독 가져오기

클라이언트를 열고 '구독' 또는 '설정' 페이지로 들어가, URL 입력란에 구독 링크를 붙여넣은 뒤 가져오기를 누릅니다. 클라이언트가 구독을 다운로드하고 파싱하며, 성공하면 프록시 페이지에 노드와 정책 그룹 목록이 나타납니다. 가져오기 오류가 나거나 목록이 비어 있으면 먼저 링크를 다시 완전하게 복사해 재시도하고, 이후 구독 자가 점검 체크리스트를 항목별로 확인하세요. 서둘러 재설치하지 마세요.

시스템 프록시와 TUN

일상적인 사용: 메인 화면에서 '시스템 프록시' 스위치를 켜면 브라우저 트래픽이 Clash를 거치게 됩니다. 명령줄이나 게임 트래픽까지 접수해야 할 때는 TUN을 사용하세요: 주요 클라이언트는 TUN에 필요한 시스템 서비스를 원클릭 설치로 제공하며, 처음 켤 때 관리자 권한(UAC 알림)을 요청합니다. 승인하면 서비스가 상주하고, 이후에는 TUN을 켜고 끌 때 다시 알림이 뜨지 않습니다. TUN을 켜기 전에 시스템 프록시 스위치를 먼저 끄세요.

플랫폼 특유의 문제

포트 점유: 시작 시 7890 또는 9090 포트 점유 오류가 나면, 먼저 점유 중인 프로세스를 확인하고 프로세스를 종료할지 포트를 바꿀지 결정하세요. 관리자 권한으로 터미널을 열고 실행:

netstat -ano | findstr :7890
tasklist | findstr <이전 단계에서 확인한 PID>

첫 번째 명령의 마지막 열은 점유 중인 프로세스의 PID이고, 두 번째 명령으로 프로세스 이름을 확인합니다. 흔한 점유 주체는 종료되지 않은 다른 프록시 클라이언트입니다. 포트를 변경하는 전체 절차는 포트 점유 처리 전체 가이드를 참고하세요.

프록시 설정 잔여: 클라이언트가 강제 종료되거나 비정상 종료되면 시스템 프록시를 제대로 복원하지 못할 수 있으며, 종료 후 모든 웹페이지가 열리지 않는 형태로 나타납니다. 수동 복구: '설정 → 네트워크 및 인터넷 → 프록시'에서 '프록시 서버 사용'을 끄세요. 부팅 시 자동 시작: 클라이언트 설정에서 자동 시작과 '조용히 시작'을 켜면 부팅마다 메인 창이 뜨는 것을 피할 수 있습니다.

CH 04macOS: 칩 아키텍처, 게이트키퍼, 시스템 확장 프로그램

칩 아키텍처를 먼저 확인하고 다운로드

macOS 설치 파일은 Apple Silicon(M 시리즈 칩)과 Intel 두 종류로 나뉘며, 아키텍처를 잘못 선택하면 눈에 띄게 느려지거나 실행되지 않을 수 있습니다. 기기 모델이 불확실하면 터미널에서 실행:

uname -m

출력이 arm64면 Apple Silicon 패키지를, x86_64면 Intel 패키지를 선택하세요. 그런 다음 다운로드 페이지 macOS 영역에서 해당 dmg를 받으세요. 1순위는 Clash Plus이고, 2순위는 Clash Verge Rev와 FlClash입니다.

설치와 첫 실행

dmg를 열고 앱 아이콘을 Applications 폴더로 끌어다 놓은 뒤, 런치패드나 응용 프로그램 폴더에서 실행하세요. 처음 열 때 시스템 게이트키퍼(Gatekeeper)가 개발자를 확인할 수 없다고 안내할 수 있습니다: '시스템 설정 → 개인 정보 보호 및 보안' 페이지 하단에서 차단된 앱 옆의 '그래도 열기'를 찾아 확인하세요. '앱이 손상되어 열 수 없습니다'라는 메시지가 뜨면 다운로드한 파일에 격리 속성이 붙은 것으로, 터미널에서 다음 명령을 실행한 뒤 다시 열면 됩니다(경로는 실제 앱 이름으로 바꿔주세요):

xattr -cr /Applications/사용 중인 클라이언트 이름.app

구독 가져오기와 시스템 프록시

구독 가져오기 절차는 Windows와 동일합니다: 구독 페이지에서 링크를 붙여넣고 가져오기를 눌러 노드 목록이 나타나는지 확인하세요. '시스템 프록시'를 켜면 macOS가 네트워크 설정 변경을 허용할지 묻는 권한 대화상자를 띄우며, 로그인 비밀번호를 한 번 입력해 확인하면 됩니다. 켠 뒤에는 '시스템 설정 → 네트워크 → 현재 네트워크 → 세부 정보 → 프록시'에서 HTTP/HTTPS 프록시가 127.0.0.1의 해당 포트를 가리키고 있는지 확인할 수 있으며, 이것이 스위치가 실제로 작동하는지 검증하는 확실한 방법입니다.

TUN과 시스템 확장 프로그램

macOS에서 TUN을 켜려면 시스템 확장 프로그램 또는 네트워크 확장 프로그램을 허용해야 합니다: 처음 켤 때 안내에 따라 '시스템 설정 → 개인 정보 보호 및 보안'에서 해당 확장 프로그램의 로드를 허용하세요. 일부 기기에서는 클라이언트를 한 번 재시작해야 합니다. 여러 '네트워크 위치'를 사용하거나 유선과 무선을 동시에 연결한 경우 프록시 설정이 네트워크 서비스별로 따로 저장되므로, 네트워크를 전환한 뒤 프록시가 작동하지 않으면 현재 사용 중인 네트워크 서비스가 설정할 때의 그 서비스인지부터 확인하세요.

플랫폼 특유의 문제

시스템 업데이트 후 확장 프로그램 권한이 가끔 초기화됩니다. TUN이 갑자기 작동하지 않으면 먼저 '개인 정보 보호 및 보안'으로 돌아가 확장 프로그램이 여전히 허용 목록에 있는지 확인하세요. 클라이언트를 제거할 때는 앱에 내장된 제거 기능을 사용하거나, 앱 안에서 먼저 시스템 프록시와 TUN을 끈 뒤 삭제하는 것을 권장합니다. 바로 휴지통으로 끌어다 놓으면 프록시 설정이 남을 수 있으며, 복구 방법은 앞 절과 같이 네트워크 세부 정보에서 수동으로 프록시를 끄면 됩니다.

CH 05Linux: 데스크톱 클라이언트와 서버 배포

데스크톱 배포판: Clash Verge Rev 또는 FlClash 설치

Debian/Ubuntu 계열은 다운로드 페이지 Linux 영역에서 deb 패키지를 받은 뒤 설치합니다:

sudo dpkg -i 다운로드한설치파일.deb
sudo apt-get -f install

두 번째 명령은 의존성을 자동으로 보완합니다. RPM 계열 배포판은 해당 rpm 패키지를 배포판 기본 패키지 관리자로 설치하면 됩니다. 설치 후 앱 메뉴에서 실행하며, 구독 가져오기 절차는 데스크톱 플랫폼과 동일합니다.

데스크톱 환경의 시스템 프록시

Linux에는 통일된 '시스템 프록시' 입구가 없습니다. 클라이언트의 시스템 프록시 스위치는 GNOME과 KDE의 데스크톱 프록시 설정에는 적용되지만, 해당 설정을 따르는 그래픽 애플리케이션에만 영향을 미칩니다. 터미널 세션은 환경 변수를 따로 설정해야 합니다:

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890

이 변수들은 현재 터미널 세션에만 적용되며 터미널을 닫으면 사라집니다. 장기적으로 적용하려면 셸 설정 파일에 작성해야 하지만, 더 간단한 방법은 TUN 모드로 기기 전체를 접수하는 것입니다. Linux에서 TUN을 켜는 것도 마찬가지로 권한 상승이 필요하며, 클라이언트가 서비스 설치나 root 권한 요청을 안내합니다.

GUI 없는 서버: Mihomo 코어 직접 배포

서버와 소프트 라우터 환경에서는 그래픽 클라이언트가 필요 없으며, Mihomo 코어를 직접 실행합니다. 코어 패키지는 다운로드 페이지의 코어 영역에서 제공합니다. 기본 절차: 바이너리를 /usr/local/bin/mihomo에 압축 해제하고, 설정 파일을 /etc/mihomo/config.yaml에 두고, systemd 서비스를 작성합니다:

[Unit]
Description=mihomo daemon
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure

[Install]
WantedBy=multi-user.target

/etc/systemd/system/mihomo.service로 저장한 뒤 실행:

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo

상태가 active (running)으로 표시되면 시작에 성공한 것입니다. 설정 파일 작성법은 데스크톱 클라이언트가 쓰는 것과 완전히 같은 근원이며, 각 구간의 의미는 설정 단계별 해설을 참고하세요.

플랫폼 특유의 문제

53번 포트 충돌: 설정에서 DNS 모듈이 53번 포트를 리스닝하도록 켜져 있으면 systemd-resolved와 충돌해 시작 로그에 address already in use가 뜹니다. 처리 방법은 둘 중 하나: 설정의 DNS 리스닝을 0.0.0.0:1053 등 53번이 아닌 포트로 바꾸거나, systemd-resolved의 스텁 리스너를 비활성화하세요. 포트 점유 확인:

ss -lntp | grep 7890

권한 문제: TUN 모드는 프로세스가 NET_ADMIN 권한을 가지고 있어야 합니다. systemd 방식은 root로 실행되므로 자연히 이 조건을 만족하며, 수동으로 포그라운드에서 실행할 때는 sudo를 붙여야 한다는 점을 기억하세요.

CH 06Android: APK 설치와 VPN 권한

APK 설치

다운로드 페이지 Android 영역에서 APK를 받으세요. 1순위는 Clash Plus이고, 2순위는 Clash Meta for Android, FlClash, Surfboard입니다. 브라우저로 다운로드한 APK를 처음 설치할 때 시스템이 '알 수 없는 앱 설치' 권한을 요구합니다: 알림 안내에 따라 현재 브라우저나 파일 관리자에 이 권한을 켜준 뒤 돌아와 설치를 이어가면 됩니다. 이는 스토어가 아닌 경로로 설치되는 앱에 대한 Android의 표준 절차입니다.

구독 가져오기와 첫 연결

앱을 열고 구독/설정 페이지에서 구독 링크를 붙여넣고 가져오기를 하세요. 휴대폰에서는 링크를 복사한 뒤 바로 앱으로 들어가는 경로가 더 흔히 쓰이며, 대부분의 클라이언트는 클립보드를 인식해 원클릭 가져오기를 제안합니다. 처음 연결 버튼을 누르면 시스템이 'XX에서 VPN 연결을 설정하려고 합니다'라는 권한 대화상자를 띄웁니다 — Android에서 Clash는 시스템 VPN 인터페이스를 통해 트래픽을 접수하며, 이는 데스크톱의 TUN 모드와 동등합니다. '확인'을 누르면 상태 표시줄에 열쇠 아이콘이 나타나며 접수가 작동 중임을 나타냅니다. 이 알림이 뜨지 않았거나 실수로 거부를 눌렀다면 '설정 → 네트워크 → VPN'에서 기록을 삭제한 뒤 다시 연결하면 다시 뜹니다.

플랫폼 특유의 문제

백그라운드 종료: 국내 제조사의 커스텀 시스템은 백그라운드 상주 앱을 적극적으로 정리하는 경향이 있어, 화면 잠금 후 일정 시간이 지나면 프록시가 끊기는 현상으로 나타납니다. 처리 방법: 클라이언트를 배터리 최적화 예외 목록에 추가하고, 백그라운드 실행과 자동 시작을 허용하세요. 제조사마다 메뉴 이름이 다르며 보통 '배터리' 또는 '앱 관리'에 있습니다. 개인 DNS 충돌: 시스템 '개인 DNS'를 특정 호스트 이름으로 지정하면 클라이언트의 DNS 접수와 서로 간섭할 수 있으며, 해석 오류를 조사할 때는 개인 DNS를 '자동'으로 되돌린 뒤 다시 테스트하세요. 앱별 프록시: 클라이언트 설정에서 어떤 앱이 프록시를 거치고 어떤 앱이 직접 연결할지 지정할 수 있습니다. 은행 앱처럼 프록시에 민감한 앱은 전체 프록시를 끄는 것보다 직접 연결 목록에 추가하는 편이 더 간편합니다.

CH 07iOS: App Store 다운로드와 VPN 설정

클라이언트 받기

iOS용 Clash Plus는 App Store로 배포되며, 스토어 입구와 안내는 다운로드 페이지 iOS 영역을 참고하세요. App Store에서 설치를 완료하면 앱 업데이트는 스토어가 자동으로 관리하므로 설치 파일을 수동으로 유지 관리할 필요가 없습니다. 이는 iOS가 다른 플랫폼과 절차상 가장 크게 다른 부분입니다.

첫 설정과 권한

앱을 열고 구독 페이지에서 링크를 붙여넣어 가져옵니다. 절차는 Android와 동일합니다. 처음 연결을 시작할 때 시스템이 'VPN 설정 추가'를 요청하며 Face ID/암호 인증을 요구합니다 — iOS에서는 모든 프록시 클라이언트가 시스템 VPN 프레임워크를 통해 동작하므로, 이 권한 승인 단계는 반드시 거쳐야 합니다. 완료하면 '설정 → VPN'에 해당 항목이 나타나고, 상태 표시줄에 VPN 표시가 뜨면 접수가 작동 중임을 뜻합니다. 이후 연결과 해제는 앱 안에서 조작할 수도 있고, 시스템 설정의 VPN 스위치로 바로 조작할 수도 있습니다.

플랫폼 특유의 문제

네트워크 전환 후 끊김: Wi-Fi와 셀룰러 데이터 사이를 전환하면 VPN 터널이 다시 만들어지며, 가끔 앱으로 돌아가 수동으로 재연결해야 합니다. 클라이언트에 '온디맨드 연결' 옵션이 있다면 켜두는 것을 권장하며, 필요할 때 시스템이 자동으로 터널을 다시 띄웁니다. 구독 업데이트: iOS의 백그라운드 새로 고침은 시스템 스케줄링 제한을 받으므로, 앱을 오래 열지 않으면 구독이 만료될 수 있습니다. 노드가 전부 타임아웃되면 먼저 앱에 들어가 구독을 수동으로 한 번 업데이트한 뒤 다시 테스트하세요. 규칙과 설정: iOS 클라이언트가 사용하는 구독과 설정 문법은 데스크톱과 같은 근원이며, 정책 그룹과 규칙 조정 방법도 공통이므로 iOS용으로 별도의 설정을 따로 관리할 필요가 없습니다.

CH 08설정 자주 묻는 문제: 설치 후 문제 해결 매뉴얼

YAML 들여쓰기와 필드 오타

설정 파일을 직접 편집할 때 가장 흔한 오류는 들여쓰기입니다: YAML은 공백 두 칸으로 계층을 표현하며 Tab 문자를 금지합니다. 같은 레벨의 필드는 정렬이 맞아야 하고, 목록 항목의 - 뒤에는 공백이 하나 있어야 합니다. 클라이언트가 '설정 로드 실패'를 표시하며 줄 번호를 알려줄 때는 먼저 해당 줄과 주변 문맥의 들여쓰기가 일치하는지 확인하고, 그다음 필드 이름 철자를 확인하세요 — proxy-groupsproxy-group으로 쓰는 것처럼 글자 하나 차이의 오류는 오류 메시지만으로는 직관적으로 알기 어려운 경우가 많습니다. 최소한으로 동작하는 공통 구간 예시:

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

mixed-port는 HTTP와 SOCKS를 동시에 받는 혼합 포트이고, external-controller는 로컬 관리 인터페이스입니다. 이 두 포트가 앞서 각 플랫폼에서 다룬 '포트 점유' 문제의 당사자이며, 둘 중 하나를 바꾸면 클라이언트를 재시작해야 적용됩니다. 전체 구간별 설명은 YAML 구조 단계별 해설을 참고하세요.

포트 충돌의 공통 판단법

세 플랫폼의 점유 확인 명령은 각 장에서 이미 안내했습니다(Windows는 netstat, macOS/Linux는 ss 또는 lsof). 공통 판단 순서: 먼저 종료되지 않은 다른 프록시 클라이언트인지 확인합니다. 그렇다면 기존 클라이언트를 종료하고, 아니라면 로컬 포트를 바꿉니다 — 설정 파일이나 클라이언트 설정에서 7890을 다른 사용 가능한 포트로 바꾸고, 이 포트를 참조하는 곳(브라우저 확장 프로그램, 터미널 환경 변수)도 함께 업데이트하세요. 전체 절차는 포트 점유 처리 전문 가이드를 참고하세요.

구독 관련 문제

가져오기 오류, 노드 목록 비어 있음, 업데이트 실패라는 세 가지 현상은 같은 흐름으로 점검합니다: 링크 완전성 → 응답 콘텐츠 형식 → 구독 만료 여부 → 클라이언트 호환성. 항목별 자가 점검 방법은 구독 자가 점검 체크리스트를 참고하세요. 여기서 한 가지 팁을 덧붙이면: 브라우저에서 구독 링크를 직접 열었을 때 오류 페이지가 아닌 텍스트가 반환된다면 링크 자체는 정상이며 문제는 클라이언트 쪽에 있는 것이고, 오류 페이지나 빈 화면이 뜨면 구독 제공처에 바로 문의하세요.

프록시는 작동 중인데 브라우저에서 인증서 오류가 뜨는 경우

프록시를 켠 뒤 웹페이지에서 '연결이 비공개로 설정되어 있지 않습니다' 같은 알림이 뜨는 경우, 대부분 클라이언트 설정과는 무관합니다: 먼저 시스템 시간을 정확히 맞추세요(시간이 몇 분만 어긋나도 인증서 검증이 실패할 수 있습니다). 그다음 다른 노드로 바꿔 재시도하고, 여전히 재현된다면 다른 원인을 고려하세요. 오류 유형별 분류 점검은 인증서 오류 점검 전문 가이드를 참고하세요.

정책 그룹이 선택되지 않거나 노드 전환이 적용되지 않는 경우

규칙 모드에서 노드를 수동으로 전환할 때는 노드 목록이 아니라 해당 정책 그룹 안에서 전환해야 합니다 — 요청이 실제로 향하는 곳은 정책 그룹이며, 그룹 안에서 현재 선택된 노드가 실제 출구입니다. url-test 유형의 그룹은 속도 측정 결과에 따라 자동으로 선택되므로 수동 지정이 반영되지 않는 것은 설계상 정상입니다. 수동으로 제어하고 싶다면 자주 쓰는 그룹을 select 유형으로 설정하세요. 세 가지 정책 그룹의 作동 원리와 설정 조각은 정책 그룹 상세 설명을 참고하세요.

아직 해결되지 않았나요?

현상별로 더 많은 질문과 답변이 자주 묻는 질문 페이지에 정리되어 있고, 개념적인 의문은 용어집에서 찾아보세요. 문제를 알려주실 때는 세 가지 정보를 함께 주세요: 플랫폼과 클라이언트 이름, 재현 절차, 클라이언트 로그의 오류 줄. 이렇게 하면 주고받는 소통을 최대한 줄일 수 있습니다.