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

배포 방식 선택: 데스크톱 클라이언트 또는 독립 실행형 코어

Linux에서 Clash 설정을 사용하는 방법은 크게 두 가지입니다. 데스크톱 환경에서는 GUI 클라이언트를 설치해 mihomo를 관리하고, 서버나 최소 환경에서는 mihomo를 직접 실행해 systemd로 프로세스를 관리합니다. mihomo는 프록시 코어이지 데스크톱 설정 창이 아닙니다. 바이너리만 시스템에 설치해도 시스템 프록시가 자동으로 켜지거나 모든 터미널 명령이 프록시를 거치는 것은 아닙니다.

사용 환경	권장 방식	관리할 항목
일상적인 데스크톱 사용, 설정을 자주 전환	GUI 클라이언트	설정 가져오기, 정책 그룹, 시스템 프록시 및 로그인 시 자동 실행
SSH 서버, CLI 도구	mihomo 및 systemd	설정 파일, 서비스 계정, 포트 및 터미널 환경 변수
프록시를 지원하지 않는 앱도 프록시로 연결해야 하는 경우	TUN 추가 설정	가상 네트워크 인터페이스, 권한, 라우팅 및 DNS

아래 명령은 systemd를 사용하는 Debian 12, Ubuntu 24.04 계열을 기준으로 하며, 로컬 루프백 주소 127.0.0.1과 혼합 포트 7890을 사용합니다. 먼저 ps -p 1 -o comm=을 실행해 PID 1이 systemd인지 확인하세요. 컨테이너, 일부 WSL 환경, OpenRC 시스템에는 서비스 관리 절차를 그대로 적용할 수 없습니다.

Linux 데스크톱: 클라이언트 설치 및 프록시 연결 확인

배포판과 CPU 아키텍처에 맞는 패키지 선택

클라이언트 다운로드 페이지에서 Linux 플랫폼을 선택하고 Clash Verge Rev, FlClash 등 클라이언트의 제공 패키지와 시스템 요구 사항을 확인하세요. Debian과 Ubuntu에서는 보통 DEB, Fedora 계열에서는 RPM을 선택합니다. ARM64 패키지를 x86_64 기기에 설치하지 않도록 먼저 아래 두 명령을 실행해 아키텍처를 확인하세요.

uname -m
cat /etc/os-release

x86_64는 보통 x64 또는 amd64, aarch64는 보통 arm64에 해당합니다.
DEB 또는 RPM 패키지는 데스크톱 소프트웨어 설치 프로그램으로 열 수 있습니다. 의존성 오류가 발생하면 배포판의 패키지 관리자로 해결하고, 다른 시스템 버전의 공유 라이브러리를 임의로 내려받지 마세요.
설치가 끝났는데 창이 열리지 않으면 터미널에서 클라이언트를 실행하고 오류 메시지를 확인하세요. 그래픽 라이브러리 누락과 프록시 설정 오류는 서로 다른 문제입니다.

설정을 먼저 가져온 다음 시스템 프록시 설정

클라이언트의 설정 또는 구독 메뉴에서 서비스 제공자가 준 호환 설정을 가져온 뒤 해당 설정을 선택하고, 연결 로그와 정책 그룹을 확인하세요. 메뉴 이름은 클라이언트마다 다를 수 있으니 실제 화면을 기준으로 진행합니다. 코어가 실행 중이고 7890 포트가 수신 대기 중인지 확인한 다음 클라이언트의 시스템 프록시를 켜세요.

수동 설정이 필요하다면 GNOME 데스크톱에서는 보통 「설정」→「네트워크」→「네트워크 프록시」→「수동」으로 이동합니다. HTTP와 HTTPS 프록시 모두 호스트에 127.0.0.1, 포트에 7890을 입력할 수 있습니다. 여기서 HTTPS는 HTTPS 요청이 사용할 프록시 연결을 뜻하며, 로컬 수신 포트에서 반드시 TLS를 활성화해야 한다는 의미는 아닙니다.

데스크톱 시스템 프록시는 해당 설정을 따르는 프로그램에 연결 정보를 제공합니다. 브라우저는 사용할 수 있지만 SSH, 일부 게임, 터미널 도구는 사용하지 않을 수 있습니다. 클라이언트를 종료하기 전에는 시스템 프록시를 꺼야 합니다. 그렇지 않으면 데스크톱이 이미 수신을 중단한 포트를 계속 가리켜 웹 페이지가 열리지 않을 수 있습니다.

CLI 설치: 바이너리·설정·데이터 경로 고정

실행 파일과 전용 계정 설치

mihomo 프로젝트의 배포 채널에서 기기 아키텍처와 명령어 세트에 맞는 Linux 코어를 내려받으세요. 압축을 푼 뒤 실행 파일 이름을 mihomo로 지정해 현재 디렉터리에 둡니다. 압축 파일을 풀지 않은 채 실행 파일로 설치하지 마세요. 아래에서 먼저 아키텍처와 버전을 확인한 다음 코어를 고정 경로에 설치합니다.

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

getent group mihomo >/dev/null || sudo groupadd --system mihomo
id mihomo >/dev/null 2>&1 || sudo useradd \
  --system --gid mihomo --home-dir /var/lib/mihomo \
  --no-create-home --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

이 예시에서는 설정 파일을 /etc/mihomo/config.yaml에, 실행 데이터를 /var/lib/mihomo에 둡니다. 관리자가 설정을 관리하고 서비스 계정은 읽기만 할 수 있도록 합니다. 캐시와 규칙 리소스는 데이터 디렉터리에 기록합니다. 실행 당시의 현재 디렉터리에 의존하지 말고, SSH 사용자 계정의 ~/.config가 시스템 서비스의 설정 경로로 자동 사용된다고 가정하지 마세요.

최소 설정으로 수신 상태 확인

아래 설정은 서비스와 로컬 포트를 확인하기 위한 것으로, 모든 요청을 직접 연결하며 프록시 노드는 포함하지 않습니다. 실제 구독을 대신할 수 없습니다. 기존 설정이 있다면 명령 실행으로 덮어쓰지 않도록 먼저 백업하세요. 최소 설정을 사용하면 구독 형식, 원격 규칙 다운로드, 노드 연결 상태로 인한 영향을 잠시 배제할 수 있습니다.

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

-t는 설정을 테스트하고, -d는 작업 데이터 디렉터리를 지정하며, -f는 설정 파일을 지정합니다. 실제 설정으로 바꾼 뒤에도 다시 테스트해야 합니다. 구문 검사를 통과해도 노드 연결이나 원격 규칙 다운로드가 보장되는 것은 아니므로 시작 로그도 함께 확인하세요.

구독 URL이 Base64 노드 목록, 웹 페이지 또는 로그인 안내를 반환한다면 mihomo 기본 설정 파일로 바로 저장할 수 없습니다. 호환되는 전체 YAML을 받거나 기본 설정에 맞는 형식으로 proxy-providers를 설정하세요. 구독 링크에는 접근 자격 증명이 포함되는 경우가 많으므로 공개 로그나 스크린샷에 노출하지 마세요.

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

시스템 수준의 unit 파일을 만듭니다. 이 예시는 전용 일반 사용자 계정으로 실행하고 로컬 HTTP/SOCKS 혼합 프록시만 제공합니다. TUN은 활성화하지 않으므로 코어를 계속 root 권한으로 실행할 필요가 없습니다.

sudo tee /etc/systemd/system/mihomo.service >/dev/null <<'UNIT'
[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=5s
LimitNOFILE=65536
UMask=0077

[Install]
WantedBy=multi-user.target
UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service
systemctl status mihomo.service --no-pager
sudo journalctl -u mihomo.service -n 80 --no-pager
sudo ss -lntup | grep ':7890'

enable --now는 부팅 시 자동 시작을 설정하고 서비스를 즉시 시작합니다. enable만 실행하면 서비스가 바로 시작되지는 않습니다.
Restart=on-failure는 비정상 종료 시 다시 실행하지만, 서비스를 직접 중지한 경우에는 강제로 재시작하지 않습니다.
network-online.target에서 실제로 얼마나 기다릴지는 시스템의 네트워크 관리 구성 요소에 따라 달라지며, 원격 구독 서버에 연결할 수 있음을 보장하지 않습니다.
서비스 상태가 active (running)으로 표시되더라도 수신 주소가 127.0.0.1:7890인지 확인하세요. 모든 네트워크 인터페이스에 의도치 않게 노출되어서는 안 됩니다.

설정 파일 변경과 unit 변경은 처리 방법이 다릅니다

YAML을 수정한 뒤에는 동일한 서비스 계정으로 설정을 테스트하고 서비스를 재시작하세요. 이 문서의 unit에는 ExecReload가 정의되어 있지 않으므로 systemctl reload를 일반적인 설정 갱신 방법으로 사용하지 마세요. 재시작하는 동안 기존 프록시 연결이 잠시 끊깁니다.

sudo -u mihomo /usr/local/bin/mihomo -t \
  -d /var/lib/mihomo -f /etc/mihomo/config.yaml
sudo systemctl restart mihomo.service
sudo journalctl -u mihomo.service -n 40 --no-pager

/etc/systemd/system/mihomo.service 또는 관련 drop-in을 수정한 경우에만 먼저 sudo systemctl daemon-reload를 실행하면 됩니다. 코어를 업데이트하기 전에는 기존 바이너리와 설정을 백업하세요. 서비스를 중지한 뒤 파일을 교체하고 mihomo -v와 설정 테스트 결과를 확인한 다음 서비스를 시작합니다.

터미널 프록시: 환경 변수는 이를 읽는 프로그램에만 적용

mihomo가 7890 포트에서 수신 대기 중이면 현재 터미널에서 다음 변수를 설정하세요. 이 변수를 지원하는 대부분의 HTTP 도구가 프록시를 사용하지만, Linux 네트워크 전체를 투명하게 프록시 처리하는 방법은 아닙니다.

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 https://example.com
curl -I --proxy http://127.0.0.1:7890 https://example.com
curl -I --proxy socks5h://127.0.0.1:7890 https://example.com

socks5h는 대상 도메인 이름을 프록시 서버에서 조회하고, socks5는 보통 로컬에서 먼저 조회한다는 뜻입니다. 위의 https_proxy도 http://를 사용합니다. 로컬 HTTP 프록시 주소를 나타내기 때문이며, HTTPS 대상에는 일반적으로 CONNECT 터널을 사용합니다.

최소 직접 연결 설정에서 프록시를 명시한 요청이 성공해도, 해당 프로그램이 로컬 코어를 통해 대상에 접속할 수 있다는 점만 확인한 것입니다. 원격 프록시 노드를 검증하려면 유효한 설정으로 바꾸고 정책 그룹에서 노드를 선택한 뒤 연결 로그에서 실제 규칙과 아웃바운드를 확인하세요.

환경 변수 유지 및 해제

Bash 터미널을 열 때마다 적용하려면 위의 export 행을 ~/.bashrc에 추가하세요. Zsh에서는 보통 ~/.zshrc를 사용합니다. GUI 앱, 예약 작업, systemd 서비스는 대화형 셸 설정을 자동으로 읽지 않으므로 이 설정만으로 해당 프로그램에도 프록시가 적용된다고 판단할 수 없습니다.

unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

sudo는 기본적으로 프록시 환경 변수를 제거할 수 있으며, APT에도 별도의 프록시 설정이 있을 수 있습니다. 일회성 다운로드를 위해 사용자 환경 전체를 관리자 권한 프로세스에 무차별 전달하지 마세요. curl을 한 번 테스트할 때는 명시적인 --proxy 옵션을 사용하고, 환경 변수를 지원하지 않는 앱은 자체 프록시 설정을 확인하세요.

자주 발생하는 문제: 설정, 권한, 포트, 라우팅 순으로 확인

서비스가 시작 직후 종료됨: 서비스 계정의 설정 파일 접근 권한부터 확인

sudo journalctl -u mihomo.service -b -n 100 --no-pager
namei -l /etc/mihomo/config.yaml
sudo -u mihomo test -r /etc/mihomo/config.yaml && echo readable
sudo -u mihomo test -w /var/lib/mihomo && echo writable

permission denied는 설정 파일 자체의 문제만을 뜻하지 않습니다. 상위 디렉터리에 접근 권한이 없거나 원격 규칙 파일이 서비스 계정에 쓰기 권한이 없는 경로를 가리킬 수도 있습니다. 대상 디렉터리의 소유자와 최소 권한을 바로잡고 chmod -R 777로 문제를 덮지 마세요. SELinux를 사용하는 시스템에서는 관련 거부 로그도 확인하고, 보안 기능을 직접 끄지 않는 것이 좋습니다.

7890 포트가 이미 사용 중임: 코어가 두 개 실행 중인지 먼저 확인

sudo ss -lntp 'sport = :7890'
pgrep -a mihomo

데스크톱 클라이언트, 수동으로 실행한 코어, systemd 서비스가 동시에 실행 중일 수 있습니다. 프로세스의 실행 주체를 확인한 뒤 불필요한 프로세스만 중지하고, 이름이 같은 프로세스를 전부 종료하지 마세요. 포트를 7891로 바꾸려면 mixed-port, 데스크톱 프록시, 터미널 변수도 함께 수정한 뒤 재시작하고 수신 상태를 다시 확인하세요.

서비스는 정상인데 요청 실패: 연결 진입점과 아웃바운드 문제 구분

Connection refused: 포트가 수신 대기 중이 아니거나 프로세스가 종료됐거나 주소가 잘못된 경우가 많습니다. 먼저 ss로 확인하고 규칙은 아직 변경하지 마세요.
프록시 연결 후 시간 초과: 코어 로그에서 노드 연결, 도메인 조회, 규칙 리소스 오류를 확인하세요. 규칙이 일치해도 아웃바운드 경로가 정상이라는 뜻은 아닙니다.
인증서 오류: 시스템 시간, CA 인증서, 대상 도메인을 확인하세요. TLS 검증 비활성화를 장기적인 해결책으로 사용하지 마세요.
시작 실패가 반복된 뒤 재시도되지 않음: 원인을 해결한 다음 sudo systemctl reset-failed mihomo.service를 실행하고 서비스를 다시 시작하세요.

TUN 사용 시 권한, DNS, 원격 접속 위험을 별도로 고려

이 예시의 일반 사용자 서비스는 완전한 TUN 배포에 그대로 사용할 수 없습니다. Linux TUN에는 보통 /dev/net/tun 접근 권한이 필요하고, 가상 인터페이스와 라우팅 설정에도 적절한 네트워크 관리 권한이 필요합니다. 관련 권한, 서비스 제한, DNS 가로채기 방안을 함께 설계해야 하며 YAML에 enable: true 한 줄만 추가하면 되는 것이 아닙니다.

특히 SSH 서버에서는 자동 라우팅을 켜기 전에 두 번째 관리 세션이나 콘솔 접속 경로를 확보하고, SSH 응답 트래픽, LAN 대역, 내부 DNS의 경로를 명확히 하세요. 먼저 로컬 7890 포트를 지정한 프록시 요청으로 확인한 뒤 TUN을 도입합니다. 포트, DNS, 기본 라우트를 한꺼번에 변경하면 접속이 끊긴 원인을 찾기 어렵습니다.

설정 관리: 복구 경로를 남기고 업데이트 대상을 구분

배포 후에는 바이너리 경로, 설정 경로, 데이터 디렉터리, 수신 포트, 서비스 이름을 기록하세요. 구독 업데이트, 코어 업데이트, 클라이언트 업데이트는 서로 별개의 작업입니다. 코어를 교체해도 노드가 자동 갱신되지 않으며, systemd의 자동 시작이 기본 설정을 자동으로 새로 고치지도 않습니다.

GUI 클라이언트를 사용하는 경우 설정 화면에서 자동 업데이트 여부와 주기를 확인하고, 업데이트 후 실제 적용된 설정도 점검하세요.
독립 코어에서 proxy-providers의 업데이트 주기는 해당 provider에만 적용되며 기본 YAML 전체를 주기적으로 교체하는 기능은 아닙니다.
기본 설정을 자동으로 내려받으려면 안전한 다운로드, 테스트, 교체 및 실패 시 복구 절차를 직접 설계해야 합니다. 테스트하지 않은 응답으로 실행 중인 설정 파일을 바로 덮어쓰지 마세요.
시스템 서비스를 더 이상 사용하지 않는다면 sudo systemctl disable --now mihomo.service를 실행하고 터미널 변수와 데스크톱 프록시 설정도 해제하세요.

일상적인 데스크톱 사용에는 GUI 클라이언트가 편리하고, 무인 환경에는 고정 경로와 systemd 서비스가 적합합니다. 어느 방식을 택하든 설정을 읽는 위치, 프로그램이 수신하는 포트, 앱이 연결하는 경로부터 확인한 뒤 규칙 분기와 TUN을 하나씩 추가하세요. 설정 개념은 프로토콜 레퍼런스에서, 작업 절차는 설정 가이드에서 확인할 수 있습니다.