Clashのサブスクリプション更新・解析エラー対処法：User-AgentとYAMLの確認ポイント

1. エラーを切り分ける：まず失敗した段階を記録する

現在使えている設定は残したまま、サブスクリプションを手動で一度更新し、更新時刻とエラー全文を記録します。更新処理は、ドメインの名前解決、HTTPS接続、HTTPレスポンス、コンテンツの解析、設定の読み込みの順に進みます。前の段階で失敗している場合、その後のルールを変更しても通常は解決しません。

デスクトップクライアントでは、サブスクリプションまたは設定の一覧を開き、どの項目を更新しているか確認してから、アプリのログまたはコアのログを確認します。画面上の名称はクライアントによって異なります。「設定ファイルの更新成功」を「プロキシプロバイダーの更新成功」と混同しないでください。両者は異なるURLを参照している場合があり、キャッシュも別々です。

2. URL形式：ログインページではなく元のサブスクリプションURLをコピーする

サービスの管理画面からURLをコピーし直す

1. サービスの管理画面にログインし、「Clash」または現在のコアに対応すると明記されたサブスクリプション形式を選びます。
2. 「リンクをコピー」機能を使い、チャットアプリで途中までしか表示されていないURLをつなぎ合わせないでください。
3. 先頭が https:// か、末尾に空白、改行、全角句点、閉じ括弧が混入していないか確認します。
4. クエリパラメーターをすべて残します。? 以降を不用意に削除したり、& で区切られたパラメーターを途中で切ったりしないでください。

Webページのソースにある & はHTMLエンティティ表記です。実際のURLでは、パラメーターの区切りに & を使います。コピーしたURLに文字列 & がそのまま含まれていると、後続のパラメーターが誤った名前として扱われることがあります。手作業で置換するより、管理画面のコピー機能でURLを取得し直すほうが確実です。

clash:// のようなURLは、アプリを起動して読み込むための指示であり、直接ダウンロードできるHTTPSサブスクリプションではない場合があります。ブラウザーのアドレス欄に表示されるユーザーセンター、注文詳細、サブスクリプションの説明ページも、設定ファイルのURLとしては使えません。ブラウザーでページが開けても、それはページにアクセスできたというだけで、YAMLが返されたことを意味しません。

ログイン状態とリダイレクトを確認する

ブラウザーにログインCookieが保存されていればダウンロードできても、そのCookieを持たないクライアントにはログインページや拒否レスポンスが返ることがあります。正規のサブスクリプションAPIでは通常、URL内のトークンなどの認証方式を使います。ブラウザーのCookieを出所不明のスクリプトに貼り付けず、サービスの案内に従ってクライアント用URLを再発行してください。

301、302、307 が返る場合は、最終的なURLが想定しているサービスのものか確認します。ログインページ、認証ページ、または失効したドメインにリダイレクトされる場合は、YAMLのインデントではなく、まずAPIへのアクセスを解決してください。

3. HTTPレスポンス：ステータスコード、ヘッダー、レスポンス本文を保存する

LinuxとmacOSでは、ローカルのターミナルからcurlを使えます。Windows PowerShellでは、古い環境で同名のエイリアスが使われるのを避けるため、curl.exeを明示して実行してください。以下のコマンドではURLを対話形式で入力するため、サブスクリプションURL全体がコマンド履歴に残りません。入力時に画面を見られないようにする点には引き続き注意してください。

# Linux / macOS：ホームディレクトリ内にアクセス制限付きの調査用ディレクトリを作成
mkdir -m 700 subscription-check
cd subscription-check
umask 077
read -r -s -p 'サブスクリプションのHTTPS URLを貼り付けてください：' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --dump-header response-headers.txt \
  --output response-body.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

10秒は接続タイムアウト、30秒はリクエスト全体の上限時間です。いずれも今回の診断用の値であり、性能を保証するものではありません。コマンドでは --fail を使っていないため、サーバーがエラーを返した場合も本文が保存され、認証エラーの案内と設定データを区別できます。コマンドでネットワークエラーが出た場合は、まずそのエラーに対処してください。HTTP 000 は、サーバーからステータスコード000が送信されたという意味ではありません。

• 200：レスポンス本文を確認します。ログインページ、認証ページ、エラーを示すJSONが200で返る場合もあります。
• 401 / 403：トークン、サブスクリプションの状態、アクセス制限、レスポンスの説明を確認します。403だけでUser-Agentが原因だとは断定できません。
• 404 / 410：パスが失効していないか、ドメインが移転していないか確認し、管理画面からURLを取得し直します。
• 429：Retry-After がある場合は、その指示に従って待ちます。更新を何度も繰り返さないでください。
• 500 / 502 / 503：発生時刻とステータスコードを記録し、時間をおいて再試行します。クライアントを再インストールしても、通常はサーバー側のエラーは解決しません。

ローカルのテキストエディターで response-body.txt を開きます。先頭が <!DOCTYPE html> または <html なら、通常はWebページです。JSONのエラーオブジェクトで始まる場合は、まずエラー項目を確認してください。Content-Type は参考になりますが、YAMLを通常のテキストとして返すAPIもあります。レスポンスヘッダーだけで内容の有効性を判断しないでください。

4. User-Agent：根拠のあるリクエストだけを比較する

サブスクリプションAPIによっては、User-Agent に応じて出力形式を切り替えるものや、形式をパラメーターで明示する必要があるものがあります。ブラウザーにはノードの共有リンクが返り、クライアントにはYAMLが返る場合、同じAPIが異なる出力方法を使っている可能性があります。まずサービスが案内するクライアント向けの説明を確認し、ブラウザーのUser-Agentを手当たり次第に試さないでください。

上記のターミナルセッションでサブスクリプションURLを入力し直した後、次のコマンドで一度比較できます。mihomo はテスト用の識別子にすぎず、特定のGUIクライアントが実際に送信するリクエストヘッダーと同じとは限りません。また、すべてのAPIが認識するわけではありません。

read -r -s -p 'サブスクリプションのHTTPS URLを貼り付けてください：' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --user-agent 'mihomo' \
  --dump-header response-headers-ua.txt \
  --output response-body-ua.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

2つのレスポンス本文のトップレベル項目とステータスコードを比較します。指定したリクエストヘッダーを付けた場合のみ互換性のある設定が返るなら、クライアントに「サブスクリプションのリクエストUser-Agent」設定があるか確認してください。サブスクリプション全体の読み込みと、proxy-providers によるダウンロードは別の経路です。一方を変更しても、もう一方に反映されるとは限りません。使用中のコアのドキュメントで明確にサポートされている場合に限り、該当するプロバイダー設定にリクエストヘッダーを指定してください。

5. コンテンツ形式：完全な設定、プロバイダー、共有リンクを混同しない

Clashの設定は、あらゆる「ノードのテキスト」を指すものではありません。よくあるレスポンスは3種類あり、それぞれ適切な読み込み先が異なります。拡張子が .yaml でも、内部構造がコアの要件を満たしているとは限りません。

完全な設定でも、proxies を直接含めず、proxy-providers からノードを取得できます。そのため、設定内のリストが空だからといって、サブスクリプションにノードがないとは限りません。プロバイダーのダウンロードが成功したか、ポリシーグループの use で正しい名前を参照しているかも確認してください。

サービスからエンコードされた共有リンクだけが返る場合、デコードしてもClash設定とは限りません。デコードしたテキストを config.yaml にリネームしないでください。サービスが提供する対応形式を優先し、見知らぬ変換APIにサブスクリプションの認証情報を渡さないようにしましょう。

6. YAMLの解析：最初のエラーを直してから、フィールドの互換性を確認する

インデント、引用符、フィールドの型

YAMLのインデントにはスペースを使い、Tabは使いません。同じ階層のインデントは、たとえば各階層2スペースのように統一します。「18行目付近で解析に失敗」と表示されたら、17行目も確認してください。閉じ忘れた引用符、コロンの不足、誤ったインデントは、次の行で初めてエラーとして検出されることがよくあります。

• コロン：キーと値の区切りには半角の : を使い、その後には通常スペースを1つ入れます。
• リスト：項目には半角の - とスペースを使い、リストを含むフィールドも正しいインデントにします。
• 文字列：名前に「コロンとスペース」が含まれる場合は、マッピング構造として誤認されないよう引用符で囲みます。
• 型：ポートなどの数値フィールドには、コアの要件に従って整数を指定します。真偽値には true または false を使い、日本語のオン・オフ表記は使わないでください。
• 重複キー：トップレベルの rules や proxy-groups を重複して定義しないでください。解析器によってはエラーになり、別の解析器では先に設定した値が上書きされることがあります。

以下はポリシーグループとルールの構造例です。リモートノードは含まず、サブスクリプションの代わりになる完全な設定でもありません。調査時に現在使用中のファイルを上書きしないでください。

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

rules:
  - "DOMAIN-SUFFIX,example.com,手動選択"
  - "MATCH,手動選択"

ルール末尾のポリシー名は、定義済みのポリシーグループまたは組み込みポリシーと一致させる必要があります。「手動選択」を別の名前に変更する場合は、ルール内の参照も合わせて変更してください。YAMLの構文が通るのはテキストを解析できたというだけで、プロキシプロトコル、フィールドの組み合わせ、名前の参照がすべて有効とは限りません。

実際に使用するコアでテストする

mihomoではローカルで設定のテストを実行できます。まず mihomo -v でバージョンを記録し、次のコマンドを実行します。ファイル名は、現在のディレクトリに保存したテスト対象の設定ファイルに合わせてください。

mihomo -v
mihomo -t -f ./config.yaml

できるだけGUIクライアントが実際に使用しているコアのバージョンでテストしてください。別の新しいコアでテストして分かるのは、そのコアが設定を受け付けるかどうかだけです。アプリに内蔵されたコアとの互換性を証明するものではありません。プロバイダー、ルールセット、ジオデータベースなどの外部依存関係は、起動ログも合わせて確認してください。

プロキシの種類やフィールドがサポートされていないというエラーが出た場合は、まずサブスクリプションの出力対象を確認します。Clash、Clash Meta（mihomo）、各種フォークでは、設定機能が完全に同じではありません。エラーを消すためにプロトコル必須のフィールドを削除しないでください。互換性のある形式で出力するか、クライアントが対応していることを確認してからコアを更新してください。

7. プロキシが表示されない・通信に失敗する：ダウンロードと読み込みを分けて確認する

更新に成功したのに一覧が空なのはなぜ？

1. 有効な設定を確認：設定Aを更新しても、実行中なのは設定Bかもしれません。更新後に現在の設定名と読み込みログを確認してください。
2. プロバイダーを確認：メイン設定のダウンロードが成功していても、DNS、認証、ネットワークのエラーでプロキシプロバイダーの取得に失敗する場合があります。
3. フィルターを確認：filter、exclude-filter、または画面上の検索条件ですべてのプロキシが除外されている可能性があります。まずコピーを作成し、そのコピーでフィルターを外して結果を確認してください。
4. ポリシーグループの参照を確認：プロバイダー名は、ポリシーグループの use と一致している必要があります。プロバイダーを定義しただけでは、すべてのポリシーグループにそのノードが表示されるわけではありません。
5. 一覧が空の場合とテストのタイムアウトを区別：ノードが表示されているのに遅延テストに失敗する場合は、接続またはテスト経路の問題です。「サブスクリプションからノードを解析できなかった」状態ではありません。

システムプロキシ、TUN、ローカルポート

サブスクリプションのリクエストがプロキシ経由になるかどうかは、クライアント独自の更新設定と実行環境によります。システムプロキシを有効にしても、バックグラウンド更新機能がそれを使うとは限りません。TUNを有効にしても、失効したトークンや不正なYAMLは直りません。まずリクエストが直接接続か、既存のプロキシ経由かを確認し、設定は一度に1つだけ変更してください。

エラーに 127.0.0.1:7890 と表示される場合は、実際の待ち受けポートが7890か、コアが起動しているかを確認します。7890はよくある例にすぎず、すべてのクライアントで固定されているわけではありません。コアの起動に失敗した後も更新機能がローカルプロキシに依存すると、「設定が読み込めず、サブスクリプションも取得できない」というループに陥ります。クライアントが対応している場合は、一時的に直接接続で更新し、元の設定は復元できるよう残しておきます。

x509、証明書の期限切れ、または証明書の有効期間外というエラーが出る場合は、まずシステムの日付、時刻、タイムゾーンを合わせます。次に、ログインが必要な公共ネットワークを利用していないか確認してください。証明書検証を無効にしたまま使うのは避けてください。DNSエラーの場合は、システムの名前解決とサブスクリプションのドメインを先に確認します。DNS、TUN、ルール、プロキシのプロトコルを一度に大きく変更すると、どの変更が効いたのか分からなくなります。

8. 復旧を確認する：2回連続で確認してから自動更新を再開する

1. 手動で一度更新し、レスポンス本文が想定した設定であり、ログインページやAPIエラーではないことを確認します。
2. 設定を読み込み、解析エラーがないこと、プロバイダーのダウンロードが完了すること、ポリシーグループに想定したノードが表示されることを確認します。
3. ノードを1つ選び、正常に接続できるか確認します。ノードの接続可否とサブスクリプションの更新結果は別々に記録し、すべての確認を1つの「成功」表示で済ませないでください。
4. 適切な間隔を空けてもう一度更新し、古いキャッシュが一時的に成功と表示されているだけではないことを確認してから、元の自動更新間隔に戻します。

解決しない場合は、クライアント名、実際のコアのバージョン、OS、エラー発生時刻、HTTPステータスコード、機密情報を伏せたエラー行をサービス窓口に伝えてください。トークン全体、プロキシのパスワード、設定ファイル全体は送信しないでください。ローカルの調査用ファイルを削除する前に、認証情報を含まない調査結果を残します。レスポンスヘッダーにはCookieやトークンを含むリダイレクト先URLが含まれることもあるため、同様に機密情報として扱ってください。

クライアントを選び直す場合はクライアント比較をご覧ください。ルール、ポリシーグループ、プロバイダーの違いを確認するには用語クイックガイドをご覧ください。復旧の順序は変わりません。URLが有効であること、正しいレスポンスが返ること、形式に互換性があること、設定を読み込めることを確認し、最後に接続をテストします。