Clash 設定檔參考手冊

一、YAML 結構總覽

Clash 的全部行為由一份 YAML 格式的設定檔驅動。用戶端介面上的每一個開關、每一個策略群組、每一條分流規則,最終都對應這份檔案裡的某個欄位。理解它的整體結構,是後續所有修改動作的前提:知道一個欄位屬於哪一段,才知道改動會影響什麼、會不會被訂閱更新覆蓋。

一份完整設定在最上層由若干個固定名稱的段落組成,核心依名稱識別,順序不影響解析。常用段落如下:

• 通用欄位:散落在最上層的標量設定,如 mixed-port、mode、log-level,控制連接埠、代理模式與執行參數;
• dns:網域解析行為,包括是否啟用內建 DNS、Fake-IP 模式與上游伺服器清單;
• proxies:代理節點陣列,每個項目描述一個出口伺服器的協定、位址與憑證;
• proxy-groups:策略群組陣列,把節點組織成可選擇、可自動測速的群組;
• rules:分流規則陣列,決定每一條連線走哪個策略群組或直連;
• proxy-providers / rule-providers:從外部位址或本地檔案引入節點與規則集,便於拆分維護;
• tun:虛擬網路卡模式,接管系統全局流量時使用。

一份能跑起來的最小設定只需要三段:一個入站連接埠、至少一個節點(或直接用 DIRECT)、一條兜底規則。下面的骨架可以直接儲存為 config.yaml 驗證:

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

proxies: []

proxy-groups: []

rules:
  - MATCH,DIRECT

YAML 有幾條硬性的書寫約定,設定解析失敗的多數原因都出在這裡。第一,層級完全由縮排表達,同一層級的縮排寬度必須一致,慣例是兩個空格;第二,冒號後面必須有一個空格,mode:rule 是非法寫法;第三,欄位名稱區分大小寫,Mode 不會被識別為 mode;第四,字串一般可以不加引號,但含有冒號、井號、星號等特殊字元時必須用引號包裹,例如密碼 "p@ss:word#1"。

關於設定檔的存放位置與訂閱更新時哪些段會被整體替換,可參閱站內文章《Clash 設定檔(Profile)結構解析》,本頁第八章也會給出讓本地改動在更新後存活的合併方案。

二、通用欄位:連接埠、模式與執行控制

通用欄位直接寫在設定檔最上層,控制核心以何種姿態運作。這類欄位數量不多,但幾乎每次排錯都要先核對這一段——連接埠衝突、模式選錯、區域網路裝置連不上,根源都在這裡。

2.1 入站連接埠

核心可以同時開啟多種入站監聽。port 是純 HTTP 代理連接埠,socks-port 是純 SOCKS5 連接埠,而 mixed-port 在同一個連接埠上同時識別 HTTP 與 SOCKS5 請求,是目前多數用戶端的預設選擇——系統代理和第三方軟體都指向同一個連接埠,設定最簡單。三者可以並存,但監聽的連接埠號不能重複,也不能與系統上其他程式占用的連接埠衝突;啟動時報 bind: address already in use,就是連接埠被占用,換一個未使用的連接埠號即可。

2.2 區域網路存取

allow-lan 決定入站連接埠是否接受來自本機以外的連線。設為 true 後,同一區域網路內的手機、電視盒子可以把代理伺服器指向這台機器的內網 IP,共享同一套出口與規則;搭配 bind-address 可以限定只在某張網路卡上監聽。開啟前請留意所處的網路環境:在公司或公共 Wi-Fi 上開放區域網路監聽,意味著同網段任何裝置都能使用這個代理連接埠。

2.3 代理模式 mode

mode 接受三個值:rule(依規則段逐條比對分流)、global(所有流量交給全域出口)、direct(所有流量直連)。日常應固定停留在 rule,另外兩種模式是排查工具而非常駐選項——什麼時候臨時切換、切換後如何驗證,站內文章《Clash 三種代理模式怎麼選》有完整的操作順序說明。

2.4 常用通用欄位速查

external-controller 值得特別說明:它開放一個 HTTP 介面,用戶端圖形介面正是透過這個介面切換節點、讀取延遲與流量資料。預設綁定 127.0.0.1:9090 僅對本機開放;若改成 0.0.0.0:9090 供區域網路面板存取,必須同時設定 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 是最容易被忽視的一環:如果網域解析仍然走本地電信業者的明文 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)分配一個虛擬位址回傳給應用程式,同時記住「這個虛擬位址對應哪個網域」;應用程式拿著虛擬位址發起連線時,核心依網域而非 IP 比對規則並轉送。好處是省掉一次解析往返、顯著降低首包延遲,且規則比對始終依網域進行,準確度高。redir-host 則回傳真實解析結果,行為更接近傳統 DNS,相容性好但速度與比對精確度略遜。兩種模式的機制差異,以及區域網路服務與遊戲連線等需要避開 Fake-IP 的情境,站內文章《Clash Fake-IP 模式運作原理》有專門拆解。

使用 Fake-IP 時,某些必須取得真實 IP 的查詢要透過 fake-ip-filter 排除,典型的有區域網路主機名稱、系統連網偵測網域與 NTP 服務:

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

其中 * 比對單層子網域,+ 比對任意多層子網域並包含網域本身。

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

三組伺服器職責不同,不能混為一談。default-nameserver 只能填純 IP,專門用來解析後面兩組加密 DNS 伺服器自身的網域,解決「先有雞還是先有蛋」的問題;nameserver 是主力解析組,建議使用 DoH(https:// 前綴)或 DoT(tls:// 前綴)等加密協定;fallback 是備用組,與 fallback-filter 連動——當主力組的解析結果符合過濾條件(例如 geoip-code: CN 以外的結果),就改用備用組的答案,以此對抗汙染。若不需要這套雙查詢機制,可以只保留 nameserver 一組。

四、代理節點欄位(proxies)

proxies 是一個陣列,每個項目完整描述一個出口節點。訂閱設定裡這一段由服務商產生,通常不需要手寫;但在自建節點、為訂閱補充私有出口,或對照排查「某個節點為何連不上」時,需要能讀懂每個欄位的含義。

4.1 所有通訊協定共有的欄位

無論哪種通訊協定,四個欄位必不可少:name(節點名稱,策略群組透過它引用,同一設定內不能重名)、type(協定類型)、server(伺服器網域或 IP)、port(服務連接埠)。此外 udp: true 聲明該節點支援 UDP 轉送,語音通話、遊戲等依賴 UDP 的應用程式需要它。

4.2 三種常見協定範例

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 核心在這三類之外還支援 vless、hysteria2、tuic、wireguard 等協定,欄位結構遵循同樣的模式:公共四欄位加協定專屬欄位。拿到一個新協定節點時,先確認 type 拼寫與核心支援清單一致,再逐一補齊協定要求的憑證欄位。

五、策略群組欄位(proxy-groups)

如果說 proxies 是原材料,proxy-groups 就是把原材料組織成「可決策單元」的一層。規則段的出口幾乎總是指向策略群組而不是單一節點——這樣換節點時只需要在群組內切換,規則不用動。用戶端主介面上的群組選擇清單,就是這一段的視覺化呈現。

5.1 四種群組類型

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

自動類群組的三個參數直接影響體驗。url 是測速目標,慣例使用回傳 204 狀態碼的輕量位址,測的是「經該節點存取此位址」的完整往返;interval 是測速間隔秒數,過短會產生大量探測流量;tolerance 是切換容差(毫秒)——新的最快節點要比目前節點快出這個差值才會切換,用來避免兩個延遲相近的節點來回抖動。lazy: true 讓群組在未被使用時暫停測速,減少背景開銷。

群組可以引用群組:範例中的「節點選擇」把「自動測速」作為第一個可選項,形成「頂層手動、底層自動」的兩級結構。訂閱設定常見的「香港」「日本」等地區群組,再匯入一個總群組,也是同樣的巢狀結構。兩個保留名稱可以直接出現在任何群組裡:DIRECT 表示直連,REJECT 表示拒絕連線(常用於廣告攔截規則的出口)。需要注意群組與節點共用同一個命名空間,群組名稱不能與節點名稱重複,也不能構成循環引用——A 群組包含 B 群組、B 群組又包含 A 群組會導致載入失敗。

六、規則語法(rules)

rules 段決定每一條連線的去向,是整份設定裡最值得親手維護的部分。每條規則是一行以逗號分隔的文字,基本形態為「類型,比對值,出口」,出口填策略群組名稱、節點名稱或 DIRECT / REJECT。

6.1 比對順序:自上而下,首條命中即停

核心對每條新連線從第一條規則開始逐條嘗試,命中即採用該條的出口,後面的規則不再參與。這個機制推導出規則編排的全部原則:精確規則放前面,寬泛規則放後面,兜底規則放最後。一條 GEOIP,CN,DIRECT 如果被放在了針對某個網域的代理規則之前,而該網域恰好解析到中國大陸 IP,後面的網域規則就永遠不會生效——絕大多數「規則明明寫了卻不生效」的問題都是順序問題。

6.2 常用規則類型

DOMAIN-SUFFIX,example.com 會同時命中 example.com 與 a.b.example.com,是涵蓋一個網站最常用的類型;DOMAIN-KEYWORD 範圍最寬,容易誤傷,只在確認關鍵字足夠獨特時使用。IP 類規則末尾的 no-resolve 參數含義是「如果目前連線的目標是網域而非 IP,跳過這條規則,不要為了比對它而發起解析」——為內網網段規則加上它,可以避免所有網域連線都先被解析一遍拖慢比對。

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,節點選擇

這段編排體現了建議的層次:處理程序與精確網域規則最先,業務網域規則其次,內網網段與地理位置直連靠後,MATCH 兜底收尾。MATCH 之後的任何規則都是死代碼,核心不會報錯但永遠不會執行,自查設定時可以把它當作「規則段結束標記」。自訂規則寫好後如何驗證命中情況,見第九章的日誌方法。

七、外部資源:proxy-providers 與 rule-providers

當節點來自多個訂閱、規則條目成百上千時,把所有內容堆在一份 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 欄位可以並存——一個群組可以同時包含手寫節點和整個訂閱來源。

7.2 rule-providers:規則集的三種 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 聲明規則集檔案的內容形態,三個值不可混用:domain 表示檔案內全部是網域條目,ipcidr 表示全部是網段條目,這兩種形態核心會建立高效索引,適合上萬條的大清單;classical 表示檔案內是帶類型前綴的完整規則行,靈活但比對開銷更高。format 支援 yaml 與 text,需與檔案實際格式一致。主設定裡用 RULE-SET,規則集名稱,出口 引用,這一行在規則段裡的位置仍然遵循第六章的順序原則。

八、覆寫與合併:讓改動在訂閱更新後存活

直接編輯訂閱產生的設定檔有一個根本問題:訂閱更新是整份替換,手動加的節點、改的規則會在下一次更新時全部遺失。解決思路只有一個——把「服務商提供的內容」與「本地自訂的內容」分開存放,由用戶端在載入時合併。各用戶端都提供了這一機制,叫法不同,原理一致。

8.1 用戶端的覆寫機制

下載中心首推的 Clash Plus 提供設定覆寫入口,可以在不改動訂閱原文的前提下追加規則與節點;Clash Verge Rev 提供「合併(Merge)」與「腳本(Script)」兩類擴充設定——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 伺服器等直接跑 mihomo 核心、沒有圖形用戶端的環境裡,沒有現成的合併層,建議把訂閱下載為一份基準檔案,再用腳本或手動把自訂段落拼接成最終設定,更新訂閱時只替換基準部分。目錄組織與 systemd 常駐方案見站內文章《Clash 在 Linux 下的兩條部署路線》。

九、驗證與排錯

設定改完不要直接重新載入了事,先驗證語法、再觀察行為,能把問題定位的時間壓縮到最短。本章提供一套固定的驗證順序。

9.1 載入前:語法驗證

mihomo 核心自帶設定測試參數,不啟動服務、只做解析,幾秒內給出結果:

mihomo -t -f config.yaml

輸出 configuration file test is successful 即語法通過;否則會列印出錯的欄位路徑與行號提示。桌面用戶端在匯入或儲存設定時也會執行同等驗證並彈出錯誤詳情,報錯文案與核心一致,可以直接按下表對照。

9.2 常見報錯對照

9.3 載入後:觀察實際行為

語法通過不代表分流符合預期。把 log-level 暫時調到 debug 後重新載入,用戶端日誌面板會逐條列印連線記錄,格式類似 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 用戶端啟動閃退排查手冊》給出的各平台日誌位置與驗證順序逐項處理。

9.4 下一步

如果讀到這裡你還沒有一個能跑通的基礎環境,建議先回到快速上手按主線流程完成第一次連線,再帶著具體需求回來查對應章節;用戶端本體在下載中心按平台取得,全平台首推 Clash Plus。使用過程中的高頻疑問——開機自動啟動、訂閱失效、節點逾時等——集中整理在常見問題頁,與本頁互為補充。