まずはリクエストエラーか設定の解析エラーかを切り分ける
Clashのサブスクリプション更新は通常、クライアントが配布 URL にリクエストを送り、応答を読み込んでから、設定処理とコアによる検証を行います。どの段階で失敗しても、画面には「更新失敗」と表示されることがあります。まずは再インストールではなく、クライアントのサブスクリプション詳細とログを開き、エラー全文、発生時刻、使用中のコアを記録しましょう。
同じサブスクリプション URL でも、ブラウザー、クライアント、コマンドラインで異なる内容が返ることがあります。ブラウザーで開けても、そのリクエストに応答があったことしか分からず、Clashで使える設定が返されたとは限りません。すでに取り込んだノードで接続できても、それは以前の設定が使えるというだけで、サブスクリプションの配布 API が正常とは限りません。
| ログまたは応答 | 考えられる原因 | 優先して確認する項目 |
|---|---|---|
timeout、connection refused | リクエストが正常に完了していない | ネットワーク経路、プロキシポート、サービスの状態 |
401、403 | 認証またはアクセス制御による拒否 | サブスクリプショントークン、アカウント状態、リクエストヘッダー |
404、410 | URLが存在しない、またはリソースが無効化されている | 現在のサブスクリプション URL とリンクの再発行状況 |
429 | リクエスト頻度の制限 | 自動更新の間隔と再試行回数 |
yaml: line … | 応答本文を想定どおり解析できない | 応答形式、インデント、特殊文字 |
unsupported proxy type | コアが一部のノード形式に対応していない | コアのバージョンとサブスクリプションの出力先 |
リンク切れ、アカウントの問題、HTTPステータスコード
現在のサブスクリプション URL をコピーし直す
サブスクリプション提供元のアカウントページで、プランの状態、有効期限、残りの通信量を確認し、現在の画面からClashまたはmihomo向けの URL をコピーします。プランの期限切れ、トークンの再発行、APIの移行、通信量の上限到達などで応答に影響が出ることがあります。具体的な挙動は提供元によって異なるため、ステータスコードだけでアカウントの期限切れと判断しないでください。
- コピーした URL の先頭と末尾を確認し、改行、空白、引用符、チャットアプリが付け加えた句読点が混入していないか確認します。
- クエリパラメーターはすべて残してください。「URLを短くする」ために疑問符以降を削除してはいけません。
- Webページのソースから URL をコピーした場合、
&はHTML上の表記です。実際の URL では、パラメーターの区切り文字は&です。 - サブスクリプショントークンを再発行した直後は、古い URL がすぐに無効になることがあります。既存のサブスクリプション項目を編集し、同じ名前の設定を複数作らないようにしてください。
更新ボタンを連打せず、ステータスコードに応じて対処する
401 は認証情報がない、または無効な場合によく発生します。403 はアクセス制限、リスク判定、リクエストヘッダーの設定が原因のこともあります。404 はAPIのパスが変更された可能性もあります。429 が返った場合は、サーバーの Retry-After に従って待ちます。指定がなければ自動更新をいったん停止し、提供元に問い合わせてください。再試行を続けてもリクエスト数が増えるだけで、トークンの問題は解決しません。
500、502、503 の場合は、サーバーやゲートウェイの状態を確認しましょう。エラーの発生時刻を記録し、しばらく時間をおいてから再試行してください。304 はキャッシュ制御による正常な応答の場合もあり、必ずしも失敗を意味しません。古い内容がクライアントに正しく保持されているかも確認します。
タイムアウトした場合：サブスクリプション取得時のネットワーク経路を確認する
システムプロキシ、TUN、サブスクリプションのダウンロードは関連していますが、同じ仕組みではありません。クライアント自身が設定をダウンロードするものもあれば、「プロキシ経由で更新」のような項目を備えるものもあります。コアのプロキシプロバイダーにも、独立した更新設定が使われる場合があります。画面に更新失敗と表示されても、ブラウザーと同じネットワーク経路を使っているとは限りません。
- 同じネットワークで失敗時のログを記録し、DNS名前解決、TCP接続、TLS接続、応答の読み込みのどこで失敗したかを切り分けます。
- クライアントが実際に待ち受けているローカルプロキシポートを確認し、古い記事の情報をそのまま使わないでください。以下のコマンドでは
127.0.0.1:7890を使用します。このポートがHTTPまたは混合プロキシの接続先である場合に限り利用できます。 - 使える古い設定を残し、プロキシを使わない場合と、古い設定を経由する場合をそれぞれ試します。一度に変更する条件は1つにしてください。
- ネットワークを切り替えて直った場合は、ノードのパスワードを変更するのではなく、元のネットワークのDNS、ゲートウェイの制限、セキュリティソフトを確認します。
curl で応答を比較する
以下のコマンドはLinuxまたはmacOSのBash向けです。URLは非表示入力で読み込むため、シェルの履歴への直接記録を避けられます。ただし、入力時も使用端末の安全性には注意してください。接続待ち時間は10秒、リクエスト全体の制限時間は30秒に設定し、レスポンスヘッダーと本文を別々のローカルファイルに保存します。Windowsでは curl.exe を使用できますが、変数の入力方法は利用するターミナルに合わせて調整してください。
read -r -s -p 'サブスクリプション URL：' SUB_URL
printf '\n'
curl --noproxy '*' --connect-timeout 10 --max-time 30 \
-D subscription.headers -o subscription.body "$SUB_URL"
curl --noproxy '' --proxy http://127.0.0.1:7890 \
--connect-timeout 10 --max-time 30 \
-D subscription-proxy.headers -o subscription-proxy.body "$SUB_URL"
unset SUB_URLここでいう「プロキシなし」は、curlで明示的なプロキシを使わないという意味です。システムでTUNが有効な場合、接続はTUN経由になることがあります。比較する際は、ほかの作業に影響しないことを確認したうえで、一時的にTUNを無効にして再テストしてください。301 または 302 が返った場合は、まず Location の転送先ドメインを確認します。信頼できると判断した場合のみ、-L でリダイレクトを追跡してください。
User-Agent：同じ URL から異なる形式が返る理由
User-Agent は、リクエストを送信したプログラムを示すHTTPヘッダーです。サブスクリプションサービスによっては、この値に応じて出力形式を切り替えます。たとえば、ブラウザーには説明ページ、特定のクライアントにはYAMLを返したり、認識できないリクエストを拒否したりします。一方、この項目を参照せず、専用 URL やクエリパラメーターで形式を切り替えるサービスもあります。
リクエストヘッダーを変更する前に、提供元の要件を確認する
- サブスクリプション提供元の形式に関する説明を確認し、その URL がClash、Clash Meta（mihomo）、その他のクライアントのどれを対象としているか確認します。
- クライアント名、クライアントのバージョン、コアのバージョンを記録します。クライアントとコアのバージョンは別々の情報です。画面上でクライアントを更新しても、コアまで更新されるとは限りません。
- クライアントのログとコマンドラインの応答を比較します。ブラウザーに表示されたログインページをサブスクリプションの本文と誤認しないでください。
- 提供元から特定の User-Agent が指定されている場合に限り、クライアントのサブスクリプションリクエスト設定に入力します。メニュー名はクライアントによって異なります。
たとえば、提供元が clash.meta の使用を明示している場合は、前述のcurlコマンドに -A 'clash.meta' を加えて比較できます。この文字列を受け付けるサービスもありますが、すべてのmihomoクライアントで使われる固定ヘッダーではなく、万能な解決策でもありません。User-Agentを偽装しても、実際のアカウント期限切れや権限の制限は回避できません。
User-Agent を設定のトップレベルに安易に追加しても、クライアントのサブスクリプションリクエストに反映されるとは限りません。クライアントによる設定全体のダウンロードと、コアによる proxy-providers の更新は別の処理です。それぞれのコンポーネントが対応する設定だけが有効になります。ヘッダーを変更してYAMLが返るようになってもクライアントで失敗する場合は、形式とコアの互換性を確認してください。
HTTP 200 でも解析に失敗する場合：応答本文を確認する
200 OK はHTTPリクエストの成功を示すだけで、Clashで使える内容が返ったことを意味しません。応答本文には、ログインページ、認証用画面、JSON形式のエラー、Base64でエンコードされたノード一覧、別のコア向けの設定などが含まれる場合があります。まずレスポンスヘッダーの Content-Type を確認し、次に本文の冒頭をローカルで確認してください。ヘッダーが正しくない場合もあるため、最終的には本文の内容で判断します。
| 本文の特徴 | 対処方法 |
|---|---|
<!DOCTYPE html> または <html で始まる | ログインページ、ブロック画面、選択したURLを確認する |
| JSONにエラーコードまたはエラーメッセージが含まれる | まずAPIエラーを解決する。YAML設定として読み込まない |
複数行の ss://、vmess:// などのURI | クライアントが変換に対応しているか確認するか、Clash向けの出力を選び直す |
proxies:、proxy-groups: などの構造を含む | YAMLの構文とフィールドの互換性を確認する |
proxies: とノード一覧のみ | ノードプロバイダーファイルの可能性があるため、インポート先を確認する |
完全な設定ファイルとノードプロバイダーは使い分ける
完全な設定ファイルには通常、プロキシグループ、ルール、実行パラメーターも定義されています。一方、proxy-providers のリモートファイルは、主にノード一覧を提供します。ノード一覧だけを受け付けるプロバイダーの URL に完全な設定を指定したり、ノード一覧を完全な設定として使ったりすると、解析に失敗したりポリシーが不足したりすることがあります。rule-providers はルールセットの取得先であり、ノードのサブスクリプション先ではありません。
Clash Metaは後にmihomoへ名称変更されました。mihomoとオリジナルのClashでは、対応するプロトコルや設定機能が完全には一致しません。たとえば、Hysteria2やVLESSのノードには、それぞれに対応したコアが必要です。ログに未対応のタイプやフィールドが出た場合は、まず実際に動作しているコアを確認し、提供元の指定に合わせて出力形式を選んでください。type の名前を変更しても、プロトコルを別の種類に変換することはできません。
YAMLのインデントと設定の参照エラー
yaml: line 12、did not find expected key、cannot unmarshal などのエラーが出たら、指定された行とその前後を確認してください。パーサーが示す行は問題を検出した場所であり、原因は直前の行にあることもあります。たとえば、引用符の不足、リストのインデントのずれ、リストにするべきフィールドを文字列として記述した場合などです。
空白、リスト、特殊文字を確認する
- インデントにはスペースを使い、Tabは使わないでください。同じ階層のキーは位置をそろえます。2スペースのインデントはよく使われる形式ですが、唯一の正解ではありません。
rulesはリストとして記述し、各ルールの先頭に-を付けます。YAMLでは全角コロンではなく、半角コロンを使ってください。- コロンの後に空白が続く名前や、シャープ記号などの特殊文字を含む名前は、引用符で囲むことをおすすめします。参照元と参照先の名前も完全に一致させてください。
- 重複したキーや、意図せず結合されたセクションがないか確認します。手作業でノードを貼り付けた後、上書きルールを追加した後、複数のサブスクリプションを統合した後は特に注意してください。
以下はリストとインデントを確認するための、直接接続用の設定例です。リモートサブスクリプションは含まず、ノードを復元する代わりにもなりません。定義済みのプロキシグループをルールから参照しているため、問題のある設定構造との部分的な比較に使えます。
mixed-port: 7890
allow-lan: false
mode: rule
proxy-groups:
- name: "デフォルトポリシー"
type: select
proxies:
- DIRECT
rules:
- MATCH,デフォルトポリシーYAMLの構文だけでなく、実際に使うコアで検証する
汎用のYAMLパーサーで確認できるのは構文だけです。コアがフィールド、プロトコル、ポリシーの参照を受け付けるかまでは検証できません。実際に使用しているmihomoのバイナリで、まずバージョンを確認し、一時設定をテストします。
mihomo -v
mihomo -t -f ./subscription.yamlここでいう subscription.yaml は、ローカルに保存した設定ファイルです。クライアント内蔵のコアがコマンド検索パスにない場合は、バイナリの実際のパスを指定してください。外部プロバイダーを含む設定をテストする場合は、パスやネットワークの依存関係も考慮する必要があります。proxy not found のようなエラーが出た場合は、プロキシグループが参照するノードの有無と名前、ノードプロバイダーの読み込み状況を確認してください。
更新を再開するための最終チェックリスト
- 現在の状態を保存：使える古い設定を保存し、エラー全文、発生時刻、クライアントのバージョン、コアのバージョンを記録します。
- アカウントを確認：有効期限、通信量、トークンの状態を確認し、アカウントページから正しいサブスクリプション URL をコピーし直します。
- リクエストを検証：HTTPステータス、リダイレクト、応答本文を確認し、プロキシを使わない場合とプロキシ経由の場合を比較します。
- 形式を確認：HTML、JSON、URI一覧、完全なYAML、ノードプロバイダーファイルを見分けます。
- リクエストヘッダーを確認：提供元の説明に従ってUser-Agentを確認し、推測で何度も変更しないようにします。
- 設定を確認：YAMLのインデント、フィールドの型、ノードのプロトコル、プロキシグループの参照を調べます。
- 自動更新を再開：手動更新が一度成功してから適切な更新間隔を設定し、同じサブスクリプションへの重複リトライを避けます。
新しく追加したサブスクリプションは更新できるのに、既存の項目だけ失敗し続ける場合は、保存済み URL、リクエストのオプション、上書きスクリプト、ローカルキャッシュを優先して確認してください。すべての設定をすぐに消去するのではなく、まずバックアップを取り、クライアントのドキュメントに従って問題の項目だけを対処します。複数のデバイスで同じサーバーエラーが発生する場合は、提供元への問い合わせ時に、個人情報を伏せたステータスコード、発生時刻、本文のエラー情報を添えると、「更新できない」と伝えるだけの場合より原因を特定しやすくなります。
更新成功の判断には、サブスクリプションの取得、設定の検証、プロキシグループの読み込みがすべて正常であることを確認してください。ノードの接続性は次の段階で確認します。サブスクリプションを取得できてもノードに接続できない場合は、回線、ノードのパラメーター、ローカルプロキシの設定を確認してください。関連用語は用語集をご覧ください。接続に関する問題は、トラブル対処のページで引き続き診断できます。