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

먼저 선택하세요: 데스크톱 세션 또는 백그라운드 서비스

mihomo는 Clash Meta 프로젝트에서 사용하는 코어 이름입니다. 설정을 읽고 규칙을 매칭해 연결을 수립하는 역할을 하며, GUI 클라이언트는 구독 관리, 트레이 메뉴, 시스템 연동을 담당합니다. 코어 바이너리만 설치한다고 데스크톱 창이 자동으로 표시되거나 모든 Linux 프로그램이 프록시를 사용하게 되는 것은 아닙니다.

GNOME이나 KDE 같은 데스크톱 환경을 사용하고 노드를 자주 바꿔야 한다면 mihomo 코어가 포함된 클라이언트를 우선 고려하세요. SSH로 서버를 관리하며 터미널을 종료한 뒤에도 계속 실행하려면 독립 코어를 설치해 systemd로 관리하는 편이 적합합니다. 두 방식은 비슷한 YAML 설정을 사용할 수 있지만, 같은 수신 포트를 동시에 점유하지 않도록 주의하세요.

항목	데스크톱 클라이언트	독립 코어와 systemd
실행 환경	그래픽 데스크톱과 사용자 세션	systemd를 사용하는 호스트 또는 가상 머신
설정 방법	구독, 설정 및 연결 관리 화면	YAML 파일, 로그 및 제어 API
시작 방식	데스크톱 로그인 후 실행하거나 클라이언트 서비스 사용	시스템 부팅 시 서비스 시작
이 문서에서 다루는 범위	먼저 시스템 프록시 사용	먼저 로컬 7890 프록시 포트 제공

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

CPU 아키텍처와 설치 패키지 형식 확인

먼저 터미널에서 아래 두 명령을 실행하세요. x86_64는 보통 다운로드 항목의 x64 또는 amd64에 해당하고, aarch64는 arm64에 해당합니다. CPU 아키텍처와 배포판 패키지 형식은 별개의 조건입니다. DEB 패키지를 올바르게 골랐더라도 패키지에 맞는 CPU 아키텍처가 포함되어 있다는 뜻은 아닙니다.

uname -m
cat /etc/os-release

Debian·Ubuntu 계열: 배포판과 호환되는 DEB 패키지를 우선 선택하세요.
Fedora 계열: 해당 배포판에 맞는 RPM 패키지를 선택하고 패키지 관리자로 의존성을 설치하세요.
AppImage: 실행 권한이 필요하며, 바로 실행할 수 있는지는 시스템 라이브러리와 FUSE 지원 여부에도 달려 있습니다.

클라이언트 다운로드 페이지에서 Linux 설치 패키지를 선택할 수 있습니다. 아래 명령은 로컬 DEB 패키지의 이름을 clash-client.deb로 바꾸고 해당 디렉터리로 이동했다고 가정합니다. 이는 작업 예시이며 실제 배포 파일 이름이 아닙니다.

sudo apt install ./clash-client.deb

구독을 확인한 다음 시스템 프록시 활성화

클라이언트를 실행하고 구독 또는 설정 관리 화면에서 서비스 제공업체의 Clash YAML 구독을 가져오세요. 메뉴 이름은 클라이언트마다 다르므로 특정 프로그램의 메뉴 경로를 모든 클라이언트에 그대로 적용하면 안 됩니다.
가져온 설정을 선택하고 코어 시작 로그를 확인하세요. 노드 목록이 비어 있지 않다고 해서 규칙, 정책 그룹, DNS 설정이 모두 정상이라는 뜻은 아닙니다.
규칙 모드를 선택하고 정책 그룹에서 사용할 노드를 고른 다음, 클라이언트에 표시된 로컬 HTTP 또는 혼합 포트를 확인하세요.
클라이언트에서 시스템 프록시를 켠 뒤 브라우저로 대상 사이트에 접속하세요. 연결 목록도 확인해 트래픽이 예상한 정책 그룹으로 전달되는지 점검하세요.

GNOME 데스크톱에서는 「설정」→「네트워크」→「네트워크 프록시」에서 수동 방식을 선택하고 HTTP 및 HTTPS 프록시 주소를 127.0.0.1과 클라이언트의 실제 포트로 지정할 수도 있습니다. 여기서 설정하는 것은 로컬 HTTP 프록시 연결입니다. HTTPS 사이트는 보통 CONNECT 터널을 통해 접속하므로 프록시 주소를 임의로 HTTPS로 바꿀 필요가 없습니다.

시스템 프록시는 데스크톱 프록시 설정을 읽는 애플리케이션에서 주로 작동합니다. 터미널 프로그램, 컨테이너, 일부 게임은 해당 설정을 사용하지 않을 수 있습니다. 이런 프로그램에는 프록시를 명시적으로 지정하거나 앱별로 설정하세요. ‘시스템 프록시가 켜짐’을 ‘모든 기기 트래픽이 프록시를 통과함’과 같은 뜻으로 보면 안 됩니다.

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

프로젝트 배포 채널에서 CPU 아키텍처와 명령어 세트에 맞는 Linux 코어를 받아 압축을 푼 다음 실행 파일 이름을 mihomo로 바꾸세요. 아래 명령은 해당 파일이 있는 디렉터리에서 실행합니다. 구형 x86 프로세서는 빌드에 필요한 명령어 세트도 확인해야 합니다. 단순히 ‘64비트’라는 이유만으로 호환 여부를 판단할 수 없습니다.

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

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

시스템 계정 mihomo가 이미 있으면 계정 생성 단계를 건너뛰고 소속 그룹을 확인하세요. 배포판에 따라 nologin 경로가 다를 수 있으므로 먼저 command -v nologin을 실행해 확인할 수 있습니다. 설정 디렉터리는 root가 관리하고 실행 디렉터리는 서비스 계정이 쓰도록 설정하세요. 네트워크 서비스가 자체 설정 전체를 직접 수정하지 못하게 하기 위한 조치입니다.

최소 설정으로 실행 절차 확인

아래는 실행 여부를 확인하는 데 사용할 수 있는 직접 연결 설정입니다. 프록시 노드가 없으며 모든 요청은 마지막 규칙에 따라 직접 연결되므로 원격 프록시 작동 여부를 확인하는 데는 사용할 수 없습니다. 먼저 프로세스, 디렉터리 권한, 포트 수신을 확인한 다음 신뢰할 수 있는 출처의 전체 설정으로 바꾸세요. 이렇게 하면 문제를 더 쉽게 좁힐 수 있습니다.

sudo tee /etc/mihomo/config.yaml > /dev/null <<'YAML'
mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
ipv6: false

rules:
  - MATCH,DIRECT
YAML

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

mixed-port: 7890은 하나의 포트에서 HTTP와 SOCKS 프록시 연결을 모두 받습니다. -d는 작업 디렉터리를 지정하며 캐시 같은 실행 파일이 보통 이곳에 저장됩니다. -f는 기본 설정 파일의 위치를 명시합니다. 설정 검사가 통과했다는 것은 코어가 현재 설정을 읽고 불러올 수 있다는 뜻이지 모든 노드에 연결할 수 있다는 뜻은 아닙니다.

전체 구독 설정으로 바꾼 뒤 -t를 다시 실행하세요. 일부 설정은 GeoIP, GeoSite 또는 원격 규칙 세트를 참조하므로 처음 검사할 때 추가 파일을 받아야 할 수 있습니다. 서버에서 해당 주소에 접근할 수 없다면 설정 요구사항에 맞춰 리소스를 미리 준비하거나, 먼저 해당 리소스에 의존하지 않는 설정으로 실행 문제를 확인하세요.

systemd 서비스 작성: 시작, 로그, 자동 복구

아래 내용을 /etc/systemd/system/mihomo.service로 저장하세요. 이 서비스는 전용 계정으로 실행하며 일반 프록시 포트만 제공합니다. TUN 인터페이스 생성에 필요한 네트워크 관리 권한은 없습니다. 권한 범위를 이해하기 전에 root로 실행하도록 바꾸지 마세요.

[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
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

StateDirectory는 실행 데이터 디렉터리를 관리하고, ProtectSystem=strict는 서비스가 시스템 파일을 수정하지 못하게 제한하며, ReadWritePaths는 실행 디렉터리에 쓰기 권한을 유지합니다. 설정에서 홈 디렉터리의 인증서나 규칙 파일을 참조하면 ProtectHome=true 제한을 받습니다. 필요한 파일을 전용 디렉터리에 두고 읽기 전용 권한을 부여하세요. 보호 설정을 전부 해제하는 방식은 피해야 합니다.

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
sudo journalctl -u mihomo -b -n 80 --no-pager
sudo ss -lntp 'sport = :7890'

정상적으로 실행되면 서비스 상태가 active (running)으로 표시되고 로컬 7890 포트가 수신 대기해야 합니다. network-online.target은 시작 순서를 정하는 조건일 뿐, 그 시점에 구독 서버에 접속할 수 있다는 보장은 아닙니다. 네트워크 문제는 로그와 함께 확인하세요. 시작 실패가 반복되어 빈도 제한이 걸리면 문제를 해결한 뒤 sudo systemctl reset-failed mihomo를 실행하고 다시 시작할 수 있습니다.

설정 변경 후 따라야 할 순서

기존 설정을 백업한 뒤 /etc/mihomo/config.yaml을 편집하세요. 인증 정보가 포함된 파일을 공개 디렉터리에 두지 마세요.
서비스와 동일한 계정, 작업 디렉터리, -f 인수를 사용해 설정을 검사하세요.
검사가 통과하면 sudo systemctl restart mihomo를 실행한 다음 로그와 수신 포트를 확인하세요.

YAML만 수정한 경우 daemon-reload는 필요하지 않습니다. 서비스 유닛을 수정했을 때만 필요합니다. 이 문서에서는 ExecReload를 설정하지 않았으므로 systemctl reload mihomo로 업데이트할 수 있다고 가정하지 마세요.

프록시 적용 범위 확인: 터미널, 규칙, TUN

서비스를 시작해도 현재 셸에 환경 변수가 설정되지는 않습니다. 먼저 요청 하나에 프록시를 명시적으로 지정하면 ‘애플리케이션이 프록시를 사용하지 않음’과 ‘코어 전달 실패’를 구분하기 쉽습니다. 아래 요청은 연결과 HTTP 응답을 확인하기 위한 것이며 지연 시간이나 속도 측정용이 아닙니다.

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

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

socks5h를 사용하면 curl이 대상 도메인 이름을 프록시 쪽에서 확인하도록 전달합니다. 반면 socks5는 보통 클라이언트에서 먼저 도메인을 해석합니다. 이에 따라 DNS 경로가 달라질 수 있습니다. 최소 설정에서는 요청이 여전히 직접 연결됩니다. 노드와 정책 그룹이 포함된 설정으로 바꾼 뒤 연결 기록에서 적용된 규칙과 실제 출구를 확인하세요.

현재 터미널에서 해당 변수를 지원하는 프로그램에 프록시를 사용하려면 임시로 설정할 수 있습니다.

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

모든 프로그램이 같은 변수를 읽는 것은 아니며 systemd 서비스도 대화형 터미널의 export를 자동으로 상속하지 않습니다. 다른 백그라운드 서비스에 프록시가 필요하면 해당 서비스의 환경을 따로 설정하고 로컬 리소스 접근을 위한 제외 규칙도 검토하세요.

웹 대시보드 연결: 제어 포트는 루프백 주소에서만 수신

웹 대시보드는 제어 API용 프런트엔드이며 프록시 코어가 아닙니다. 7890은 프록시 트래픽을 전달하는 포트이고, 아래 예시의 9090은 코어를 관리하는 포트입니다. 두 포트의 역할은 다르므로 브라우저의 HTTP 프록시 설정에 9090을 입력하면 안 됩니다.

제어 키 생성 및 API 활성화

아래 명령을 사용하려면 시스템에 OpenSSL이 설치되어 있어야 하며, 현재 설정에 같은 이름의 external-controller 또는 secret 필드가 없어야 합니다. 명령을 실행하면 수신 주소와 무작위로 생성된 키가 설정 파일 끝에 추가됩니다. 이미 해당 필드가 있다면 중복 키가 생기지 않도록 기존 항목을 수정하세요.

sudo sh -c '
set -eu
key=$(openssl rand -hex 24)
printf "\nexternal-controller: 127.0.0.1:9090\nsecret: \"%s\"\n" "$key" >> /etc/mihomo/config.yaml
'

sudo -u mihomo /usr/local/bin/mihomo -t \
  -d /var/lib/mihomo -f /etc/mihomo/config.yaml
sudo systemctl restart mihomo
sudo ss -lntp 'sport = :9090'

키는 관리용 인증 정보이므로 공개 로그나 스크린샷에 노출하지 마세요. 대시보드 연결 설정에는 http://127.0.0.1:9090과 방금 생성한 키를 입력하세요. 루프백 주소에만 바인딩하더라도 호스트의 다른 로컬 프로세스가 이 포트에 접근할 수 있으므로 인증을 유지해야 합니다.

로컬 정적 대시보드 제공

현재 코어 API와 호환되는 대시보드 정적 빌드 파일을 받아 /var/lib/mihomo/ui에 압축을 푸세요. 해당 디렉터리 바로 아래에 index.html이 있어야 하며 mihomo 계정에 읽기 권한을 부여해야 합니다. 그런 다음 YAML 최상위에 아래 설정을 추가하고 검사를 통과하면 서비스를 재시작하세요.

external-ui: /var/lib/mihomo/ui

로컬 브라우저에서 http://127.0.0.1:9090/ui/에 접속하세요. 대시보드에서 백엔드 주소와 키를 입력하라고 하면 앞서 설정한 제어 API 정보를 사용하면 됩니다. 대시보드 소스 코드만 받고 빌드 결과물을 받지 않았거나 파일이 한 단계 더 중첩된 디렉터리에 있으면 페이지가 로드되지 않을 수 있습니다.

원격 서버에는 SSH 로컬 포트 포워딩을 우선 사용하세요. 아래 명령의 proxy-host는 로컬 SSH 설정에 등록된 서버 별칭입니다. 먼저 해당 별칭이 실제 호스트를 가리키도록 설정해야 합니다.

ssh -N -L 19090:127.0.0.1:9090 proxy-host

터널을 연결한 뒤 로컬에서 http://127.0.0.1:19090/ui/에 접속하고 대시보드 백엔드 주소에도 로컬 19090 주소를 입력하세요. 서버에서는 계속 루프백 주소만 수신하도록 유지하면 되며 제어 포트를 공개 인터넷에 열 필요가 없습니다. 터널은 API 키 인증을 대신하지 않으므로 두 보호 장치는 각각 적용됩니다.

자주 발생하는 문제: 아키텍처, 포트, 권한, 설정 순으로 확인

증상	확인 항목	해결 방법
Exec format error	`uname -m` 및 `file /usr/local/bin/mihomo`	아키텍처에 맞는 바이너리를 다시 선택하고 압축이 올바르게 풀렸는지 확인하세요.
Illegal instruction	CPU 명령어 세트와 릴리스 빌드 요구사항	구형 CPU와 호환되는 빌드를 선택하고 같은 파일을 반복해서 재시작하지 마세요.
address already in use	`sudo ss -lntp`	데스크톱 클라이언트나 이전 프로세스가 7890 또는 9090을 점유하고 있는지 확인하세요.
permission denied	파일 읽기 권한, 디렉터리 실행 권한, 서비스 샌드박스 확인	실행 계정을 기준으로 문제를 확인하고 모든 디렉터리 권한을 777로 바꾸지 마세요.
대시보드에 401 오류가 표시됨	대시보드 키와 YAML 설정이 일치하는지	연결 인증 정보를 갱신하고 다른 코어 인스턴스에 연결된 것은 아닌지 확인하세요.
브라우저는 되지만 명령줄은 실패함	터미널에서 프록시를 명시적으로 사용하고 있는지	curl의 `--proxy`로 먼저 따로 확인한 다음 애플리케이션 환경을 설정하세요.

데스크톱 클라이언트와 독립 서비스가 동시에 실행 중이라면 ‘어느 코어에 연결되어 있는지’도 확인해야 합니다. 두 인스턴스는 서로 다른 포트를 사용하면 함께 실행할 수 있지만, 클라이언트에서 선택한 노드는 다른 서비스의 정책을 자동으로 바꾸지 않습니다. 일상적으로 사용할 기본 인스턴스를 정해 두고, 잘못된 대시보드에서 설정을 변경하지 않도록 주의하세요.

배포가 완료됐는지는 네 단계로 확인하세요. 프로세스가 계속 실행되는지, 포트가 예상대로 수신하는지, 애플리케이션이 실제로 해당 포트를 사용하는지, 연결이 예상한 규칙과 노드를 적용하는지 확인하면 됩니다. 이 순서로 점검하면 TUN을 바로 전환하거나 방화벽을 끄고 반복해서 재설치하는 것보다 문제를 쉽게 찾을 수 있습니다. 설정 구조와 규칙 순서는 Clash 설정 안내에서 더 확인할 수 있습니다.