はじめに

GitHub のリポジトリを取得したり、Docker Hub からイメージを pull したり、AI ツールへアクセスしたりする際、通信先に応じて適切なノードを選ぶことは安定性を大きく左右します。しかし、サービスごとに手動でノードを切り替える運用は、作業を中断するだけでなく、混雑や障害が発生したときに切り替えが遅れる原因にもなります。

Clash API を利用すると、現在選択されているプロキシグループ、各ノードの遅延、HTTP リクエストの成功状況を外部スクリプトから取得できます。これらの情報を組み合わせれば、単純に「最も ping が速いノード」を選ぶのではなく、実際に目的のサービスへ接続できる可能性が高い出口へ自動的に切り替えられます。

本記事では、Mihomo や Clash Verge Rev で利用できる External Controller API を前提に、ノード検査、スコアリング、切り替え、ログ出力、障害時の復旧までを一つの運用フローとして整理します。設定をそのまま適用するだけでなく、なぜその設計が必要なのかも順番に解説します。

この記事の目標

API でノードの状態を定期的に確認し、遅延だけでなく成功率、地域、負荷、切り替え頻度を考慮した自動選択を実現します。

1APIを有効にする前の準備

自動切替スクリプトを作る前に、Clash 側で API の待受先と認証方法を確認します。Mihomo の設定では、通常 external-controller に API のアドレスを指定します。ローカルマシンだけから利用する場合は、外部公開を避けるため 127.0.0.1 にバインドするのが基本です。

Mihomo の基本設定例

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

# 必要に応じて WebSocket API も有効化
external-controller-cors:
  allow-origins:
    - http://127.0.0.1
    - http://localhost

secret は推測されにくい長いランダム文字列に変更してください。API ポートを 0.0.0.0 で待ち受けると、同一ネットワーク上の他の端末から操作される危険があります。リモートから操作する必要がある場合も、ファイアウォールで接続元を限定し、TLS や安全なトンネルを検討してください。

Clash Verge Rev を使用している場合は、プロファイルを編集する前に現在のコアが Mihomo であることを確認します。サブスクリプションから生成された設定を直接書き換えると、次回更新時に変更が失われることがあります。自動切替に必要な共通設定は、Merge 設定、ローカルオーバーライド、または更新後にも適用できる専用プロファイルへ分離するのが安全です。

利用するAPIエンドポイント

ノード情報は GET /proxies、プロキシグループの現在選択されているノードは GET /proxies/{name} で取得できます。グループを切り替えるときは、対象グループへ PUT /proxies/{name} を送信し、JSON の name に選択したノード名を指定します。ノード名に日本語や記号が含まれる場合は、URL に埋め込む前に必ず URL エンコードしてください。

セキュリティのポイント

API トークンをスクリプトへ直書きする場合はファイルの権限を制限し、GitHub のリポジトリや共有ログへコミットしないでください。環境変数や OS の資格情報ストアから読み込む方法がより安全です。

2ノード検査とスコアリング

自動切替でよくある失敗は、遅延値だけを見てノードを選ぶことです。ICMP ping が速くても、GitHub の API が拒否する、Docker Hub への TLS 接続が失敗する、AI サービスの認証ページだけが開けない、といったケースがあります。そのため、実際に利用するサービスに近い URL へ HTTP 検査を行い、接続成功率を記録する必要があります。

Mihomo にはプロキシの遅延を測定する API が用意されています。代表的には GET /proxies/{proxy}?url=https://www.gstatic.com/generate_204 のように、テスト URL とタイムアウトを指定します。URL はクライアントやコアのバージョンによって扱いが異なるため、実環境でステータスコードとレスポンスを確認してください。

選択ロジックの考え方

遅延： 低いほど有利ですが、瞬間的な値だけで判断せず、複数回の中央値を使用します。
成功率： 直近 5〜10 回の検査で何回成功したかを記録し、接続が不安定なノードを除外します。
用途別の到達性： GitHub、Docker Hub、AI ツールなど、実際に利用するドメインへ個別に確認します。
地域とポリシー： サービスの利用条件、アカウントの地域、組織の規則に適合するノードだけを候補にします。
切替コスト： ストリーミングやアップロード中の切替は通信を中断するため、頻繁な変更を避けます。

例えば、スコアを 遅延スコア × 0.4 + 成功率 × 0.5 + 安定性 × 0.1 とし、成功率が 80 パーセント未満のノードは候補から外す方法があります。数値は環境によって調整してください。GitHub の clone が中心なら遅延と TLS 成功率を重視し、Docker イメージの取得が中心なら長時間転送中の切断回数や帯域も評価対象にします。

候補ノードを取得
  ↓
各ノードを複数回検査
  ↓
タイムアウト・失敗を除外
  ↓
遅延の中央値と成功率を計算
  ↓
現在のノードとの差が十分な場合だけ切替

Pythonによる最小構成

以下はローカル API からプロキシ一覧を取得し、指定グループの候補を確認する最小例です。実運用では、グループ名を自分の設定に合わせ、ノード名に含まれる地域や用途の文字列をフィルタリングしてください。

import os
import requests

API = "http://127.0.0.1:9090"
TOKEN = os.environ["CLASH_SECRET"]
GROUP = "Auto-Select"

headers = {"Authorization": f"Bearer {TOKEN}"}
response = requests.get(f"{API}/proxies/{GROUP}", headers=headers, timeout=5)
response.raise_for_status()

data = response.json()
for name in data.get("all", []):
    print(name)

ノード名をそのまま信頼するのではなく、グループ API の all に含まれるものだけを選択対象にしてください。設定ファイルに存在しない名前を送信すると切替に失敗するため、取得した一覧と候補リストを照合することが重要です。

3安全な自動切替スクリプトを作る

実際の切替処理では、最良のノードを見つけた瞬間に毎回変更するのではなく、ヒステリシスを設けます。現在のノードより少し速いだけのノードへ変更すると、測定値の揺らぎによって切替が繰り返されるからです。例えば、新しいノードのスコアが現在より 20 パーセント以上改善している場合だけ切り替え、同じノードに最低 10 分は留まるようにします。

import time
import requests
from urllib.parse import quote

API = "http://127.0.0.1:9090"
TOKEN = os.environ["CLASH_SECRET"]
GROUP = "Auto-Select"
TEST_URL = "https://www.gstatic.com/generate_204"
MIN_INTERVAL = 600
IMPROVEMENT = 0.20

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

def delay(name):
    path = quote(name, safe="")
    r = session.get(
        f"{API}/proxies/{path}/delay",
        params={"url": TEST_URL, "timeout": 5000},
        timeout=8
    )
    r.raise_for_status()
    return r.json()["delay"]

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

def choose(names):
    results = {}
    for name in names:
        try:
            results[name] = delay(name)
        except requests.RequestException:
            continue
    return min(results, key=results.get) if results else None

この例は遅延測定と切替 API の骨格を示すものです。実際には現在のノード名、最後に切り替えた時刻、直近の失敗回数を状態ファイルへ保存します。監視処理が再起動しても、直後に大量の API リクエストを発生させたり、切替を連続実行したりしないようにするためです。

リトライ： API が一時的に応答しない場合は、指数バックオフで 2〜3 回だけ再試行します。
タイムアウト： ノードごとの検査に上限を設け、停止したノードのために全体が待たされないようにします。
除外リスト： 認証失敗、極端なパケットロス、帯域不足が確認されたノードは一定時間ブラックリスト化します。
手動優先： 作業中に手動選択された場合は、自動処理を一時停止できるフラグを用意します。

頻繁な切替に注意

ノードを切り替えると TCP セッション、認証状態、Docker のダウンロード接続などが中断されることがあります。自動化の目的は常時変更することではなく、障害時に適切なノードへ一度だけ移行することです。

4運用、ログ、トラブル対策

スクリプトを常駐させる場合は、単に「切り替えた」というログだけでなく、判断材料を残してください。日時、現在のノード、候補ノード、測定遅延、成功率、切替理由、API のステータスコードを記録すると、後から障害を再現しやすくなります。ただし、Authorization ヘッダー、サブスクリプション URL、Cookie、AI サービスのトークンは絶対にログへ書き出さないでください。

よくあるエラーと確認項目

401 Unauthorized： secret と Bearer トークンが一致しているか、前後に余分な空白がないか確認します。
404 Not Found： API パス、プロキシグループ名、使用している Clash コアの仕様を確認します。
400 Bad Request： PUT の JSON が {"name":"ノード名"} 形式になっているか確認します。
タイムアウト： ノード自体の問題だけでなく、テスト URL が現在の経路から到達可能か、DNS が正常かを調べます。
切替後も通信が変わらない： 実際に通信しているプロキシグループと、API で変更したグループが同じか確認します。

GitHub、Docker Hub、AI ツールを同じグループへまとめると管理は簡単ですが、必要な地域や接続特性が異なる場合があります。より安定させたい場合は、GitHub-Auto、Docker-Auto、AI-Auto のように用途別グループを作り、ルールで振り分けます。自動選択スクリプトもグループ単位で実行すれば、Docker の大容量転送が他の通信のノード選択へ影響することを防げます。

本番運用前のチェックリスト

API を localhost に限定し、強い認証トークンを設定する。
候補ノードを少なくとも 3 回ずつ検査し、中央値と成功率を保存する。
切替の最低間隔と、現在のノードへ戻す条件を決める。
API 障害時は現在の接続を維持し、無闇に DIRECT へ変更しない。
ログから秘密情報を除外し、一定期間後にローテーションする。
手動停止スイッチを用意し、作業中の予期しない切替を防ぐ。

最終的に重要なのは、最短遅延のノードを永久に選ぶことではありません。目的のサービスへ安定して到達でき、失敗時には原因を追跡でき、必要なら人間が自動化を停止できることです。Clash API は非常に強力ですが、認証情報の保護、利用規約の遵守、プロバイダーの許可範囲、地域ごとの法令を確認したうえで運用してください。

自動切替を初めて導入する場合は、まず手動実行のスクリプトとして動作を確認し、その後に 5〜10 分間隔のスケジューラーへ移行する方法がおすすめです。検査対象、スコアの重み、切替間隔をログを見ながら調整すれば、不要な切替を減らしながら、GitHub や Docker Hub、AI ツールをより快適に利用できる環境を構築できます。

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

Clash APIでノード自動切替を実装する高度なスクリプト設定