Clash External Controller APIでノード自動切替を実装する設定ガイド

Clash External Controller APIで実現できること

Clash External Controller APIは、Clash や Mihomo の稼働状態を外部プログラムから読み取り、プロキシグループや接続設定を操作するための HTTP API です。通常の GUI では、ユーザーが画面を開いてノードを選び、遅延テストを実行してから切り替える必要があります。しかし external-controller を有効にすれば、スクリプトや監視サービスがノードの状態を定期的に確認し、応答時間、接続失敗、特定 URL の到達性などを条件に自動切替できます。

この仕組みは、単純に「一番速いノードを常に選ぶ」ためだけのものではありません。短時間の遅延変動で頻繁に切り替わると、既存の TCP 接続やログインセッションが切断され、かえって使いにくくなるからです。実運用では、複数回連続した失敗、許容遅延の超過、クールダウン時間を組み合わせ、安定性を優先したフェイルオーバーとして設計するのが基本です。

対象は Clash Verge、Clash Verge Rev、Mihomo 系クライアント、ルーター上の OpenClash などです。ただし、画面上の項目名や対応 API はコアの世代によって異なる場合があります。本稿では、共通して使いやすい API の考え方を中心に説明し、最後に実際に動かせる設定例と Python スクリプトを示します。

external-controller の公開範囲と認証を先に決める

最初に確認したいのは、API の便利さではなく誰が API を呼び出せるかです。External Controller はプロキシの状態を読むだけでなく、プロキシグループの選択、設定の再読み込み、接続の終了なども実行できます。認証なしで LAN やインターネットへ公開すると、第三者にノードを変更されたり、設定情報を取得されたりする危険があります。

ローカル端末だけから利用する場合は、次のようにループバックアドレスへバインドします。ポート番号は既存サービスと重ならないものを選びます。

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

同じ LAN 上の監視サーバーからアクセスする必要がある場合だけ、バインド先を LAN 内のアドレスまたは全インターフェースへ変更します。その場合もファイアウォールで送信元を限定し、長く推測しにくい secret を必ず設定してください。Mihomo の構成では、コントローラーを HTTPS で保護するための証明書設定を利用できる場合もありますが、クライアント側の対応状況を確認してから導入します。

secret を URL やログへ直接書かないでください:トークンをコマンドライン引数や共有チャットに残すと、シェル履歴、CI ログ、監視ログから漏れることがあります。環境変数や権限を制限した設定ファイルで管理し、漏えいした場合はすぐにローテーションしてください。

API が起動しているかは、まずプロセスと同じ端末から確認します。認証を設定した場合は Authorization ヘッダーを付けます。

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

/version が JSON を返せば、コントローラーへの基本接続は成立しています。返答がない場合は、Clash コアが実際に読み込んでいるプロファイル、ポート競合、OS のファイアウォール、GUI が管理する設定と手動編集した YAML の優先関係を順番に確認します。

ノード状態を読むために使う主要 API

自動切替には多くのエンドポイントは必要ありません。まずグループ一覧を取得し、対象グループの名前と現在選択されているプロキシを特定します。一般的な Clash API では、プロキシ情報を /proxies から取得できます。

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

レスポンスには、プロキシグループと個別ノードの両方が含まれます。グループは Selector、URLTest、Fallback などの種類として表示され、グループの now が現在の選択先です。自動化スクリプトでは、表示名を推測せず、最初に返された JSON を保存して実環境の名前を確認してください。購読サービスによっては、同じ地域名の後ろに倍率や倍率記号が付くためです。

  • GET /version:Clash コアや Mihomo のバージョン確認に使います。
  • GET /proxies:グループ、ノード、現在の選択状態を取得します。
  • GET /proxies/{name}/delay:指定したプロキシの URL テストを実行します。
  • PUT /proxies/{name}:Selector 系グループの現在のプロキシを変更します。
  • GET /connections:現在の接続数や通信先を調査します。

名前に日本語、スラッシュ、括弧が含まれるグループでは、API パスを URL エンコードする必要があります。Python の requests を使えば、パスの組み立てをライブラリに任せられるため、手作業で文字列を連結するより安全です。また、遅延テストの URL は普段使うサービスに近い HTTPS エンドポイントを選びます。常に同じ CDN の小さな応答だけを測ると、動画、開発 API、画像配信で実際に感じる品質を反映できないことがあります。

実装手順:遅延と接続失敗でプロキシを切り替える

ここでは Auto という Selector グループに複数ノードが登録されている前提で、最も安定したノードを選ぶ簡易スクリプトを作ります。処理の要点は、候補を一度だけ測って即座に切り替えるのではなく、失敗回数と切替間隔を記録することです。

  1. 対象グループを確認:/proxies のレスポンスから、実際に切り替えたい Selector 名と候補ノード名を確認します。購読更新で名前が変わる場合は、固定名ではなく接頭辞やタグで候補を抽出します。
  2. 測定 URL を決める:自分が日常的に使う HTTPS URL を一つ以上用意し、タイムアウト値を短すぎない範囲で設定します。DNS だけの測定にならないよう、HTTP ステータスまで確認できる URL が適しています。
  3. 候補を評価する:各ノードを複数回測定し、成功回数、中央値、最大遅延を保存します。一回だけ速いノードではなく、成功率が高く中央値が低いノードを優先します。
  4. 切替条件を適用する:現在のノードが連続して失敗した場合、または遅延が上限を超えた状態が続いた場合だけ切り替えます。切替後は一定時間、再評価による連続切替を抑制します。
  5. ログと通知を残す:時刻、旧ノード、新ノード、測定値、切替理由を記録します。障害がプロキシ側なのか、ローカル回線なのかを後から判断するために重要です。

次の例は、Python 3 と requests を使った最小構成です。対象グループ名、テスト URL、候補除外語は自分の環境に合わせて変更してください。実際の API 仕様やコアのバージョンによって、遅延測定のレスポンス形式が異なることがあるため、最初はログを確認しながら試します。

import os
import time
import statistics
import requests

API = "http://127.0.0.1:9090"
SECRET = os.environ["CLASH_SECRET"]
GROUP = "Auto"
TEST_URL = "https://www.gstatic.com/generate_204"
TIMEOUT_MS = 1800
COOLDOWN = 300

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {SECRET}"})

def get_proxies():
    response = session.get(f"{API}/proxies", timeout=5)
    response.raise_for_status()
    return response.json()["proxies"]

def measure(name):
    values = []
    encoded = requests.utils.quote(name, safe="")
    for _ in range(3):
        try:
            data = session.get(
                f"{API}/proxies/{encoded}/delay",
                params={"url": TEST_URL, "timeout": TIMEOUT_MS},
                timeout=5
            ).json()
            values.append(int(data["delay"]))
        except Exception:
            pass
    return statistics.median(values) if values else None

def select(name):
    response = session.put(
        f"{API}/proxies/{requests.utils.quote(GROUP, safe='')}",
        json={"name": name},
        timeout=5
    )
    response.raise_for_status()

while True:
    data = get_proxies()
    group = data.get(GROUP, {})
    candidates = [
        name for name in group.get("all", [])
        if "DIRECT" not in name and "REJECT" not in name
    ]
    results = [(name, measure(name)) for name in candidates]
    usable = [(name, delay) for name, delay in results if delay is not None]
    if usable:
        best = min(usable, key=lambda item: item[1])
        current = group.get("now")
        if current != best[0] and best[1] < TIMEOUT_MS:
            select(best[0])
            print(f"switched: {current} -> {best[0]} ({best[1]} ms)")
    time.sleep(COOLDOWN)

この例は理解しやすさを優先したものです。毎回すべてのノードを測ると、候補数が多い購読では API リクエストが増えます。実運用では地域ごとに代表ノードを選ぶ、前回良好だったノードを先に測る、一定時間内に測定した結果をキャッシュするなどの工夫が有効です。さらに、最速値だけでなく中央値や成功率を使うことで、瞬間的な測定誤差に引きずられにくくなります。

頻繁な切替を防ぐ評価ルール

自動化で最も多い失敗は、遅延が 150ms と 170ms の間を揺れるだけでノードを何度も変更してしまうことです。これを避けるため、現在のノードから別ノードへ切り替えるには、たとえば「現在のノードが 3 回連続で失敗」「新候補が現在より 30% 以上速い」「前回切替から 5 分以上経過」という複数条件を置きます。

また、グループの役割ごとに評価基準を分けることも大切です。動画用グループでは帯域と再生の継続性、開発 API 用グループでは TLS 接続の成功率と短い応答時間、通常閲覧用グループでは DNS とページ表示の安定性を重視します。単一の URL テストだけで全用途を判断すると、測定上は優秀でも実際のサービスでは失敗することがあります。

「最速ノード」ではなく十分に速く、長く安定しているノードを選ぶのが自動切替のコツです。切替理由をログへ残し、手動選択時の体感と比較すると、しきい値を調整しやすくなります。

動かないときの確認ポイント

API スクリプトが起動しても切替が発生しない場合、最初に疑うのはコードよりもグループの種類です。Selector は外部から選択先を変更できますが、URLTest や一部の自動グループでは、手動選択 API の挙動が異なります。GUI で表示される名前と、API の JSON に現れるキーが一致しているかを確認してください。

  • 401 や 403 が返る:Bearer トークンの値、余分な空白、secret の再読み込み状態を確認します。
  • 404 になる:URL エンコードされていない日本語名や記号がパスに含まれていないか確認します。
  • delay が常に失敗する:テスト URL が対象ネットワークでブロックされていないか、タイムアウトが短すぎないか確認します。
  • 切替後も通信が変わらない:TUN モード、システムプロキシ、アプリ独自のプロキシ設定が同じ Clash コアを通っているか確認します。
  • 購読更新後に停止する:グループ名やノード名の変更を想定し、候補一覧を毎回 API から再取得します。

切替処理を systemd、タスクスケジューラ、Docker コンテナなどで常駐させる場合は、プロセスの再起動、API の一時停止、ネットワーク断を考慮します。指数バックオフを入れずに短い間隔で再試行すると、障害中に API とログを余計に圧迫します。標準出力だけでなくファイルや journald へ記録し、秘密情報がログに出ないことも確認してください。

Clash API ノード自動切替に関する FAQ

Clash Verge と Mihomo のどちらでも使えますか?

External Controller を提供するコアであれば、基本的なバージョン取得、プロキシ一覧取得、Selector の変更という考え方を利用できます。ただし、API のパラメーター名、グループの種類、遅延テストのレスポンスはクライアントやコアの版によって差があります。まず /version と /proxies の返答を保存し、実環境に合わせてスクリプトを調整してください。

遅延のしきい値は何 ms にすればよいですか?

一律の正解はありません。普段の回線で同じ URL を数時間測定し、通常時の中央値と混雑時の値を把握してから決めます。たとえば通常 120〜220ms の環境で 300ms を警戒値にする方法はありますが、失敗率、用途、切替の影響も合わせて評価してください。

External Controller を LAN に公開しても安全ですか?

認証、ファイアウォール、送信元制限を組み合わせれば運用できますが、必要がなければ 127.0.0.1 のままにするのが安全です。ルーターでポート転送したり、認証なしでインターネットへ公開したりする構成は避けてください。

ノードが頻繁に入れ替わる場合はどうしますか?

測定回数を増やし、中央値を使い、連続失敗回数とクールダウンを設定します。現在のノードに小さな遅延差で勝っただけの候補へ切り替えないよう、ヒステリシスの幅を設けることも有効です。

自動切替を安定運用へつなげる

一部の同種クライアントや単純な VPN アプリでは、ノードの状態を細かく取得できなかったり、接続失敗の理由を確認できなかったりします。画面上の「自動選択」だけに任せる構成では、遅延の一時的な変動で切替が発生し、どの条件で経路が変わったのか追跡しにくいこともあります。

その点、Clash の External Controller API は、グループ、ノード、遅延、接続ログを同じ運用モデルで扱えます。認証付き API と測定履歴を組み合わせれば、通常閲覧、動画、開発 API など用途別に異なる条件を設定でき、短時間の揺らぎでは切り替えず、明確な障害時だけ安全にフェイルオーバーできます。スクリプトを導入する際は、まず手動実行で十分に検証し、次に常駐化する順序が適切です。

まだ Clash クライアントを用意していない場合は、対応プラットフォームを確認できるダウンロードページから取得し、External Controller の公開範囲と secret を設定してから本稿の例を試してください。

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

ダウンロードページへ