Clash 設定ファイル YAML 構造の逐条解説:基本フィールド、proxies、proxy-groups、rules

設定ファイル全体の構造と読み進め方

Clash の config.yaml は YAML 形式のテキストファイルで、クライアントは起動時にトップレベルのフィールドを順番に読み込みます。最も分かりやすい読み方は、ファイルを上から「基本設定」「DNS 設定」「ノード定義」「ポリシーグループとルール」の 4 セクションに分けて捉えることです。

YAML の構文ルールはシンプルです。インデントはスペースを使い(Tab は禁止)、同じ階層のフィールドはインデントを揃え、キーと値の間は半角コロンとスペースで区切ります。フィールドの順序自体は解析結果に影響しませんが、proxies・proxy-groups・rules の間には参照関係があります。ポリシーグループが参照するノード名は先に proxies で定義し、ルールが参照するポリシーグループ名は先に proxy-groups で定義する必要があります。「基本設定 → DNS → proxies → proxy-groups → rules」の順で書けば、読み進めやすく、未定義名の参照エラーも避けられます。

最小構成で動く設定の骨組み:

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

dns:
  enable: true
  nameserver:
    - 223.5.5.5

proxies:
  - name: "サンプルノード"
    type: ss
    server: 203.0.113.10
    port: 443
    cipher: aes-256-gcm
    password: "example-password"

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - "サンプルノード"
      - DIRECT

rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

この骨組みでは ipv6 や external-controller などの任意フィールドを省略していますが、「起動 → プロキシ経由 → ルールで振り分け」という一連の流れはすでに成立しています。

基本フィールド:ポート・モード・ログ

トップレベルの基本フィールドはクライアントの基礎動作を制御します。よく使うものを表にまとめました。

mode は 3 つの値の違いが最も紛らわしいフィールドです。rule モードは rules セクションのルールを上から順に照合し、最初に一致したルールで転送します。日常利用で最も一般的なモードです。global モードはすべてのトラフィックを proxy-groups の最初のポリシーグループに流し、rules の照合をスキップします。direct モードはすべてのトラフィックを直接接続し、実質的にプロキシを完全に迂回するため、ノード障害の切り分けに適しています。

port と socks-port は同時に待ち受けることも、どちらか一方だけを有効にすることもできます。ローカルの 7890 が他のプログラムに使用されている場合、起動ログに bind: address already in use と表示されるので、7897 など空いているポートに変更してください。

external-controller は RESTful API を提供し、Clash Verge のパネル、Yacd、Metacubexd はいずれもこのアドレス経由で設定の読み取り・変更を行います。デフォルトでは 127.0.0.1 にバインドされ、ローカルからのみアクセスできます。secret フィールドを設定した場合は、API アクセス時に対応するリクエストヘッダーが必要です。

log-level は日常では info、問題調査のときだけ一時的に debug に切り替えるのがおすすめです。debug では各接続のルールマッチ結果が出力されます。

[TCP] dial Match(DomainSuffix): github.com → PROXY
[UDP] dial Match(GEOIP): 8.8.8.8 → DIRECT

このログを見れば、どのルールでトラフィックが振り分けられたかがすぐ分かるため、ルーティングのデバッグに最も有効です。

DNS 設定セクション:nameserver と fallback の役割分担

dns セクションはドメイン名解決の経路を決める、設定の中でも特に重要な部分です。主要フィールドは以下のとおりです。

nameserver はほとんどのドメイン名の解決を担当し、通常は中国国内の公共 DNS、たとえば 223.5.5.5(アリババ)や 119.29.29.29(テンセント)を指定します。応答が速く、DNS 汚染の問題もありません。

fallback は DNS 汚染を受けたドメイン名の処理に使います。nameserver が返した IP が geoip で予約アドレスと判定された場合、クライアントは fallback のサーバーでもう一度解決を試みます。シンプルな構成なら、fallback に 8.8.8.8 と 1.1.1.1 を指定しておけば十分です。

ここでよくある落とし穴があります。proxies のノードが IP ではなくドメイン名で指定されている場合、クライアントはノードのドメイン名解決にも dns セクションを使います。ノードのドメイン名が汚染されると、すべてのノードに接続できなくなります。そのため default-nameserver には信頼できる中国国内の DNS を必ず指定し、ノードのドメイン名解決を fallback に任せないようにしてください。TUN モードでは dns セクションの enable を true にする必要があります。false のままだと TUN 有効時にシステムのトラフィックが正しく名前解決できません。

proxies ノード:プロトコルごとの定義方法

proxies は配列で、各要素が 1 つのプロキシノードを定義します。どのプロトコルでも name・type・server・port の 4 つの基本フィールドは共通で、プロトコル固有のフィールドはそれぞれ異なります。

SS ノードはフィールドが最も少なくて済みます。

- name: "SS-東京"
  type: ss
  server: 203.0.113.10
  port: 443
  cipher: aes-256-gcm
  password: "your-password"

cipher の主な値には aes-256-gcm、chacha20-ietf-poly1305、2022-blake3-aes-256-gcm などがあります。パスワードはサブスクリプション事業者から提供されたものと完全に一致させる必要があります。一致しないとハンドシェイクの段階で失敗します。

VMess ノードには uuid、alterId とトランスポート層のフィールドが加わります。

- name: "VMess-シンガポール"
  type: vmess
  server: 203.0.113.20
  port: 443
  uuid: "550e8400-e29b-41d4-a716-446655440000"
  alterId: 0
  cipher: auto
  network: ws
  ws-opts:
    path: "/path"
    headers:
      Host: "example.com"

alterId は新しいサーバー実装では通常 0 です。network が ws の場合は ws-opts の path と Host を併せて指定する必要があり、これらはサブスクリプション事業者の設定と 1 対 1 で対応します。誤った値を設定すると、TLS ハンドシェイク後にトンネルを確立できません。

Trojan ノードの構造は VMess に似ていますが、uuid はありません。

- name: "Trojan-ロサンゼルス"
  type: trojan
  server: 203.0.113.30
  port: 443
  password: "your-password"
  sni: "example.com"
  skip-cert-verify: false

sni は TLS の SNI 拡張に使われ、証明書のドメイン名と一致している必要があります。skip-cert-verify のデフォルトは false で、ノード証明書自体が無効でリスクを受け入れられる場合を除き、true に変更しないことをおすすめします。

Hysteria2 ノードでは、さらに up と down の帯域パラメータが必要です。

- name: "Hysteria2-香港"
  type: hysteria2
  server: 203.0.113.40
  port: 443
  password: "your-password"
  up: "50 Mbps"
  down: "200 Mbps"
  sni: "example.com"

up/down はクライアントが利用可能な帯域幅を宣言するもので、値が小さすぎると転送速度が制限され、大きすぎると輻輳を引き起こす可能性があります。

proxy-groups ポリシーグループ:選択ロジックの入れ子構造

proxy-groups はポリシーグループを定義します。グループ内の proxies リストにはノードだけでなく、他のポリシーグループも指定できます。よく使われるタイプは次の 4 つです。

select タイプが最も分かりやすいでしょう。

- name: PROXY
  type: select
  proxies:
    - "SS-東京"
    - "VMess-シンガポール"
    - "Trojan-ロサンゼルス"
    - DIRECT
    - REJECT

url-test では、速度測定用の URL と測定間隔の追加設定が必要です。

- name: Auto
  type: url-test
  url: "https://www.gstatic.com/generate_204"
  interval: 300
  tolerance: 50
  proxies:
    - "SS-東京"
    - "VMess-シンガポール"

interval の単位は秒で、300 は 5 分ごとに速度を測定することを意味します。tolerance は遅延差が 50ms 未満の場合は切り替えないという設定で、頻繁なノードの揺れを防ぎます。

ポリシーグループは入れ子にできます。これは上級者向けの書き方です。

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Auto
      - "SS-東京"
      - DIRECT
  - name: Auto
    type: url-test
    proxies:
      - "SS-東京"
      - "VMess-シンガポール"

ここでは PROXY グループの最初の選択肢が Auto グループになっており、Auto を選ぶと実際のトラフィックは url-test が自動的に決定します。入れ子の階数に厳密な制限はありませんが、2 階層までにしておくことをおすすめします。それ以上深くすると「今どのノードを使っているのか」の確認が難しくなります。

rules ルールセクション:マッチング順序がトラフィックの行き先を決める

rules は設定の最後のセクションであり、トラフィック振り分けの中核です。Clash は上から順にルールを照合し、最初に一致したルールで処理を終了します。以降のルールは確認されません。そのためルールの順序が非常に重要です。

よく使うルールタイプ:

実運用で使える rules の例:

rules:
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT
  - DOMAIN-SUFFIX,cn,DIRECT
  - GEOIP,CN,DIRECT
  - DOMAIN-SUFFIX,google.com,PROXY
  - DOMAIN-SUFFIX,youtube.com,PROXY
  - DOMAIN-KEYWORD,github,PROXY
  - MATCH,PROXY

上記の順序に注目してください。LAN 内と中国国内のトラフィックを先に DIRECT で処理し、その後に海外ドメインを PROXY にマッチさせ、最後に MATCH でフォールバックします。もし DOMAIN-SUFFIX,google.com,PROXY を GEOIP,CN,DIRECT より前に置くと、google.com の解決結果が中国国内の IP(たとえば CDN によって国内ノードに振り分けられた場合)だと、誤って直接接続されてしまいます。

ルールの最後のフィールド(ターゲット)は、proxy-groups で定義したグループ名、または DIRECT・REJECT のどちらかの組み込みターゲットでなければなりません。存在しないグループ名を参照すると、設定の検証で即座にエラーになります。

設定の検証とよくあるエラー

config.yaml を書き終えたら、まずコマンドラインで構文を検証してからクライアントを起動すると、調査にかかる時間を大幅に節約できます。mihomo コアの検証コマンドは次のとおりです。

./mihomo -t -f config.yaml

configuration file ... test is successful と出力されれば検証は成功です。Clash Verge の「設定」→「パラメータ設定」にも設定チェックの項目があり、内部的には同じ検証ロジックを呼び出しています。

よくあるエラーを発生頻度順にまとめます。

1. インデントに Tab を使用している。YAML はスペースのみを認識します。エディタで「Tab をスペースに変換」を有効にすれば防げます。
2. コロンの後にスペースを入れ忘れている。port:7890 はポートフィールドではなく文字列キーとして解釈されます。
3. パスワードなどの特殊文字を引用符で囲んでいない。パスワードに #、:、* などの文字が含まれる場合は必ず二重引用符で囲んでください。囲まないと YAML がコメントや構造記号として解釈します。
4. 未定義のノード名またはポリシーグループ名を参照している。proxies の name と proxy-groups の proxies リストが完全に一致しているか確認してください。
5. 同じ名前のノードを重複して定義している。後から定義したものが前の定義を上書きするため、「設定を変更したのに挙動が変わらない」という現象が起きます。

検証コマンドの出力を上のリストと照らし合わせれば、ほとんどの設定問題は 5 分以内に特定できます。