Linuxでmihomoを使う方法｜GUIクライアントとsystemdの導入手順

まずは選択：GUIクライアントかsystemdサービスか

デスクトップ環境でポリシーグループを頻繁に切り替えるなら、GUI搭載のClashクライアントがおすすめです。SSHでサーバーを管理する場合や、ログアウト後も稼働させたい場合は、mihomoをsystemdサービスとして動かします。mihomoはClash Meta系のプロキシコアで、デスクトップ向けの操作画面は付属しません。コアの実行ファイルをダウンロードしても、GUIクライアントがインストールされるわけではありません。

GUIクライアントを使う：インストール・設定・動作確認

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

まずuname -mを実行します。一般的なx86_64はamd64、aarch64はarm64に対応します。「64ビット」というだけで両者を同じものとして扱わないでください。DebianやUbuntuでは通常DEB、FedoraなどではRPMを選びます。AppImageで追加の実行環境が必要かどうかは、利用するクライアントの説明を確認してください。

クライアントのダウンロードページでLinuxを選び、アーキテクチャとパッケージ形式を確認します。カレントディレクトリに保存済みのDEBパッケージを使う場合は、ファイルマネージャーから開くか、sudo apt install ./の後に実際のファイル名を指定してインストールします。コア単体のアーカイブをDEBパッケージとしてパッケージ管理ツールに渡さないでください。

機能ごとに画面を確認

1. 設定画面：サブスクリプションURLまたはローカルのYAMLを読み込み、完了したら使用する設定として選択します。URLに認証情報が含まれる場合があるため、公開ログに貼り付けないでください。
2. プロキシ画面：モードをルールモードにし、ルールで参照されているポリシーグループに利用可能なプロキシが選択されているか確認します。設定を読み込めても、ポリシーグループが正しく選択されているとは限りません。
3. 設定画面：実際の混合ポートを確認し、7890かどうかを記録してから、必要に応じてシステムプロキシを有効にします。画面上の名称は「設定」や「ネットワーク設定」など、バージョンによって異なります。
4. ログ画面：リクエストを1回実行し、設定の解析、ポートのバインド、上流への接続に関するエラーがないか確認します。タスクトレイのアイコンだけで通信経路を判断しないでください。

デスクトップのシステムプロキシ設定が反映されるのは、その設定を参照するアプリに限られます。ターミナルのcurl、一部の開発ツールやバックグラウンドサービスには適用されないことがあるため、後述の手順でターミナルの環境変数も設定します。GUIクライアントを使う場合は、動作確認とトラブル対処の項目を参照してください。独立サービスのインストール手順を重ねて実行する必要はありません。

コマンドラインで導入：実行ファイルと設定ディレクトリを固定

以下のコマンドはsystemdを使用するDebian・Ubuntu系システムを対象とし、現在のユーザーにsudo権限があることを前提としています。コンテナ、軽量ディストリビューション、WSLではsystemdが初期化システムとして動作していない場合があります。まずps -p 1 -o comm=を実行してください。出力がsystemdでなければ、サービス管理コマンドをそのまま使うことはできません。

実行ファイルをインストール

プロジェクトのリリース配布元から、アーキテクチャとCPU要件に合ったLinux向けコアを入手します。展開後、実行ファイルをmihomoという名前にしてカレントディレクトリに置きます。以下のコマンドはファイルをダウンロードしません。インストール前に、カレントディレクトリのファイルが使用するコアであることを確認してください。

uname -m
ps -p 1 -o comm=
sudo install -m 0755 ./mihomo /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

-vで表示されるのは、実際にインストールされたバージョンです。設定項目の互換性を後から確認できるよう、出力を導入記録と一緒に保存してください。クライアント画面に表示されるバージョンから、コアのバージョンを推測しないでください。

専用ユーザーとディレクトリを作成

sudo useradd --system --user-group \
  --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

• /usr/local/bin/mihomo：rootが管理する実行ファイル。サービス用ユーザーには上書きを許可しません。
• /etc/mihomo/config.yaml：管理者が編集するメイン設定ファイル。サービス用ユーザーには読み取り権限のみ付与します。
• /var/lib/mihomo：キャッシュや設定に応じて保存するリソース用のデータディレクトリ。

ユーザーの作成は一度だけ行います。「ユーザーがすでに存在する」と表示されたら、削除して作り直すのではなく、既存ユーザーの用途を確認してください。設定内のprovider、ルールセット、データベースで相対パスを使う場合は、-dで指定したデータディレクトリを基準に実際の保存場所を確認します。パスが常にメイン設定ファイルの場所を基準にするとは限りません。

最小構成でサービスの起動を確認

初回導入では、実際のサブスクリプションを設定する前に「プログラムが起動する」「設定を読み込める」「ポートが待ち受け状態になる」ことを確認します。以下は起動確認用の直接接続設定で、リモートプロキシは含みません。リクエストが成功しても、ローカルのプロキシ入口が機能していることしか確認できず、プロキシノード経由の接続を証明するものではありません。

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は、同じポートでHTTPとSOCKSのプロキシ接続を受け付けます。allow-lan: falseにより、サービスの利用をローカルホストに限定します。mode: ruleはルールの順番に従って接続を処理します。この例では末尾のMATCH,DIRECTにより、すべてのリクエストを直接接続します。-tは設定の検査用で、サービスをバックグラウンドで常時起動するものではありません。

実際のプロキシ設定に置き換える際の確認事項

1. サブスクリプションの形式：コアの-fは設定ファイルを読み込みます。サブスクリプションURLを直接渡すことはできません。ノード一覧だけでは、一般設定、ポリシーグループ、ルールを含む完全な設定とはいえません。
2. 参照先の名称：rulesで参照するポリシーグループが存在し、ポリシーグループから参照するノードやproviderも正しく読み込める必要があります。
3. リソースへのアクセス権：ダウンロードや更新が必要なproviderやルールセットは、サービス用ユーザーが書き込めるデータディレクトリに配置します。読み取り専用の/etc/mihomoには置かないでください。

systemdサービスを作成して自動起動を設定

以下の内容を/etc/systemd/system/mihomo.serviceとして保存します。この記事のローカル向け明示的プロキシ構成では、専用の一般ユーザーでサービスを実行します。StateDirectoryは実行データ用ディレクトリを管理し、ProtectSystem=strictはファイルシステムへの書き込み範囲を制限します。

[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

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 -l
sudo journalctl -u mihomo.service -b -n 80 --no-pager

enableはシステム起動時の自動起動を設定し、--nowを付けると同時にサービスを開始します。network-online.targetで実際にどの程度待機するかは、システムのネットワーク管理サービスに依存します。すべてのリモートアドレスに接続できることを保証するものではありません。ネットワークリソースの取得に失敗した場合は、ログを確認し、名前解決・接続・権限のどこで問題が起きたかを調べてください。

サービスファイルを変更した場合は、再起動の前にdaemon-reloadを実行します。YAMLだけを変更した場合は、先ほどの-tで検査し、問題がなければsudo systemctl restart mihomo.serviceを実行してください。このサービスにはExecReloadを定義していないため、systemctl reloadを設定済みのホットリロードとして使うことはできません。

ターミナルのプロキシ設定：明示的にテストしてから環境変数を設定

ローカルのプロキシポートが待ち受け状態か確認

sudo ss -lntp 'sport = :7890'
curl --noproxy "" --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 30 \
  -I https://clash03.com/

1つ目のコマンドでTCPの待ち受けを確認します。ローカルアドレスは127.0.0.1:7890が想定されます。すべてのネットワークインターフェースに公開する0.0.0.0:7890ではありません。2つ目のコマンドではプロキシを明示し、以前に設定した環境変数の影響を避けてテストします。応答速度や接続先の地域を保証するものではありません。最小構成の直接接続設定では、通信は引き続き接続先サイトに直接送られます。

現在のシェルにプロキシを設定

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 30 -I https://clash03.com/

https_proxyの値もhttp://のままです。これはローカルのHTTPプロキシ経由でHTTPS接続を行うことを意味し、プロキシ入口にTLSが必要という意味ではありません。この形式に対応したプログラムでは、socks5h://を使うと接続先のホスト名をSOCKSプロキシ側で解決します。プログラムがhttp_proxyやhttps_proxyを優先して参照する場合、all_proxyが使われるとは限りません。

これらの環境変数が影響するのは現在のシェルと、そこから起動する子プロセスだけです。すでに起動しているブラウザー、別のログインセッション、システムサービスには自動で適用されません。設定を永続化する場合は、利用しているシェルに応じて~/.bashrcまたは~/.zshrcに記述します。1つのアプリのために、すべてのシステムサービスへプロキシ環境変数を設定しないでください。

unset http_proxy https_proxy all_proxy no_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

変数を解除すると、以後起動するコマンドはこれらの環境変数からプロキシ設定を読み込まなくなります。sudoはデフォルトで環境変数を引き継がない場合があります。また、Gitやパッケージ管理ツールには独自のプロキシ設定があることもあります。「curlは使えるが、ほかのコマンドは使えない」場合は、すぐにノードを変更せず、各ツールの設定を個別に確認してください。

よくあるトラブル：プロセス・設定・接続の順に確認

サービスが何度も再起動する

ログが出続けるのを防ぐため、まずsudo systemctl stop mihomo.serviceを実行します。同じサービス用ユーザーで-tによる検査を行い、今回の起動ログを確認してください。失敗回数がsystemdの起動制限に達した場合は、原因を修正してからsudo systemctl reset-failed mihomo.serviceを実行し、サービスを再起動します。YAMLの誤りを隠すために、リトライ回数だけを増やさないでください。

サービスは正常だが、ターミナルから接続できない

まずcurlが接続するアドレスとmixed-portが一致しているか確認します。ポートを7890から7891に変更した場合は、システムプロキシ、ターミナルの環境変数、アプリ独自のプロキシ設定もすべて更新してください。別のマシンから接続する場合、127.0.0.1が指すのは接続元のマシンであり、mihomoを実行しているホストではありません。

このサービスではTUNを使用しない

TUNは仮想ネットワークデバイスとルーティングを使って通信を取り込みます。HTTPプロキシの環境変数を設定する方法とは異なる仕組みです。/dev/net/tun、ネットワーク管理権限、ルートやDNSの設定が必要になるため、この記事のサービスには意図的に権限を付与していません。tun.enableをtrueに変更するだけでは動作するとは限りません。TUNを使う場合は、対象のクライアントまたはコアのドキュメントに従って権限とルーティングを別途設計し、ほかのVPNとの競合がないことを確認してください。

アップデートとロールバック：動作する設定を維持

1. 更新前にmihomo -vの出力を記録し、メイン設定と現在の実行ファイルをバックアップします。バックアップにサブスクリプション情報が含まれる場合は、アクセス権を制限してください。
2. 新しい実行ファイルを一度一時的な場所に置き、既存の設定に対して-tで検査します。検査に成功しても、設定を解析できたことしか確認できないため、実際の起動も確認してください。
3. サービスを停止してから実行ファイルを置き換えます。root所有と実行権限を維持したうえで、サービスを再起動してください。
4. systemctl is-active、直近のログ、明示的なプロキシ接続を確認します。問題があれば、以前の実行ファイルと設定に戻してから再起動してください。

導入完了の判断には、サービスが正常であること、ローカルポートが想定どおりであること、実際のリクエストが想定したポリシーを通ることの3点が必要です。GUIクライアントは対話的な管理に、systemdは固定された構成での長期稼働に適しています。どちらを選ぶ場合も、設定ファイルの場所、プロキシの入口、更新方法を明確にし、複数のコアが同時に動いて通信経路が分からなくなる状況を避けてください。設定項目の詳細は設定リファレンスを、初回の設定読み込みはクイックスタートを参照してください。