環境別セットアップ 読了目安 14分

Linux版Clashの導入：デスクトップクライアントとGUIなしmihomoサービスの設定

GUIクライアントとコマンドライン版カーネルの導入経路を分けて整理し、設定ディレクトリ、systemdサービス、プロキシ環境変数、ログ確認を解説します。2つの起動経路を混同しないためのガイドです。

まず導入経路を決める：デスクトップクライアントかmihomoサービスか

Linuxで「Clashをインストールする」とき、実際には2つの異なる導入経路があります。1つ目は、GNOME、KDE Plasma、Xfceなどのデスクトップ環境にGUIクライアントを導入する方法です。サブスクリプションの追加、設定の切り替え、カーネルの起動、システムプロキシ、ログ表示をクライアントが管理します。2つ目は、サーバー、ホームルーター、開発マシン、GUIのないホストでmihomoカーネルを直接実行し、systemdでプロセスを管理する方法です。どちらも似たYAML設定を使えますが、操作の入口、権限の範囲、障害の切り分け方は異なります。

導入方式 適した環境 設定の入口 プロセス管理 通信の取り込み
デスクトップクライアント 日常利用のデスクトップ、開発用ワークステーション クライアント画面と設定ディレクトリ クライアント自身 システムプロキシまたはTUN
mihomoサービス サーバー、GUIなしホスト、透過ゲートウェイ YAMLファイルを手動で管理 systemd 環境変数、明示的プロキシ、またはTUN

デスクトップクライアントとmihomoは、互いに置き換えて呼べる同じ階層の製品ではありません。クライアントは画面、更新、設定管理を提供し、mihomoは設定を読み込んでプロキシ、DNS、ルールを実行するカーネルです。クライアントによってはmihomoを内蔵していたり、カーネルのバージョンを選べたりします。デスクトップクライアントですでにカーネルを起動している場合、同じポートを待ち受けるsystemdサービスを同時に起動しないでください。通常、address already in useが発生します。

Linuxデスクトップクライアント：導入後にカーネルと設定ディレクトリを確認

ディストリビューションに合ったパッケージを選ぶ

Debian、Ubuntu、Linux Mintなどでは通常.deb、Fedora、RHEL系、openSUSEでは.rpmを使います。その他のディストリビューションでは、クライアントが提供するAppImageやアーカイブを選べます。ダウンロード前にuname -mでアーキテクチャを確認してください。x86_64はamd64またはx64、aarch64はarm64に対応します。パッケージ形式とCPUアーキテクチャの両方を一致させる必要があります。

uname -m

# Debian、Ubuntuでローカルのdebをインストール
sudo apt install ./client-linux-amd64.deb

# Fedoraでローカルのrpmをインストール
sudo dnf install ./client-linux-x86_64.rpm

初回起動後は、クライアントの「設定」→「カーネル設定」または「設定」→「パラメーター設定」を開き、現在のカーネル名、カーネルバージョン、作業ディレクトリを確認します。クライアントによってメニュー名は多少異なりますが、確認すべきなのはカーネル、設定ディレクトリ、待ち受けポート、ログの4項目です。「クライアントのバージョン」と「カーネルのバージョン」を混同しないでください。ルールやDNSの互換性を調べるときは、両方を記録します。

サブスクリプションの追加だけでは通信はプロキシに流れない

  1. 「設定」または「サブスクリプション」画面にサブスクリプションURLを貼り付け、インポートを実行します。
  2. インポートした設定を選択し、クライアントが解析を完了してカーネルを起動するまで待ちます。
  3. 「プロキシ」画面でプロキシグループを選択します。設定内のPROXYは通常、プロキシグループ名であり、固定された組み込み出口ではありません。
  4. 必要に応じて「システムプロキシ」または「TUNモード」を有効にします。両者が取り込める通信範囲は異なります。
  5. ログを確認し、ポートの競合、YAMLの解析エラー、DNSの初期化エラーがないことを確認します。

システムプロキシは通常、デスクトップ環境にHTTPおよびSOCKSプロキシの設定を書き込み、システムプロキシに従うブラウザーやGUIアプリに適しています。TUNモードは仮想ネットワークインターフェースを使って、より広い範囲の通信を取り込みますが、管理者権限、ネットワーク機能、追加のDNS設定が必要になる場合があります。サブスクリプションを追加しただけで通信の入口を有効にしていない場合、カーネルが動作していてもアプリが自動的にプロキシを使うことはありません。

ポートでクライアントが実際にカーネルを起動したか確認する

Clash系の設定では、混合プロキシポートに7890を使うことが多く、HTTPに7890、SOCKSに7891を個別に割り当てる場合もあります。これらはあくまで一般的な値なので、最終的には現在の設定とクライアントの画面を確認してください。ssで待ち受けプロセスを確認できます。

ss -lntp | grep -E '7890|7891|9090'

# ローカルHTTPプロキシ経由でテスト
curl -I -x http://127.0.0.1:7890 https://example.com

# SOCKS5経由で、プロキシ側に名前解決させる
curl -I --proxy socks5h://127.0.0.1:7891 https://example.com

curlは成功するのにブラウザーが失敗する場合は、ブラウザー独自のプロキシ拡張機能やデスクトップのシステムプロキシを確認します。ブラウザーは成功するのにターミナルが失敗する場合は、ターミナルの環境変数を確認してください。アプリによってプロキシの入口が完全に分かれていることがあり、ルールモードを切り替えても入口の設定の代わりにはなりません。

GUIなしホスト：mihomoバイナリと作業ディレクトリを準備

固定ディレクトリと専用アカウントを作成する

サーバーでは、バイナリ、設定、実行状態を分離します。以下の例では、プログラムを/usr/local/bin/mihomo、メイン設定を/etc/mihomo/config.yaml、実行時データを/var/lib/mihomoに配置します。専用のシステムアカウントを使うことで、通常のプロキシサービスがアクセスできるファイル範囲を制限できます。

sudo install -m 0755 mihomo /usr/local/bin/mihomo
sudo useradd --system --home /var/lib/mihomo --shell /usr/sbin/nologin mihomo
sudo install -d -o mihomo -g mihomo /etc/mihomo
sudo install -d -o mihomo -g mihomo /var/lib/mihomo
sudo install -m 0640 -o mihomo -g mihomo config.yaml /etc/mihomo/config.yaml

ディストリビューションによってはnologinが/sbin/nologinにあります。まずcommand -v nologinを実行してパスを確認してください。設定でGeoIP、GeoSite、ルールセット、証明書ファイルを参照する場合は、mihomoアカウントに対象ファイルの読み取り権限があることも確認します。設定で相対パスを使う場合、通常はmihomoの作業ディレクトリが基準になります。そのため、systemdのWorkingDirectoryと起動パラメーターを一致させる必要があります。

設定をテストしてからsystemdに渡す

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

-tは設定のテスト、-dは実行ディレクトリの指定、-fは設定ファイルの指定に使います。テストに合格しても、現在のカーネルが設定を解析できることしか確認できません。すべてのノードに接続できることや、システム通信がプロキシに流れていることを意味するわけではありません。mihomoを更新した後やルールプロバイダーを変更した後は、テストを再実行してからサービスを再起動します。

systemdでmihomoサービスを管理する

基本的なプロキシサービスユニット

HTTP、SOCKS、またはmixed-portだけを提供する場合、通常はTUN権限は必要ありません。/etc/systemd/system/mihomo.serviceを作成します。

[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 -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=5
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

保存後、systemdの設定を再読み込みして起動します。

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

ExecStartPreは起動のたびにYAMLを検証します。テストに失敗するとメインプロセスは起動しません。再起動操作では古いプロセスがすでに終了している可能性もあるため、本番環境で設定を変更する前には、必ずテストコマンドを手動で実行してください。Restart=on-failureは異常終了への対応に適していますが、無効な設定や他のプロセスによるポート占有を修正するものではありません。

TUNを有効にする場合だけネットワーク権限を追加する

mihomoのTUN設定は、一般的に次のような構成です。利用できるフィールドは、現在のmihomoのバージョンとシステムのネットワークスタックによって異なります。古い設定を移行する場合は、使用するバージョンのドキュメントを確認してください。

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

専用アカウントでTUNを動かす場合、通常はCAP_NET_ADMINが必要です。また、ホストに/dev/net/tunが用意されていなければなりません。サービスの[Service]セクションに次を追加できます。

AmbientCapabilities=CAP_NET_ADMIN
CapabilityBoundingSet=CAP_NET_ADMIN
DeviceAllow=/dev/net/tun rw

サービスを変更したら、sudo systemctl daemon-reloadとsudo systemctl restart mihomoを実行します。その後、ip link、ip route、サービスログで仮想インターフェースとルートを確認します。コンテナ環境では、ホストからコンテナにTUNデバイスとネットワーク管理機能を渡す必要があります。コンテナ内でYAMLだけを変更しても、ホスト側のデバイスや権限制限を越えることはできません。

プロキシ環境変数：ターミナルのプログラムからmihomoを使う

現在のターミナルだけ一時的に有効にする

TUNを有効にしていない場合、コマンドラインのプログラムでは通常、明示的なプロキシ指定が必要です。mihomoがローカルのmixed-port 7890で待ち受けているとすると、次のように設定できます。

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 https://example.com

変数名には大文字と小文字の両方の表記があり、読み取る方法はプログラムによって完全には統一されていません。特定のツールとの互換性が必要なら、HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXYを同時に設定できます。ただしCGIなどの環境では、大文字のHTTP_PROXYに追加のセキュリティ上の制約があります。サーバー全体に設定する前に、実際の実行環境を確認してください。

socks5hのhは、プロキシ側でドメイン名を解決することを示します。socks5では、アプリがローカルで名前解決してからIPアドレスをプロキシへ渡す場合があり、DNSの経路が変わります。DNSの問題を診断するときは、socks5とsocks5hのどちらを使ったかを明確に記録してください。

Git、APT、systemdサービスを個別に設定する

Gitは現在のシェルに依存せず、独自の設定を使えます。

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 確認
git config --global --get http.proxy

# 削除
git config --global --unset http.proxy
git config --global --unset https.proxy

APTでは/etc/apt/apt.conf.d/80proxyでプロキシを指定できます。

Acquire::http::Proxy "http://127.0.0.1:7890";
Acquire::https::Proxy "http://127.0.0.1:7890";

別のsystemdサービスでmihomo経由の通信が必要な場合、ログインシェルの変数を引き継ぐとは限りません。systemctl edit サービス名でオーバーライド設定を作成します。

[Unit]
After=mihomo.service
Wants=mihomo.service

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,::1"

保存後、sudo systemctl daemon-reloadを実行して対象サービスを再起動します。Afterは起動順序だけを指定し、Wantsは弱い依存関係を示します。どちらも、mihomoの特定プロキシノードへの接続確認が完了するまで待機するものではありません。起動時にネットワーク接続が必須のタスクには、アプリ側の再試行機能を追加してください。

ポート、ルール、コントロールインターフェースを設定する

最小限の待ち受け設定と注意点

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

external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"

rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,PROXY

mixed-portはHTTPとSOCKSの接続を同時に受け付けます。allow-lan: falseはローカルホストだけで使う場合に適しています。LAN内のデバイスからアクセスする必要がある場合は、待ち受けアドレス、ファイアウォール、アクセス範囲も同時に設定してください。external-controllerはコントロールインターフェースであり、プロキシポートではありません。例ではループバックアドレス127.0.0.1:9090にバインドしています。コントロールキーは実際のランダムな値に変更し、信頼できないネットワークへ直接公開しないでください。

ルールは上から順に評価され、最初に一致した項目で接続先が決まります。DIRECTは直接接続、REJECTは拒否を表します。PROXYは設定内に定義済みのプロキシグループに対応していなければなりません。no-resolveは、そのIPルールで積極的にドメイン名を解決しないことを示すもので、すべてのDNSを無効にするという意味ではありません。

サブスクリプションの更新とローカル上書きを分ける

GUIクライアントには通常、独自のサブスクリプションキャッシュ、実行用設定、上書き機能があります。生成後の実行ファイルを手動で編集しても、次回更新時に上書きされる可能性があります。GUIなしのmihomoは、サブスクリプションURLを完全な本番設定として自動的に扱うわけではありません。専用の更新スクリプト、設定生成ツール、プロキシプロバイダーでダウンロードと変換を行い、その後にテスト、置き換え、再読み込みを実行します。

  1. リモートの内容は、現在の設定へ直接上書きせず、一時ファイルにダウンロードします。
  2. プロキシグループ名、ルールの参照先、DNSフィールド、ルールプロバイダーのパスを確認します。
  3. 現在実行中のmihomoバイナリで-tテストを実行します。
  4. テストに合格したら設定ファイルをアトミックに置き換えます。
  5. サービスを再起動し、直近100行のログと待ち受けポートを確認します。

ログとトラブル対処：プロセス、ポート、入口を順に確認する

systemdサービスの起動に失敗する

systemctl status mihomo --no-pager
sudo journalctl -u mihomo -b --no-pager
sudo journalctl -u mihomo -f
  • YAMLの行番号やフィールドエラーが表示された場合は、まず設定テストを実行し、インデントと現在のカーネルが対応するフィールドを確認します。
  • permission deniedが表示された場合は、設定、ルールセット、作業ディレクトリ、/dev/net/tunの権限を確認します。
  • address already in useが表示された場合は、ss -lntpで7890、7891、9090を使用しているプロセスを特定します。
  • サービスが何度も再起動する場合は、再起動回数だけでなく、最初に失敗したときのログを確認します。
  • TUNの起動に失敗した場合は、カーネルモジュール、デバイスノード、systemdのcapability、ルート設定の権限を確認します。

ポートは開いているのにリクエストが失敗する

まずローカルプロキシ経由でリクエストを送り、アプリ側の設定問題を切り分けます。次にmihomoのログで接続先、適用されたルール、最終的なポリシーを確認します。ログにリクエストがまったく出ない場合、通常は通信がプロキシポートまで届いていません。リクエストは記録されているのにポリシーが想定と違う場合は、ルールの順序とプロキシグループの選択を確認します。ポリシーが正しいのに接続がタイムアウトする場合は、ノードの利用可否、サーバー時刻、DNS、上流ネットワークを確認します。

# HTTPプロキシの入口
curl -v -x http://127.0.0.1:7890 https://example.com

# SOCKSプロキシの入口、リモートで名前解決
curl -v --proxy socks5h://127.0.0.1:7890 https://example.com

# ローカルのルートを確認
ip route

# DNSの状態を確認、systemd-resolved向け
resolvectl status

mihomoが別のホストで動作している場合は、テスト先をそのホストのLAN内IPアドレスに変更し、allow-lan、待ち受けアドレス、ファイアウォールルールを確認します。コントロールポート9090をHTTPプロキシポートとして使わないでください。また、SOCKSのURLをHTTPのURLとして記述しないでください。

デスクトップクライアントとsystemdが競合する

同じLinuxワークステーションにデスクトップクライアントとsystemdサービスの両方を設定する場合は、常駐実行を担当するものを1つに絞ることをおすすめします。systemctl disable --now mihomoを実行してシステムサービスを停止してからデスクトップクライアントを起動するか、デスクトップクライアントを終了し、カーネルプロセスが停止したことを確認してからsystemdを起動します。クライアントウィンドウを閉じただけではトレイプロセスが終了していない場合があるため、待ち受けポートとプロセスのコマンドラインを再確認してください。

導入後のチェックリスト

  • クライアントのバージョンとmihomoカーネルのバージョンを記録し、現在どちらがカーネルを起動しているかを明確にします。
  • 設定ファイル、実行ディレクトリ、ルールセットファイルを実行アカウントが読み取れることを確認します。
  • mihomo -tで現在の設定をテストします。
  • ss -lntpでプロキシポートとコントロールポートに競合がないことを確認します。
  • curl -xまたはcurl --proxyで明示的なプロキシ入口を検証します。
  • ターミナルの変数、Git、APT、systemdの環境変数を、アプリごとに設定します。
  • TUNを有効にした後、仮想インターフェース、デフォルトルート、DNS、SSHの戻り経路を確認します。
  • サブスクリプションやカーネルを更新した後は、設定を再テストして起動ログを確認します。

Linuxデスクトップでの導入では、クライアントに設定、カーネル、システムの入口を一元管理させることが重要です。GUIなしの導入では、mihomoを通常のシステムサービスとして管理します。「設定を追加した」「カーネルが待ち受けている」「アプリがプロキシを指定している」「TUNが通信を取り込んでいる」という4つの状態を常に区別すれば、ポート競合やプロキシが有効にならない問題の大半を避けられます。

Clash をダウンロード プラットフォームに合うクライアントを選択