Clash YAML
設定ファイルリファレンス

共通フィールド：ポート、モード、コントロールAPI

リスニングポートの使い分け

portはHTTPプロキシの待受、socks-portはSOCKS5の待受に使われ、mixed-portは同じポートでHTTPとSOCKS5の両方を受け付けます。デスクトップのGUIクライアントでは通常、mixed-portを1つ用意すれば十分で、システムプロキシが自動的にそこを指します。別のアプリがSOCKS5アドレスを明示的に要求する場合は、socks-portを個別に設定できます。複数の待受ポートで同じ番号を使うことはできず、システム上の他のサービスとも競合させないでください。

redir-portとtproxy-portは主にLinuxゲートウェイ、ルーター、透過プロキシのルールで使用します。デスクトップ環境では、「より多くの通信をカバーする」ためだけに不用意に有効化しないでください。TUNモードには独立した仮想NICとルーティング経路があり、待受ポートを単純に1つ増やすものではありません。2つの取り込み方式を比較する場合は、TUNモードとシステムプロキシの違いを参照し、まず通信がどこからコアに入るのかを確認してから関連フィールドを選びます。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false

external-controller: 127.0.0.1:9090
secret: "your-controller-secret"

profile:
  store-selected: true
  store-fake-ip: true

LANアクセスとバインドアドレス

allow-lanは、他のデバイスが現在の端末のプロキシポートへ接続できるかどうかを決めます。falseなら単体利用に適しています。trueにした場合は、OSのファイアウォール、待受アドレス、LAN分離設定も確認してください。LANアクセスを許可しただけで、スマートフォンやテレビが自動的にプロキシ設定されるわけではありません。対象デバイスで、Clashを実行している端末のLANアドレスと待受ポートを入力する必要があります。アドレスが変わると接続できなくなるため、継続的に共有する場合はホストに安定したLANアドレスを割り当ててください。

bind-addressは待受範囲を制限します。クライアントによっては「LAN接続を許可」するスイッチに応じてこのフィールドを自動生成するため、起動時に画面の設定でファイルの値が上書きされることがあります。トラブル対処では実際の待受アドレスを確認してください。127.0.0.1だけを待ち受けている場合、他のデバイスからアクセスできません。すべてのインターフェースで待ち受ける場合は、コントロールAPIとプロキシポートを信頼できないネットワークへ直接公開しないようにしてください。プロキシの待受と外部コントロールAPIは別のサービスであり、混同してはいけません。

動作モード、ログ、状態の保存

mode: ruleはrulesを上から順に照合する、日常設定の中心となるモードです。globalは通信をグローバルプロキシへ渡すため、特定のノードが使えるか一時的に確認するのに適しています。directはリクエストを直接接続し、問題がプロキシ経路にあるかを切り分けるのに役立ちます。GUIクライアントのモードボタンは実行中の状態だけを切り替え、元のサブスクリプションファイルへ書き戻さないことがあります。ファイルのmodeだけでなく、クライアントの現在の画面も確認してください。

log-levelは通常infoを使い、トラブル対処時だけ一時的にdebugへ上げ、終了後に戻します。ログが多すぎると判断の妨げになります。ipv6はコアがIPv6関連の機能を処理するかを制御しますが、ローカルネットワーク自体にIPv6ルートがない問題を解決するものではありません。有効化後に接続待ちが発生した場合は、DNSがIPv6アドレスを返していないか、システムに利用可能なIPv6出口があるか、ルールが対象アドレスをカバーしているかを確認してください。

external-controllerは画面とコアが通信するコントロールアドレスを提供し、通常は本機のループバックアドレスにバインドします。secretはコントロールAPIのアクセス資格情報なので、サンプル値を必ず置き換えてください。これはプロキシノードのパスワードではなく、リモート接続にも使われません。profile.store-selectedはプロキシグループの選択を保存し、profile.store-fake-ipはFake-IPのマッピング状態を保存します。サブスクリプション更新後に選択が毎回リセットされる場合は、YAMLだけでなくクライアント側の永続化設定も確認してください。

プロキシノードのフィールドとプロキシプロバイダー

ノードオブジェクトの共通構造

proxiesは静的なノード一覧です。各項目には少なくとも名前、タイプ、サーバーアドレス、ポートを含め、プロトコルに応じて認証やトランスポートのフィールドを追加します。nameは設定全体で使う参照識別子で、プロキシグループはこの名前でノードを探します。同名ノードがあると選択や上書きの結果が不確定になるため、サブスクリプションをマージした後は名前が一意か確認してください。serverにはドメインまたはIPを指定でき、portはサーバー側の実際の待受ポートと一致させます。

プロトコルの種類によって利用できるフィールドが決まるため、あるプロトコルのパラメーターを別のプロトコルへ機械的にコピーしないでください。暗号方式、ユーザー識別子、トランスポート層、TLS、サーバー名はすべてサーバー側の設定と一致させる必要があります。クライアントがYAMLを読み込めても、構文とフィールド構造が基本的に有効というだけで、リモート認証の成功までは意味しません。ログに出るハンドシェイク失敗、認証失敗、接続拒否、タイムアウトはそれぞれ異なる段階を示すため、エラーの段階に応じて対処します。

proxies:
  - name: "SS サンプルノード"
    type: ss
    server: ss.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "Trojan サンプルノード"
    type: trojan
    server: trojan.example.com
    port: 443
    password: "your-password"
    sni: service.example.com
    skip-cert-verify: false
    udp: true

  - name: "Hysteria2 サンプルノード"
    type: hysteria2
    server: hy2.example.com
    port: 443
    password: "your-password"
    sni: service.example.com
    skip-cert-verify: false

認証、TLS、トランスポートのフィールド

Shadowsocksノードでは、cipher、password、udpがよく使われます。暗号方式はサーバー側と同じにする必要があり、名前が似ていても代用できません。Trojan系ノードはTLSに依存し、パスワードに加えてsniが必要になることもあります。SNIはハンドシェイクで使うサーバー名です。接続先アドレスと同じ場合もあれば、サービス提供者から指定される場合もあります。誤って入力するとTCP接続は成功してもTLSハンドシェイクに失敗します。

skip-cert-verifyは証明書検証を制御します。通常の設定ではfalseを維持し、サーバー名、システム時刻、証明書チェーンの問題を先に修正してください。trueへの変更は、証明書検証が故障箇所かを切り分ける場合だけに使い、一般的な修復方法にはしないでください。システム時刻のずれ、制限されたネットワークによる遮断、誤ったSNIはいずれも証明書関連のエラーを引き起こします。「接続失敗」という表示だけでは原因を判断できないため、ログのハンドシェイク段階も確認してください。

VMess、VLESS、TUIC、Hysteria2などでは、ユーザー識別子、ネットワークタイプ、WebSocketパス、HTTPヘッダー、フロー制御、輻輳制御のフィールドが含まれることもあります。フィールドの集合はコアの機能やサーバー側の構成によって変わります。ノードを手動で移行する場合は、元のサブスクリプションと現在のコアのドキュメントを基準にし、別のノードの見た目だけでフィールドを追加しないでください。オリジナルClash、Meta、mihomoの名称と互換性については、コアバージョンの選び方を参照してください。

proxy-providersのオンデマンド読み込み

ノード数が多い場合やリモート更新が必要な場合は、proxy-providersを使えます。プロバイダーはノードの集合で、プロキシグループからuseで参照します。一般的なタイプはHTTPまたはローカルファイルです。リモートプロバイダーには、URL、更新間隔、保存先、ヘルスチェックを指定します。保存先はクライアントが書き込みを許可している場所にしてください。コンテナやサービスとして動かす場合は、ディレクトリ権限も確認します。リモートURLのクエリパラメーターにはアクセス資格情報が含まれることがあるため、公開ログや公開サンプルに書かないでください。

proxy-providers:
  provider-main:
    type: http
    url: "https://subscription.example/config?token=xxxx"
    path: ./providers/provider-main.yaml
    interval: 3600
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

proxy-groups:
  - name: "サブスクリプションノード"
    type: select
    use:
      - provider-main
    proxies:
      - DIRECT

intervalは更新間隔であり、起動するたびに必ず即時ダウンロードするという意味ではありません。クライアント独自の更新ボタンやキャッシュ戦略が使われることもあります。health-checkは固定アドレスでノードの到達性を確認し、その結果を画面表示や自動プロキシグループの選択に使います。ただし、1つのテストアドレスだけで、すべてのWebサイトが利用できるとは判断できません。テストに失敗したら、まずそのアドレスが現在のネットワークから到達可能か確認し、その後でノード障害を判断してください。

proxiesとuseは同じプロキシグループ内に共存できます。前者は固定ノードや内蔵アクションを列挙し、後者はプロバイダーの集合を取り込みます。上書きツールはこの2種類のフィールドを異なる方法で処理することがあり、静的ノードを追加してもプロバイダーへ自動的に追加されるとは限りません。サブスクリプション更新後にノードが消えた場合は、リモートプロバイダーの更新成功、保存先の書き込み可否、プロキシグループが正しいプロバイダー名を参照しているかを確認します。

ルール構文、マッチ順、ルールセット

ルールは上から下へ順番にマッチする

rulesは順序付きリストです。リクエストは最初にマッチしたルールで処理を止めるため、具体的なルールを広範なルールより上に置き、末尾には残りの通信を受けるMATCHを置きます。MATCHを先頭に置くと、後続のルールは一切有効になりません。広いドメインサフィックスを先に書き、その後にサブドメイン用の特殊ルールを書くと、サブドメインも先のルールで処理されます。

ルールは通常、「タイプ、マッチ値、プロキシグループ」で構成され、一部には追加パラメーターを指定できます。カンマはフィールドの区切りで、プロキシグループ名はproxy-groupsに存在するか、DIRECT、REJECTなどの内蔵アクションでなければなりません。ルール行の余分な空白が値の一部になることがあるため、手動編集では形式を統一してください。

rules:
  - DOMAIN,api.example.com,ノード選択
  - DOMAIN-SUFFIX,example.com,ノード選択
  - DOMAIN-KEYWORD,example,ノード選択
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - PROCESS-NAME,example-app.exe,DIRECT
  - GEOIP,CN,DIRECT
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-domain,ノード選択
  - MATCH,ノード選択

ドメイン、アドレス、プロセスのルール

DOMAINは完全一致のドメインだけにマッチし、単一ホストに適しています。DOMAIN-SUFFIXは指定ドメインとそのサブドメインにマッチし、サイト全体に適しています。DOMAIN-KEYWORDはドメインにキーワードが含まれるだけでマッチする可能性があり、範囲が最も広く、誤マッチもしやすい方式です。完全なドメインを使えるならキーワードを使わず、明確なサフィックスを使えるなら短すぎる断片を指定しないでください。

IP-CIDRとIP-CIDR6は対象アドレスの範囲でマッチします。LAN、コンテナのネットワーク、社内ネットワークは通常ダイレクト接続を優先しますが、アドレス範囲は実際のネットワークに合わせる必要があります。no-resolveは、マッチ判定のためにIPを取得する追加のドメイン解決を行わない指定です。不要なDNSクエリを避けられますが、既存のIP通信を禁止するものでも、アプリがすでに完了した名前解決を変更するものでもありません。

PROCESS-NAMEやプロセスパス系のルールは、プラットフォームの機能、権限、通信の取り込み方式に依存します。システムプロキシモードでは、すべての通信からプロセス情報を確実に取得できるとは限りません。モバイルプラットフォームでも、同じプロセスルールに対応しないことがあります。クロスプラットフォーム設定では、ドメインとアドレスのルールを基本とし、プロセスルールは特定デバイス向けの補助として使ってください。デスクトップではマッチするのにスマートフォンではマッチしない場合、まずルールタイプがプラットフォームをまたいで利用できるか確認します。

GEOIPはIPデータベースに基づいて分類し、GEOSITEやルールセットはドメイン集合に基づいて分類します。利用できる機能はコアとデータファイルに依存します。データベースルールは広範囲を簡単にカバーできますが、分類データには更新周期があるため、明確な業務ルールの代わりにはなりません。特定ドメインを必ず指定したプロキシグループへ送る場合は、データベースルールより前に正確なルールを置いてください。

rule-providersで大規模なルールセットを管理する

大量のルールはrule-providersにまとめるのが適しています。各プロバイダーには、名前、タイプ、動作、取得元、保存先、更新間隔が必要です。behaviorは内容の形式を決めます。ドメイン集合、IPアドレス範囲、従来型のルール行を混在させることはできません。プロバイダーのダウンロードに成功しても、分岐へ参加したとは限りません。rulesで同じ名前のRULE-SETを使用する必要があります。

rule-providers:
  private-domain:
    type: http
    behavior: domain
    format: yaml
    url: "https://rules.example/private-domain.yaml"
    path: ./rules/private-domain.yaml
    interval: 86400

  service-domain:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/service-domain.yaml

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-domain,ノード選択
  - MATCH,ノード選択

domain動作はドメインまたはドメインサフィックスの集合に適し、ipcidrはアドレス範囲に、classicalは従来型のルール表現に対応します。リモート内容の形式は宣言と一致させてください。プロバイダーファイル自体に完全なpayload構造が含まれる場合、保存後にコアが対応する形式で読み込みます。通常のサブスクリプションファイルを誤ってルールセットとして扱うと、解析段階でエラーになります。

ルールセットの更新に失敗したら、まずネットワークリクエストの状態、次に保存先の権限とファイル形式を確認します。古いキャッシュが使われ続けることがあるため、「現在もアクセスできる」だけでは更新成功の証明になりません。サービスモードでは相対パスの基準が実行ディレクトリやクライアント設定ディレクトリになるため、YAMLファイルのある場所とは限りません。端末移行後にルールプロバイダーが使えなくなった場合、パスの違いがよくある原因です。

結果を推測せず、ルールのマッチを確認する

クライアントの接続履歴には通常、対象ドメイン、マッチしたルール、最終的なプロキシグループが表示されます。テスト時はブラウザーの既存接続を閉じるか、新しいリクエストを使ってください。接続の再利用により、古いプロキシグループが使われ続けることがあります。ルールを変更したら設定を再読み込みし、新しい接続が新ルールにマッチするか確認します。Webページが開くかどうかだけでは、ダイレクト接続かプロキシ経由かを区別できません。

カスタムルールは少数の正確な項目から始めます。まず明確なドメインルールを1つ書いてマッチを確認し、その後サフィックスやルールセットへ段階的に広げます。新しいルールで多くのサイトに異常が出たら、短すぎるキーワード、広すぎるアドレス範囲、早すぎる位置のMATCHを確認してください。ルール分岐で重要なのは数ではなく、順序が明確で、対象が存在し、範囲を説明できることです。

設定チェック、読み込み手順、障害の切り分け

まず構文、次にネットワークを確認する

設定障害は、ファイルのエンコーディングとYAML構文、フィールド構造と参照、待受ポート、DNS、ノード接続、プロキシグループ、ルールのマッチ、アプリの取り込みという順番で対処します。前の段階を通過していないのに次へ進まないでください。構文エラーは設定全体を読み込めなくします。ノードエラーは該当する接続だけに影響し、ルールエラーは通信を誤ったプロキシグループへ送る可能性があります。障害の範囲を分けることで、目的なくすべての設定を交換せずに済みます。

GUIクライアントには通常、設定チェックや再読み込みのボタンがあります。サーバーやコマンドライン環境では、使用中のコアが提供するテストパラメーターを使えますが、実行ファイル名とパラメーターはインストーラーに付属する説明を基準にしてください。チェックコマンドは実際の設定ディレクトリを指す必要があります。相対パスを誤ると、同名の別ファイルをテストしてしまうことがあります。「設定は有効」と表示されても、起動ログを確認してください。ポート競合、ディレクトリ権限、ネットワーク接続は実行段階の問題です。

# 実際の設定ディレクトリへ移動してから、使用中のコアの設定チェックパラメーターを呼び出す例
cd /path/to/clash-config
mihomo -t -d .

# 本機のポートが使用中か確認する場合は、OSに対応したツールを使う
# Linux
ss -lntup

# Windows PowerShell
Get-NetTCPConnection -State Listen

解析エラーが起きやすい箇所

エラーに行番号が含まれる場合は、その行だけでなく上数行も確認してください。YAMLパーサーは処理を続けられなくなった時点でエラーを出すことが多く、実際の原因は前の行の閉じ忘れた引用符、コロンの後の空白不足、リストのインデント中断かもしれません。マッピングキーの重複が示されたら、同じ階層に同名フィールドがないか検索します。型が合わないと表示されたら、本来リストである場所からハイフンが抜けていないか、整数をオブジェクトとして書いていないか確認してください。

チャットアプリやリッチテキストからコピーした内容には、全角コロン、曲がった引用符、ノーブレークスペース、見えない文字が含まれることがあります。最も確実なのは、問題の行をプレーンテキストエディターで入力し直す方法です。日本語のプロキシグループ名は問題なく使えますが、句読点や区切りには通常の半角YAML記号を使用してください。コメントはシャープから始め、有効な値との間に適切な空白を置きます。

設定は解析できるのに対象が存在しないと表示される場合は、ノード名、プロバイダー名、プロキシグループ名、ルールセット名を確認します。よくある原因は、プロキシグループがサブスクリプション更新で改名されたノードを参照している、ルールが上書きで削除されたグループを指している、RULE-SET名とプロバイダーキーが一致していない、といったものです。名前を検索するときは引用符内の完全な文字列を対象にし、末尾の空白や似た文字にも注意してください。

ポート、システムプロキシ、TUNの分岐

クライアントは動作中と表示されるのにアプリがネットワークへ接続できない場合、まず待受ポートが存在するか確認し、次にシステムプロキシのアドレスを照合します。YAMLのmixed-portを新しい値へ変更したのに、システムプロキシが古い値を指していると、ブラウザーはすぐに接続に失敗します。システムプロキシに従わないアプリだけが取り込めない場合、基本のプロキシは正常で、ノードプロトコルを変更し続けるのではなくTUNの利用を検討すべき可能性があります。

TUNを有効にして完全にネットワークへ接続できなくなったら、権限、仮想NIC、ルート、DNSの取り込み、他のネットワークソフトとの競合を確認します。まずTUNを無効にし、システムプロキシ経路が機能することを確認してから、TUNだけを個別に調べてください。クライアントを終了しても接続できない場合は、システムプロキシが有効なまま残っていないか、仮想NICのルートが復元されているか確認します。同じテスト中に複数のプロキシクライアントを有効にしないでください。システムプロキシ、ポート、ルートを奪い合う可能性があります。

ノードの可用性とルールマッチを検証する

ノードテストに失敗したら、DNS名前解決の失敗、TCP接続タイムアウト、接続拒否、TLSハンドシェイク失敗、認証失敗を区別します。名前解決の失敗ではノードサーバーのドメインとproxy-server-nameserverを確認します。タイムアウトではネットワークとリモートアドレスを調べ、拒否なら対象ポートが接続を受け付けているか確認します。ハンドシェイク失敗ではシステム時刻、SNI、証明書を、認証失敗ではパスワード、ユーザー識別子、プロトコルフィールドを確認してください。異なるエラーを同じ方法で修復することはできません。

ノードテストは成功するのに対象サイトへ接続できない場合は、接続履歴でマッチしたルールとプロキシグループを確認します。DIRECTにマッチしているなら、問題はルール順またはモードにあります。想定したノードにマッチしているなら、対象ドメインの名前解決、ノードの出口、サイト側の制限を調べてください。一時的にグローバルモードへ切り替えると、ルールの問題かどうかを切り分けられますが、テスト後はルールモードへ戻します。グローバルモードでアクセスできても、元のルールが正しいとは限りません。プロキシ経路の1つが利用可能だと分かるだけです。

動作する最小設定を作る

複雑な設定の原因を特定できない場合は、ポート1つ、ノード1つ、手動プロキシグループ1つ、ルール2つから始めます。読み込みと接続を確認した後、DNS、自動プロキシグループ、ルールプロバイダー、TUNを順番に追加してください。各層を追加するたびに、動作するコピーを保存します。数千行のサブスクリプションで推測を繰り返すより速く、クライアントとコアが実際に対応するフィールドも明確になります。

最小設定のテストに使うノードは、必要な情報がすべて揃っていることを確認してください。テストドメインも安定している必要があります。最小設定でも失敗するなら、問題はルールセットではなく、ノード、システムネットワーク、権限、クライアントのインストールにある可能性が高いです。その場合は利用ガイドで初期設定を確認するか、サブスクリプション、モード、接続状態に関する10の質問を参照してください。再インストールが必要なら、ダウンロードセンターで対応プラットフォームを選びます。デスクトップ、モバイルともにClash Plusを優先して確認してください。

トラブル対処が終わったら、一時的に有効にしたdebugログ、広範なテストルール、証明書検証の変更を通常の設定へ戻します。使わなくなったポート、重複したプロキシグループ、無効なプロバイダーを削除し、カスタム部分には短いコメントを付けてください。設定を長期的に保守できるかどうかは、フィールド数ではなく、各モジュールの役割が明確かで決まります。各ルールの存在理由、各グループの参照先、各DNSリゾルバーの役割を説明できてこそ、継続的に更新できる設定になります。

動作する設定から次へ進む

まだクライアントをインストールしていない場合は、プラットフォームに合ったインストーラーを取得します。インストール済みで画面操作に慣れていない場合は、クイックスタートの手順に従ってサブスクリプションを読み込み、プロキシグループを選び、接続を確認してください。

ダウンロードセンターへ 利用ガイドを見る