高度な設定 読了目安 13分

Clash 設定ファイルのYAML構造を徹底解説｜基本項目からproxy-groups・rulesまで

config.yamlを項目ごとに解説。トップレベル設定、dns、proxies、proxy-groups、rule-providers、rulesの役割と記述順を紹介します。

YAMLファイル・サブスクリプション・コア設定の違い

config.yamlは設定ファイルによく使われる名前で、拡張子は.ymlでも構いません。YAMLはキーと値、リスト、階層構造を記述する形式です。各項目を解釈するのはClashやmihomoです。YAMLとして読み込めても、ノードのプロトコルやDNS設定、ルール形式が使用中のコアに対応しているとは限りません。

Clash Metaは後継プロジェクトでmihomoという名称で開発されています。クライアントによって、組み込まれているコアや設定画面は異なります。この記事ではmihomoの設定構造を中心に説明します。インラインルールセットなどの機能を旧バージョンのClashコアにそのまま適用することはできません。互換性を確認する際は、クライアント名だけで判断せず、「バージョン情報」やコア情報の画面で実際に動作しているコアを確認してください。

  • 設定一式を含むサブスクリプション：ポート、DNS、ノード、プロキシグループ、ルールなどが含まれる場合があり、更新時にこれらの内容も変更されることがあります。
  • プロキシプロバイダー：proxy-providersからノードを取得し、ローカルのプロキシグループで参照します。設定一式を含むファイルとは異なります。
  • クライアント側のオーバーライド：サブスクリプションの内容に項目を追加したり、置き換えたりします。マージの順序はクライアントによって異なります。

構造を検証できる完全なconfig.yamlの例

以下の設定例には、ローカルの混合ポートと直結用のポリシーのみが含まれ、プロキシサーバーはありません。項目の階層、ポリシーの参照関係、ルールの順序を確認するための例です。読み込みに成功しても、プロキシ経由で通信できるわけではありません。インラインルールセットを使うには、type: inlineに対応したmihomoコアが必要です。

# 基本の接続設定
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

# DNSモジュール；独立したDNS待ち受けポートは未設定
dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '*.lan'
    - 'localhost'
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

# リモートプロキシノードは未設定
proxies: []

# ポリシーグループ名はrulesから参照
proxy-groups:
  - name: 出口選択
    type: select
    proxies:
      - DIRECT

# インラインルールセット。別途ルールファイルは不要
rule-providers:
  サンプルドメイン:
    type: inline
    behavior: domain
    payload:
      - '+.example.com'

# 上から順に照合し、最後のルールをフォールバックにする
rules:
  - DOMAIN,localhost,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - RULE-SET,サンプルドメイン,出口選択
  - MATCH,出口選択

この設定ではシステムプロキシもTUNも有効になっていません。アプリのHTTPプロキシを手動で127.0.0.1:7890に設定すると、そのアプリの該当する通信が混合ポートに送られます。コアに接続が届くと、ルールによって「出口選択」が適用されます。このグループに現在含まれているのはDIRECTのみなので、接続先へは直接アクセスします。

記述順と実行順は別

トップレベルでdnsとproxiesのどちらを先に書いても、通常は設定の意味に影響しません。「接続設定 → DNS → ノード → プロキシグループ → ルールセット → ルール」の順に並べるのは、依存関係を確認しやすくするためです。実際の照合結果を左右するのはrulesリストの順序です。プロキシグループ内の候補順も画面上の表示に影響するため、すべてのリストを自由に並べ替えられる辞書のように扱わないでください。

基本設定：ポート・動作モード・ログ

項目設定例動作
mixed-port7890同じポートでHTTPとSOCKSのプロキシ接続を受け付けます。
allow-lanfalseほかのLAN端末からこのデバイスのプロキシ接続口を利用できないようにします。
moderuleルールリストに基づいて、接続に適用するポリシーを決定します。
log-levelinfo通常の動作情報を出力します。問題の調査時は一時的にdebugへ切り替えられます。
ipv6falseコアのIPv6機能を無効にします。OSのネットワーク設定を変更するものではありません。

mixed-port: 7890を設定しても、システム上のすべての通信がClashに送られるわけではありません。システムプロキシの設定が適用されるのは、その設定に従うアプリだけです。独自に通信するプログラムはプロキシを経由しない場合があります。TUNは仮想ネットワークインターフェースとルーティングを使って通信を取り込む仕組みで、システムプロキシとは接続の入口が異なります。

external-controllerは管理APIの待ち受けアドレスで、ブラウザーに入力するプロキシアドレスではありません。たとえば、ローカルの管理ポートには127.0.0.1:9090を指定できます。ただし、混合ポートと同じアドレスの7890を重複して使うことはできません。クライアントがコントロールインターフェースを管理している場合もあるため、手動で上書きする前に要件を確認してください。

dns：名前解決モード・上流DNS・Fake-IPの関係

dnsはトップレベルのマッピングです。内部のenableやnameserverなどの項目は、dns:より1段深くインデントします。例ではnameserverに上流DNSアドレスを2つ指定しています。2つ指定しても、必ず1つ目から順番に問い合わせて失敗時に切り替えるとは限りません。実際の問い合わせ動作は、コアの実装やほかのDNS設定によって異なります。

Fake-IPはプロキシノードのアドレスではない

enhanced-mode: fake-ipでは、対象となるドメインの問い合わせに合成アドレスを割り当て、その対応関係を使って後続の接続を処理します。例のアドレスプール198.18.0.1/16はリモートサーバーのアドレスではなく、ノードのserver項目にも指定しません。実際の名前解決結果が必要なLANアプリは、必要に応じてfake-ip-filterに追加してください。

  • dns.enable: trueはコアのDNSモジュールを有効にする設定です。OSがすべてのDNSリクエストをコアに渡すことを意味するわけではありません。
  • dns.listenは独立したDNS待ち受け口を開く設定です。この例では、ポートを追加で使用しないよう指定していません。
  • dns.ipv6: falseは、コアがAAAAレコードの問い合わせをどう処理するかを制御します。これを設定しても、OSからIPv6接続が一切行われなくなるわけではありません。
  • 暗号化DNSが保護するのは該当する名前解決経路です。プロキシルールを自動的に置き換えるものではなく、すべてのDNSリクエストがプロキシ経由になることを保証するものでもありません。

「ドメイン名では開けないが、IPアドレスなら開ける」場合は、まずDNS問い合わせがコアに届いているか、上流DNSに到達できるかを確認し、その後Fake-IPの対応関係とルーティングを調べてください。この状況でノードを何度も切り替えても、原因の解消につながらないことがあります。

proxiesとproxy-groups：ノードと選択方法を分けて記述

proxiesはノードのリストです。各ノードには通常、name、type、server、portのほか、プロトコルに応じた認証情報や通信パラメーターを指定します。プロトコルごとに必要な項目は異なり、相互に置き換えることはできません。たとえば、パスワードの項目を別のプロトコルで必要なUUIDの代わりにはできません。実際の値はサービス提供元または自分で構築したサーバーの設定を確認してください。

proxy-groupsはリモートサーバーを定義するのではなく、接続先の出口を選ぶ方法を定義します。グループ内のproxiesはトップレベルの項目と同じ名前ですが、ここでは候補名のリストを表します。指定する名前は、定義済みのノード、参照可能な別のプロキシグループ、またはDIRECTなどの組み込みポリシーと一致している必要があります。

よく使われるプロキシグループの種類

  • select：クライアント上で候補を手動選択します。ノードや直接接続を明示的に指定したい場合に適しています。
  • url-test：指定したテストURLへの接続結果に基づいて候補を自動選択します。測定した遅延が、すべてのサイトでの実際の読み込み速度を示すわけではありません。
  • fallback：候補の順序とヘルスチェックの結果に応じて利用可能な候補を選びます。メイン・バックアップの切り替えに適しています。
  • load-balance：設定した分散方式に基づいて接続を振り分けます。1つのダウンロード接続を複数ノードに分割し、帯域を合算する機能ではありません。

この例ではselectを使うため、テストURLは不要です。自動テスト型のプロキシグループに変更する場合は、現在のネットワークに適したテストURLと確認間隔も設定します。たとえばinterval: 300は300秒を表します。typeだけ変更して、その種類の動作に必要な設定を省略しないでください。

サブスクリプションのノードをproxy-providers経由で参照する

プロキシプロバイダーを使う場合、プロキシグループでは通常、useを使ってプロバイダー名を参照します。サブスクリプションURLをグループ内のproxiesリストに記入するわけではありません。プロバイダーが返す内容も指定形式に合っている必要があり、設定一式を含む通常のサブスクリプションをそのままプロキシプロバイダーとして使えるとは限りません。「ルールからプロキシグループを指定し、グループからノードを選択する」という参照関係を明確に保ちましょう。

rule-providersとrules：ルールセットの定義と照合

rule-providersには再利用可能なルールセットを定義し、rulesで参照するタイミングと一致後に適用するポリシーを指定します。「サンプルドメイン」というルールセットを定義しただけでは、自動的に通信の振り分けに使われません。RULE-SET,サンプルドメイン,出口選択のように参照するルールが必要です。

behaviorに応じてpayloadの記述形式を選ぶ

behavior記述例注意点
domain+.example.comドメインルールセットの形式を使います。各行に適用先のプロキシグループは記述しません。
ipcidr192.168.0.0/16IPアドレスの範囲を記述します。ドメイン名を混在させないでください。
classicalDOMAIN-SUFFIX,example.comルール式を記述し、適用先のポリシーは参照する側で指定します。

この例ではtype: inlineを使い、ルールセットの内容をpayloadの下に直接記述しています。HTTP経由のリモートルールプロバイダーでは、ダウンロードURL、キャッシュパス、更新間隔、形式なども設定する必要があります。リモートファイルの本文をURLの項目に貼り付けることはできません。旧バージョンのコアがインラインプロバイダーに対応していない場合は、意味が同じであることを確認したうえで通常のルールに書き換えてください。

上から照合し、最初に一致したルールを適用

たとえば、サンプルドメインには「出口選択」を適用し、それ以外の接続は直接接続にする場合、次のように記述できます。

rules:
  - DOMAIN-SUFFIX,example.com,出口選択
  - MATCH,DIRECT

DOMAINは完全一致するドメインを照合し、DOMAIN-SUFFIXはそのドメインとサブドメインを照合します。MATCHは最後に使うフォールバックルールです。先頭に移動すると、後続のドメインルールが照合されなくなります。ルールを追加するときは既存のリストを編集してください。ファイル末尾に2つ目のrules:を追加してはいけません。

IPルール末尾のno-resolveは、そのルールとの照合のためにドメイン名をIPアドレスへ積極的に解決しない指定です。DNSを全体的に無効化するものではありません。接続先IPがすでに分かっている場合は、該当するネットワーク範囲の照合対象になることがあります。この例には一部のローカルアドレス範囲しか記載していないため、完全なプライベートネットワーク用ルールセットとして扱わないでください。

TUN設定の記述場所と、有効化だけでは不十分な理由

tunはdnsやrulesと同じトップレベルの項目です。プロキシグループの内部にインデントしてはいけません。デスクトップでは次のような設定がよく使われますが、実際に使えるかどうかはコア、OS、クライアントによる通信の取り込み方法によって異なります。

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

auto-routeは関連するルートを自動設定し、auto-detect-interfaceは出口インターフェースを自動検出します。TUNを有効にするには、通常、管理者権限またはクライアントのサービスモードが必要です。Androidクライアントは多くの場合、システムのVpnServiceでVPNインターフェースを作成するため、デスクトップと同じ権限設定をそのまま適用しないでください。

dns-hijackのany:53は、対象となる従来型DNS通信を横取りする設定です。ブラウザーがHTTPS経由で行う暗号化DNSのリクエストすべてを対象にするものではありません。社内VPN、ほかの仮想ネットワークインターフェース、手動設定したルートが自動ルーティングと競合する場合もあります。まずシステムプロキシ経由で設定が動作することを確認してからTUNを有効にしましょう。接続方法、DNS、ルールを同時に変更すると、原因を特定しにくくなります。

読み込み前に確認：インデント・参照・クライアント側の上書き

YAMLでよくあるミス

  • Tabでインデントする：半角スペース2つに統一し、同じ階層の項目をそろえます。
  • リストのハイフンを忘れる：rules、nameserver、グループ内の候補はいずれもリストです。
  • トップレベルの項目を重複させる：2つのdns:が自動でマージされるわけではありません。パーサーがエラーを出したり、片方だけを採用したりする場合があります。
  • 特殊文字を引用符で囲まない：パスワード、特殊記号を含む名前、別の型として解釈される可能性がある値は、引用符で囲むのがおすすめです。
  • 大文字・小文字や名前が一致しない：出口選択と出口選択 は同じ参照先として扱われるとは限りません。コピー時に末尾の空白がないか確認してください。

コアで設定を検証し、実際の適用状態を確認

mihomoのコマンドライン版がインストールされている場合は、設定ファイルのあるディレクトリで次のコマンドを実行します。

mihomo -t -f ./config.yaml

Windowsでは、現在のディレクトリに実行ファイルがあることを確認し、.\mihomo.exe -t -f .\config.yamlを実行します。テストに成功すれば、そのコアで設定を検証できたことを示します。ノードの認証情報が正しいか、ネットワークに接続できるか、システム通信がプロキシに届いているかまでは確認できません。

  1. まず設定をテストし、ログに示された行番号、未知の項目、ポリシーの参照エラーを優先して修正します。
  2. クライアントに設定を読み込み、混合ポートが7890になっていることと、ポート競合のエラーがないことを確認します。
  3. プロキシを設定したアプリから通信し、接続一覧で一致したルールと最終的に適用されたポリシーを確認します。
  4. ファイルにmode: ruleと記述しているのに、画面に別のモードが表示される場合は、クライアントの全体設定や実行時APIによって設定値が上書きされていないか確認してください。
  5. 最後にサブスクリプションを更新し、カスタムルールが残っていることを確認します。変更を維持するには、オーバーライド設定に記述されている必要があります。
Clash をダウンロード