2026-09-27 · プラットフォーム別導入 · 読了時間：約13分

Ubuntuでmihomoを導入する方法｜GUIクライアントとsystemdによるCLI運用

UbuntuでのGUIクライアントの導入方法と、サーバー向けのmihomo単体運用を解説。実行ファイルの配置、config.yamlの保存先、systemdの設定、TUNに必要な権限を紹介します。

導入方法を選ぶ：GUIクライアントかmihomo単体か

mihomoはYAML設定を読み込み、プロキシルールを適用して接続を確立するコアエンジンで、Clash Metaとも呼ばれます。GUIクライアントはその外側に、サブスクリプション管理、プロキシグループの切り替え、システムプロキシ、ログ表示などの機能を提供します。mihomoの実行ファイルをインストールしただけではGUIは表示されず、Ubuntuデスクトップのネットワークプロキシも自動では変更されません。

以下のコマンドは、Ubuntu 22.04 LTS／24.04 LTSで一般的なsystemd環境を想定しています。コンテナ、WSL、制限のあるVPSではデバイス権限が異なる場合があり、特にTUNが利用できるか個別に確認が必要です。この記事ではmihomoのバージョンを固定していません。導入時に mihomo -v で実際のバージョンを記録し、設定の互換性を調べやすいよう、アップグレード後もバージョン情報を残してください。

利用環境	おすすめの方法	管理する項目
GNOMEデスクトップを日常的に使用	GUIクライアント	サブスクリプション、システムプロキシ、クライアントのサービスモード
GUIのないUbuntuサーバー	mihomoとsystemd	設定ファイル、サービスアカウント、ログ、起動順序
一時的なターミナル作業	ローカルプロキシのポート	コマンドごとにプロキシを指定。TUNの有効化は不要

同じマシンでは、まずどちらか一方の方法を選んでください。GUIクライアント内蔵のコアとsystemdサービスを同時に起動すると、7890ポートを取り合ったり、TUNルートが重複して作成されたりすることがあります。

Ubuntuデスクトップへのクライアント導入と設定の読み込み

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

まずターミナルで次のコマンドを実行します。x86_64は通常amd64パッケージ、aarch64は通常arm64パッケージに対応します。デバイスのブランド名だけでアーキテクチャを判断しないでください。

uname -m
dpkg --print-architecture
lsb_release -ds

クライアントのダウンロードページで、Clash Verge RevなどLinux版が提供されているクライアントを選び、現在のUbuntuリリースに必要な依存関係を確認します。Ubuntuでは、対応するアーキテクチャの.debパッケージがおすすめです。ダウンロード先のディレクトリで sudo apt install ./ に続けて実際のファイル名を指定します。Tabキーで補完できます。この方法なら、aptが利用可能な依存パッケージを処理します。AppImageも選択肢の一つです。FUSE互換パッケージが必要かどうかはクライアントのリリースノートで確認し、Ubuntuのバージョンをまたいで同じ依存関係のコマンドを使わないでください。

サブスクリプション、システムプロキシ、ブラウザーでの確認

クライアントの設定またはサブスクリプション画面を開き、信頼できるURLまたはローカルのYAMLファイルを読み込みます。サブスクリプションURLには通常アクセス用の認証情報が含まれるため、公開スクリーンショットやチケット、Gitリポジトリに載せないでください。
読み込んだ設定を選び、プロキシグループから利用可能なノードを選択します。まずはRule（ルール）モードを使いましょう。ルールモードではルールに従って接続先が選ばれ、すべての通信がプロキシ経由になるわけではありません。
クライアントの設定で実際のHTTPポートまたはmixed-portを確認してから、システムプロキシを有効にします。ポート番号はクライアント側で上書きされることがあるため、サブスクリプションの設定値だけを見て判断しないでください。
ブラウザーで対象サイトを開き、クライアントの接続ログで適用されたルール、プロキシグループ、接続先を確認します。

GNOMEのプロキシを手動で設定する場合は、Ubuntuの「設定」→「ネットワーク」→「ネットワークプロキシ」で手動設定を選びます。ローカルのmixed-portが7890の場合、HTTPとHTTPSのプロキシホストにはどちらも127.0.0.1、ポートにはどちらも7890を指定します。HTTPSプロキシ欄は、HTTPSリクエストに使用するプロキシの接続先を示すもので、このローカルポート自体がTLSを提供する必要はありません。

デスクトップのシステムプロキシ設定が反映されるのは、その設定に従うアプリだけです。ターミナルのツール、コンテナ、一部のアプリはGNOMEのプロキシ設定を自動では使用しません。クライアントの設定ディレクトリが必ず~/.config/mihomoにあるとは限りません。クライアントの「設定フォルダーを開く」機能を使い、元のサブスクリプション、マージ用テンプレート、実行時設定を区別してください。次回のサブスクリプション更新で上書きされるファイルの編集は避けましょう。

CLIで導入する：実行ファイルとディレクトリの権限

サーバーでは、実行ファイルを/usr/local/bin/mihomo、設定ファイルを/etc/mihomo/config.yaml、実行データを/var/lib/mihomoに配置します。こうして分けると書き込み権限を制限しやすく、ログインユーザーによってサービスの作業ディレクトリが変わることも防げます。

mihomoを配置してサービスアカウントを作成する

CPUアーキテクチャに合った公式リリースの実行ファイルを用意します。gzip圧縮ファイルをダウンロードした場合は、先に展開してください。以下では、展開後のファイルが/tmp/mihomoに配置済みであることを前提とします。このファイルは実行可能なバイナリでなければならず、圧縮ファイルやダウンロード失敗時に保存されたHTMLページではありません。古いCPUに対応しない命令セット向けのビルドを無理に使用しないでください。

file /tmp/mihomo
sudo install -m 0755 /tmp/mihomo /usr/local/bin/mihomo
/usr/local/bin/mihomo -v

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

アカウント作成コマンドは一度だけ実行します。同じ名前のアカウントがすでにある場合は、id mihomoで用途を確認し、既存サービスの実行ユーザーを安易に変更しないでください。設定ファイルの所有者はrootとし、mihomoグループには読み取り権限を付与します。実行データディレクトリはサービスアカウントの書き込みを許可し、キャッシュや必要なルール・データベースファイルなどを保存できるようにします。

起動確認用の最小設定を作成する

sudoedit /etc/mihomo/config.yamlを使い、以下の内容を書き込みます。この設定はローカルでの待ち受けとルール処理を確認するためのもので、すべての接続はDIRECT（直接接続）となり、リモートプロキシ機能はありません。実際に使う際は、実在するノード、プロキシグループ、ルールを含む信頼できる完全な設定に置き換えてください。サブスクリプションURLだけを貼り付けても設定にはなりません。

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

rules:
  - MATCH,DIRECT

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

-fは設定ファイル、-dは実行データディレクトリを指定し、-tは設定を検証します。検証に通っても、現在のコアが設定を読み込めることを示すだけで、ノードへの接続やルールの動作が正しいとは限りません。完全な設定で外部ルールセット、Geoデータ、ローカルファイルを参照する場合は、パス、ダウンロード条件、サービスアカウントの読み取り権限も確認してください。

systemdサービスファイルと自動起動の設定

sudoedit /etc/systemd/system/mihomo.serviceでサービスを作成します。以下は通常のローカルプロキシモードで、ネットワークデバイスを作成する権限は付与しません。独立したアカウントで実行すれば、7890のような非特権ポートを待ち受けるだけのためにrootを使わずに済みます。

[Unit]
Description=mihomo proxy core
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=5s
UMask=0027
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/mihomo

[Install]
WantedBy=multi-user.target

ProtectSystem=strictはサービスによるファイルシステムへの書き込みを制限し、書き込みを許可するのは指定した実行データディレクトリだけです。継続的に更新するproviderファイルを/etc/mihomoに置かないでください。設定では/var/lib/mihomo内のパスを使用できます。network-online.targetが実際にどのように待機するかは、システムのネットワーク管理サービスによって異なります。外部のサブスクリプションサーバーに接続できることを保証するものではありません。

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
sudo journalctl -u mihomo -b -n 80 --no-pager
sudo ss -lntp 'sport = :7890'

通常、サービスの状態はactive (running)となり、ローカルプロキシが待ち受けていることを確認できます。ログにaddress already in useと表示されたら、まずポートを使用しているGUIクライアントや古いプロセスを特定してください。強制終了コマンドをすぐに実行したり、解決のために全ネットワークインターフェースで待ち受ける設定に変えたりしないでください。

ターミナルでの動作確認と設定の更新

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

このコマンドはプロキシのアドレスを明示するため、「アプリがプロキシを使っていない」のか「プロキシコアの処理に失敗している」のかを切り分けるのに役立ちます。この記事の最小設定では、リクエストはローカルから対象サイトへ直接接続されます。実際の設定に置き換えた後は、ログで接続先を確認してください。HTTPステータスコードだけでノードが機能しているとは判断できません。

YAMLを変更したら、まず-tを付けた検証コマンドを再実行し、次にsudo systemctl restart mihomoを実行します。このサービスにはExecReloadを設定していないため、systemctl reloadが有効だとは限りません。unitファイルまたはdrop-inを変更した場合に限り、追加でdaemon-reloadを実行します。再起動すると既存の接続が切れることがあるため、サーバーでは適切な時間帯を選んでください。

TUNモード：デバイス、権限、DNSの取り扱い

TUNは仮想ネットワークインターフェースを使う方式で、システムプロキシに従わないアプリの通信を取り込むのに適しています。通常のHTTPプロキシポートの別名ではなく、Ubuntuサーバーを自動的にLANゲートウェイにする機能でもありません。ゲートウェイとして転送するには、IPフォワーディング、ファイアウォール、他のデバイスのルーティング設定も必要です。これらはローカルマシンの通信を取り込む設定の範囲外です。

TUNデバイスが利用できることを確認する

ls -l /dev/net/tun
sudo modprobe tun

デバイスが見つからず、モジュールの読み込みにも失敗する場合は、ホスト側でTUNが提供されているか確認します。コンテナでは通常、ホスト側からデバイスを渡し、ネットワーク管理権限を付与する必要もあります。サービス権限の設定を避けるために、/dev/net/tunを全ユーザーが書き込める権限に変更しないでください。

root以外で実行するサービスにネットワーク権限を付与する

sudo systemctl edit mihomoを実行し、以下のdrop-inを記述します。CAP_NET_ADMINはネットワークインターフェースやルートの操作に、CAP_NET_RAWは関連するrawソケット操作に使われます。これらの権限は、TUNが本当に必要なサービスにだけ付与してください。

[Service]
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW

ここではsystemdがプロセスの起動時に権限を付与するため、バイナリにsetcapを実行する必要はありません。この記事の基本unitではPrivateDevices=trueを有効にしていません。独自にデバイス分離やデバイスアクセスの許可リストを追加する場合は、サービスから/dev/net/tunにアクセスできることを必ず確認してください。

TUNとDNSの設定を追加する

既存のYAMLのトップレベルに以下のフィールドを追加します。すでにdnsまたはtunがある場合は既存のセクションに統合し、同じトップレベルキーを重複して定義しないでください。この例ではDNSをローカルの1053ポートで待ち受けます。Ubuntuで一般的なsystemd-resolvedのローカルDNSエンドポイントを直接使用しないためです。

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 1.1.1.1

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

auto-routeはルートの自動設定を要求し、auto-detect-interfaceは外向きのインターフェースを自動検出します。DNSの例ではパブリックDNSサーバーを指定していますが、実際のネットワークから到達できるか確認し、必要に応じて変更してください。すべてのネットワークで使える固定の設定ではありません。fake-ipが返すのはコア内部の対応付けに使う仮想IPアドレスであり、接続先サイトの実際のIPアドレスではありません。

dns-hijackは、該当するTUN経路に入った53番ポートのDNSリクエストを処理します。アプリ内蔵のDoH（暗号化DNS）を自動検出して取り込む機能ではありません。dns.enableを有効にしただけで、システムのすべてのDNSリクエストがコアを経由するわけでもありません。トラブル対処のために/etc/resolv.confを削除したり、システムの名前解決サービスを停止したりしないでください。まず実際のDNSとルーティングの経路を確認しましょう。

sudo -u mihomo /usr/local/bin/mihomo \
  -t -d /var/lib/mihomo -f /etc/mihomo/config.yaml
sudo systemctl daemon-reload
sudo systemctl restart mihomo
sudo journalctl -u mihomo -b -n 100 --no-pager
ip link show
ip rule show
resolvectl status

SSH経由でリモートサーバーを操作している場合、自動ルーティングによって管理用接続に影響することがあります。TUNを有効にする前に、クラウド管理コンソールなど別経路から操作できる手段を確保し、設定のバックアップとサービス停止方法を確認してください。GUIクライアントのTUN、mihomo単体のTUN、ほかのVPNのデフォルトルートを同時に重ねないでください。

よくあるトラブルとメンテナンスの手順

起動しない場合：ファイルとネットワークの問題を切り分ける

Exec format error：アーキテクチャの不一致、または圧縮ファイルを実行しようとした場合によく発生します。fileの出力とuname -mをもう一度確認してください。
Permission denied：設定ファイルと上位ディレクトリのアクセス権を確認します。ログインユーザーで実行できても、mihomoサービスアカウントがファイルを読み取れるとは限りません。
設定を読み込めるのにルールセットの読み込みに失敗する：providerのパス、ネットワークアクセス、データディレクトリの書き込み権限を確認します。ProtectHome=trueを使用している場合、個人のホームディレクトリにあるサブスクリプションファイルは参照しないでください。
TUN operation not permitted：デバイスの有無、drop-inの読み込み状況、実行環境でネットワーク管理権限が許可されているかを順番に確認します。systemctl cat mihomoで統合後のunitを確認できます。

ブラウザーでは使えるのに、ターミナルやコンテナでは使えない

多くの場合、原因はアプリごとにプロキシの設定元が異なることであり、コアの起動失敗ではありません。環境変数に対応したターミナルツールなら、HTTPS_PROXY=http://127.0.0.1:7890をコマンドごとに指定できます。curl --proxyを使うと、より明確に動作を確認できます。コンテナ内の127.0.0.1はコンテナ自身を指し、Ubuntuホストではありません。到達可能なアドレスとアクセス制御を別途設定してください。

通常はallow-lan: falseのままにし、GUI管理画面のために制御インターフェースをインターネットへ直接公開しないでください。リモート管理が必要な場合は、認証付きのアクセス方法と制限されたネットワーク経路を利用し、ファイアウォールも確認します。HTTPプロキシポートと制御APIポートは用途が異なり、互いに置き換えることはできません。

アップグレードとサービスの停止

アップグレード前に、現在の実行ファイルと設定を復元できる形でバックアップします。サービスを停止して実行ファイルを置き換えた後、新しいバージョンを確認し、設定の検証と起動確認を行ってください。ログには接続先のドメインや接続情報が含まれることがあります。共有前にサブスクリプションの認証情報など、機密情報を削除してください。

sudo systemctl stop mihomo
sudo systemctl disable mihomo
systemctl is-enabled mihomo

最後のコマンドの結果がdisabledなら、自動起動が解除されたことを示します。設定ファイルが削除されたわけではありません。GNOMEの手動プロキシやターミナルのプロキシ環境変数を設定していた場合は、それらも解除してください。残したままでは、アプリが停止済みの127.0.0.1:7890に接続し続けます。デスクトップではクライアントにシステム連携を任せ、サーバーではファイルの場所、サービスの実行ユーザー、ルーティングの範囲を明確にすると、プロキシモードを何度も切り替えるより問題を特定しやすくなります。