ClashのAPIでプロキシを自動切替|external-controller実装ガイド
external-controller APIでできることと安全上の前提
ClashやMihomoのexternal-controllerは、実行中のコアの状態を取得したり、プロキシグループの選択先を変更したりするためのHTTP APIです。GUIクライアントの画面操作を自動化するのではなく、コアが提供するコントロール用インターフェースへリクエストを送ります。そのため、自動切替を作る前に、使用中のクライアントがAPI対応のコアを起動していること、APIのアドレスとポートが現在の設定に合っていることを確認してください。
設定例では、APIをローカル端末だけに公開するため、次のようにループバックアドレスへバインドします。ポート番号は例であり、実際にはクライアントの有効な設定を優先します。
external-controller: 127.0.0.1:9090
secret: "十分に長いランダムな文字列"
external-controllerはシステムプロキシ用の待受ポートとは別物です。ブラウザーやターミナルのプロキシ先に指定するのではなく、スクリプトやGUIがコアを操作するために使います。APIに認証を設定した場合、リクエストには通常、Authorization: Bearer ...ヘッダーでSecretを渡します。Secretを設定ファイルに直接書く場合は、ファイルのアクセス権を制限し、スクリーンショットや公開ログに値が残らないようにしてください。
APIの仕様や対応項目はコアの種類とバージョンによって異なる場合があります。Mihomoを使っている場合も、実行中のバージョンとクライアントのログを確認し、該当するAPIエンドポイントが利用可能かを先にテストします。APIが接続できないときは、ノードの問題と決めつけず、まずコアが起動しているか、設定の変更が反映されたか、ポート競合がないかを切り分けましょう。
プロキシグループの構造を読み取り切替先を選ぶ
プロキシの一覧を取得する基本的なエンドポイントはGET /proxiesです。応答には、プロキシやグループの名前、種類、現在の選択先、選択可能な候補などが含まれます。目的のグループを選ぶときは、表示名だけでなく種類も確認してください。Selectorは手動選択を行うグループで、URLTestやFallbackなどは自動テストや優先順位に基づいて動作する別種のグループです。構成が異なるグループを同じ手順で操作すると、期待した結果にならないことがあります。
指定したグループの詳細はGET /proxies/{グループ名}で取得できます。Selectorでは、候補の一覧と現在の選択先を確認した後、PUT /proxies/{グループ名}へJSONを送って選択を更新します。リクエスト本文の形式は次のとおりです。
{
"name": "選択するプロキシ名"
}
実際のプロキシ名は大文字・小文字、記号、空白を含む場合があります。名前を手作業でURLへ連結すると、空白や日本語を含む名前でリクエストが失敗することがあります。HTTPクライアントのURLエンコード機能を使い、パス部分を適切にエスケープしてください。また、リクエスト本文の名前は、グループの候補一覧に実在する値と完全に一致させます。
- グループが見つからない:設定内の実際のグループ名とAPI応答のキーを照合します。表示名を独自に短縮しているクライアントでは、画面表示とAPI上の名前が異なることがあります。
- 候補が見つからない:サブスクリプションの更新が完了しているか、グループの参照先にノードやProviderが含まれているかを確認します。
- 選択が拒否される:対象のグループがSelectorか、指定名が候補に含まれるか、APIが認証済みかを確認します。
グループの候補には、別のプロキシグループ、DIRECT、REJECTなどが含まれる場合があります。遅延測定を行う自動切替スクリプトでは、これらを実ノードと同じ候補として扱わないようにします。候補の詳細をGET /proxies/{候補名}で取得し、グループや直接接続などを除外してから測定する方法が安全です。
遅延を測定してSelectorを切り替える
自動切替では、「遅延が最小のノードを一度選ぶ」だけでなく、測定に失敗した候補の扱い、APIのタイムアウト、応答がない場合の再試行も決めておきます。以下の例はPython標準ライブラリだけを使い、Selectorグループの候補を順番に測定して、設定したURLへの応答が確認できた中から遅延の小さいノードを選択します。APIポート、グループ名、Secretは実環境に合わせて変更してください。
import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request
API = "http://127.0.0.1:9090"
GROUP = "自動選択"
SECRET = os.environ["CLASH_SECRET"]
TEST_URL = "https://www.gstatic.com/generate_204"
TIMEOUT_MS = 5000
def request(path, method="GET", body=None, retries=3):
data = None if body is None else json.dumps(body).encode("utf-8")
headers = {"Authorization": f"Bearer {SECRET}"}
if data is not None:
headers["Content-Type"] = "application/json"
for attempt in range(retries):
req = urllib.request.Request(
API + path, data=data, headers=headers, method=method
)
try:
with urllib.request.urlopen(req, timeout=8) as response:
return json.loads(response.read().decode("utf-8"))
except urllib.error.HTTPError as error:
if error.code < 500 or attempt == retries - 1:
raise
except (urllib.error.URLError, TimeoutError):
if attempt == retries - 1:
raise
time.sleep(0.5 * (2 ** attempt))
def path_name(name):
return urllib.parse.quote(name, safe="")
group_path = "/proxies/" + path_name(GROUP)
group = request(group_path)
if group.get("type") != "Selector":
raise RuntimeError("対象グループはSelectorではありません")
candidates = group.get("all", [])
results = []
for name in candidates:
if name.upper() in {"DIRECT", "REJECT", "REJECT-DROP"}:
continue
detail = request("/proxies/" + path_name(name))
if detail.get("type") in {"Selector", "URLTest", "Fallback", "LoadBalance"}:
continue
query = urllib.parse.urlencode({
"url": TEST_URL,
"timeout": str(TIMEOUT_MS)
})
try:
result = request(
"/proxies/" + path_name(name) + "/delay?" + query
)
delay = int(result["delay"])
if delay > 0:
results.append((delay, name))
except (urllib.error.HTTPError, urllib.error.URLError,
TimeoutError, KeyError, ValueError):
continue
if not results:
raise RuntimeError("応答を確認できる候補がありません")
delay, selected = min(results)
request(group_path, method="PUT", body={"name": selected})
print(f"選択: {selected} / 遅延: {delay} ms")
実行前に、環境変数へSecretを設定します。macOSやLinuxのシェルでは、たとえばexport CLASH_SECRET='設定したSecret'を実行してからスクリプトを起動します。PowerShellでは$env:CLASH_SECRET = '設定したSecret'のように設定できます。履歴に認証値を残したくない場合は、シェルの履歴管理やタスク実行環境のシークレット保管機能も確認してください。
この例の遅延は、指定したURLへのテスト結果です。ノードの品質全体を示す値ではなく、測定先の応答状況、DNS、時刻、ネットワーク混雑の影響を受けます。実運用では、テスト先が利用環境から安定して到達できるかを確認し、過剰な頻度で測定しないようにします。候補数が多い場合は、全ノードを短い間隔で繰り返し測定せず、実行間隔を数分程度にする、直近の失敗状態を記録する、現在選択中のノードに十分な余裕がある場合は切り替えない、といった制御を加えると安定します。
応答確認、リトライ、失敗時の切り分け
自動切替は、APIの応答が返ったことと、ノード経由の通信が成功したことを別々に確認する必要があります。コントローラーからHTTP 200が返っても、テスト先への接続が成功したとは限りません。一方、遅延測定が一度失敗しただけでノードが完全に停止しているとも判断できません。タイムアウト、DNSの一時障害、測定先の制限などを考慮し、少なくとも複数回の失敗や、別のテスト先での確認を組み合わせます。
リトライは回数と待ち時間を制限してください。上の例では最大3回、待ち時間を段階的に増やし、サーバーエラーや一時的な通信エラーを再試行します。認証失敗や存在しないグループのようなクライアント側エラーは、同じリクエストを繰り返しても解消しないため再試行しません。切替処理自体は同じSelectorに同じ候補を指定する操作なので再実行できますが、APIが成功したか不明な場合は、再送の前後にグループの現在値を読み直すと状態を把握しやすくなります。
- 接続拒否:コアが起動しているか、
external-controllerのアドレスとポートが正しいかを確認します。別のコアが同じポートを使っていないかも調べます。 - 401または403:Secretの値、Bearerヘッダーの形式、実際に読み込まれている設定を確認します。クライアントの再起動後にSecretが変わっていないかも確認してください。
- 404:グループ名のURLエンコード、APIパス、コアのバージョンを確認します。大文字・小文字や空白の違いも見落としやすい点です。
- 遅延測定だけが失敗:テストURLへの直接アクセス可否、候補名、測定タイムアウト、DNSの状態を確認します。全候補が失敗する場合は、自動的に不明な候補へ切り替えず、現在の選択を維持する設計にします。
- 切替後も通信が変わらない:対象ルールが本当にそのグループを参照しているか、新しい接続で検証しているか、別のクライアントやTUNが通信を処理していないかを確認します。
スクリプトを常駐させる場合は、終了コードとログを残し、API応答にSecretやサブスクリプション情報を記録しないようにします。起動のたびに現在の選択先を確認し、切替が不要なら何もしないことも重要です。APIを使った選択変更は、GUI上の一時的な操作とは異なり、コアの実行状態を直接変更します。設定ファイルやサブスクリプションがその選択を永続化するかどうかはクライアントによって異なるため、再起動後に選択が維持されるとは限りません。
よくある質問
external-controllerのポートは7890ですか?
必ずしもそうではありません。7890はプロキシのmixed-portとして使われる例が多く、コントローラー用ポートとは用途が異なります。設定のexternal-controllerまたはクライアントのコア設定画面で、実際のアドレスを確認してください。
URLTestグループもこのスクリプトで切り替えられますか?
この例は手動選択を行うSelectorを対象にしています。URLTestはコア側がテスト先と選択を管理するグループであり、候補を外部スクリプトから直接選ぶ方法は同じではありません。グループの種類と使用中コアのAPI仕様を確認し、目的に合わない場合はSelectorを使う構成にします。
Clash Vergeなどの画面を開いたままでも使えますか?
コアが起動し、コントローラーAPIが有効であれば、通常は画面を操作せずAPIへ接続できます。ただし、クライアントがコアを停止したり、設定更新でAPIポートやSecretを変更したりすることがあります。実行中の設定を確認し、クライアントの更新後には接続テストをやり直してください。
LAN内の別端末からAPIを操作できますか?
技術的に可能な構成はありますが、コントローラーはプロキシ選択などを操作できる管理インターフェースです。アクセス範囲、強いSecret、OSファイアウォールを適切に設定できない場合は公開しないでください。通常の自動切替スクリプトは、Clashと同じ端末上で実行してループバック接続を使う方法が安全です。