Clash Nyanpasu 설치 및 초기 설정 가이드: Windows·macOS·Linux 공통 설정과 문제 해결

설치 전 확인: 클라이언트·코어·프로필 구분하기

Clash Nyanpasu는 데스크톱 GUI 클라이언트입니다. 창이 열린다고 해서 확인되는 것은 화면 프로세스가 실행됐다는 점뿐입니다. 네트워크 요청을 처리하려면 프록시 코어가 실행 중이어야 하고, 유효한 설정과 코어에 연결된 트래픽 진입점도 필요합니다. 처음 설정할 때는 ‘설치 → 프로필 가져오기 → 코어 실행 → 수동 프록시 테스트 → 시스템 프록시’ 순서로 진행하고, TUN은 일단 꺼 두세요.

클라이언트: 프로필 관리, 설정 화면, 로그 표시와 시스템 연동을 담당합니다.
코어: 설정을 읽고 연결을 처리합니다. mihomo는 Clash Meta 코어라고도 불리며, 선택 가능한 항목은 클라이언트 배포 버전에 따라 다릅니다.
Profile: 로컬 설정 파일 또는 원격 구독 기록입니다. 설정에는 보통 노드, 정책 그룹, DNS, 라우팅 규칙이 포함됩니다.
프록시 진입점: 로컬 HTTP/SOCKS 리스닝 포트나 TUN 가상 네트워크 인터페이스 등을 말합니다. 진입점에 따라 처리되는 트래픽 범위가 달라집니다.

Windows·macOS·Linux 설치 방법

Windows: 시스템 종류와 설치 권한 확인

‘설정’ → ‘시스템’ → ‘정보’를 열어 ‘시스템 종류’를 확인하세요. x64와 ARM64에 맞는 빌드를 선택해야 합니다. Windows 11이라는 이름만으로 아키텍처를 판단하지 마세요.
다운로드 페이지에서 현재 릴리스에 제공되는 설치 파일을 선택하세요. 일반적인 방법으로 설치하고 실행한 뒤, 종속 항목 누락이나 Windows 보안 알림이 표시되면 내용을 빠짐없이 기록해 두세요.
처음 실행할 때는 일반 사용자 권한으로 프로필을 가져오고 로컬 포트를 테스트하세요. 서비스 모드나 TUN이 필요할 때 클라이언트 안내에 따라 서비스를 설치하거나 권한을 부여하면 됩니다.
WebView2 관련 오류가 발생하면 해당 버전의 설치 안내에 따라 런타임을 확인하세요. 오프라인 기기에는 아키텍처에 맞는 런타임 설치 파일을 준비해야 합니다. 화면 표시 관련 종속성 오류를 구독 오류로 오해하지 마세요.

Windows 시스템 프록시는 ‘설정’ → ‘네트워크 및 인터넷’ → ‘프록시’에서 확인할 수 있습니다. 테스트할 때 시스템 프록시를 변경하는 클라이언트를 두 개 이상 실행하지 마세요. 마지막으로 설정을 기록한 프로그램이 앞서 설정한 주소와 포트를 덮어쓸 수 있습니다.

macOS: 칩을 확인한 다음 보안 알림 처리하기

Apple 메뉴 → ‘이 Mac에 관하여’에서 ‘칩’ 또는 ‘프로세서’를 확인하세요. Apple Silicon 기기는 해당 ARM64 빌드를, Intel 기기는 해당 x64 빌드를 선택하세요. 범용 빌드 여부는 다운로드 페이지의 안내를 따르세요.
디스크 이미지 파일을 다운로드했다면 파일을 연 뒤 앱을 ‘응용 프로그램’ 폴더로 복사하고 그곳에서 실행하세요. 마운트된 이미지 안에서 계속 실행하지 않는 것이 좋습니다.
시스템에서 앱 실행을 차단하면 먼저 출처와 시스템 호환성을 확인한 다음, ‘시스템 설정’ → ‘개인정보 보호 및 보안’에 실제로 표시되는 옵션을 이용하세요. 앱 하나를 실행하려고 시스템 전체의 보안 기능을 끄지 마세요.
필요한 기능을 켤 때만 권한 요청을 처리하세요. 일반적인 로컬 프록시 리스닝과 시스템 프록시 사용에 모든 네트워크 확장이나 키체인 요청을 승인해야 하는 것은 아닙니다.

최신 macOS에서는 ‘시스템 설정’ → ‘네트워크’ → 현재 네트워크 서비스 → ‘세부사항’ → ‘프록시’에서 프록시 상태를 확인할 수 있습니다. macOS 버전에 따라 메뉴 이름이 조금 다를 수 있습니다. 권한 요청 창이 반복해서 나타나면 요청 앱 이름과 내용을 기록한 뒤, 서비스 설치·시스템 네트워크 설정·자격 증명 접근 중 무엇을 위한 요청인지 확인하세요.

Linux: 패키지 형식·아키텍처·데스크톱 환경 구분하기

먼저 uname -m을 실행해 아키텍처를 확인하세요. 흔히 나오는 x86_64는 x64, aarch64는 ARM64에 해당합니다. 배포판과 현재 릴리스에서 제공하는 파일에 맞춰 설치 방법을 선택하세요. 패키지 관리자로 설치하는 방법과 AppImage를 실행하는 방법은 서로 다른 절차이므로 명령을 섞어 사용하면 안 됩니다.

배포판 패키지: 시스템 패키지 관리자로 설치하고 의존성 해결 결과를 확인하세요. 그래픽 라이브러리가 없다는 오류가 나면 오류 메시지를 바탕으로 필요한 의존성을 설치하세요.
AppImage: 먼저 파일에 실행 권한을 부여하세요. 로그에 FUSE 오류가 표시되면 배포판과 해당 빌드의 안내에 따라 처리하세요. 그래픽 앱을 계속 root 권한으로 실행해 문제를 우회하지 마세요.
데스크톱 시스템 프록시: GNOME, KDE, 터미널 프로그램은 시스템 프록시를 읽는 방식이 서로 다릅니다. 클라이언트에 시스템 프록시가 켜졌다고 표시되어도 대상 앱이 해당 설정을 사용하는지 확인해야 합니다.

Linux 데스크톱에서 실행한 뒤 창이 나타나지 않으면 터미널에서 실제 설치된 실행 파일을 실행하고 출력 내용을 보존하세요. 공유 라이브러리 누락, 디스플레이 세션 사용 불가, 코어 설정 오류는 서로 다른 단계의 문제입니다. 가장 먼저 나타난 명확한 오류부터 해결하세요.

프로필 가져오기: 먼저 작동하는 Profile 준비하기

클라이언트의 프로필 관리 화면에서 로컬 YAML 파일이나 원격 구독을 추가하고, 가져오기가 끝나면 해당 프로필을 현재 사용 항목으로 지정하세요. 버전에 따라 버튼 이름이 ‘설정’, ‘Profiles’ 등으로 다를 수 있습니다. 중요한 것은 설정 기록을 만들고 활성화하는 것이며, 입력란에 링크만 저장하는 것이 아닙니다.

구독 제공자가 Clash YAML 또는 현재 코어에서 인식할 수 있는 설정 형식을 지원하는지 확인하세요. 브라우저에서 링크가 열린다고 해서 응답 내용이 바로 가져오기에 적합한 것은 아닙니다.
다운로드 결과가 실제 설정 텍스트인지 확인하세요. 로그인 페이지, 만료 안내, HTML 오류 페이지, 노드 목록만 있는 콘텐츠는 파싱에 실패하거나 정책 그룹이 누락되는 원인이 될 수 있습니다.
프로필을 활성화한 뒤 로그를 확인해 YAML 파싱 오류, 알 수 없는 필드로 인한 실행 실패, 존재하지 않는 규칙 대상이 없는지 살펴보세요.
프록시 또는 정책 그룹 화면에서 선택 가능한 노드가 실제로 있는지 확인하세요. 그룹에 DIRECT만 있다면 시스템 프록시를 반복해서 전환하지 말고 설정 내용을 더 살펴봐야 합니다.

구독 URL에 접근 토큰이 포함될 수 있습니다. 화면을 캡처하거나 질문을 올리고 로그를 복사하기 전에 URL 쿼리 매개변수, 노드 비밀번호, 컨트롤 인터페이스 키를 가리세요. 원격 구독을 업데이트하면 원본 내용도 바뀝니다. 로컬 수정 사항의 보존 여부는 클라이언트의 설정 처리 방식에 따라 다르므로, 장기적으로 사용자 설정을 유지하려면 해당 버전에서 지원하는 오버라이드 방식을 사용하세요.

코어와 포트: 실제 적용된 값부터 확인하기

처음 설치할 때는 클라이언트 배포 버전에 포함된 코어를 우선 사용하세요. mihomo 전용 필드가 필요하다면 현재 실행 중인 코어와 버전이 해당 필드를 지원하는지 확인하세요. 코어를 바꾼 뒤에는 설정을 다시 불러오고 새 프로세스의 시작 로그를 확인해야 합니다. 화면에서 코어 이름을 선택한 것만으로 새 코어가 정상 실행됐다고 볼 수는 없습니다.

필드 또는 설정	용도	처음 확인할 항목
`mixed-port`	하나의 포트에서 HTTP와 SOCKS 프록시 진입점을 제공합니다.	실제 리스닝 포트를 기록하고 테스트 주소를 클라이언트 설정과 일치시키세요.
`allow-lan`	LAN 기기가 프록시에 접속할 수 있는지 제어합니다.	로컬 기기에서만 사용할 때는 끄고 바인딩 주소를 확인하세요.
`mode`	규칙·전역·직결 등의 작동 모드를 선택합니다.	일상적인 사용은 규칙 모드부터 시작하고 규칙 대상이 유효한지 확인하세요.
`external-controller`	클라이언트와 코어 사이의 컨트롤 인터페이스를 제공합니다.	컨트롤 인터페이스 포트를 브라우저 프록시 포트로 입력하지 마세요.

아래는 필드 간 관계를 설명하기 위한 YAML 예시이며, 노드와 규칙을 모두 포함한 완전한 구독 설정이 아닙니다. 현재 설정 전체를 이 내용으로 덮어쓰지 마세요. 클라이언트 오버라이드에 따라 최종 값이 달라질 수 있으므로 실제 적용 설정과 로그를 기준으로 확인해야 합니다.

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

컨트롤 인터페이스와 트래픽 진입점은 구분해야 합니다. 예를 들어 설정에서 컨트롤 인터페이스를 127.0.0.1:9090으로 지정했다면 이 주소는 코어 관리용이지 웹 요청을 전달하는 프록시 주소가 아닙니다. 필요한 접근 제어 없이 컨트롤 인터페이스가 모든 네트워크 인터페이스에서 수신하도록 설정하지 마세요.

연결 확인: 수동 프록시·시스템 프록시·TUN

1단계: 명시적 프록시로 포트 테스트하기

먼저 사용할 수 있는 정책 그룹과 노드를 선택한 다음, 단일 요청이 로컬 프록시를 거치도록 지정하세요. 아래 명령은 표준 HTTPS 예시 도메인에 접속합니다. 응답을 받았다는 것은 해당 요청이 처리됐다는 뜻일 뿐, 모든 웹사이트·프로토콜·앱의 트래픽이 프록시를 거친다는 의미는 아닙니다. Windows에서는 일부 PowerShell 환경에서 같은 이름의 별칭이 인자 해석에 영향을 주지 않도록 curl.exe를 사용하세요.

# Windows PowerShell
curl.exe -I --proxy http://127.0.0.1:7890 --connect-timeout 10 https://example.com

# macOS / Linux
curl -I --proxy http://127.0.0.1:7890 --connect-timeout 10 https://example.com

127.0.0.1에 연결할 수 없다는 오류가 나오면 먼저 포트와 프로세스를 확인하세요. 프록시 연결은 됐지만 이후 시간 초과가 발생한다면 로그를 확인해 노드 연결, TLS, DNS, 규칙 결과를 점검하세요. HTTP 오류 상태를 받았다고 해서 로컬 프록시가 실행되지 않는 것은 아닙니다. ‘연결 여부’와 ‘대상 사이트가 반환한 내용’을 구분해야 합니다.

2단계: 시스템 프록시를 켜고 연결 확인하기

명시적 프록시 테스트가 통과한 뒤 클라이언트에서 시스템 프록시를 켜세요. 테스트할 앱을 다시 시작하거나 새 연결을 만든 다음, 클라이언트의 연결 목록에서 대상 도메인과 적용된 규칙, 최종 정책을 확인하세요. 시스템 프록시는 시스템 설정을 따르는 앱에만 영향을 줍니다. 기존 연결, 일부 터미널 도구, 자체 네트워크 설정을 관리하는 프로그램은 프록시 전환에 반응하지 않을 수 있습니다.

터미널 환경의 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY 환경 변수도 요청 경로를 바꿀 수 있습니다. 특정 프로그램을 점검할 때는 먼저 자체 프록시 설정과 환경 변수를 확인하세요. 시스템 프록시가 작동하지 않는다고 단정하지 마세요.

3단계: 필요한 경우에만 TUN 활성화하기

TUN은 가상 네트워크 인터페이스와 라우팅을 통해 트래픽을 처리하며, 시스템 프록시가 적용되지 않는 일부 상황에 유용합니다. 일반적으로 추가 권한이나 서비스 지원이 필요하고 DNS, 라우팅, 인터페이스 선택도 함께 고려해야 합니다. 일반 브라우저 테스트가 통과하지 않았다면 TUN을 동시에 켜지 마세요. 노드 문제와 라우팅 문제를 구분하기 어려워집니다.

중복 라우팅과 DNS 처리를 막으려면 다른 VPN이나 유사한 TUN 클라이언트를 먼저 종료하세요.
현재 버전의 안내에 따라 서비스를 설치하거나 권한을 부여한 뒤, 로그에서 가상 인터페이스가 생성됐는지 확인하세요.
일반 웹페이지, LAN 주소, 프록시 적용이 필요한 앱을 각각 테스트하세요. TUN 스위치가 켜져 있는지만 확인해서는 안 됩니다.
전체 네트워크 연결이 끊기면 먼저 TUN을 끄고 네트워크가 복구되는지 확인하세요. 그런 다음 라우팅과 DNS 설정을 점검하고, 설정을 계속 겹쳐서 변경하지 마세요.

실행 오류와 포트 충돌 해결 순서

창이 열리지 않음: 먼저 UI 단계 확인하기

설치 파일의 아키텍처, 지원되는 시스템 범위, 설치 경로부터 확인하세요. Windows에서는 종속 항목 안내, macOS에서는 시스템 보안 알림, Linux에서는 터미널 출력을 살펴보세요. 이 단계에서는 아직 코어가 포트를 수신하지 않으므로 구독 규칙을 바꿔도 UI 실행 실패를 해결할 수 없습니다. 업그레이드 전후 동작이 달라졌다면 기존 설정 백업, 클라이언트 버전, 오류 발생 시각을 보관하세요.

창은 열리지만 코어 실행 실패: 첫 번째 오류 확인하기

로그에 address already in use 또는 bind 관련 오류가 있으면 충돌한 포트가 프록시 포트인지, DNS 수신 포트인지, 컨트롤 인터페이스 포트인지 확인하세요. 아래 명령은 예시 프록시 포트 7890만 조회하므로 오류에 표시된 실제 숫자로 바꿔 사용하세요.

# Windows PowerShell: 리스닝 프로세스 PID 확인
Get-NetTCPConnection -LocalPort 7890 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

# macOS: TCP 리스닝 프로세스 확인
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux: 리스닝 정보 확인; 프로세스 상세 정보는 추가 권한이 필요할 수 있음
ss -ltnp 'sport = :7890'

PID로 해당 프로세스를 확인하고, 중복 실행된 이전 클라이언트는 정상적으로 종료하세요. 출처를 알 수 없는 시스템 프로세스를 종료하지 마세요.
두 프로그램을 함께 실행해야 한다면 둘 중 하나의 프록시 리스닝 포트를 사용 중이지 않은 다른 값으로 바꾸세요. 예: 7891.
포트를 바꾼 뒤에는 시스템 프록시, 브라우저, 터미널의 명시적 프록시 주소도 함께 업데이트하고 설정을 다시 불러오세요.
리스닝 상태를 다시 조회한 뒤 연결 테스트를 반복하세요. 화면에 표시된 값만 바꾸고 실제 적용된 설정을 놓치지 마세요.

로그에 YAML 줄 번호, 들여쓰기, 정책 그룹 이름 오류가 표시되면 먼저 설정을 수정하세요. YAML은 공백으로 계층을 구분하고 같은 수준의 필드는 들여쓰기를 맞춰야 합니다. 규칙에서 참조하는 정책 이름은 기존 그룹 이름과 일치해야 합니다. 필드의 의미는 YAML 설정 참고에서 확인하세요.

실행은 되지만 접속할 수 없음: 연결 경로를 단계별로 확인하기

‘앱이 프록시를 사용하는지 → 로컬 포트가 수신 중인지 → 규칙이 어떤 정책에 적용되는지 → 노드에 연결할 수 있는지 → DNS가 정상인지’ 순서로 확인하세요. 지연 시간 테스트 한 번의 결과만으로 전체 연결 경로를 판단할 수는 없습니다. 규칙 모드에서는 요청이 DIRECT에 적용되어 현재 수동으로 선택한 노드를 거치지 않을 수도 있습니다.

초기 설정 후 기록해 둘 항목

버전과 설정 기록: 클라이언트 버전, 코어 버전, 현재 Profile 이름, 프록시 포트, TUN 활성화 여부를 기록하세요.
종료 후 동작 확인: 클라이언트를 정상 종료한 뒤 시스템 프록시가 원래 상태로 복구되는지 확인하세요. 비정상 종료 후 프록시 주소가 남아 있다면 시스템 네트워크 설정에서 직접 끈 다음 네트워크를 확인하세요.
마지막으로 시작 프로그램 설정: 종료와 재실행, 연결 테스트를 한 차례 마친 뒤 컴퓨터 시작 시 자동 실행을 켜세요. 로그인 후 같은 오류가 반복되는 상황을 피할 수 있습니다.
백업 내용 보호: 설정을 내보내면 구독 토큰과 노드 인증 정보가 포함될 수 있습니다. 신뢰할 수 있는 저장소에만 보관하고 전체 프로필을 공개 토론 공간에 올리지 마세요.

초기 설치가 끝났다는 기준은 모든 스위치가 켜져 있는지가 아닙니다. 현재 설정을 불러올 수 있고, 진입점이 포트를 수신하며, 대상 앱의 요청 경로를 확인할 수 있어야 합니다. 검증된 기본 설정을 하나 보관하고 사용자 규칙, 오버라이드, TUN 설정은 나중에 하나씩 추가하세요. 문제가 생겼을 때 되돌리고 원인을 찾기도 쉬워집니다.