Linux에서 mihomo 코어 실행하기: CLI 설치, 설정 경로 및 systemd 자동 시작
아키텍처에 맞는 mihomo 바이너리 다운로드부터 설정 디렉터리와 config.yaml 배치, systemd 서비스 작성, 데스크톱 시스템 프록시 설정까지 안내합니다.
1. 설치 범위: 로컬 프록시부터 시작하고 TUN은 나중에
이 문서는 Debian, Ubuntu처럼 systemd를 사용하는 Linux 환경을 기준으로 합니다. sudo 권한이 필요하며 gzip, curl, iproute2와 CA 인증서가 설치되어 있어야 합니다. 먼저 아래 명령으로 PID 1이 systemd인지 확인하세요. 컨테이너, 일부 WSL 환경 및 다른 초기화 시스템에서는 서비스 관리 절차를 그대로 사용할 수 없습니다.
ps -p 1 -o comm=
uname -m
sudo apt update
sudo apt install gzip curl iproute2 ca-certificatesmihomo는 Clash Meta에서 발전한 프록시 코어이며, 창이 있는 데스크톱 클라이언트는 아닙니다. 코어는 YAML을 읽고 프록시 연결과 규칙 매칭을 처리합니다. 데스크톱 메뉴, 구독 관리 화면, 시스템 프록시 전환 기능은 이 바이너리에 포함되어 있지 않습니다.
- 로컬 앱 연결 주소: 이 문서에서는
127.0.0.1:7890을 사용합니다. 동일한 mixed 포트에서 HTTP 프록시와 SOCKS5 요청을 모두 받습니다. - 서비스 권한: 로그인이 불가능한 전용 계정을 사용하고, 일반 프록시 포트에 root 권한을 부여하지 않습니다.
- 적용 범위: 먼저 명시적 프록시를 확인합니다. 이 문서에서는 투명 프록시, 방화벽 포워딩 또는 TUN 가상 네트워크 인터페이스를 설정하지 않습니다.
2. 바이너리 선택: 아키텍처 확인, 압축 해제 및 설치
먼저 uname -m의 출력 결과를 확인한 다음 다운로드 페이지에서 해당 Linux 코어 파일을 선택하세요. 클라이언트용 DEB, RPM 설치 패키지를 독립형 코어 압축 파일처럼 사용하지 마세요. 기기 브랜드만 보고 CPU 아키텍처를 판단해서도 안 됩니다.
| 명령 출력 | 파일 아키텍처 선택 | 설치 전 확인 사항 |
|---|---|---|
x86_64 | Linux amd64 | CPU 명령어 세트별 빌드가 제공된다면 릴리스 안내에 따라 호환되는 버전을 선택하세요. |
aarch64 | Linux arm64 | 64비트 사용자 공간을 실행 중인지 확인하세요. |
armv7l | 해당 Linux ARM 빌드 | ARM 버전과 부동소수점 ABI를 확인하세요. arm64 파일을 그대로 사용할 수는 없습니다. |
다음 절차에서는 다운로드한 .gz 코어 압축 파일을 현재 사용자의 Downloads 디렉터리에 저장하고, 로컬에서 mihomo.gz로 이름을 바꾼 것으로 가정합니다. 이는 작업 편의를 위한 로컬 파일명이며 배포 파일의 원래 이름이 아닙니다. 압축되지 않은 바이너리를 다운로드했다면 gzip 압축 해제 단계를 건너뛰세요.
gzip -dc "$HOME/Downloads/mihomo.gz" > "$HOME/Downloads/mihomo"
chmod 0755 "$HOME/Downloads/mihomo"
"$HOME/Downloads/mihomo" -v
sudo install -m 0755 "$HOME/Downloads/mihomo" /usr/local/bin/mihomo
/usr/local/bin/mihomo -v버전 명령을 실행하면 해당 파일의 버전 정보가 출력되어야 합니다. Exec format error가 나타나면 CPU 아키텍처와 압축 여부를 먼저 확인하세요. Illegal instruction이 나타나면 더 높은 명령어 세트를 요구하는 빌드를 잘못 선택했는지 확인하세요. 이 두 오류를 해결하려고 sudo를 반복해서 추가하지 마세요.
3. 디렉터리 구성: 설정은 /etc, 실행 데이터는 /var/lib
디렉터리를 고정하면 터미널에서 직접 실행할 때와 systemd로 실행할 때 서로 다른 파일을 읽는 문제를 피할 수 있습니다. 이 문서에서는 -f로 설정 파일을, -d로 데이터 디렉터리를 지정하여 로그인 사용자의 기본 설정 경로에 의존하지 않습니다.
| 경로 | 용도 | 권한 원칙 |
|---|---|---|
/usr/local/bin/mihomo | 코어 실행 파일 | root가 설치하고 서비스 계정은 실행만 합니다. |
/etc/mihomo/config.yaml | 기본 설정 파일 | root가 수정하고 mihomo 그룹이 읽습니다. |
/var/lib/mihomo | 캐시, 규칙 리소스 및 제공자 파일 | 서비스 계정에 쓰기 권한이 필요합니다. |
/etc/systemd/system/mihomo.service | systemd 서비스 유닛 | root가 관리합니다. |
처음 설치할 때 서비스 계정과 디렉터리를 만드세요. 시스템에 같은 이름의 계정이 이미 있다면 먼저 id 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구독 파일에는 서버 주소, 비밀번호, 액세스 토큰이 포함될 수 있습니다. 공개 웹 디렉터리에 저장하거나 내용을 그대로 지원 요청에 붙여 넣지 마세요. 규칙 제공자나 프록시 제공자의 상대 경로는 일반적으로 데이터 디렉터리를 기준으로 해석됩니다. ./rules/, ./providers/처럼 데이터 디렉터리 안의 경로를 사용하고 서비스 계정에 쓰기 권한이 있는지 확인하세요.
4. config.yaml: 수신 상태를 확인한 뒤 실제 설정 가져오기
최소 설정으로 시작 절차부터 확인
아래 YAML에는 프록시 노드가 없으며 모든 요청은 최종적으로 DIRECT로 연결됩니다. 코어, 파일 권한, 로컬 포트가 정상인지 확인하는 용도일 뿐 원격 프록시가 작동한다는 뜻은 아닙니다. 먼저 이 기준 설정으로 실행을 확인한 뒤 전체 설정을 가져오면 설치 문제와 구독 문제를 구분하기 쉽습니다.
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
proxies: []
proxy-groups: []
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는 설정을 검사하는 옵션입니다. 검사가 통과하면 포그라운드에서도 한 번 실행해 보세요. 다른 터미널에서 아래에 나오는 curl 테스트를 실행한 뒤 Ctrl+C를 눌러 종료하면 포그라운드 프로세스와 systemd 서비스가 포트를 동시에 사용하지 않습니다.
sudo -u mihomo /usr/local/bin/mihomo \
-d /var/lib/mihomo -f /etc/mihomo/config.yaml전체 구독 설정에는 노드와 정책 정의가 필요합니다
서비스 제공자가 안내한 mihomo 또는 Clash Meta 설정 경로에서 전체 YAML을 받아 로컬에 Downloads/config.yaml로 저장하세요. 노드 URI, Base64 텍스트 또는 웹페이지 내용만으로는 기본 설정을 실행할 수 없습니다. proxies만 있는 노드 목록도 규칙과 정책 그룹을 포함한 전체 기본 설정과는 다릅니다.
sudo cp -a /etc/mihomo/config.yaml /etc/mihomo/config.yaml.bak
sudo install -o root -g mihomo -m 0640 \
"$HOME/Downloads/config.yaml" /etc/mihomo/config.yaml
sudoedit /etc/mihomo/config.yaml
sudo -u mihomo /usr/local/bin/mihomo \
-t -d /var/lib/mihomo -f /etc/mihomo/config.yaml- 편집기에서 최상위 항목인
mixed-port: 7890,allow-lan: false,bind-address: 127.0.0.1을 확인하세요. 같은 키가 이미 있다면 기존 값을 수정하고 중복해서 추가하지 마세요. - 처음 설치할 때는 설정에서
tun.enable을 비활성화하세요. 53번 포트를 수신하는 DNS 서비스도 활성화되어 있다면 먼저 끄거나 권한을 별도로 계획해야 합니다. 이 문서의 서비스 유닛에는 해당 기능에 필요한 권한이 없습니다. rules에서 참조하는 정책 이름이proxy-groups또는 노드 목록에 실제로 있는지 확인하세요. YAML 들여쓰기에는 공백을 사용하고 Tab은 사용하지 마세요.- 처음 실행할 때는 필수적이지 않은 컨트롤 인터페이스 설정을 제거해도 됩니다. 외부 컨트롤러가 필요하면 루프백 주소에 바인딩하고 액세스 키를 설정하세요. 인터넷에 직접 노출하지 마세요.
5. systemd 서비스: 사용자, 경로 및 시작 옵션 고정
포그라운드 프로세스가 종료되었는지 확인한 다음 서비스 파일을 만드세요. 절대 경로를 사용하면 systemd 환경 변수와 대화형 터미널 환경의 차이로 프로그램을 찾지 못하는 문제를 피할 수 있습니다. network-online.target은 시스템의 네트워크 준비 절차가 완료되었음을 나타낼 뿐, 구독 주소나 원격 노드에 연결할 수 있다는 보장은 아닙니다.
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
UMask=0077
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
UNIT
sudo 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
sudo journalctl -u mihomo.service -b -n 80 --no-pagerenable --now는 부팅 시 자동 시작을 설정하고 서비스를 즉시 시작합니다. is-enabled는 enabled, is-active는 active로 표시되어야 합니다. 이 결과로 확인할 수 있는 것은 프로세스 상태뿐이며, 대상에 연결할 수 있는지는 다음 절에서 별도로 테스트해야 합니다.
설정 변경과 서비스 파일 변경은 나눠서 처리하세요
- YAML만 수정한 경우:
mihomo -t로 전체 설정 검사 명령을 실행하고 통과하면sudo systemctl restart mihomo를 실행하세요. - service 파일을 수정한 경우: 먼저
sudo systemctl daemon-reload를 실행한 다음 서비스를 재시작하세요. - 일시 중지:
sudo systemctl stop mihomo를 실행합니다. 다음 부팅 시 자동 시작 설정은 유지됩니다. - 자동 시작을 해제하고 중지:
sudo systemctl disable --now mihomo를 실행합니다.
이 서비스에는 ExecReload가 정의되어 있지 않으므로 systemctl reload mihomo를 사용할 수 있다고 가정하지 마세요. 설정을 검사한 뒤 재시작하는 방법이 명확합니다. 재시작하면 기존 연결이 끊기므로 다운로드나 원격 세션이 진행 중일 때는 피하세요.
6. 연결 확인: 수신 포트, HTTP, SOCKS5 순서로 점검
먼저 포트를 확인한 뒤 요청을 테스트하세요. -q를 사용하면 사용자의 curl 설정 파일이 결과에 영향을 주지 않으며, --noproxy ""를 사용하면 기존 프록시 제외 목록이 이번 테스트를 우회하지 않습니다. 아래 주소는 요청 절차를 보여 주기 위한 예시이며 노드 속도 측정 기준이 아닙니다.
sudo ss -lntp | grep ':7890'
curl -q --noproxy "" --proxy http://127.0.0.1:7890 \
--connect-timeout 10 --max-time 30 -I https://example.com/
curl -q --noproxy "" --proxy socks5h://127.0.0.1:7890 \
--connect-timeout 10 --max-time 30 -I https://example.com/socks5h는 대상 도메인 이름을 프록시 측에서 해석하도록 합니다. curl 로컬에서 도메인을 해석하는 socks5와는 다릅니다. mihomo 사용 시 실제 DNS 해석 경로는 코어의 DNS 설정에도 영향을 받으므로, 이 옵션만으로 모든 DNS 트래픽의 경로를 판단할 수는 없습니다.
- 연결이 거부됨: 코어가 실행 중인지, 포트가 일치하는지, 다른 주소에만 바인딩되어 있는지 확인하세요.
- 프록시에는 연결되지만 대상 응답이 시간 초과됨: 로컬 수신 포트를 계속 바꾸기보다 실제 적용된 규칙, 선택한 정책 및 노드를 확인하세요.
- 최소 설정에서 요청 성공: 명시적 프록시 연결 지점이 작동한다는 뜻일 뿐, 트래픽은 여전히 직접 연결됩니다.
- 실제 노드 확인: 전체 설정으로 실행한 상태에서
journalctl -u mihomo -f를 확인하고 요청에 적용된 규칙과 아웃바운드 정책을 점검하세요. HTTP CONNECT 연결 수립 메시지를 대상 사이트의 응답 성공으로 간주하지 마세요.
7. 데스크톱과 터미널: 각각 프록시 연결 설정
GNOME 데스크톱 설정
GNOME에서 「설정」→「네트워크」→「네트워크 프록시」로 이동한 뒤 「수동」을 선택하세요. HTTP와 HTTPS 프록시 모두 호스트에 127.0.0.1, 포트에 7890을 입력합니다. SOCKS 호스트에도 같은 주소와 포트를 사용할 수 있습니다. HTTPS 항목은 HTTPS 대상에 사용할 프록시를 지정하는 설정이며, 로컬 포트 자체가 TLS를 제공해야 한다는 뜻은 아닙니다.
현재 데스크톱 사용자의 터미널에서 아래 명령으로 GNOME 설정을 변경할 수도 있습니다. sudo를 붙이지 마세요. root 사용자의 설정을 변경하거나 현재 사용자 세션 버스에 접근하지 못할 수 있습니다.
gsettings set org.gnome.system.proxy.http host '127.0.0.1'
gsettings set org.gnome.system.proxy.http port 7890
gsettings set org.gnome.system.proxy.https host '127.0.0.1'
gsettings set org.gnome.system.proxy.https port 7890
gsettings set org.gnome.system.proxy.socks host '127.0.0.1'
gsettings set org.gnome.system.proxy.socks port 7890
gsettings set org.gnome.system.proxy ignore-hosts "['localhost', '127.0.0.0/8', '::1']"
gsettings set org.gnome.system.proxy mode 'manual'현재 터미널의 환경 변수
데스크톱 프록시 설정이 터미널 프로그램에 자동 적용되는 것은 아닙니다. 프록시 환경 변수를 지원하는 명령줄 도구라면 현재 셸에서 아래 값을 설정할 수 있습니다. 변수는 이후에 실행하는 프로그램에만 적용되며, 도구마다 대소문자 변수명, SOCKS 및 프록시 제외 목록 지원 방식이 다를 수 있습니다.
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브라우저에서 별도의 프록시를 직접 지정했다면 시스템 프록시를 사용하도록 바꾸거나 위 포트를 직접 설정하세요. 컨테이너와 가상 머신에서 127.0.0.1은 호스트가 아니라 해당 환경 자신을 가리킵니다. 이 문서의 루프백 바인딩 방식으로는 컨테이너나 가상 머신에 직접 연결 지점을 제공할 수 없습니다.
8. 자주 발생하는 오류와 복구 절차
| 증상 | 우선 확인할 항목 | 조치 |
|---|---|---|
status=203/EXEC | 실행 파일 경로와 권한, 파일 아키텍처 | /usr/local/bin/mihomo -v를 직접 실행하고 서비스에 지정된 절대 경로를 확인하세요. |
permission denied | 기본 설정 파일 읽기 권한, 디렉터리 접근 권한, 데이터 디렉터리 쓰기 권한 | sudo -u mihomo로 설정을 검사하세요. root로 실행해 권한 문제를 감추지 마세요. |
address already in use | 7890 또는 설정에 지정된 다른 수신 포트 | sudo ss -lntup으로 포트를 사용 중인 프로세스를 찾고, 중복 실행된 코어를 중지하거나 포트를 변경하세요. |
| 리소스 다운로드 실패 | 설정에서 Geo 데이터, 규칙 제공자 또는 프록시 제공자를 참조하는지 확인 | 리소스 URL, 디렉터리 권한, 시작 시 외부로 직접 연결할 수 있는지 확인하세요. 바이너리를 반복해서 재설치하지 마세요. |
| 데스크톱을 종료한 뒤에도 터미널에서 인터넷에 연결할 수 없음 | 셸에 프록시 환경 변수가 남아 있음 | 환경 변수를 해제하고 명령 자체에 별도의 프록시 설정이 있는지도 확인하세요. |
설정을 업데이트한 뒤 시작되지 않으면 로그에서 처음 발생한 유효한 오류를 확인하세요. 이번 YAML 수정이 원인이라면 보관해 둔 복사본을 복원하고 다시 검사한 뒤 재시작할 수 있습니다. 이 문서에서 처음 만든 복사본은 직접 연결 기준 설정이므로 복원해도 실제 프록시 노드는 되돌아오지 않습니다.
sudo cp -a /etc/mihomo/config.yaml.bak /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서비스를 비활성화하기 전에 앱을 로컬 프록시에서 직접 연결로 전환하세요. GNOME과 현재 터미널 설정은 아래 방법으로 각각 되돌릴 수 있습니다. 셸 시작 파일에 변수를 추가했다면 해당 줄도 삭제한 뒤 터미널을 다시 여세요.
gsettings set org.gnome.system.proxy mode 'none'
unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY
sudo systemctl disable --now mihomo최종 점검 순서는 다음과 같습니다. 바이너리 실행 가능, 서비스 계정의 설정 파일 읽기 가능, 설정 검사 통과, 7890 정상 수신, 지정 프록시 요청 성공, 로그에 예상 정책 표시, 시스템 재부팅 후 서비스 복구. 각 단계를 따로 확인해야 설치, 설정, 앱 연결 지점, 원격 연결 문제를 구분할 수 있습니다.