Clash APIでプロキシを自動切替する実践設定ガイド

Clash APIで自動切替を設計する前に

Clash APIを使うと、GUIでプロキシを手動選択しなくても、現在の遅延や接続状態に応じて利用するノードを切り替えられます。特に external-controller を有効にした Clash または mihomo では、HTTP APIからプロキシグループの現在値を取得したり、グループの選択先を変更したりできます。動画視聴、長時間のダウンロード、開発用 API への接続など、通信の性質が変わる環境では、単純な固定ノードよりも「平常時は低遅延のノードを使い、失敗時は別のノードへ移る」構成のほうが運用しやすくなります。

ただし、自動切替は「速いノードを一度選べば終わり」という機能ではありません。測定 URL が応答していても、実際に使うサービスの TLS 接続や長時間通信が安定するとは限らず、逆に一時的な DNS 遅延だけで正常なノードを外してしまうこともあります。そのため本稿では、API エンドポイントの確認、認証、現在のグループ取得、遅延測定、切替、再確認という順序で、判断材料を増やしながら安全に自動化します。

external-controller と認証を安全に設定する

API を使う最初の作業は、Clash の設定ファイルでコントローラーの待受先を確認することです。一般的には external-controller: 127.0.0.1:9090 のようにローカルアドレスとポートを指定し、必要に応じて secret を設定します。クライアントによっては「外部コントローラー」「External Controller」「API ポート」などの名前で表示されるため、GUI の設定画面と実際の YAML の値を両方確認してください。Clash Verge、Clash Verge Rev、Mihomo Party などでは、GUI が内部で管理する設定と編集対象のプロファイルが異なる場合があります。

認証用のシークレットを設定した場合、リクエストには Authorization: Bearer your-secret ヘッダーを付けます。シェルの履歴、CI のログ、共有したスクリーンショットに秘密文字列が残らないよう、環境変数から読み込む方法が安全です。API ポートを変更した後は、Clash の再起動または設定の再読み込みが必要になることがあります。まずはブラウザや curl でコントローラーが応答するかを確認し、いきなり自動切替スクリプトを実行しないことが重要です。

export CLASH_API="http://127.0.0.1:9090"
export CLASH_SECRET="replace-with-your-secret"

curl -s \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  "${CLASH_API}/version"

/version が JSON を返せば、少なくとも待受ポートと認証ヘッダーは機能しています。401 が返る場合はシークレットの値や Bearer の綴りを確認し、接続拒否ならポート番号、Clash の起動状態、ファイアウォールを調べます。404 の場合は URL のパスやクライアントが提供する API 互換性を確認してください。コアの種類やバージョンによって利用可能なエンドポイントに差があるため、固定のサンプルだけを信じず、実機でレスポンスを確認するのが堅実です。

プロキシグループと候補ノードを取得する

自動切替の対象は、通常は個別ノードではなく select、url-test、fallback などのプロキシグループです。API からグループ情報を取得し、現在の選択先、候補に含まれるノード名、各ノードの遅延情報を確認します。グループ名には購読側が作った日本語や絵文字が含まれることもあるため、スクリプトでは表示名を決め打ちするより、設定に存在する名前を最初に一覧化したほうがトラブルを減らせます。

curl -s \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  "${CLASH_API}/proxies" | jq '.proxies | keys[]'

ここで見つけたグループの詳細を取得すると、現在の now、候補ノードの all、グループの種類などを確認できます。自動切替対象を GLOBAL にするか、特定のサービス用グループにするかは、普段のルール設計に合わせて決めてください。全通信を一つの API 操作で切り替えると、社内サービスや国内サイトまで同時に経路が変わることがあります。最初は開発用、動画用、海外サービス用など、影響範囲を限定したグループから始めるほうが安全です。

遅延測定と API 切替スクリプトの実装

候補ノードを選ぶときは、単発の最小値だけで判断しないことが大切です。ネットワーク遅延には揺らぎがあるため、数回測定して中央値を使い、失敗回数や測定時刻も記録します。Clash の遅延測定 API は、コアやバージョンによってパスやパラメーターの扱いが異なる場合があります。まず /proxies のレスポンスで候補名を確認し、公式ドキュメントまたは実機の API 応答に合わせて測定 URL を組み立ててください。

切替 API は、グループ名を URL エンコードしたパスへ送信する形式が一般的です。グループ名に空白、日本語、スラッシュが含まれる場合、文字列をそのまま連結すると失敗するため、スクリプト側で URL エンコードします。以下は概念を示す最小例です。実際の API パスは利用中の Mihomo または Clash のバージョンで確認し、候補名やグループ名を自分の環境へ置き換えてください。

GROUP="Proxy"
NODE="Tokyo-01"

curl -sS -X PUT \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  -H "Content-Type: application/json" \
  "${CLASH_API}/proxies/${GROUP}" \
  -d "{\"name\":\"${NODE}\"}"

実運用では、測定値が最も小さいノードへ毎回切り替える処理は避けたほうがよいでしょう。現在のノードとの差が数ミリ秒程度なら切替を見送り、例えば 20 秒以上の差が数回続いた場合だけ変更するようにします。また、一度切り替えた直後に一定時間のクールダウンを設けると、二つのノードを短時間で往復するフラッピングを防げます。切替後には同じ API から now を再取得し、意図したノードが選ばれたことを確認してください。

監視・定期実行・失敗時の復旧設計

自動切替を安定させるには、切替処理と監視処理を分けて考えます。監視側では、現在のグループ、選択ノード、測定遅延、HTTP エラー、切替回数を時刻付きで保存します。Clash のライブ接続ログも併用し、測定 URL には成功しているのに目的の API だけタイムアウトしていないかを確認してください。前者だけを見ていると、DNS は通るが TLS 握手が失敗する、あるいは長時間接続だけが切れる問題を見逃します。

Linux や macOS では cron、systemd timer、launchd、Windows ではタスク スケジューラを使って定期実行できます。実行間隔はノード数や用途に応じて調整し、短時間に多数の測定を送らないようにします。スクリプトが異常終了した場合は、現在の選択をすぐ書き換えるのではなく、最後に成功したノードを記録しておき、復旧時の候補として利用します。API 自体に接続できないときはノード切替を試みても意味がないため、まず Clash コアが起動しているか、次にコントローラーが応答するかを確認する段階的な処理が必要です。

さらに、設定ファイルや購読更新でグループ名が変わる可能性も考慮してください。購読更新後に Proxy が 自動選択 へ改名されると、古いスクリプトは 404 や対象なしで停止します。起動時にグループの存在を検査し、候補が空の場合は何も変更せずエラーを記録する設計にします。シークレットはスクリプトへ直書きせず、OS の権限で保護した環境変数や秘密管理機能から読み込むと、バックアップや Git リポジトリへの誤登録も防げます。

本番投入前の確認手順

まず手動で API のバージョン確認とグループ一覧取得を行い、次に一つのテストグループだけを対象にします。候補ノードを二つ以上用意し、意図したノードへ変更できること、変更後に通常のブラウザや curl の通信がそのグループを通ることを確認します。続いて測定 URL を一時的に不達へした場合のエラー処理、認証ヘッダーがない場合の拒否、Clash を再起動した場合の復帰を順番に検証します。

• external-controller が localhost に限定されているか確認する
• secret をログやリポジトリへ出力しない
• 対象グループと候補ノードの名前を API から確認する
• 中央値、失敗回数、切替回数を記録する
• 差分しきい値とクールダウンを設ける
• 切替後に現在の選択先を再取得する

競合する VPN クライアントや別の自動選択機能が同時に動いていると、API で選んだノードと実際の出口が一致しないことがあります。また、単純な ping だけを基準にするツールは、TLS、HTTP/2、ストリーミング、DNS の差を評価できません。Clash V.CORE なら、Mihomo 系コアの API 操作、ルール分流、接続ログ、複数グループの管理を一つの構成で確認しやすく、今回のような「遅延だけでなく失敗時の復旧まで含めた」運用へ発展させやすい設計です。GUI ごとに API 設定の場所が違って迷いやすい場合も、古いクライアントの手動切替だけに頼るより再現性を保ちやすいため、実環境での検証用クライアントとして Clash V.CORE をダウンロードして試してみてください。