Linux Clash 설치 가이드: 데스크톱 클라이언트와 mihomo CLI

1. 실행 환경에 맞는 설치 방식 선택

Linux에서 Clash 규칙 기반 프록시를 사용하는 방법은 크게 두 가지입니다. 데스크톱 클라이언트는 구독 관리, 노드 선택, 시스템 프록시 설정을 담당하고, mihomo CLI는 YAML 설정을 직접 읽어 systemd로 백그라운드 프로세스를 관리합니다. mihomo는 Clash Meta 프로젝트에서 이어서 사용하는 코어 이름으로, 그래픽 인터페이스가 있어야만 작동하는 프로그램은 아닙니다.

GNOME이나 KDE 데스크톱에서 웹을 주로 이용한다면 그래픽 클라이언트가 편리합니다. GUI가 없는 서버나 개발 머신, 장시간 켜 두는 호스트에는 코어를 직접 설치할 수 있습니다. 어느 방식을 선택하든 유효한 설정 파일이 필요하며, 클라이언트나 바이너리만 설치한다고 프록시 노드가 제공되는 것은 아닙니다.

항목	데스크톱 클라이언트	mihomo CLI
사용 환경	GNOME, KDE 등 그래픽 데스크톱	GUI 없는 서버, 백그라운드 호스트
설정 위치	설정 또는 구독 관리 화면	이 예시의 경로: /etc/mihomo/config.yaml
노드 선택	프록시 그룹 화면에서 선택	설정에서 기본 순서를 지정하거나 컨트롤 API로 관리
자동 실행	클라이언트의 시작 시 실행 옵션	systemd 시스템 서비스
프록시 적용 범위	시스템 프록시 또는 TUN	먼저 로컬 프록시 포트를 사용하고, 필요할 때 TUN을 설정

2. 데스크톱 클라이언트 설치 및 구독 가져오기

배포판, CPU 아키텍처, 패키지 형식 확인

먼저 아래 두 명령을 실행하세요. x86_64는 보통 x64 또는 amd64 패키지에 해당하고, aarch64는 대개 arm64 패키지에 해당합니다. 패키지 관리자가 아키텍처가 맞지 않는 프로그램을 실행 가능한 파일로 자동 변환해 주지는 않습니다.

uname -m
cat /etc/os-release

다운로드 센터에서 Clash Verge Rev, FlClashs 등 Linux 패키지를 제공하는 클라이언트를 선택할 수 있습니다. Ubuntu와 Debian은 보통 DEB를, Fedora 등은 대개 RPM을 사용합니다. 현재 시스템에서 지원되는지는 클라이언트 릴리스 노트의 OS 및 런타임 라이브러리 요구 사항도 확인하세요.

아래는 로컬 패키지를 설치하는 예시입니다. 다운로드한 패키지 파일의 이름을 아키텍처에 맞게 client.deb 또는 client.rpm으로 바꾼 뒤 다운로드 폴더에 넣으세요. 배포판에 맞는 설치 명령 하나만 선택해 실행해야 합니다.

cd ~/Downloads

# Debian / Ubuntu: 이 명령만 실행
sudo apt install ./client.deb

# Fedora: 이 명령만 실행
sudo dnf install ./client.rpm

AppImage를 선택했다면 보통 먼저 실행 권한을 부여해야 합니다. AppImage 실행 여부는 FUSE와 데스크톱 환경의 의존성에도 영향을 받습니다. 공유 라이브러리가 없다는 메시지가 나오면 해당 클라이언트 안내에 따라 의존성을 설치하고, 그래픽 프로그램 전체를 root로 실행하는 방식은 피하세요.

가져오기, 활성화, 노드 선택, 프록시 설정 순서로 진행

클라이언트를 실행하고 ‘설정’ 또는 ‘구독’ 화면에서 서비스 제공자가 안내한 Clash/mihomo 설정 주소를 가져오세요. 메뉴 이름은 클라이언트마다 다릅니다. 임의의 노드 공유 링크가 완전한 YAML 설정 파일인 것은 아닙니다.
업데이트가 끝나면 해당 설정을 현재 사용 항목으로 지정하세요. 구독 이름만 저장된 것이 아니라 노드 목록, 프록시 그룹, 규칙까지 불러왔는지 확인합니다.
프록시 그룹으로 이동해 사용할 수 있는 노드를 선택하고 지연 시간을 테스트하세요. 시간 초과가 표시되더라도 테스트 주소에 연결할 수 없는 경우일 수 있으므로, 실제 접속 여부를 함께 확인해야 합니다.
규칙 모드를 선택한 다음 시스템 프록시를 켜세요. 클라이언트에 표시된 로컬 수신 포트를 확인합니다. 뒤에서 사용하는 7890은 설명을 위한 예시일 뿐입니다.

GNOME을 예로 들면 ‘설정’ → ‘네트워크’ → ‘네트워크 프록시’에서 수동 프록시 주소를 확인할 수 있습니다. 클라이언트에서 mixed-port: 7890을 사용하는 경우 HTTP와 HTTPS 프록시 모두 주소는 127.0.0.1, 포트는 7890으로 설정하면 됩니다. 다른 데스크톱 환경에서는 메뉴 경로가 다를 수 있습니다.

시스템 프록시는 모든 앱의 트래픽을 가로채는 기능이 아닙니다. 브라우저는 데스크톱 프록시 설정을 따르는 경우가 많지만, 터미널 도구와 컨테이너, 일부 독립 실행형 앱은 따르지 않을 수 있습니다. 브라우저에서는 되는데 터미널에서 실패한다면 전체 모드를 바꾸기 전에 터미널에 프록시를 명시적으로 지정해 보세요.

3. mihomo 코어 설치 및 설정 디렉터리 구성

바이너리와 완전한 YAML 설정 준비

GUI 없는 환경에 설치하려면 CPU 아키텍처와 시스템 환경에 맞는 mihomo Linux 바이너리가 필요합니다. 압축 파일을 먼저 풀고, 안에 있는 실행 파일의 이름을 mihomo로 바꾸세요. 아래 명령은 현재 디렉터리의 파일을 설치한 뒤 실제 버전을 확인합니다. 버전 번호를 기록해 두면 설정 항목 호환성 문제를 진단하기 쉽습니다.

sudo install -m 0755 ./mihomo /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

이 예시에서는 정적 설정과 실행 데이터를 분리합니다. /etc/mihomo/config.yaml에는 완전한 설정을 저장하고, /var/lib/mihomo에는 캐시와 규칙 리소스 등 쓰기 가능한 데이터를 둡니다. 별도의 시스템 사용자 mihomo로 실행해 일반 프록시 서비스에 시스템 전체의 관리자 권한을 부여하지 않습니다.

getent passwd mihomo >/dev/null || sudo useradd \
  --system --user-group --home-dir /var/lib/mihomo \
  --shell /usr/sbin/nologin mihomo

sudo install -d -m 0750 -o root -g mihomo /etc/mihomo
sudo install -d -m 0750 -o mihomo -g mihomo /var/lib/mihomo

# 현재 디렉터리의 config.yaml에는 준비가 완료된 전체 설정이 있어야 합니다
sudo install -m 0640 -o root -g mihomo \
  ./config.yaml /etc/mihomo/config.yaml

시스템에 같은 이름의 사용자가 이미 있다면 주 그룹과 디렉터리 권한부터 확인하세요. 계정에 관한 가정을 그대로 적용해 사용자를 중복 생성하지 마세요. 설정에는 노드 인증 정보, 구독 주소, 컨트롤 키가 포함될 수 있습니다. 로컬의 모든 사용자에게 읽기 권한을 주거나 공개 저장소에 올리지 마세요.

노드와 규칙은 유지하고 수신 설정만 병합

기존 전체 설정에서 다음 최상위 항목을 확인하세요. 아래 내용은 기존 설정에 병합하는 조각이며, 구독 설정 전체를 대체하지 않습니다. 기존 proxies, proxy-providers, proxy-groups, rules 등의 항목은 유지하세요. 같은 YAML 맵에서 동일한 키를 중복 정의하면 안 됩니다.

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

mixed-port는 한 포트에서 HTTP 프록시와 SOCKS5 요청을 모두 받습니다. 그렇다고 시스템의 모든 트래픽이 자동으로 이 포트를 거치는 것은 아닙니다.
allow-lan: false와 루프백 주소 수신 설정은 로컬 접속용이며, 공용 인터넷에 프록시 포트를 공개하지 않습니다.
mode: rule은 설정에 정의된 규칙에 따라 트래픽을 분기합니다. 규칙에서 참조하는 정책 그룹이 실제로 존재해야 하며, 마지막에는 적절한 기본 규칙을 두는 것이 일반적입니다.
처음 설치할 때는 TUN을 꺼 두세요. 노드, 라우팅, DNS, 권한 문제를 한꺼번에 진단해야 하는 상황을 피할 수 있습니다.

서비스 계정으로 설정을 검사하세요. -d는 실행 데이터 디렉터리, -f는 설정 파일, -t는 설정 테스트를 지정합니다. 설정에서 외부 규칙이나 지리 데이터를 사용한다면 해당 리소스를 가져올 수 있는지, 지정한 경로를 읽을 수 있는지도 확인해야 합니다. 문법 검사를 통과해도 노드 연결까지 성공한 것은 아닙니다.

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml

4. systemd로 mihomo 상시 실행

설정 검사에 통과하면 /etc/systemd/system/mihomo.service를 만드세요. 아래 서비스 단위는 일반적인 로컬 프록시 포트용이며, TUN에 필요한 네트워크 관리 권한은 부여하지 않습니다. network-online.target은 서비스 시작 순서를 정할 뿐, 노드나 인터넷에 연결할 수 있음을 보장하지 않습니다.

sudo tee /etc/systemd/system/mihomo.service >/dev/null <<'EOF'
[Unit]
Description=mihomo local proxy service
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5
UMask=0077
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF

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

active (running)은 프로세스가 계속 실행 중이라는 뜻일 뿐입니다. 로그에서 설정 파싱 실패, 리소스 다운로드 실패, address already in use 메시지가 있는지 확인하세요. 클라이언트도 7890 포트를 사용 중이라면 한쪽을 종료하거나 두 프로세스에 서로 다른 포트를 지정해야 합니다.

config.yaml을 수정했다면 먼저 설정 테스트를 다시 실행한 뒤 서비스를 재시작하세요. 이 서비스 단위에는 ExecReload가 정의되어 있지 않으므로 systemctl reload mihomo로 설정을 다시 불러올 수 있다고 가정하면 안 됩니다. service 파일을 수정한 경우에만 daemon-reload를 다시 실행하면 됩니다.

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml

# 앞 단계의 검사가 성공한 뒤 실행
sudo systemctl restart mihomo
sudo journalctl -u mihomo -b -n 40 --no-pager

5. 포트, 터미널 프록시, 규칙 적용 확인

먼저 수신 포트를 확인한 다음 프록시 요청을 명시적으로 전송

첫 번째 명령은 7890 포트의 TCP 수신 주소를 확인합니다. 예상되는 결과는 127.0.0.1:7890입니다. 공용 주소나 0.0.0.0이 표시되면 수신 설정을 다시 확인하세요. 두 번째 명령은 HTTP 프록시를 명시적으로 거쳐 이 사이트에 접속합니다. 20초 제한은 요청 제한 시간이지 노드 지연 시간 지표가 아닙니다.

sudo ss -lntp 'sport = :7890'

curl --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 20 \
  --output /dev/null --show-error \
  --write-out 'HTTP %{http_code}\n' \
  https://clash-system.com/

HTTP 응답을 받으면 요청이 로컬 프록시 포트까지 도달했다는 뜻입니다. 하지만 원격 노드를 거쳤다고 단정할 수는 없습니다. 규칙에 따라 DIRECT가 선택되었을 수 있습니다. 로그에서 대상 도메인, 일치한 규칙, 실제 적용된 정책을 확인하세요. 설정에서 프록시 그룹을 참조한다면 그룹에서 어떤 노드를 선택했는지도 확인해야 합니다.

현재 터미널에 프록시 환경 변수 설정

프록시 환경 변수를 따르는 프로그램이라면 현재 셸에서 아래 변수를 설정할 수 있습니다. HTTPS 사이트에 접속할 때도 HTTP 프록시 주소는 http://127.0.0.1:7890로 지정합니다. 도구가 CONNECT 터널을 만들기 때문에 대상 사이트가 HTTPS라는 이유만으로 프록시 주소의 프로토콜까지 HTTPS로 바꾸면 안 됩니다.

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1

# SOCKS5를 테스트하고 도메인 조회를 프록시 측에서 처리할 때
curl --proxy socks5h://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 20 \
  --output /dev/null --show-error \
  https://clash-system.com/

# 현재 터미널 환경 변수 해제
unset http_proxy https_proxy no_proxy

이 변수는 현재 셸과 그 자식 프로세스에만 적용되며, 모든 systemd 서비스에 자동으로 전달되지는 않습니다. sudo가 환경 변수를 제거할 수도 있습니다. 컨테이너 안의 127.0.0.1은 컨테이너 자신을 가리키므로 호스트의 루프백 주소를 컨테이너 프록시 주소로 바로 사용할 수 없습니다. 접근 가능한 주소와 접근 제한을 별도로 구성해야 합니다.

6. TUN, DNS, 원격 관리 설정 시 주의할 점

TUN은 일반 포트 프록시에 반드시 필요한 기능이 아닙니다

TUN은 가상 네트워크 장치와 라우팅을 이용해 트래픽을 전달하며, 시스템 프록시를 따르지 않는 앱에 유용합니다. 커널의 TUN 지원과 장치 접근, 네트워크 관리 권한, 라우팅 설정이 필요합니다. 앞서 만든 최소 권한 systemd 서비스에서 tun.enable만 true로 바꾼다고 바로 사용할 수 있는 것은 아닙니다.

먼저 ls -l /dev/net/tun으로 장치를 확인한 뒤, 사용 중인 mihomo 문서에 따라 서비스 권한과 TUN 옵션을 설정하세요.
원격 서버에서 자동 라우팅을 켜기 전에 콘솔이나 다른 복구 경로를 준비하세요. SSH 관리 연결이 끊기는 상황을 막을 수 있습니다.
DNS 문제를 진단할 때는 시스템 리졸버, mihomo의 DNS 설정, TUN의 DNS 처리 방식을 함께 확인해 DNS 조회가 순환하거나 업스트림에 연결되지 않는 상황을 방지하세요.
데스크톱 클라이언트의 TUN과 다른 코어 서비스의 자동 라우팅을 동시에 켜지 마세요.

일반 HTTP 프록시, SOCKS5, TUN은 도메인 조회 경로가 서로 다를 수 있습니다. 예를 들어 socks5h는 대상 도메인 조회를 프록시 측에 맡깁니다. 따라서 로컬에서 getent hosts만 실행해 본 결과로 모든 프록시 요청을 검증할 수는 없습니다. IP 주소로는 접속되지만 도메인으로는 실패한다면 먼저 어느 조회 경로에서 문제가 발생하는지 구분하세요.

컨트롤 인터페이스와 프록시 포트는 별도로 관리

external-controller는 관리 API이며 브라우저 트래픽을 전달하는 HTTP 프록시가 아닙니다. 흔한 예시 주소는 127.0.0.1:9090으로, mixed-port: 7890과 역할이 다릅니다. 꼭 활성화해야 한다면 별도의 강력한 secret을 설정하고 루프백 주소에서만 수신하도록 하세요. 이 예시에서는 컨트롤 인터페이스를 기본으로 활성화하지 않습니다.

원격으로 작업할 때는 SSH로 로컬 프록시 포트를 포워딩할 수 있습니다. 예를 들어 개인 컴퓨터에서 아래 명령을 실행하면 컴퓨터의 17890 포트를 서버의 7890 포트로 연결합니다. 이 명령은 SSH 설정에 미리 등록된 proxy-server 호스트 별칭을 사용합니다. 먼저 개인 컴퓨터의 SSH 설정에서 해당 별칭에 실제 호스트와 사용자 정보를 지정해야 합니다.

ssh -N -L 127.0.0.1:17890:127.0.0.1:7890 proxy-server

이제 개인 컴퓨터의 앱에서 127.0.0.1:17890에 연결하면 됩니다. SSH 포워딩이 서버의 프록시 서비스를 자동으로 시작하거나 컴퓨터의 시스템 프록시를 자동으로 변경하는 것은 아닙니다. 원격 접속을 위해 7890 포트나 컨트롤 포트를 인터넷에 직접 공개하지 마세요.

7. 구독 업데이트와 자주 발생하는 문제

데스크톱 클라이언트에서는 보통 구독을 업데이트할 수 있습니다. 독립 실행형 mihomo는 로컬 YAML 파일을 읽는 것만으로 원격 구독 전체를 자동 갱신하지 않습니다. 설정의 proxy-providers와 rule-providers는 각각의 옵션에 따라 리소스를 업데이트할 수 있지만, 전체 설정 파일을 교체하는 기능은 아닙니다.

전체 설정을 업데이트할 때는 먼저 기존 파일을 백업하고 새 내용을 후보 파일에 저장한 뒤, 같은 서비스 계정으로 테스트하세요. 테스트를 통과하면 /etc/mihomo/config.yaml에 설치하고 서비스를 재시작합니다. 네트워크 다운로드가 한 번 실패했다고 현재 사용 중인 설정을 바로 덮어쓰지 마세요. 구독 주소를 로그나 지원 요청에 공개하는 것도 피해야 합니다.

증상	우선 확인할 항목	해결 방법
Exec format error	uname -m 결과와 다운로드한 아키텍처	압축을 풀고 해당 아키텍처에 맞는 바이너리 설치
Permission denied	실행 권한, 디렉터리 권한, 서비스 사용자	바이너리에 실행 권한이 있는지, 설정을 읽을 수 있는지, 실행 데이터 디렉터리에 쓸 수 있는지 확인
7890 포트가 이미 사용 중	ss 출력에 표시된 프로세스	중복 인스턴스를 중지하거나 수신 포트를 변경
프로세스는 실행 중이지만 요청 실패	노드 상태, 규칙 적용 결과, DNS 로그	로컬 프록시 포트 접속 성공과 원격 노드 연결 성공을 구분
브라우저는 되지만 터미널은 실패	터미널에서 프록시를 사용 중인지 확인	curl --proxy 또는 환경 변수로 테스트
재시작 후 설정이 바뀜	클라이언트 구독 업데이트 여부, 서비스의 -f 경로	설정 출처를 확인하고 덮어써질 파일을 직접 수정하지 않도록 주의

설치 완료 여부는 바이너리 실행, 설정 테스트 통과, 서비스 안정성, 루프백 포트 수신, 요청의 코어 전달, 예상한 규칙 적용 순서로 확인하세요. 이 여섯 단계를 나눠 검증한 뒤 자동 업데이트나 TUN을 추가하면 이후 문제를 더 쉽게 진단할 수 있습니다.