Clash Linux 설치 방법: 데스크톱 클라이언트와 순수 명령줄 코어 배포 가이드

먼저 경로 선택: 데스크톱 클라이언트와 Mihomo 명령줄 코어

Linux에는 모든 환경에 맞는 단일 설치 방식이 없습니다. Ubuntu, Fedora, Linux Mint 또는 Arch 데스크톱을 일상적으로 사용하는 경우에는 구독 관리, 정책 그룹 전환, 로그 확인과 시스템 프록시 제어가 중요합니다. 반면 서버, 소프트 라우터의 우회 환경, 모니터가 없는 호스트에서는 리소스 사용량, 원격 관리와 부팅 시 자동 실행을 더 중시합니다. 이 두 가지 요구에 맞춰 데스크톱 클라이언트와 순수 코어라는 두 경로를 선택할 수 있습니다.

비교 항목	데스크톱 클라이언트	Mihomo 명령줄 코어
적합한 장치	Ubuntu, Fedora, Mint, Arch 데스크톱	서버, 개발 머신, NAS, 데스크톱 환경이 없는 호스트
구독 가져오기	그래픽 인터페이스에 URL을 붙여 넣고 업데이트	config.yaml을 직접 준비하거나 주기적으로 업데이트
정책 전환	정책 그룹과 노드를 직접 클릭	외부 컨트롤러 API 또는 Web 패널로 조작
백그라운드 실행	데스크톱 로그인 후 자동 시작	systemd가 시스템 부팅 시 시작
일반적인 메모리 사용량	인터페이스와 코어 합산 약 140~320MB	일반적인 규칙 설정 기준 약 35~110MB
TUN 권한	대개 서비스 모드나 권한 부여 구성 요소가 처리	CAP_NET_ADMIN 등의 권한 필요

설치 전에 CPU 아키텍처 확인

아키텍처가 잘못된 패키지를 다운로드하면 곧바로 “바이너리 파일을 실행할 수 없음” 또는 Exec format error가 발생합니다. 먼저 터미널에서 다음 명령을 실행하세요:

uname -m
cat /etc/os-release

x86_64는 amd64 또는 x64에 해당하며 Intel·AMD 데스크톱과 서버에서 흔히 사용됩니다.
aarch64는 arm64에 해당하며 Raspberry Pi 4/5, 일부 NAS와 ARM 클라우드 호스트에서 흔히 사용됩니다.
armv7l은 32비트 ARM에 해당하므로 armv7을 명시적으로 제공하는 빌드를 선택해야 합니다.

배포판 정보에 따라 패키지 형식이 달라집니다. Ubuntu, Debian, Linux Mint는 .deb를 우선 선택하고, Fedora와 RHEL 계열 배포판은 .rpm을 우선 선택하세요. 그 밖의 데스크톱 배포판에서는 AppImage를 사용할 수 있습니다. 서버에 코어를 배포할 때는 아키텍처에 맞는 실행 파일을 직접 사용하면 됩니다.

경로 1: Linux 데스크톱 클라이언트 설치

데스크톱 방식에서는 Mihomo 코어가 내장되어 있고 현재도 유지 관리되며 Linux 빌드를 제공하는 클라이언트를 선택하는 것이 좋습니다. 설치 파일 이름에는 amd64, x86_64, arm64 또는 aarch64가 표시될 수 있으므로 앞서 실행한 uname -m 결과에 맞추세요. macOS용 ClashX 설치 파일을 Linux에 복사해서는 안 됩니다. 두 시스템은 프로그램 형식과 시스템 인터페이스가 호환되지 않습니다.

Ubuntu, Debian, Linux Mint에 DEB 설치

설치 파일이 “다운로드” 디렉터리에 있다고 가정하겠습니다. 먼저 해당 디렉터리로 이동한 뒤 APT로 로컬 패키지를 설치하세요. dpkg -i만 실행하는 대신 APT를 사용하면 패키지에 선언된 의존성도 함께 처리할 수 있습니다.

cd ~/다운로드
sudo apt install ./Clash-Linux-amd64.deb

영문 디렉터리 환경에서는 보통 cd ~/Downloads를 사용합니다. 파일명은 실제로 다운로드한 파일의 전체 이름으로 바꾸세요. 앞부분 몇 글자만 입력한 뒤 Tab을 누르면 자동 완성할 수 있습니다. 설치가 끝나면 애플리케이션 메뉴에서 실행하거나 dpkg -l | grep -i clash를 실행해 패키지가 등록되었는지 확인할 수 있습니다.

Fedora, RHEL 계열 배포판에 RPM 설치

cd ~/Downloads
sudo dnf install ./Clash-Linux-x86_64.rpm

dnf install은 RPM의 의존성 정보를 읽습니다. 시스템에서 데스크톱 보안 정책을 엄격하게 적용하는 경우 TUN 또는 서비스 모드를 처음 활성화할 때 관리자 권한 요청 창이 나타날 수 있습니다. 이는 가상 네트워크 카드 생성과 라우팅 변경에 필요한 권한 절차이므로 반복해서 취소하지 마세요.

AppImage 실행 및 위치 고정

AppImage는 배포판의 패키지 데이터베이스에 등록할 필요가 없지만 실행 권한이 있어야 합니다. 다음은 다운로드 디렉터리에 있는 파일을 기준으로 한 예입니다:

cd ~/Downloads
chmod +x Clash-Linux-x86_64.AppImage
./Clash-Linux-x86_64.AppImage

시스템에서 FUSE 관련 오류가 표시되면 현재 배포판의 소프트웨어 저장소를 통해 호환되는 FUSE 실행 구성 요소를 설치하세요. 또는 먼저 --appimage-extract-and-run으로 프로그램이 시작되는지 확인할 수 있습니다. 장기간 사용할 경우 AppImage를 ~/Applications로 옮기는 것이 좋습니다. 다운로드 디렉터리를 정리하다 실수로 삭제하는 일을 막을 수 있습니다.

구독을 가져오고 첫 연결 완료하기

클라이언트의 「구독」 페이지를 열고 「새로 만들기」 또는 「URL에서 가져오기」를 선택하세요. 일부 클라이언트에서는 「구독」→「새로 만들기」→「URL」 경로를 사용합니다.
서비스 제공자가 안내한 구독 주소를 붙여 넣고 확인한 뒤 한 번 업데이트하세요.
「프록시」 또는 「정책」 페이지로 이동해 주요 정책 그룹에서 노드를 선택하세요. URL 속도 측정 그룹을 선택할 수도 있습니다.
「시스템 프록시」를 켠 다음 테스트 페이지에 접속하거나 명령으로 외부 IP 주소를 확인하세요.
시스템 프록시를 읽지 않는 프로그램까지 연결을 넘겨야 할 때만 TUN 모드를 설정하세요. 처음 실행할 때 모든 네트워크 설정을 한꺼번에 변경할 필요는 없습니다.

curl -I --proxy http://127.0.0.1:7890 https://example.com
curl -I --proxy socks5h://127.0.0.1:7890 https://example.com

첫 번째 명령은 HTTP 프록시를 확인하고, 두 번째 명령은 SOCKS5를 사용하며 도메인 이름 확인을 프록시 측에 맡깁니다. 포트는 클라이언트의 실제 설정을 기준으로 해야 합니다. 일반적인 혼합 포트는 7890이지만 일부 설정에서는 HTTP와 SOCKS를 각각 7890과 7891에 지정합니다. 확인 경로는 보통 「설정」→「매개변수 설정」→「포트 설정」입니다.

경로 2: Mihomo 명령줄 코어 설치

Mihomo는 Clash 설정 체계를 이어가는 오픈 소스 코어로, 규칙 분기, 정책 그룹, 규칙 세트, DNS와 TUN을 지원합니다. 명령줄 배포에는 구독 목록이나 트레이 메뉴가 포함되지 않으며, 실행 파일을 준비하고 config.yaml을 배치한 뒤 systemd에 관리를 맡기는 것이 핵심입니다.

바이너리 파일과 전용 계정 설치

다음 명령은 다운로드 후 압축을 해제한 mihomo-linux-amd64-v1.19.12를 예로 듭니다. 버전 번호는 파일 이름 형식을 설명하기 위한 것이므로 실제 배포에서는 다운로드 페이지의 최신 버전과 올바른 아키텍처를 선택하세요.

sudo install -Dm755 mihomo-linux-amd64-v1.19.12 /usr/local/bin/mihomo
sudo useradd --system --home-dir /var/lib/mihomo --create-home --shell /usr/sbin/nologin mihomo
sudo install -d -o mihomo -g mihomo -m 750 /var/lib/mihomo
/usr/local/bin/mihomo -v

배포판에 /usr/sbin/nologin이 없다면 먼저 command -v nologin을 실행해 실제 경로를 확인하세요. 별도의 시스템 계정을 사용하면 실행 디렉터리와 일반 사용자의 홈 디렉터리를 분리할 수 있고, systemd에서 네트워크 권한을 정확하게 부여하기도 쉽습니다.

최소 실행 설정 준비

변환하거나 내보낸 전체 Clash/Mihomo 설정을 /var/lib/mihomo/config.yaml로 저장하세요. 다음 조각은 포트, 컨트롤러, DNS와 규칙의 기본 구조를 보여 주지만 프록시 노드는 포함하지 않으므로 코어의 시작과 직접 연결 경로만 확인할 수 있습니다.

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

external-controller: 127.0.0.1:9090
secret: "change-this-controller-secret"

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: true
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

proxies: []

rules:
  - MATCH,DIRECT

mixed-port: 7890은 HTTP와 SOCKS 연결을 모두 받습니다. external-controller는 제어 인터페이스이며 프록시 포트가 아닙니다. 제어 인터페이스는 127.0.0.1에서만 수신하도록 해 LAN에 직접 노출되지 않게 할 수 있습니다. 실제 설정에는 별도의 강력한 secret을 지정하고, 원격 관리 시에는 SSH 포트 포워딩으로 접근하는 것이 좋습니다.

설정을 복사한 뒤 소유자를 바로잡고 문법 테스트를 실행하세요. YAML은 들여쓰기에 민감하며 목록 항목은 일반적으로 상위 항목보다 공백 두 칸을 더 사용합니다. Tab 문자는 들여쓰기에 적합하지 않습니다.

sudo chown mihomo:mihomo /var/lib/mihomo/config.yaml
sudo chmod 640 /var/lib/mihomo/config.yaml
sudo -u mihomo /usr/local/bin/mihomo -t -d /var/lib/mihomo

테스트가 성공하면 설정 파싱이 완료됩니다. yaml, mapping 또는 unmarshal 오류가 발생하면 오류가 표시된 줄 주변의 들여쓰기, 콜론과 필드 형식을 확인하세요. 구독 응답이 웹 페이지, 로그인 안내 또는 Base64 노드 목록이라면 완전한 config.yaml로 바로 사용할 수 없습니다.

systemd로 백그라운드 실행과 부팅 시 자동 시작 설정

SSH 세션에서 Mihomo를 직접 실행하면 터미널을 닫은 뒤 프로세스가 종료될 수 있습니다. systemd는 시작 순서, 비정상 재시작, 로그 확인과 부팅 시 자동 실행을 일관되게 관리할 수 있습니다. /etc/systemd/system/mihomo.service를 만들고 다음 내용을 입력하세요:

[Unit]
Description=Mihomo Proxy Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
ExecStartPre=/usr/local/bin/mihomo -t -d /var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo
Restart=on-failure
RestartSec=5
LimitNOFILE=1048576
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target

ExecStartPre는 시작할 때마다 설정을 테스트하므로 잘못된 설정이 현재 작동 중인 프로세스를 대체하지 않습니다. Restart=on-failure는 비정상 종료 시에만 5초 간격으로 재시작합니다. CAP_NET_ADMIN과 CAP_NET_RAW는 TUN 및 관련 네트워크 작업에 사용됩니다. 로컬 HTTP/SOCKS 포트만 열고 TUN을 사용하지 않는다면 두 capability 설정 줄을 제거해 권한 범위를 더 줄일 수 있습니다.

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
journalctl -u mihomo -n 80 --no-pager

active (running)이 표시되면 서비스가 실행 중이라는 뜻입니다. YAML을 수정한 뒤 먼저 테스트 명령을 실행하고, 이어서 sudo systemctl restart mihomo를 실행하세요. 로그를 계속 확인하려면 journalctl -u mihomo -f를 사용합니다. Ctrl+C를 누르면 로그 보기만 종료되며 서비스는 중지되지 않습니다.

포트가 실제로 수신 중인지 확인

ss -lntp | grep -E '7890|9090'
curl -I --proxy http://127.0.0.1:7890 https://example.com

systemd에서는 실행 중으로 표시되지만 7890이 수신 대기하지 않는다면 설정에서 포트가 다른 값으로 변경되었는지, 규칙 세트 로드 실패로 프로세스가 종료되었는지 먼저 확인하세요. 포트는 열려 있지만 요청이 시간 초과된다면 정책 그룹 선택, 노드 연결 상태, DNS 로그와 서버 방화벽을 계속 확인해야 합니다. 바이너리 파일을 반복해서 다시 설치할 문제는 아닙니다.

TUN 모드, 시스템 프록시와 터미널 환경 변수 선택 방법

데스크톱 일상 사용: 먼저 시스템 프록시 활성화

시스템 프록시는 변경 범위가 작아 브라우저, 데스크톱 메신저와 GNOME·KDE 프록시 설정을 따르는 애플리케이션에 적합합니다. 클라이언트의 일반적인 경로는 「설정」→「시스템 프록시」→「활성화」입니다. 일상적인 웹 접속과 개발 문서 확인만 필요하다면 먼저 시스템 프록시를 사용해야 문제를 더 쉽게 좁힐 수 있습니다.

터미널 도구: 프로세스별 프록시 변수 설정

많은 명령줄 프로그램은 HTTP_PROXY, HTTPS_PROXY와 ALL_PROXY를 읽습니다. 임시 설정은 현재 터미널 세션에만 적용되며 터미널을 닫으면 자동으로 해제됩니다:

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5h://127.0.0.1:7890

curl -I https://example.com

직접 연결로 되돌리려면 다음을 실행하세요:

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxy

Git도 별도로 설정할 수 있으므로 모든 터미널 프로그램에 영구적으로 영향을 줄 필요가 없습니다:

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

git config --global --unset http.proxy
git config --global --unset https.proxy

컨테이너, 게임과 프록시 설정을 읽지 않는 프로그램: 그다음 TUN 고려

TUN 모드는 가상 네트워크 카드를 만들고 라우팅을 통해 더 많은 트래픽을 Mihomo로 전달합니다. HTTP/SOCKS 프록시를 지원하지 않는 프로그램도 처리할 수 있지만 DNS, 라우팅 우선순위, LAN 접근과 권한 문제가 추가됩니다. 서버를 원격으로 배포하기 전에는 두 번째 SSH 세션을 유지하세요. 잘못된 라우팅으로 현재 관리 연결이 끊기는 일을 막을 수 있습니다.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-redirect: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

auto-detect-interface는 기본 출구 네트워크 카드를 식별하고, auto-route는 트래픽을 넘길 라우팅을 추가하며, dns-hijack은 지정된 DNS 트래픽을 코어가 처리하도록 전달합니다. 지원 항목은 코어 버전과 운영 체제 네트워크 스택에 따라 다르므로 활성화하기 전에 mihomo -t를 실행하세요. Docker, Podman, 가상 머신 브리지 또는 정책 라우팅 환경에서는 컨테이너 네트워크 대역이 잘못 프록시로 전달되지 않도록 제외할 네트워크 대역도 확인해야 합니다.

설정 파일, 구독 업데이트와 로그 관리

데스크톱 클라이언트의 설정 위치

데스크톱 클라이언트는 보통 /etc가 아니라 사용자 데이터 디렉터리에 설정을 저장합니다. Linux에서 흔한 위치는 ~/.config/애플리케이션 디렉터리, ~/.local/share/애플리케이션 디렉터리이며, Flatpak 애플리케이션은 대개 ~/.var/app/애플리케이션 ID에 있습니다. 클라이언트가 실행 중일 때 디렉터리 전체를 직접 덮어쓰지 말고, 우선 인터페이스의 가져오기·업데이트·백업 기능을 사용하세요.

최근 수정된 YAML 파일을 찾으려면 다음을 실행하세요:

find ~/.config ~/.local/share -type f \
  \( -name '*.yaml' -o -name '*.yml' \) \
  -mtime -7 2>/dev/null

명령줄 배포 환경의 구독 업데이트

명령줄 코어는 구독 형식을 대신 판단해 주지 않습니다. 안전한 절차는 새 설정을 임시 파일에 먼저 다운로드하고 문법을 테스트한 뒤, 성공하면 정식 설정으로 교체하고 재시작하는 것입니다. 사용 중인 파일을 직접 덮어쓰면 다운로드가 한 번만 불완전해도 서비스를 다시 시작하지 못할 수 있습니다.

새 내용을 임시 YAML 파일로 저장합니다.
응답 내용이 HTML 오류 페이지가 아니라 실제 Clash/Mihomo 설정인지 확인합니다.
별도의 임시 디렉터리에서 mihomo -t를 실행합니다.
테스트가 성공하면 /var/lib/mihomo/config.yaml로 이동합니다.
파일 소유자를 바로잡고 systemd 서비스를 재시작합니다.

설정에 proxy-providers를 사용하면 Mihomo가 설정의 interval에 따라 provider를 주기적으로 새로 고칠 수 있습니다. 일반적인 interval: 86400은 86400초, 즉 24시간마다 업데이트한다는 뜻입니다. 상태 확인의 interval: 300은 5분마다 검사한다는 의미로 용도가 다릅니다. “더 빠른 업데이트”를 위해 두 값을 모두 지나치게 작게 설정하지 마세요.

로그 수준과 디스크 사용량

일상적인 실행에서는 log-level: info를 사용하는 것이 좋습니다. DNS, 규칙 매칭과 연결 실패를 점검할 때는 잠시 debug로 전환하고, 확인이 끝나면 되돌리세요. systemd 로그는 journald가 관리하며 다음 명령으로 서비스가 차지하는 용량을 확인할 수 있습니다:

journalctl --disk-usage
journalctl -u mihomo --since "30 minutes ago"
journalctl -u mihomo -p warning --since today

로그의 connection refused는 대개 대상 주소에는 도달했지만 해당 포트에서 서비스가 실행되지 않는다는 뜻입니다. i/o timeout은 네트워크 경로 또는 노드 응답 시간 초과에 가깝습니다. no such host와 DNS resolve failed가 나오면 먼저 DNS 업스트림, 하이재킹 설정과 IPv6 사용 가능 여부를 확인하세요. 오류가 로컬 수신, DNS, 노드 연결 또는 대상 사이트 중 어디에서 발생했는지 구분하면 노드를 반복해서 바꾸는 것보다 효율적으로 해결할 수 있습니다.

일반적인 설치 문제와 점검 순서

시작 시 Exec format error 발생

거의 항상 아키텍처가 맞지 않는 경우입니다. uname -m을 다시 실행하고 file /usr/local/bin/mihomo로 바이너리의 대상 아키텍처를 확인하세요. x86_64 호스트는 amd64 빌드를, aarch64 호스트는 arm64 빌드를 사용해야 합니다.

데스크톱 클라이언트는 열리지만 시스템 프록시가 작동하지 않음

「설정」→「매개변수 설정」에서 혼합 포트가 실제로 7890인지 확인하세요.
--proxy가 포함된 curl 명령을 실행해 먼저 로컬 프록시 포트가 사용 가능한지 확인하세요.
브라우저에 별도의 프록시 확장 프로그램이 설치되어 있는지 확인하세요. 확장 프로그램이 시스템 설정을 덮어쓸 수 있습니다.
현재 정책 그룹에서 사용할 수 없는 노드를 선택한 것은 아닌지 확인하세요.
터미널 프로그램은 환경 변수를 별도로 설정해야 하며 데스크톱 스위치에만 의존할 수 없습니다.

systemd가 계속 재시작됨

systemctl status mihomo --no-pager
journalctl -u mihomo -b -n 120 --no-pager
sudo -u mihomo /usr/local/bin/mihomo -t -d /var/lib/mihomo

일반적인 원인으로는 YAML 들여쓰기 오류, 다른 프로세스의 포트 사용, 실행 계정의 설정 파일 읽기 권한 부족, Geo 데이터 다운로드 실패 또는 TUN 권한 부족이 있습니다. 포트 충돌은 sudo ss -lntp로 확인하고, 권한 문제는 namei -l /var/lib/mihomo/config.yaml 출력에서 각 디렉터리의 권한을 점검하세요.

LAN 장치가 Linux 호스트의 프록시에 연결되지 않음

기본값인 allow-lan: false는 로컬 장치만 사용하도록 허용합니다. 신뢰할 수 있는 LAN 장치에 프록시를 제공해야 한다면 allow-lan: true로 변경하고 명확한 bind-address를 설정한 뒤, 호스트 방화벽에서 LAN 대역만 프록시 포트에 접근하도록 허용하세요. 외부 컨트롤러 9090은 프록시 포트를 개방한다는 이유로 함께 노출해서는 안 됩니다.