· Clash や Mihomo を長時間運用していると、「朝は快適だったノードが夕方にはタイムアウトする」「自動選択グループはあるが、切り替わった理由が分からない」という場面に遭遇します。そこで役立つのが、Mihomo の external-controller と REST API を使った監視です。API から策略グループ、ノード一覧、遅延、現在の接続状態を取得し、一定条件を満たさない場合だけ別のノードへ切り替える構成を作れます。

本記事では、Clash Verge Rev や Mihomo 系クライアントをすでに導入していることを前提に、API を安全に待ち受ける設定、ノードの死活確認、応答速度の比較、切り替えスクリプト、定期実行、障害時の調査までを順に説明します。単純に最速のノードを毎回選ぶのではなく、連続失敗回数や切り替え間隔を考慮し、接続が安定しているときは無駄に出口を変えない設計を目指します。

⚠️
API ポートを公開しない:external-controller は設定変更や接続情報の取得が可能な管理 API です。認証なしで LAN やインターネットへ公開すると、第三者にノードを切り替えられたり、設定情報を読まれたりするおそれがあります。原則として 127.0.0.1 に限定し、外部から操作する場合も VPN や SSH トンネルなど認証済みの経路だけを使ってください。

external-controller と REST API の基本を確認する

Mihomo の API は、通常 http://127.0.0.1:9090 のようなアドレスで待ち受けます。ポート番号はクライアントやプロファイルによって異なるため、まず Clash Verge Rev の設定画面、または読み込んでいる YAML の external-controller を確認してください。API 用の秘密文字列を設定している場合は、リクエストに Authorization: Bearer ヘッダーを付けます。

external-controller: 127.0.0.1:9090
secret: "change-this-to-a-long-random-token"

最初の疎通確認では、コアのバージョンと策略一覧を取得します。ここで接続できなければ、ポート番号、コアの起動状態、ファイアウォール、secret の記述を順番に確認します。

curl -s http://127.0.0.1:9090/version \
  -H 'Authorization: Bearer change-this-to-a-long-random-token'

curl -s http://127.0.0.1:9090/proxies \
  -H 'Authorization: Bearer change-this-to-a-long-random-token'

/proxies のレスポンスには、各ノードだけでなく Selector、URLTest、Fallback などの策略グループも含まれます。自動切替の対象にする場合は、まず実際のグループ名を確認してください。画面上の表示名と YAML 内の名前が異なることがあるため、スクリプトに推測した名前を固定するのではなく、API のレスポンスに現れる正確な文字列を使うのが安全です。

グループを手動で切り替える API は、対象グループへ新しいノード名を送る形式が基本です。JSON の文字列はノード名と完全一致していなければなりません。ノード名に日本語、絵文字、スラッシュが含まれている場合は、シェルのクォートや JSON エスケープにも注意します。

curl -s -X PUT http://127.0.0.1:9090/proxies/Auto \
  -H 'Authorization: Bearer change-this-to-a-long-random-token' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Tokyo-01"}'
ℹ️
最初は読み取り専用で試す:いきなり切り替え処理を自動化せず、まず /version と /proxies の取得だけを実行してください。レスポンスの構造、グループ名、ノード名、現在の選択状態を記録してから PUT 操作へ進むと、誤ったグループを変更する事故を減らせます。

死活監視と応答速度を正しく測定する

ノードの表示が存在していることと、現在使えることは別問題です。購読設定に残っていても、サーバー停止、証明書エラー、帯域制限、上流回線の障害によって通信できない場合があります。監視では、少なくともHTTP リクエストが成功するか、応答まで何ミリ秒かかるか、同じ結果が連続して得られるかを分けて扱います。

Mihomo では、特定ノードに対してテスト URL への遅延測定を要求できます。エンドポイントの表記はコアのバージョンや互換実装によって差があるため、使用中の API ドキュメントと実レスポンスを確認してください。一般的な形式は次のようになります。

curl -sG 'http://127.0.0.1:9090/proxies/Tokyo-01/delay' \
  -H 'Authorization: Bearer change-this-to-a-long-random-token' \
  --data-urlencode 'url=https://www.gstatic.com/generate_204' \
  --data-urlencode 'timeout=5000'

テスト URL は、常に同じホストを使うことが重要です。大きなページや動画 URL を測定対象にすると、ノードの帯域や相手側の混雑まで強く反映され、単純な接続比較になりません。軽量な HTTPS エンドポイントを選び、タイムアウトは短すぎない値にします。たとえば 1 秒では一時的なジッターをすべて障害と判定しやすく、10 秒では利用者が長く待たされます。自宅回線なら 3〜5 秒程度から始め、ログを見ながら調整するとよいでしょう。

速度だけで選ぶ場合にも注意が必要です。あるノードが 80ms、別のノードが 120ms なら前者が有利に見えますが、前者が 5 回中 2 回失敗するなら、平均値だけでは実用性を判断できません。次のような評価ルールを設けると、瞬間的な最速値に振り回されにくくなります。

  • 失敗を最優先で除外:タイムアウト、DNS エラー、TLS エラーが発生したノードは、その回の候補から外します。
  • 連続成功を評価:一度だけ速いノードより、複数回安定して応答するノードを優先します。
  • 切り替え幅を設ける:現在のノードが 110ms で、新候補が 105ms しか速くないなら、頻繁な切り替えを避けます。
  • クールダウンを置く:切り替え後の数分間は再評価しても、別ノードへすぐ戻さないようにします。
  • 用途別に測る:Web 閲覧、開発 API、長時間接続では最適な出口が異なるため、全用途を一つの数値で決めません。

URL テストが成功しても、アプリの通信が必ず成功するとは限りません。対象サービスが WebSocket、HTTP/2、UDP、長時間ストリームを使う場合、短い HTTPS の遅延だけでは十分な検証にならないことがあります。まず軽量なテストで候補を絞り、その後に実際のアプリケーションのログと Clash の接続ログを確認する二段階方式が現実的です。

API で安全にノードを選び、切り替えるスクリプト

監視スクリプトは、一覧取得、候補の測定、順位付け、現在値との比較、切り替え、ログ保存という流れに分けると保守しやすくなります。下記は構造を理解するための簡略化したシェル例です。実環境ではノード名の取得方法、API のエンドポイント、JSON 処理ツールの有無を確認してから調整してください。

#!/usr/bin/env bash
set -eu

API="http://127.0.0.1:9090"
GROUP="Auto"
TOKEN="${CLASH_API_TOKEN:?set CLASH_API_TOKEN}"
TEST_URL="https://www.gstatic.com/generate_204"
TIMEOUT=5000
MIN_IMPROVEMENT=30

get_delay() {
  local node="$1"
  curl -fsS -G "$API/proxies/$node/delay" \
    -H "Authorization: Bearer $TOKEN" \
    --data-urlencode "url=$TEST_URL" \
    --data-urlencode "timeout=$TIMEOUT" |
    jq -r '.delay // empty'
}

# Candidate names should be maintained explicitly at first.
for node in Tokyo-01 Tokyo-02 Singapore-01; do
  delay="$(get_delay "$node" 2>/dev/null || true)"
  [ -n "$delay" ] && printf '%s %s\n' "$delay" "$node"
done | sort -n | head -n 1

この例をそのまま本番運用するのではなく、まず測定結果をファイルへ保存し、数回実行して挙動を確認します。次の段階では、/proxies からグループの all や now を取得し、候補を動的に作ります。ただし、すべてのノードを無条件に監視すると API リクエストが増え、プロキシサーバーやテスト先へ余計な通信を発生させます。地域、プロトコル、用途によって対象を絞る方が運用上は安定します。

切り替え処理では、現在のノードを読み取り、新候補の遅延が十分に改善した場合だけ PUT します。改善幅を設定しないと、100ms と 101ms のような差で選択が往復し、WebSocket やダウンロードが頻繁に切断されます。さらに、切り替え直後には「変更したノード名、測定値、理由、スクリプトの終了コード」をログへ残してください。障害時に GUI の表示だけを見ていると、自動切替が原因なのか、上流障害なのか判断しにくくなります。

定期実行には Linux の systemd timer、cron、macOS の launchd、Windows のタスク スケジューラなどを使えます。実行間隔は用途に合わせ、一般的な Web 閲覧なら 5〜15 分程度から始めるとよいでしょう。1 分ごとの測定は、ノードの状態が短時間で変わらない環境では効果が薄く、ログと API 負荷だけが増えることがあります。長時間の音声通信や開発用 API では、接続中に切り替えないロック機構を追加することも検討してください。

⚠️
API トークンをコードへ直書きしない:シェルスクリプト、Git リポジトリ、共有ログ、画面録画に secret が残らないよう、環境変数や OS の秘密情報ストアで管理してください。権限を分けられる環境では、監視専用 API と切り替え可能な管理 API を分離し、不要なユーザーやプロセスからポートへ接続できないようにします。

自動切替が期待どおり動かないときの調査手順

最初に確認するのは、スクリプトの判定ではなく API そのものです。curl で /version が返るか、/proxies に目的のグループがあるか、ノード名が URL エンコードや JSON の中で壊れていないかを調べます。GUI が起動していても、実際に使われているコアが別のポートで動いていることがあります。複数の Clash 系クライアントを同時起動している場合は、プロセスと待受ポートの対応も確認してください。

遅延測定だけが失敗する場合は、テスト先、DNS、ノードのプロトコル、TLS 検証を切り分けます。すべてのノードが同時に失敗するなら、監視用 URL やローカル DNS の問題である可能性があります。一つの地域だけが失敗するなら、ノード側の障害や経路の混雑を疑います。API が 401 を返す場合は secret、404 ならエンドポイントやノード名、400 なら JSON の形式やパラメータを確認する、というように HTTP ステータスも記録しておくと調査が早くなります。

切り替え後に通信が改善しない場合は、実際の接続ログで対象ドメインの策略名を確認します。ルール設定の上位で別のグループへ送られていれば、API で Auto を変更してもアプリの通信には影響しません。また、すでに確立した TCP、TLS、WebSocket 接続はノードを変更しても既存セッションが自動移動するわけではありません。切り替え後も古い接続が残る場合は、アプリ側の再接続、接続のタイムアウト、または必要最小限の接続リセットを検討します。

ログは「測定開始」「測定結果」「選択中のノード」「切り替え理由」「切り替え後の確認結果」を一行ずつ残す形式が扱いやすいです。個人情報や URL のクエリ文字列、Authorization ヘッダーをそのまま記録しないようにしてください。過去 24 時間の失敗回数を集計すれば、単発のタイムアウトと、特定時間帯に続く品質低下を区別できます。監視が自動化されるほど、成功時のログを省略せず、後から「なぜ切り替わらなかったのか」も追えるようにすることが重要です。

一般的な GUI クライアントでは、手動選択や単純な URL テストはできても、API を使った細かな閾値、連続失敗数、クールダウン、監査ログまで自分で組み立てる必要があり、複数のツールをつなぐほど設定が複雑になりがちです。ClashSky なら Mihomo 系のプロファイルと策略グループを分かりやすく管理でき、API 監視を始める前のポート確認やノード選択も進めやすい構成です。自動切替を安全に試したい方は、まず環境に合うクライアントを確認してから、ClashSky を無料でダウンロードして実際の接続ログと照らし合わせてみてください。