プラットフォーム別 読了目安 12分

LinuxにClashをインストールする方法：mihomoの導入とsystemdでの常時起動

LinuxデスクトップのGUIクライアントから、ヘッドレスサーバーでのmihomo導入まで解説。設定ファイルの配置、systemdサービスの登録、ターミナルのプロキシ設定を紹介します。

まずは導入方法を選ぶ：デスクトップクライアントか単体カーネルか

デスクトップ環境がある場合は、GUIクライアントでサブスクリプション、プロキシグループ、接続履歴を管理するのがおすすめです。SSHターミナルだけの環境では、mihomoをコマンドラインから実行し、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をインストールする

まず、システムのアーキテクチャと初期化プロセスを確認します。以下のコマンドは一般的な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とOSのビット数も確認が必要です。機器の見た目だけで判断しないでください。
  • 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のような1024より大きいポートを待ち受けるために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. mixed-portが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が待ち受けていることを確認し、具体的なリクエストをそのポート経由で送信します。mixed-portは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 として再インストールしてから起動します。カーネルと設定構文が同時に変わる場合があるため、実行ファイルと設定ファイルの両方をバックアップしておいてください。

導入後は、3項目で動作を確認します。再起動後にサービスが自動起動すること、7890が想定したアドレスだけで待ち受けていること、指定したアプリの通信に想定したルールが適用されることです。「プログラムがインストール済み」「プロキシの待ち受けが使える」「実際の通信がルールどおり転送される」を区別でき、後から問題を調べる際にも役立ちます。

Clash最新版をダウンロード