Linux版Clashの導入方法｜mihomoをデスクトップアプリまたはsystemdで運用

まず選ぶのはデスクトップ運用かバックグラウンドサービスか

mihomoはClash Metaプロジェクトで使われているコアの名称です。設定の読み込み、ルールの判定、接続の確立を担います。GUIクライアントはサブスクリプション管理、トレイメニュー、システム連携を担当します。コアのバイナリをインストールしただけでは、デスクトップ画面は表示されず、Linux上のすべてのアプリが自動でプロキシを使うわけでもありません。

GNOMEやKDEなどのデスクトップ環境があり、ノードを頻繁に切り替える場合は、mihomoコアを搭載したクライアントがおすすめです。SSHでサーバーを管理し、ターミナルを終了した後も稼働させたい場合は、mihomoを単独で配置してsystemdに管理させる方法が適しています。どちらの方法でも近い形式のYAML設定を使えますが、同じポートを同時に使用しないようにしてください。

方法1：Linuxデスクトップクライアントをインストール

CPUアーキテクチャとパッケージ形式を確認

まずターミナルで次の2つのコマンドを実行します。x86_64は通常、ダウンロード項目のx64またはamd64に相当し、aarch64はarm64に相当します。CPUアーキテクチャとディストリビューションのパッケージ形式は別々に確認が必要です。DEBを選んでも、パッケージ内のCPUアーキテクチャが合っているとは限りません。

uname -m
cat /etc/os-release

• Debian・Ubuntu系：ディストリビューションに対応したDEBパッケージを選びます。
• Fedora系：ディストリビューションに合ったRPMパッケージを選び、パッケージマネージャーで依存関係をインストールします。
• AppImage：実行権限が必要です。起動できるかどうかは、システムライブラリやFUSEの対応状況にも左右されます。

クライアントのダウンロードページからLinux用パッケージを選べます。以下のコマンド例では、ダウンロードしたDEBファイルを clash-client.deb にリネームし、そのファイルがあるディレクトリに移動したものとします。操作例であり、実際の配布ファイル名ではありません。

sudo apt install ./clash-client.deb

サブスクリプションを確認してからシステムプロキシを有効化

1. クライアントを起動し、サブスクリプションまたは設定管理画面からプロバイダー提供のClash YAMLサブスクリプションを追加します。画面の名称はクライアントによって異なるため、特定のアプリのメニュー操作をすべてのクライアントに当てはめないでください。
2. 追加した設定を選び、コアの起動ログを確認します。ノード一覧が表示されていても、ルール、プロキシグループ、DNSの設定がすべて正常とは限りません。
3. ルールモードを選び、プロキシグループで利用可能なノードを選択します。クライアントに表示されるローカルHTTPポートまたはmixed-portを控えてください。
4. クライアントのシステムプロキシを有効にしてブラウザーで目的のサイトにアクセスします。あわせて接続一覧を確認し、通信が想定したプロキシグループを通っていることを確かめます。

GNOMEデスクトップの場合は、「設定」→「ネットワーク」→「ネットワークプロキシ」で手動を選び、HTTPとHTTPSのプロキシに 127.0.0.1 とクライアントで確認したポートを指定する方法もあります。ここで設定するのはローカルHTTPプロキシへの接続です。HTTPSサイトには通常CONNECTトンネルで接続するため、プロキシのアドレスを独断でHTTPSに変更する必要はありません。

システムプロキシを利用できるのは、デスクトップのプロキシ設定を参照するアプリが中心です。ターミナルのプログラム、コンテナ、一部のゲームでは反映されないことがあります。その場合はアプリごとにプロキシを明示するなど、個別に設定してください。「システムプロキシが有効」だからといって「端末の全通信がプロキシ経由」とは限りません。

方法2：mihomoバイナリと設定ディレクトリを準備

プロジェクトの配布元から、CPUアーキテクチャと命令セットに合ったLinux用コアを入手します。展開後、実行ファイル名を mihomo に変更してください。以下のコマンドはファイルを置いたディレクトリで実行します。古いx86プロセッサではビルドの命令セット要件にも注意が必要です。「64ビット」というだけでは互換性を判断できません。

chmod +x ./mihomo
./mihomo -v
sudo install -m 0755 ./mihomo /usr/local/bin/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

システムに mihomo アカウントがすでにある場合は、作成手順を省略し、所属グループを確認してください。ディストリビューションによって nologin のパスが異なる場合があります。まず command -v nologin を実行して確認できます。設定ディレクトリはrootが管理し、実行時ディレクトリにはサービスアカウントから書き込めるようにします。ネットワークサービスが自身の設定全体を直接変更できないようにするためです。

最小構成で起動までの流れを確認

以下は起動確認に使える、直接接続のみの設定です。プロキシノードは含まず、すべてのリクエストが最後のルールにより直接接続されるため、リモートプロキシの動作確認には使えません。まずプロセスの起動、ディレクトリ権限、ポートの待ち受けを確認し、その後で信頼できる提供元の完全な設定に置き換えると、問題を切り分けやすくなります。

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

mixed-port: 7890 は同じポートでHTTPとSOCKSの接続を受け付けます。-d は作業ディレクトリを指定し、キャッシュなどの実行時ファイルは通常ここに保存されます。-f はメイン設定ファイルの場所を明示します。設定チェックが成功しても、コアが現在の設定を解析・読み込みできたことを示すだけで、すべてのノードへの接続を保証するものではありません。

完全なサブスクリプション設定に置き換えた後、もう一度 -t を実行します。設定によってはGeoIP、GeoSite、リモートルールセットを参照するため、初回チェック時に追加ファイルの取得が必要な場合があります。サーバーから該当のURLにアクセスできない場合は、設定の要件に応じて必要なリソースをあらかじめ配置するか、まずはそれらに依存しない設定で起動時の問題を切り分けてください。

systemdサービスを作成：起動、ログ、自動復旧

以下の内容を /etc/systemd/system/mihomo.service として保存します。このサービスは専用アカウントで実行し、通常のプロキシポートのみを提供します。TUNインターフェースの作成に必要なネットワーク管理権限はありません。権限の範囲を理解せずにroot実行へ変更しないでください。

[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.target

StateDirectory は実行データ用ディレクトリを管理し、ProtectSystem=strict はサービスによるシステムファイルの変更を制限します。ReadWritePaths では実行ディレクトリへの書き込みを許可します。設定がホームディレクトリ内の証明書やルールファイルを参照している場合、ProtectHome=true によってアクセスが制限されます。必要なファイルを専用ディレクトリに置き、読み取り権限を付与してください。保護設定を一括で解除するのは避けましょう。

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
sudo journalctl -u mihomo -b -n 80 --no-pager
sudo ss -lntp 'sport = :7890'

正常に動作していれば、サービスの状態は active (running) となり、ローカルの7890番ポートが待ち受け状態になります。network-online.target は起動順序を制御するもので、その時点でサブスクリプションサーバーに接続できることを保証しません。ネットワーク障害の有無はログも確認してください。起動失敗が続いて頻度制限に達した場合は、修正後に sudo systemctl reset-failed mihomo を実行してから起動します。

設定変更後に行う手順

1. 旧設定のバックアップを残し、/etc/mihomo/config.yaml を編集します。認証情報を含むファイルを公開ディレクトリに置かないでください。
2. サービスと同じアカウント、作業ディレクトリ、-f 引数を指定して設定をチェックします。
3. チェックに成功したら sudo systemctl restart mihomo を実行し、ログと待ち受けポートを確認します。

YAMLだけを変更した場合、daemon-reload は不要です。サービスユニットを変更した場合にのみ必要です。この記事の設定には ExecReload がないため、systemctl reload mihomo による更新を前提にしないでください。

プロキシの適用範囲を確認：ターミナル、ルール、TUN

サービスを起動しても、現在のShellに環境変数は設定されません。まずは1つのリクエストにプロキシを明示し、「アプリがプロキシを使っていない」のか「コアの転送に失敗している」のかを切り分けます。以下のリクエストは接続とHTTP応答の確認用であり、遅延や速度の測定には使えません。

curl -I --connect-timeout 10 \
  --proxy http://127.0.0.1:7890 https://example.com

curl -I --connect-timeout 10 \
  --proxy socks5h://127.0.0.1:7890 https://example.com

socks5h を指定すると、curlは接続先のドメイン名をプロキシ側に渡します。一方、socks5 では通常、クライアント側でドメイン名を解決します。そのためDNSの経路が異なる場合があります。最小構成ではリクエストは直接接続されます。ノードとプロキシグループを含む設定に置き換えた後は、接続履歴で適用されたルールと実際の出口を確認してください。

現在のターミナルで、次の環境変数に対応したプログラムにプロキシを使わせる場合は、一時的に設定できます。

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

# このShellのプロキシ環境変数だけを解除
unset http_proxy https_proxy all_proxy no_proxy

すべてのプログラムが同じ環境変数を参照するわけではありません。systemdサービスも、対話型ターミナルの export を自動で引き継ぎません。別のバックグラウンドサービスにもプロキシを使わせる場合は、そのサービスごとに環境変数を設定し、ローカルリソースへのアクセスを除外するルールも検討してください。

Webパネルを接続：Controlポートはループバックアドレスで待ち受け

WebパネルはControl APIを操作するフロントエンドであり、プロキシコアではありません。7890番ポートはプロキシ通信の転送に、以下の例で9090番ポートはコアの管理に使用します。用途が異なるため、9090をブラウザーのHTTPプロキシ設定に指定しないでください。

Control用のシークレットを生成してAPIを有効化

以下のコマンドを実行するには、OpenSSLがインストールされており、現在の設定に同名の external-controller または secret フィールドがないことが条件です。待ち受けアドレスとランダム生成したシークレットを設定ファイルの末尾に追加します。すでにこれらのフィールドがある場合は、重複キーを作らず既存の項目を編集してください。

sudo sh -c '
set -eu
key=$(openssl rand -hex 24)
printf "\nexternal-controller: 127.0.0.1:9090\nsecret: \"%s\"\n" "$key" >> /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
sudo ss -lntp 'sport = :9090'

シークレットは管理用の認証情報です。公開ログやスクリーンショットに載せないでください。パネルには接続先 http://127.0.0.1:9090 と、生成したシークレットを入力します。ループバックアドレスだけで待ち受ける場合も、ホスト上の別のプロセスがポートにアクセスする可能性があるため、認証を有効にしてください。

ローカルの静的パネルを配置

現在のコアAPIに対応するパネルの静的ビルドファイルを取得し、/var/lib/mihomo/ui に展開します。このディレクトリ直下に index.html があることを確認し、mihomo アカウントに読み取り権限を付与してください。次にYAMLのトップレベルへ以下の設定を追加し、設定チェックに成功したら再起動します。

external-ui: /var/lib/mihomo/ui

ローカルのブラウザーで http://127.0.0.1:9090/ui/ にアクセスします。パネルでバックエンドのアドレスとシークレットの入力を求められた場合は、前述のControl APIの接続情報を指定してください。パネルのソースコードだけでビルド済みファイルがない場合や、余分な階層のディレクトリに配置した場合は、ページを読み込めないことがあります。

リモートサーバーにはSSHのローカルポートフォワーディングを使う方法がおすすめです。以下のコマンドの proxy-host は、ローカルのSSH設定に登録したサーバーのエイリアスです。実際のホストを指すよう、事前に設定してください。

ssh -N -L 19090:127.0.0.1:9090 proxy-host

トンネルを確立したら、ローカルで http://127.0.0.1:19090/ui/ にアクセスし、パネルのバックエンドにもローカルの19090番アドレスを指定します。サーバー側は引き続きループバックアドレスで待ち受けさせ、Controlポートをインターネットに公開する必要はありません。トンネルはAPIキー認証の代わりにはならず、それぞれが別の保護層として機能します。

よくあるトラブル：アーキテクチャ、ポート、権限、設定から原因を特定

デスクトップクライアントと独立したサービスを同時に動かしている場合は、どちらのコアに接続しているかも確認してください。2つのインスタンスで別々のポートを使えば共存できますが、クライアント上で選んだノードが別サービスのルールに反映されるわけではありません。普段使うインスタンスを明確にし、別のパネルで誤って設定を変更しないようにしましょう。

導入後は次の4段階で確認します。プロセスが継続して動作していること、ポートが想定どおり待ち受けていること、アプリが実際にそのポートを使っていること、接続に想定したルールとノードが適用されていることです。この順に確認すれば、いきなりTUNを切り替えたり、ファイアウォールを無効にしたり、何度も再インストールしたりするより原因を特定しやすくなります。設定の構造やルールの順序については、Clashの設定ガイドもご覧ください。