Linuxでmihomoを導入する方法｜GUIクライアントとsystemdでの起動

まずは運用方法を選ぶ：デスクトップ管理か単独サービスか

Linuxデスクトップで日常的にノードを切り替えたり、サブスクリプションを読み込んだりするなら、GUIクライアントが便利です。デスクトップ環境のないホストで常時稼働させる場合や、ログイン前からプロキシを起動したい場合は、mihomo単体をsystemdで管理します。どちらもルール設定の考え方は共通ですが、設定ディレクトリや更新方法、必要な権限は異なります。クライアントの自動起動とシステムサービスは別の設定です。

mihomoはネットワーク処理を担うコアで、「Clash Metaコア」とも呼ばれます。GUIクライアントは設定管理や画面表示、システムとの連携を担当します。コアをインストールしただけでは、トレイアイコンの追加やGNOMEのプロキシ設定は行われず、すべてのコマンドラインアプリが自動でプロキシを使うわけでもありません。この記事では、まずローカルの127.0.0.1:7890だけで待ち受けるプロキシを用意し、アプリが実際にそのポートへ接続できるか確認します。

項目	GUIクライアント	systemdでmihomo単体を実行
用途	デスクトップでの操作、サブスクリプション管理、ノード切り替え	サーバー、固定設定、バックグラウンドでの常時稼働
起動タイミング	通常はユーザーのログイン後に起動	システム起動時に実行可能
設定の参照元	クライアントの設定画面とサブスクリプションの上書き設定	明示的に指定したYAMLファイル
ログの確認先	クライアントのログ画面	`journalctl -u mihomo`
基本的な権限	一般ユーザーで利用可能。TUNには別途権限が必要	専用の一般サービスユーザーを使用

Ubuntu・Debian・ArchにGUIクライアントをインストール

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

まず、以下の2つのコマンドを実行します。x86_64は通常x64またはamd64パッケージ、aarch64は通常arm64パッケージに対応します。Ubuntu・Debianでは、ディストリビューションに合ったDEBパッケージを優先してください。ArchではDEBやRPMをそのままインストールできません。クライアントの動作はCPUアーキテクチャだけでなく、システムライブラリやデスクトップ環境にも左右されます。

uname -m
cat /etc/os-release

クライアントのダウンロードページでLinux向けパッケージとメンテナンス状況を確認し、Clash Verge RevやFlClashなどの対応状況を比較してください。この記事では特定のバージョンを指定しません。インストール後は「バージョン情報」でクライアントのバージョンを、ログ画面やコア情報画面でコアのバージョンを記録しておくと、問題の再現に役立ちます。

Ubuntu / Debian：環境に合ったDEBをダウンロードします。ローカルファイルをclient.debにリネームしてから、sudo apt install ./client.debを実行できます。このファイル名はローカルでのリネーム例であり、配布パッケージの正式名称ではありません。
Arch：Archに対応した、メンテナー提供の方法でインストールしてください。AURを利用する場合は、PKGBUILDとダウンロード元を事前に確認しましょう。AURパッケージはコミュニティによる保守であり、公式リポジトリのパッケージとは異なります。インストールのために他のディストリビューションのシステムライブラリを混在させないでください。
ポータブル版：配布元がAppImageを提供している場合は、実行権限を付与して起動します。FUSEやグラフィックライブラリのエラーが発生したら、配布元の案内に従って依存関係を追加してください。エラーを回避するためにrootでGUIを起動するのは避けてください。

設定を読み込んだら、まずローカルポートを確認

クライアントの「設定」画面で、mihomo対応のYAMLファイルまたはサブスクリプションを読み込み、現在有効な設定を確認します。サブスクリプションURLには認証情報が含まれることが多いため、公開ログに貼り付けないでください。
「設定」でHTTP、SOCKS、または混合ポートの実際の番号を確認します。この記事では混合ポート7890を例にしますが、クライアントの初期値は異なる場合があります。コマンドは実際の設定に合わせて変更してください。
まずTUNを無効にし、テストに必要なプロキシだけを有効にします。ログで設定の読み込みが成功したことを確認してから、後述のプロキシを明示するコマンドで動作を検証してください。
デスクトップアプリを接続する場合は、クライアントの「システムプロキシ」を有効にします。GNOMEでは「設定」→「ネットワーク」→「ネットワークプロキシ」→「手動」でアドレスとポートを確認できます。デスクトップ環境によって設定場所は異なります。

デスクトップクライアントの「自動起動」は、通常ユーザーセッションに依存します。ログインしていない状態でも動作させるには、後述のsystemd方式を使ってください。デスクトップ側のコア自動起動は同時に有効にしないでください。クライアントを終了する前にシステムプロキシが解除されていることも確認しましょう。解除されていないと、停止したポートを参照し続けることがあります。

mihomo単体で運用：ディレクトリと最小限の設定を準備

バイナリを配置し、専用ユーザーを作成

コアの配布元から、アーキテクチャに合ったLinux用バイナリを入手し、パッケージ形式に応じて展開します。展開した実行ファイルの名前をmihomoにしてください。以下のコマンドはカレントディレクトリにあるファイルをインストールするもので、特定のリモートパッケージ名は前提としていません。まずバージョンを表示できることを確認してから、サービスの設定に進みます。

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

sudo useradd --system --user-group --no-create-home \
  --home-dir /var/lib/mihomo --shell /bin/false mihomo
sudo install -d -o root -g mihomo -m 0750 /etc/mihomo
sudo install -d -o mihomo -g mihomo -m 0750 /var/lib/mihomo

専用ユーザーがすでに存在する場合は重複して作成せず、id mihomoでユーザーとグループを確認してください。バイナリはrootが管理し、実行データはサービスユーザーが所有します。設定ディレクトリへのアクセスはrootとmihomoグループのみに制限してください。ノードのパスワードが含まれる場合もあるため、誰でも読めるディレクトリに設定を置くより安全です。

パス	用途	推奨権限
`/usr/local/bin/mihomo`	コアの実行ファイル	rootが管理、0755
`/etc/mihomo/config.yaml`	メイン設定とノード情報	root:mihomo，0640
`/var/lib/mihomo`	キャッシュ、ルールプロバイダー、実行データ	mihomo:mihomo，0750
`/etc/systemd/system/mihomo.service`	サービス定義ファイル	rootが管理、0644

まず直結設定でサービスを検証する。ノード設定としては使わない

sudoedit /etc/mihomo/config.yamlを実行し、以下の設定を書き込みます。これはローカルの混合プロキシポートを用意するだけで、すべてのリクエストは直接接続されます。インストール、権限、待ち受けの問題を切り分けるための設定です。プロキシノードがなければ、プロセスが正常に動いていても、リモートのプロキシ出口を利用できるわけではありません。

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

tun:
  enable: false

rules:
  - MATCH,DIRECT

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はデータディレクトリを指定し、-tは設定を検証します。テストに成功しても、設定を読み込めたことを示すだけで、リモートノードへの接続は保証されません。実際のサブスクリプション設定に置き換えた後は、プロキシグループ名、ルールの参照先、プロバイダーのパスも確認してください。相対パスで指定する実行データは、書き込み可能なデータディレクトリにまとめ、デスクトップユーザーの専用ディレクトリを参照しないようにします。

systemdで管理：起動、ログ、自動起動

sudoedit /etc/systemd/system/mihomo.serviceを実行し、以下のサービス定義をすべて書き込みます。この構成は一般ユーザー向けのローカルプロキシ用で、TUNは有効にせず、53などの特権ポートにもバインドしません。作業ディレクトリは書き込み可能なディレクトリとし、設定ファイルは読み取り専用にします。

[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=5
UMask=0027
NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target

network-online.targetの効果は、システムで対応するネットワーク待機サービスが有効かどうかによって異なります。これを、リモートのサブスクリプションに必ずアクセスできるという意味に捉えないでください。初回起動時にルールや地理データをダウンロードする場合は、ログで完了を確認します。起動時にネットワークを利用できない環境では、必要なデータをあらかじめ用意してください。

sudo systemd-analyze verify /etc/systemd/system/mihomo.service
sudo systemctl daemon-reload
sudo systemctl enable --now mihomo.service
systemctl status mihomo.service --no-pager
sudo journalctl -u mihomo.service -b -n 80 --no-pager
ss -lntp 'sport = :7890'

enable --nowは自動起動を設定し、サービスをすぐに起動します。enableだけでは、プロセスは直ちに起動しません。
正常時はactive (running)と表示され、ポートの確認結果にローカルの7890番ポートが表示されます。一般ユーザーがssを実行した場合、他ユーザーのプロセス名は表示されないことがあります。
設定を更新したら、まず-tで再検証し、その後sudo systemctl restart mihomoを実行します。YAMLだけを変更した場合はdaemon-reloadは不要です。サービスファイルを変更した場合に実行してください。
一時的に停止するにはsudo systemctl stop mihomoを実行します。自動起動も無効にするにはsudo systemctl disable --now mihomoを実行してください。

この記事のサービス定義にはExecReloadがないため、systemctl reloadで再起動の代わりにはできません。外部コントローラーで設定をホットリロードする場合は、認証と待ち受け範囲を別途設計してください。基本的なサービスの運用に、管理画面用の制御ポートを公開する必要はありません。

プロキシの経路を検証：ポート、リクエスト、ルールを個別に確認

まずプロキシを明示して接続し、その後に環境変数を確認

以下の2つのコマンドで、HTTPプロキシとSOCKS5プロキシをそれぞれ検証します。--noproxy ""は今回のリクエストでバイパス対象を空にし、既存のNO_PROXYによってプロキシが迂回されるのを防ぎます。SOCKSの例ではsocks5hを使い、接続先のドメイン名をプロキシ側で解決します。

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

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

HTTPレスポンスが返れば、そのリクエストは完了しています。想定したルールに一致したかどうかは、コアのログも確認してください。最小限の設定では直結と表示されます。実際のノードを有効にした後で、想定したプロキシグループに一致しているか、そのグループでどのノードが選ばれているかを確認します。遅延テストの成功だけでは、実際のHTTPSリクエストの代わりにはなりません。

プロキシを明示した接続は成功するのに、通常のターミナルコマンドがプロキシを使わない場合は、現在のシェルで環境変数を一時設定できます。環境変数名はプログラムによって異なります。以下は一般的なコマンドラインツール向けの設定で、すべてのプログラムを一括してプロキシに接続するものではありません。

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 -I --connect-timeout 10 --max-time 20 https://example.org/

unset http_proxy https_proxy all_proxy no_proxy

https_proxyの値にhttp://を使うのは矛盾ではありません。HTTPプロキシのCONNECTトンネル経由でHTTPSサイトに接続する指定です。シェルの設定ファイルに記述した場合は、サービスを停止した後に設定を削除してください。ブラウザーやAPT、systemdで起動する他のサービスが環境変数を引き継ぐとは限らないため、アプリごとに設定が必要です。

よくあるエラーは種類ごとに原因を確認

Connection refused：まず7890番ポートが待ち受け中か、ポート番号とサービスの状態が正しいか確認します。この段階でノードを変更する必要はありません。
address already in use：デスクトップクライアントや古いコアのプロセスがポートを使用していないか確認し、待ち受けるプロセスを1つだけにします。
permission denied：ファイルと親ディレクトリの権限を確認し、サービスユーザーで設定を検証します。原因を隠すためにchmod 777を実行しないでください。
ルールやデータのダウンロードに失敗：プロバイダーのURL、データディレクトリへの書き込み権限、起動時のネットワークを確認します。まずエラーの前後を含むログを保存し、その後DNSの問題かどうか判断してください。
サービスが繰り返し再起動する：journalctlで最初に発生した設定またはリソースのエラーを確認します。修正後、起動制限に達している場合はsudo systemctl reset-failed mihomoを実行してから再起動してください。

TUNと更新時の運用：権限の範囲を維持

TUNはenableをtrueにするだけでは使えない

TUNを利用するには/dev/net/tunへのアクセスが必要で、インターフェースの作成やルートの変更、DNS制御に必要なネットワーク管理権限も通常必要です。ls -l /dev/net/tunで確認できるのはデバイスノードの存在だけで、サービスに必要な権限が付与されているかどうかは分かりません。この記事の一般ユーザーサービスには、これらの権限をあえて設定していないため、そのままTUNには使用できません。

TUNを使う場合は、まずクライアントが提供する権限付与サービスを選ぶか、使用中のmihomoのバージョンに合わせてsystemdの権限とケーパビリティ制限を再設計してください。サービスユーザーをrootに変更し、他の設定をそのまま流用するだけでは不十分です。もう一方の通信制御を停止し、DNSの待ち受けポート、ルートの範囲、LANへの通信も制御するかを明確にしたうえで、LANへのアクセスと停止後のルート復旧を確認します。

更新前にバージョンを記録し、更新後に再検証

/usr/local/bin/mihomo -vの出力を記録し、現在のバイナリと設定をバックアップします。設定のバックアップも、アクセス制限を維持してください。
アーキテクチャに合った新しいコアをダウンロードし、新しいファイルに対して-vと-tを実行します。テストにはサービスユーザーと同じデータディレクトリを使用してください。
サービスを停止してからinstall -m 0755でバイナリを置き換え、サービスを起動します。実行中のファイルを直接上書きしないでください。
ログ、7890番ポートの待ち受け、HTTPSリクエストを再確認します。新しいバージョンで互換性の問題が発生した場合は、サービスを停止して古いバイナリと設定に戻し、再起動してください。

最終確認では、systemdがプロセスを安定して管理できること、ローカルアプリがプロキシポートに接続できること、実際のリクエストが正しいルールとノードに一致することをそれぞれ確認します。3つすべてを満たせば導入完了です。基本設定は入門ガイドを、ブラウザーとターミナルで結果が異なる場合はトラブル対処を確認し、アプリのプロキシ設定を順番に見直してください。