この記事で分かること

Clash のノードを手動で切り替えていると、接続が遅くなったときや突然タイムアウトしたときに、利用者がその都度プロファイル画面を開いて別のノードを選ばなければなりません。短時間の閲覧なら対応できますが、長時間のダウンロード、API 呼び出し、リモート作業、動画再生などでは、切断に気付くまで通信が止まり続けることがあります。

本稿では、Clash API でノードの死活監視を行い、遅延や接続失敗を条件に代理グループを自動切替する方法を解説します。Mihomo を利用する Clash Verge Rev などを前提に、API の認証、プロキシグループの確認、健康チェックの実行、失敗時の切替、定期実行、ログ調査までを一つの運用手順として整理します。単に「最も速いノード」を一度選ぶのではなく、現在のネットワーク環境で継続的に使える出口を選ぶことが目的です。

なお、API でノードを操作する場合は、外部ネットワークから管理 API を直接公開しないことが重要です。まずは Clash が動作している同じ端末、または信頼できる LAN 内の管理ホストから試し、認証用の Secret を設定した状態で検証してください。

Clash API と死活監視の基本

Clash 系コアには、現在の設定やプロキシ、接続情報を HTTP API から取得できる機能があります。Mihomo では、管理 API のアドレスと認証用 Secret を設定ファイルで指定します。代表的な設定は次のような形です。

external-controller: 127.0.0.1:9090
secret: change-this-secret

external-controller を 0.0.0.0 にすると LAN からもアクセスできるようになりますが、ファイアウォールや認証を正しく設定しない限り推奨できません。ノード選択や設定変更を許可する API は、閲覧用のエンドポイントよりも影響が大きく、第三者に利用されると通信経路を勝手に変更される可能性があります。ローカルの自動化だけが目的なら、127.0.0.1 のままにしてください。

死活監視で見るべき値は、単純な HTTP ステータスだけではありません。接続先まで到達できたか、応答まで何ミリ秒かかったか、指定したタイムアウト内に結果が返ったか、検査が何回連続して失敗したかを分けて扱います。例えば一度だけ 800ms になったノードを即座に切り替えると、混雑のたびにノードが入れ替わるフラッピングが起きます。実用上は、遅延の閾値と連続失敗回数を組み合わせる方が安定します。

  • 到達性：テスト URL へ接続できるか。
  • 応答時間：設定した上限以内に応答が返るか。
  • 連続失敗：一時的な損失と継続的な障害を区別できるか。
  • 回復判定：切替後に元のノードが復旧したとき、すぐ戻すか。

自動切替しやすい代理グループを作る

API による切替では、個別ノードを直接操作するより、まずプロキシグループを作る方が管理しやすくなります。たとえば「Proxy」というグループに複数ノードを登録し、ルールからは常に「Proxy」だけを参照します。こうすると、ルールの各行を書き換えずに、グループ内の現在の選択だけを変更できます。

グループには、手動選択用の Select、遅延を基準に候補を選ぶ URLTest、障害時に次のプロキシへ移る Fallback などがあります。利用目的によって適した型が異なります。自動的に最も応答の速いノードを使いたい場合は URL テスト型、現在のノードをできるだけ維持しながら停止時だけ切り替えたい場合はフォールバック型が向いています。

ただし、遅延が最も低いノードが常に最良とは限りません。テスト URL には応答するものの、実際に使う API や動画サービスでは帯域制限があるケースもあります。そのため、監視用 URL は実際の用途に近い HTTPS エンドポイントを選び、短い応答だけでなく数分間の安定性も確認してください。プロバイダの利用規約に反する大量のテストを行わないよう、間隔と回数にも余裕を持たせます。

TIP：最初は自動切替の対象を一つのプロキシグループに限定してください。DNS、社内サービス、決済サイトまで同じグループへ入れると、切替の影響範囲が広がり、問題発生時の原因確認が難しくなります。

実際に API から状態を確認して切り替える

まず、Clash が待ち受けている API へ認証付きでアクセスし、プロキシ一覧を確認します。API のパスやレスポンス形式は利用しているコアやバージョンによって差があるため、実行前に Mihomo のドキュメントと実際のレスポンスを確認してください。

curl -H "Authorization: Bearer change-this-secret" \
  http://127.0.0.1:9090/proxies

レスポンスには、プロキシグループとその中に含まれる候補ノード、現在選択されている名前などが含まれます。ここで確認するポイントは、スクリプトが個別ノードの表示名に依存しすぎていないかという点です。ノード名は購読更新で変更されることがあるため、グループ名を固定し、候補を API から毎回取得する設計の方が保守しやすくなります。

次に、対象グループの遅延を測定します。多くの Clash 系 API では、グループ名またはプロキシ名を URL パラメータで渡し、テスト先とタイムアウトを指定します。グループ名に日本語、空白、記号が含まれる場合は必ず URL エンコードしてください。

curl -G \
  -H "Authorization: Bearer change-this-secret" \
  --data-urlencode "url=https://www.gstatic.com/generate_204" \
  --data-urlencode "timeout=5000" \
  "http://127.0.0.1:9090/proxies/Proxy/delay"

結果が正常なら遅延値を読み取り、例えば 800ms を超えた状態が三回続いた場合だけ次の候補へ切り替える、という判定を行います。接続拒否、名前解決失敗、TLS エラー、タイムアウトは、いずれも失敗として記録しますが、原因を同じものとして扱わないことが大切です。DNS だけの障害なら、ノードを変更しても改善しない可能性があります。

グループの選択を変更する API を使う場合は、PUT リクエストの JSON に切替先の名前を渡します。実際のエンドポイントはコアの仕様に合わせてください。

curl -X PUT \
  -H "Authorization: Bearer change-this-secret" \
  -H "Content-Type: application/json" \
  -d '{"name":"Node-B"}' \
  "http://127.0.0.1:9090/proxies/Proxy"

切替後は、API の GET で現在の選択をもう一度取得し、意図したノードになったことを確認します。さらに新しいノードで同じテストを実行し、切替処理が成功したという事実と、実際に通信が回復したことを分けて記録してください。HTTP 200 が返っても、直後の接続が失敗している場合があります。

定期実行とフラッピング対策

定期実行には、Linux の systemd timer、cron、macOS の launchd、Windows のタスク スケジューラなどを使えます。検査間隔は用途によって異なりますが、数秒ごとの実行は API と接続先の双方に負荷をかけます。通常の閲覧や開発用途なら、まず 1〜5 分間隔から始め、障害の検出に時間がかかりすぎる場合だけ短くします。

スクリプトには最低限、現在のノード、検査時刻、対象 URL、応答時間、エラー種別、連続失敗数、切替前後のノードを記録させます。ログを一行の JSON として保存すると、後で時間帯別の失敗率を集計しやすくなります。Secret はログへ出力せず、環境変数や OS の安全な資格情報ストアから読み込んでください。

フラッピングを防ぐには、三つの制御が有効です。第一に、切替条件へ連続失敗回数を入れること。第二に、切替後のクールダウン時間を設定し、すぐに別ノードへ移らないこと。第三に、復旧した元ノードへ戻るためのヒステリシスを設けることです。例えば悪化判定を 800ms、復帰判定を 400ms と別々にすると、境界付近の小さな変動で往復しにくくなります。

すべての候補が失敗した場合に備え、最後のノードを無条件に使い続ける設計は避けてください。安全側に停止する、DIRECT へ戻す、管理者へ通知するなど、用途に応じた退避動作を決めます。認証 API や社内業務で誤った DIRECT が危険になる場合は、通信を止めて明示的な復旧を待つ方が適切です。

認証、ログ、障害切り分け

管理 API は通信の中枢を操作できるため、Secret を空にしたまま運用しないでください。LAN 内からしか接続できない構成でも、ゲスト Wi-Fi、他の仮想マシン、マルウェア感染端末が存在すれば安全とは限りません。API ポートをルーターのポート転送へ登録せず、必要ならホスト側のファイアウォールで接続元を限定します。

自動切替が動かないときは、最初に API 自体へ接続できるかを確認します。次に認証ヘッダー、グループ名の URL エンコード、JSON のプロキシ名、対象 URL の到達性を順番に調べます。Clash のログには、DNS 解決、ルールマッチ、接続先、エラー内容が出ることがあります。API の成功ログだけを見て「通信も直った」と判断せず、実際のアプリケーションから発生した接続ログと照合してください。

  • 401 や 403：Secret、Bearer 形式、API のアクセス制限を確認します。
  • 404：API パスやコアのバージョン差、グループ名のエンコードを確認します。
  • タイムアウト：テスト URL、DNS、現在のノード、上流プロキシを分けて確認します。
  • 切替後も通信不能：アプリが別のプロキシ設定を使っている、または Keep-Alive 接続を再利用している可能性があります。

よくある質問

何を監視すればノードの良し悪しを判断できますか？

まずは接続成功率と応答時間を監視し、その後に実際の用途で問題がないかを確認します。単一の速度テストだけでは、ストリーミング、長時間 API、WebSocket、ファイル転送の安定性までは判断できません。重要な用途がある場合は、負荷を抑えた専用の検証を追加してください。

管理 API を LAN に公開してもよいですか？

必要な場合に限り、認証、ファイアウォール、接続元制限を組み合わせて公開します。外出先から操作したい場合も、API ポートを直接インターネットへ公開するのではなく、VPN や安全な管理経路を利用してください。

URLTest と自作スクリプトはどちらを使うべきですか？

単純に遅延の良い候補を使うだけなら URLTest の方が設定しやすく、常時運用にも向いています。連続失敗回数、時間帯、特定 URL、通知、業務ごとの退避動作など細かな条件が必要なら API スクリプトが適しています。両方を重ねる場合は、どちらが最終的な選択権を持つかを決めてください。

Secret をスクリプトへ直接書いてもよいですか？

共有リポジトリやバックアップへ入る可能性があるため、直接記述は避けてください。環境変数、権限を制限した設定ファイル、OS の資格情報管理機能などを使い、ログ、エラーメッセージ、画面共有に Secret が表示されないことも確認します。

まとめ

Clash API を使った自動切替は、単に「遅いノードを別のノードへ変える」仕組みではありません。管理 API をローカルまたは安全な LAN に限定し、プロキシグループを抽象化し、遅延・連続失敗・復旧条件を分けて設計することで、手動操作の回数と切断時間を減らせます。最初は一つのグループと一つの検査 URL から始め、ログを確認しながら閾値や実行間隔を調整してください。

単純なプロキシアプリでは、ノード選択が手動中心になったり、死活監視の条件やログを細かく確認しにくかったり、OS ごとに設定方法が分断されたりすることがあります。一方、Clash はプロファイル、ルール、代理グループ、Mihomo の API を組み合わせて、手動選択から自動フェイルオーバーまで同じ構成の中で管理できます。複数のノードを用途別に運用し、接続状態を記録しながら安定性を高めたいなら、この柔軟な運用を試せる Clash を選ぶ価値があります。

Clash を無料でダウンロードして、快適なネット体験を →