Clash 設定檔 YAML 手冊

設定檔的結構總覽

Clash 系用戶端的全部運作行為,由一份 YAML 格式的設定檔決定。訂閱連結匯入後,用戶端從訂閱位址取回的本質上也是這份檔案;介面上切換節點、調整模式、增減規則,最終都會落回檔案中的對應欄位。把這份檔案讀通,用戶端的每一項介面操作也就都有了依據。

檔案通常命名為 config.yaml,存放在用戶端的設定目錄中。Clash Plus、Clash Verge Rev、FlClash 等圖形用戶端會代為管理這份檔案的讀寫:匯入訂閱時生成,切換選項時改寫。手動編輯之前,建議先退出用戶端,或先確認該用戶端的覆寫策略,否則剛改好的內容可能被介面操作整份覆蓋。覆寫機制的詳細說明見本頁第 8 章。

頂層欄位一覽

一份完整設定的頂層由若干欄位並列組成,欄位之間沒有先後依賴,書寫順序不影響解析。常用欄位及其職責如下:

一份最小可用設定只需要三類內容:監聽埠口、至少一個節點、至少一條規則。其餘欄位均有預設值,缺省時內核依預設行為運作。訂閱轉換服務生成的設定往往欄位齊全,手動精簡時保留主幹即可,不必逐項照搬。

YAML 語法的四條底線

YAML 的解析規則嚴格,絕大多數「設定無法啟動」都源於格式問題而非內容問題。書寫時守住四條底線:

• 縮排只用空格,不用 Tab;同一層級的縮排寬度必須一致,通行約定是兩格。
• 鍵與值之間用半角冒號加一個空格分隔,寫成 key: value;冒號後漏空格是高頻錯誤。
• 清單項目以半角連字號加空格開頭;連字號頂格或縮排均可,但同一份檔案裡要統一風格。
• 值中含冒號、井號、花括號等特殊字元時,整個值用英文雙引號包起;密碼、令牌類欄位建議一律加引號。

config.yaml · 最小骨架

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

proxies:
  - name: "節點甲"
    type: ss
    server: ss.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"

rules:
  - MATCH,節點甲

這份骨架只有九行,已經是一份可啟動的設定:本機 7890 埠口接收代理請求,所有流量經唯一節點轉發。實際訂閱設定在此基礎上擴充節點、策略組與規則,骨架結構不變。後續章節逐一展開每個部分的欄位細節。

通用欄位:埠口、模式與開關

頂層通用欄位控制內核的整體行為:在哪個埠口接收請求、按什麼策略分流、日誌寫到什麼程度、是否允許區域網路共享。圖形用戶端大多把這些欄位映射成設定頁裡的開關,手動編寫時按本節對照即可。

監聽埠口

port 是 HTTP 代理埠口,socks-port 是 SOCKS5 埠口,mixed-port 是混合埠口,同一個入口同時接受 HTTP 與 SOCKS5 兩種連線。目前用戶端普遍只暴露混合埠口,系統代理與瀏覽器擴充功能都指向它。三個欄位可以並存,埠口互不衝突即可;不需要的入口整行省略,內核便不監聽對應埠口。

redir-port 與 tproxy-port 服務於 Linux 透明代理,配合 iptables 轉發使用,桌面使用者一般用不到,路由器與網關情境才會啟用。相關部署流程見 Linux 命令列部署 一文。

執行模式

mode 取三個值之一:rule 按規則清單分流,是日常使用模式;global 把全部流量交給名為 GLOBAL 的內建策略組,即介面上的「全域模式」;direct 全部直連,等於暫停代理。介面上切換模式只是改寫這個欄位並熱載入,設定檔裡的初值決定每次啟動時的預設模式。

日誌與外部控制

log-level 從安靜到囉唆依次為 silent、error、warning、info、debug。日常用 warning 或 info;排查規則命中問題時暫時調到 debug,能看到每條連線的比對過程與命中結果。

external-controller 指定外部控制介面的監聽位址,圖形用戶端的連線面板、延遲測試、設定熱載入都走這個介面。external-ui 指向一套靜態面板檔案,瀏覽器開啟對應位址即可直接管理內核;secret 是介面的存取密鑰,為空表示不驗證。

區域網路共享與其他開關

allow-lan 設為 true 後,同一區域網路的裝置可以把本機作為代理閘道;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 列出不應回傳虛擬位址的網域名稱,命中這些網域名稱時走真實解析。區域網路網域名稱、時間伺服器、需要真實 IP 做服務發現的協定都應列入,否則會出現找不到區域網路裝置、系統時間無法同步一類怪象。

上游伺服器

default-nameserver 負責解析「DNS 伺服器自己的網域名稱」——例如上游寫成 dns.alidns.com 這類網域形式時,得先有一台純 IP 的上游把它解析出來,因此這一層必須填 IP。nameserver 是主上游清單,支援 UDP、TLS、HTTPS 三種寫法。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 是節點清單,清單中每一項描述一個出站節點。四個欄位是任何協定的底線:name 節點名稱、type 協定類型、server 伺服器位址、port 伺服器埠口。其餘欄位隨協定而定。訂閱匯入的節點已由訂閱方生成,手動情境主要是新增備用節點與微調個別欄位。

共同欄位

name 在整份設定裡必須唯一,策略組靠名稱引用節點,重名會讓引用結果不可預期。udp 控制該節點是否轉發 UDP 流量,語音通話、部分遊戲與 QUIC 協定依賴它。sni 指定 TLS 交握時聲明的網域名稱,多數節點要求與節點網域一致;skip-cert-verify 設為 true 跳過憑證驗證,只應在自簽憑證的測試環境使用。alpn 與 client-fingerprint 微調 TLS 指紋;dialer-proxy 指定前置節點,把本節點串在另一個節點之後,構成鏈式中轉。

各協定寫法

config.yaml · 四種協定的節點範例

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 是否齊全,決定了節點能否通過啟動驗證。手動新增節點時,建議先只寫必填欄位跑通連線,再逐項補齊擴充欄位,出問題時的定位範圍會小得多。

策略組欄位

proxy-groups 把節點組織成可選擇的集合。分流規則的目標一般不直接寫節點名稱,而是寫策略組名稱:規則決定「流量交給哪個組」,組決定「組裡目前用哪個節點」。兩層解耦之後,換節點不用動規則,改規則不用動節點。

組類型與選擇方式

測速欄位

url-test、fallback、load-balance 三類組依賴健康檢查。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:
      - "自動選擇"
      - "手動節點甲"
      - "手動節點乙"
      - 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 是內核內建的兩個出站,無需在 proxies 裡定義:DIRECT 表示直連,REJECT 表示直接拒絕連線,常用於廣告與追蹤網域攔截。

組巢狀時,介面顯示的是最外層組,內層組目前的選擇會作為外層組的一個成員出現。把「自動選擇」嵌進 PROXY 之後,日常只需在 PROXY 裡保持選中它,測速與切換都由內層組完成;需要指定節點時,再在外層暫時改選,規則清單全程不用動。

規則語法與匹配順序

rules 是分流的核心。每條連線建立時,內核從清單第一條開始逐條比對,命中即按該條指定的策略組出站,不再繼續向下;全部未命中時由最後的 MATCH 兜底。順序就是優先順序,寫規則的一半功夫花在排順序上。

規則的三段結構

一條規則由逗號分成三段:類型、匹配內容、目標策略組,例如 DOMAIN-SUFFIX,example.com,PROXY。IP 類規則允許追加第四段 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 條目;規則集則把成千上萬條分流規則壓縮成一次引用。

proxy-providers 訂閱來源

每個訂閱是一個具名條目。type 取 http(遠端拉取)或 file(本機檔案);url 是訂閱位址;path 是本機快取路徑,斷網時用快取啟動;interval 是自動更新間隔秒數。health-check 子段為整個訂閱的節點統一開啟測速,欄位與策略組的測速欄位相同。override 子段可以統一改寫訂閱內節點的欄位,例如強制開啟 UDP。

rule-providers 規則集來源

規則集的關鍵欄位是 behavior:domain 表示條目按網域名稱後綴匹配,ipcidr 表示按 IP 網段匹配,classical 表示條目本身是完整規則(帶類型前綴)。前兩種內核會建構專用索引,匹配極快,但檔案裡只能寫純粹的網域或網段清單。format 支援 yaml 與 text 兩種檔案格式。

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 裡手動維護一兩個備用節點,proxy-providers 管訂閱的大批節點,策略組把兩者同時列入。更新訂閱只影響提供方條目,手動節點不受波及——這也是比「全部寫進 proxies」更穩的組織方式。

覆寫與合併

訂閱更新的本質是整份取代:用戶端拉取新設定,舊檔案連同手動改動一起被覆蓋。要長期保住自己的修改,有兩條路——用用戶端提供的覆寫機制把改動做成「補丁」,或者利用 YAML 的錨點語法減少重複、降低維護成本。

用戶端的覆寫機制

主流圖形用戶端都把「訂閱原文」與「使用者改動」分層保存。Clash Verge Rev 提供全域擴充設定(Merge)與腳本兩種覆寫入口,前者按欄位合併,後者用 JavaScript 自由改寫;FlClash 在覆寫頁中增刪改任意欄位;Clash Plus 把介面設定與訂閱設定分開存放,更新訂閱時設定項自動保留。共同點是訂閱檔案保持原樣,使用者改動以補丁形式疊加,每次更新後重新套用。

需要留意的是合併語義因用戶端而異:標量欄位(埠口、模式)一律以補丁為準;陣列欄位(rules、proxies)有的用戶端按條目合併,有的整段取代,有的支援前插後插。改動生效後,最穩妥的確認方式是匯出用戶端最終生成的執行設定,核對目標欄位是否如願,而不是只看覆寫頁裡的補丁文字。

YAML 錨點與引用

手寫設定時,錨點能消除重複:在值前寫 &名字 定義錨點,之後用 *名字 原樣引用;映射類型還可用 <<: *名字 把錨點的鍵值合併進來。多個策略組共用同一份節點清單、同一組測速參數時,錨點讓設定只維護一份真源,改一處即全改。

config.yaml · 錨點重用範例

proxy-groups:
  - name: "自動選擇"
    type: url-test
    url: &test-url http://www.gstatic.com/generate_204
    interval: &test-interval 300
    proxies: &all-nodes
      - "節點甲"
      - "節點乙"
      - "節點丙"

  - name: "備用鏈路"
    type: fallback
    url: *test-url
    interval: *test-interval
    proxies: *all-nodes

驗證與排錯

設定問題集中在三類:YAML 格式錯誤、欄位引用錯誤、規則邏輯與預期不符。按本節的順序排查,絕大多數問題能在幾分鐘內定位。

啟動前驗證

mihomo 內核自帶設定檢查,不必啟動即可驗證:

終端機 · 設定驗證命令

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

輸出 configuration ok 表示語法與欄位檢查通過;失敗時錯誤訊息會帶行號與欄位名稱,按提示回到對應章節核對。圖形用戶端在匯入或儲存設定時也會做同樣的驗證,錯誤彈窗的文字與命令列一致。

高頻錯誤對照

不重啟讓改動生效

圖形用戶端儲存設定即觸發熱載入,無須重啟內核。命令列情境可以請求外部控制介面:向 /configs?force=true 提交 PUT 並帶上新設定路徑即整體重載;fake-ip 快取導致的解析殘留,可清空對應快取介面後重試。規則命中與預期不符時,把 log-level 暫時調到 debug,日誌會逐條印出每條連線命中的規則序號,對照序號回到 rules 清單即可看出是哪一條截了流量。

排錯的一般順序

遇到「改了設定沒效果」時,建議按固定順序排查,而不是反覆重寫整份檔案。第一步確認改動確實已載入:圖形用戶端看設定頁的生效時間,命令列看熱載入介面的回傳;第二步確認流量確實經過內核:系統代理或 TUN 是否開啟,目標應用是否繞開了系統代理設定;第三步才回到規則本身,用 debug 日誌觀察命中序號。三步走下來,問題落在哪一層一目瞭然,再對照前面章節修改對應欄位即可。還有一個容易被忽略的點是快取:瀏覽器、系統代理解析結果與 fake-ip 快取都可能讓舊行為延續幾分鐘,改動後先清快取或換隱私視窗驗證,能避免把快取現象誤判為設定錯誤。

設定之外的問題——訂閱匯入失敗、系統代理不生效、開機自動啟動等——已在 新手十問 中逐條解答;上手主線見 使用文件,用戶端安裝包見 下載頁。