Clash 設定ファイル リファレンスマニュアル

一、YAML構造の全体像

Clash のすべての動作は YAML 形式の設定ファイルによって駆動されます。クライアント画面上のすべてのスイッチ、すべてのポリシーグループ、すべての振り分けルールは、最終的にこのファイル内のいずれかの項目に対応しています。全体構造を理解することは、以降のすべての変更作業の前提です。ある項目がどのセクションに属するかを把握していれば、変更が何に影響するのか、サブスクリプション更新で上書きされてしまうのかが分かります。

完全な設定は最上位にいくつかの固定名のセクションで構成され、カーネルは名前で識別するため順序は解析に影響しません。よく使われるセクションは以下の通りです。

• 共通項目:最上位に散らばるスカラー設定。mixed-port、mode、log-level など、ポート・プロキシモード・実行パラメータを制御;
• dns:ドメイン名解決の動作。内蔵DNSの有効化、Fake-IPモード、上流サーバー一覧など;
• proxies:プロキシノードの配列。各エントリが1台の出口サーバーのプロトコル・アドレス・認証情報を記述;
• proxy-groups:ポリシーグループの配列。ノードを選択可能・自動速度測定可能なグループにまとめる;
• rules:振り分けルールの配列。各接続をどのポリシーグループに流すか、または直接接続するかを決定;
• proxy-providers / rule-providers:外部アドレスやローカルファイルからノードとルールセットを取り込み、分割管理しやすくする;
• tun:仮想ネットワークアダプタモード。システム全体のトラフィックを引き受ける際に使用。

動作する最小限の設定は3セクションだけで十分です。入り口ポートが1つ、ノードが最低1つ(または直接 DIRECT を使う)、兜底ルールが1つ。以下の骨組みはそのまま config.yaml として保存して検証できます。

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

proxies: []

proxy-groups: []

rules:
  - MATCH,DIRECT

YAML にはいくつかの厳格な記法規則があり、設定解析失敗の原因の多くはここにあります。第一に、階層は完全にインデントで表現され、同じ階層のインデント幅は統一しなければならず、慣例として半角スペース2つを使います。第二に、コロンの後には必ず半角スペースが必要で、mode:rule という書き方は無効です。第三に、フィールド名は大文字小文字を区別し、Mode は mode として認識されません。第四に、文字列は通常引用符なしで記述できますが、コロン・シャープ・アスタリスクなどの特殊文字を含む場合は必ず引用符で囲みます。例えばパスワード "p@ss:word#1" のように。

設定ファイルの保存場所や、サブスクリプション更新時にどのセクションが丸ごと置き換えられるかについては、サイト内記事『Clash 設定ファイル(Profile)構造解説』を参照してください。本ページの第八章でも、ローカルでの変更を更新後も維持するための統合方法を紹介します。

二、共通項目:ポート、モードと実行制御

共通項目は設定の最上位に直接記述され、カーネルがどのような姿勢で動作するかを制御します。数は多くありませんが、ほぼすべてのトラブル対処でまずこのセクションを確認することになります――ポートの競合、モードの選択ミス、LAN内デバイスが接続できないといった問題の根本原因は、たいていここにあります。

2.1 入り口ポート

カーネルは複数種類の入り口リスニングを同時に開くことができます。port は純粋な HTTP プロキシポート、socks-port は純粋な SOCKS5 ポート、そして mixed-port は同じポート上で HTTP と SOCKS5 の両リクエストを識別でき、現在多くのクライアントの既定選択となっています――システムプロキシもサードパーティソフトも同じポートを指定すればよく、設定が最も簡単です。3つは併存可能ですが、リスニングポート番号は重複できず、システム上の他のプログラムが使用しているポートと衝突してもいけません。起動時に bind: address already in use が出た場合はポートが占有されているので、未使用のポート番号に変更してください。

2.2 LAN アクセス

allow-lan は入り口ポートが自機以外からの接続を受け付けるかどうかを決めます。true に設定すると、同じLAN内のスマートフォンやTVボックスがプロキシサーバーをこの端末のプライベートIPに向けることで、同じ出口とルールを共有できます。bind-address と組み合わせることで、特定のネットワークアダプタに限定してリスニングすることも可能です。有効化する前にネットワーク環境を確認してください――会社や公共Wi-Fi上でLANリスニングを開放すると、同一セグメント内の任意のデバイスがこのプロキシポートを使用できてしまいます。

2.3 プロキシモード mode

mode は3つの値を受け付けます:rule(ルールセクションに従って一件ずつマッチングして振り分け)、global(すべてのトラフィックをグローバル出口に渡す)、direct(すべてのトラフィックを直接接続)。通常時は rule に固定しておくべきで、残り2つのモードはトラブル対処用のツールであり常用の選択肢ではありません――いつ一時的に切り替え、切り替え後どう確認するかについては、サイト内記事『Clash の3つのプロキシモードの選び方』に完全な操作手順が記載されています。

2.4 よく使う共通項目一覧

external-controller は特に説明する価値があります。これは HTTP インターフェースを開放するもので、クライアントのグラフィカルインターフェースはまさにこのインターフェースを通じてノードを切り替え、遅延やトラフィックデータを読み取っています。既定では 127.0.0.1:9090 にバインドされ自機のみに開放されます。0.0.0.0:9090 に変更してLAN内のパネルからアクセス可能にする場合は、必ず secret も同時に設定してください。そうしないと同一セグメント内のデバイスが直接カーネルを操作できてしまいます。

2.5 TUN セクション概観

システムプロキシはプロキシ設定に従うアプリケーションにのみ有効で、コマンドラインツール、ゲーム、一部のクライアントソフトはそれを回避してしまいます。tun セクションは仮想ネットワークアダプタを作成することでネットワーク層でトラフィックを丸ごと引き受け、「プロキシを設定したのに一部のプログラムが経由しない」問題を解決します。

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

stack はプロトコルスタックの実装(system / gvisor / mixed)を指定します。互換性の問題がある場合は複数の値を切り替えて比較できます。auto-route は自動でシステムのルーティングテーブルに書き込みます。dns-hijack は53番ポート宛の平文DNSクエリを内蔵DNSにハイジャックし、次章の設定と組み合わせて解析の回避を防ぎます。TUN を有効化するには管理者または root 権限が必要で、各クライアントが対応するシステムサービスのインストールを案内します。

三、DNSセクション:解決動作とFake-IP

プロキシ環境において DNS は最も見落とされがちな部分です――ドメイン名解決が依然としてローカルISPの平文53番ポートを経由している場合、トラフィック自体はプロキシを経由していても、どのドメインにアクセスしたかはローカルの経路上に露出したままになり、一部のドメインは汚染されたアドレスに解決されて接続失敗を招くこともあります。dns セクションの役割は、カーネルに解決プロセスを引き受けさせ、「誰が解決するか、どう解決するか、解決結果をどう使うか」を統一的に決定することです。

3.1 基本スイッチとリスニング

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16

enable: true は内蔵DNSモジュールを有効化します。listen は通常のDNSサーバーとしても外部に解決を提供させるもので、主にTUNの dns-hijack やルーター環境と組み合わせて使用します。enhanced-mode はこのセクションの中核となる選択で、解決結果の提示方式を決定します。

3.2 Fake-IP と Redir-Host

fake-ip モードでは、カーネルは実際の解決が完了するのを待たず、直ちに fake-ip-range の予約セグメント(既定 198.18.0.1/16)から仮想アドレスを1つ割り当ててアプリケーションに返し、同時に「この仮想アドレスがどのドメインに対応するか」を記憶します。アプリケーションが仮想アドレスを使って接続を開始すると、カーネルはIPではなくドメイン名でルールをマッチングして転送します。利点は解決の往復を1回省けること、初回パケットの遅延を大幅に下げられること、そしてルールマッチングが常にドメイン名ベースなので精度が高いことです。redir-host は実際の解決結果を返すもので、従来のDNSに近い挙動をとり、互換性は良いものの速度とマッチング精度はやや劣ります。この2つのモードの仕組みの違いや、LAN内サービスやゲームのオンライン対戦などFake-IPを避けるべき場面については、サイト内記事『Clash Fake-IP モードの動作原理』で詳しく解説しています。

Fake-IPを使用する場合、実際のIPを取得しなければならない一部のクエリは fake-ip-filter で除外する必要があります。典型的なものはLAN内のホスト名、システムの接続検出用ドメイン、NTPサービスです。

  fake-ip-filter:
    - "*.lan"
    - "+.local"
    - "+.msftconnecttest.com"
    - "+.pool.ntp.org"

ここで * は単一階層のサブドメインにマッチし、+ は任意の階層のサブドメイン(ドメイン自体を含む)にマッチします。

3.3 上流サーバーの3層構造

  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

3つのサーバー群は役割が異なり、混同してはいけません。default-nameserver には純粋なIPアドレスのみ記述でき、後続2つの暗号化DNSサーバー自体のドメイン名を解決するために専用に使われ、「鶏が先か卵が先か」の問題を解決します。nameserver は主力の解決グループで、DoH(https:// プレフィックス)やDoT(tls:// プレフィックス)などの暗号化プロトコルの使用が推奨されます。fallback は補助グループで、fallback-filter と連動します――主力グループの解決結果がフィルタ条件に合致した場合(例えば geoip-code: CN 以外の結果)、補助グループの回答に切り替えて汚染に対抗します。この二重クエリの仕組みが不要であれば、nameserver のみを残しても構いません。

四、プロキシノード項目(proxies)

proxies は配列で、各エントリが1つの出口ノードを完全に記述します。サブスクリプション設定ではこのセクションはサービス提供者側で生成され、通常は手書きする必要はありません。しかし自前ノードの構築、サブスクリプションへの独自出口の追加、あるいは「あるノードがなぜ接続できないか」を照らし合わせて調べる際には、各項目の意味を理解しておく必要があります。

4.1 すべてのプロトコルに共通する項目

どのプロトコルであっても、4つの項目は必須です:name(ノード名。ポリシーグループがこれを参照するため、同一設定内で重複不可)、type(プロトコル種別)、server(サーバーのドメイン名またはIP)、port(サーバーポート)。さらに udp: true はそのノードがUDP転送に対応していることを示し、音声通話やゲームなどUDPに依存するアプリケーションで必要になります。

4.2 3つの一般的なプロトコル例

proxies:
  - name: "HK-01"
    type: ss
    server: hk01.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

  - name: "JP-01"
    type: vmess
    server: jp01.example.com
    port: 443
    uuid: 0f7b7c4e-3a52-4e70-9d2b-1c8a5f6e0d43
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ws
      headers:
        Host: jp01.example.com

  - name: "US-01"
    type: trojan
    server: us01.example.com
    port: 443
    password: "your-password"
    sni: us01.example.com
    udp: true

Shadowsocks(ss)のキー項目は暗号化方式を示す cipher と password で、両端で完全に一致させる必要があります。VMess は uuid を認証情報として使用し、alterId は現行のプロトコルでは 0 に固定します。network はトランスポート層(ws、grpc、http など)を宣言し、選んだトランスポート層に応じて対応する *-opts サブセクションを設定します。サンプル中の ws-opts はWebSocketのパスとHostヘッダーを指定しています。Trojan はもともとTLS上で動作し、sni はハンドシェイク時に宣言するサーバー名を指定します。サーバー証明書と一致しない場合は接続が即座に失敗します。

mihomo カーネルはこの3種類以外にも vless、hysteria2、tuic、wireguard などのプロトコルに対応しており、項目構造は同様のパターンに従います――共通の4項目にプロトコル固有の項目を加えたものです。新しいプロトコルのノードを入手したら、まず type の表記がカーネルの対応リストと一致しているか確認し、それからプロトコルが要求する認証情報の項目を1つずつ補ってください。

五、ポリシーグループ項目(proxy-groups)

proxies が原材料だとすれば、proxy-groups はその原材料を「判断可能な単位」にまとめる層です。ルールセクションの出口はほとんど常にポリシーグループを指し、単一ノードを直接指すことはありません――こうしておけばノードを変更する際にグループ内で切り替えるだけで済み、ルールを変更する必要がなくなります。クライアントのメイン画面にあるグループ選択リストは、まさにこのセクションを可視化したものです。

5.1 4種類のグループタイプ

5.2 完全なサンプルとパラメータ説明

proxy-groups:
  - name: "ノード選択"
    type: select
    proxies:
      - 自動速度テスト
      - HK-01
      - JP-01
      - US-01
      - DIRECT

  - name: "自動速度テスト"
    type: url-test
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true
    proxies:
      - HK-01
      - JP-01
      - US-01

自動系グループの3つのパラメータは体験に直結します。url は速度測定の対象で、慣例として204ステータスコードを返す軽量なアドレスを使い、「このノードを経由してこのアドレスにアクセスする」完全な往復時間を測定します。interval は速度測定の間隔(秒)で、短すぎると探測トラフィックが大量に発生します。tolerance は切り替えの許容差(ミリ秒)――新しい最速ノードが現在のノードよりこの差分以上速くなければ切り替えません。これは遅延が近い2つのノードが交互に切り替わり続けるのを防ぐためのものです。lazy: true はグループが使用されていない間は速度測定を一時停止し、バックグラウンドの負荷を減らします。

グループはグループを参照できます。サンプル中の「ノード選択」は「自動速度テスト」を最初の選択肢として持ち、「上位は手動、下位は自動」という2層構造を形成しています。サブスクリプション設定でよく見る「香港」「日本」などの地域グループを1つの総合グループにまとめるのも、同様のネストです。2つの予約名はどのグループにも直接記述できます:DIRECT は直接接続を表し、REJECT は接続拒否を表します(広告ブロックルールの出口としてよく使われます)。注意すべきは、グループとノードは同じ名前空間を共有するため、グループ名はノード名と重複できず、循環参照も構成できません――AグループがBグループを含み、BグループがまたAグループを含む場合、読み込みに失敗します。

六、ルール構文(rules)

rules セクションは各接続の行き先を決定するもので、設定全体の中で最も自分の手でメンテナンスする価値がある部分です。各ルールはカンマ区切りの1行のテキストで、基本形は「タイプ,マッチ値,出口」です。出口にはポリシーグループ名、ノード名、または DIRECT / REJECT を記述します。

6.1 マッチング順序:上から下へ、最初に命中したら停止

カーネルは新しい接続ごとに、最初のルールから順に試行し、命中したらそのルールの出口を採用して、以降のルールは参照されません。この仕組みからルール編成のすべての原則が導かれます――精確なルールを前に、広範なルールを後に、兜底ルールを最後に置くこと。GEOIP,CN,DIRECT が特定ドメインへのプロキシルールより前に置かれ、そのドメインがたまたま中国本土のIPに解決される場合、後ろのドメインルールは永久に有効になりません――「ルールを書いたはずなのに効かない」という問題の大半は順序の問題です。

6.2 よく使うルールタイプ

DOMAIN-SUFFIX,example.com は example.com と a.b.example.com の両方に命中し、1つのサイトをカバーする際に最もよく使われるタイプです。DOMAIN-KEYWORD は範囲が最も広く誤爆しやすいため、キーワードが十分に独特であることを確認できた場合のみ使用してください。IP系ルール末尾の no-resolve パラメータの意味は「現在の接続の宛先がドメイン名であってIPでない場合、このルールをスキップし、マッチさせるために解決を発生させない」ということです――LAN内のセグメントルールに付けておくと、すべてのドメイン名接続が先に解決されてからマッチング処理が遅延するのを避けられます。

6.3 そのまま使える編成例

rules:
  - PROCESS-NAME,steam.exe,DIRECT
  - DOMAIN,dl.example.com,DIRECT
  - DOMAIN-SUFFIX,openai.com,ノード選択
  - DOMAIN-KEYWORD,github,ノード選択
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,ノード選択

この編成は推奨される階層構造を示しています:プロセスと精確なドメインルールを最初に、業務ドメインルールをその次に、LAN内セグメントと地理的位置による直接接続を後方に、MATCH で兜底として締めます。MATCH より後のルールはすべてデッドコードとなり、カーネルはエラーを出しませんが永久に実行されません。設定の自己点検時には、これを「ルールセクションの終了マーカー」として扱ってください。カスタムルールを書いた後にどう命中状況を検証するかは、第九章のログを使った方法を参照。

七、外部リソース:proxy-providers と rule-providers

ノードが複数のサブスクリプションから来ていたり、ルールの件数が数百から数千に達する場合、すべてを1つのYAMLに積み上げると急速に保守不能になります。Providerの仕組みは、ノード一覧とルールセットを独立したファイルに分割し、カーネルが周期的に自動で取得・更新できるようにするもので、メイン設定には参照関係だけを残せます。

7.1 proxy-providers:ノードの取得元とヘルスチェック

proxy-providers:
  main-sub:
    type: http
    url: "https://example.com/subscribe/token"
    path: ./providers/main-sub.yaml
    interval: 86400
    health-check:
      enable: true
      url: http://www.gstatic.com/generate_204
      interval: 600

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

type: http はリモートアドレスから取得することを示し、path はローカルキャッシュのパス(取得失敗時はキャッシュを使い続け、オフラインでの起動を保証)、interval は自動更新の周期(秒)です。health-check はカーネルにこの取得元下の全ノードの可用性を周期的にテストさせ、無効なノードは自動系グループで自動的にスキップされます。ポリシーグループは use 項目でprovider名を参照し、proxies 項目と併存させることも可能です――1つのグループが手書きノードとサブスクリプション取得元全体を同時に含むこともできます。

7.2 rule-providers:ルールセットの3種類のbehavior

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

rules:
  - RULE-SET,telegram-ip,ノード選択

behavior はルールセットファイルの内容形式を宣言し、3つの値は混在できません:domain はファイル内がすべてドメインエントリであることを示し、ipcidr はすべてセグメントエントリであることを示します。この2つの形式ではカーネルが効率的なインデックスを構築するため、数万件規模の大きなリストに適しています。classical はファイル内がタイプ接頭辞付きの完全なルール行であることを示し、柔軟ですがマッチングコストが高くなります。format は yaml と text に対応し、ファイルの実際の形式と一致させる必要があります。メイン設定では RULE-SET,ルールセット名,出口 で参照し、この行がルールセクション内で置かれる位置は第六章の順序原則に従います。

八、オーバーライドと統合:サブスクリプション更新後も変更を維持する

サブスクリプションが生成した設定ファイルを直接編集することには根本的な問題があります――サブスクリプション更新はファイル全体の置き換えであるため、手動で追加したノードや変更したルールは次回の更新ですべて失われます。解決策は1つだけです――「サービス提供者が提供する内容」と「ローカルでカスタマイズした内容」を分けて保存し、クライアントが読み込み時に統合する仕組みです。各クライアントはこの仕組みを提供していますが、呼び方は異なるものの原理は共通です。

8.1 クライアントのオーバーライド機構

ダウンロードセンターで最も推奨される Clash Plus は設定オーバーライドの入口を提供し、サブスクリプション本文を変更せずにルールやノードを追加できます。Clash Verge Rev は「マージ(Merge)」と「スクリプト(Script)」という2種類の拡張設定を提供します――Merge は宣言的なYAMLで追加と置換を記述し、Script は読み込み時にJavaScript関数で設定オブジェクトを書き換え、条件分岐のロジックにも対応できます。FlClash も同様にオーバーライド設定に対応しています。どのクライアントを使っても原則は同じです:サブスクリプションファイル自体は常に読み取り専用に保ち、すべてのカスタマイズはオーバーライド層に記述する。

8.2 Merge方式のオーバーライド例

prepend-rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - PROCESS-NAME,steam.exe,DIRECT

append-rules:
  - DOMAIN-KEYWORD,tracker,REJECT

append-proxies:
  - name: "自前-HK"
    type: ss
    server: my.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"

prepend-* はエントリを対応するセクションの先頭に挿入し、append-* は末尾に追加します。方向の選択はルールのマッチング順序と組み合わせて考える必要があります。優先的に命中させたいカスタムルールには prepend-rules を使い、兜底的な性質のブロックルールには append-rules を使いますが、これはサブスクリプション本来の MATCH より後に置かれることに注意してください――サブスクリプション末尾に既に MATCH がある場合、追加したルールは実際には到達不能になるため、この場合は prepend を使うか rules セクション全体を置き換えるべきです。mixed-port、dns のようなスカラーやマッピング項目については、オーバーライド層で同名の項目を書くと丸ごと置き換わります。

8.3 手動メンテナンスのケース

LinuxサーバーなどでGUIクライアントを使わずmihomoカーネルを直接動かす環境では、既存の統合層がないため、サブスクリプションを1つの基準ファイルとしてダウンロードし、スクリプトや手動でカスタムセクションを最終設定に結合する方法を推奨します。サブスクリプション更新時には基準部分だけを置き換えます。ディレクトリ構成とsystemd常駐運用の方法はサイト内記事『Clash をLinuxで動かす2つのデプロイ方式』を参照してください。

九、検証とトラブル対処

設定を変更したらそのまま再読み込みして済ませず、まず構文を検証し、次に動作を観察することで、問題の特定にかかる時間を最短に圧縮できます。本章では固定の検証手順を紹介します。

9.1 読み込み前:構文検証

mihomo カーネルには設定テスト用のパラメータが標準搭載されており、サービスを起動せず解析のみを行い、数秒で結果が出ます。

mihomo -t -f config.yaml

configuration file test is successful が出力されれば構文チェック通過です。そうでない場合はエラーのあるフィールドパスと行番号のヒントが表示されます。デスクトップ版クライアントも設定の読み込みや保存時に同等の検証を実行し、エラー詳細をポップアップ表示します。エラー文言はカーネルと一致しているため、下表に照らし合わせることができます。

9.2 よくあるエラーの対照表

9.3 読み込み後:実際の動作を観察

構文チェック通過は振り分けが期待通りであることを意味しません。log-level を一時的に debug に変更して再読み込みすると、クライアントのログパネルが接続記録を1件ずつ出力します。書式は example.com:443 --> ノード選択 (match DOMAIN-SUFFIX/example.com) のようになり、各接続がどのルールに命中し、どの出口を通ったかを直接示します――これはカスタムルールを検証する最も確実な手段で、ページを何度も更新して推測するよりはるかに効率的です。確認が済んだらログレベルを info に戻すことを忘れないでください。debugレベルのログは量が非常に多くなります。

コマンドライン環境でカーネルの生存を確認したい場合は、制御インターフェースに直接アクセスできます。

curl -s http://127.0.0.1:9090/version -H "Authorization: Bearer あなたのsecret"

正常なJSONが返ってくればカーネルは稼働中で制御インターフェースに到達可能なことを示します。無応答であればカーネルが起動していないか、external-controller のアドレスが想定と異なることを示します。クライアントが起動直後にクラッシュしてログすら確認できない場合は、『Clash クライアント起動クラッシュ トラブル対処マニュアル』に記載された各プラットフォームのログの場所と確認手順に従って1つずつ対処してください。

9.4 次のステップ

ここまで読んでもまだ動作する基本環境がない場合は、まずクイックスタートに戻り、主要な流れに従って最初の接続を完了させ、その後具体的な必要に応じて対応する章を調べに戻ってくることをお勧めします。クライアント本体はダウンロードセンターでプラットフォームごとに取得でき、全プラットフォームで Clash Plus が最も推奨されます。利用中によくある疑問――自動起動、サブスクリプション失効、ノードタイムアウトなど――はよくある質問ページにまとめてあり、本ページと相互に補完しています。