はじめに

Clash の外部コントローラー API は、現在のプロキシモードや接続中のノードを、別のアプリケーションやスクリプトから操作するための管理インターフェースです。画面を開いて手動でノードを変更しなくても、レイテンシ、接続状態、時間帯、サーバーの混雑状況などを判断材料にして、最適なノードへ切り替えられます。

特に Clash Verge Rev や Mihomo を常時起動しているサーバー、ホームラボ、リモートワーク用 PC では、API による自動化が有効です。たとえば、定期的に候補ノードを測定し、応答速度が最も良いノードをプロキシグループへ設定する運用が可能です。接続が切れた場合だけ予備ノードへ切り替える構成にすれば、頻繁な変更による不安定化も抑えられます。

この記事の目的

API の認証、プロキシグループの確認、ノードの遅延測定、グループ選択の変更までを一通り設定し、無人環境でも安全に自動切替できる仕組みを構築します。

1外部コントローラー API の基本

外部コントローラーは、Clash のコアが待ち受ける HTTP API です。通常はローカルホスト上のポートで提供され、プロキシグループ、個別プロキシ、接続情報、設定値などを JSON 形式で取得または変更できます。Mihomo では、設定ファイルの external-controller にアドレスを指定し、secret で認証用のトークンを設定します。

基本的な API 設定例

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

127.0.0.1 に限定すると、同じ端末上のスクリプトだけが API に接続できます。別の PC や監視サーバーから操作する必要がある場合は、待受アドレスを変更できますが、ファイアウォールで接続元を制限し、長く推測しにくい secret を必ず設定してください。

API を公開しない

外部コントローラー API は管理権限に相当する操作を受け付けます。インターネットへ直接公開したり、ルーターのポート転送で開放したりするのは避けてください。リモート操作が必要な場合は、VPN や SSH トンネルを利用する方が安全です。

認証ヘッダーの指定方法

API リクエストには、設定したシークレットを Authorization ヘッダーで渡します。形式は Bearer に続けてトークンを記述します。トークンを URL のクエリ文字列へ付ける方法は、アクセスログや履歴に残る可能性があるため使用しないでください。

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

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

自動切替を始める前に、設定ファイル内のプロキシグループ名を正確に確認します。サブスクリプションによってグループ名は異なり、PROXY、Proxy、GLOBAL、地域別のグループなど、表示名に日本語や記号が含まれる場合もあります。推測で URL を作るのではなく、まず API から一覧を取得してください。

curl -s \
  -H "Authorization: Bearer $CLASH_SECRET" \
  http://127.0.0.1:9090/proxies

返却された JSON の proxies オブジェクトには、プロキシグループと個別ノードの情報が含まれます。グループには all、now、type、all の配列などがあり、type が Select のグループは API から選択中のノードを変更できます。一方、URLTest や LoadBalance のグループは内部の選択方式が異なるため、手動切替 API を適用する前に動作を確認しましょう。

遅延測定 API の使い方

ノードの応答速度は、プロキシ名を URL エンコードした delay エンドポイントで測定できます。テスト対象の URL は、実際に利用するサービスに近いものを選びます。単純な HTTP 204 応答を使うと比較しやすく、対象サービスの認証ページだけで測定するよりも、不要な負荷をかけずに済みます。

curl -s \
  -H "Authorization: Bearer $CLASH_SECRET" \
  "http://127.0.0.1:9090/proxies/JP%20Node%201/delay?url=http%3A%2F%2Fwww.gstatic.com%2Fgenerate_204&timeout=5000"

数値が小さいほど応答は速くなります。ただし、1 回だけの測定結果で切り替えると、一時的な混雑や DNS の揺らぎに反応してしまいます。複数回測定して中央値を使う、一定時間内に連続して失敗した場合だけ切り替える、といった条件を設けることが重要です。

3実際に自動切替を構築する

ここでは、候補ノードの遅延を API で測定し、最も速いノードを PROXY という Select グループへ設定する例を紹介します。グループ名とノード名は、自分の環境で取得した値に置き換えてください。自動化スクリプトは、Clash と同じ端末で実行する構成を前提にしています。

Python による簡易切替スクリプト

import os
import statistics
import time
import urllib.parse
import requests

API = "http://127.0.0.1:9090"
SECRET = os.environ["CLASH_SECRET"]
GROUP = "PROXY"
NODES = ["JP Node 1", "JP Node 2", "SG Node 1"]
TEST_URL = "http://www.gstatic.com/generate_204"

headers = {"Authorization": f"Bearer {SECRET}"}
results = {}

for node in NODES:
    encoded = urllib.parse.quote(node, safe="")
    params = {"url": TEST_URL, "timeout": 5000}
    samples = []
    for _ in range(3):
        try:
            response = requests.get(
                f"{API}/proxies/{encoded}/delay",
                headers=headers,
                params=params,
                timeout=8
            )
            value = response.json().get("delay")
            if isinstance(value, int):
                samples.append(value)
        except (requests.RequestException, ValueError):
            pass
        time.sleep(1)

    if samples:
        results[node] = statistics.median(samples)

if results:
    best = min(results, key=results.get)
    requests.put(
        f"{API}/proxies/{urllib.parse.quote(GROUP, safe='')}",
        headers=headers,
        json={"name": best},
        timeout=8
    )
    print(f"selected: {best}, delay: {results[best]} ms")
else:
    raise SystemExit("no healthy node found")

実行前に CLASH_SECRET 環境変数へ API トークンを設定します。スクリプトでは各ノードを 3 回測定し、中央値が最も小さいノードを採用しています。測定に失敗したノードは候補から除外するため、一時的に停止しているノードがあっても全体の処理は継続できます。

切替頻度と安定性を調整する

最速のノードを毎回選ぶだけでは、数ミリ秒の差でノードが頻繁に入れ替わることがあります。現在のノードより一定値以上速い場合だけ切り替える、同じノードを最低 10 分維持する、切替後に再測定する、といったルールを加えると安定します。たとえば、現在 180 ms のノードを使用中なら、120 ms 未満の候補が見つかった場合だけ変更する、という閾値を設定できます。

測定間隔： 通常は 5〜15 分に 1 回程度。短すぎる間隔は API と対象サイトの負荷を増やします。
失敗判定： 1 回のタイムアウトでは切り替えず、2〜3 回連続で失敗した場合に予備ノードへ移行します。
ヒステリシス： 現在のノードとの差が小さい場合は切り替えず、無用な再接続を防ぎます。
除外リスト： 認証エラー、容量制限、動画に不向きなノードなどは自動選択の候補から外します。

4運用時の確認とトラブル対策

API が応答しない場合は、まず Clash が起動しているか、設定ファイルが実際に読み込まれているかを確認します。設定を変更した後にコアを再起動していないと、古いポートやシークレットが有効なままになっていることがあります。また、127.0.0.1:9090 が別のプロセスで使用されていないかも確認してください。

401 または 403： Authorization ヘッダーの形式、シークレットの文字列、余分な空白を確認します。
404： プロキシ名やグループ名の URL エンコードが不正でないか確認します。日本語、空白、記号は必ずエンコードしてください。
400： Select ではないグループに選択変更を送っていないか、JSON のキーが name になっているか確認します。
遅延が常に失敗： テスト URL がノード側で遮断されている可能性があります。複数の HTTPS URL や軽量な応答先で比較してください。
切替後に通信が止まる： 新しいノードの UDP 対応、DNS、TLS、地域制限を確認し、切替後に接続テストを実行します。

ログを残すポイント

切替時刻、元のノード、選択後のノード、各ノードの遅延、失敗理由を記録すると、時間帯による混雑や特定ノードの不調を把握しやすくなります。API シークレットそのものはログへ出力しないでください。

よくある質問

Clash Verge Rev でも利用できますか？

利用できます。Clash Verge Rev で使用しているコアが Mihomo であり、外部コントローラーが有効になっていれば、同じ API 仕様で操作できます。画面上の設定が優先される場合があるため、API で変更した後に手動操作やプロファイル更新を行うと、選択状態が戻ることがあります。

グループ名が分かりません。どう調べればよいですか？

GET /proxies の結果を確認するのが確実です。JSON のトップレベルにあるキーと各グループの type、all 配列を確認し、実際に選択変更を行いたい名前をそのまま使用してください。表示名と内部名が異なるケースもあるため、設定ファイルだけで判断しないことが大切です。

外部ネットワークから API を操作しても安全ですか？

API ポートをそのまま WAN へ公開する方法は推奨できません。どうしても遠隔操作が必要な場合は、VPN のプライベートネットワーク、SSH ポートフォワーディング、またはアクセス元を限定したファイアウォールを利用してください。強力なシークレットを設定しても、管理 API の不用意な公開は避けるべきです。

自動切替すれば常に最速になりますか？

必ずしもそうとは限りません。遅延が低くても、パケットロス、帯域幅、混雑、ストリーミングとの相性、接続先による地域差があるためです。遅延だけでなく、実際のサービスへの接続成功率や通信の安定性も記録し、用途別にグループや候補ノードを分けると、より実用的な運用になります。

API による自動切替は、単純に最速のノードを選ぶ機能ではありません。認証情報を安全に管理し、測定の揺らぎを抑え、切替条件と復旧方法を明確にすることで、無人運用でも扱いやすいネットワーク環境を作れます。

Clashを無料でダウンロード — 快適なネット体験をはじめよう →

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