REF-00 · CONFIG.YAML · FIELD MANUAL

Clash 設定ファイルフィールド完全リファレンス

このページは config.yaml のフィールド別リファレンスです。ファイル全体の構造から始め、共通の動作設定、DNS モジュール、ノード、プロキシグループ、ルール構文を順に解説し、最後にサブスクリプション利用時のオーバーライドとマージの仕組みを説明します。各セクションにはそのまま実行できる YAML の抜粋とパラメータ対照表を用意しました。クライアントのインストールとサブスクリプション導入がまだの場合は、先に使い方ガイドの手順で一通り接続を通してから、必要に応じて本ページを参照することをお勧めします。クライアントの入手先はダウンロードページを参照してください。

SEC-01

読み方ガイド

Clash 系クライアントの動作はすべて1つの YAML 設定ファイルによって決まります。どのポートを監視するか、DNS をどう解決するか、どんなノードがあるか、通信をどのルールで振り分けるか——これらすべてがこのファイルに記述されています。GUI クライアントのスイッチやドロップダウンは、本質的にはこのファイルを可視化した編集画面にすぎません。フィールドそのものを理解しておけば、画面上の選択肢が足りないときやサブスクリプション内容を微調整したいときにも困らずに済みます。

本サイトでは設定に関するコンテンツの役割を明確に分けています。使い方ガイドは「ダウンロードから接続まで」の最短経路を担い、フィールドの詳細には踏み込みません。よくある質問は症状別に検索できる独立した Q&A 集です。本ページは体系的なフィールドリファレンスであり、設定ファイルの記述順に沿って構成しているため、通読して全体像をつかむのにも、目次から該当セクションへ直接ジャンプするのにも使えます。

フィールドの意味はmihomo カーネルを基準としています。オリジナルの Clash カーネルがアーカイブされた後、本サイトが第一に推奨する Clash Plus をはじめ、Clash Verge Rev、FlClash、Clash Nyanpasu などの主要な GUI クライアントはすべて mihomo に移行済みで、本ページで説明するフィールドはこれらのクライアント間で共通です。一部の mihomo 拡張フィールドは古いカーネルでは利用できないため、その場合は本文中に個別に注記します。各クライアントの対応プラットフォームと入手方法はダウンロードページを、プロジェクト間の系譜については記事「Clash・mihomo・Verge Rev の関係を整理する」を参照してください。

NOTE

サブスクリプション型サービスを利用しているユーザーへの注意:サブスクリプションリンクが返すのは完全な config.yaml で、その中のノードとルールはサービス提供者側が管理しています。本ページを読むとサブスクリプションの内容を理解する助けになりますが、サブスクリプションファイル本体を直接手動で編集しても次回更新時に上書きされます。恒久的な修正の正しい方法は第8章「オーバーライドとマージ」を参照してください。

↑ 目次に戻る
SEC-02

YAML 構造の全体像

トップレベル構造:最小構成のひな型

config.yaml はいくつかのトップレベルキーからなるマッピングです。オプションを全部省くと、動作可能な最小構成は5つの要素だけで済みます。動作パラメータ、DNS、ノード一覧、プロキシグループ一覧、ルール一覧です。まずひな型を見て、以降の章で1つずつ展開していきます。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://223.5.5.5/dns-query

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

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - HK-01
      - DIRECT

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

トップレベルキーの読み込みには順序の制約はなく、カーネルはキー名で値を取得します。ただし慣習として「動作パラメータ → dns → proxies → proxy-groups → rules」の順に並べるのが一般的で、通信処理の論理的な流れと一致するため、読解もトラブル対処もしやすくなります。よく使われるトップレベルキーとその型は次の表の通りです。

トップレベルキー役割必須か
mixed-port などのポート系整数ローカル監視ポートいずれか1つ必須
mode列挙型文字列振り分けモード(rule/global/direct)明示的な指定を推奨
dnsマッピング内蔵 DNS モジュールTUN・透過プロキシでは必須
proxies配列ノード定義必須
proxy-groups配列プロキシグループ定義必須
rules文字列配列振り分けルール(上から順に照合)rule モードでは必須
proxy-providersマッピング外部ノード集合(サブスクリプション分離)任意
rule-providersマッピング外部ルール集合任意
tunマッピング仮想ネットワークアダプタのパラメータ任意

記述ルール:インデント・引用符・よくあるミス

YAML は書式に敏感で、設定エラーの多くはフィールドの誤用ではなく書式の問題が原因です。3つの鉄則があります。第一に、インデントには半角スペースのみを使い、2文字で統一すること。タブ文字は解析失敗の直接原因になり、しかもエラー行番号がファイルのかなり後ろを指すため特定が非常に困難です。第二に、コロンの後には必ず半角スペースを1つ入れること。port:7890 は文法違反です。第三に、配列要素は「ハイフン+スペース」で始め、ハイフンのインデント階層がどのキーに属するかを決定します。

文字列は通常引用符不要ですが、3つの場合は必須です。値にコロンやシャープなどの特殊文字が含まれる場合、数字のみの値を文字列として扱いたい場合、パスワードや UUID のように特殊文字で始まる可能性のある機密値の場合です。常に二重引用符を付ける習慣にしておくと最も安全です。また YAML 1.1 の名残として、引用符なしの yesnoonoff は一部のパーサーで真偽値として解釈されるため、ノード名がこれらの語と一致する場合は必ず引用符を付けてください。

WARN

Web ページから設定の断片をコピーすると、リッチテキストエディタが通常の半角スペースを改行なしスペース(U+00A0)に置き換えてしまうことがあります。目視では判別できず、解析時に「found character that cannot start any token」というエラーになります。プレーンテキストエディタに貼り付けるか、貼り付け後に全選択してインデントを再入力することをお勧めします。

↑ 目次に戻る
SEC-03

共通フィールド

ポート系:mixed-port、port、socks-port

ポートフィールドは、ローカルのアプリケーションがどのように通信をカーネルへ渡すかを決めます。mixed-port は現在推奨される書き方で、1つのポートで HTTP と SOCKS5 両方のプロトコルの着信を受け付けます。システムプロキシはこの1つのポートを指定するだけでよく、ほとんどのクライアントがデフォルトで生成する形式です(慣例値は 7890)。従来の書き方である port(HTTP 専用)と socks-port(SOCKS5 専用)も依然有効で、mixed-port と併用してそれぞれ別ポートで監視することもでき、プロトコルごとに入口を分けたいデバッグ場面に向いています。

その他に redir-porttproxy-port があり、Linux の透過プロキシ(iptables/nftables と連携)向けで、デスクトップの日常利用では設定不要です。すべてのポートに共通する制約はローカルの他プロセスと競合しないことです。起動時に bind: address already in use というエラーが出た場合はポートが使用中であることを示しており、特定と変更の手順は記事「Clash でポート占有エラーが出たときの対処法」を参照してください。

allow-lan と bind-address

allow-lan は同一 LAN 内の他デバイスからの着信を受け付けるかどうかを制御し、デフォルトは false(127.0.0.1 のみ監視)です。true にすると、同じ Wi-Fi 上のスマートフォンやテレビ機器がこのパソコンの LAN 内 IP とポートをプロキシ先として指定でき、「1台でプロキシを起動して家中で共有」が可能になります。合わせて使う bind-address は監視するネットワークインターフェースを限定するもので、デフォルトの "*" は全インターフェースを意味し、複数のネットワークインターフェースがある環境では特定のアドレスを指定して入口を絞ることができます。allow-lan を有効にすると LAN 内のどの端末もあなたの出口経由で通信できるようになるため、公共のネットワーク環境(オフィスやホテル)では無効のままにしておくべきです。

mode:3つの振り分けモード

mode は3つの値を取ります。rule はルールモードで、各接続を rules リストと1件ずつ照合して振り分け先を決める、日常利用における標準の形態です。global はグローバルモードで、ルールをスキップしてすべての通信を単一の出口に送ります(画面上ではノードを1つ選ぶ形で表現されることが多いです)。direct は直接接続モードで、すべての通信がプロキシを経由せず、振り分けを一時停止しつつカーネルの動作は維持する形になります。「あるサイトが実際にどのルールを通っているか」を調べる際は、global と rule を切り替えて比較すると、問題がルール側かノード側かを素早く判断できます。

ログと外部コントローラー

log-level はカーネルログの詳細度を制御し、簡潔から詳細の順に silenterrorwarninginfodebug があります。通常は info を推奨し、トラブル対処時には debug に切り替えれば各接続がどのルールに命中したか、DNS 解決の経路まで確認できます。安定を確認したら元に戻し、ログファイルが無意味に肥大化しないようにしましょう。external-controller は RESTful 制御インターフェースの監視アドレスを宣言するもので(慣例は 127.0.0.1:9090)、GUI クライアントやWeb パネルはこれを通じて状態を読み取り、ノードを切り替えます。合わせて使う secret はこのインターフェースへのアクセスパスワードを設定するもので、コントローラーを 0.0.0.0 で監視したり LAN に開放したりする場合には secret を必ず設定してください。例:secret: "your-secret"

その他よく使うスイッチ

ipv6 はデフォルト false で、true にするとカーネルが AAAA レコードを解決・接続するようになります。ローカルまたはノード側で IPv6 が通らない場合、一部サイトでタイムアウトが発生することがあるため、経路が IPv6 に対応していることを確認してから有効化することをお勧めします。unified-delay(mihomo 拡張)は遅延テストからハンドシェイクのオーバーヘッドを除外し、異なるプロトコルのノード間で遅延値を比較しやすくします。profile ブロック下の store-selected: true は各プロキシグループで前回選択したノードを記憶し、再起動やサブスクリプション更新後も再選択が不要になります。ほとんどのクライアントテンプレートでデフォルト有効です。

↑ 目次に戻る
SEC-04

DNS フィールド

内蔵 DNS が必要な理由

振り分けの前提は「この接続がどこへ向かうかを知る」ことであり、ドメイン名解決はまさに最も汚染や漏洩されやすい部分です。信頼できない上流に解決を任せれば取得する IP が誤っている可能性があり、すべての解決をローカルの ISP に任せればアクセス記録がそのまま露出してしまいます。dns モジュールはカーネルに解決処理を任せ、ルールシステムと連携して「どのドメインをどの DNS グループで解決し、その結果をどうアプリケーションに返すか」を決定します。TUN モードや透過プロキシでは dns モジュールは必須であり、システムプロキシのみを使う場合は有効化しなくても構いませんが、有効化すると振り分けの精度が明らかに向上します。

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "+.local"
    - "time.*.com"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://223.5.5.5/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

enhanced-mode:fake-ip と redir-host

これは dns ブロックの中で最も影響の大きいフィールドです。fake-ip モードでは、カーネルは各ドメインに対して予約ネットワーク帯(fake-ip-range で定義、デフォルト 198.18.0.0/16)内の仮アドレスを先に返し、アプリケーションはこの仮 IP で接続を開始し、カーネル側で仮 IP とドメインのマッピングを管理します。利点はアプリケーション側が実際の名前解決を完全にスキップでき、ルールはドメイン名で直接マッチングできる点で、接続確立が速く解決漏洩もありません。代償として、実際の IP に依存する一部のアプリ(LAN 内デバイス探索、一部のゲームのローカル対戦、NTP 時刻同期)が異常動作する場合があり、そうしたドメインを fake-ip-filter のホワイトリストに追加する必要があります。ホワイトリストに一致したドメインは実際の解決にフォールバックします。redir-host モードは常に実際の IP を返すため互換性が最も高いですが、一部の経路でドメイン情報が失われ、ルールの命中率と解決速度は fake-ip に劣ります。デスクトップクライアントのテンプレートは概して fake-ip がデフォルトで、特定のアプリで異常が出た場合に filter を追加すれば十分です。

比較項目fake-ipredir-host
アプリが取得する IP予約帯の仮アドレス実際の解決結果
接続確立速度速い(解決待ち不要)上流の解決時間に依存
ドメインルールの命中安定一部で IP 照合に退化する場合あり
互換性リスク実 IP 依存アプリはホワイトリスト要ほぼなし

3系統の上流:default-nameserver、nameserver、fallback

3つのリストはそれぞれ役割が明確です。default-nameserver は1つのことだけを行います。後述する2つの上流にある DoH/DoT サーバー自身のドメイン名を解決することで、そのため純粋な IP を指定する必要があり、そうしないと「解決サーバーのドメインを誰も解決できない」というデッドロックが発生します。nameserver は主力の上流で、日常のすべての解決を担い、暗号化プロトコルのアドレス(https:// で始まる DoH または tls:// で始まる DoT)を指定するのがお勧めです。平文の 53 番ポートが経路上で改ざんされるのを避けられます。fallback は予備の上流で、fallback-filter と連携します。nameserver の解決結果がフィルタ条件に一致した場合(典型的には geoip: true かつ geoip-code: CN、つまり「結果が中国本土の IP に属さない」場合)に fallback の結果に切り替えます。汚染への対抗策として、海外のドメインに対してクリーンな解決結果を得るために使われます。この仕組みが不要であれば nameserver のみを残せば構造がより単純になります。

NOTE

dns ブロックを変更したら、一度システムの DNS キャッシュをクリアしてから検証することをお勧めします(Windows は ipconfig /flushdns、macOS は sudo killall -HUP mDNSResponder を実行)。そうしないと古いキャッシュのせいで新しい設定が「反映されていない」ように見えることがあります。

↑ 目次に戻る
SEC-05

ノードフィールド

すべてのプロトコルに共通する4つのフィールド

proxies 配列の各要素が1つのノードを定義します。どんなプロトコルでも4つのフィールドは必須です。name(ノード名。ファイル全体で一意である必要があり、プロキシグループとルールはこれを参照するため、重複すると読み込みに失敗します)、type(プロトコル種別)、server(サーバーのドメイン名または IP)、port(サーバーポート)です。任意の udp フィールドはそのノードが UDP 通信を転送するかどうかを示し、ゲームやリアルタイム通話の用途では有効化を推奨します(サーバー側が対応していることが前提)。mihomo は非常に多くのプロトコルに対応しており、ss、vmess、trojan、vless、hysteria2、tuic、wireguard、socks5、http などが type の値として使えます。以下では代表的な3種類を詳しく説明します。

Shadowsocks(type: ss)

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

核心は暗号化パラメータです。cipherpassword はサーバー側と完全に一致していなければなりません。よく使われる cipher には aes-256-gcmchacha20-ietf-poly1305、そして次世代の 2022-blake3-aes-256-gcm(パスワードは Base64 エンコードされた固定長キーである必要があり、適当な文字列は使えません)があります。暗号化パラメータが一致しない場合の典型的な症状は接続が即座に切断され、ログに復号エラーが記録されることです。サーバー側がプラグイン(obfs など)を使っている場合は、pluginplugin-opts の2つのフィールドも追加する必要があります。

VMess(type: vmess)

  - name: "JP-01"
    type: vmess
    server: jp01.example.com
    port: 443
    uuid: 23ad6b10-8d1a-40f7-8ad0-e3e35cd38297
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ray
      headers:
        Host: jp01.example.com

認証情報は uuid で、サーバー側から発行されたものを1文字も変えずに転記します。alterId は現代的な構成では 0 に固定します(AEAD を有効化)。network はトランスポート層の形式を決めます。tcp は直接接続、ws は WebSocket 経由(CDN 中継と組み合わせることが多い)、grpc は gRPC 経由です。ws を選んだ場合は ws-opts に path と Host ヘッダーを指定する必要があり、この3つがサーバー側と一致しないとハンドシェイクに失敗します。tls: true の場合、servername で SNI を個別に指定できます(server に IP を入れつつ証明書がドメイン名に紐づいている場合に使用)。

Trojan(type: trojan)

  - name: "SG-01"
    type: trojan
    server: sg01.example.com
    port: 443
    password: "your-password"
    sni: sg01.example.com
    skip-cert-verify: false
    udp: true

Trojan は本質的に TLS の上で動作し、通常の HTTPS 通信を装います。sni はサーバー証明書のドメイン名と一致させる必要があります。skip-cert-verify は証明書検証をスキップするかどうかを制御しますが、false を維持するのが最低限のルールです——true にするとサーバーの身元確認を放棄することになり、いかなる中間者もノードになりすませてしまいます。自己署名証明書のテスト環境でのみ、一時的に有効化する理由があります。プロキシ経由での証明書エラーの原因と調査方法は記事「プロキシ有効時に HTTPS 証明書エラーが出る原因」を参照してください。

WARN

一部のサブスクリプションは「エラーを減らす」ためノードに一律で skip-cert-verify: true を書き込んでいます。本節を理解した上で、オーバーライドの層で一括して false に戻すことをお勧めします。それによって接続できなくなるノードがある場合は、検証を無効化するのではなく、そのノードの証明書設定自体を疑うべきです。

↑ 目次に戻る
SEC-06

プロキシグループフィールド

プロキシグループとは何か

proxy-groups はノードとルールの間に抽象化の層を1つ加えます。ルールは特定のノードを直接指すのではなく、プロキシグループを指し、グループ内で決められた方式(手動選択、自動測速、フェイルオーバーなど)によって実際の出口が決まります。利点は明白で、ノードを変更するにはグループ内で切り替えるだけでよく、数百のルールを一切変更する必要がありません。サブスクリプション更新でノード名が変わっても、影響はグループのメンバーリストだけに限定されます。グループの proxies メンバーにはノード名、組み込みポリシーの DIRECT(直接接続)と REJECT(拒否)、さらに別のグループの名前も指定できるため、「地域グループ → 総合出口グループ」という階層構造を構築できます。唯一の制約は循環参照が発生しないことです。

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - AUTO
      - HK-01
      - JP-01
      - DIRECT

  - name: "AUTO"
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true
    proxies:
      - HK-01
      - JP-01
      - SG-01

5種類のグループタイプを1つずつ解説

type動作典型的な用途
select手動選択、ユーザーが変更するまで維持総合出口、人手で管理したい場面
url-test定期的に測速し、遅延最小のメンバーを自動選択同一地域の複数ノードから自動最適化
fallbackリスト順に最初に利用可能なメンバーを採用主従切り替え、メイン復旧時に自動で戻る
load-balance複数メンバーへ接続を分散単一ノードの帯域制限回避、並列スループット向上
relayメンバーを順に直列接続してチェーン転送マルチホップ出口(ホップごとに遅延が増える)

自動タイプのグループ(url-test/fallback/load-balance)は3つの測速パラメータに依存します。url は検出用アドレスを指定し、204 の空レスポンスを返す軽量エンドポイントが一般的です。interval は検出周期(秒)で、300 が一般的なバランス値であり、小さすぎると継続的な測速通信が発生します。tolerance は url-test のみで使われ、「新旧の最適ノードの遅延差がこのミリ秒数を超えた場合のみ切り替える」を意味し、遅延が近い2ノード間の頻繁な切り替えを抑制します。lazy: true(mihomo 拡張)はグループが使用されていないときに検出を停止するもので、ノード数が多い場合にバックグラウンドリクエストを明確に減らせます。load-balance にはさらに strategy フィールドがあり、consistent-hashing は同一の宛先サイトを可能な限り同じノードに固定します(ログイン状態の維持に有利)。round-robin は厳密に順番に振り分けます。

グループ構成の推奨案

実践的には3層構造が推奨されます。最上層に select 型の総合出口を1つ置き(ルールは主にこれを指す)、中間層に地域ごとの url-test 自動グループを設け、最下層がノード本体です。さらに動画配信サービスや AI サービスなど地域指定が必要な用途向けに専用の select グループを作り、メンバーとして地域グループを参照させます。こうすることで日常はほぼ無操作(自動測速に任せる)、特定用途では手動で地域を固定でき、サブスクリプション更新の影響も地域グループ内部に隔離されます。

↑ 目次に戻る
SEC-07

ルール構文

基本形式と照合順序

rules 配列の各要素は1行の文字列で、タイプ,照合値,ポリシー の3段構成をカンマで区切ります。ポリシー欄にはグループ名、ノード名、あるいは組み込みの DIRECT/REJECT を指定できます。カーネルは新しい接続ごとに上から順に1件ずつ照合し、最初に一致した時点で停止します——このルールがすべてを決定します。厳密なルール(完全なドメイン名)は広範なルール(サフィックス、キーワード、GEOIP)より前に書かなければならず、そうしないと決して出番が来ません。リストの末尾には MATCH で兜底し、一致しなかったすべての通信を受け止めます。ルールの件数はパフォーマンスにほとんど影響しません(ドメインルールはプレフィックスツリーで索引化される)が、順序の誤りによる振り分けミスは非常に見つけにくいため、変更後は毎回ログで命中状況を検証することをお勧めします。

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,tracker,REJECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOSITE,category-ads-all,REJECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

ルールタイプ対照表

タイプ照合対象
DOMAIN完全なドメイン名の厳密一致DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIXそのドメインとすべてのサブドメインDOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORDドメインに指定文字列を含むDOMAIN-KEYWORD,google,PROXY
IP-CIDR / IP-CIDR6宛先 IP がそのネットワーク帯に属するIP-CIDR,10.0.0.0/8,DIRECT,no-resolve
GEOIP宛先 IP の地理的帰属GEOIP,CN,DIRECT
GEOSITEコミュニティが管理するドメイン集合GEOSITE,github,PROXY
PROCESS-NAME接続元のプロセス名(デスクトップ版)PROCESS-NAME,steam.exe,DIRECT
RULE-SETrule-providers の集合を参照RULE-SET,streaming,PROXY
MATCH無条件の兜底MATCH,PROXY

no-resolve とドメイン/IP ルールの相互作用

IP 系ルール(IP-CIDR/GEOIP)には見落とされやすい副作用があります。接続先がまだドメイン名の状態のとき、IP と照合するには先に名前解決を行う必要があり、この解決はローカル DNS を経由することがあり、漏洩を招くうえマッチングも遅くなります。IP ルールの4番目の項目として no-resolve を追加すると、「宛先がもともと IP である場合のみ照合し、ドメイン名であればこのルールをスキップする」という意味になり、LAN 内のネットワーク帯ルールには例外なく付けるべきです。全体の並べ方の要点は、ドメイン系ルールを前に、IP 系を後に、MATCH で締める、広告ブロック(REJECT)は同種のドメインルールの最も前に置くことです。ルールの書き方の完全な専題(自分で追加したルールをサブスクリプションのルールより前に置くか後に置くか、を含む)は記事「Clash のカスタムルールの書き方」を参照してください。

rule-providers:ルールを外部化する

rule-providers:
  streaming:
    type: http
    behavior: classical
    format: yaml
    url: https://example.com/rules/streaming.yaml
    path: ./rules/streaming.yaml
    interval: 86400

rules:
  - RULE-SET,streaming,PROXY

何千件ものルールを主ファイルに詰め込むと保守も共有も困難になるため、rule-providers は外部の URL やローカルファイルからルール集合を読み込み、interval 秒ごとに更新することを可能にします。behavior は集合の内容形式を宣言します。domain(純粋なドメインリスト)、ipcidr(純粋なネットワーク帯リスト)、classical(rules と同じ完全な3段構成)です。behavior とファイルの実際の内容が一致しない場合、集合は静かに機能しなくなります。これが外部化ルールが「読み込まれているように見えるのに効かない」という現象の最大の原因です。

↑ 目次に戻る
SEC-08

オーバーライドとマージ

サブスクリプションファイルを直接編集できない理由

サブスクリプション型のユーザーは構造的な矛盾に直面します。設定ファイルはサービス提供者側が生成し、サブスクリプションを更新するたびにファイル全体が再ダウンロードされて上書きされます。手動で追加したルールや変更したポートは、次回の更新までしか持ちません。正しい方法は「サービス提供者のベース設定」と「自分自身の変更」を分けて保存し、クライアントが読み込み時に両者を統合して最終的な設定にすることです。この仕組みはクライアントによって呼び方が異なります——オーバーライド、Override、Merge、拡張設定など、名前は違っても原理は同じです。

マージの基本的な意味

マージ用の設定自体も1つの YAML で、変更したい部分だけを書きます。意味は2種類に分かれます。スカラー値とマッピングフィールドは直接置き換えられます——オーバーライドに mixed-port: 7891 と書けば最終的な設定のポートは 7891 になり、完全な dns: ブロックを書けばベースの dns ブロック全体が置き換わります。配列フィールドは先頭挿入と末尾追加に対応します——多くのクライアントでは prepend- プレフィックスがベース配列の先頭への挿入、append- プレフィックスが末尾への追加を意味する約束になっており、これは rules にとって非常に重要です。先頭挿入したルールはサブスクリプションのルールより優先度が高く、末尾追加したルールは兜底としてしか機能しません。典型的なオーバーライドの例です。

mixed-port: 7891
log-level: warning

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

append-proxies:
  - name: "SELF-01"
    type: ss
    server: my.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
NOTE

prepend/append の具体的なキー名と対応範囲はクライアントの実装によって多少異なります。Clash Verge Rev は「グローバル拡張設定」とサブスクリプション単位の Merge/Script という2段階のオーバーライドを提供し、Clash Plus はサブスクリプション詳細画面にオーバーライド編集の入口を用意しています。実際の書き方は使用しているクライアントのドキュメントに従ってください。本節で示したのは一般的な意味です。

スクリプトによるオーバーライドと proxy-providers

宣言的なマージだけでは足りない場合——例えば名前でノードを一括フィルタリングしたい、すべてのグループに同じメンバーを一律で追加したいなど——一部のクライアント(Verge Rev など)は JavaScript によるスクリプトオーバーライドに対応しています。スクリプトは解析済みの設定オブジェクトを受け取り、変更後のオブジェクトを返す仕組みで、自由度は最も高い一方、エラーが起きると設定全体の読み込みに失敗するため、小さく変更して都度検証することが重要です。もう1つの考え方は逆に、サービス提供者の設定全体を使わず、proxy-providers だけを通じてサブスクリプションのノード部分だけを参照し、プロキシグループとルールは完全に自分で構築するというものです。これによりサブスクリプション更新はノードプールにのみ影響し、主設定は常に自分自身のものになります。本書を読み終え、自分でルール体系を保守する意欲があるユーザーに向いています。

proxy-providers:
  airport:
    type: http
    url: https://example.com/subscribe?token=xxxx
    path: ./providers/airport.yaml
    interval: 43200
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "PROXY"
    type: select
    use:
      - airport

グループは use フィールドで provider を参照する点に注意してください(proxies ではありません)。両者は併用可能で、health-check を設定すると provider 内のノードも可用性チェックの対象になります。

↑ 目次に戻る
SEC-09

検証とトラブル対処

読み込み前:静的検証

設定を変更したら、いきなり再起動して運任せにしないでください。mihomo カーネルの実行ファイルがある環境では、1つのコマンドで純粋な構文・意味の検査ができ、監視ポートを一切起動しません。

mihomo -d . -t -f config.yaml

-t はテストモードを、-d は作業ディレクトリを指定します(GeoIP データなどのリソースはここから探します)、-f は検査対象のファイルを指定します。configuration file ... test is successful と出力されれば合格です。エラーメッセージには行番号と原因が示され、よくあるものにはインデント誤り(yaml: line N)、ノード名の重複(proxy N: name duplicated)、グループが存在しないメンバーを参照している(proxy group ... proxy not found)、ルールのポリシー欄の誤字などがあります。GUI クライアントでも読み込み時に同等の検証が行われ、エラーダイアログの内容はコマンドラインと一致するので、行番号を頼りにファイルを特定すれば十分です。

読み込み後:振り分けが期待通りか検証する

設定の読み込みが成功しても動作が正しいとは限りません。3ステップの検証法があります。第一にログを確認する方法で、log-level を一時的に debug に切り替えて対象サイトにアクセスすると、ログにその接続が命中したルールと最終的な出口が出力され、「実際にどのルールを通ったか」を判断する唯一の権威ある根拠になります。第二に接続パネルを確認する方法で、GUI クライアントの接続画面はアクティブな接続の宛先、命中ルール、出口グループをリアルタイムに一覧表示し、全体的な通信分布を観察するのに向いています。第三に外部検証を行う方法で、直接接続とプロキシ経由の状態でそれぞれ IP 確認サービスにアクセスし、出口アドレスが実際にポリシーに応じて変わることを確認します。振り分けが正しいのに特定のアプリだけプロキシを通らない場合は、まずアプリがシステムプロキシを迂回している可能性を疑ってください——Windows ストアアプリのループバック制限が典型例で、解決方法は記事「Windows ストアアプリがプロキシを通らない理由」を参照してください。

高頻度トラブル早見表

症状高確率の原因対応する章
起動時に bind: address already in use が出るポートが他プロセスに使用されている第3章・ポート系
読み込み時に yaml: line N が出るインデント/タブ/コロン後のスペース不足第2章・記述ルール
ノードが全てタイムアウトするがサブスクリプションは更新できるノードの認証情報またはトランスポート層パラメータがサーバー側と不一致第5章・ノードフィールド
ドメインルールが効かないredir-host 下でドメイン情報が失われる、または広範なルールに順序を奪われている第4章/第7章
変更内容がサブスクリプション更新で消えるサブスクリプションファイル本体を直接編集した第8章・オーバーライドとマージ
LAN 内のデバイスが共有プロキシに接続できないallow-lan が無効、またはファイアウォールが着信を遮断第3章・allow-lan

症状別に整理されたその他の Q&A はよくある質問ページに収録されています。問題がクライアント側にあり設定側ではないと疑う場合は、ダウンロードページで別のクライアントに切り替えて相互検証してみてください——全プラットフォームで第一に推奨するのは Clash Plus です。同じ設定を異なるクライアントで試した際の動作の違いから、問題のある層を素早く特定できることが多くあります。

↑ 目次に戻る