Linux에 mihomo 설치하기: 데스크톱 클라이언트와 systemd 서비스 설정

먼저 실행 방식을 선택하세요: 데스크톱 관리 또는 독립 서비스

Linux 데스크톱에서 노드를 바꾸거나 구독을 관리하려면 GUI 클라이언트를 사용하는 것이 편리합니다. 데스크톱이 없는 서버에서 계속 실행하거나 로그인 전부터 프록시를 사용하려면 mihomo 커널을 systemd 독립 서비스로 실행하세요. 두 방식은 규칙과 설정의 개념은 공유하지만 설정 디렉터리, 업데이트 방법, 권한이 서로 다릅니다. 클라이언트의 시작 프로그램 설정과 시스템 서비스는 같은 기능이 아닙니다.

mihomo는 네트워크 처리 커널이며 Clash Meta 커널이라고도 합니다. GUI 클라이언트는 설정 관리와 화면, 시스템 연동을 담당합니다. 커널을 설치해도 트레이 아이콘이 생기거나 GNOME 프록시 설정이 바뀌지 않으며, 모든 명령줄 프로그램이 자동으로 프록시를 사용하는 것도 아닙니다. 먼저 로컬 127.0.0.1:7890에서만 연결을 받는 프록시를 구성한 뒤, 앱이 해당 포트에 실제로 연결되는지 확인합니다.

항목	GUI 클라이언트	systemd 독립 커널
사용 환경	데스크톱 조작, 구독 관리, 노드 전환	서버, 고정 설정, 백그라운드 상시 실행
시작 시점	일반적으로 사용자 로그인 후 시작	시스템 부팅 단계부터 실행 가능
설정 출처	클라이언트 설정 화면 및 구독 덮어쓰기	직접 지정한 YAML 파일
로그 확인 위치	클라이언트 로그 화면	`journalctl -u mihomo`
기본 권한	일반 사용자 권한; TUN은 별도 권한 필요	이 문서에서는 전용 일반 서비스 사용자 사용

Ubuntu·Debian·Arch에 데스크톱 클라이언트 설치

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

먼저 아래 두 명령을 실행하세요. x86_64는 일반적으로 x64 또는 amd64 패키지, aarch64는 보통 arm64 패키지에 해당합니다. Ubuntu와 Debian에서는 배포판에 맞는 DEB를 우선 선택하세요. Arch에는 DEB나 RPM을 직접 설치하지 않습니다. 클라이언트 실행 여부는 CPU 아키텍처뿐 아니라 시스템 라이브러리와 데스크톱 환경에도 영향을 받습니다.

uname -m
cat /etc/os-release

클라이언트 다운로드 페이지에서 Linux 패키지와 유지보수 상태를 확인하세요. Clash Verge Rev, FlClash 등 클라이언트별 실제 배포 지원도 비교할 수 있습니다. 이 문서에서는 특정 클라이언트 버전을 지정하지 않습니다. 설치 후 ‘정보’ 화면에서 클라이언트 버전을, 로그나 커널 정보 화면에서 커널 버전을 확인해 기록해 두면 문제를 재현하기 쉽습니다.

Ubuntu / Debian: 시스템에 맞는 DEB를 다운로드한 뒤 로컬 파일 이름을 client.deb로 바꾸고 sudo apt install ./client.deb를 실행합니다. 여기서 사용하는 파일명은 로컬에서 임의로 정한 것으로, 실제 패키지 이름이 아닙니다.
Arch: Arch에 맞는 방식 중 유지관리자가 제공하는 설치 방법을 선택하세요. AUR을 이용한다면 PKGBUILD와 다운로드 출처를 먼저 확인하세요. AUR 패키지는 커뮤니티에서 관리하며 공식 저장소 패키지와는 다릅니다. 설치 패키지에 맞추려고 다른 배포판의 시스템 라이브러리를 섞어 사용하지 마세요.
포터블 패키지: 배포처에서 AppImage를 제공한다면 실행 권한을 부여한 뒤 실행하세요. FUSE 또는 그래픽 라이브러리 오류가 발생하면 해당 패키지 안내에 따라 필요한 의존성을 설치하세요. 오류를 피하려고 그래픽 인터페이스를 root 권한으로 실행하지 마세요.

설정을 가져온 뒤 로컬 포트부터 확인

클라이언트의 ‘설정’ 화면에서 mihomo 호환 YAML 파일이나 구독을 가져오고 현재 활성화된 설정을 확인하세요. 구독 URL에는 보통 접근 정보가 포함되므로 공개 로그에 붙여 넣지 마세요.
‘설정’에서 실제 HTTP, SOCKS 또는 혼합 포트를 확인하세요. 이 문서에서는 혼합 포트 7890을 예시로 사용합니다. 클라이언트의 기본 포트는 다를 수 있으니 명령어도 실제 설정에 맞게 바꾸세요.
먼저 TUN을 끄고 테스트할 프록시 포트만 활성화하세요. 로그에서 설정이 정상적으로 불러와졌는지 확인한 다음, 아래의 프록시 지정 명령으로 연결을 검증합니다.
데스크톱 앱에서 프록시를 사용하려면 클라이언트의 ‘시스템 프록시’를 활성화하세요. GNOME에서는 ‘설정’ → ‘네트워크’ → ‘네트워크 프록시’ → ‘수동’에서 주소와 포트를 확인할 수 있습니다. 데스크톱 환경에 따라 메뉴 경로는 다릅니다.

데스크톱 클라이언트의 ‘시작 시 실행’은 일반적으로 사용자 세션에 종속됩니다. 로그인하지 않아도 실행되도록 하려면 아래의 systemd 방식을 사용하고, 데스크톱 커널의 자동 시작은 함께 활성화하지 마세요. 클라이언트를 종료하기 전에 시스템 프록시 설정이 해제됐는지도 확인하세요. 그렇지 않으면 꺼진 포트로 계속 연결할 수 있습니다.

독립 mihomo 서비스: 디렉터리와 최소 설정 준비

실행 파일 설치 및 전용 사용자 생성

커널 배포처에서 시스템 아키텍처에 맞는 Linux 바이너리를 받아 패키지 형식에 따라 압축을 푼 다음, 실행 파일 이름을 mihomo로 지정하세요. 아래 명령은 현재 디렉터리에 있는 이 파일을 설치하며, 원격 패키지의 이름은 가정하지 않습니다. 먼저 버전 정보가 출력되는지 확인한 뒤 서비스를 설정하세요.

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

sudo useradd --system --user-group --no-create-home \
  --home-dir /var/lib/mihomo --shell /bin/false mihomo
sudo install -d -o root -g mihomo -m 0750 /etc/mihomo
sudo install -d -o mihomo -g mihomo -m 0750 /var/lib/mihomo

전용 사용자가 이미 있다면 다시 만들지 말고 id mihomo로 계정과 그룹을 확인하세요. 바이너리는 root가 관리하고 실행 데이터는 서비스 사용자가 소유하도록 합니다. 설정 디렉터리에는 root와 mihomo 그룹만 접근할 수 있게 하세요. 구독 정보에는 노드 비밀번호가 포함될 수 있으므로 모든 사용자가 읽을 수 있는 디렉터리에 두지 않는 것이 안전합니다.

경로	용도	권장 권한
`/usr/local/bin/mihomo`	커널 실행 파일	root 관리, 0755
`/etc/mihomo/config.yaml`	기본 설정 및 노드 매개변수	root:mihomo，0640
`/var/lib/mihomo`	캐시, 규칙 provider 및 실행 데이터	mihomo:mihomo，0750
`/etc/systemd/system/mihomo.service`	서비스 정의 파일	root 관리, 0644

먼저 직접 연결 설정으로 서비스를 검증하세요. 이 설정을 노드 설정으로 사용하지 마세요.

sudoedit /etc/mihomo/config.yaml를 실행하고 아래 설정을 입력하세요. 이 설정은 로컬 혼합 프록시만 열며 모든 요청은 직접 연결됩니다. 설치와 권한, 포트 바인딩 문제를 따로 확인하기 위한 용도입니다. 프록시 노드가 없으면 서비스가 실행되더라도 원격 프록시를 사용할 수 있는 것은 아닙니다.

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

tun:
  enable: false

rules:
  - MATCH,DIRECT

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

-f는 기본 설정 파일을, -d는 데이터 디렉터리를 지정하며 -t는 설정을 검사합니다. 검사를 통과하면 설정을 불러올 수 있다는 뜻일 뿐, 원격 노드 연결까지 보장하지는 않습니다. 실제 구독 설정을 사용한다면 정책 그룹 이름, 규칙 참조, provider 경로도 확인하세요. 상대 경로로 지정하는 실행 데이터는 쓰기 가능한 데이터 디렉터리에 일관되게 배치하고 데스크톱 사용자의 개인 디렉터리를 가리키지 않도록 합니다.

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

sudoedit /etc/systemd/system/mihomo.service를 실행하고 아래 서비스 정의 전체를 입력하세요. 이 설정은 TUN을 사용하지 않고 53번 등 1024 미만의 포트에 바인딩하지 않는 일반 로컬 프록시용입니다. 작업 디렉터리는 쓰기 가능한 디렉터리와 동일하게 지정하고 설정 파일은 읽기 전용으로 유지합니다.

[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=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target

network-online.target의 동작은 시스템에서 관련 네트워크 대기 서비스가 활성화되어 있는지에 따라 다릅니다. 이 설정만으로 원격 구독에 반드시 접속할 수 있는 것은 아닙니다. 처음 실행할 때 규칙이나 지리 데이터 다운로드가 필요하다면 로그에서 완료 여부를 확인하세요. 부팅 시 네트워크에 연결되지 않는 환경에서는 설정에 필요한 데이터를 미리 준비해야 합니다.

sudo systemd-analyze verify /etc/systemd/system/mihomo.service
sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service
systemctl status mihomo.service --no-pager
sudo journalctl -u mihomo.service -b -n 80 --no-pager
ss -lntp 'sport = :7890'

enable --now는 부팅 시 자동 실행을 설정하고 서비스를 즉시 시작합니다. enable만 실행하면 프로세스가 바로 시작되지는 않습니다.
정상 상태는 active (running)으로 표시되고 포트 확인 결과에는 로컬 7890 포트의 수신 기록이 나타나야 합니다. 일반 사용자로 ss를 실행하면 다른 사용자의 프로세스 이름이 보이지 않을 수 있습니다.
설정을 변경한 뒤 먼저 -t로 다시 검사하고 sudo systemctl restart mihomo를 실행하세요. YAML 파일만 수정한 경우 daemon-reload는 필요하지 않습니다. 서비스 파일을 수정했을 때만 실행하면 됩니다.
서비스를 일시 중지하려면 sudo systemctl stop mihomo를 실행하세요. 부팅 시 자동 실행도 해제하려면 sudo systemctl disable --now mihomo를 실행합니다.

이 문서의 서비스 정의에는 ExecReload가 없으므로 systemctl reload로 재시작을 대신하지 마세요. 외부 컨트롤러를 연결해 설정을 실시간으로 불러오려면 인증과 수신 범위를 별도로 설계해야 합니다. 기본 서비스에서는 관리 화면을 위해 제어 포트를 개방할 필요가 없습니다.

프록시 연결 확인: 포트, 요청, 규칙을 각각 점검

먼저 프록시를 직접 지정하고 환경 변수를 확인하세요

아래 두 명령은 각각 HTTP 프록시와 SOCKS5 프록시 연결을 확인합니다. --noproxy ""는 이번 요청의 우회 목록을 비워 기존 NO_PROXY 설정 때문에 프록시를 건너뛰는 일을 방지합니다. SOCKS 예시에서는 socks5h를 사용해 대상 도메인 이름도 프록시에서 조회합니다.

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

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

HTTP 응답이 돌아오면 해당 요청은 완료된 것입니다. 다만 실제로 적용된 규칙은 커널 로그와 함께 확인해야 합니다. 최소 설정에서는 직접 연결로 표시됩니다. 실제 노드를 설정한 뒤에는 예상한 정책 그룹이 적용됐는지, 해당 그룹에서 어떤 노드를 선택했는지 확인하세요. 지연 시간 테스트에 성공해도 실제 HTTPS 요청을 확인하는 과정을 대신할 수 없습니다.

프록시를 직접 지정한 요청은 성공하지만 일반 터미널 명령이 프록시를 사용하지 않는다면 현재 셸에만 환경 변수를 임시로 설정하세요. 프로그램마다 지원하는 변수 이름이 다릅니다. 아래 방법은 일반적인 명령줄 도구에 적합하며 모든 프로그램의 연결을 전역으로 프록시 처리하지는 않습니다.

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

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

unset http_proxy https_proxy all_proxy no_proxy

https_proxy 값에 http://를 사용해도 문제없습니다. HTTP 프록시의 CONNECT 터널을 통해 HTTPS 대상에 접속한다는 뜻입니다. 셸 설정 파일에 추가했다면 서비스를 끈 뒤 변수도 제거하세요. 브라우저, APT, systemd로 실행되는 다른 서비스는 해당 변수를 상속하지 않을 수 있으므로 각 앱에서 별도로 설정해야 합니다.

오류 유형별 문제 해결

Connection refused: 먼저 7890 포트가 수신 중인지 확인하고 포트 번호와 서비스 상태를 점검하세요. 이 단계에서는 노드부터 바꿀 필요가 없습니다.
address already in use: 데스크톱 클라이언트나 이전 커널 프로세스가 포트를 사용 중인지 확인하고 프록시 진입점 하나만 남기세요.
permission denied: 파일과 상위 디렉터리의 권한을 확인하고 서비스 사용자로 설정 검사를 실행하세요. chmod 777로 원인을 덮지 마세요.
규칙 또는 데이터 다운로드 실패: provider 주소, 데이터 디렉터리의 쓰기 권한, 시작 시 네트워크 연결을 확인하세요. 먼저 오류 전후의 로그를 보존한 뒤 DNS 문제인지 판단합니다.
서비스가 반복해서 재시작됨: journalctl에서 가장 먼저 발생한 설정 또는 리소스 오류를 찾으세요. 문제를 해결한 뒤 시작 제한에 걸렸다면 sudo systemctl reset-failed mihomo를 실행하고 서비스를 다시 시작할 수 있습니다.

TUN 및 업데이트 관리: 권한 범위 유지

TUN은 enable을 true로 바꾸는 것만으로 설정되지 않습니다

TUN을 사용하려면 /dev/net/tun에 접근해야 하며, 인터페이스 생성, 라우팅 조정, DNS 연결 처리를 위한 네트워크 관리 권한도 필요한 경우가 많습니다. ls -l /dev/net/tun으로 장치 파일이 있는지 확인할 수 있지만 현재 서비스에 필요한 권한이 부여됐는지는 알 수 없습니다. 이 문서의 일반 사용자 서비스에는 해당 권한을 의도적으로 부여하지 않았으므로 TUN에 바로 사용할 수 없습니다.

TUN이 필요하다면 먼저 클라이언트에서 제공하는 권한 부여 서비스를 이용하거나, 사용 중인 mihomo 버전의 안내에 따라 systemd 권한과 capability 제한을 다시 설계하세요. 서비스 사용자를 root로 바꾸고 나머지 설정을 그대로 적용하는 방식은 피해야 합니다. 다른 트래픽 처리 기능을 먼저 끄고 DNS 수신 포트, 라우팅 범위, LAN 트래픽 처리 여부를 정한 다음, 내부망 접속과 서비스 종료 후 경로 복구를 확인하세요.

업데이트 전 버전을 기록하고 업데이트 후 다시 검증

/usr/local/bin/mihomo -v 출력을 기록하고 현재 바이너리와 설정 파일을 백업하세요. 백업한 설정 파일에도 제한된 접근 권한을 유지합니다.
아키텍처에 맞는 새 커널을 다운로드한 뒤 새 파일의 -v와 -t를 먼저 실행하세요. 검사할 때는 서비스 사용자와 동일한 데이터 디렉터리를 사용합니다.
서비스를 중지한 뒤 install -m 0755로 바이너리를 교체하고 서비스를 다시 시작하세요. 실행 중인 파일을 직접 덮어쓰지 마세요.
로그, 7890 포트 수신 여부, HTTPS 요청을 다시 확인하세요. 새 버전에서 호환성 문제가 발생하면 서비스를 중지하고 이전 바이너리와 설정을 복원한 뒤 다시 시작합니다.

최종 점검은 세 가지로 나눠 확인하세요. systemd가 프로세스를 안정적으로 관리하는지, 로컬 앱이 프록시 포트에 연결되는지, 실제 요청에 올바른 규칙과 노드가 적용되는지 확인합니다. 세 항목이 모두 충족돼야 설치가 완료된 것입니다. 기본 설정은 사용 가이드에서 확인하세요. 브라우저와 터미널의 결과가 다르다면 문제 해결 안내에 따라 앱의 프록시 설정을 확인합니다.