Clashの外部コントローラーAPIを保護しプロキシノードを自動切替する方法

外部コントローラー API とは:ノード切替を自動化する前に知っておきたいこと

Clash API や外部コントローラーを使うと、GUI を開かずにプロキシグループや現在の選択ノードを確認し、対応するグループの接続先を変更できます。定期的な遅延チェックを行い、応答が悪いノードから別の候補へ切り替える処理も組めます。ただし、API は単なる状態表示用の窓口ではありません。設定変更まで行えるため、待受アドレスや認証を誤ると、同じネットワーク上の第三者にプロキシ設定を操作されるおそれがあります。

まず押さえたいのは、外部コントローラー API とプロキシ通信ポートは別の機能だという点です。たとえば mixed-port はアプリの通信を受け付けるポートですが、external-controller は管理 API の待受先です。API を有効にしただけで、プロキシ利用者にノード一覧が公開されるわけではありません。一方で、管理ポートを LAN 全体やインターネットへ無制限に公開すると、認証設定を含めた別のリスクが生じます。

この記事では、Mihomo 系コアを使う Clash クライアントを想定し、API をローカルに安全に公開する方法、Selector グループの切替方法、条件を決めた自動化、失敗時のログ確認までを順に扱います。クライアントによって設定画面や API の細部に違いがあるため、API の応答とコアのログを照合しながら進めてください。

認証情報は秘密情報です。API の secret をスクリプト、シェル履歴、スクリーンショット、公開リポジトリへそのまま載せないでください。まずは 127.0.0.1 だけで動作を確認し、必要がなければ LAN や外部ネットワークから到達できる設定にしないのが基本です。

secret 認証と待受範囲を安全に設定する

最初の設定では、API をループバックアドレスに限定し、推測されにくい secret を指定します。以下は構成の概念例です。既存プロファイルを編集する場合は、同じキーを重複して追加せず、クライアントの設定画面や生成済み設定が値を上書きしていないかも確認してください。

# 外部コントローラーの基本例
external-controller: 127.0.0.1:9090
secret: "十分に長く推測されにくい値"

127.0.0.1 は同じ端末からの接続に限定する指定です。自動切替スクリプトを Clash と同じ PC で実行するなら、通常はこの形で十分です。0.0.0.0 は複数のネットワークインターフェースで接続を受け付ける指定なので、何も考えずに使うのは避けてください。スマートフォンや別の管理端末から操作する必要がある場合も、待受を広げる前に、ファイアウォール、認証、接続元の制限を一緒に設計します。

API クライアントは、認証が有効な場合に通常 Authorization: Bearer ... ヘッダーで secret を送ります。URL のクエリ文字列へ認証情報を付ける方法は、アクセスログや履歴に残りやすいため避けましょう。リモート接続が必要な環境では、API ポートを直接インターネットへ転送するのではなく、VPN や適切に認証・暗号化された管理経路を利用してください。HTTPS のリバースプロキシを使う場合も、外側の接続制御だけに頼らず、Clash 側の認証とファイアウォールを維持します。

  • 待受先:同一端末内の自動化なら 127.0.0.1 を選びます。
  • secret:長くランダムな値を使い、プロファイルを共有するときは値を削除または差し替えます。
  • ファイアウォール:管理ポートへの不要な受信接続を許可しません。
  • 変更後の確認:コアを再読み込みしたあと、設定画面とログで有効な待受先を確かめます。
Clash Verge、Clash Verge Rev などの GUI クライアントでは、画面からコア設定を生成・管理する場合があります。YAML に書いた値が実際に有効とは限らないため、設定画面の項目名や実行中のコアログも確認してください。

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

安全な待受を確認したら、いきなり切替を自動化せず、まず API からグループの情報を取得します。次の例はローカル端末からの読み取りです。secret は環境変数から渡す形にし、コマンド文字列へ実値を書かないようにします。

export CLASH_SECRET='ここにローカルで管理するsecret'
curl --silent --show-error \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  http://127.0.0.1:9090/proxies

応答にはプロキシ名やグループ情報が含まれます。出力の形はコアのバージョンや構成によって異なるため、スクリプトを作る前に実際の JSON を確認してください。切替対象として扱いやすいのは select 型の Selector グループです。url-test や fallback はコア自身が候補の測定や切替を行う仕組みを持つため、外部スクリプトからさらに頻繁に選択を変更すると、意図しない競合や過剰な切替につながる場合があります。

グループ名と子プロキシ名は、設定内で定義された名前をそのまま使います。「自動」「海外」などの表示ラベルを想定で決めつけず、API の応答にある実際の値を確認しましょう。名前に日本語、空白、記号が含まれる場合は、URL パスへ入れる際のエンコードにも注意が必要です。文字列を単純に連結すると、別の名前として解釈されたり、リクエストが失敗したりすることがあります。

API の応答が空、または想定したグループが見つからない場合は、プロファイルが有効か、対象のポリシーグループが設定に存在するかを先に確認します。ノード一覧が表示されても、すべてのノードが現在利用できるとは限りません。購読更新直後やネットワーク障害時には、一覧に残っていても接続できない候補があります。ログの失敗理由と、遅延テストの結果を組み合わせて選定することが重要です。

Selector グループを手動で切り替えて動作を検証する

読み取りができたら、次は対象グループを一つだけ選び、API による切替を試します。以下はリクエスト形式の例です。GROUP_NAME と NODE_NAME は、API から取得した実際の名前に置き換えます。グループ名やノード名を含む URL は適切にパーセントエンコードしてください。

curl --silent --show-error --request PUT \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  -H "Content-Type: application/json" \
  --data '{"name":"NODE_NAME"}' \
  "http://127.0.0.1:9090/proxies/GROUP_NAME"

リクエスト後は、同じグループの情報をもう一度取得し、選択中のノードが変わったか確認します。HTTP の成功応答だけでは、通信全体が正常になったとは判断できません。接続ログに対象アプリの通信が現れるか、意図したルールにマッチしているか、実際のアクセスが成功するかまで確かめてください。設定の変更がすぐ反映されない場合は、コアの状態やグループ種別を見直し、同じリクエストを短時間に繰り返すのは避けます。

切替先の候補を評価するには、目的に合った URL とタイムアウト値で遅延チェックを行います。遅延の数値だけで「最適なノード」と決めるのではなく、連続測定のばらつき、タイムアウト、実際に使うサービスへの到達性を記録しましょう。測定対象の URL が応答しないだけでノード自体は正常なケースもあります。複数のチェック先や実利用のログを組み合わせると、誤判定を減らせます。

最初は GUI で選択したノードと API の取得結果を見比べ、次に API で一度だけ切り替えます。手動操作と API 操作の結果が一致することを確認してから、自動化へ進むと原因を切り分けやすくなります。

誤切替を防ぐプロキシノード自動切替の設計

プロキシの自動切替は、「遅延が一度高かったら即変更」という単純な条件にしないことが大切です。無線品質の揺れや一時的な混雑を障害と誤認すると、ノードが短い間隔で行き来するフラッピングが発生します。自動切替を始める前に、対象グループ、候補ノード、チェック先、許容遅延、連続失敗回数、切替後の待機時間を決めておきます。

  1. Selector グループを限定する:自動化するグループ名を固定し、DIRECT や管理用のグループを誤って対象にしないようにします。
  2. 候補を絞る:利用地域や用途に合うノードだけを候補にし、停止中のノードや除外対象をリストから外します。
  3. 複数回測定する:一度のタイムアウトでは切り替えず、一定時間内の連続失敗や複数回の高遅延を条件にします。
  4. 切替後に確認する:選択ノードの変更だけで完了とせず、少し待ってから再測定し、接続ログと実利用も確認します。
  5. 頻度に上限を設ける:連続切替を抑えるクールダウン時間を設定し、異常時には自動化を停止できる手段を用意します。

実装はシェル、Python、Node.js などから可能ですが、処理の骨格は共通です。API からグループと現在の選択を取得し、候補ノードを測定し、条件を満たしたときだけ Selector へ変更リクエストを送り、最後に結果を記録します。複数のスクリプトや端末が同じグループを書き換えると、後から送った要求が先の選択を上書きするため、実行主体を一つにするか、排他制御を設けてください。

ログには時刻、対象グループ、切替前後のノード、測定値、判断理由だけを残し、secret や Authorization ヘッダーは出力しないようにします。切替条件を変更したときは、すぐ本番の定期実行にせず、まずはログだけ記録する「判定のみ」の期間を設けると安全です。その期間に、実際に切替条件が成立する場面と誤判定の頻度を確認できます。自動化は常時オンにすること自体が目的ではなく、手動操作より安定して問題を減らせる条件を見つけることが目的です。

また、自動切替は利用しているサービスの制限や組織のネットワークポリシーを回避するための仕組みではありません。管理対象端末では、API の有効化やノード変更が許可されているかを確認してください。API が応答しなくなったときも、更新処理を無限に再試行せず、回数制限とエラー通知を設け、必要なら手動運用へ戻せるようにしておきます。

API の失敗をログと設定から切り分ける

Clash 外部コントローラー APIに接続できない場合は、まずアドレスとポートが実際の設定に一致するかを確認します。接続拒否なら、コアが起動していない、設定変更が反映されていない、別のポートを使っているといった可能性があります。タイムアウトなら、待受アドレス、ファイアウォール、接続元と接続先の組み合わせを調べます。認証エラーの場合は、クライアントが送っている secret とコア側の値を照合し、余分な空白や古い環境変数にも注意してください。

API の読み取りは成功するのに切替だけ失敗するなら、対象が Selector 型か、URL 内のグループ名が正しいか、JSON のキーが name になっているかを確認します。ノード名が API の応答に存在しない場合は、購読更新やプロファイル変更で名前が変わっている可能性があります。応答の HTTP ステータスや本文は環境によって異なるため、スクリプトでは成功を決めつけず、エラー内容を安全に記録してください。

切替自体は通るのにアプリが改善しない場合は、API の操作よりもルールと通信経路を調べます。対象の通信が別のポリシーグループに振り分けられていれば、切り替えたグループは使われません。コアの接続ログで対象ドメイン、マッチしたルール、選択されたポリシーを確認し、GUI 上のモードやプロファイルが想定どおりかを照合します。API 呼び出しの成否と、実トラフィックの経路は別々に検証しましょう。

症状 確認する項目 次の対応
接続拒否 コアの起動状態、待受アドレス、ポート 有効な設定を確認し、必要ならコアを再読み込みする
認証エラー secret の値、Bearer ヘッダー、環境変数 実値をログへ出さず、認証情報を安全に再設定する
グループが見つからない API の応答、グループ名、現在のプロファイル 実際の名前を取得し、URL エンコードも確認する
切替後も通信が変わらない Selector の選択状態、ルール、接続ログ 対象通信が切替対象グループを通っているか調べる

運用を続ける場合は、Clash や Mihomo の更新時に API の挙動と設定項目を再確認し、スクリプトの前提が変わっていないかテストします。secret を変更したら自動化側も更新し、古い認証情報を使うプロセスが残っていないか確認してください。障害対応の記録には、発生時刻、コアのバージョン、プロファイル、対象グループ、エラーの要約を残すと、再現と原因調査が容易になります。

一部の同種ツールでは、ノード選択を画面操作に頼るため、定期的な確認や細かな条件分岐を組みにくいことがあります。また、管理 API を備えていても、認証や待受範囲を意識せず公開すれば、利便性がそのままリスクになります。Clash と Mihomo 系コアは、ローカルに限定した API、secret 認証、Selector グループ、接続ログを組み合わせて、状態確認から切替の検証まで段階的に行えるのが利点です。まずは安全なローカル設定で手動テストを済ませ、必要な条件だけを自動化しましょう。各プラットフォームのクライアントを探している方はダウンロードページを確認できます。環境に合うクライアントを選び、API の待受範囲と認証を確かめてから運用を始めてください。

→ Clashを無料でダウンロードして、快適なインターネット環境を手に入れよう

ダウンロードページへ