· Clash や Mihomo を長時間使っていると、「いつも同じノードが速い」と感じていても、時間帯、回線混雑、サービス側の負荷によって最適な出口は変わります。特に AI サービス、Git 操作、パッケージレジストリのように接続先が複数に分かれたり、短時間に多くの HTTPS 通信を発生させたりする用途では、手動でノードを選び直す運用に限界があります。

そこで役立つのが、Clash または Mihomo の external-controller API です。API からプロキシグループの現在値を取得し、各ノードの遅延を測定し、条件に合うノードへグループを切り替えられます。本記事では、external-controller の安全な公開方法、REST API の基本、url-test や fallback との使い分け、さらに Bash と Python による自動切替スクリプトまで、実際の運用を意識して説明します。

⚠️
アクセスキーを必ず設定:external-controller は Clash の操作権限を持つ管理 API です。0.0.0.0:9090 のように LAN 全体へ公開する場合は、必ず secret を設定し、ルーターのポート開放やインターネットからの直接公開は避けてください。API は便利ですが、漏洩するとプロキシ選択や設定情報を第三者に操作される可能性があります。

Clash APIで自動切替する仕組み

Clash の自動ノード選択には、大きく分けて二つの方法があります。ひとつは設定ファイル側で url-test、fallback、load-balance を定義し、Mihomo に定期的な判定を任せる方法です。もうひとつは、外部スクリプトから API を呼び出し、用途や時間帯に応じて明示的にプロキシグループを変更する方法です。

url-test は、指定した URL への応答時間を定期的に計測して、最も速い候補を選びます。普段の Web 閲覧には十分便利ですが、AI API だけは米国系、Git 操作はシンガポール系、といった用途別の判断や、「遅延が低くても失敗率が高いノードは除外する」といった複雑な条件には向きません。その場合に API スクリプトを組み合わせると、単純な RTT だけではなく、失敗回数、直近の切替時刻、利用するサービスまで考慮できます。

API の代表的なエンドポイントは次のとおりです。バージョンやコアによって細部が異なる場合があるため、実際には使用中の Mihomo の API 仕様とレスポンスを確認してください。

  • GET /version:Clash または Mihomo のバージョンを確認します。
  • GET /proxies:プロキシ、プロキシグループ、現在選択されている値を取得します。
  • GET /proxies/{name}/delay:指定ノードまたはグループの遅延を測定します。
  • PUT /proxies/{name}:セレクト型グループの選択ノードを変更します。
  • GET /connections:現在の接続情報を取得し、どのルールやグループが使われているか確認します。

グループ名やノード名に日本語、空白、スラッシュ、括弧が含まれている場合、URL に埋め込むときは必ず URL エンコードしてください。スクリプトで文字列を直接連結すると、特定のノードだけ API エラーになることがあります。

external-controllerとプロキシグループの基本設計

まず、API を待ち受けるアドレスと認証キーを設定します。ローカルマシンだけから操作するなら 127.0.0.1 が最も安全です。同じ LAN 上のスマートフォンや別 PC から操作する必要がある場合だけ、LAN アドレスへの公開を検討してください。

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

proxy-groups:
  - name: AI-AUTO
    type: select
    proxies:
      - AI-HK
      - AI-SG
      - AI-US
      - DIRECT

  - name: AI-HK
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    proxies:
      - HK-01
      - HK-02

  - name: AI-SG
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    proxies:
      - SG-01
      - SG-02

rules:
  - DOMAIN-SUFFIX,openai.com,AI-AUTO
  - DOMAIN-SUFFIX,github.com,AI-AUTO
  - MATCH,PROXY

ここで重要なのは、スクリプトが直接個別ノードを選ぶのではなく、まず用途別のグループを操作する設計にすることです。購読更新でノード名が変わっても、AI-AUTO のような安定したグループ名を残しておけば、スクリプトの修正範囲を小さくできます。また、AI サービスと GitHub を同じグループへ入れると、片方に最適なノードがもう片方に適しているとは限りません。長時間の API 通信と Git の HTTPS 通信を分けたい場合は、AI-AUTO と GIT-AUTO を別々に用意してください。

ℹ️
測定 URL の考え方:遅延測定用 URL は、ノードから安定して到達でき、レスポンスが小さい HTTPS エンドポイントを選びます。ただし、測定 URL の RTT が低いことは、実際の AI API や Git サーバーへの応答速度を保証しません。最終確認では対象サービスへの実通信も試してください。

ステップ形式でAPI切替を実装する

ステップ1:APIへの接続を確認する

設定を反映して Clash または Mihomo を再起動したら、まず /version と /proxies を読み取ります。以下の例では、secret を HTTP ヘッダーに渡しています。シェルの履歴にキーが残る環境では、コマンドラインへ直接書かず、環境変数を利用してください。

export CLASH_API="http://127.0.0.1:9090"
export CLASH_SECRET="change-this-to-a-long-random-token"

curl -fsS \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  "${CLASH_API}/version"

curl -fsS \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  "${CLASH_API}/proxies"

レスポンスにプロキシ一覧が返らない場合は、API ポートの間違い、認証キーの不一致、設定ファイルの読み込み失敗を順番に確認します。GUI の設定画面で外部コントローラーを変更した場合、編集した YAML と実際に読み込まれたプロファイルが異なることもあります。

ステップ2:候補ノードの遅延を測定する

次に、候補ノードを一つずつ測定します。ノード名は URL エンコードが必要なので、Python や専用ライブラリを使う方法が安全です。単純な例では次のように呼び出せます。

curl -G -fsS \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  --data-urlencode "timeout=5000" \
  --data-urlencode "url=https://www.gstatic.com/generate_204" \
  "${CLASH_API}/proxies/HK-01/delay"

返される遅延値が極端に小さくても、DNS キャッシュや測定先の CDN によって結果が偏る場合があります。1 回の最小値で判断せず、3〜5 回の中央値を使うと一時的な揺らぎを抑えられます。また、タイムアウトを単に「最悪のノード」とみなすのではなく、数回連続した失敗を別の指標として記録すると、混雑ノードと一時的な経路障害を区別しやすくなります。

ステップ3:選択グループを変更する

測定結果から候補を選んだら、セレクト型グループへ PUT リクエストを送ります。グループ名とプロキシ名は実際の設定に合わせて置き換えてください。

curl -fsS -X PUT \
  -H "Authorization: Bearer ${CLASH_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"name":"HK-01"}' \
  "${CLASH_API}/proxies/AI-AUTO"

切替直後に既存の TCP セッションがすべて新ノードへ移るわけではありません。すでに確立した WebSocket、SSH、Git の通信は元の出口を維持したまま、次に作られる接続から新しいグループ選択が使われることがあります。そのため、長時間接続中の AI セッションを途中で切り替えると、かえって切断を招く場合があります。切替はリクエストが少ないタイミング、またはアプリケーション側の再接続処理と組み合わせて実行してください。

ステップ4:Pythonで中央値と失敗回数を使う

実運用では、最初に応答したノードではなく、複数回測定した中央値と成功率で判断します。次のスクリプトは候補を測定し、中央値が最も低く、一定回数以上成功したノードを AI-AUTO に設定する最小構成です。実行前に候補名と API キーを環境変数へ登録してください。

import os
import statistics
import time
from urllib.parse import quote

import requests

BASE = os.environ.get("CLASH_API", "http://127.0.0.1:9090")
SECRET = os.environ["CLASH_SECRET"]
GROUP = "AI-AUTO"
NODES = ["HK-01", "HK-02", "SG-01", "SG-02"]
TEST_URL = "https://www.gstatic.com/generate_204"

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

for node in NODES:
    samples = []
    for _ in range(3):
        try:
            response = requests.get(
                f"{BASE}/proxies/{quote(node, safe='')}/delay",
                params={"timeout": 5000, "url": TEST_URL},
                headers=headers,
                timeout=8,
            )
            response.raise_for_status()
            samples.append(int(response.json()["delay"]))
        except (requests.RequestException, ValueError, KeyError):
            pass
        time.sleep(0.4)

    if len(samples) >= 2:
        results.append((statistics.median(samples), node, samples))

if not results:
    raise SystemExit("No usable proxy was found")

results.sort()
best_delay, best_node, samples = results[0]

requests.put(
    f"{BASE}/proxies/{quote(GROUP, safe='')}",
    headers={**headers, "Content-Type": "application/json"},
    json={"name": best_node},
    timeout=8,
).raise_for_status()

print(f"selected={best_node} median={best_delay}ms samples={samples}")

この例は分かりやすさを優先しており、最低遅延だけを選びます。実際には「中央値が 180ms を超えたら切替」「現在のノードより 30ms 以上改善した場合だけ切替」のようなヒステリシスを入れてください。改善幅の条件がないと、数ミリ秒の差で頻繁に切り替わり、WebSocket や Git の接続を不安定にするからです。cron やタスクスケジューラーで定期実行する場合も、前回選択したノードと実行時刻を JSON や小さな状態ファイルに保存すると、不要な API 操作を減らせます。

AIサービスとGit操作で失敗しにくい運用

AI サービスでは、低遅延だけでなく長時間の HTTPS や WebSocket が安定して維持できるかを重視します。短い測定 URL では高速でも、長時間接続で切断されるノードがあります。Clash の接続ログで、対象ドメインが意図したグループを通過しているか、DIRECT とプロキシが混在していないかを確認してください。認証、モデル API、アップデート CDN が別ドメインの場合は、ルールが一部だけ不足している可能性があります。

Git 操作では、github.com、api.github.com、Git の SSH ホスト、パッケージ取得先が別々の通信になります。HTTPS の clone は通るのに、SSH push だけ失敗するケースでは、API のノード選択以前に SSH が Clash のプロキシ経路へ入っていないことがあります。ターミナル、GUI クライアント、CI ツールでプロキシ設定が異なるため、接続ログを見ながら一つずつ確認してください。

自動切替を常時有効にするのではなく、用途別にプロファイルを分けるのも有効です。たとえば、普段の Web 閲覧は Mihomo の url-test に任せ、AI 開発中だけ Python スクリプトを実行し、Git の大量 push 前には低遅延より安定性を優先する、といった運用です。自動化は「常に最速にする」ためではなく、「人が毎回画面を開いて選び直す作業を減らし、判断基準を再現可能にする」ための仕組みと考えると、過剰な切替を防げます。

⚠️
APIを外部へ公開しない:ファイアウォールで管理ポートを閉じ、必要なら SSH トンネルや VPN 内からのみ利用してください。secret を設定していても、API の存在を無制限に公開する設計は避けるべきです。ログやシェル履歴、CI の環境変数に認証キーが残っていないかも定期的に確認しましょう。

切替できないときのトラブルシューティング

401や404が返る

401 Unauthorized は secret の渡し方、ヘッダー名、ポート番号を確認します。404 はエンドポイントのパスやコアの実装差が原因です。特にグループ名を URL に直接含めたとき、空白や日本語が壊れていないかを見てください。まず /proxies で正確なグループ名を取得し、その値を URL エンコードして使用するのが安全です。

APIは成功するが通信が変わらない

PUT が成功しても、対象ルールがそのグループを使っていなければ通信経路は変わりません。接続ログで該当ドメインの策略名を確認し、ルールの上から先に一致する行を調べます。広い DOMAIN-SUFFIX、GEOIP、MATCH が先に置かれていると、後ろに追加した AI や Git 用ルールへ到達しません。また、既存接続は切替後も残るため、テスト時は新しいリクエストを発生させてください。

ノードが頻繁に切り替わる

測定間隔が短すぎる、候補間の差が小さい、測定先 CDN の応答が揺れている、といった原因が考えられます。中央値を利用し、切替の最小改善幅を設け、一定時間は同じノードを維持してください。さらに、連続失敗が発生した場合だけ即時切替する通常モードと、定期的に全候補を再評価するメンテナンスモードを分けると、日常通信への影響を抑えられます。

よくある質問

url-testだけでは不十分ですか?

一般的な閲覧なら十分なことが多いです。ただし、AI API や Git のように接続時間、宛先、認証方式が異なる通信を一つのグループで扱う場合、測定 URL の遅延だけでは実際の品質を判断できません。API スクリプトを追加すると、用途別のグループ、失敗率、切替条件を細かく設計できます。

LAN内の別端末からAPIを使えますか?

可能ですが、external-controller を LAN アドレスで待ち受け、secret を設定し、ファイアウォールで接続元を限定してください。ルーターのポート転送で外部公開する方法は推奨しません。必要なときだけ SSH トンネルや VPN を利用する方が安全です。

自動切替でWebSocketが切断されませんか?

確立済みの WebSocket は出口変更の影響を受ける可能性があります。AI のリアルタイム通信や開発用の長時間セッション中は自動切替を停止し、新しいセッションを開始する前にノードを選ぶ運用が安全です。どうしても切替が必要なら、接続の再確立を前提にしたアプリケーション側の処理を用意してください。

購読更新でスクリプトは壊れませんか?

個別ノード名をスクリプトへ固定すると壊れる可能性があります。用途別グループ名を固定し、起動時に /proxies から候補を取得して、名前の接頭辞や地域タグで絞り込む設計にすると影響を減らせます。購読更新後は必ずグループ名、ノード名、ルールの三つを確認してください。

同類の代理工具では、遅延測定、グループ切替、ログ確認をそれぞれ別画面で行う必要があり、API と YAML を組み合わせた運用では設定の所在が分かりにくくなることがあります。ClashSky は Mihomo 系の設定を GUI で確認しながら、external-controller、プロキシグループ、接続ログを一つの運用フローで整理しやすく、手作業の切替から段階的に自動化へ移行したい場合にも扱いやすい選択肢です。AI サービスや Git 操作の経路を安定させたい方は、まず小さな候補グループから試してみるとよいでしょう。

ClashSkyを無料でダウンロードして、API と自動ノード切替の運用を始めましょう。