Clash 設定ファイル YAML マニュアル

設定ファイルの構造概要

Clash 系クライアントの動作は、すべて YAML 形式の設定ファイルによって決まります。サブスクリプションリンクを導入すると、クライアントがサブスクリプション元から取得しているのも実質的にこのファイルであり、画面上でノードを切り替えたりモードを調整したりルールを追加削除したりする操作は、最終的にファイル内の対応する項目に反映されます。このファイルを読み解けば、クライアントの画面操作の裏側が理解できます。

ファイルは通常 config.yaml という名前で、クライアントの設定ディレクトリに置かれます。Clash Plus、Clash Verge Rev、FlClash などの GUI クライアントは、このファイルの読み書きを代行します。サブスクリプション導入時に生成され、設定変更時に書き換えられます。手動で編集する前にはクライアントを終了するか、そのクライアントの上書き方式を確認しておくことを推奨します。そうしないと、手動で編集した内容が画面操作によってまるごと上書きされる可能性があります。上書き機構の詳細は本ページの第8章で説明します。

トップレベル項目の一覧

完全な設定ファイルのトップレベルは複数の項目が並列に並んでおり、項目間に依存関係はなく、記述順序は解析結果に影響しません。よく使う項目とその役割は以下の通りです。

最小限の設定に必要なのは3種類のみです:リスニングポート、少なくとも1つのノード、少なくとも1件のルール。他の項目にはすべて既定値があり、省略時はカーネルが既定の動作で稼働します。サブスクリプション変換サービスが生成する設定は項目が揃っていることが多いので、手動で簡略化する場合は主要部分だけ残せば十分で、すべてをそのまま模倣する必要はありません。

YAML 構文の4つの原則

YAML の解析規則は厳格で、「設定が起動しない」問題の大半は内容ではなく書式に起因します。記述時は以下の4原則を守ってください。

• インデントはスペースのみを使い、Tab は使わない。同一階層のインデント幅は統一し、慣例として2文字幅が一般的。
• キーと値の間は半角コロンと半角スペース1つで区切り、key: value のように書く。コロンの後のスペース漏れは頻出のミス。
• リスト項目は半角ハイフンとスペースで始める。ハイフンを行頭に置くかインデントするかは自由だが、同一ファイル内では書式を統一する。
• 値にコロン・シャープ・波括弧などの特殊文字が含まれる場合は、値全体を英字の二重引用符で囲む。パスワードやトークン系の項目は常に引用符で囲むことを推奨。

config.yaml · 最小構成

mixed-port: 7890
mode: rule
log-level: info

proxies:
  - name: "ノードA"
    type: ss
    server: ss.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"

rules:
  - MATCH,ノードA

この構成はわずか9行ですが、これだけで起動可能な設定になっています。ローカルの7890ポートがプロキシ要求を受け付け、すべての通信が唯一のノードを経由して転送されます。実際のサブスクリプション設定はこの構成をベースにノード・ポリシーグループ・ルールを拡張したものであり、基本構造は変わりません。以降の章で各部分の項目を順に解説していきます。

共通項目:ポート、モード、スイッチ

トップレベルの共通項目は、カーネルの全体的な動作を制御します。どのポートで要求を受け付けるか、どの方式で振り分けるか、ログをどの程度出力するか、LAN 共有を許可するかなどです。GUI クライアントの多くはこれらの項目を設定画面のスイッチに対応させているため、手動で記述する場合は本節を参照してください。

リスニングポート

port は HTTP プロキシポート、socks-port は SOCKS5 ポート、mixed-port は混合ポートで、同一の入口が HTTP と SOCKS5 の両方の接続を受け付けます。現在のクライアントはほとんどが混合ポートのみを公開し、システムプロキシやブラウザ拡張はこのポートを指定します。3つの項目は共存できますが、ポートが重複しないようにしてください。不要な入口は行ごと省略すれば、カーネルはそのポートを監視しません。

redir-port と tproxy-port は Linux の透過プロキシ用で、iptables による転送と組み合わせて使います。デスクトップ利用では通常不要で、ルーターやゲートウェイ用途で有効化されます。関連する導入手順は Linux コマンドライン導入 の記事を参照してください。

動作モード

mode は3つの値のいずれかを取ります:rule はルールリストに従って振り分ける通常モード、global はすべての通信を GLOBAL という名前の内蔵ポリシーグループに委ねる、画面上の「グローバルモード」に相当します。direct はすべて直結、つまりプロキシを一時停止した状態と同じです。画面上でモードを切り替える操作は、この項目を書き換えて再読み込みするだけであり、設定ファイル内の初期値が起動時ごとの既定モードを決めます。

ログと外部コントロール

log-level は静かな順に silent、error、warning、info、debug です。通常は warning か info を使用し、ルールのマッチ状況を調査する際は一時的に debug に変更すると、各接続のマッチ過程と結果を確認できます。

external-controller は外部コントロールインターフェースのリスニングアドレスを指定し、GUI クライアントの接続パネル・遅延テスト・設定の再読み込みはすべてこのインターフェース経由で行われます。external-ui は静的パネルファイル群を指すもので、ブラウザで対応するアドレスを開けばカーネルを直接管理できます。secret はインターフェースのアクセスキーで、空の場合は検証されません。

LAN 共有とその他のスイッチ

allow-lan を true にすると、同一 LAN 内の他デバイスが本機をプロキシゲートウェイとして利用できます。bind-address は監視するネットワークインターフェースを指定し、既定の * は全インターフェースを意味します。その他よく使うスイッチ:ipv6 は IPv6 の解析・転送を制御、unified-delay は遅延テストをハンドシェイク完了時点で統一計測し、プロトコル間の測定結果を比較可能にします。tcp-concurrent は候補ノードへ同時に接続し最速のものを採用、profile.store-selected は各ポリシーグループの手動選択を保持し、再起動時に既定ノードへ戻らないようにします。

config.yaml · 共通項目の例

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: warning
ipv6: false
external-controller: 127.0.0.1:9090
secret: ""
unified-delay: true
tcp-concurrent: true
profile:
  store-selected: true
  store-fake-ip: false

DNS 項目:解析動作とアップストリーム

振り分けルールはドメインと IP の対応関係に依存するため、DNS 設定はいつ・どのアップストリームでドメインを解析するかを決め、ルールが正しくマッチするための前提となります。設定が不適切な場合の典型的な症状は、代理すべきサイトが直結と判定される、またはページを開く前に明らかな遅延が発生するといったものです。

基本スイッチ

dns.enable はこのセクション全体の総スイッチで、既定は false です。この場合、カーネルはドメイン解析をシステムに委ね、本節の他の項目はすべて無効になります。listen は内蔵 DNS サービスのリスニングアドレスを指定し、TUN モードやシステム DNS を本機に向ける場合に使用します。ipv6 は AAAA クエリに応答するかどうかを制御します。

解析モード:fake-ip と redir-host

enhanced-mode は fake-ip か redir-host を取ります。fake-ip モードでは、カーネルはドメインクエリを受け取ると直接 fake-ip-range 範囲内(既定 198.18.0.1/16)の仮想アドレスを返し、アプリケーションはこの仮想アドレスで接続を開始します。カーネルは接続が来た時点でテーブルを引いてドメインを復元し、ルールに従って振り分けたうえで実際の IP を解析します。この方式によりアプリ側の解析待ちが省け、システム DNS の汚染された結果が振り分けを誤らせることも避けられます。redir-host は従来型のモードで、先にプロキシ側で実際の IP を解析してからアプリに渡すため、互換性は最も高いものの速度はやや遅くなります。

fake-ip-filter には仮想アドレスを返すべきでないドメインを列挙します。該当ドメインは実解析されます。LAN 内のドメイン、時刻サーバー、実際の IP によるサービス発見が必要なプロトコルなどは列挙しておくべきで、そうしないと LAN デバイスが見つからない、システム時刻が同期できないといった不具合が起きます。

アップストリームサーバー

default-nameserver は「DNS サーバー自身のドメイン名」を解析する役割を担います。たとえば上流を dns.alidns.com のようなドメイン形式で書く場合、まず純粋な IP のアップストリームでそれを解析する必要があるため、この層は IP を記入する必要があります。nameserver はメインのアップストリームリストで、UDP・TLS・HTTPS の3種類の書式に対応します。fallback は補助アップストリームで、代理経由での解析が必要と判定された場合に使用されます。nameserver-policy はドメインまたは GEOSITE 分類ごとに専用のアップストリームを指定するもので、たとえば日本国内のドメインを固定でプロバイダの DNS に、特定サービスを暗号化アップストリームに振るなど、fallback より細かい粒度で制御できます。

config.yaml · DNS セクションの例

dns:
  enable: true
  listen: 0.0.0.0:53
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "ntp.*.com"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
    - tls://8.8.4.4

プロキシノードの項目

proxies はノードのリストで、リスト内の各項目が1つの出口ノードを表します。どのプロトコルでも共通する必須4項目は name(ノード名)、type(プロトコル種別)、server(サーバーアドレス)、port(サーバーポート)です。その他の項目はプロトコルによって異なります。サブスクリプション導入時のノードはサブスクリプション提供者側で生成済みのため、手動で扱う場面は主に予備ノードの追加や個別項目の微調整です。

共通項目

name は設定ファイル全体で一意である必要があります。ポリシーグループは名前でノードを参照するため、名前の重複は参照結果を不定にします。udp はそのノードが UDP 通信を転送するかどうかを制御し、音声通話・一部のゲーム・QUIC プロトコルはこれに依存します。sni は TLS ハンドシェイク時に宣言するドメインを指定し、多くのノードでノードのドメインと一致させる必要があります。skip-cert-verify を true にすると証明書検証をスキップしますが、自己署名証明書のテスト環境でのみ使用すべきです。alpn と client-fingerprint は TLS フィンガープリントを微調整し、dialer-proxy は前置ノードを指定して、本ノードを別のノードの後段に連結する多段中継を構成します。

各プロトコルの記述方法

config.yaml · 4種類のプロトコルのノード例

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

  - name: "VMess ノード"
    type: vmess
    server: vm.example.com
    port: 443
    uuid: 00000000-0000-0000-0000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    servername: vm.example.com
    network: ws
    ws-opts:
      path: /ray
      headers:
        Host: vm.example.com

  - name: "Trojan ノード"
    type: trojan
    server: tj.example.com
    port: 443
    password: "your-password"
    sni: tj.example.com
    skip-cert-verify: false

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

各プロトコルの必須項目と拡張項目には差異が大きいため、下表に主要プロトコルのチェックリストをまとめました。項目名のスペルミスがある場合、カーネルは起動時の検証段階で具体的な行番号を出力します。エラーの特定方法は第9章を参照してください。

サブスクリプション導入後にノード項目を確認したい場合は、クライアントの設定プレビューで解析結果を確認できます。トランスポート層(network)、TLS スイッチ、SNI が揃っているかが、起動検証を通過できるかを左右します。手動でノードを追加する場合は、まず必須項目だけで接続を確認し、その後拡張項目を1つずつ補完すると、問題発生時の調査範囲が大幅に狭まります。

ポリシーグループの項目

proxy-groups はノードを選択可能な集合としてまとめるものです。振り分けルールの対象は通常ノード名ではなくポリシーグループ名を指定します。ルールが決めるのは「通信をどのグループに渡すか」、グループが決めるのは「グループ内でどのノードを現在使うか」です。この2層を分離することで、ノードを変えてもルールを変更せずに済み、ルールを変えてもノードを変更せずに済みます。

グループ種別と選択方式

速度測定の項目

url-test、fallback、load-balance の3種類のグループはヘルスチェックに依存します。url は測定先アドレスで、既定は http://www.gstatic.com/generate_204。204 が返れば利用可能と判定されます。interval は測定間隔(秒)で、短すぎるとノードの通信量を無駄に消費します。tolerance は遅延許容差(ミリ秒)で、新旧の最適値の差がこの値未満なら切り替えを行わず、ノードが頻繁に切り替わることを防ぎます。lazy を true にすると、グループ内に接続がない間は測定を停止します。複数の予備系統を並べる構成に適しています。

グループメンバーの指定元

proxies 項目にメンバー名を直接列挙します。ノード名でも、別のポリシーグループ名でも構いません(グループは入れ子にできます)。画面上の「ノード選択」グループの中に「自動選択」グループを入れる構成は一般的です。use 項目は proxy-providers で宣言したサブスクリプションを参照し、サブスクリプション内の全ノードをグループに取り込みます。filter の正規表現と組み合わせて名前が一致するノードだけを残し、exclude-filter は逆に除外します。

config.yaml · ポリシーグループの例

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "自動選択"
      - "手動ノードA"
      - "手動ノードB"
      - DIRECT

  - name: "自動選択"
    type: url-test
    use:
      - mysub
    filter: "香港|台湾"
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true

  - name: "広告ブロック"
    type: select
    proxies:
      - REJECT
      - DIRECT

DIRECT と REJECT はカーネルに内蔵された2つの出口で、proxies で定義する必要はありません。DIRECT は直結、REJECT は接続を直接拒否することを意味し、広告・トラッキングドメインのブロックによく使われます。

グループを入れ子にした場合、画面に表示されるのは最も外側のグループで、内側のグループの現在の選択が外側のグループのメンバーの1つとして表示されます。「自動選択」を PROXY の中に組み込んでおけば、通常は PROXY 内でそれを選択したままにしておくだけで、測定と切り替えは内側のグループが自動で行います。特定のノードを指定したい場合は外側で一時的に選択を変えるだけで済み、ルールリストは一切変更不要です。

ルール構文とマッチング順序

rules は振り分けの核心部分です。接続が確立されるたびに、カーネルはリストの先頭から順に比較し、マッチした時点でそのルールが指定するポリシーグループへ出口を振り分け、以降の比較は行いません。すべてマッチしなかった場合は最後の MATCH がフォールバックとして機能します。順序がそのまま優先度であり、ルールを書く作業の半分は順序の調整に費やされます。

ルールの3段構成

1件のルールはコンマで3段に区切られます:タイプ、マッチ内容、目的のポリシーグループ。例:DOMAIN-SUFFIX,example.com,PROXY。IP 系のルールには4段目に no-resolve を追加できます。既定では、ドメインで接続する通信を IP ルールと比較する際に先に解析が発生してしまいますが、no-resolve を付けた IP ルールは元々 IP である接続だけにマッチし、そのために解析を行いません。DNS リクエストを節約でき、解析結果が振り分けを乱すことも防げます。GEOIP と IP-CIDR のルールには慣例としてこのサフィックスを付けます。

ルールタイプ一覧

並び順が持つ実践的な意味

例外的なルールは範囲の広いルールより前に書きます。あるサイトを強制的に直結させたい場合、その DOMAIN-SUFFIX は GEOSITE や GEOIP のような広範囲の項目より上に置く必要があります。そうしないと、そこに到達する前に前段の項目に通信を奪われてしまいます。範囲が狭いルールほど前に、範囲が広いルールほど後に置き、MATCH は常に最後です。プロセス系のルールはシステムのプロセス情報に依存するため、Windows デスクトップ版では使えますが、モバイル端末のカーネルは通常プロセス名を取得できず、記述してもマッチしません。

config.yaml · ルールリストの例

rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - RULE-SET,ads,REJECT
  - GEOSITE,private,DIRECT
  - GEOSITE,google,PROXY
  - GEOSITE,cn,DIRECT
  - GEOIP,private,DIRECT,no-resolve
  - GEOIP,CN,DIRECT,no-resolve
  - MATCH,PROXY

プロバイダー設定:サブスクリプションとルールセット

ノードもルールも、メインの設定から切り離して「プロバイダー」に管理を委ねることができます。メインの設定は取得元と更新方式だけを宣言し、内容はクライアントが定期的に取得します。サブスクリプションリンク導入後に生成されるのはまさに proxy-providers の項目であり、ルールセットは数千数万件の振り分けルールを1回の参照に圧縮します。

proxy-providers:サブスクリプション元

各サブスクリプションは名前付きの項目です。type は http(リモート取得)か file(ローカルファイル)を取ります。url はサブスクリプションアドレス、path はローカルキャッシュのパスで、ネット切断時にはキャッシュから起動します。interval は自動更新間隔(秒)です。health-check 子項目はサブスクリプション全体のノードに対して統一的に速度測定を有効化し、項目はポリシーグループの速度測定項目と同じです。override 子項目でサブスクリプション内のノード項目を一括で書き換えられます。例えば UDP を強制的に有効化するなどです。

rule-providers:ルールセット元

ルールセットの重要な項目は behavior です。domain は項目がドメインサフィックスでマッチすることを表し、ipcidr は IP 帯でマッチすることを、classical は項目自体が完全なルール(タイプ接頭辞付き)であることを表します。前者2つはカーネルが専用の索引を構築するためマッチが非常に高速ですが、ファイルには純粋なドメインまたは IP 帯のリストしか書けません。format は yaml と text の2種類のファイル形式に対応します。

config.yaml · プロバイダーの例

proxy-providers:
  mysub:
    type: http
    url: "https://example.com/sub?token=xxxx"
    path: ./providers/mysub.yaml
    interval: 86400
    health-check:
      enable: true
      url: http://www.gstatic.com/generate_204
      interval: 300

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

宣言した後は参照して初めて有効になります。ポリシーグループでは use: [mysub] でサブスクリプションのノードを取り込み、ルールリストでは RULE-SET,ads,REJECT でルールセットを紐付けます。サブスクリプションリンクの取得と形式変換については サブスクリプション導入に関する記事 を参照してください。

インライン記述とプロバイダー方式は併用できます。proxies で1〜2個の予備ノードを手動で管理し、proxy-providers でサブスクリプションの大量のノードを管理し、ポリシーグループには両方を含めます。サブスクリプションの更新はプロバイダー項目にのみ影響し、手動ノードは影響を受けません。これは「すべてを proxies に書く」よりも安定した構成方法です。

上書きと統合

サブスクリプションの更新は本質的に丸ごとの置き換えです。クライアントが新しい設定を取得すると、古いファイルは手動での変更ごと上書きされます。長期的に自分の変更を保持するには2つの方法があります。クライアントが提供する上書き機構で変更を「パッチ」として扱う方法、または YAML のアンカー構文で重複を減らして保守コストを下げる方法です。

クライアントの上書き機構

主要な GUI クライアントはいずれも「サブスクリプション本体」と「ユーザーの変更」を別レイヤーで保存します。Clash Verge Rev はグローバル拡張設定(Merge)とスクリプトという2つの上書き手段を提供し、前者は項目単位で統合、後者は JavaScript で自由に書き換えます。FlClash は上書きページで任意の項目を追加・変更・削除できます。Clash Plus は画面上の設定とサブスクリプション設定を別々に保存し、サブスクリプション更新時に設定項目は自動的に保持されます。共通点は、サブスクリプションファイルはそのまま保ち、ユーザーの変更はパッチとして重ね合わされ、更新のたびに再適用される点です。

注意すべきは、統合の意味づけがクライアントによって異なることです。スカラー項目(ポート、モード)は常にパッチが優先されますが、配列項目(rules、proxies)はクライアントによって項目単位で統合するもの、丸ごと置き換えるもの、前挿入・後挿入に対応するものがあります。変更が反映された後は、クライアントが最終的に生成する実行時設定を書き出して対象項目を確認するのが最も確実な方法で、上書きページのパッチ文面だけを見るのでは不十分です。

YAML アンカーと参照

手動で設定を書く場合、アンカーは重複を排除できます。値の前に &名前 を書いてアンカーを定義し、以降 *名前 でそのまま参照します。マッピング型では <<: *名前 でアンカーのキーと値をまとめて取り込むこともできます。複数のポリシーグループが同じノードリストや同じ測定パラメータを共有する場合、アンカーを使えば設定を1つの真の源として保持でき、1箇所を変更すればすべてに反映されます。

config.yaml · アンカー再利用の例

proxy-groups:
  - name: "自動選択"
    type: url-test
    url: &test-url http://www.gstatic.com/generate_204
    interval: &test-interval 300
    proxies: &all-nodes
      - "ノードA"
      - "ノードB"
      - "ノードC"

  - name: "予備系統"
    type: fallback
    url: *test-url
    interval: *test-interval
    proxies: *all-nodes

検証とトラブルシュート

設定の問題は主に3種類に集約されます:YAML の書式エラー、項目参照のエラー、ルールのロジックが期待と異なる、というものです。本節の順序で調べていけば、大半の問題は数分以内に特定できます。

起動前の検証

mihomo カーネルには設定チェック機能が内蔵されており、起動しなくても検証できます。

ターミナル · 設定検証コマンド

mihomo -t -d /path/to/config-dir

configuration ok と出力されれば構文と項目のチェックを通過したことを意味します。失敗した場合はエラーに行番号と項目名が含まれるので、該当する章に戻って確認してください。GUI クライアントも設定の導入や保存時に同様の検証を行い、エラーダイアログの文言はコマンドラインと同じです。

よくあるエラー対照表

再起動せずに変更を反映する

GUI クライアントは設定を保存するだけで再読み込みがトリガーされ、カーネルの再起動は不要です。コマンドライン環境では外部コントロールインターフェースにリクエストを送れます。/configs?force=true に新しい設定パスを添えて PUT を送れば全体を再読み込みできます。fake-ip キャッシュによる解析結果の残留は、対応するキャッシュクリア用インターフェースを呼んでから再試行してください。ルールのマッチが期待と異なる場合は、log-level を一時的に debug にすると、ログが各接続がマッチしたルールの番号を逐次出力するので、その番号を rules リストと照合すれば、どのルールが通信を横取りしたのかが分かります。

設定以外の問題——サブスクリプション導入の失敗、システムプロキシが効かない、起動時の自動起動など——は 初心者向けQ&A でひとつずつ回答しています。導入の主な手順は 使用ガイド、クライアントの入手は ダウンロードページ を参照してください。