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

Linux 설치 경로와 사용 범위

데스크톱 환경에서 노드를 자주 바꿔 사용한다면 클라이언트 다운로드 페이지에서 Linux GUI 클라이언트를 선택한 뒤, 서비스 제공업체의 구독을 가져오세요. SSH 터미널만 사용할 수 있는 서버라면 mihomo를 직접 실행하고 systemd로 프로세스를 관리하는 편이 적합합니다. 두 방식은 비슷한 프록시 설정을 사용할 수 있지만 설치 방법과 권한, 프록시 연결 방식은 다릅니다. 한 시스템에서 두 방식을 동시에 활성화할 필요는 없습니다.

Clash는 이런 프록시 도구와 설정 생태계를 가리킬 때 흔히 쓰이는 이름이고, mihomo는 Clash Meta에서 이어져 발전한 코어입니다. GUI 클라이언트는 설정 관리, 트레이 아이콘, 켜기·끄기 같은 기능을 제공하고, 코어는 포트 수신, 규칙 적용, 연결 수립을 담당합니다. 코어 바이너리만 다운로드한다고 데스크톱 인터페이스가 생기는 것은 아닙니다. GUI 클라이언트를 실행해도 모든 Linux 프로그램이 자동으로 프록시에 연결되는 것은 아닙니다.

사용 환경	권장 방식	최초 확인 방법
Ubuntu·Debian 데스크톱	시스템 아키텍처에 맞는 DEB GUI 클라이언트	설정을 가져온 뒤 노드와 로컬 수신 포트 확인
Fedora 등 RPM 기반 데스크톱	시스템 아키텍처에 맞는 RPM GUI 클라이언트	코어 로그를 확인한 뒤 프록시를 지정해 요청 테스트
헤드리스 서버	mihomo 바이너리와 systemd 시스템 서비스	먼저 설정을 검증한 뒤 서비스와 7890 포트 확인

데스크톱 클라이언트 설치 및 구독 추가

시스템 아키텍처와 설치 패키지

다운로드 전에 아래 명령 두 개를 실행하세요. x86_64는 일반적으로 amd64 또는 x64 패키지에 해당하고, aarch64는 보통 arm64 패키지에 해당합니다. 배포판에 맞는 패키지 형식도 선택해야 합니다. DEB는 Debian 계열용이고 RPM은 RPM 기반 배포판용입니다. 아키텍처가 맞아도 시스템 종속성이 충족된다는 보장은 없으므로, 오래된 배포판에서는 클라이언트의 최소 실행 요구 사항도 확인하세요.

uname -m
cat /etc/os-release

다운로드 페이지에서 Clash Verge Rev, FlClash 등 프로젝트의 Linux 다운로드 경로와 현재 지원 범위를 확인할 수 있습니다. 아래 명령은 로컬 파일을 설치하는 방법을 보여 줍니다. 실제로 다운로드한 설치 패키지의 이름을 client.deb 또는 client.rpm으로 바꾸고, 파일이 있는 디렉터리로 이동한 다음 현재 배포판에 맞는 명령 하나만 실행하세요. 여기 표시된 파일명은 다운로드 주소가 아닙니다.

# Debian / Ubuntu: 현재 디렉터리에 있는 DEB 패키지 설치
sudo apt install ./client.deb

# Fedora: 현재 디렉터리에 있는 RPM 패키지 설치
sudo dnf install ./client.rpm

패키지 관리자로 로컬 패키지를 설치하면 저장소에서 제공하는 종속 항목도 함께 처리할 수 있습니다. 그래픽 라이브러리, WebKit 또는 런타임이 없다는 메시지가 표시되면 종속성 검사를 무시하고 설치를 강행하지 말고, 배포판 버전과 프로젝트 안내를 먼저 확인하세요. 서버에 그래픽 세션이 없다면 아래의 명령줄 방식을 사용하는 편이 간단합니다.

구독·설정·노드 선택

클라이언트에서 ‘구독’ 또는 ‘설정’ 페이지로 이동해 ‘가져오기’나 ‘새로 만들기’를 선택한 뒤, 서비스 제공업체가 준 구독 주소를 붙여 넣으세요. 메뉴 이름은 클라이언트와 버전에 따라 다를 수 있습니다. 노드 이름 입력란이 아니라 설정 관리 페이지에서 작업해야 합니다.
업데이트가 완료되면 방금 가져온 설정을 선택하세요. 구독 카드가 표시된다는 사실만으로 코어에 설정이 적용되었다고 볼 수는 없습니다.
‘프록시’ 페이지로 이동해 먼저 규칙 모드를 사용하고, 해당 프록시 그룹에서 사용할 수 있는 노드를 선택하세요. 구독에 노드 목록만 있고 규칙이 없다면 클라이언트가 지원하는 완전한 설정이나 서비스 제공업체가 제공하는 전체 설정과 함께 사용해야 합니다.
‘설정’에서 ‘시스템 프록시’ 스위치를 찾아 켠 다음, 브라우저가 데스크톱 프록시 설정을 사용하는지 확인하세요. 메뉴 구성이 다르면 스위치 이름으로 찾아보세요. 특정 버전의 스크린샷에서 메뉴 위치를 추측하지 마세요.

구독 링크에는 계정을 식별할 수 있는 토큰이 포함되는 경우가 많으므로 자격 증명처럼 안전하게 관리해야 합니다. 문제 해결용 스크린샷에는 오류 유형과 발생 시각만 남기고, 전체 구독 주소와 노드 비밀번호, 제어 인터페이스 키는 가리세요. 가져오기에 실패하면 먼저 응답 내용을 확인하세요. 로그인 페이지, HTML 오류 페이지, 일반 노드 URI 목록은 그대로 사용할 수 있는 완전한 mihomo YAML 설정이 아닙니다.

시스템 프록시와 TUN의 차이

시스템 프록시는 데스크톱 프록시 설정을 참조하는 앱에 주로 영향을 줍니다. 명령줄 도구, 일부 게임, 독립 실행형 네트워크 프로그램은 이를 우회할 수 있습니다. GNOME에서는 ‘설정’ → ‘네트워크’ → ‘네트워크 프록시’에서 확인할 수 있고, KDE에서는 보통 ‘시스템 설정’ → ‘네트워크’ → ‘프록시’에서 확인합니다. 클라이언트에 실제로 표시된 포트를 기준으로 삼으세요. 모든 클라이언트가 7890 포트를 사용하는 것은 아닙니다.

TUN은 가상 네트워크 인터페이스와 라우팅을 사용해 트래픽을 처리하므로 시스템 프록시와 적용 범위가 다르며, 서비스 모드와 네트워크 관리 권한, DNS 설정도 고려해야 합니다. 데스크톱에 처음 설치할 때는 먼저 시스템 프록시로 설정을 확인한 다음 클라이언트 문서에 따라 TUN을 활성화하세요. 데스크톱 코어와 별도의 systemd 코어가 같은 포트를 사용하거나 기본 경로를 동시에 수정하지 않도록 주의하세요.

mihomo 바이너리와 서비스 계정

명령줄 방식으로 설치하려면 CPU 아키텍처에 맞는 Linux 바이너리가 필요합니다. amd64와 arm64 외에도 배포 파일에 따라 명령어 집합이나 호환성 등급이 다를 수 있습니다. 오래된 CPU에서 Illegal instruction 오류가 발생하면 서비스를 반복해서 재시작하지 말고 릴리스 안내에서 호환성을 확인하세요. 해당 릴리스 파일을 다운로드해 압축을 푼 뒤 실행 파일 이름을 mihomo로 바꾸고, 파일이 있는 디렉터리로 이동합니다.

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

-v는 실제 설치된 코어 버전을 출력합니다. 이 결과를 기록해 두면 나중에 설정 필드가 호환되지 않을 때 해당 버전의 문서를 확인할 수 있습니다. GUI 클라이언트 버전만 기록하지 마세요. Exec format error가 발생하면 먼저 아키텍처와 파일 압축 해제 여부를 확인하세요. 압축 파일을 실행 파일로 바로 설치하면 안 됩니다.

전용 계정과 디렉터리 권한

로컬 HTTP/SOCKS 프록시가 7890 포트에서 수신하는 데 root 권한은 필요하지 않습니다. 아래에서는 전용 시스템 계정을 만들고, 설정은 /etc/mihomo에, 캐시와 실행 데이터는 /var/lib/mihomo에 둡니다. 예시는 Debian과 Ubuntu에서 흔히 쓰는 /usr/sbin/nologin 경로를 사용합니다. 다른 배포판에서는 먼저 command -v nologin으로 경로를 확인한 뒤 명령을 조정하세요.

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

계정은 한 번만 만들면 됩니다. 같은 이름의 계정이 이미 있다면 용도와 소속 그룹을 먼저 확인하고 바로 삭제해 다시 만들지 마세요. root가 설정을 관리하고 서비스 계정은 읽기만 할 수 있게 하면 실행 중인 프로세스가 구독 자격 증명을 실수로 덮어쓸 위험을 줄일 수 있습니다. 데이터 디렉터리는 서비스 계정에 쓰기 권한이 있어야 캐시나 규칙 리소스를 업데이트할 수 있습니다.

config.yaml 설정 및 포그라운드 검증

최소 설정과 수신 범위

sudoedit /etc/mihomo/config.yaml을 사용해 설정 파일을 만드세요. 아래는 서비스 실행 경로를 확인하기 위한 최소 완전 설정입니다. 모든 트래픽을 직접 연결하므로 포트와 프로세스가 정상 작동하는지만 확인할 수 있고, 원격 프록시 노드의 사용 가능 여부는 확인할 수 없습니다. 실제로 사용할 때는 현재 mihomo 버전과 호환되는 서비스 제공업체의 완전한 설정으로 바꾸고 로컬 수신 범위를 적절히 제한하세요.

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

rules:
  - MATCH,DIRECT

mixed-port는 같은 포트에서 HTTP와 SOCKS5 프록시 요청을 받습니다. DNS 수신 포트나 제어 패널 포트가 아닙니다. 여기서는 LAN 접근을 끄고 루프백 주소에 바인딩합니다. 서버에 공인 IP가 있더라도 7890 포트의 인바운드 방화벽 규칙을 열 필요는 없습니다.

sudo chown root:mihomo /etc/mihomo/config.yaml
sudo chmod 0640 /etc/mihomo/config.yaml

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

-t는 설정을 테스트하고, -d는 데이터 디렉터리를, -f는 설정 파일을 지정합니다. YAML 들여쓰기에 Tab을 사용하면 안 됩니다. 줄 번호 오류가 표시되면 해당 줄과 바로 위 줄의 들여쓰기, 콜론, 따옴표부터 확인하세요. 설정 테스트 통과는 설정을 읽고 불러올 수 있다는 뜻일 뿐, 노드 연결이나 모든 규칙 리소스의 지속적인 업데이트를 보장하지는 않습니다.

완전한 구독 설정으로 이전하기

완전한 YAML 설정이 이미 있다면 로컬에 config.yaml로 저장해 서버의 사용자 디렉터리에 업로드한 다음 서비스 디렉터리로 옮기세요. 아래 예시는 업로드한 파일이 현재 디렉터리에 있다고 가정합니다. 토큰이 포함된 구독 URL을 공유 스크립트나 터미널 스크린샷에 직접 넣지 마세요. 파일 확장자만 보고 내용이 올바르다고 판단해서도 안 됩니다.

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

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

새 설정의 mixed-port, allow-lan, bind-address를 확인해 설정을 덮어쓴 뒤 수신 범위가 의도치 않게 넓어지지 않도록 하세요.
proxy-providers, rule-providers 또는 상대 경로 리소스가 포함되어 있다면 경로와 디렉터리 권한을 확인하세요. 이 문서에서는 /var/lib/mihomo를 데이터 기준 디렉터리로 사용합니다.
external-controller를 활성화했다면 해당 인터페이스가 꼭 필요한지 확인하고, 루프백 주소에서 수신하도록 설정한 뒤 강력한 키를 사용하세요. 처음 설치할 때는 제어 인터페이스 설정을 제거해도 됩니다.
tun, 자동 라우팅 또는 DNS 하이재킹 설정이 포함되어 있는지 확인하세요. 이 문서의 일반 서비스 계정 구성에는 이러한 기능에 필요한 네트워크 관리 권한이 없습니다.

systemd에 등록하기 전에 포그라운드에서 한 번 실행해 로그를 확인하세요. 테스트가 끝나면 Ctrl+C를 눌러 종료하고 7890 포트를 해제한 뒤 서비스를 시작합니다.

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

systemd 상시 실행 및 부팅 시 자동 시작

/etc/systemd/system/mihomo.service를 만드세요. 시스템 서비스이므로 SSH 로그인 세션에 종속되지 않으며 터미널 연결이 끊겨도 systemd가 관리합니다. 아래 유닛은 앞서 설명한 일반 프록시 모드용입니다. 전용 계정으로 실행하고 쓰기 권한을 데이터 디렉터리로 제한합니다.

[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
ExecStartPre=/usr/local/bin/mihomo -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
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

ExecStartPre는 시작 전에 설정을 테스트하며, 테스트에 실패하면 주 프로세스를 시작하지 않습니다. Restart=on-failure는 프로세스가 비정상 종료된 뒤 재시작하는 옵션으로, 만료된 구독이나 연결할 수 없는 노드를 해결해 주지는 않습니다. network-online.target의 효과는 배포판의 네트워크 대기 서비스 구성에도 좌우되며, 원격 노드 연결을 보장하지 않습니다.

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service
systemctl is-enabled mihomo.service
systemctl is-active mihomo.service
sudo systemctl status mihomo.service --no-pager
sudo journalctl -u mihomo.service -b -n 80 --no-pager

enabled는 부팅 시 자동 시작이 설정된 상태이고, active는 현재 실행 중인 상태입니다. 두 항목을 각각 확인하세요. 서비스 유닛을 수정했다면 daemon-reload를 실행한 뒤 재시작해야 합니다. YAML만 수정한 경우 설정을 먼저 테스트한 뒤 sudo systemctl restart mihomo.service를 실행하면 됩니다. 이 문서에는 ExecReload가 설정되어 있지 않으므로 systemctl reload가 구독을 다시 불러온다고 가정하지 마세요.

프록시 연결과 네트워크 확인

서비스를 시작해도 Linux의 모든 프로세스가 자동으로 프록시를 사용하는 것은 아닙니다. 먼저 수신 상태를 확인한 다음 프록시를 명시해 요청을 테스트하세요. 이렇게 하면 코어가 시작되지 않은 문제와 앱이 프록시에 연결되지 않은 문제를 구분할 수 있습니다. 아래에서는 요청 예시로 example.com을 사용합니다. 응답 상태와 소요 시간은 현재 네트워크에 따라 달라지며 고정된 테스트 결과가 아닙니다.

sudo ss -lntp 'sport = :7890'

curl --connect-timeout 10 --max-time 30 \
  --proxy http://127.0.0.1:7890 \
  -I https://example.com

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

수신 주소는 127.0.0.1:7890이어야 합니다. HTTP 프록시를 통해 HTTPS 사이트에 접속할 때 curl은 CONNECT 터널을 사용합니다. SOCKS 예시의 socks5h는 대상 도메인 이름의 해석을 프록시에 맡긴다는 뜻입니다. 실제 DNS 해석과 트래픽 전달 방식은 코어 설정 및 적용되는 규칙에 따라 달라지므로 명령 형식만으로 요청이 원격 노드를 통과했다고 판단할 수는 없습니다.

터미널 환경 변수

현재 터미널에서 프록시를 지원하는 프로그램에 프록시를 사용하게 하려면 다음 변수를 설정할 수 있습니다. 이 변수는 현재 셸과 이후에 실행되는 하위 프로세스에만 적용되며 다른 사용자나 이미 실행 중인 프로그램, 기존 systemd 서비스에는 영향을 주지 않습니다. 일부 도구는 별도 프록시 설정을 제공하므로 해당 도구의 문서를 확인하세요.

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
export no_proxy=localhost,127.0.0.1,::1

# 현재 터미널에서 방금 설정한 프록시 변수 해제
unset http_proxy https_proxy all_proxy no_proxy

https_proxy에도 값은 http://로 지정합니다. 로컬 HTTP 프록시에 연결한다는 뜻이지, 대상 웹사이트에 암호화되지 않은 연결을 사용한다는 뜻이 아닙니다. 특정 systemd 서비스에 프록시를 적용하려면 해당 서비스의 설정에 환경 변수를 추가하세요. 프로그램 하나를 위해 서버 전체의 라우팅을 억지로 변경하지 마세요.

원격 접속 범위

개인 컴퓨터에서 서버의 루프백 프록시를 임시로 사용하려면 서버의 7890 인바운드 포트를 열지 말고 로컬에서 SSH 포트 포워딩을 설정하세요. 예를 들어 서버의 127.0.0.1:7890으로 로컬 포워딩을 설정하면 로컬 프로그램이 포워딩 포트에 연결해 프록시를 사용할 수 있습니다. SSH 호스트 이름은 기존 연결 설정을 사용하고, 접속 권한은 SSH 계정의 권한을 따릅니다.

LAN에 프록시를 공유해야 하는 경우에만 allow-lan, 수신 주소, 인증, 방화벽의 허용 출발지 범위를 별도로 계획하세요. 모든 네트워크 인터페이스에서 수신하도록 바꾸는 것은 접속 범위를 넓힐 뿐 성능 최적화가 아닙니다. 특히 공인 IP가 있는 서버에서는 접근 제어 없이 프록시를 외부에 노출하지 마세요.

시작 오류 및 유지 관리 점검

증상	우선 확인할 항목	해결 방법
`Exec format error`	CPU 아키텍처와 바이너리 형식	해당 Linux 아키텍처에 맞는 배포 파일을 다시 선택해 압축 해제
`Permission denied`	실행 권한, 디렉터리 권한, 파일 경로	서비스 계정에 설정 파일 읽기 및 데이터 디렉터리 쓰기 권한이 있는지 확인
`address already in use`	7890 포트를 이미 사용 중인 프로세스	포그라운드 테스트를 종료하거나 중복 코어를 중지
YAML 파싱 실패	로그의 줄 번호, 들여쓰기, 응답 내용	설정을 수정하고 HTML 페이지나 노드 목록을 잘못 가져오지 않았는지 확인
포트는 열려 있지만 요청 실패	노드 상태, 규칙 매칭, DNS, 외부 네트워크 연결	해당 요청의 로그를 확인해 직접 연결과 프록시 경로를 구분
서비스가 계속 시작에 실패함	설정 테스트 결과와 이번 시작의 로그	원인을 수정한 뒤 실패 상태를 초기화하고 시작

문제를 해결할 때는 구체적인 오류를 먼저 확인하고 노드, 설정, 코어, 포트를 한꺼번에 바꾸지 마세요. sudo journalctl -u mihomo.service --since "10 minutes ago" --no-pager를 실행해 최근 로그를 확인할 수 있습니다. systemd의 시작 빈도 제한에 걸렸다면 설정을 수정한 뒤 sudo systemctl reset-failed mihomo.service를 실행하고 서비스를 시작하세요. 원인을 고치지 않고 상태만 초기화하면 다시 실패합니다.

업데이트 및 롤백

현재 mihomo -v 출력을 기록하고 사용 중인 바이너리와 설정을 백업하세요. 백업 파일의 읽기 권한도 제한해야 합니다.
새 바이너리로 기존 설정을 먼저 테스트하고 버전 간 필드와 동작 변경 사항을 확인하세요. 상대 경로 리소스가 있다면 실제 서비스와 동일한 데이터 디렉터리를 사용합니다.
짧은 유지 보수 시간을 정해 서비스를 중지하고 새 바이너리를 설치한 뒤 다시 시작합니다. 수신 상태와 로그, 실제 요청을 확인하세요.
새 버전이 정상적으로 작동하지 않으면 이전 바이너리와 이에 맞는 설정을 함께 복원한 뒤 다시 확인하세요. 둘 중 하나만 복원하지 마세요.

완전한 YAML 설정 업데이트와 구독 제공자 업데이트는 별개의 작업입니다. GUI 클라이언트에는 보통 자체 구독 새로 고침 절차가 있습니다. mihomo를 단독으로 배포한 경우 proxy-providers의 업데이트 동작은 설정에 따라 달라지며, systemd를 사용한다고 전체 config.yaml이 자동으로 교체되지는 않습니다. 나중에 예약 업데이트를 추가한다면 먼저 임시 파일에 다운로드해 검증한 뒤 교체하고, 실패 시 사용할 수 있도록 이전 설정을 보관하세요.

데스크톱 방식에서는 올바른 설정을 선택하고 앱이 프록시에 연결되는 방식을 확인하는 것이 중요합니다. 명령줄 방식에서는 권한과 설정 경로, 프로세스 생명주기를 중점적으로 살펴야 합니다. 먼저 로컬 루프백 프록시가 정상 작동하는지 확인한 다음 규칙 제공자, 원격 관리, TUN을 단계적으로 추가하면 문제를 찾기 쉽습니다. 여러 플랫폼의 점검 방법은 전체 플랫폼 가이드에서, 처음 설정을 가져오는 방법은 빠른 시작 가이드에서 확인할 수 있습니다.