플랫폼 예상 읽기 시간 12분

Linux Clash 설치 가이드: 데스크톱 GUI 클라이언트와 systemd 서버 배포

Linux 데스크톱에는 GUI 클라이언트를, 서버나 헤드리스 환경에는 mihomo 바이너리와 systemd를 설치하는 방법을 안내합니다. 설치부터 설정 디렉터리, 부팅 시 자동 실행, 터미널 프록시 환경 변수까지 두 가지 배포 방식을 정리했습니다.

배포 방식 선택: 데스크톱은 GUI, 서버는 독립 실행형 코어

먼저 결론부터 말하면, GNOME이나 KDE 같은 데스크톱 환경에서 구독과 정책 그룹을 자주 바꿔야 한다면 Linux GUI 클라이언트를 권장합니다. SSH로 관리하고 데스크톱 세션이 없는 서버에는 mihomo와 systemd 조합이 더 적합합니다. 두 방식 모두 로컬 프록시 포트를 제공하지만 시작 시점, 설정 위치, 권한 범위가 다릅니다. 같은 포트를 두 코어가 동시에 점유하도록 설정하지 마세요.

Clash는 이 유형의 클라이언트를 통칭할 때 흔히 쓰이는 이름입니다. mihomo는 Clash Meta를 계승해 발전한 코어이며, GUI 클라이언트는 인터페이스와 구독, 서비스 관리를 담당합니다. 실제 연결 기능은 탑재된 코어에 따라 달라집니다. 오래된 클라이언트의 설명을 현재 mihomo에 그대로 적용하거나, 모든 Clash 형식 구독이 같은 프로토콜을 지원한다고 가정하지 마세요.

비교 항목GUI 클라이언트mihomo 및 systemd
사용 환경로그인된 데스크톱 세션서버 및 헤드리스 호스트
설정 방식구독·설정·정책 그룹 인터페이스로컬 YAML 파일
시작 방식데스크톱 로그인 시 자동 실행 또는 클라이언트 서비스시스템 부팅 시 서비스 시작
이 문서의 테스트 포트클라이언트에 표시된 실제 값을 기준으로 확인예시에서는 127.0.0.1:7890으로 고정

설치 전 확인: 아키텍처, 패키지 형식, 사용 중인 포트

먼저 아래 세 명령을 실행하세요. 첫 번째는 CPU 아키텍처, 두 번째는 systemd 설치 여부, 세 번째는 사용할 포트를 확인합니다. 출력에 이미 7890을 사용하는 프로세스가 있으면 다른 프록시 코어인지 먼저 확인한 뒤 중지하거나 포트를 변경하세요.

uname -m
systemctl --version
sudo ss -lntup 'sport = :7890'
  • x86_64는 보통 amd64 또는 x64 패키지에 해당하고, aarch64는 보통 arm64에 해당합니다. 32비트 ARM에서는 arm64 바이너리를 실행할 수 없습니다.
  • Debian 및 Ubuntu 계열은 아키텍처에 맞는 DEB 패키지를, Fedora 등 RPM 계열은 RPM 패키지를 선택하세요. 패키지 형식과 CPU 아키텍처를 각각 확인해야 합니다.
  • 구형 CPU에서는 릴리스 노트에 안내된 명령어 집합 요구 사항도 확인하세요. Illegal instruction 오류가 발생하면 파일명의 amd64 표기만 믿지 말고 빌드 변형을 먼저 확인해야 합니다.
  • Alpine은 일반적으로 OpenRC를 사용하고 사용자 공간도 musl 기반인 경우가 많습니다. 이 환경에는 이 문서의 systemd 유닛을 그대로 적용할 수 없습니다.

클라이언트와 코어는 프로젝트의 공식 릴리스 채널에서 받으세요. 이 문서에서는 검증하지 않은 특정 버전을 지정하지 않습니다. 설치한 버전과 아키텍처를 기록해 두면 나중에 문제를 비교하고 진단하기 쉽습니다. 코어 설치 후 mihomo -v로 실제 버전을 확인할 수 있습니다. GUI 클라이언트는 앱 버전과 코어 버전을 모두 기록하세요.

방법 1: Linux 데스크톱 GUI 클라이언트

전체 설정을 먼저 가져온 뒤 시스템 프록시를 켜세요

Clash Verge Rev, FlClash 등은 Linux GUI를 제공하지만 배포 패키지와 시스템 통합 방식은 서로 다릅니다. 사이트의 다운로드 센터에서 플랫폼별 다운로드와 지원 조건을 비교한 뒤 해당 프로젝트의 안내에 따라 설치하세요. DEB 패키지는 sudo apt install ./파일명.deb 명령으로 설치할 수 있습니다. 파일명은 다운로드 디렉터리에 있는 실제 파일명으로 바꾸세요. 설명에 적힌 이름을 그대로 복사하면 안 됩니다.

  1. 클라이언트의 구독 또는 설정 화면에서 서비스 제공자가 준 Clash/mihomo 설정을 가져오세요. 구독 URL에는 보통 접근 자격 증명이 포함되므로 공개 스크린샷이나 로그에 노출하지 마세요.
  2. 설정을 업데이트한 뒤 노드와 정책 그룹이 표시되는지 확인하세요. 노드 목록만 있다고 해서 DNS, 규칙, 정책 그룹까지 모두 올바르게 설정된 것은 아닙니다.
  3. 규칙 모드를 선택한 다음 대상 정책 그룹에서 노드를 하나 고르세요. 화면에 표시된 HTTP, SOCKS 또는 혼합 포트도 기록해 두세요.
  4. 시스템 프록시를 켜고 프록시 규칙이 적용될 것이 확실한 주소에 브라우저로 접속하세요. 연결 기록에서 적용된 규칙과 정책 그룹, 실제 출구를 확인합니다.

클라이언트마다 메뉴 구성은 다를 수 있으므로 모든 프로그램에 공통인 고정 메뉴 경로를 찾으려 하지 마세요. 대신 설정 활성화 여부, 코어 실행 여부, 포트 번호, 시스템 프록시 적용 여부를 확인하세요. 트레이 아이콘이 보인다는 사실만으로 트래픽이 코어에 전달되고 있다고 볼 수는 없습니다.

설정 디렉터리와 데스크톱 로그인 시 자동 실행

GUI 클라이언트는 XDG 사용자 디렉터리의 애플리케이션 하위 폴더에 데이터를 저장할 수 있습니다. 예를 들면 ~/.config 또는 ~/.local/share 아래입니다. 정확한 경로는 앱마다 다르므로 클라이언트에서 제공하는 설정 디렉터리 기능을 우선 사용하세요. 경로를 추측해 파일을 일괄 삭제하지 마세요. 구독 캐시, 오버라이드 파일, 코어가 실제로 사용하는 설정 파일은 서로 다를 수 있습니다.

먼저 수동 실행이 정상인지 확인한 다음 클라이언트에서 로그인 시 자동 실행을 켜고, 로그아웃 후 다시 로그인해 검증하세요. 데스크톱 자동 실행은 일반적으로 사용자가 로그인한 뒤 시작한다는 뜻이지, 로그인하지 않아도 실행된다는 뜻은 아닙니다. 클라이언트에서 독립 서비스 모드를 제공한다면 해당 서비스 설치 안내를 따르세요. 같은 포트를 사용하는 systemd 서비스를 추가로 설정하지 마세요.

방법 2: mihomo 바이너리와 설정 디렉터리 준비

아래 절차에서는 권한이 제한된 전용 사용자로 일반 프록시 서비스를 실행합니다. TUN에 필요한 네트워크 관리 권한은 부여하지 않습니다. 먼저 아키텍처에 맞는 공식 압축 파일을 받으세요. gzip으로 압축된 단일 파일을 받았다면 로컬에서 mihomo.gz로 이름을 바꾼 다음 해당 디렉터리에서 실행합니다.

gzip -dk mihomo.gz
file ./mihomo
chmod u+x ./mihomo
./mihomo -v
sudo install -o root -g root -m 0755 ./mihomo /usr/local/bin/mihomo

Exec format error는 아키텍처가 맞지 않거나 압축 파일을 실행 파일처럼 실행했을 때 흔히 발생합니다. 다운로드 및 압축 해제 단계부터 다시 확인하세요. 실행 권한을 반복해서 추가하는 방식으로 해결하려 하지 마세요. 다음으로 서비스 계정을 만듭니다. 같은 이름의 계정이 이미 있으면 용도를 먼저 확인하고, 중복 생성하거나 권한을 바로 변경하지 마세요.

sudo useradd --system --user-group \
  --home-dir /var/lib/mihomo \
  --shell /usr/sbin/nologin mihomo

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

준비한 완전한 설정 파일을 현재 디렉터리의 config.yaml로 저장한 뒤 서비스 설정 디렉터리에 설치하세요. 이 문서에서는 공개 노드를 제공하지 않으며 DNS와 포트만 있는 일부 설정을 완전한 구독으로 취급하지 않습니다. 설정에는 서비스에 맞는 노드 또는 제공자, 정책 그룹, 규칙이 포함되어야 합니다.

sudo install -o root -g mihomo -m 0640 \
  ./config.yaml /etc/mihomo/config.yaml

완전한 설정 파일에 이미 있는 동일한 필드를 수정하세요. YAML 파일 끝에 같은 키를 중복으로 추가하지 마세요. 로컬 일반 프록시에 필요한 주요 필드는 다음과 같습니다. 이 코드는 일부 설정만 보여 주며 단독으로 동작하는 전체 설정은 아닙니다.

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

mixed-port를 설정하면 하나의 포트에서 HTTP와 SOCKS 프록시 연결을 모두 받을 수 있습니다. 이 예시는 로컬 사용만을 대상으로 합니다. 완전한 설정에 다른 인바운드 포트, DNS 리스너 또는 제어 인터페이스가 있다면 각각의 리스닝 주소도 확인하세요. 특히 external-controller는 관리 기능이 필요 없다면 활성화하지 않아도 됩니다. 활성화해야 한다면 루프백 주소에 바인딩하고 별도의 접근 키를 설정하세요.

이 문서에서는 읽기 전용 기본 설정을 /etc/mihomo에, 캐시와 데이터베이스 및 실행 데이터를 /var/lib/mihomo에 둡니다. proxy-providers 또는 rule-providers를 사용한다면 업데이트할 파일은 ./providers/main.yaml처럼 작업 디렉터리 안에 저장하세요. 나중에 읽기 전용으로 설정할 디렉터리에 파일을 쓰지 않도록 주의하세요.

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

테스트 통과는 설정 파일을 정상적으로 불러왔다는 뜻일 뿐, 노드 연결까지 확인됐다는 뜻은 아닙니다. 파일 권한이나 데이터베이스 누락 오류가 발생하면 오류 내용에 따라 경로와 권한, 필요한 리소스를 수정한 뒤 서비스를 설정하세요.

systemd 서비스 설정: 시작, 부팅 시 자동 실행, 로그 확인

sudoedit /etc/systemd/system/mihomo.service로 새 유닛 파일을 만들고 아래 내용을 입력하세요. 실행 파일과 설정 파일, 작업 디렉터리를 명시하고 서비스가 시스템의 다른 위치에 쓰지 못하도록 제한합니다. 네트워크 관리 권한은 부여하지 않으므로 설정에서 TUN을 활성화하지 마세요.

[Unit]
Description=mihomo local proxy service
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
StateDirectory=mihomo
StateDirectoryMode=0750
WorkingDirectory=/var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5s
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service
systemctl is-enabled mihomo.service
systemctl is-active mihomo.service
sudo journalctl -u mihomo.service -b -n 80 --no-pager
sudo ss -lntp 'sport = :7890'

enable --now는 부팅 시 자동 시작을 설정하고 서비스를 즉시 실행합니다. enabled는 앞으로 시작될지, active는 현재 실행 중인지를 각각 보여 줍니다. 리스닝 주소가 예시 설정과 일치하는지 확인하세요. 의도치 않은 공인 네트워크 주소가 아니라 127.0.0.1:7890에서 수신해야 합니다.

  • YAML을 수정한 뒤에는 설정을 먼저 테스트하고 sudo systemctl restart mihomo를 실행하세요. 재시작하는 동안 기존 프록시 연결이 잠시 끊깁니다.
  • 서비스 유닛을 수정한 뒤에는 sudo systemctl daemon-reload를 먼저 실행한 다음 서비스를 재시작하세요.
  • 서비스가 계속 실패하면 로그에서 실제로 발생한 첫 번째 오류를 확인하세요. 수정 후 시작 빈도 제한에 걸렸다면 sudo systemctl reset-failed mihomo를 실행한 다음 다시 시작할 수 있습니다.

network-online.target이 활성화되어도 인터넷, DNS 또는 구독 서버에 반드시 연결할 수 있는 것은 아닙니다. 원격 규칙 및 제공자 업데이트가 실패하면 네트워크 준비 지연, 잘못된 URL, 파일 쓰기 권한 문제를 구분해 확인하세요. 로그를 공개하기 전에 구독 주소와 키 등 민감한 정보를 삭제하세요.

터미널 프록시 환경 변수: 해당 변수를 읽는 프로세스에만 적용

서비스를 실행해도 모든 명령줄 도구가 자동으로 프록시를 사용하지는 않습니다. 먼저 현재 터미널에서 HTTP 프록시를 임시로 설정하세요. HTTPS 주소에도 보통 아래의 http:// 프록시 주소를 사용하며, 클라이언트가 CONNECT로 터널을 만듭니다. 접속 대상 URL이 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

curl -I --connect-timeout 10 --max-time 20 https://example.com

환경 변수를 설정하지 않고 요청 한 번에 프록시를 지정할 수도 있습니다. 아래 두 명령은 각각 HTTP와 SOCKS5 프록시를 테스트합니다. socks5h의 h는 대상 도메인 이름을 프록시에서 해석한다는 뜻이지만, 실제 DNS 해석 경로는 코어 설정과 노드 프로토콜에 따라 달라집니다.

curl --noproxy "" -x http://127.0.0.1:7890 \
  -I --connect-timeout 10 --max-time 20 https://example.com

curl --noproxy "" --proxy socks5h://127.0.0.1:7890 \
  -I --connect-timeout 10 --max-time 20 https://example.com

환경 변수를 유지하려면 Bash 대화형 터미널에서는 ~/.bashrc, Zsh에서는 ~/.zshrc에 추가한 뒤 터미널을 다시 열어 확인하세요. 로그인 셸, 데스크톱 앱, systemd 서비스는 각각 환경 변수를 불러오는 경로가 다르므로 모두 Bash 설정을 읽는다고 가정하면 안 됩니다. 일부 도구는 소문자 변수만 받지만 대문자 변수도 지원하는 도구도 있으므로 해당 도구의 문서를 따르세요.

sudo는 일반적으로 프록시 환경 변수를 제거합니다. APT와 컨테이너, 기타 서비스도 별도 설정이 필요할 수 있습니다. 편의를 위해 모든 프로세스에 적용되는 전역 환경에 프록시 변수를 넣지 마세요. 먼저 단일 명령으로 확인한 뒤 적용 범위를 정하세요. 현재 터미널의 프록시 설정을 해제하려면 다음을 실행합니다.

unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

TUN, 원격 접속, 자주 발생하는 문제

TUN은 어떤 경우에 고려할까요?

브라우저와 프록시 환경 변수를 지원하는 도구는 정상인데 시스템 프록시나 환경 변수를 읽지 않는 앱이 있을 때 TUN을 고려하세요. TUN은 가상 네트워크 인터페이스와 라우팅, DNS를 제어하므로 enable을 true로 바꾸는 것만으로 어떤 시스템에서든 작동하지는 않습니다.

먼저 ls -l /dev/net/tun으로 확인하세요. 컨테이너에서는 호스트가 해당 장치와 네트워크 권한을 허용해야 하고, VPS에서도 제한이 있을 수 있습니다. 이 문서의 권한 제한 서비스는 필요한 권한을 설정하지 않았으므로 TUN에 바로 사용할 수 없습니다. 필요하다면 최신 mihomo 문서를 참고해 서비스 권한을 다시 검토하세요. 특히 네트워크 관리 권한과 자동 라우팅, DNS 가로채기 설정을 확인해야 합니다. 일반적인 해결책이라며 서비스 전체를 root로 실행하지 마세요.

SSH로 원격 호스트의 라우팅을 변경할 때는 두 번째 세션과 서비스 제공업체의 관리 콘솔을 열어 두고 되돌릴 방법을 준비하세요. TUN의 자동 라우팅이나 엄격한 라우팅이 원격 관리 연결에 영향을 줄 수 있습니다. 연결 패널에 기록이 보이더라도 DNS가 TUN을 통과한다고 단정할 수 없습니다. 앱 자체의 암호화 DNS 설정도 별도로 확인하세요.

원격 컴퓨터에서 로컬 리스너를 안전하게 사용하는 방법

내 컴퓨터에서 서버의 프록시를 사용하려는 경우 7890 포트를 인터넷에 직접 노출할 필요가 없습니다. SSH 로컬 포트 포워딩을 설정하세요. ssh -L 17890:127.0.0.1:7890 뒤에 평소 서버 로그인에 사용하는 접속 대상을 붙이면 됩니다. 그런 다음 로컬 앱에서 127.0.0.1:17890에 연결하세요. 서버의 노드와 규칙, 네트워크가 정상적으로 작동해야 합니다.

여러 변수를 한꺼번에 바꾸지 말고 증상별로 확인하세요

  • Connection refused: 먼저 서비스 상태와 리스닝 포트를 확인하세요. 보통 이 단계에서는 요청이 아직 규칙 판정에 도달하지 않았습니다.
  • 서비스는 실행 중인데 요청이 시간 초과됨: 제공자 업데이트와 선택한 노드, 대상 규칙, 서버의 외부 네트워크 연결을 확인하세요. 바로 클라이언트를 다시 설치하지 마세요.
  • 터미널은 되지만 브라우저는 안 됨: 브라우저와 데스크톱 프록시 설정을 확인하세요. 환경 변수는 이미 실행 중인 브라우저의 네트워크 동작을 자동으로 바꾸지 않습니다.
  • 브라우저는 되지만 터미널은 안 됨: 현재 셸의 환경 변수와 도구의 프록시 지원 여부, sudo가 환경 변수를 제거하는지 확인하세요.
  • 재부팅 후 작동하지 않음: 데스크톱 로그인 시 자동 실행과 시스템 부팅 시 서비스를 구분하세요. systemctl is-enabled mihomo를 확인하고 이번 부팅의 로그도 살펴보세요.

마지막으로 세 가지를 확인하세요. 재부팅 후 서비스가 시작되는지, 7890이 예상한 주소에서만 수신하는지, 프록시 규칙이 적용될 것이 확실한 요청이 연결 기록에 해당 노드와 함께 표시되는지 확인합니다. 이 세 항목과 실제 코어 버전을 기록해 두면 업그레이드나 이전 후 같은 조건으로 다시 점검할 수 있습니다. 설정 기초는 입문 가이드에서, DNS와 규칙은 사용 설명서에서 확인하세요.

최신 Clash 다운로드