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

Clash APIで自動切替を行う仕組み

Clash のプロキシ自動切替は、クライアントの画面を人が操作する代わりに、外部コントローラー API へリクエストを送り、現在の状態を確認しながらプロキシグループの選択を変更する仕組みです。通信が不安定になったときに別ノードへ切り替えたい、特定の時間帯だけ高速な出口を選びたい、サーバーの稼働状況を定期的に記録したい、といった用途に利用できます。

Clash Verge、Clash Verge Rev、Mihomo 系クライアントでは、コアが起動している間に HTTP API が待ち受けています。API のエンドポイントはクライアントや設定によって多少異なりますが、代表的な構成では external-controller にアドレスとポートを指定し、必要に応じて secret で認証します。たとえば API が 127.0.0.1:9090 で待ち受けている場合、同じ端末上のスクリプトから http://127.0.0.1:9090 にアクセスします。

自動切替を安定して運用するには、「ノードが存在するか」「プロキシグループが期待した名前か」「実際の通信が成功しているか」を分けて考えることが大切です。API が応答していても、選択されたノードの先に接続できるとは限りません。反対に、遅延測定だけが失敗していても、通常の HTTPS 通信は問題なく通るケースがあります。単純に一度のエラーで切り替えるのではなく、複数回の確認と復旧条件を組み合わせると、頻繁な切り替えを防げます。

external-controllerと認証の基本

まず、Clash の設定ファイルまたはクライアントの詳細設定で API の待受設定を確認します。設定例は次のような形です。実際のポート番号や secret は、他のアプリケーションと競合しない値に変更してください。

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

127.0.0.1 は同じ端末からのみアクセスできるループバックアドレスです。外部のパソコンや LAN 内の監視サーバーから API を呼び出す必要がない場合は、できるだけこのアドレスを使用してください。0.0.0.0:9090 のように全インターフェースで公開すると、ファイアウォールやルーターの設定次第で LAN 上の別端末から管理 API に到達できる可能性があります。

注意

external-controller は、プロキシの選択変更や設定確認ができる管理インターフェースです。認証なしで LAN に公開したり、ルーターのポート転送でインターネットへ公開したりしないでください。API を遠隔操作したい場合は、まず VPN や SSH トンネルなど、認証済みの管理経路を用意する必要があります。

認証を有効にした場合、リクエストには Authorization: Bearer ヘッダーを追加します。secret が空の場合と認証に失敗した場合では、クライアントによって返されるステータスコードやエラーメッセージが異なることがあります。ブラウザの開発者ツールだけに頼らず、まずは curl で API の疎通を確認すると原因を切り分けやすくなります。

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

正常に応答すれば、プロキシやプロキシグループの情報を含む JSON が返ります。ここで timeout、connection refused、401 Unauthorized が表示された場合は、それぞれ API の未起動、ポートの誤り、secret の不一致を確認してください。Mihomo のバージョンや GUI の実装によって利用できる API が異なるため、設定変更後はクライアントのログにも目を通すことをおすすめします。

自動切替を実装する手順

ここでは、特定のプロキシグループに対して遅延測定を行い、応答が失敗した場合に別のノードへ切り替える流れを作ります。グループ名は設定ファイルの実際の名前に合わせてください。サブスクリプションによっては「Proxy」「AUTO」「海外」など表記が異なり、名前の大文字・小文字や記号も識別に影響します。

Clash クライアントを起動し、対象プロファイルを有効にする。
external-controller のアドレス、ポート、secret を確認する。
/proxies で対象グループと候補ノードの名前を取得する。
/proxies/{グループ名} に対して遅延測定を実行する。
失敗が連続した場合だけ、別ノードを選択する。
切替後に通常の HTTPS 通信を再確認し、結果をログへ記録する。

ノード一覧を取得するだけなら GET /proxies を使用します。個別プロキシの遅延を調べる場合は、クライアントの API 仕様に応じて /proxies/{name}/delay を利用します。URL に含めるノード名には日本語、空白、括弧、スラッシュなどが含まれることがあるため、手作業で連結せず必ず URL エンコードしてください。

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

プロキシグループの選択を変更する操作は、通常 PUT /proxies/{group} に JSON を送信して行います。次の例では、グループ「Proxy」の現在の選択を「Node-B」に変更しています。

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"

実運用では、最初から特定のノード名を固定するより、候補リストを用意して順番に確認する方法が扱いやすいです。候補には同じ地域や同じプロトコルのノードだけを含め、負荷が高いノードや管理用の特殊なグループは除外します。切替先をランダムにすると、障害が起きているノードへ再び戻る可能性があるため、直前に失敗したノードを一定時間候補から外す設計が安全です。

Python で簡単な監視処理を書く場合は、API の応答コードだけでなく、例外、測定時間、切替回数を記録します。以下は概念を確認するための最小例です。グループ名と候補名は自分の設定に置き換えてください。

import time
import requests

API = "http://127.0.0.1:9090"
TOKEN = "change-this-secret"
GROUP = "Proxy"
CANDIDATES = ["Node-A", "Node-B", "Node-C"]
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def select(name):
    response = requests.put(
        f"{API}/proxies/{GROUP}",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"name": name},
        timeout=5,
    )
    response.raise_for_status()

def check(name):
    response = requests.get(
        f"{API}/proxies/{name}/delay",
        headers=HEADERS,
        params={"url": "https://www.example.com/generate_204", "timeout": 5000},
        timeout=8,
    )
    return response.ok

for node in CANDIDATES:
    if check(node):
        select(node)
        break
    time.sleep(1)

この例をそのまま常駐サービスとして使う前に、連続失敗回数、クールダウン時間、現在の選択状態を追加してください。たとえば 1 回の失敗で切り替えるのではなく、30 秒間隔で 3 回連続して失敗したときだけ切り替えます。切替後は 1〜5 分ほど同じノードを維持し、短時間で元へ戻す処理を避けます。これにより、一時的な DNS 遅延やテスト先の瞬間的な停止で、ノードが何度も変わる現象を抑えられます。

定期実行と運用時の設計ポイント

Windows ではタスクスケジューラ、macOS や Linux では cron、systemd timer、または専用の常駐サービスを利用できます。短い間隔で API を呼び続けると、ノード側の負荷だけでなく、Clash のログや監視先にも余計な通信が発生します。通常の家庭利用なら 30 秒から数分の間隔で十分であり、業務用環境では通信量と復旧要求の優先度を見ながら調整します。

監視先を複数用意する：一つのドメインだけで判定すると、そのサイトの障害をノード障害と誤認することがあります。
HTTP ステータスを確認する：応答が返るだけでなく、期待するステータスコードや本文の条件も確認します。
切替履歴を残す：日時、現在のノード、失敗理由、切替後の結果を記録すると、プロバイダ側の障害を説明しやすくなります。
secret をコードへ直書きしない：環境変数や権限を制限した設定ファイルで管理し、ログへ出力しないようにします。
設定更新と切替処理を分離する：サブスクリプション更新直後はノード名が変わることがあるため、更新完了を確認してから候補一覧を再取得します。

自動選択グループを使う場合、Clash 内蔵の URL テストやヘルスチェックと、外部スクリプトの判定が競合しないよう注意してください。内部の自動選択が短い周期でノードを変更している状態で外部スクリプトも PUT を送ると、どちらが最終的な選択権を持つのか分からなくなります。自動切替を外部で管理するなら、内蔵グループは手動選択にして外部側で候補を制御する方法もあります。

運用のヒント

最初は「切り替える」処理を有効にせず、監視結果だけをログへ保存するドライランから始めてください。実際のネットワークで誤判定がないことを確認してから PUT 操作を有効にすると、意図しないノード変更や業務通信の中断を防げます。

切り替わらないときの確認方法

API に接続できない場合は、まず Clash のコアが起動しているか、設定ファイルが現在有効になっているかを確認します。GUI が表示されていてもコアだけが停止している場合があり、そのときはポートが開いていない、または接続が即座に切断される状態になります。次に、設定に書いたポートとスクリプトのポートが一致しているか、別のアプリが同じポートを使用していないかを確認してください。

401 や 403 が返る場合は secret の値を見直します。Bearer の前後に余計な引用符や空白を入れないこと、環境変数が古い値を保持していないことも重要です。ノード名に日本語が含まれる場合は、JSON の文字コードを UTF-8 に統一し、URL パスではエンコード済みの値を使用します。グループが見つからない場合は、/proxies の応答に含まれる実際の名前を再確認してください。

API 操作は成功しているのに通信が改善しない場合、選択対象が本当にトラフィックで使われるグループかを調べます。ルールが別のグループを参照している、ルールモードでは対象ドメインが DIRECT に割り当てられている、TUN やシステムプロキシが無効になっている、といった可能性があります。Clash の接続ログで対象リクエストを開き、最終的な策略グループと出口ノードを確認すると、API の操作対象との食い違いを発見できます。

HTTPS の遅延測定が失敗する場合は、テスト URL がプロバイダや地域ネットワークからアクセスしにくい可能性もあります。複数のテスト先を使い、DNS 解決、TLS 接続、HTTP 応答を別々に確認してください。タイムアウトを短くしすぎると、混雑しているだけの正常なノードまで除外してしまいます。反対に長すぎると、障害発生時の切替が遅れます。利用目的に合わせて 3〜10 秒程度から調整するとよいでしょう。

よくある質問

external-controllerは必ず設定する必要がありますか？

外部スクリプトから Clash を操作する場合は必要です。GUI 内部の自動選択だけを使う場合は必須ではありません。ただし、API を有効にする場合は待受アドレスをローカルに限定し、secret を設定するのが基本です。

遅延が低いノードへ常に切り替えるべきですか？

必ずしもそうとは限りません。遅延は測定先や時間帯によって変化し、低遅延でも帯域や安定性が不足するノードがあります。連続失敗を主条件にし、遅延は候補の優先順位として使うほうが、実際の通信では安定しやすくなります。

どのClashクライアントでも同じAPIを使えますか？

基本的なエンドポイントは共通していることがありますが、Clash、Clash.Meta、Mihomo の世代や GUI により対応範囲とパスが異なります。使用中のクライアントで /version と /proxies を確認し、API の仕様差を吸収できるようスクリプトを作ってください。

APIをインターネットから操作しても問題ありませんか？

推奨できません。認証情報が漏れると、第三者にプロキシ設定を変更されたり、接続状態を取得されたりする危険があります。遠隔操作が必要な場合は、VPN、SSH トンネル、アクセス元を限定したファイアウォールなどを組み合わせ、管理ポートを直接公開しない構成にしてください。

GUI に自動切替機能があっても、クライアントごとに設定画面や判定条件が異なり、細かなログを残せない場合があります。API を使った外部監視なら、切替回数や失敗理由を保存し、複数のクライアントやサーバーで同じ運用方針を共有できます。一方で、スクリプトを手作業で組むツールは認証、URL エンコード、再試行処理の設定が複雑になりやすく、障害時に原因を追いにくいことがあります。Clash はプロキシグループ、ルール、API、詳細な接続ログを一つの構成で扱えるため、段階的に監視を強化しながら運用できます。自動切替を安全に試したい方は、対応クライアントを用意して設定をバックアップしたうえで、Clashを無料でダウンロードして実際の環境で確認してみてください。