Clashのサブスクリプション更新・解析エラー対処ガイド：リンクからYAMLまで

まず、ダウンロード失敗・解析失敗・ノード接続不可を切り分ける

まず現在使える設定を残し、更新ログを確認します。サブスクリプションの更新には、ダウンロードの応答、設定の解析、コアへの読み込みという3つの段階があります。ノードの接続テストはその後です。これらを混同すると、リンクが無効なのにルールを何度も編集したり、YAMLの形式エラーなのにノードを切り替え続けたりすることになります。

ClashXとmihomoコアを使うクライアントでは、メニュー名やエラーメッセージの表現が異なる場合があります。クライアント名、クライアントのバージョン、コア名、コアのバージョンを記録し、ウィンドウタイトルだけで済ませないでください。アプリ本体を更新しても、実際に動作しているコアまで切り替わったとは限りません。

手順1：コピーしたURLが有効なサブスクリプションか確認する

入口、トークン、契約状態を確認する

1. サービス提供元のアカウントページで「サブスクリプション」または「インポート」を開き、Clashまたはmihomo向けと明記された設定形式を選択します。アカウントのログインページ、支払いページ、ノード紹介ページはサブスクリプションURLではありません。
2. URLをもう一度コピーし、先頭が https:// か、末尾に空白・改行・日本語の句読点が混入していないか確認します。クエリ文字列は削除しないでください。アカウントの識別や出力形式を指定するパラメーターが含まれている場合があります。
3. 契約期間が終了していないこと、通信量を使い切っていないこと、サブスクリプショントークンがリセットされていないことを確認します。トークンをリセットした場合は、クライアントに保存した古いURLも新しいものに差し替えてください。
4. QRコードやワンクリック登録用リンクを取得した場合は、クライアントがそのインポート方式に対応しているか確認します。アプリを起動するリンクと、設定ファイルを直接返すHTTPS URLは別のものです。

HTTP 401は認証失敗、403はアカウント権限・アクセス制限・セキュリティ確認、404はURLのパス変更を示す場合があります。ステータスコードで原因を絞り込めますが、403だけで契約切れとは断定できません。レスポンス本文とサービス提供元のアカウント状態もあわせて確認してください。

ブラウザーで開けても、クライアントで更新できるとは限らない

ブラウザーにはログインCookieが保存されていたり、サブスクリプションのダウンロードとは異なるネットワーク経路が使われたりする場合があります。URLを開くとログインフォーム、認証画面、「JavaScriptを有効にしてください」などが表示される場合、クライアントは設定として解析できません。ページのソースをコピーするのではなく、クライアントから直接読み込めるサブスクリプションURLを探してください。

手順2：サブスクリプションのダウンロード経路を確認する

まず、エラーがDNS名前解決、TCP接続、TLSハンドシェイクのどこで発生しているか確認します。no such host は名前解決、connection refused は接続拒否、certificate has expired やホスト名の不一致は証明書の問題を示します。context deadline exceeded の場合は、前後のログからタイムアウト箇所を特定してください。

• ドメインの名前解決に失敗：まずシステムからサブスクリプションのドメインを名前解決できるか確認し、次にクライアント独自のDNS設定を確認します。ブラウザーでセキュアDNSを有効にしていても、システムの名前解決が正常とは限りません。
• 直接接続がタイムアウト：現在使えるノードがある場合、クライアントが対応していれば、そのノード経由でサブスクリプションを更新します。更新経路を失わないよう、古い設定は先に削除せず残してください。
• プロキシ経由の更新がタイムアウト：現在のプロキシノードが使えるか確認します。無効になったノードに依存して更新する必要があると、「接続するには更新が必要、更新するには接続が必要」というループに陥ります。
• TLSエラー：システムの日付・時刻・タイムゾーンを確認し、サブスクリプションのドメインの証明書が有効か調べます。証明書検証のスキップを恒久的な解決策にしないでください。

システムプロキシ、TUNモード、サブスクリプションのダウンロードが同じ経路を通るとは限りません。アプリ層がサブスクリプションをダウンロードするクライアントもあれば、プロバイダーの更新をコアが処理するクライアントもあります。TUNを有効にして問題が解消しても、通信経路が変わったことを示すだけで、YAMLが正しい証拠にはなりません。すべてのユーザーにTUNを推奨する理由にもなりません。

ローカルプロキシを使って再現可能なテストを行う

以下はmacOSまたはLinuxのBash向けです。URLは対話形式で入力し、コマンド履歴に直接残らないようにしています。ただし実行時にはローカルのプロセス引数に表示される可能性があるため、信頼できる端末でのみ実行してください。レスポンスファイルにも機密情報が含まれるので、アップロードしないでください。まず直接接続でテストし、次に動作確認済みのローカル混合ポート経由で比較します。

umask 077
read -r -s -p 'サブスクリプションURLを入力：' SUB_URL
printf '\n'
curl --noproxy '*' --location --connect-timeout 10 --max-time 30 \
  --output subscription-direct.yaml \
  --write-out 'HTTP %{http_code}\n' "$SUB_URL"

curl --noproxy '' --proxy http://127.0.0.1:7890 \
  --location --connect-timeout 10 --max-time 30 \
  --output subscription-proxy.yaml \
  --write-out 'HTTP %{http_code}\n' "$SUB_URL"
unset SUB_URL

7890 は一般的な混合ポートの例です。クライアントが現在実際に待ち受けているポートに置き換えてください。クライアントがそのポートで待ち受けていない場合、2つ目のコマンドで接続拒否されても、サブスクリプションサーバーに問題があるとは限りません。ここでは --fail を使っていないため、HTTP 403でも本文が保存される場合があります。HTTPステータスとファイル内容の両方を確認してください。

手順3：サーバーから返された内容を確認する

HTTP 200はリクエストが成功応答を受け取ったことを示すだけで、レスポンスがClashの設定ファイルとは限りません。保存したファイルをローカルのテキストエディターで開き、先頭の数行とトップレベルのキーを確認します。内容をそのまま実行しないでください。

完全な設定ファイルとノードプロバイダーを混同しない

完全な設定ファイルには通常、プロキシ、プロキシグループ、ルールが含まれ、proxy-providers から外部ノードを参照することもできます。一方、ノードプロバイダーのファイルは proxies: で始まることが多く、ノードの提供だけを担います。ノードだけを含むファイルをメイン設定として読み込むと、ノードは表示されても期待したプロキシグループがない場合があります。完全な設定ファイルをプロバイダーとして読み込むと、形式エラーになることもあります。

プロバイダーを使う場合は、メイン設定の読み込み結果とプロバイダーのダウンロードログを分けて確認します。メイン設定の構文が正しくても、リモートプロバイダーの更新が成功したとは限りません。特定のプロキシグループだけが空の場合は、すぐにすべての設定をリセットせず、そのグループの use、プロバイダーの状態、フィルター式を確認してください。

手順4：エラー行と参照名からYAMLを確認する

YAMLではインデントが重要です。Tabではなく半角スペースを使い、同じ階層ではインデントを統一します。各階層2スペースが一般的です。mapping values are not allowed や did not find expected key が表示されたら、エラー行から上へ3～5行確認します。実際の原因は、前の行の引用符が閉じていない、またはリスト項目のインデントがずれていることがあります。

まず最小構成で読み込み経路を確認する

以下はリモートノードを含まない最小構成です。「クライアントがどの設定も読み込めない」のか「サブスクリプションの内容に問題がある」のかを切り分けるために使います。選択できるのは直接接続のみで、リモートプロキシには接続しません。別のテストファイルとして保存し、元のサブスクリプションを上書きしないでください。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: "手動選択"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,手動選択

テストファイルでポート使用中と表示された場合は、別のプロキシプロセスを終了するか、空いているポートに変更し、テストコマンドも同じポートに合わせます。ポートの待ち受け失敗は実行時の問題であり、YAML構文エラーではありません。テスト設定を正常に読み込めたら、元のサブスクリプションに戻り、違いを特定してください。

重点的に確認する4種類の構造上の問題

• キーと値の間のスペース不足：mixed-port: 7890 と記述します。mixed-port:7890 でも同じキーと値の構造になるとは限りません。
• 名前を引用符で囲んでいない：ノード名に : や # などの特殊な並びが含まれる場合は、名前全体を引用符で囲みます。文字列内の引用符も正しく扱ってください。
• 参照名が一致しない：プロキシグループ内のノード名は、定義された名前と大文字・小文字、スペース、記号まで完全に一致させます。ノード名を変更した場合は、参照先も同時に変更してください。
• トップレベルのキーが重複：2つの設定ファイルをそのまま結合し、proxies: や rules: を重複させないでください。重複キーを拒否するパーサーもあれば、異なる方法で処理するものもあります。上書き動作を前提にしないでください。

拡張子だけで形式を判断しないでください。config.yaml という名前でも、中身がHTMLのエラーページなら設定ファイルではありません。理解できないキーをまとめて削除するのも避けてください。認証情報、トランスポート設定、TLS設定を消すと、構文チェックは通ってもノードに接続できなくなる場合があります。

手順5：実際に使われているコアとプロトコルの互換性を確認する

Clashの設定形式には、関連性はあるものの完全には同一でない複数の種類があります。mihomoコアでサポートされている一部のプロトコルやキーは、旧バージョンのClashコアでは使えない場合があります。たとえばサブスクリプションに type: hysteria2 が含まれる場合は、実際に動作しているコアがそのノードタイプに対応しているか確認してください。別のプロトコル名に書き換えるのは避けてください。

1. クライアントの「バージョン情報」画面または起動ログでバージョンを記録します。画面にコア情報が表示されない場合は、ログにあるコア名とバージョンの行を確認してください。
2. ダウンロードしたパッケージのOSとアーキテクチャを確認し、別のインストール先にある複製ではなく、実際に起動中のクライアントを更新していることを確かめます。
3. ログに未対応のプロキシタイプやフィールドが明記されている場合は、サービス提供元が用意する互換形式を選ぶか、該当機能に対応するクライアントとコアを使用してください。
4. エラーを消すためだけに reality-opts や tls などの接続パラメーターを削除しないでください。設定を読み込めることと、ノードが正常にハンドシェイクできることは別です。

mihomo付属のチェックコマンドを使う

ローカルにコマンドライン版mihomoがインストールされている場合は、ターミナルで保存済みの設定を確認できます。以下のコマンドは、実行ファイルがPATH上にあり、テストファイルがカレントディレクトリにあることを前提としています。まずバージョンを確認してから、設定テストを実行してください。

mihomo -v
mihomo -t -f ./subscription-direct.yaml

テスト結果が当てはまるのは、そのファイルとコアの組み合わせだけです。GUIクライアントでは、オーバーライドや設定の結合、スクリプト処理が加わる場合があります。ターミナルでテストに成功しても、クライアントが実際に生成した実行設定を確認してください。外部リソースを参照する設定は、テスト時または後続の読み込み時にネットワークアクセスが必要になることがあります。テストに成功したからといって、すべてのノードがオンラインとは限りません。

更新は成功するのにノードが空：フィルターと設定の有効化状態を確認する

まず、更新したばかりの設定が選択されているか確認します。クライアントによっては、サブスクリプションの更新と有効な設定への切り替えは別の操作です。ノード一覧が変わらない場合は、更新時刻、有効な設定の表示、読み込みログを確認します。リクエスト頻度の制限を避けるため、更新ボタンを連続して押さないでください。

• 設定ファイルにもノードがない：ローカルファイルが proxies: [] で、ほかに有効なノードの取得元もない場合は、アカウントと出力条件をサービス提供元に確認してください。
• 設定ファイルにはノードがあるが、画面に表示されない：名前検索、地域フィルター、正規表現フィルター、除外条件が有効になっていないか確認します。まずフィルターを解除して比較してください。
• プロバイダーのグループだけが空：プロキシグループの use が正しいプロバイダー名を参照していることを確認し、そのプロバイダーの直近のダウンロードが成功しているかログを確認してください。
• 読み込み後にだけエラーが発生する：カスタムオーバーライドや結合ルールを一時的に無効にして比較し、バックアップを残します。メインのサブスクリプションと追加設定はそれぞれ正しくても、結合後に名前が衝突する場合があります。

ノード一覧に表示されていて、遅延テストだけがタイムアウトする場合は、接続のトラブルとして調査してください。テスト先に到達できない、ノードの出口に問題がある、ローカルネットワークが通信を遮断しているなど、さまざまな原因でタイムアウトが発生します。これをサブスクリプションの解析エラーと判断することはできません。この場合、YAMLのインデントを何度も変更しても通常は解決しません。

修正後の確認と、問い合わせ時に共有する情報

一度に変更するのは1項目だけにし、その都度更新して同じログ箇所を確認します。DNS、コア、サブスクリプションURL、ルールを同時に変更すると、原因を判断できなくなります。ポップアップが消えただけで終わらないよう、修正後は次の順に確認してください。

1. サブスクリプションを手動で一度更新し、HTTPリクエストが成功して更新時刻が変わることを確認する。
2. 設定の解析とコアへの読み込みが成功し、ノード、プロキシグループ、プロバイダーの不足を示すエラーがないことを確認する。
3. ノードを1つ選び、実際のプロキシ経由でHTTPSページにアクセスした後、必要なアプリでもテストする。ブラウザーで正常に表示されても、すべてのアプリがプロキシ経由とは限りません。
4. クライアントを再起動し、有効な設定が維持されていることを確認する。定期更新を使っている場合は、次のスケジュール実行も成功するか確認してください。
5. 調査中に生成した機密情報を含むレスポンスファイルを削除し、不要になった一時設定も片付けてください。

調査の順序は変えず、まずURLの有効性を確認し、次にネットワーク経由でレスポンスを取得できるか、最後にレスポンス形式・YAML構造・コアの互換性を確認します。ポートやルールの基礎は使い方ガイドを、アカウントURLや自動更新の問題はサブスクリプションに関するFAQをあわせてご覧ください。