無料ノードは安全に使えますか？

無料ノードは運営元やログ方針が不明な場合が多く、安全性を確認できないものがあります。個人情報や重要な通信には利用せず、提供元、更新履歴、利用規約を確認してください。

Clashにはどのリンクを登録すればよいですか？

Clash用に変換された購読URL、またはプロバイダが提供するClash専用URLを登録します。個別のVMessやShadowsocksリンクをそのままプロファイル欄へ貼ると、期待どおり読み込めない場合があります。

有料サービスなら必ず高速ですか？

有料であることだけで高速になるわけではありません。サーバーの混雑、回線品質、経路、利用時間によって速度は変わるため、試用期間中に複数の時間帯で確認することが大切です。

Clash外部コントローラーAPIで実現するノード自動切替設定ガイド

external-controller APIとは何か

Clash の external-controller は、起動中の Clash コアを外部プログラムから操作するための HTTP API です。通常の GUI では、プロキシグループを開いてノードを選択し、遅延テストの結果を確認してから手動で切り替えます。一方、API を使えば、現在のプロキシ状態の取得、グループ内ノードの一覧表示、遅延測定、選択ノードの変更をスクリプトから実行できます。

この仕組みを利用すると、単に「最も速いノード」を選ぶだけでなく、タイムアウトが続いたノードを一時的に避ける、一定時間ごとにヘルスチェックを実行する、復旧したノードを再び候補に戻す、といった自動フェイルオーバーを構築できます。Clash Verge Rev、Mihomo を利用する環境では、GUI の設定画面と API の状態が同じコアを参照するため、手動操作と自動処理を組み合わせやすいのも利点です。

ただし、external-controller は「ノードを自動的に最適化する機能」そのものではありません。API は命令を受け取る入口であり、どの条件で切り替えるか、何回失敗したら障害と判定するか、切り替え後にどのように通知するかは、利用者側のスクリプトや監視サービスで設計する必要があります。まずは読み取りだけで状態を確認し、その後に切り替え操作を追加する段階的な進め方が安全です。

external-controller の有効化と認証

API を使うには、Clash の設定ファイルで管理用リスナーを有効にします。ポート番号は既存サービスと競合しないものを選び、同じ端末上のスクリプトだけが利用するなら、待ち受けアドレスは 127.0.0.1 に限定するのが基本です。

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

secret を設定した場合、API リクエストには認証ヘッダーを付けます。例として、現在の Clash バージョンやコアの情報を確認する場合は次のように実行します。

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

応答が JSON 形式で返れば、API への接続と認証は成功しています。認証なしで管理ポートを LAN やインターネットへ公開する構成は避けてください。ノード一覧の取得だけでなく、選択ノードの変更、設定の再読み込み、プロキシの停止など、通信状態を大きく変える操作まで許可される可能性があるためです。

注意

管理ポートを 0.0.0.0:9090 で公開すると、ファイアウォールの設定次第では同じ LAN 上の他端末から操作できてしまいます。リモート監視が必要な場合も、VPN、SSH トンネル、アクセス制御付きのリバースプロキシなどを経由し、ポートを直接インターネットへ公開しないでください。トークンは設定ファイルやシェル履歴に平文で残ることがあるため、権限管理にも注意が必要です。

Clash Verge Rev では GUI の設定画面から external-controller や Secret を編集できる場合がありますが、項目名や表示場所はバージョンによって異なります。設定を変更した後はコアを再起動し、/version へのアクセスで有効化を確認してください。設定ファイルに保存した値と GUI が表示する値が一致しないときは、実際に起動しているプロファイルとコアがどれかを先に確認します。

APIでプロキシグループとノードを確認する

自動切替を作る前に、切り替え対象となるプロキシグループの名前を正確に把握します。プロバイダの設定では、グループ名に日本語、絵文字、空白、括弧が含まれることがあります。画面に見えている名称と API が返す URL エンコードされたパスが異なる場合があるため、最初から文字列を推測せず、一覧を取得して確認してください。

curl -H "Authorization: Bearer YOUR_SECRET" \
  http://127.0.0.1:9090/proxies

レスポンスには、各プロキシグループとその配下のプロキシ名、現在選択されているノード、遅延情報などが含まれます。一般的なグループは select、url-test、fallback、load-balance のようなタイプで表現されます。API で手動切替を行う場合は、対象グループが実際にノード選択を受け付けるタイプかどうかも確認してください。

グループの種類	主な動作	自動切替との関係
select	ユーザーが候補から一つを選ぶ	外部スクリプトで選択ノードを変更しやすい
url-test	URL の応答時間を比較して候補を選ぶ	簡単な自動選択に向くが、測定条件の確認が必要
fallback	利用可能な候補へ順番に切り替える	到達性重視のフェイルオーバーに向く
load-balance	複数ノードへ分散する	固定の出口を必要とする用途では挙動を確認する

ノード名を取得したら、まず一つのグループだけを対象にします。プロキシグループを階層化している設定では、上位グループが下位グループを参照していることがあります。最上位グループを変更しても、下位の選択状態が期待どおり変わるとは限らないため、API の応答と GUI の表示を照合しておくとトラブルを減らせます。

遅延チェックと自動フェイルオーバーの設計

Clash API の遅延チェックは、指定したテスト URL に対してノードが応答できるか、どれくらい時間がかかったかを確認する仕組みです。代表的な呼び出しは、対象プロキシ名をパスに含めて URL とタイムアウトを指定する形式です。実際の API パスや利用できるパラメータはコアの種類とバージョンで差があるため、使用中の Mihomo または Clash の API ドキュメントと照合してください。

curl -G \
  -H "Authorization: Bearer YOUR_SECRET" \
  --data-urlencode "url=https://www.gstatic.com/generate_204" \
  --data-urlencode "timeout=5000" \
  http://127.0.0.1:9090/proxies/Node-A/delay

一回の測定結果だけでノードを切り替えると、瞬間的な混雑やテスト URL 側の揺らぎに反応して、ノードが何度も入れ替わるフラッピングが起こります。実運用では、成功回数と失敗回数を別々に数える設計が重要です。たとえば 5 秒間隔で測定し、連続 3 回のタイムアウトで障害と判定する一方、復旧は連続 2 回の成功を確認してから行うと、短い通信揺らぎに過剰反応しにくくなります。

自動切替を安定させる判定例

現在のノードに対して HTTPS の遅延チェックを実行する。
タイムアウト、接続拒否、異常に大きな遅延を失敗として記録する。
連続失敗数がしきい値に達したら、候補ノードを順番に検査する。
最低遅延だけでなく、設定した上限値を満たすノードを選ぶ。
グループ API に切替命令を送り、実際の選択状態を再取得する。
切替後にもう一度通信確認を行い、失敗した場合は次の候補へ進む。

テスト URL は一つに固定しない方がよい場合があります。特定の CDN や地域に依存した URL だけを使うと、ノードではなくテスト先の障害を検出してしまう可能性があります。普段利用するサービスに近い HTTPS エンドポイントを選び、必要であれば複数 URL の結果を組み合わせてください。ただし、短時間に大量のリクエストを送ると相手側から不審なアクセスと判断されることがあるため、監視間隔は控えめに設定します。

ノードを選ぶ基準も、単純な最低レイテンシだけでは不十分です。遅延が 80 ミリ秒でも頻繁に切断されるノードより、120 ミリ秒で安定して通信できるノードの方が実用的なことがあります。遅延、成功率、直近の切替回数、クールダウン時間を組み合わせると、動画視聴や長時間のダウンロードでも状態が安定します。

グループ切替、ログ確認、運用上の注意

対象グループの選択ノードを変更する場合は、グループ名とプロキシ名を JSON で送信します。名称に日本語や記号が含まれるときは、URL パスのエンコードと JSON の文字列を混同しないようにしてください。

curl -X PUT \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Node-B"}' \
  http://127.0.0.1:9090/proxies/Auto-Select

切替 API が成功したように見えても、それだけで通信が復旧したとは限りません。直後に /proxies を再取得し、対象グループの現在値が新しいノードになっているか確認します。その後、Clash の接続画面やログで実際のリクエストがどの出口へ流れているかを確認してください。上位グループから別のグループを参照している場合、変更した下位グループが通信経路に使われていないこともあります。

ログ確認では、単に「接続できない」という表示だけを見るのではなく、ドメイン、ルールに一致したポリシー、接続先ノード、エラーの種類を分けて記録します。TLS ハンドシェイク失敗、DNS 解決失敗、リモート側の拒否、ローカルポートの競合では対処が異なります。自動化スクリプトには、切替時刻、旧ノード、新ノード、測定値、失敗理由を含むログを残すと、後から原因を追いやすくなります。

運用のヒント

切替処理にはクールダウン時間を設けてください。たとえば一度切り替えた後は 60 秒間、新しい切替を禁止します。また、候補がすべて失敗した場合に無理にノードを選び続けるのではなく、現在のノードを維持して警告を出す、または明示的に DIRECT へ戻すなど、失敗時のポリシーを事前に決めておきます。サービスによっては直接接続が安全とは限らないため、無条件の DIRECT フォールバックは避けるべきです。

管理 API の応答が突然 401 になる場合は Secret の不一致、404 の場合はパスやグループ名の誤り、タイムアウトの場合は Clash コアの停止やファイアウォールを確認します。GUI を閉じた後に API が使えなくなったなら、GUI がコアも終了させる構成になっている可能性があります。自動監視を常時動かす場合は、コアをサービスとして稼働させ、スクリプト側にもリトライ回数と異常終了時の通知を実装してください。

実運用へ移す前のチェックリスト

自動ノード切替は便利ですが、最初から全通信を対象にすると問題の範囲が広がります。まずテスト用のプロキシグループを作り、特定のブラウザや検証端末だけで動作を確認します。設定ファイルは変更前にバックアップし、API を操作するスクリプトには最小限の権限と必要な環境変数だけを渡してください。Secret をコードへ直接書き込むのではなく、OS の環境変数、権限を制限した設定ファイル、または安全なシークレット管理機能を使う方が望ましいです。

管理ポートは原則として 127.0.0.1 にバインドする
Secret は十分に長く、他のサービスと使い回さない
テスト URL、タイムアウト、失敗回数、クールダウン時間を明文化する
切替後に API の状態と実際の接続ログを二重に確認する
スクリプトのログに Secret、購読 URL、個人情報を出力しない
サブスクリプション更新や設定変更後はグループ名とノード名を再確認する

検証が終わったら、監視スクリプトを systemd、タスクスケジューラ、Docker のヘルスチェックなど、利用環境に合った仕組みで常駐させます。プロセスが停止したときに再起動できること、API が応答しないときに無限リトライしないこと、ログが無制限に肥大化しないことも確認してください。自動化の目的は切替回数を増やすことではなく、通信を安定させて手動対応の回数を減らすことです。

GUI だけで運用するクライアントでは、遅延表示が簡単でも、細かい判定条件や切替履歴を管理しにくい場合があります。反対に、独自スクリプトだけで構築すると認証、プロファイル変更、ログの見やすさ、アップデート時の互換性を自分で維持しなければなりません。Clash は external-controller API によって、GUI の扱いやすさとスクリプトの柔軟性を両立できます。ノード監視と自動フェイルオーバーを安全に試したい方は、まず小さなグループで API の読み取りと一回の切替を検証し、結果を確認しながら運用範囲を広げてください。