플랫폼 배포 예상 읽기 시간 12분

Linux에 Clash 코어 설치하기: mihomo CLI 배포 및 systemd 서비스 설정

Linux 데스크톱용 GUI 클라이언트부터 헤드리스 서버까지, mihomo 설치와 설정 디렉터리 구성, systemd 서비스 등록, 터미널 프록시 설정을 안내합니다.

사용 환경에 따라 선택: 데스크톱 클라이언트 또는 독립 실행형 코어

데스크톱 환경이라면 GUI 클라이언트로 구독, 정책 그룹, 연결 기록을 관리하는 편이 좋습니다. SSH 터미널만 사용할 수 있는 서버에서는 mihomo CLI와 systemd를 이용하세요. mihomo는 흔히 Clash Meta 코어라고 불리며, 설정을 읽고 프록시 포트를 열어 트래픽을 분류합니다. GUI 클라이언트는 코어 위에 조작 화면을 제공하므로 둘은 서로 다른 계층입니다.

실행 환경권장 방식주요 관리 방법
Ubuntu, Fedora 등 데스크톱 환경Linux를 지원하는 GUI 클라이언트클라이언트의 설정·프록시·연결 화면
Debian, Ubuntu 등 서버mihomo와 systemd 시스템 서비스설정 파일, systemctl, journalctl
OpenRC 또는 경량 컨테이너 환경기존 프로세스 관리 방식에 맞춰 실행이 문서의 systemd 유닛을 그대로 적용하지 않음

데스크톱에서는 클라이언트 다운로드 페이지에서 Linux 설치 파일을 선택할 수 있습니다. Debian과 Ubuntu는 보통 DEB, Fedora는 RPM을 사용하며, CPU 아키텍처도 확인해야 합니다. 설정을 가져온 뒤 클라이언트의 시스템 프록시를 켜고 브라우저에서 동작을 확인하세요. 데스크톱 시스템 프록시가 터미널 도구, 게임 또는 모든 백그라운드 서비스에 적용되는 것은 아닙니다. 터미널은 아래 방법으로 별도 설정해야 합니다.

아키텍처 확인 후 mihomo 실행 파일 설치

먼저 시스템 아키텍처와 init 프로세스를 확인하세요. 아래 명령은 일반적인 GNU/Linux 배포판을 기준으로 합니다. PID 1이 systemd가 아니라면 뒤에서 설명하는 서비스 관리 명령을 그대로 사용할 수 없습니다.

uname -m
ps -p 1 -o comm=
getconf GNU_LIBC_VERSION
  • x86_64는 amd64에 해당합니다. 구형 CPU라면 프로젝트 릴리스 페이지에서 호환성이 명시된 빌드를 우선 선택하세요. 지원 명령어 집합이 확실하지 않다면 더 높은 최적화 수준의 빌드를 바로 선택하지 마세요.
  • aarch64는 일반적으로 arm64에 해당합니다. 32비트 ARM은 CPU와 운영체제의 비트 수를 추가로 확인해야 하며, 기기 외형만 보고 선택해서는 안 됩니다.
  • Alpine은 보통 musl을 사용하고 기본적으로 systemd 환경이 아닙니다. 이에 맞는 빌드와 서비스 관리 방법을 별도로 선택해야 하며, glibc 기반 시스템의 설치 방법을 그대로 적용할 수 없습니다.

mihomo 프로젝트의 공식 배포 채널에서 시스템에 맞는 압축 파일을 내려받아 압축을 푼 다음, 실행 파일을 현재 디렉터리에 mihomo라는 이름으로 둡니다. 아래 명령은 압축을 푼 실행 파일을 대상으로 하므로 릴리스마다 달라지는 압축 파일 이름에 의존하지 않습니다.

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

file은 실행 파일의 CPU 아키텍처를 확인할 때, -v는 현재 시스템에서 코어가 실행되는지 확인할 때 사용합니다. 실제 출력 내용을 기록해 두면 오류를 해결할 때 설정 항목과 대조하기 쉽습니다. Exec format error가 나오면 아키텍처가 맞는지, 압축 파일을 실행 파일로 착각하지 않았는지 먼저 확인하세요. Illegal instruction이 나오면 빌드에 필요한 CPU 명령어 집합을 확인하는 것이 좋습니다.

설정 파일과 실행 데이터 분리하기

설정은 /etc/mihomo/config.yaml에, 쓰기 가능한 실행 데이터는 /var/lib/mihomo에 둡니다. 전용 사용자로 서비스를 실행하면 7890 같은 비특권 포트를 열기 위해 root 권한을 부여할 필요가 없습니다. 아래 계정 생성 명령은 useradd를 제공하는 Debian, Ubuntu, Fedora 등의 시스템을 대상으로 합니다.

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 \
  --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으로 확인한 뒤 조정할 수 있습니다. 전용 계정은 서비스 실행에만 사용하고, 대화형 로그인에는 사용하지 마세요.

최소 설정으로 실행 경로 먼저 점검하기

아래는 모든 요청을 직접 연결하는 완전한 로컬 프록시 설정입니다. 파일 권한, 포트 리슨, 서비스 시작을 확인하기 위한 것으로 프록시 노드를 포함하지 않으며 외부로 나가는 네트워크 경로도 바꾸지 않습니다. 처음 설치했다면 이 설정으로 설치 문제를 먼저 확인한 다음 실제 구독 설정으로 바꾸세요.

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

-f는 설정 파일을, -d는 코어의 데이터 디렉터리를 지정하며 두 경로는 서로 달라도 됩니다. 규칙 세트, 프록시 그룹, 지리 데이터에 로컬 파일이 필요하다면 경로와 전용 사용자의 접근 권한을 확인하세요. 일반 사용자의 개인 홈 디렉터리에 파일을 두고 시스템 서비스가 자동으로 읽을 것으로 기대해서는 안 됩니다.

실제 구독 설정으로 교체하기

완전한 Clash YAML을 준비한 뒤 파일을 교체하세요. 노드 목록만 담긴 Base64 텍스트나 단일 URI는 완전한 실행 설정이 아니므로 config.yaml에 그대로 저장할 수 없습니다. 완전한 설정에는 해당 노드를 사용하는 정책 그룹과 규칙도 필요합니다. 규칙에서 참조하는 정책 이름이 실제로 존재하는지도 확인하세요.

  1. 변경에 실패했을 때 복구할 수 있도록 정상적으로 작동하는 설정 파일을 따로 보관하세요.
  2. 실제 설정을 /etc/mihomo/config.yaml에 저장하고, 소유권은 root:mihomo, 권한은 0640으로 유지하세요.
  3. 혼합 포트가 계속 7890으로 설정되어 있는지 확인하고 LAN 접근은 차단하세요. 포트를 바꾸면 아래 테스트 명령도 모두 수정해야 합니다.
  4. 앞서 실행한 -t 명령을 다시 실행하세요. 설정에서 GEOIP, GEOSITE 또는 원격 컬렉션을 사용한다면 필요한 리소스를 준비하고, 처음 리소스를 내려받을 때 필요한 네트워크 연결도 확인하세요.

systemd 서비스 생성 및 부팅 시 자동 시작 설정

/etc/systemd/system/mihomo.service 파일을 만듭니다. 이 서비스는 일반 사용자 권한으로 실행되며, 명시적인 HTTP/SOCKS 프록시만 제공합니다. TUN 네트워크 인터페이스를 생성하지 않습니다. 유닛에 지정한 절대 경로는 앞서 설치한 위치와 일치해야 합니다.

sudo tee /etc/systemd/system/mihomo.service >/dev/null <<'UNIT'
[Unit]
Description=mihomo proxy core
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
StateDirectory=mihomo
StateDirectoryMode=0750
WorkingDirectory=/var/lib/mihomo
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

[Install]
WantedBy=multi-user.target
UNIT

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl is-active mihomo
sudo systemctl status mihomo --no-pager

StateDirectory는 실행 데이터 디렉터리에 쓰기 권한을 제공하고, ProtectSystem=strict는 그 밖의 파일 시스템 위치에 대한 쓰기를 제한합니다. 설정 파일은 root가 관리하고 코어는 읽기 전용으로 접근합니다. 원격 규칙 세트처럼 파일을 써야 하는 데이터는 데이터 디렉터리에 저장하세요. network-online.target은 시스템의 네트워크 준비 절차가 완료되었음을 나타낼 뿐, 특정 구독 서버에 연결할 수 있음을 보장하지 않습니다.

설정 파일 변경과 서비스 유닛 변경 구분하기

  • YAML만 수정한 경우: 설정을 테스트한 다음 sudo systemctl restart mihomo를 실행하세요.
  • 서비스 유닛을 수정한 경우: 먼저 sudo systemctl daemon-reload를 실행한 뒤 서비스를 재시작하세요.
  • 서비스 일시 중지: sudo systemctl stop mihomo를 실행하세요.
  • 부팅 시 자동 시작을 해제하고 즉시 중지하려면 sudo systemctl disable --now mihomo를 실행하세요.

이 문서에서는 ExecReload를 정의하지 않으므로 systemctl reload mihomo를 일반적인 설정 다시 불러오기 방법으로 사용하지 않습니다. 서비스를 재시작하면 기존 연결이 끊기므로 대용량 다운로드나 원격 작업이 진행 중일 때는 피하세요.

터미널 프록시 설정 후 실제 요청 확인하기

서비스 상태가 active라는 것은 프로세스가 실행 중이라는 뜻일 뿐입니다. 먼저 7890 포트가 리슨 중인지 확인한 뒤, 실제 요청을 보내 해당 프록시를 통과하는지 점검하세요. 혼합 포트는 HTTP 프록시와 SOCKS5 연결을 모두 받을 수 있으므로 아래에서 각각 테스트합니다.

sudo ss -lntp 'sport = :7890'

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

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

socks5h는 대상 도메인 이름을 프록시에서 조회한다는 뜻입니다. socks5는 보통 클라이언트가 먼저 도메인을 조회합니다. HTTP 프록시로 HTTPS 사이트에 접속할 때는 일반적으로 CONNECT로 터널을 만들기 때문에 프록시 주소를 http://127.0.0.1:7890로 적는 것이 정상입니다. 대상 사이트에 평문 HTTP로 접속한다는 의미는 아닙니다.

현재 터미널 세션에 적용하기

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 20 -I https://example.com/

이 환경 변수는 현재 셸과 이후에 실행되는 프로그램 중 해당 변수를 지원하는 프로그램에만 적용됩니다. 계속 사용하려면 Bash에서는 ~/.bashrc, Zsh에서는 ~/.zshrc에 추가한 뒤 터미널을 다시 여세요. 도구마다 변수 이름의 대소문자 지원이 다를 수 있으며, curl의 HTTP 프록시 변수는 특히 소문자 http_proxy를 사용해야 합니다.

sudo는 환경 변수를 지우는 경우가 많고 systemd 서비스도 대화형 셸 설정을 자동으로 읽지 않습니다. 따라서 터미널에서 curl이 작동한다고 해서 패키지 관리자나 백그라운드 작업도 프록시를 사용한다고 볼 수는 없습니다. 이들 도구를 별도로 설정하기 전에 실제로 필요한지 확인하고, 모든 시스템 서비스에 프록시 환경 변수를 일괄 적용하지 않도록 주의하세요.

환경 변수 해제하기

unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

셸 설정 파일에 추가했다면 해당 줄도 삭제해야 합니다. 앞서 사용한 최소 직접 연결 설정에서 테스트가 성공했다면 로컬 프록시 진입점이 작동한다는 뜻입니다. 실제 설정으로 바꾼 뒤에는 로그에서 적용된 규칙과 출구 정책도 확인하세요. HTTP 응답만으로 노드 사용 여부를 판단할 수는 없습니다.

로그·포트·권한을 확인해 문제 해결하기

오류가 발생한 상황을 먼저 기록하고 한 번에 하나씩 변경하세요. DNS, 규칙, 권한을 동시에 수정하면 연결이 복구되어도 원인을 파악하기 어렵습니다. 아래 두 명령으로 최근 로그와 실시간 로그를 각각 확인할 수 있으며, 실시간 로그는 Ctrl+C로 종료합니다.

sudo journalctl -u mihomo -b -n 100 --no-pager
sudo journalctl -u mihomo -f
증상 또는 로그우선 확인할 항목해결 방법
status=203/EXEC실행 파일 경로, 실행 권한, 아키텍처ExecStart를 확인하고 mihomo -v를 다시 실행
address already in use7890 포트를 다른 클라이언트가 사용 중인지 확인ss로 프로세스를 확인한 뒤 중복 코어를 중지하거나 포트를 통일
permission denied설정 디렉터리 및 실행 디렉터리 권한mihomo 사용자로 설정 테스트를 실행하고 경로의 모든 상위 디렉터리 확인
YAML 파싱 오류 또는 존재하지 않는 정책들여쓰기, 설정 형식, 정책 이름공백으로 들여쓰고 rules와 proxy-groups의 참조 항목 확인
서비스는 실행 중이지만 요청이 시간 초과됨대상 주소 조회, 출구 정책, 원격 리소스최소 직접 연결 설정부터 테스트한 다음 실제 노드와 규칙을 확인
Start request repeated too quickly서비스 시작이 반복해서 실패한 원인문제를 해결한 뒤 reset-failed를 실행하고 서비스 시작

경로 권한을 확인하려면 namei -l /etc/mihomo/config.yaml을 실행하세요. 시작이 반복해서 실패한 문제를 해결한 뒤 sudo systemctl reset-failed mihomo와 sudo systemctl start mihomo를 실행합니다. 권한 문제를 해결한다며 모든 사용자에게 쓰기 권한을 허용하지 마세요.

TUN 적용 범위를 확인하고 롤백 경로 확보하기

명시적 프록시를 지원하지 않는 프로그램까지 처리해야 한다면 TUN 사용을 검토하세요. TUN은 가상 네트워크 인터페이스, 라우팅, DNS, 권한 설정이 필요하며 allow-lan을 true로 바꾸는 것만으로 활성화되지 않습니다. 이 문서의 서비스는 일반 사용자 권한으로 실행되고 NoNewPrivileges=true가 설정되어 있으므로 TUN 서비스로 그대로 사용할 수 없습니다.

Linux에서 TUN을 사용하려면 보통 /dev/net/tun과 CAP_NET_ADMIN 등의 권한이 필요합니다. 자동 라우팅, DNS 하이재킹, 네트워크 스택에 따라 추가 설정이 필요할 수도 있습니다. 원격 호스트의 라우팅을 변경하기 전에는 SSH 세션을 하나 더 열어 두고 콘솔을 통한 복구 방법도 확보하세요. 컨테이너에서는 YAML만 수정할 것이 아니라 호스트가 장치 접근과 네트워크 권한을 허용하는지도 확인해야 합니다.

롤백할 수 있는 순서로 코어 업그레이드하기

  1. 현재 mihomo -v 출력 내용을 기록하고 설정 파일을 백업하세요.
  2. 새 코어의 -v를 임시 경로에서 실행한 뒤 서비스 사용자로 기존 설정을 테스트하세요.
  3. 서비스를 중지하고 기존 실행 파일을 백업한 다음 교체하고 서비스를 시작하세요.
  4. 로그와 7890 포트를 확인한 뒤 HTTP 및 SOCKS5 요청 테스트를 다시 실행하세요.
sudo systemctl stop mihomo
sudo cp -p /usr/local/bin/mihomo /usr/local/bin/mihomo.previous
sudo install -m 0755 ./mihomo /usr/local/bin/mihomo
sudo systemctl start mihomo
sudo journalctl -u mihomo -b -n 50 --no-pager

여기서 ./mihomo는 테스트를 마친 새 실행 파일입니다. 이전 버전으로 되돌리려면 서비스를 중지하고 /usr/local/bin/mihomo.previous를 /usr/local/bin/mihomo로 다시 설치한 뒤 서비스를 시작하세요. 코어와 설정 문법이 함께 바뀔 수 있으므로 실행 파일과 설정 파일을 모두 백업해 두세요.

배포가 끝나면 세 가지를 확인하세요. 재부팅 후 서비스가 자동으로 실행되는지, 7890이 예상한 주소에서만 리슨하는지, 지정한 앱의 요청이 의도한 정책을 따르는지 점검합니다. 이를 통해 ‘프로그램 설치 완료’, ‘프록시 진입점 사용 가능’, ‘실제 트래픽이 규칙에 따라 전달됨’을 구분하고 이후 문제도 쉽게 추적할 수 있습니다.

Clash 최신 버전 다운로드