Linux에서 mihomo 실행하기: 데스크톱 클라이언트와 systemd 명령줄 설치 가이드
Linux용 Clash 데스크톱 클라이언트와 systemd 기반 mihomo 설치 방법을 비교하고, 실행 파일 위치부터 설정 디렉터리, 서비스 파일, 터미널 프록시 변수까지 안내합니다.
먼저 설치 방식 선택: 데스크톱 클라이언트 또는 독립 서비스
데스크톱 환경에서 전략 그룹을 자주 바꿔야 한다면 GUI가 있는 Clash 클라이언트를 사용하는 편이 좋습니다. SSH로 서버를 관리하거나 로그아웃 후에도 계속 실행해야 한다면 mihomo와 systemd를 선택하세요. mihomo는 Clash Meta 계열의 프록시 코어로, 완전한 데스크톱 인터페이스를 제공하지 않습니다. 코어 실행 파일을 내려받아도 GUI 클라이언트가 설치되는 것은 아닙니다.
| 비교 항목 | 데스크톱 클라이언트 | systemd 독립 서비스 |
|---|---|---|
| 일상적인 사용 | GUI에서 구독을 가져오고 전략을 선택 | YAML을 관리하고 서비스 로그 확인 |
| 설정 관리 방식 | 클라이언트에서 관리하는 설정 및 오버라이드 | 경로를 지정한 config.yaml |
| 실행 시점 | 일반적으로 데스크톱 로그인 시 실행. 클라이언트 설정에 따라 다름 | 시스템 서비스 활성화 후 부팅 시 실행 |
| 권장 환경 | 개인용 Linux 데스크톱 | 서버 및 상시 가동 호스트 |
데스크톱 방식: 설치, 설정 가져오기, 확인
아키텍처와 설치 패키지 확인
먼저 uname -m을 실행하세요. 일반적으로 x86_64는 amd64 아키텍처, aarch64는 arm64에 해당합니다. 둘 다 64비트라고 해서 서로 바꿔 사용할 수 있는 것은 아닙니다. Debian과 Ubuntu에서는 보통 클라이언트가 제공하는 DEB 패키지를, Fedora 등에서는 RPM 패키지를 선택합니다. AppImage에 추가 런타임 의존성이 필요한지는 해당 클라이언트 안내를 확인하세요.
클라이언트 다운로드 페이지에서 Linux를 선택한 다음 아키텍처와 패키지 형식을 확인하세요. 현재 디렉터리에 저장한 DEB 패키지를 설치하는 경우 파일 관리자에서 열거나 sudo apt install ./ 뒤에 실제 파일명을 입력하면 됩니다. 독립 코어 압축 파일을 DEB 패키지로 착각해 패키지 관리자에 전달하지 마세요.
기능별로 화면 확인
- 설정 화면: 구독 URL이나 로컬 YAML 파일을 가져온 뒤 사용할 설정으로 지정하세요. URL에 인증 정보가 포함될 수 있으므로 공개 로그에 붙여 넣지 마세요.
- 프록시 화면: 모드를 규칙 모드로 설정하고 규칙에서 참조하는 전략 그룹에 사용 가능한 프록시가 선택되어 있는지 확인하세요. 설정을 가져왔다고 해서 전략 그룹까지 올바르게 선택된 것은 아닙니다.
- 설정 화면: 실제 혼합 포트를 확인하고
7890인지 기록한 다음 필요에 따라 시스템 프록시를 활성화하세요. 클라이언트 버전에 따라 메뉴 이름이 ‘설정’ 또는 ‘네트워크 설정’으로 표시될 수 있습니다. - 로그 화면: 요청을 한 번 보내고 설정 파싱, 포트 바인딩 또는 상위 서버 연결 오류가 표시되는지 확인하세요. 시스템 트레이 아이콘만 보고 트래픽 경로를 판단하지 마세요.
데스크톱 시스템 프록시는 해당 설정을 읽는 프로그램에만 적용됩니다. 터미널의 curl, 일부 개발 도구와 백그라운드 서비스에는 적용되지 않을 수 있으므로 아래에서 터미널 환경 변수도 별도로 설정합니다. 데스크톱 방식을 선택했다면 확인 및 문제 해결 부분을 참고하세요. 독립 서비스 설치 단계는 다시 진행할 필요가 없습니다.
명령줄 방식: 실행 파일과 설정 디렉터리 고정
아래 명령은 systemd를 사용하는 Debian·Ubuntu 계열 시스템을 대상으로 하며, 현재 계정에 sudo 권한이 있다고 가정합니다. 컨테이너, 경량 배포판 또는 WSL 환경은 systemd를 초기화 시스템으로 사용하지 않을 수 있습니다. 먼저 ps -p 1 -o comm=을 실행하세요. 출력이 systemd가 아니면 서비스 관리 명령을 그대로 사용할 수 없습니다.
실행 파일 설치
프로젝트 릴리스 채널에서 아키텍처와 CPU 요구 사항에 맞는 Linux 코어 패키지를 받아 압축을 푼 다음, 실행 파일 이름을 mihomo로 바꾸어 현재 디렉터리에 둡니다. 아래 명령은 파일을 다운로드하지 않습니다. 설치 전에 현재 디렉터리의 파일이 실제로 사용할 코어인지 확인하세요.
uname -m
ps -p 1 -o comm=
sudo install -m 0755 ./mihomo /usr/local/bin/mihomo
/usr/local/bin/mihomo -v-v는 실제 설치된 버전을 표시합니다. 설정 필드의 호환성을 나중에 점검할 수 있도록 출력 결과를 배포 기록과 함께 보관하세요. 클라이언트 창에 표시된 버전으로 코어 버전을 추측하지 마세요.
전용 계정과 디렉터리 만들기
sudo useradd --system --user-group \
--home-dir /var/lib/mihomo \
--shell /usr/sbin/nologin mihomo
sudo install -d -m 0750 -o root -g mihomo /etc/mihomo
sudo install -d -m 0750 -o mihomo -g mihomo /var/lib/mihomo/usr/local/bin/mihomo: root가 관리하는 실행 파일입니다. 서비스 계정은 이 파일을 덮어쓸 수 없습니다./etc/mihomo/config.yaml: 관리자가 편집하는 기본 설정 파일입니다. 서비스 계정에는 읽기 권한만 있으면 됩니다./var/lib/mihomo: 캐시와 설정에 따라 저장할 리소스를 보관하는 런타임 데이터 디렉터리입니다.
계정 생성은 한 번만 실행하세요. 사용자가 이미 있다는 메시지가 나오면 삭제 후 다시 만들지 말고 기존 계정의 용도를 먼저 확인하세요. 설정에서 provider, 규칙 세트 또는 데이터베이스를 상대 경로로 참조한다면 -d로 지정한 데이터 디렉터리를 기준으로 실제 경로를 확인하세요. 경로가 항상 기본 설정 파일 기준이라고 가정하면 안 됩니다.
최소 설정으로 서비스 실행 여부 확인
처음 배포할 때는 실제 구독을 연결하기 전에 ‘프로그램 실행, 설정 파일 읽기, 포트 리슨’을 먼저 확인하세요. 아래는 시작 여부를 확인하기 위한 직접 연결 설정으로, 원격 프록시가 포함되어 있지 않습니다. 따라서 요청이 성공해도 로컬 프록시 진입점이 작동한다는 것만 확인할 수 있으며, 프록시 노드를 통해 접속했다는 뜻은 아닙니다.
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.yamlmixed-port는 하나의 포트에서 HTTP와 SOCKS 프록시 연결을 모두 받습니다. allow-lan: false는 서비스를 로컬에서만 사용할 수 있도록 제한합니다. mode: rule은 규칙 순서에 따라 연결을 처리하며, 이 예시의 마지막 MATCH,DIRECT는 모든 요청을 직접 연결합니다. -t는 설정을 검사하는 옵션으로, 서비스를 백그라운드에 계속 실행하지 않습니다.
실제 프록시 설정으로 바꿀 때 확인할 세 가지
- 구독 형식: 코어의
-f옵션은 설정 파일을 읽으며 구독 URL을 직접 받지 않습니다. 노드 목록만 있는 파일은 일반 설정 필드, 전략 그룹, 규칙이 포함된 완전한 설정과 다릅니다. - 참조 이름:
rules에서 참조하는 전략 그룹이 실제로 있어야 합니다. 전략 그룹에서 참조하는 노드나 provider도 정상적으로 확인할 수 있어야 합니다. - 리소스 권한: 다운로드하거나 업데이트할 provider와 규칙 세트는 서비스 계정에 쓰기 권한이 있는 데이터 디렉터리에 저장해야 합니다. 읽기 전용인
/etc/mihomo에 두지 마세요.
systemd 서비스 작성 및 부팅 시 자동 실행 설정
아래 내용을 /etc/systemd/system/mihomo.service로 저장하세요. 일반 전용 계정을 사용하는 서비스이며, 이 문서의 로컬 명시적 프록시 구성에 적합합니다. StateDirectory는 런타임 데이터 디렉터리를 관리하고, ProtectSystem=strict는 파일 시스템에 쓸 수 있는 범위를 제한합니다.
[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.targetsudo 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 -l
sudo journalctl -u mihomo.service -b -n 80 --no-pagerenable은 시스템 부팅 시 자동 실행을 설정하고, --now는 즉시 시작도 함께 수행합니다. network-online.target에서 실제로 대기하는 동작은 시스템의 네트워크 관리 서비스에 따라 다르며 모든 원격 주소에 연결할 수 있음을 보장하지 않습니다. 네트워크 리소스 다운로드에 실패하면 로그를 확인해 이름 확인, 연결 또는 권한 문제인지 판단하세요.
서비스 파일을 수정한 뒤에는 daemon-reload를 먼저 실행하고 서비스를 다시 시작해야 합니다. YAML만 수정했다면 앞서 안내한 -t 검사에 통과한 뒤 sudo systemctl restart mihomo.service를 실행하면 됩니다. 이 서비스에는 ExecReload가 정의되어 있지 않으므로 systemctl reload를 설정된 핫 리로드 기능으로 사용하지 마세요.
터미널 프록시: 명시적으로 테스트한 뒤 변수 설정
로컬 프록시 포트가 실제로 리슨 중인지 확인
sudo ss -lntp 'sport = :7890'
curl --noproxy "" --proxy http://127.0.0.1:7890 \
--connect-timeout 10 --max-time 30 \
-I https://clash03.com/첫 번째 명령으로 TCP 리슨 상태를 확인하세요. 로컬 주소는 127.0.0.1:7890이어야 하며, 모든 네트워크 인터페이스에 공개되는 0.0.0.0:7890이어서는 안 됩니다. 두 번째 명령은 기존 환경 변수가 테스트에 영향을 주지 않도록 프록시를 명시합니다. 지연 시간이나 외부 접속 위치를 보장하는 것은 아닙니다. 최소 직접 연결 설정을 사용하는 경우 트래픽은 대상 사이트에 직접 연결됩니다.
현재 셸에 프록시 설정
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 --connect-timeout 10 --max-time 30 -I https://clash03.com/https_proxy 값에 http://를 사용하는 것은 로컬 HTTP 프록시를 통해 HTTPS 연결을 만든다는 뜻이며, 로컬 프록시 진입점에 TLS가 필요하다는 의미는 아닙니다. 이 형식을 지원하는 프로그램에서 socks5h://는 대상 호스트명 확인을 SOCKS 프록시 측에 맡긴다는 뜻입니다. 프로그램이 http_proxy 또는 https_proxy를 우선해서 읽는다면 all_proxy를 사용하지 않을 수도 있습니다.
이 변수는 현재 셸과 그 뒤에 실행되는 하위 프로세스에만 적용됩니다. 이미 실행 중인 브라우저, 다른 로그인 세션 또는 시스템 서비스에는 자동으로 적용되지 않습니다. 설정을 유지하려면 사용하는 셸에 따라 ~/.bashrc 또는 ~/.zshrc에 추가하세요. 프로그램 하나를 위해 모든 시스템 서비스에 프록시 변수를 설정하지 마세요.
unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY변수를 해제하면 새로 실행하는 명령은 해당 변수에서 프록시 설정을 가져오지 않습니다. sudo는 기본적으로 환경 변수를 제거할 수 있으며, Git이나 패키지 관리자 등은 자체 프록시 설정을 사용할 수도 있습니다. ‘curl은 되는데 다른 명령은 안 되는’ 경우 노드를 바로 바꾸기보다 각 도구의 설정을 따로 확인하세요.
자주 발생하는 문제: 프로세스, 설정, 연결 순으로 점검
| 증상 | 우선 확인할 항목 | 해결 방법 |
|---|---|---|
| Exec format error | uname -m 출력과 바이너리 아키텍처 | 아키텍처에 맞는 빌드로 교체 |
| Illegal instruction | 빌드에 필요한 CPU 명령어 세트 | 프로젝트에서 제공하는 호환 빌드 선택 |
| address already in use | ss -lntp에 표시된 포트 사용 프로세스 | 중복 실행 중인 코어를 종료하거나 포트를 통일 |
| permission denied | 설정 읽기 권한 및 데이터 디렉터리 쓰기 권한 | 소유자, 경로 또는 보안 정책 수정 |
| 설정 검사는 통과했지만 요청이 실패 | 전략 그룹 선택, 상위 서버 연결 상태, 리소스 로드 로그 | 설정 문법이 올바른지와 실제 연결 가능 여부를 구분 |
서비스가 반복해서 재시작됨
로그가 계속 쌓이지 않도록 먼저 sudo systemctl stop mihomo.service를 실행하세요. 같은 서비스 계정으로 -t 검사를 수행한 다음 이번 시작 로그를 확인합니다. 실패 횟수가 systemd의 시작 제한에 도달했다면 원인을 수정한 뒤 sudo systemctl reset-failed mihomo.service를 실행하고 다시 시작하세요. YAML 오류를 감추려고 재시도 횟수만 늘리지 마세요.
서비스는 정상인데 터미널에서 연결할 수 없음
먼저 curl이 가리키는 주소와 mixed-port가 일치하는지 확인하세요. 포트를 7890에서 7891로 바꾸면 시스템 프록시, 터미널 변수, 애플리케이션 자체의 프록시 설정도 함께 변경해야 합니다. 다른 기기에서 연결할 때 127.0.0.1은 mihomo가 실행되는 호스트가 아니라 해당 기기 자신을 가리킵니다.
이 서비스는 TUN 사용 권한을 부여하지 않습니다
TUN은 가상 네트워크 장치와 라우팅을 통해 트래픽을 처리하며 HTTP 프록시 변수를 설정하는 것과는 다른 방식입니다. /dev/net/tun, 네트워크 관리 권한, 라우팅 및 DNS 설정이 필요합니다. 이 문서의 서비스에는 의도적으로 이러한 권한을 부여하지 않았습니다. tun.enable을 true로 바꾸는 것만으로 작동이 보장되지는 않습니다. TUN이 필요하다면 해당 클라이언트나 코어 문서를 바탕으로 권한과 라우팅을 별도로 설계하고 다른 VPN과 충돌하지 않는지 확인하세요.
업데이트 및 롤백: 실행 가능한 설정 유지
- 업데이트 전에
mihomo -v출력 결과를 기록하고 기본 설정과 현재 실행 파일을 백업하세요. 백업에 구독 정보가 포함되어 있다면 접근 권한을 제한하세요. - 새 실행 파일을 임시 위치에 먼저 두고 기존 설정에
-t검사를 실행하세요. 검사를 통과해도 설정을 파싱할 수 있다는 뜻일 뿐이므로 실제 시작 상태도 확인해야 합니다. - 서비스를 중지한 뒤 실행 파일을 교체하고 root 소유권과 실행 권한을 유지한 다음 서비스를 시작하세요.
systemctl is-active결과와 최근 로그, 명시적인 프록시 요청을 확인하세요. 문제가 있으면 이전 실행 파일과 원래 설정을 복원한 뒤 다시 시작합니다.
배포 완료 여부는 세 가지를 모두 확인해 판단해야 합니다. 서비스 상태가 정상이고, 로컬 포트가 예상대로 열려 있으며, 실제 요청이 예상한 정책을 따르는지 확인하세요. 데스크톱 클라이언트는 대화형 관리에, systemd는 경로를 고정해 장시간 실행하는 데 적합합니다. 어느 방식을 선택하든 설정 파일 위치, 프록시 진입점, 업데이트 방법을 명확히 해 여러 코어가 동시에 실행되면서 트래픽 경로를 파악하기 어려운 상황을 피하세요. 필드별 자세한 내용은 전체 설정 가이드를, 처음 설정을 가져오는 방법은 빠른 시작 가이드를 참고하세요.