プラットフォーム導入 読了時間：約12分

Linux版Clashの導入方法｜デスクトップアプリとmihomo CLI

Linuxデスクトップアプリの導入から、GUIのないサーバーでmihomoをsystemd常駐させる方法まで解説。設定ファイルの配置やポート設定も紹介します。

1. 実行環境に合わせて導入方法を選ぶ

LinuxでClashのルールベースのプロキシを使う方法は、大きく分けて2つあります。デスクトップアプリでサブスクリプションやノード、システムプロキシを管理する方法と、mihomoのCLI版でYAMLを直接読み込み、systemdでバックグラウンド実行する方法です。mihomoはClash Metaプロジェクトで引き続き使われているコアの名称で、GUIがないと動作しないプログラムではありません。

GNOMEやKDEのデスクトップで日常的にウェブを閲覧するなら、GUIクライアントがおすすめです。デスクトップ環境のないサーバーや開発機、常時稼働するホストには、コアを直接導入できます。どちらの方法でも有効な設定が必要です。クライアントやバイナリをインストールしただけでは、プロキシノードは利用できません。

比較項目デスクトップクライアントmihomo CLI
適した環境GNOME、KDEなどのデスクトップ環境GUIのないサーバー、バックグラウンド用ホスト
設定方法設定・サブスクリプション管理画面この例では /etc/mihomo/config.yaml
ノードの選択プロキシグループ画面で操作設定のデフォルト順を指定するか、コントロールAPIで管理
自動起動クライアントの自動起動設定systemdサービス
プロキシの適用範囲システムプロキシまたはTUNまずローカルプロキシポートを使い、必要に応じてTUNを設定

2. デスクトップクライアントの導入とサブスクリプションの追加

ディストリビューション、CPUアーキテクチャ、パッケージ形式を確認する

まず次の2つのコマンドを実行します。x86_64は通常x64またはamd64パッケージ、aarch64は通常arm64パッケージに対応します。パッケージマネージャーが、異なるアーキテクチャ向けのプログラムを実行可能な形式に変換することはありません。

uname -m
cat /etc/os-release

ダウンロードセンターから、Clash Verge RevやFlClashsなど、Linux向けパッケージを提供するクライアントを選べます。UbuntuやDebianでは通常DEB、Fedoraなどでは通常RPMを使います。利用中のシステムで動作するかどうかは、各クライアントのリリースノートにあるOSとランタイムライブラリの要件も確認してください。

ここではダウンロードしたパッケージを使ってインストールします。対応アーキテクチャのパッケージ名をclient.debまたはclient.rpmに変更し、ダウンロードディレクトリに置いてください。以下のインストールコマンドはディストリビューションに合わせてどちらか一方だけ実行します。両方実行しないでください。

cd ~/Downloads

# Debian / Ubuntu：このコマンドだけ実行
sudo apt install ./client.deb

# Fedora：このコマンドだけ実行
sudo dnf install ./client.rpm

AppImageを選ぶ場合は、通常、先に実行権限を付与します。起動できるかどうかはFUSEやデスクトップ環境の依存関係にも左右されます。共有ライブラリが見つからないというエラーが出た場合は、クライアントの説明に従って依存関係を追加してください。GUIアプリ全体をrootで実行するのは避けましょう。

「追加、適用、ノード選択、プロキシ」の順に設定

  1. クライアントを起動し、「設定」または「サブスクリプション」画面でサービス提供元から入手したClash/mihomoの設定URLを追加します。メニュー名はクライアントによって異なります。また、任意のノード共有リンクを完全なYAML設定として使うことはできません。
  2. 更新後、その設定を現在使用する設定として選択します。サブスクリプション名を保存しただけではなく、ノード一覧、プロキシグループ、ルールが読み込まれていることを確認してください。
  3. プロキシグループを開き、利用可能なノードを選んで遅延をテストします。タイムアウトは、テスト先に到達できない場合も、ノードに障害がある場合もあります。実際にアクセスして状況を確認してください。
  4. ルールモードを選択してから、システムプロキシを有効にします。クライアントに表示されたローカル待ち受けポートを確認してください。後述の7890は説明用の共通例にすぎません。

GNOMEの場合は、「設定」→「ネットワーク」→「ネットワークプロキシ」で手動プロキシのアドレスを確認できます。クライアントの設定がmixed-port: 7890なら、HTTPとHTTPSのプロキシに127.0.0.1、ポートに7890を指定します。他のデスクトップ環境では設定画面の場所が異なります。

システムプロキシを設定しても、すべてのアプリの通信が自動的にプロキシ経由になるわけではありません。ブラウザーはデスクトップのプロキシ設定を参照することが多い一方、ターミナルツールやコンテナ、一部の単独アプリは参照しない場合があります。「ブラウザーは使えるがターミナルでは失敗する」場合は、まずターミナルにプロキシを明示的に設定してください。すぐに全体モードへ切り替える必要はありません。

3. mihomoコアの導入と設定ディレクトリ

バイナリと完全なYAML設定を用意する

GUIなしで導入する場合は、CPUアーキテクチャとシステム環境に合ったLinux版mihomoバイナリが必要です。アーカイブを展開し、中の実行ファイル名をmihomoに変更してください。以下のコマンドでカレントディレクトリにあるファイルをインストールし、実際のバージョンを確認します。バージョンを記録しておくと、設定項目の互換性に関する問題を調べやすくなります。

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

この例では静的な設定と実行時データを分けます。/etc/mihomo/config.yamlに完全な設定を保存し、キャッシュやルールデータなどの書き込み可能なデータは/var/lib/mihomoに保存します。専用のシステムユーザーmihomoで実行し、一般的なプロキシサービスにマシン全体の管理権限を与えないようにします。

getent passwd mihomo >/dev/null || 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

# カレントディレクトリのconfig.yamlには、用意済みの完全な設定を配置してください
sudo install -m 0640 -o root -g mihomo \
  ./config.yaml /etc/mihomo/config.yaml

同じ名前のユーザーがすでに存在する場合は、主グループとディレクトリの権限を確認してから設定してください。ユーザーやグループの前提をそのまま重ねて適用しないでください。設定にはノードの認証情報、サブスクリプションURL、コントロールキーが含まれる場合があります。ローカルの全ユーザーに読み取り権限を与えたり、公開リポジトリに置いたりしないでください。

待ち受け設定だけを追加し、ノードやルールは残す

既存の完全な設定で、次のトップレベル項目を確認してください。この断片は既存設定への追加用であり、サブスクリプション設定全体の代わりにはなりません。元のproxies、proxy-providers、proxy-groups、rulesなどは残してください。同じYAMLマッピング内で同じ項目を重複して定義しないでください。

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
tun:
  enable: false
  • mixed-portは1つのポートでHTTPプロキシとSOCKS5リクエストを受け付けますが、システム上のすべての通信が自動的にそのポートを通るわけではありません。
  • allow-lan: falseとループバックアドレスでの待ち受けを組み合わせると、ローカルからのみアクセスできます。インターネット向けのプロキシ入口にはなりません。
  • mode: ruleでは設定内のルールに従って通信を振り分けます。ルールが参照するポリシーグループが存在すること、末尾に適切なフォールバックルールがあることを確認してください。
  • 初回の導入ではTUNを無効にしておきましょう。ノード、ルーティング、DNS、権限の問題が重なるのを避けられます。

サービスアカウントで設定をチェックします。-dは実行データのディレクトリ、-fは設定ファイル、-tは設定テストを指定します。外部のルールや地理データに依存する設定では、リソースを取得できることと、パスを読み取れることも確認してください。構文チェックに成功しても、ノードへの接続が成功したとは限りません。

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

4. systemdでmihomoを常時実行する

設定チェックが通ったら、/etc/systemd/system/mihomo.serviceを作成します。以下のユニットは一般的なローカルプロキシポート向けで、TUNに必要なネットワーク管理権限は付与しません。network-online.targetは起動順序の依存関係を示すもので、ノードやインターネットへの接続を保証するものではありません。

sudo tee /etc/systemd/system/mihomo.service >/dev/null <<'EOF'
[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=0077
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF

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

active (running)は、プロセスが動作中であることを示すだけです。ログを確認し、設定の解析エラー、リソースのダウンロード失敗、address already in useがないか調べてください。クライアントも7890を使っている場合は、どちらかを終了するか、プロセスごとに異なるポートを設定します。

config.yamlを変更したら、設定テストを再実行してからサービスを再起動します。このユニットではExecReloadを定義していないため、systemctl reload mihomoで再読み込みできるとは限りません。daemon-reloadが必要なのはserviceファイルを変更した場合だけです。

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

# 直前のチェックが成功してから実行
sudo systemctl restart mihomo
sudo journalctl -u mihomo -b -n 40 --no-pager

5. ポート、ターミナルのプロキシ、ルール適用を確認する

まず待ち受けを確認し、プロキシを明示してリクエストする

最初のコマンドで7890のTCP待ち受けアドレスを確認します。127.0.0.1:7890と表示されるのが想定どおりです。外部向けアドレスや0.0.0.0が表示された場合は、待ち受け設定を見直してください。2つ目のコマンドはHTTPプロキシ経由でこのサイトにアクセスします。20秒はリクエストのタイムアウト上限であり、ノードの遅延時間ではありません。

sudo ss -lntp 'sport = :7890'

curl --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 20 \
  --output /dev/null --show-error \
  --write-out 'HTTP %{http_code}\n' \
  https://clash-system.com/

HTTPレスポンスが返れば、リクエストがローカルのプロキシ入口を通ったことは確認できます。ただし、リモートノードを経由したとは限りません。ルールによってDIRECTが選択されている可能性があります。ログで接続先ドメイン、適用ルール、実際のポリシーを確認してください。設定でプロキシグループを参照している場合は、グループ内で選択されているノードも確認します。

現在のターミナルにプロキシ環境変数を設定する

プロキシ環境変数に対応したプログラムでは、現在のシェルに次の変数を設定できます。HTTPSサイトにアクセスする場合も、HTTPプロキシのアドレスはhttp://127.0.0.1:7890とします。ツールはCONNECTでトンネルを確立するため、接続先がHTTPSだからといってプロキシURLのスキームをHTTPSに変更する必要はありません。

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1

# SOCKS5をテストし、プロキシ側でドメイン名を解決する場合
curl --proxy socks5h://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 20 \
  --output /dev/null --show-error \
  https://clash-system.com/

# 現在のターミナル環境を元に戻す
unset http_proxy https_proxy no_proxy

これらの変数が影響するのは現在のシェルと、その子プロセスだけです。すべてのsystemdサービスに自動で引き継がれるわけではなく、sudoによって削除される場合もあります。コンテナ内の127.0.0.1はコンテナ自身を指すため、ホストのループバックアドレスをそのままコンテナのプロキシ入口として使うことはできません。到達可能なアドレスとアクセス制限を別途設計してください。

6. TUN、DNS、リモート管理の注意点

通常のポートプロキシにTUNは必須ではない

TUNは仮想ネットワークデバイスとルーティングを使って通信を取り込み、システムプロキシに対応していないアプリにも適しています。カーネルのTUNサポートに加え、デバイスへのアクセス、ネットワーク管理権限、ルーティング設定が必要です。前述の低権限systemdユニットでは、tun.enableをtrueに変更するだけでは使えません。

  • まずls -l /dev/net/tunでデバイスを確認し、利用中のmihomoのドキュメントに従ってサービス権限とTUN関連の設定を行ってください。
  • リモートサーバーで自動ルーティングを有効にする前に、コンソールなどの復旧手段を用意し、SSHの管理接続に影響が出ないようにしてください。
  • DNSの問題を調べるときは、システムのリゾルバー、mihomoのDNS設定、TUNによるDNSの取り込み方法を併せて確認します。名前解決のループや上流DNSへの到達不能を防いでください。
  • デスクトップクライアントのTUNと、別のコアサービスの自動ルーティングを同時に有効にしないでください。

通常のHTTPプロキシ、SOCKS5、TUNでは、ドメイン名の解決経路がそれぞれ異なります。たとえばsocks5hでは、接続先のドメイン名をプロキシ側で解決します。ローカルでgetent hostsを実行した結果だけでは、すべてのプロキシリクエストを検証できません。「IPアドレスでは接続できるがドメイン名では失敗する」場合は、まずどの名前解決経路で問題が起きているかを切り分けてください。

コントロールAPIとプロキシポートは分けて管理する

external-controllerは管理用APIであり、ブラウザーの通信に使うHTTPプロキシではありません。一般的な例では127.0.0.1:9090を使い、mixed-port: 7890とは役割が異なります。有効にする場合は、専用の強力なsecretを設定し、ループバックアドレスでの待ち受けを維持してください。この例ではコントロールAPIをデフォルトで有効にしません。

SSHのポートフォワーディングを使うと、リモートサーバーのプロキシポートに接続できます。たとえば個人用PCで次のコマンドを実行すると、PCの17890番ポートがサーバーの7890番ポートに転送されます。このコマンドでは、SSH設定に登録済みのホスト別名proxy-serverを使います。先に個人用PCのSSH設定で、その別名に実際のホスト名とユーザー名を登録してください。

ssh -N -L 127.0.0.1:17890:127.0.0.1:7890 proxy-server

この場合、個人用PCのアプリでは127.0.0.1:17890に接続します。SSHポートフォワーディングによって、サーバー上のプロキシサービスが自動で起動したり、PCのシステムプロキシが自動で変更されたりするわけではありません。リモート接続のために7890番ポートやコントロールポートをインターネットに直接公開しないでください。

7. サブスクリプション更新とよくある問題

デスクトップクライアントには通常、サブスクリプションを更新する機能があります。一方、単独で動作するmihomoは、ローカルのYAMLを読み込むだけでリモートのサブスクリプション全体を自動更新するわけではありません。設定内のproxy-providersやrule-providersは各自の設定に従ってリソースを更新できますが、設定ファイル全体の置き換えとは異なります。

設定全体を更新するときは、まず旧ファイルを保存し、新しい内容を候補ファイルに書き込んでから、同じサービスアカウントでテストします。テストに成功したら、/etc/mihomo/config.yamlに配置してサービスを再起動してください。ネットワークからのダウンロードに一度失敗しただけで使用中の設定を上書きしないでください。ログや問い合わせにサブスクリプションURLを公開するのも避けましょう。

症状まず確認すること対処方法
Exec format erroruname -mの結果とダウンロードしたアーキテクチャ対応アーキテクチャのバイナリを展開してインストール
Permission denied実行権限、ディレクトリ権限、サービスユーザーバイナリの実行権限、設定の読み取り権限、実行データディレクトリの書き込み権限を確認
7890番ポートが使用中ssの出力に表示されたプロセス重複しているインスタンスを停止するか、待ち受けポートを変更
プロセスは動作しているがリクエストが失敗するノードの状態、ルールの適用、DNSログローカルのプロキシ入口への接続成功と、リモートノードへの接続成功を切り分ける
ブラウザーでは使えるがターミナルでは失敗するターミナルがプロキシを使用しているかcurl --proxyまたは環境変数で確認
再起動後に設定が変わるクライアントのサブスクリプション更新、サービスの-fで指定したパス設定の参照元を特定し、上書きされるファイルを直接編集しない

導入できたかどうかは、バイナリの起動、設定テストの成功、サービスの安定稼働、ループバックポートの正常な待ち受け、リクエストがコアに届くこと、ルールが想定どおり適用されることの順に確認します。この6段階を分けて検証してから自動更新やTUNを追加すると、問題の切り分けや保守がしやすくなります。

Clash最新版をダウンロード