Linuxでの導入方法と利用上の注意

デスクトップ環境があり、ノードを頻繁に切り替える場合は、まずクライアントのダウンロードページからLinux用GUIクライアントを選び、プロバイダーから提供されたサブスクリプションを読み込みます。SSHのみで操作するサーバーでは、mihomoを直接実行してsystemdでプロセスを管理する方法が適しています。どちらも似たプロキシ設定を使えますが、インストール方法や必要な権限、プロキシの適用方法は異なります。同じマシンで両方を同時に有効にする必要はありません。

Clashは、この種のプロキシツールや設定エコシステムを指す一般的な呼び名です。mihomoはClash Metaから発展したコアです。GUIクライアントは設定管理やトレイ表示、オン・オフ操作を担い、コアはポートの待ち受け、ルール判定、接続処理を担当します。コアのバイナリをダウンロードしただけではデスクトップ画面は使えません。また、GUIクライアントを起動しても、Linux上のすべてのアプリが自動的にプロキシを使うわけではありません。

利用環境おすすめの方法最初に確認すること
Ubuntu・Debianのデスクトップ対応アーキテクチャのDEB形式GUIクライアント設定を読み込んだ後、ノードとローカルの待ち受けポートを確認
FedoraなどRPM系のデスクトップ対応アーキテクチャのRPM形式GUIクライアントコアのログを確認し、明示的にプロキシを指定してリクエストをテスト
GUIのないサーバーmihomoバイナリとsystemdのシステムサービス設定をテストしてから、サービスと7890番ポートを確認

デスクトップクライアントのインストールとサブスクリプションの読み込み

システムのアーキテクチャとインストールパッケージ

ダウンロード前に、次の2つのコマンドを実行してください。x86_64は通常amd64またはx64パッケージ、aarch64は通常arm64パッケージに対応します。パッケージ形式もディストリビューションに合わせます。DEBはDebian系、RPMはRPMを採用するディストリビューション向けです。アーキテクチャが一致していても、システム依存関係を満たすとは限りません。古いディストリビューションでは、クライアントの最低動作要件も確認してください。

uname -m
cat /etc/os-release

ダウンロードページで、Clash Verge RevやFlClashなどのLinux向け配布先と、現在の対応状況を確認できます。以下では、ダウンロード済みのファイルを使ってインストールする手順を示します。実際のパッケージ名を client.deb または client.rpm に変更し、そのファイルがあるディレクトリに移動してから、利用中のディストリビューションに合ったコマンドを1つだけ実行してください。ここに記載したファイル名はダウンロード先ではありません。

# Debian / Ubuntu：カレントディレクトリにあるDEBパッケージをインストール
sudo apt install ./client.deb

# Fedora：カレントディレクトリにあるRPMパッケージをインストール
sudo dnf install ./client.rpm

パッケージマネージャーでローカルパッケージをインストールすれば、リポジトリから取得できる依存関係もあわせて処理できます。グラフィックライブラリ、WebKit、ランタイムの不足が表示された場合は、ディストリビューションのバージョンとプロジェクトの説明を確認してください。依存関係のチェックを削除して無理にインストールしないでください。GUI環境のないサーバーでは、後述のコマンドライン手順がより簡単です。

サブスクリプション・設定・ノードの選択

  1. クライアントの「サブスクリプション」または「設定」画面を開き、「インポート」または「新規作成」を選んで、プロバイダーから提供されたサブスクリプションURLを貼り付けます。画面名はクライアントやバージョンによって異なります。設定管理画面を開くことがポイントで、URLをノード名の欄に入力するわけではありません。
  2. 更新が完了したら、読み込んだ設定を選択します。サブスクリプションのカードが表示されただけでは、設定がコアに読み込まれたとは限りません。
  3. 「プロキシ」画面を開き、まずルールモードを使って、該当するプロキシグループから利用可能なノードを選択します。サブスクリプションにノード一覧しかなく、ルールが含まれていない場合は、クライアントが対応する完全な設定、またはプロバイダーが提供する完全な設定と組み合わせてください。
  4. 「設定」から「システムプロキシ」のスイッチを探して有効にし、ブラウザーがデスクトップのプロキシ設定を使用しているか確認します。メニュー構成が異なる場合は、スイッチ名を手がかりに探してください。特定バージョンのスクリーンショット上の位置に頼らないでください。

サブスクリプションURLにはアカウントを特定できるトークンが含まれることがあるため、認証情報として扱ってください。トラブルシューティング用のスクリーンショットにはエラーの種類と発生時刻を残しつつ、サブスクリプションURL全体、ノードのパスワード、コントロールインターフェースのキーは隠してください。読み込みに失敗した場合は、まず応答内容を確認します。ログインページ、HTMLのエラーページ、通常のノードURI一覧は、mihomo用の完全なYAML設定としてそのまま使えません。

システムプロキシとTUNの違い

システムプロキシの影響を受けるのは、デスクトップのプロキシ設定を参照するアプリが中心です。コマンドラインツール、一部のゲーム、独自のネットワーク処理を行うアプリは、この設定を使わない場合があります。GNOMEでは「設定」→「ネットワーク」→「ネットワークプロキシ」、KDEでは通常「システム設定」→「ネットワーク」→「プロキシ」で確認できます。ポート番号はクライアントに表示されている値を使い、どのクライアントも7890を使うと決めつけないでください。

TUNは仮想ネットワークインターフェースとルーティングを使って通信を取り込みます。システムプロキシとは適用範囲が異なり、サービスモードやネットワーク管理権限、DNS設定も関係します。デスクトップで初めて設定する場合は、まずシステムプロキシで動作を確認し、その後クライアントのドキュメントに従ってTUNを有効にしてください。デスクトップ上のコアと別のsystemdコアを同時に起動して、同じポートを使用したりデフォルトルートを変更したりしないでください。

mihomoバイナリとサービス用アカウント

コマンドラインで導入するには、CPUアーキテクチャに合ったLinux用バイナリが必要です。amd64やarm64のほか、リリースファイルによっては命令セットや互換性レベルも異なります。古いCPUで Illegal instruction が発生した場合は、サービスを何度も再起動するのではなく、リリースノートを確認してください。該当するリリースファイルをダウンロードして展開し、実行ファイルを mihomo にリネームしてから、そのファイルがあるディレクトリに移動します。

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

-v には、実際にインストールされているコアのバージョンが表示されます。この結果を保存しておけば、設定項目に互換性がないときに該当バージョンのドキュメントを確認できます。GUIクライアントのバージョン番号だけを記録しないでください。Exec format error が表示された場合は、まずアーキテクチャと、ファイルが展開済みかを確認します。圧縮ファイルをそのまま実行ファイルとしてインストールしないでください。

専用アカウントとディレクトリの権限

ローカルでHTTP/SOCKSプロキシを7890番ポートに待ち受けるだけなら、root権限は不要です。以下では専用のシステムアカウントを作成し、設定を /etc/mihomo に、キャッシュと実行データを /var/lib/mihomo に置きます。DebianやUbuntuで一般的な /usr/sbin/nologin を使用します。ほかのディストリビューションでは、まず command -v nologin でパスを確認し、コマンドを調整してください。

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

アカウントの作成は1回だけで構いません。同じ名前のアカウントがすでにある場合は、用途と所属グループを確認してから作業し、すぐに削除して作り直さないでください。設定をrootが管理し、サービス用アカウントを読み取り専用にすれば、実行中のプロセスがサブスクリプションの認証情報を書き換えるリスクを抑えられます。一方、データディレクトリはサービス用アカウントが書き込める必要があります。権限がないと、キャッシュやルール関連リソースの更新に失敗することがあります。

config.yamlの設定とフォアグラウンドでの動作確認

最小構成と待ち受け範囲

sudoedit /etc/mihomo/config.yaml で設定ファイルを作成します。以下はサービスの動作経路を確認するための、最小限の完全な例です。すべての通信を直接接続するため、確認できるのはポートとプロセスが正常に動作することだけで、リモートのプロキシノードが利用できることは証明できません。実際に使う際は、プロバイダーが提供する、現在のmihomoバージョンに対応した完全な設定に置き換え、ローカルの待ち受け範囲を適切に制限してください。

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

rules:
  - MATCH,DIRECT

mixed-port は、同じポートでHTTPとSOCKS5のプロキシリクエストを受け付けます。DNSの待ち受けポートでも、コントロールパネルのポートでもありません。ここではLANからのアクセスを無効にし、ループバックアドレスにバインドしています。サーバーにパブリックIPアドレスがあっても、7890番ポートのインバウンド通信をファイアウォールで許可する必要はありません。

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

-t は設定のテスト、-d はデータディレクトリ、-f は設定ファイルを指定します。YAMLのインデントにタブは使えません。行番号付きのエラーが出た場合は、該当行とその直前の行について、インデント、コロン、引用符を確認してください。設定テストに通れば、設定を解析して読み込めることは確認できますが、ノードへの接続や、すべてのルール関連リソースが継続的に更新されることまでは保証されません。

完全なサブスクリプション設定の移行

完全なYAML設定がある場合は、ローカルに config.yaml として保存し、サーバーのユーザーディレクトリにアップロードしてからサービス用ディレクトリに配置します。以下では、アップロードしたファイルがカレントディレクトリにあるものとします。トークンを含むサブスクリプションURLを共有スクリプトやターミナルのスクリーンショットに直接記載しないでください。また、拡張子だけでファイルの内容が正しいと判断しないでください。

sudo install -o root -g mihomo -m 0640 \
  ./config.yaml /etc/mihomo/config.yaml

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
  • 新しい設定の mixed-port、allow-lan、bind-address を確認し、置き換えによって意図せず待ち受け範囲が広がらないようにします。
  • proxy-providers、rule-providers、または相対パスのリソースが含まれる場合は、パスとディレクトリの権限を確認してください。この記事では /var/lib/mihomo をデータの基準ディレクトリとして扱います。
  • external-controller を有効にしている場合は、そのインターフェースが本当に必要か確認し、ループバックで待ち受けるようにして強力なキーを設定してください。初回の導入時は、コントロールインターフェースの設定をいったん削除しても構いません。
  • tun、自動ルート、DNSハイジャックの設定が含まれていないか確認してください。この記事の一般ユーザー権限で動かすサービス構成では、これらの機能に必要なネットワーク管理権限を付与していません。

systemdに登録する前に、まずフォアグラウンドで一度起動してログを確認します。テストが終わったらCtrl+Cで終了し、7890番ポートを解放してからサービスを起動してください。

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

systemdでの常駐と起動時の自動起動

/etc/systemd/system/mihomo.service を作成します。これはシステムサービスなので、SSHのログインセッションに依存せず、ターミナルを切断した後もsystemdが管理します。以下のユニットは、前述の通常のプロキシモードを対象とし、専用アカウントで実行して、書き込み可能な範囲をデータディレクトリに限定します。

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

ExecStartPre は起動前に設定をテストし、失敗した場合はメインプロセスを起動しません。Restart=on-failure はプロセスが異常終了した際に再起動する設定で、無効なサブスクリプションや接続できないノードを自動的に解決するものではありません。network-online.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
sudo journalctl -u mihomo.service -b -n 80 --no-pager

enabled は起動時に有効化されている状態、active は現在実行中の状態を示します。それぞれ別に確認してください。サービスユニットを変更した場合は、daemon-reload を実行してから再起動します。YAMLだけを変更した場合は、設定をテストしてから sudo systemctl restart mihomo.service を実行してください。この記事では ExecReload を設定していないため、systemctl reload でサブスクリプションが自動的に再読み込みされるとは限りません。

プロキシの接続と疎通確認

サービスを起動しても、Linux上のすべてのプロセスが自動的にプロキシを使うわけではありません。まず待ち受け状態を確認し、次にプロキシを明示したリクエストでテストします。これにより、「コアが起動していない」状態と「アプリがプロキシを使っていない」状態を切り分けられます。以下ではリクエスト先の例として example.com を使います。応答ステータスや所要時間はネットワーク環境によって変わるため、固定のテスト結果ではありません。

sudo ss -lntp 'sport = :7890'

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

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

待ち受けアドレスは 127.0.0.1:7890 であることを確認します。HTTPプロキシ経由でHTTPSにアクセスすると、curlはCONNECTトンネルを使います。SOCKSの例にある socks5h は、接続先のドメイン名をプロキシ側で解決する指定です。最終的な名前解決と転送方法は、コアの設定や適用されるルールによって異なります。コマンドの書き方だけで、リクエストがリモートノードを経由したとは判断できません。

ターミナルの環境変数

現在のターミナルで、対応するプログラムにプロキシを使わせるには、以下の環境変数を設定します。影響するのはこのシェルと、ここから起動する子プロセスだけです。ほかのユーザーや起動済みのプログラム、既存のsystemdサービスには影響しません。独自のプロキシ設定を持つツールもあるため、各ツールのドキュメントを確認してください。

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

# 現在のターミナルで設定したプロキシ環境変数を解除
unset http_proxy https_proxy all_proxy no_proxy

https_proxy にも http:// を指定します。これは接続先がローカルのHTTPプロキシであることを表し、対象サイトへの接続が暗号化されないという意味ではありません。特定のsystemdサービスにプロキシを設定する場合は、そのサービスの設定に環境変数を追加してください。1つのプログラムのためにサーバー全体のルーティングを変更しないでください。

リモートから利用する場合のアクセス範囲

手元のPCからサーバー上のループバックプロキシを一時的に使う場合は、サーバーの7890番ポートを外部に公開せず、ローカルでSSHポートフォワーディングを設定してください。たとえばサーバーの 127.0.0.1:7890 に転送すれば、手元のプログラムは転送用ポートに接続できます。SSHホスト名には既存の接続設定を使ってください。アクセス範囲は引き続きSSHアカウントの権限で制御されます。

LAN内で共有する必要がある場合に限り、allow-lan、待ち受けアドレス、認証、ファイアウォールで許可する接続元を個別に検討してください。すべてのネットワークインターフェースで待ち受けても、接続範囲が広がるだけで性能は向上しません。特にインターネット上のサーバーでは、アクセス制御のないプロキシを公開しないでください。

起動失敗とメンテナンス時の確認

症状まず確認する項目対処方法
Exec format errorCPUアーキテクチャ・バイナリ形式Linux用の該当ファイルを選び直して展開する
Permission denied実行権限・ディレクトリ権限・ファイルパスサービス用アカウントに設定の読み取り権限とデータディレクトリの書き込み権限があるか確認
address already in use7890番ポートをすでに使用しているプロセスフォアグラウンドでのテストを終了するか、重複して起動したコアを停止
YAMLの解析エラーログの行番号・インデント・応答内容設定を修正し、HTMLやノード一覧を誤って読み込んでいないか確認
ポートは待ち受けているがリクエストに失敗するノードの状態・ルールの適用・DNS・外向き通信該当リクエストのログを確認し、直接接続とプロキシ経由を切り分ける
サービスの起動が繰り返し失敗する設定テストの結果と今回の起動ログ原因を修正してから失敗状態をリセットし、サービスを起動

トラブルシューティングでは、具体的なエラーを残し、ノード、設定、コア、ポートを一度に変更しないでください。直近のログは sudo journalctl -u mihomo.service --since "10 minutes ago" --no-pager で確認できます。systemdの起動頻度制限に達した場合は、設定の問題を修正してから sudo systemctl reset-failed mihomo.service を実行し、サービスを起動します。原因を直さず状態だけをリセットしても、再び失敗します。

アップデートとロールバック

  1. 現在の mihomo -v の出力を記録し、使用中のバイナリと設定をバックアップします。バックアップファイルにも読み取り権限の制限を設定してください。
  2. 新しいバイナリで既存の設定をテストし、バージョン間の設定項目や動作の変更を確認します。相対パスのリソースがある場合は、正式なサービスと同じデータディレクトリを指定してください。
  3. 短時間のメンテナンス時間を設け、サービスを停止してから新しいバイナリを配置します。起動後、待ち受け状態、ログ、実際のリクエストを確認してください。
  4. 新しいバージョンが正常に動作しない場合は、元のバイナリと対応する設定を戻してから再度確認します。片方だけを戻さないでください。

完全なYAML設定の更新と、サブスクリプションプロバイダーの更新は別の作業です。GUIクライアントには通常、独自のサブスクリプション更新手順があります。mihomoを単独で導入した場合、proxy-providers の更新動作は設定に依存し、systemdを使っても config.yaml 全体が自動的に置き換わるわけではありません。定期更新を追加する場合は、一時ファイルにダウンロードして正常に検証できてから置き換え、失敗時に使える旧設定を残してください。

デスクトップでは、正しい設定を選び、アプリにプロキシを適用する方法を明確にすることが重要です。コマンドラインでは、権限、設定ファイルのパス、プロセスのライフサイクルがポイントです。まずローカルのループバックプロキシで動作を確認し、その後にルールプロバイダー、リモート管理、TUNを順に追加すると、問題を切り分けやすくなります。各プラットフォームの詳細な確認方法は全プラットフォーム向けトラブルシューティングガイド、初回の読み込み手順はクイックスタートをご覧ください。