Clashのプロキシ自動切替を実装|API設定と障害検知スクリプト
自動切替の仕組みと対象範囲を整理する
ClashやMihomoのプロキシ自動切替は、ローカルのexternal-controller APIからプロキシグループと各ノードの状態を取得し、遅延テストの結果に応じて選択先を更新する仕組みです。GUIクライアントの画面を自動操作するのではなく、コアが公開するHTTP APIを使うため、定期実行スクリプトや監視ツールから制御できます。ただし、利用できるAPIや応答形式はコアの種類とバージョンに依存します。ここではMihomo系のAPIを例にし、導入前に使用中のコアが該当エンドポイントをサポートしていることを確認します。
切替の対象は、通常、手動選択型のselectグループです。url-testグループはコア自身が遅延を測定して選択先を管理するため、外部スクリプトから同じグループを頻繁に書き換えると、コアの自動選択と競合する可能性があります。既存設定をそのまま使う場合は、まずグループのtypeを確認してください。スクリプトに任せるならselect、コアに任せるならurl-testというように、選択を行う主体を一つに絞るのが基本です。
遅延値だけでノードの品質を完全に判断できるわけではありません。接続先の応答、DNS、経路の混雑、テストURL側の制限によって測定値が変わります。また、遅延が低くても実際のサービスへ接続できないノードや、短時間だけ良い値を示すノードもあります。そこで本稿の例では、テストに成功したノードのうち遅延が最も短いものを候補にし、現在の選択先が十分に良好なら小さな差では切り替えない仕組みを加えます。
external-controller APIを安全に設定する
external-controllerは、プロキシグループの参照や選択先の変更などを行うための管理用インターフェースです。通常のHTTPプロキシポートやSOCKSポートとは役割が異なります。例えば、mixed-port: 7890がアプリの通信を受け付ける一方、external-controller: 127.0.0.1:9090はAPIリクエストを受け付けます。APIポートをブラウザーやシステムプロキシの接続先として設定しても、Web通信を中継するプロキシとしては使えません。
ローカル端末だけでスクリプトを動かす場合は、コントローラーをループバックアドレスに限定し、強度のあるsecretを設定します。値を設定した場合、APIリクエストでは通常Authorization: Bearer ...ヘッダーによる認証が必要です。コントローラーを0.0.0.0やLANアドレスで待ち受けると、同じネットワーク上の端末から管理APIへ到達できる範囲が広がります。特別な理由がなければ外部公開せず、ファイアウォールでもアクセス元を制限してください。
external-controller: 127.0.0.1:9090
secret: "長く推測されにくい値"
APIの応答を確認するには、実際のコントローラーポートとキーを使って/proxiesへリクエストします。次の例はシェルの環境変数を使います。キーをコマンド行へ直接書くと、シェル履歴やプロセス情報に残ることがあるため、共有端末では特に注意してください。
export CLASH_API="http://127.0.0.1:9090"
export CLASH_SECRET="長く推測されにくい値"
curl --fail --silent --show-error \
-H "Authorization: Bearer ${CLASH_SECRET}" \
"${CLASH_API}/proxies"
正常な応答では、プロキシ名をキーとする情報の中に、グループの種類、現在の選択先、候補一覧などが含まれます。認証失敗ならキーとBearer形式、接続拒否ならポートとコアの稼働状態、404ならAPIのパスやコアの互換性を確認します。クライアント独自のAPIポートを使っている場合もあるため、既定値を決めつけず、設定と起動ログを照合してください。
遅延チェックとグループ切替をスクリプト化する
Mihomo系APIでは、個別プロキシの遅延を/proxies/{名前}/delayで測定し、選択型グループの候補をPUT /proxies/{グループ名}で変更できます。遅延チェックでは、テスト先URLとタイムアウトを指定します。測定先が一時的に応答しない場合にも切替が発生するため、よく利用するHTTPS接続先を選び、タイムアウトを短くしすぎないことが大切です。応答の遅延値はミリ秒で返されます。
以下はPythonとrequestsを使う例です。環境変数からAPIアドレス、認証キー、グループ名を読み込み、候補ごとに遅延を測定します。API通信が意図せず別のプロキシを経由しないよう、trust_env = Falseにしています。端末の環境変数でプロキシを設定している環境でも、ループバックへの管理リクエストを分離しやすくなります。
import os
import sys
import time
from urllib.parse import quote
import requests
API = os.environ.get("CLASH_API", "http://127.0.0.1:9090").rstrip("/")
SECRET = os.environ["CLASH_SECRET"]
GROUP = os.environ.get("CLASH_GROUP", "Proxy")
TEST_URL = os.environ.get("CLASH_TEST_URL", "https://www.gstatic.com/generate_204")
MAX_DELAY_MS = int(os.environ.get("CLASH_MAX_DELAY_MS", "1500"))
TIMEOUT_MS = int(os.environ.get("CLASH_TIMEOUT_MS", "5000"))
MIN_IMPROVEMENT = float(os.environ.get("CLASH_MIN_IMPROVEMENT", "0.20"))
session = requests.Session()
session.trust_env = False
session.headers.update({"Authorization": f"Bearer {SECRET}"})
def log(message):
print(f"{time.strftime('%Y-%m-%d %H:%M:%S')} {message}", flush=True)
def get_json(path):
response = session.get(f"{API}{path}", timeout=8)
response.raise_for_status()
return response.json()
def main():
group_path = quote(GROUP, safe="")
data = get_json("/proxies")
proxies = data.get("proxies", {})
group = proxies.get(GROUP)
if not group:
raise RuntimeError(f"グループが見つかりません: {GROUP}")
if group.get("type") not in ("Selector", "select"):
raise RuntimeError(
f"手動選択型グループではありません: {group.get('type')}"
)
current = group.get("now")
candidates = [
name for name in group.get("all", [])
if name in proxies and name not in ("DIRECT", "REJECT")
]
results = []
for name in candidates:
proxy_path = quote(name, safe="")
try:
response = session.get(
f"{API}/proxies/{proxy_path}/delay",
params={"timeout": TIMEOUT_MS, "url": TEST_URL},
timeout=TIMEOUT_MS / 1000 + 3,
)
response.raise_for_status()
delay = int(response.json()["delay"])
log(f"測定成功: {name} {delay}ms")
if 0 < delay <= MAX_DELAY_MS:
results.append((delay, name))
except (requests.RequestException, ValueError, KeyError) as error:
log(f"測定失敗: {name} ({error})")
if not results:
raise RuntimeError("しきい値内の利用可能な候補がありません")
best_delay, best_name = min(results)
current_result = next(
((delay, name) for delay, name in results if name == current),
None,
)
if current_result:
current_delay, _ = current_result
required_delay = current_delay * (1 - MIN_IMPROVEMENT)
if best_name == current or best_delay > required_delay:
log(f"切替不要: 現在={current} {current_delay}ms")
return
response = session.put(
f"{API}/proxies/{group_path}",
json={"name": best_name},
timeout=8,
)
response.raise_for_status()
log(f"切替完了: {current} -> {best_name} ({best_delay}ms)")
if __name__ == "__main__":
try:
main()
except Exception as error:
log(f"処理を中止: {error}")
sys.exit(1)
スクリプト内のGROUPは、設定上のプロキシグループ名と完全に一致させます。名前に空白や日本語が含まれていても、例ではURLのパス部分をエンコードしています。候補リストにはDIRECTやREJECTを含めず、実在するプロキシだけを測定します。グループ名が異なる場合は環境変数で指定してください。Pythonにrequestsがない場合は、管理対象の仮想環境へインストールして実行します。
MAX_DELAY_MSは採用する遅延の上限、MIN_IMPROVEMENTは切替に必要な改善率です。例では現在の選択先がしきい値内で応答し、最速候補との差が20%未満なら切り替えません。これにより、測定値が数十ミリ秒だけ揺れたたびに接続先が変わる現象を抑えます。値は回線や用途に合わせて調整し、低遅延を優先するサービスではテスト先も実利用に近いものにしてください。
一つの候補しか成功しない場合や、すべての候補がタイムアウトした場合、例は選択先を変更せずエラー終了します。障害時に必ず別ノードへ切り替える要件があるなら、上限を緩めるだけではなく、直近の成功値を記録する、同じ測定を複数回行う、失敗回数を条件に加えるなどの設計が必要です。単発の遅延結果を障害とみなすと、テスト先の一時障害やネットワークの瞬間的な混雑でも切替が起きます。
リトライ、ログ、定期実行を運用する
まずはスクリプトを手動実行し、API取得、測定、グループ更新の各段階がログに残ることを確認します。切替が起きない場合は、候補一覧にノードがあるか、測定APIが成功しているか、しきい値が厳しすぎないか、現在のグループが選択型かを順に見ます。切替要求の応答が成功しても、通信中のアプリが即座に別ノードへ移るとは限りません。既存の接続はそのまま維持されることがあり、新しい接続から変更先が使われます。
定期実行は、最初は5分から10分程度の間隔で試すと、過剰なAPI呼び出しを避けながら動作を確認できます。数秒ごとの実行は測定先やコアに余計な負荷をかけ、遅延変動による頻繁な切替を招きます。より短い監視間隔が必要な場合は、遅延測定に加えて連続失敗回数、切替後の待機時間、最大切替回数を組み合わせてください。例えば連続2~3回失敗した場合だけ障害扱いにし、切替後は数分間再評価を抑制すると、揺り戻しを減らせます。
APIエラーとノード障害は区別して記録します。接続拒否、401/403、404、タイムアウトは原因がそれぞれ異なります。認証エラーやAPIポートの誤りをノード障害とみなして別のプロキシへ切り替えても、管理操作自体が直っていないため改善しません。ログには時刻、対象グループ、候補名、遅延、HTTPエラーを残し、認証キーやサブスクリプションURLは出力しないでください。
- 401または403:secretが現在のコア設定と一致するか、Bearerヘッダーが付いているかを確認します。
- 404:エンドポイント、コアの互換性、グループ名やプロキシ名のエンコードを確認します。
- 接続拒否:コアが動作中か、コントローラーポートが正しいか、ローカルファイアウォールが遮断していないかを確認します。
- 遅延測定の失敗:テストURL、タイムアウト値、ノードの接続状態を確認し、複数回測定して一時的な失敗か判断します。
- 選択先が変わらない:対象が
selectグループか、候補がそのグループに含まれているか、改善率の条件を満たすかを確認します。
定期実行環境には、手動実行と同じ環境変数を安全に渡す必要があります。Windowsタスクスケジューラ、macOSのlaunchd、Linuxのsystemd timerやcronを使う場合、実行ユーザー、Python実行ファイルの絶対パス、作業ディレクトリ、ログ出力先を明示します。スクリプトを管理者権限で常時動かす必要は通常ありません。APIがループバックで利用できるなら、一般ユーザー権限とアクセス制限された設定ファイルで運用する方が安全です。
最後に、GUIクライアントの設定更新やコア再起動でコントローラーのポート、secret、グループ名が変わっていないかを定期的に確認します。サブスクリプション更新でグループ構成が置き換わる環境では、スクリプトが参照するグループとノード名も変わる可能性があります。自動切替は障害復旧を補助する仕組みであり、誤設定や認証情報の漏えいを防ぐ仕組みではありません。まずローカル限定のAPI設定、段階的なテスト、切替履歴の確認を整えてから常時運用してください。