プラットフォーム別導入 読了目安 16分

LinuxでClashのコアとデスクトップクライアントを導入：systemd常駐、ターミナルのプロキシ変数、GUIの選び方

LinuxデスクトップとCLI環境に対応。コアの配置、systemdサービス、ターミナルのプロキシ変数、GUIクライアントの選択と権限の注意点を解説します。

まず導入形態を決める：デスクトップクライアントか単体コアか

LinuxでのClash導入は、主に2つの方法に分かれます。デスクトップ環境では、設定管理、プロキシグループの切り替え、ログ確認に対応したGUIクライアントが便利です。サーバー、開発マシン、常時稼働する小型PCでは、Clash Meta（mihomo）コアを直接実行し、systemdでプロセスを管理する構成が適しています。どちらもYAML設定を読み込みますが、起動方法、権限範囲、システムプロキシへの接続方法は異なります。

利用環境 推奨構成 主なメリット 確認しておきたい点
GNOME、KDE Plasmaデスクトップ GUIクライアント サブスクリプションの取り込み、ノード切り替え、ログ確認が簡単 デスクトッププロキシ設定、トレイ対応、コアの権限
GUIのないクラウドサーバー mihomo + systemd リソース使用量を把握しやすく、自動再起動にも対応 設定パス、実行ユーザー、待受アドレス
開発用ワークステーション GUIまたは単体コア Git、パッケージマネージャー、コンテナごとにプロキシを設定可能 環境変数の適用範囲とDNSの動作
ゲートウェイまたは透過型ルーター mihomo TUNまたは透過プロキシ より多くのアプリの通信を引き受けられる ルーティングテーブル、nftables、DNS、ネットワーク権限

目的がブラウザー、Git、ターミナルコマンドをプロキシ経由にすることだけなら、まずはHTTP、SOCKS、mixedポートから始めましょう。TUNモードは仮想ネットワークインターフェースを作成してルートを変更するため適用範囲が広い一方、CAP_NET_ADMIN、DNSの引き受け、ファイアウォールとの互換性といった問題も生じます。通常のポートが安定して動作することを確認してからTUNを有効にすると、トラブルシューティングが短く済みます。

mihomoバイナリをインストールしてディレクトリを設計する

インストール前にCPUアーキテクチャを確認します。一般的なx86_64はamd64に、Raspberry Pi 4、一部のクラウドサーバー、新しい開発ボードは通常arm64に該当します。ディストリビューション名だけで判断せず、システムの実際の結果を直接確認する方が確実です。

uname -m
getconf LONG_BIT
cat /etc/os-release

uname -mの結果がx86_64ならamd64ビルド、aarch64ならarm64ビルドを選びます。対応するファイルをダウンロードして解凍したら、実際のバイナリを固定パスにインストールします。以下では、解凍後のファイル名をmihomo-linux-amd64と仮定します。

sudo install -m 0755 ./mihomo-linux-amd64 /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

プログラム、読み取り専用の設定、実行データは分けて配置するのがおすすめです。バイナリは/usr/local/bin、メイン設定は/etc/mihomo、キャッシュ、Geoデータ、プロキシプロバイダーファイル、実行状態は/var/lib/mihomoに置きます。systemdで書き込み範囲を制限しやすくなり、バイナリ更新時に設定が上書きされるのも防げます。

sudo useradd --system \
  --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
sudo install -d -m 0750 -o mihomo -g mihomo /var/lib/mihomo/providers
sudo install -m 0640 -o root -g mihomo ./config.yaml /etc/mihomo/config.yaml

まず検証可能な基本設定を用意する

ローカル利用向けの基本設定では、mixedポート7890で待ち受け、外部コントロールインターフェースをループバックアドレスに制限できます。mixedポートはHTTPとSOCKSの両方を受け付けるため、ターミナルツール、ブラウザー、デスクトップのプロキシ設定を共通で利用できます。

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

external-controller: 127.0.0.1:9090
secret: "linux-local-controller-2026"

profile:
  store-selected: true
  store-fake-ip: true

ここではプロキシノード、プロキシグループ、rulesを記載していません。これらは実際に利用できる設定またはサブスクリプションから取得する内容だからです。取り込み後は、MATCH,PROXYなどのフォールバックルール、または実際のプロキシグループ名と一致するルールが最終設定に含まれていることを確認してください。プロキシグループ名は大文字と小文字を区別します。存在しないグループをルールから参照すると、設定テストでエラーになります。

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

テストに成功すると、設定の読み込み完了を示す情報が表示されます。YAML解析エラーが出た場合は、まずインデント、コロンの後の空白、プロキシグループ名を確認します。YAMLではTabを階層インデントに使えません。設定テストに合格する前に自動再起動ループを作らないでください。ログが再起動メッセージで埋まってしまいます。

systemdサービスを作成して常駐起動を設定する

systemdユニットでは、実行ユーザー、作業ディレクトリ、再起動ポリシー、書き込みを許可するパスを明示します。通常のHTTP、SOCKSプロキシにroot権限やネットワーク管理権限は必要ありません。以下のユニットはTUNを有効にしない基本構成に適しています。

[Unit]
Description=mihomo proxy service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
ExecStartPre=/usr/local/bin/mihomo -t -f /etc/mihomo/config.yaml -d /var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -f /etc/mihomo/config.yaml -d /var/lib/mihomo
Restart=on-failure
RestartSec=5s
LimitNOFILE=1048576

NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=strict
ReadWritePaths=/var/lib/mihomo
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6

[Install]
WantedBy=multi-user.target

内容を/etc/systemd/system/mihomo.serviceとして保存し、ユニットを再読み込みして起動します。enable --nowを使うと、ブート時の自動起動と即時起動を同時に設定できるため、別途startを実行する必要はありません。

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
journalctl -u mihomo -n 80 --no-pager

ポートとコントロールインターフェースを確認する

サービスがactiveと表示されても、プロセスが動作中であることしか分かりません。7890と9090の待受アドレスも確認してください。期待される結果は127.0.0.1:7890と127.0.0.1:9090であり、すべてのネットワークインターフェースに公開する0.0.0.0ではありません。

ss -lntp | grep -E '7890|9090'
curl --max-time 5 \
  --proxy http://127.0.0.1:7890 \
  -I https://www.gstatic.com/generate_204

接続が正常なら、テストリクエストは通常0.4〜2秒で204、またはプロキシチェーンに応じたHTTPステータスを返します。5秒でタイムアウトする場合は、まずmihomoのログでプロキシグループが選択されているか確認し、次にノード接続エラーを調べます。Connection refusedが即座に表示されるなら、問題は通常リモートプロキシではなく、ローカルポートの待受にあります。

ターミナルのプロキシ変数：現在のセッション、永続設定、単一コマンド

Linuxのターミナルアプリは、mihomoが動作しているだけでは自動的にプロキシを使用しません。curl、wget、Git、言語用パッケージマネージャーがデスクトップのシステムプロキシを読み取るかどうかは、それぞれの実装によって異なります。最も汎用的な方法は、現在のShellでHTTP_PROXY、HTTPS_PROXY、ALL_PROXYを設定することです。

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,.local

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
export no_proxy="$NO_PROXY"

socks5hのhは、ドメイン名の解決をSOCKSプロキシ側に任せることを示します。ローカルDNSとプロキシ経路の不一致を減らせます。大文字と小文字の変数を両方設定するのは、ツールによって参照する変数名が異なるためです。変数は現在のShellとその子プロセスにのみ適用され、すでに開いているターミナルのタブに後から自動反映されることはありません。

適用範囲に応じて設定方法を選ぶ

  • 1つのコマンドだけをプロキシ経由にする：HTTPS_PROXY=http://127.0.0.1:7890 curl https://example.com。
  • 現在のターミナルだけをプロキシ経由にする：exportを直接実行します。セッションを閉じると無効になります。
  • Bashで永続化：~/.bashrcに書き込み、source ~/.bashrcを実行します。
  • Zshで永続化：~/.zshrcに書き込み、ターミナルを再起動するかsource ~/.zshrcを実行します。
  • Gitだけに設定：git config --global http.proxy http://127.0.0.1:7890を使用します。

現在のセッションのプロキシを解除する場合は、大文字と小文字の変数をすべて削除してください。残った値をツールが読み続けるのを防げます。

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY
unset http_proxy https_proxy all_proxy no_proxy

git config --global --unset http.proxy
git config --global --unset https.proxy

sudoはデフォルトでプロキシ環境変数を除外することがあり、systemdサービスも対話型Shellの~/.bashrcを引き継ぎません。バックグラウンドサービスにプロキシが必要な場合は、対象サービス用のdrop-inを作成し、[Service]の下にEnvironment=を設定してください。グローバルなシステム環境を変更する方法は避けます。これにより、プロキシの影響を対象サービスに限定できます。

Linuxデスクトップクライアントとシステムプロキシの接続

GUIクライアントは、サブスクリプションの取り込み、プロキシグループの切り替え、接続ログの確認を頻繁に行うデスクトップユーザーに適しています。選ぶ際は、Linuxビルドの提供、コアパスの認識、設定の保存場所、現在のデスクトップ環境への対応を確認してください。一般的な配布形式にはAppImage、Deb、RPM、アーカイブがあります。

インストール形式ごとの確認ポイント

  • AppImage：まずchmod +xを実行し、通常のデスクトップユーザーで起動します。一部の軽量システムではFUSE互換コンポーネントのインストールが必要です。
  • Deb：Debian、Ubuntuおよび派生ディストリビューションに適しています。sudo apt install ./クライアントファイル.debでインストールし、依存関係を解決できます。
  • RPM：Fedora、Rocky Linux、openSUSEなどに適しています。具体的な操作にはdnfまたはzypperを使用します。
  • アーカイブ：デスクトップエントリー、更新パス、実行権限を自分で管理する必要があります。バージョンを固定したい環境に適しています。

デスクトップクライアントには通常、「システムプロキシ」「TUNモード」「ログイン時に起動」などの切り替えがあります。ブラウザーやデスクトップのプロキシ設定に従うソフトだけを使う場合は、システムプロキシを有効にすれば十分です。GNOMEでは「設定」→「ネットワーク」→「ネットワークプロキシ」、KDE Plasma 6では通常「システム設定」→「ネットワーク」→「プロキシ」にあります。手動設定では、HTTP、HTTPS、SOCKSのホストに127.0.0.1、ポートにクライアントが表示するmixedポート（例：7890）を入力します。

GUIクライアントのコアと、前述のsystemdコアを同時に起動して、両方を7890で待ち受けさせないでください。ポートが競合すると、後から起動したインスタンスは通常address already in useを報告します。2つの環境を併用する場合は、一方を17890、17891など別のポートに変更し、外部コントロールポートも個別に確認してください。

TUNモードを有効にする際の権限とDNS設定

TUNモードは、HTTPプロキシ変数を読み取らないアプリ、たとえば一部のゲームランチャー、閉じたデスクトップアプリ、独自のネットワークスタックを使うソフトの通信も引き受けられます。mihomoは仮想ネットワークデバイスを作成してルートを変更するため、少なくともCAP_NET_ADMINが必要です。一部のネットワーク操作ではCAP_NET_RAWも使用します。サービスには必要な能力だけを付与し、プロセス全体をrootユーザーで実行する必要はありません。

sudo systemctl edit mihomoでoverride設定を作成できます。

[Service]
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW
PrivateDevices=false
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK

保存後、以下のコマンドを実行してoverride設定を反映します。

sudo systemctl daemon-reload
sudo systemctl restart mihomo
systemctl show mihomo -p AmbientCapabilities
ip address show
ip route show table all

TUN設定の主要フィールド

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-redirect: true
  strict-route: true
  dns-hijack:
    - any:53

auto-routeはルートを自動的に追加し、auto-redirectは対応するLinux環境でnftablesを利用して通信の引き受けを改善します。strict-routeは通信の迂回を減らすために使います。各フィールドが現在のシステムに適しているかは、NetworkManager、systemd-networkd、Docker、既存のファイアウォールルールとの組み合わせで判断してください。コンテナネットワーク、社内VPN、TUNはいずれもポリシールートを書き込む可能性があります。競合した場合は、有効化前後のip ruleとip route show table allを比較します。

DNSはTUNのトラブルシューティングで重要なポイントです。IPには接続できるのにドメインへアクセスできない場合は、まずresolvectl statusとresolvectl query example.comを実行します。システムのsystemd-resolvedがローカルの53番ポートを使用している場合、mihomoの通常DNSリスナーを同じアドレスとポートにバインドしないでください。127.0.0.1:1053などの高いポートを使用し、明示的なシステム設定から転送する方法があります。または、TUNのDNSハイジャックで仮想インターフェースを通過する53番ポートのリクエストを処理させます。

頻出トラブルの切り分け：プロセス、ポート、ルール結果を確認する

サービスが繰り返し再起動する

連続して再起動するのではなく、まず現在の起動サイクルのログを確認します。

systemctl status mihomo --no-pager
journalctl -u mihomo -b -n 120 --no-pager
sudo -u mihomo /usr/local/bin/mihomo \
  -t \
  -f /etc/mihomo/config.yaml \
  -d /var/lib/mihomo

よくある原因は、YAMLのインデントエラー、存在しないプロキシグループの参照、設定ファイルの権限不足、Geoデータディレクトリへの書き込み不可、別のクライアントによる待受ポートの使用です。

7890は待受中だが、ターミナルが直接接続する

設定ファイルだけでなく、現在のプロセスが実際に受け取っている変数を確認します。

env | grep -i proxy
curl --max-time 5 -I https://example.com
curl --max-time 5 --proxy http://127.0.0.1:7890 -I https://example.com

2つ目が失敗し、3つ目が成功する場合、mihomoは正常に動作しており、問題はターミナルのプロキシ変数またはアプリ自身の設定にあります。両方とも失敗する場合は、ログにあるDNS、ハンドシェイク、ノードのタイムアウト情報を確認します。

サブスクリプションは更新されたが、ノード一覧が変わらない

プロキシプロバイダーファイルは、/var/lib/mihomo/providersなど、mihomoユーザーが書き込めるディレクトリに置きます。ファイルの更新時刻、providerのヘルスチェック結果、サブスクリプションのレスポンス内容を確認してください。systemdのProtectSystem=strictは、ReadWritePathsに含まれないディレクトリへの書き込みを阻止します。そのため、動的なproviderファイルを読み取り専用の/etc/mihomoに置かないでください。

TUN有効化後にLANまたはコンテナへ接続できない

まず TUN を無効にし、mixed ポートが引き続き機能することを確認してから、TUN の有効化前後でルーティングとルールを比較します。LAN のサブネットには通常、192.168.0.0/16、10.0.0.0/8、172.16.0.0/12 などのダイレクト接続ルールが必要です。Docker では 172.17.0.0/16 がよく使われますが、実際のサブネットは docker network inspect の出力を基準にしてください。すべてのホストで同じだと仮定してはいけません。

更新とロールバック：設定とプログラムを分離して管理する

コアを更新する前に現在のバージョンを記録し、動作中のバイナリを保持します。設定とプログラムが分離されているため、ロールバックでは旧バイナリを戻してサービスを再起動するだけで済み、/etc/mihomo/config.yamlやproviderデータを上書きする必要はありません。

/usr/local/bin/mihomo -v
sudo cp /usr/local/bin/mihomo /usr/local/bin/mihomo.previous
sudo systemctl stop mihomo
sudo install -m 0755 ./mihomo-linux-amd64 /usr/local/bin/mihomo
sudo -u mihomo /usr/local/bin/mihomo \
  -t \
  -f /etc/mihomo/config.yaml \
  -d /var/lib/mihomo
sudo systemctl start mihomo

新しいバージョンが起動しない場合は、sudo install -m 0755 /usr/local/bin/mihomo.previous /usr/local/bin/mihomoを実行してから再起動します。アップグレード後は、ログ、ポート、プロキシグループの選択、実際のネットワークリクエストを確認してください。バージョン番号が変わっただけでは、完全な動作確認の代わりにはなりません。

Clashクライアントをダウンロード