Linux에 Clash 코어와 데스크톱 클라이언트 설치하기: systemd 상시 실행, 터미널 프록시 변수와 GUI 선택

먼저 배포 방식을 결정하세요: 데스크톱 클라이언트 또는 독립 코어

Linux에서 Clash를 배포하는 방법은 보통 두 가지입니다. 데스크톱 환경에서는 설정 관리, 프록시 그룹 전환, 로그 확인 기능을 갖춘 GUI 클라이언트를 사용할 수 있습니다. 서버, 개발 머신 또는 장시간 켜 두는 소형 장치는 Clash Meta（mihomo） 코어를 직접 실행하고 systemd로 프로세스를 관리하는 방식이 적합합니다. 두 방식 모두 YAML 설정을 읽지만 시작 방법, 권한 범위와 시스템 프록시 연동 방식은 서로 다릅니다.

사용 환경	권장 방식	주요 장점	확인할 사항
GNOME, KDE Plasma 데스크톱	GUI 클라이언트	구독 가져오기, 노드 전환과 로그 확인이 간편함	데스크톱 프록시 설정, 트레이 지원, 코어 권한
GUI 없는 클라우드 서버	mihomo + systemd	리소스 사용량이 명확하고 자동 재시작 가능	설정 경로, 실행 사용자, 수신 주소
개발 워크스테이션	GUI 또는 독립 코어	Git, 패키지 관리자와 컨테이너에 프록시를 별도로 설정 가능	환경 변수 적용 범위와 DNS 동작
게이트웨이 또는 투명 프록시 라우터	mihomo TUN 또는 투명 프록시	더 많은 애플리케이션 트래픽을 가로챌 수 있음	라우팅 테이블, nftables, DNS와 네트워크 권한

브라우저, Git과 터미널 명령만 프록시를 사용하면 된다면 먼저 HTTP, SOCKS 또는 mixed 포트부터 시작하세요. TUN 모드는 가상 네트워크 인터페이스를 만들고 라우팅을 조정하므로 적용 범위가 넓지만 CAP_NET_ADMIN, DNS 가로채기와 방화벽 호환성 문제가 추가될 수 있습니다. 일반 포트가 안정적으로 작동하는지 먼저 확인한 뒤 TUN을 활성화하면 문제 해결 경로를 줄일 수 있습니다.

mihomo 바이너리 설치와 디렉터리 구성

설치 전에 프로세서 아키텍처를 확인하세요. 일반적인 x86_64는 amd64에 해당하며, Raspberry Pi 4, 일부 클라우드 서버와 최신 개발 보드는 보통 arm64입니다. 배포판 이름만으로 아키텍처를 판단하지 말고 시스템이 반환하는 값을 직접 확인하는 편이 정확합니다.

uname -m
getconf LONG_BIT
cat /etc/os-release

uname -m의 결과가 x86_64이면 amd64 빌드를 선택하고, aarch64이면 arm64 빌드를 선택합니다. 해당 파일을 다운로드해 압축을 푼 다음 실제 바이너리를 고정 경로에 설치하세요. 아래 예시는 압축을 푼 파일 이름이 mihomo-linux-amd64인 경우를 가정합니다.

sudo install -m 0755 ./mihomo-linux-amd64 /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

프로그램, 읽기 전용 설정과 실행 데이터를 분리하는 것이 좋습니다. 바이너리는 /usr/local/bin, 기본 설정은 /etc/mihomo, 캐시·Geo 데이터·프록시 제공자 파일과 실행 상태는 /var/lib/mihomo에 둡니다. 이렇게 하면 systemd의 쓰기 범위 제한이 쉬워지고, 바이너리를 업데이트할 때 설정이 덮어써지는 일도 막을 수 있습니다.

sudo useradd --system \
  --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
sudo install -d -m 0750 -o mihomo -g mihomo /var/lib/mihomo/providers
sudo install -m 0640 -o root -g mihomo ./config.yaml /etc/mihomo/config.yaml

검증 가능한 기본 설정부터 준비하기

로컬에서 사용하기 쉬운 기본 설정은 mixed 포트 7890을 열고 외부 제어 인터페이스를 루프백 주소로 제한하는 형태입니다. mixed 포트는 HTTP와 SOCKS 연결을 모두 받아 터미널 도구, 브라우저와 데스크톱 프록시 설정을 함께 사용하기에 적합합니다.

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

external-controller: 127.0.0.1:9090
secret: "linux-local-controller-2026"

profile:
  store-selected: true
  store-fake-ip: true

여기에는 프록시 노드, 프록시 그룹과 rules를 포함하지 않았습니다. 이러한 항목은 실제로 사용할 수 있는 설정이나 구독에서 가져와야 하기 때문입니다. 가져온 뒤에는 MATCH,PROXY 또는 실제 프록시 그룹과 이름이 일치하는 규칙처럼 최종 규칙에 기본 처리 정책이 포함되어 있는지 확인하세요. 프록시 그룹 이름은 대소문자를 구분하며, 존재하지 않는 그룹을 규칙에서 참조하면 설정 테스트가 즉시 오류를 냅니다.

sudo -u mihomo /usr/local/bin/mihomo \
  -t \
  -f /etc/mihomo/config.yaml \
  -d /var/lib/mihomo

테스트가 성공하면 설정 로드가 완료되었다는 정보가 표시됩니다. YAML 파싱 오류가 발생하면 먼저 들여쓰기, 콜론 뒤 공백과 프록시 그룹 이름을 확인하세요. YAML에서는 Tab을 계층 들여쓰기로 사용할 수 없습니다. 설정 테스트가 통과하기 전에는 자동 재시작 루프를 만들지 마세요. 로그가 반복되는 시작 메시지로 뒤덮일 수 있습니다.

systemd 서비스 작성과 부팅 시 자동 실행 설정

systemd 유닛에는 실행 사용자, 작업 디렉터리, 재시작 정책과 쓰기가 허용되는 경로를 명시해야 합니다. 일반적인 HTTP 및 SOCKS 프록시는 root 권한이나 네트워크 관리 권한이 필요하지 않습니다. 아래 유닛은 TUN을 활성화하지 않는 기본 배포에 적합합니다.

[Unit]
Description=mihomo proxy service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
ExecStartPre=/usr/local/bin/mihomo -t -f /etc/mihomo/config.yaml -d /var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -f /etc/mihomo/config.yaml -d /var/lib/mihomo
Restart=on-failure
RestartSec=5s
LimitNOFILE=1048576

NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mihomo
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6

[Install]
WantedBy=multi-user.target

내용을 /etc/systemd/system/mihomo.service로 저장한 다음 유닛을 다시 불러오고 시작하세요. enable --now는 부팅 시 자동 시작과 즉시 시작을 함께 설정하므로 start를 따로 실행할 필요가 없습니다.

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
journalctl -u mihomo -n 80 --no-pager

포트와 제어 인터페이스 확인

서비스가 active로 표시된다는 것은 프로세스가 계속 실행 중이라는 뜻일 뿐입니다. 7890과 9090이 어떤 주소에서 수신 중인지도 확인해야 합니다. 예상 결과는 127.0.0.1:7890과 127.0.0.1:9090이며, 모든 네트워크 인터페이스에 열린 0.0.0.0이어서는 안 됩니다.

ss -lntp | grep -E '7890|9090'
curl --max-time 5 \
  --proxy http://127.0.0.1:7890 \
  -I https://www.gstatic.com/generate_204

연결이 정상이면 테스트 요청은 보통 0.4~2초 안에 204 또는 프록시 체인에서 설명 가능한 HTTP 상태를 반환합니다. 5초 동안 시간 초과가 발생하면 먼저 mihomo 로그에서 프록시 그룹이 선택되었는지 확인한 뒤 노드 연결 오류를 살펴보세요. 즉시 Connection refused가 표시된다면 원격 프록시보다 로컬 포트 수신에 문제가 있을 가능성이 큽니다.

터미널 프록시 변수: 현재 세션, 영구 설정과 단일 명령

Linux 터미널 프로그램은 mihomo가 실행 중이라고 해서 자동으로 프록시를 사용하지 않습니다. curl, wget, Git과 언어별 패키지 관리자가 데스크톱 시스템 프록시를 읽는지는 각 프로그램의 구현에 따라 다릅니다. 가장 범용적인 방법은 현재 Shell에서 HTTP_PROXY, HTTPS_PROXY와 ALL_PROXY를 설정하는 것입니다.

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,.local

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
export no_proxy="$NO_PROXY"

socks5h의 h는 도메인 조회를 SOCKS 프록시 서버에서 처리한다는 뜻으로, 로컬 DNS 조회와 프록시 경로가 어긋나는 문제를 줄일 수 있습니다. 도구마다 읽는 변수 이름이 다르므로 대문자와 소문자 변수를 함께 설정하세요. 변수는 현재 Shell과 그 하위 프로세스에만 적용되며, 이미 열려 있는 터미널 탭에는 이후 변경 사항이 자동으로 반영되지 않습니다.

적용 범위에 맞는 설정 방법

명령 하나에만 프록시 적용:HTTPS_PROXY=http://127.0.0.1:7890 curl https://example.com.
현재 터미널에만 프록시 적용: export를 직접 실행하며, 세션을 닫으면 사라집니다.
Bash에 영구 적용: ~/.bashrc에 추가한 뒤 source ~/.bashrc를 실행합니다.
Zsh에 영구 적용: ~/.zshrc에 추가하고 터미널을 다시 열거나 source ~/.zshrc를 실행합니다.
Git에 별도 설정: git config --global http.proxy http://127.0.0.1:7890을 사용합니다.

현재 세션의 프록시를 해제할 때는 대소문자 변수를 모두 삭제해야 합니다. 그래야 특정 도구가 남아 있는 값을 계속 읽지 않습니다.

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY
unset http_proxy https_proxy all_proxy no_proxy

git config --global --unset http.proxy
git config --global --unset https.proxy

sudo는 기본적으로 프록시 환경 변수를 필터링할 수 있으며, systemd 서비스도 대화형 Shell의 ~/.bashrc를 상속하지 않습니다. 백그라운드 서비스에 프록시가 꼭 필요하다면 전역 시스템 환경을 수정하지 말고 해당 서비스 전용 drop-in을 만들어 [Service] 아래에 Environment=를 설정하세요. 이렇게 하면 프록시의 영향을 대상 서비스로 제한할 수 있습니다.

Linux 데스크톱 클라이언트와 시스템 프록시 연동

그래픽 클라이언트는 구독을 자주 가져오고 프록시 그룹을 전환하며 연결 기록을 확인해야 하는 데스크톱 사용자에게 적합합니다. 선택할 때는 Linux 빌드 제공 여부, 코어 경로 인식 여부, 설정 저장 위치의 명확성, 현재 데스크톱 환경 지원 여부를 확인하세요. 일반적인 배포 형식으로는 AppImage, Deb, RPM과 압축 파일이 있습니다.

설치 형식별 주요 확인 사항

AppImage: 먼저 chmod +x를 실행한 뒤 일반 데스크톱 사용자로 시작합니다. 일부 경량 시스템에서는 FUSE 호환 구성 요소를 설치해야 합니다.
Deb: Debian, Ubuntu와 그 파생 배포판에 적합하며 sudo apt install ./클라이언트 파일.deb로 설치하고 의존성을 처리할 수 있습니다.
RPM: Fedora, Rocky Linux, openSUSE 등의 환경에 적합하며 구체적인 설치 명령은 dnf 또는 zypper를 사용합니다.
압축 파일: 데스크톱 바로가기, 업데이트 경로와 실행 권한을 직접 관리해야 하며 특정 버전을 고정하려는 환경에 적합합니다.

데스크톱 클라이언트에는 보통 「시스템 프록시」, 「TUN 모드」, 「시작 시 실행」 등의 옵션이 있습니다. 브라우저와 데스크톱 프록시 설정을 따르는 프로그램만 사용한다면 시스템 프록시만 켜면 됩니다. GNOME에서는 「설정」→「네트워크」→「네트워크 프록시」에서 설정하고, KDE Plasma 6에서는 보통 「시스템 설정」→「네트워크」→「프록시」에 있습니다. 수동 설정 시 HTTP, HTTPS와 SOCKS 호스트에는 127.0.0.1을 입력하고, 포트에는 클라이언트에 표시된 실제 mixed 포트(예: 7890)를 입력하세요.

GUI 클라이언트의 코어와 앞서 설정한 systemd 코어를 동시에 실행하면서 둘 다 7890을 수신하게 하지 마세요. 포트 충돌이 발생하면 나중에 시작한 인스턴스가 보통 address already in use를 보고합니다. 두 환경을 모두 유지해야 한다면 한쪽을 17890, 17891 등 다른 포트로 변경하고 외부 제어 포트도 각각 확인하세요.

TUN 모드 활성화 시 권한과 DNS 설정

TUN 모드는 HTTP 프록시 변수를 읽지 않는 애플리케이션, 예를 들어 일부 게임 런처, 폐쇄형 데스크톱 프로그램과 자체 네트워크 스택을 사용하는 소프트웨어의 트래픽도 가로챌 수 있습니다. mihomo는 가상 네트워크 장치를 만들고 라우팅을 조정하므로 최소한 CAP_NET_ADMIN이 필요합니다. 일부 네트워크 작업에는 CAP_NET_RAW도 사용될 수 있습니다. 서비스에는 필요한 capability만 부여하고 전체 프로세스를 root 사용자로 바꿀 필요는 없습니다.

sudo systemctl edit mihomo를 실행해 오버라이드 설정을 만들 수 있습니다:

[Service]
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW
PrivateDevices=false
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK

저장한 뒤 다음 명령을 실행하면 오버라이드 설정이 적용됩니다:

sudo systemctl daemon-reload
sudo systemctl restart mihomo
systemctl show mihomo -p AmbientCapabilities
ip address show
ip route show table all

TUN 설정의 주요 필드

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-redirect: true
  strict-route: true
  dns-hijack:
    - any:53

auto-route는 라우팅을 자동으로 추가하고, auto-redirect는 지원되는 Linux 환경에서 nftables를 활용해 트래픽 가로채기를 개선하며, strict-route는 트래픽 우회를 줄입니다. 각 필드가 현재 시스템에 적합한지는 NetworkManager, systemd-networkd, Docker와 기존 방화벽 규칙을 함께 고려해야 합니다. 컨테이너 네트워크, 회사 VPN과 TUN이 모두 정책 라우팅을 추가할 수 있으므로 충돌이 발생하면 활성화 전후의 ip rule과 ip route show table all 결과를 비교하세요.

DNS는 TUN 문제를 해결할 때 핵심입니다. IP에는 연결되지만 도메인에 접속할 수 없다면 먼저 resolvectl status와 resolvectl query example.com을 실행하세요. 시스템의 systemd-resolved가 로컬 53번 포트를 이미 사용 중이라면 mihomo의 일반 DNS 수신을 같은 주소와 포트에 바인딩하지 마세요. 127.0.0.1:1053처럼 높은 포트를 사용한 뒤 명시적인 시스템 설정으로 전달하거나, TUN의 DNS 하이재킹으로 가상 네트워크 장치를 거치는 53번 포트 요청을 처리할 수 있습니다.

자주 발생하는 문제 해결: 프로세스, 포트와 규칙 결과 확인

서비스가 계속 재시작됨

계속 재시작하기보다 먼저 현재 시작 주기의 로그를 확인하세요:

systemctl status mihomo --no-pager
journalctl -u mihomo -b -n 120 --no-pager
sudo -u mihomo /usr/local/bin/mihomo \
  -t \
  -f /etc/mihomo/config.yaml \
  -d /var/lib/mihomo

일반적인 원인으로는 YAML 들여쓰기 오류, 존재하지 않는 프록시 그룹 참조, 설정 파일 권한 부족, Geo 데이터 디렉터리 쓰기 불가, 다른 클라이언트가 이미 수신 포트를 사용 중인 경우가 있습니다.

7890은 수신 중이지만 터미널이 여전히 직접 연결됨

설정 파일만 보지 말고 현재 프로세스가 실제로 전달받은 변수를 확인하세요:

env | grep -i proxy
curl --max-time 5 -I https://example.com
curl --max-time 5 --proxy http://127.0.0.1:7890 -I https://example.com

두 번째 명령은 실패하고 세 번째 명령은 성공한다면 mihomo는 정상 작동하며 문제는 터미널 프록시 변수 또는 애플리케이션 자체 설정에 있습니다. 두 명령이 모두 실패하면 로그에서 DNS, 핸드셰이크 또는 노드 시간 초과 정보를 다시 확인하세요.

구독은 업데이트됐지만 노드 목록이 바뀌지 않음

프록시 제공자 파일은 /var/lib/mihomo/providers처럼 mihomo 사용자가 쓸 수 있는 디렉터리에 저장해야 합니다. 파일 수정 시간, provider 상태 확인 결과와 구독 응답 내용을 확인하세요. systemd의 ProtectSystem=strict는 ReadWritePaths에 포함되지 않은 디렉터리에 서비스가 쓰지 못하게 하므로 동적으로 갱신되는 provider 파일을 읽기 전용인 /etc/mihomo에 두지 마세요.

TUN을 켠 뒤 LAN 또는 컨테이너 연결이 끊김

먼저 TUN을 끄고 mixed 포트가 계속 작동하는지 확인한 다음 TUN 활성화 전후의 라우팅과 규칙을 비교하세요. LAN 대역에는 보통 192.168.0.0/16, 10.0.0.0/8과 172.16.0.0/12처럼 직접 연결 규칙이 필요합니다. Docker는 흔히 172.17.0.0/16을 사용하지만 실제 대역은 docker network inspect 출력으로 확인해야 하며 모든 호스트가 같다고 가정해서는 안 됩니다.

업데이트와 롤백: 설정과 프로그램을 분리해 유지하기

코어를 업데이트하기 전에 현재 버전을 기록하고 정상 작동 중인 바이너리를 보관하세요. 설정과 프로그램이 이미 분리되어 있으므로 롤백할 때는 이전 바이너리를 복원하고 서비스를 재시작하면 됩니다. /etc/mihomo/config.yaml이나 provider 데이터를 덮어쓸 필요가 없습니다.

/usr/local/bin/mihomo -v
sudo cp /usr/local/bin/mihomo /usr/local/bin/mihomo.previous
sudo systemctl stop mihomo
sudo install -m 0755 ./mihomo-linux-amd64 /usr/local/bin/mihomo
sudo -u mihomo /usr/local/bin/mihomo \
  -t \
  -f /etc/mihomo/config.yaml \
  -d /var/lib/mihomo
sudo systemctl start mihomo

새 버전이 시작되지 않으면 sudo install -m 0755 /usr/local/bin/mihomo.previous /usr/local/bin/mihomo를 실행한 뒤 다시 시작하세요. 업그레이드가 끝난 후에는 로그, 포트, 프록시 그룹 선택과 실제 네트워크 요청도 확인해야 합니다. 버전 번호가 바뀐 것만으로는 전체 실행 검증을 대신할 수 없습니다.