Clash APIでプロキシを自動切替する設定と運用の実践ガイド
2026年現在、DeepSeek は世界中で最も注目される AI モデルの一つとなりました。しかし、その急速な普及に伴い、ユーザーは頻繁に「接続タイムアウト」や「サーバー応答なし」といった問題に直面しています。特にプロキシツール Clash を使用している環境では、誤ったルーティング設定や DNS の不一致が原因でアクセスが遮断されることが少なくありません。本記事では、DeepSeek のアクセス障害を根本から解決するための Clash 設定術を徹底解説します。
external-controller とは何か
Clash の external-controller は、起動中の Clash コアを HTTP API から操作するための管理インターフェースです。通常の GUI クライアントでは、プロキシの選択、現在の接続、ログ、設定内容などを画面から確認しますが、external-controller を有効にすると、同じ情報をプログラムから取得できます。これにより、一定間隔でノードの応答を確認し、遅延が大きいノードや通信できないノードを避けて、別のプロキシへ自動的に切り替える運用が可能になります。
この API は通信そのものを中継する機能ではありません。実際のトラフィックは mixed-port、redir-port、TUN などの入口を通り、external-controller はあくまで「どのポリシーグループにどのノードを選ばせるか」を管理します。そのため、API を開けただけでは自動切替は始まりません。まずクライアントが正常に動作し、プロファイルにプロキシグループが存在し、通常の通信が成功していることを確認してください。
Clash Verge Rev や Mihomo 系クライアントでは、設定画面から外部コントローラーのアドレスや Secret を指定できる場合があります。一方、アプリによって項目名や対応 API が少し異なるため、設定を投入する前に、使用中のコアが Clash Meta または Mihomo のどちらなのか、API のポート番号が他のサービスと重複していないかを確認することが重要です。
安全に API を公開するための基本設定
external-controller は強力な管理機能を持っています。接続一覧の閲覧だけではなく、プロキシの切替、設定の再読み込み、プロファイルの操作まで実行できる構成があるため、認証なしで LAN やインターネットへ公開するのは危険です。自動化を始める前に、管理対象をローカルホストだけに限定するか、少なくとも長く推測しにくい Secret を設定してください。
external-controller: 127.0.0.1:9090
secret: "change-this-to-a-long-random-token"
同じ LAN にある別の監視サーバーから API を呼び出したい場合は、127.0.0.1 ではなく LAN 側のアドレスにバインドする方法もあります。ただし、0.0.0.0:9090 のように全インターフェースで待ち受ける設定は、ファイアウォールで送信元を制限できる場合に限って使うべきです。ルーターでポート転送を設定したり、管理ポートを直接インターネットへ公開したりする構成は避けてください。
注意
Secret を設定ファイル、シェル履歴、公開リポジトリ、共有スクリーンショットにそのまま残さないでください。API の URL にトークンを含めるのではなく、HTTP ヘッダーの Authorization: Bearer で送る運用が安全です。万一漏えいした場合は、Secret を変更してクライアントとスクリプトを再起動してください。
API ポートはプロキシの mixed-port と分ける必要があります。たとえば mixed-port が 7890、external-controller が 9090 なら、ブラウザなどの通信は 7890、管理用の HTTP リクエストは 9090 に送ります。ポートを間違えると、API が応答しないだけでなく、プロキシポートに管理リクエストを送ることになり、原因の切り分けが難しくなります。
API でノードとプロキシグループを確認する
自動切替の最初の段階は、いきなりノードを変更することではなく、API が返す状態を読み取ることです。代表的なエンドポイントは次のように整理できます。コアやバージョンによって利用できる項目が異なるため、レスポンスの形式は実環境で確認してください。
| 目的 | 代表的な API | 確認する内容 |
|---|---|---|
| コアの稼働確認 | GET /version |
バージョン、ビルド情報、API の応答 |
| プロキシ一覧 | GET /proxies |
ノード名、グループ名、現在の選択状態 |
| 遅延測定 | GET /proxies/{name}/delay |
指定 URL に対する接続遅延 |
| 現在の接続 | GET /connections |
通信先、使用中のルール、出口プロキシ |
プロキシ名に日本語、空白、スラッシュなどが含まれる場合、URL パスへそのまま連結してはいけません。必ず URL エンコードを行います。また、API の JSON に表示される名前と GUI 上の表示名が異なるケースもあるため、固定した文字列を決め打ちするより、まずグループのプロキシ一覧を取得し、対象となるノードを条件で選ぶ方が保守しやすい設計です。
curl -s \
-H "Authorization: Bearer $CLASH_SECRET" \
http://127.0.0.1:9090/proxies | jq '.proxies["自動選択"]'
上の例では、環境変数に Secret を保存し、レスポンスから「自動選択」というグループを取り出しています。監視対象を一つのノードだけに限定すると、そのノードが停止したときに判断材料がなくなります。複数の候補を登録し、遅延だけでなく HTTP ステータス、タイムアウト回数、直近の切替履歴も合わせて評価すると、短時間の揺らぎによる頻繁な切替を抑えられます。
自動切替スクリプトを実装する
ノード自動切替は、一般に「候補を取得する」「各候補を測定する」「条件を満たすノードを選ぶ」「グループへ選択結果を書き込む」「変更後に再確認する」という流れで作ります。単純に最小遅延だけを選ぶと、測定先には速いものの、実際に利用したいサービスへ接続できないノードを選ぶ可能性があります。したがって、測定 URL、許容遅延、失敗回数、切替間隔を明確に決めておく必要があります。
- API の
/proxiesから対象グループの候補を取得する。 - 各候補へ同じテスト URL を送り、遅延と HTTP ステータスを記録する。
- タイムアウト、TLS エラー、連続失敗のノードを候補から除外する。
- 現在のノードとの差が小さい場合は切り替えず、不要な再接続を避ける。
- 選択 API へ POST し、数秒後に現在のノード名を再取得する。
選択 API の形式はコアによって差がありますが、一般的には対象グループへノード名を JSON で送信します。グループ名やノード名に特殊文字がある場合は、JSON を文字列連結で作らず、使用する言語の JSON エンコーダーを利用してください。
curl -sS -X PUT \
-H "Authorization: Bearer $CLASH_SECRET" \
-H "Content-Type: application/json" \
-d '{"name":"Node-A"}' \
http://127.0.0.1:9090/proxies/自動選択
実運用では、次のようなヒステリシスを入れると安定します。現在のノードが 300 ミリ秒以内で応答している間は維持し、3 回連続で失敗した場合だけ切替候補を探します。新しいノードを選ぶ条件も「現在より 20 パーセント以上速い」または「現在のノードが利用不能」とします。これにより、測定値が 210 ミリ秒と 220 ミリ秒の間で揺れるたびに切り替わる問題を防げます。
スクリプトはユーザー権限で実行し、Secret は環境変数または権限を制限したファイルから読み込ませてください。cron や systemd timer で定期実行する場合は、実行時間、終了コード、選択したノード、測定結果をログに残します。同じスクリプトが重複起動すると API へ同時に切替命令を送りかねないため、ロックファイルや systemd の実行制御も有効です。
ログ確認と障害対応の考え方
自動切替がうまく動かないときは、まず「API に到達できない」「API は応答するが候補が空」「測定は成功するが切替できない」「切替後も実通信が失敗する」の四つに分けて確認します。ブラウザからサイトが開けるかだけを見ると、DNS、ルール、システムプロキシ、API のどこで問題が起きたのか分かりません。
- API に到達できない:ポート番号、bind アドレス、ファイアウォール、クライアントのコアが起動しているかを確認します。
- 401 や 403 が返る:Secret、Bearer ヘッダー、API パスの書式を確認します。Secret を URL パラメータへ付ける実装は避けてください。
- 候補が空になる:対象グループが実際に存在するか、グループ名の大文字小文字、プロファイルの読み込み状態を確認します。
- 遅延測定だけ失敗する:測定 URL が環境から到達可能か、URL のプロトコル、DNS、TLS 検証を確認します。
- 切替後も通信できない:ルールが別のグループを参照していないか、システムプロキシや TUN の入口が有効かを調べます。
ヒント
最初は自動切替を無効にし、スクリプトに「推奨ノード」と「理由」だけを出力させてください。人間が結果を確認して手動切替できる状態を作ってから、自動 POST を有効にすると、誤判定による通信断を発見しやすくなります。
Clash の接続ログでは、アクセス先、使用ルール、実際に選ばれた策略グループを確認できます。ノードが切り替わっているのに特定サイトだけ失敗する場合、API ではなくルールの優先順位や DNS の問題である可能性があります。逆に、すべての通信が止まる場合は、切替先のプロトコル、証明書、サーバーの有効期限、プロバイダ側の同時接続制限を確認してください。
運用開始後は、切替回数を指標として記録することも大切です。短時間に何度も切り替わるなら、テスト URL が不安定、タイムアウトが短すぎる、候補の品質に差がありすぎる、といった設計上の原因が考えられます。毎回の切替前に現在の設定を保存し、異常時には手動で安定したノードへ戻せるようにしておくと、復旧が容易になります。
長期運用で失敗しない設計
ノード自動切替は、速いノードを選ぶだけの仕組みではありません。利用するサービス、時間帯、通信量、プロバイダの制限を考慮し、速度と安定性のバランスを取る必要があります。動画や大容量ファイルでは短い遅延より継続的な帯域が重要な一方、API や Web 閲覧では接続確立の速さと DNS の安定性が大きく影響します。
| 設定項目 | 推奨する考え方 | 避けたい状態 |
|---|---|---|
| 測定間隔 | 数分単位から始め、通信環境に合わせて調整する | 数秒ごとの測定で API とノードへ過剰な負荷をかける |
| 失敗判定 | 連続失敗とタイムアウトを組み合わせる | 一回の瞬断だけで即座に切り替える |
| 候補数 | 用途ごとに信頼できる複数ノードを用意する | 無制限に全ノードを毎回測定する |
| 権限管理 | localhost または LAN 内に限定し、Secret を保護する | 管理 API を WAN へ直接公開する |
プロファイルを更新した直後は、グループ名やノード名が変わることがあります。スクリプトが古い名前を固定していると、更新後に自動切替が停止します。可能であれば、ノード名の完全一致だけでなく、地域、プロトコル、タグ、連番など、プロバイダが安定して提供する属性を使って候補を再構成してください。ただし、似た名前のノードを誤って選ばないよう、許可リストを併用するのが安全です。
また、API の状態と実際の通信結果は別々に監視します。/version が返っても、プロキシサーバーが正常とは限りません。定期的な遅延測定に加えて、実際に利用するドメインへの軽量な HTTPS テストを行い、DNS 失敗、接続拒否、HTTP エラーを分けて保存してください。ログには Secret や購読 URL のトークンを出力せず、必要な情報だけをマスクして残します。
GUI だけで自動切替を完結させようとすると、条件分岐、履歴、通知、例外処理の設定が不足しやすく、別のツールでは API の認証やノード名の扱いが複雑になることがあります。Clash は external-controller と豊富なプロキシグループを組み合わせ、状態取得から選択変更までを一貫して自動化できます。API の公開範囲と Secret を慎重に管理し、まず手動確認、次に通知、最後に自動切替という順で段階的に導入したい方は、対応クライアントをダウンロードして実際の環境で試してみてください。