Clash 設定檔
欄位參考

01 · DOCUMENT MODEL

YAML 結構與設定載入順序

頂層欄位不是執行步驟

Clash 設定檔通常命名為 config.yaml，內容由一組頂層鍵組成。常見頂層包括連接埠、運作模式、DNS、代理節點、策略群組、規則以及外部 Provider。它們在檔案中的先後位置主要是為了方便閱讀，並不表示核心嚴格按照書寫順序逐行執行。解析器會先讀取完整 YAML，建立設定物件，再驗證策略群組引用、規則目標與 Provider 定義。因此，把 rules 寫在 proxies 前面未必會直接報錯，但會明顯降低人工檢查效率。建議依照「基礎運作參數 → DNS → 節點 → 策略群組 → Provider → 規則」的順序組織。

YAML 使用縮排表示父子層級，不能以定位字元取代空格。同一層級必須維持相同的縮排寬度，通常使用兩個空格。列表項目以連字號開頭，連字號後的物件仍須遵守縮排。字串大多可以不加引號，但值中含有冒號、井號、大括號、前後空格或容易被識別為布林值的詞時，加上引號更穩妥。例如節點名稱寫成 "HK: Premium"，可避免冒號被解讀為鍵值分隔符；密碼包含 # 時也應加上引號，否則井號之後可能被當成註解。

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

dns:
  enable: true
  enhanced-mode: fake-ip

proxies:
  - name: "Example-SS"
    type: ss
    server: 203.0.113.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "節點選擇"
    type: select
    proxies:
      - "Example-SS"
      - DIRECT

rules:
  - MATCH,節點選擇

純量、列表與映射的差異

mode: rule 是純量；rules 下的多行項目是列表；dns 下由多個鍵值對組成的是映射。設定錯誤經常來自三種結構混用。例如 nameserver 要求列表，如果寫成單一且沒有連字號的字串，某些核心會拒絕載入；proxy-groups 是物件列表，每個策略群組都需要自己的 name 與 type。遇到「欄位類型不正確」時，不要只檢查欄位拼寫，還要確認它應該是字串、數字、布林值、列表還是物件。

YAML 中的 true、false 不應加上引號，因為布林值與字串的語意不同。連接埠通常寫成數字。網域、節點名稱、正規表示式和密碼更適合以字串處理。空值也需要謹慎：只有鍵而沒有值，並不等同於空列表。需要明確清空某項時，覆寫系統可能要求 [] 或 {}，具體取決於目標欄位類型。

引用關係與最終設定

策略群組透過名稱引用節點或其他策略群組，規則末尾再引用策略群組名稱。名稱必須精確匹配，空格、大小寫和全形符號都屬於名稱的一部分。若規則寫著 DOMAIN-SUFFIX,example.com,國外節點，但策略群組實際名稱是「境外節點」，核心無法自動推斷兩者等價。訂閱更新後節點名稱變更，也可能讓手寫的策略群組失去引用目標。

圖形化用戶端顯示的設定不一定就是核心最終讀取的內容。訂閱原文可能先經過用戶端的全域覆寫、腳本處理、代理群組產生和欄位相容性轉換，再產生執行時設定。排錯時應優先尋找「查看最終設定」、「執行設定」或日誌中的載入路徑，而不是只看訂閱編輯器。若用戶端提供設定語法檢查，應先解決解析錯誤，再觀察規則與網路行為；一個縮排錯誤會阻止整個檔案載入，後續網路測試便沒有參考價值。

02 · RUNTIME

連接埠、模式與通用欄位

入站連接埠如何分工

port 是 HTTP 代理連接埠，socks-port 是 SOCKS5 代理連接埠，mixed-port 可在同一個連接埠接受 HTTP 與 SOCKS5 請求。桌面用戶端通常只需啟用混合連接埠，方便系統代理和命令列工具共用同一入口。不要讓多個欄位使用同一個連接埠，也不要與其他代理軟體、開發伺服器或已啟動的 Clash 執行個體衝突。連接埠衝突時，用戶端介面可能仍顯示設定已匯入，但日誌會出現監聽失敗，系統代理之後便會指向無法正常工作的入口。

redir-port、tproxy-port 與 TUN 入站面向透明代理情境，主要由路由器、Linux 閘道或用戶端自動管理。一般 macOS 與 Windows 使用者不需要為了「涵蓋更全面」而同時手動啟用所有連接埠。系統代理模式會處理遵循系統代理設定的應用程式；TUN 模式則透過虛擬網路介面接管更廣泛的流量。兩者可由用戶端依平台能力設定，但連接埠欄位本身不能取代 TUN 驅動程式與路由設定。

allow-lan 與監聽範圍

allow-lan: true 表示允許區域網路存取，但其他裝置是否真的能夠連線，還取決於 bind-address、作業系統防火牆、網路介面與路由器隔離策略。只在本機使用時保持關閉，更容易控制暴露範圍。需要共用時，應確認目前網路可信，並為外部控制介面設定驗證。代理入站與控制介面是兩類服務：開放代理連接埠不代表應該同時把控制 API 暴露在區域網路中。

external-controller 定義外部控制介面，例如 127.0.0.1:9090。圖形化面板透過它讀取連線、切換策略和重新整理設定。繫結至迴路位址時只有本機可存取；繫結至所有介面前，需要理解 secret 的驗證作用並檢查防火牆。若介面可以啟動但無法顯示節點和連線，先核對控制位址是否被佔用、用戶端填寫的控制連接埠是否一致，以及驗證值是否匹配。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "your-controller-secret"

運作模式、日誌與 IPv6

mode 常見值為 rule、global 與 direct。規則模式依 rules 由上至下匹配；全域模式把流量交給全域策略；直連模式跳過代理。日常使用應以規則模式為主，全域模式適合暫時判斷「規則問題還是節點問題」，直連模式可用來確認應用程式本身的網路是否正常。把全域模式當成長期設定，會繞過精細分流，也會掩蓋規則編寫錯誤。

log-level 可控制日誌詳細程度。正常運作使用 info 較合適，排查規則命中、DNS 或握手問題時，可以暫時調整為 debug。詳細日誌可能快速增加，也可能包含存取網域和節點名稱，完成定位後應恢復一般層級。ipv6 決定核心是否啟用相關解析與連線能力，但它不是單獨的網路修復開關；本地網路、DNS 回應、代理節點與規則都需要同時支援。遇到 IPv6 路徑不穩定時，可以先關閉進行對照測試，再決定是否長期調整。

修改設定後，要區分「儲存成功」、「重新載入成功」和「流量已經經過新設定」三種狀態。部分用戶端只儲存文字，不會立即重新載入；部分用戶端在語法錯誤時會保留上一份可運作設定。最可靠的確認方式是查看重新載入日誌、核對目前模式與連接埠，並發起一次可識別的存取來觀察規則命中。若連接埠設定仍不明確，可搭配疑難解答中的系統代理與連接埠問題逐項檢查。

03 · NAME RESOLUTION

Clash DNS、Fake-IP 與解析鏈路

DNS 模組位於哪個環節

啟用 Clash DNS 後，網域解析不再只是作業系統向某個伺服器傳送查詢。核心可以根據規則選擇上游、快取結果，並在 Fake-IP 模式下維護網域與保留位址之間的映射。理解這點有助於區分三類問題：上游 DNS 無法存取、網域被解析到不合適的位址，以及應用程式繞過 Clash 直接發起加密 DNS。代理連線正常但網頁無法開啟時，不應直接把所有故障歸因於節點；需要同時檢查 DNS 監聽、系統 DNS 指向和規則路徑。

dns.enable 控制模組是否啟用，listen 指定監聽位址與連接埠。桌面圖形化用戶端可能自動接管系統 DNS，此時手動修改監聽連接埠會與用戶端管理邏輯衝突。路由器或區域網路服務情境才更常需要明確設定監聽位址。若繫結至區域網路介面，還要確認連接埠未被系統解析服務佔用，並控制可存取範圍。

Fake-IP 與 Redir-Host

enhanced-mode: fake-ip 會先向應用程式回傳一段保留位址，再由 Clash 根據映射還原原始網域並執行規則匹配。它的優點是完整保留網域資訊，規則判斷及時，也減少等待真實位址解析後再轉送的步驟。代價是少數依賴真實位址、區域網路探索或特殊協定的應用程式可能不相容，需要透過 fake-ip-filter 排除。redir-host 更接近傳統的真實位址解析路徑，相容性思路不同，但網域識別與連線鏈路也會受到系統快取和解析時序影響。

fake-ip-range 用於指定保留位址範圍。通常沿用用戶端或核心預設值即可，不應與本地真實網段、VPN 位址池或企業網路路由重疊。若存取某個區域網路網域後被回傳保留位址，優先將該網域加入過濾清單，而不是任意更換整個位址段。過濾規則應盡量精確：單一主機寫完整網域，需要涵蓋子網域時使用支援的萬用字元形式，並在修改後清除應用程式與系統 DNS 快取。

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  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
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://cloudflare-dns.com/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query

三組上游欄位如何搭配

default-nameserver 主要用於解析加密 DNS 上游本身的網域，因此通常填寫可直接存取的 IP 位址。若把所有項目都寫成網域，就可能形成「需要先解析 DNS 伺服器網域，但目前尚無可用解析器」的循環。nameserver 是主要查詢上游，可使用一般 UDP、DoT 或 DoH 位址。proxy-server-nameserver 用於解析代理節點伺服器網域，避免節點網域解析與代理鏈形成依賴。節點伺服器已是 IP 位址時，這一層的影響較小；節點伺服器是網域時則非常關鍵。

nameserver-policy 可以依網域指定不同上游，適合企業內網網域、地域解析或需要獨立處理的服務。它解決的是「查詢交給誰」，不直接決定最終連線經過哪個策略群組。連線分流仍由規則負責。不要把 DNS policy 與代理 rule 混為同一套語法，也不要僅憑解析結果判斷代理是否生效。

dns:
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
    "internal.example":
      - 192.0.2.53
  fallback:
    - tls://1.1.1.1
  fallback-filter:
    geoip: true
    geoip-code: CN

DNS 排錯應依鏈路進行

第一步確認 Clash DNS 是否實際監聽，第二步確認系統或 TUN 流量是否送到該監聽點，第三步觀察查詢使用了哪個上游，最後再檢查連線規則。只修改瀏覽器快取或頻繁切換節點，無法定位 DNS 層問題。日誌若出現上游逾時，應測試該上游在目前網路下能否直接連線；若網域能解析但連線失敗，應繼續檢查規則命中、IPv4 與 IPv6 選擇、節點可用性。若只有個別應用程式異常，還要考慮該應用程式內建的 DoH、QUIC 或快取機制。

04 · OUTBOUND

代理節點欄位與協定參數

所有節點共有的識別欄位

proxies 是代理節點物件列表。每個物件至少包含唯一的 name、協定 type、伺服器 server 與連接埠 port，其餘欄位由協定決定。節點名稱是設定內部的引用鍵，不只是介面標籤。兩個節點使用同名會造成策略群組引用不明，訂閱與本機節點重名也可能在合併時互相覆蓋。建議名稱同時呈現地區、線路或用途，但不要把會頻繁變化的狀態寫進名稱。

server 可以是 IP 位址或網域。使用網域時，需要確保前一章提到的節點網域解析鏈可用。連接埠是遠端服務連接埠，不是本機的 mixed-port。混淆兩者是手動輸入時常見的錯誤。協定欄位必須與伺服器端設定一致，不能透過試改加密方式或傳輸類型來「自動探測」。驗證失敗、TLS 握手失敗與網路逾時代表不同階段，應配合日誌判斷。

Shadowsocks 與 VMess 範例

Shadowsocks 節點主要要注意加密方法與密碼。cipher 必須是核心支援且與伺服器端相同的值。密碼建議一律加上引號，避免特殊字元被 YAML 解讀。若伺服器端還使用外掛程式，需要同時填寫外掛程式名稱與選項，不能只複製伺服器、連接埠和密碼。外掛程式參數通常是映射物件，層級錯誤會導致外掛程式未載入或節點無法使用。

proxies:
  - name: "SS-Example"
    type: ss
    server: 203.0.113.20
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "VMess-Example"
    type: vmess
    server: edge.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    servername: edge.example.com
    network: ws
    ws-opts:
      path: /proxy
      headers:
        Host: edge.example.com

VMess 除了身分欄位外，還可能包含 TLS、WebSocket、HTTP 或 gRPC 等傳輸設定。servername 用於 TLS SNI，WebSocket 的 Host 屬於 HTTP 請求標頭，兩者可能相同，但語意不同。路徑要保留開頭斜線，並與伺服器端入口一致。舊設定中可能出現歷史相容欄位，匯入新核心前應以服務提供者給出的目前參數為準，而不是從其他協定範本拼接。

Trojan、VLESS 與 TLS 相關欄位

Trojan 通常使用密碼驗證並依賴 TLS；VLESS 使用 UUID，並可組合不同傳輸與流控。TLS 類節點最常見的故障是伺服器位址、憑證名稱與 SNI 不一致。skip-cert-verify 會改變憑證驗證行為，不應作為長期修復手段。若憑證驗證失敗，應先確認裝置時間、伺服器端憑證、網域和 servername。只有明確知道測試環境使用哪種憑證時，才適合暫時調整並記錄原因。

  - name: "Trojan-Example"
    type: trojan
    server: gateway.example.com
    port: 443
    password: "your-password"
    sni: gateway.example.com
    udp: true
    skip-cert-verify: false

  - name: "VLESS-Example"
    type: vless
    server: vless.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000001
    tls: true
    servername: vless.example.com
    network: grpc
    grpc-opts:
      grpc-service-name: proxy

UDP、介面與撥號行為

udp: true 表示節點允許轉送 UDP，但伺服器端、協定、用戶端模式和本地網路也必須支援。僅增加此欄位，不會讓不支援 UDP 的線路獲得相應能力。涉及遊戲、語音或 DNS 時，可以從日誌確認流量是否經由 UDP，並檢查策略群組選中的節點是否具備支援能力。某些設定還提供 interface-name、routing-mark 或撥號相關欄位，它們更適合多網卡與閘道環境，桌面使用者不應在不清楚介面名稱的情況下照抄。

節點能通過延遲測試，只能說明特定測試 URL 當時可以建立請求，不代表所有協定與網站都正常。測試位址、TLS 路徑、丟包和頻寬都會影響結果。可繼續閱讀Clash 延遲測試數字怎麼看，再結合實際存取與日誌判斷。若需要更換用戶端進行對照，本網站下載清單維持 Clash Plus 為各平台首推，同時列出 Clash Verge Rev、FlClash、Clash Nyanpasu、ClashX Meta 等適用選項。

05 · POLICY

策略群組欄位與選擇邏輯

select：明確的手動選擇

策略群組會把節點、內建動作和其他策略群組組織成規則可引用的出口。select 是最直接的類型，使用者可在用戶端介面手動選擇其中一項，選擇結果通常由用戶端持久化。它適合總入口、地區選擇和需要固定線路的服務。群組內的 proxies 依名稱引用現有節點或策略群組，也可以包含 DIRECT、REJECT 等內建動作。被引用的物件必須已存在於最終設定中。

策略群組可以巢狀，例如「節點選擇」引用「香港自動」、「日本自動」和「手動選擇」。巢狀能減少規則重複，但層級過深會增加排錯成本。判斷某條連線最終走向時，需要從規則目標開始，依序展開每一層策略群組，直到具體節點或內建動作。命名應反映功能，不要讓多個群組都叫「自動選擇」而無法區分測試範圍。

url-test、fallback 與 load-balance

url-test 會定期請求指定 URL，根據測試結果選擇符合條件的節點。interval 是測試週期，tolerance 用於減少延遲接近時的頻繁切換。測試過於頻繁會增加請求和耗電量，測試間隔過長則無法及時反映線路變化。測試 URL 應穩定、回應內容小，並能代表實際出口連線能力。不要使用需要登入、重新導向複雜或受地區限制明顯的頁面。

fallback 更強調可用性順序：目前節點不可用時切換到後續可用項目。load-balance 會依策略將連線分配到多個節點，適合明確理解工作階段一致性要求的情境。需要固定來源位址的登入、付款或長連線服務，不適合任意使用負載平衡。自動群組的測試結果也不應解讀為真實瀏覽速度排名；它只對應測試位址與當次網路條件。

proxy-groups:
  - name: "節點選擇"
    type: select
    proxies:
      - "香港自動"
      - "手動選擇"
      - DIRECT

  - name: "手動選擇"
    type: select
    proxies:
      - "SS-Example"
      - "Trojan-Example"
      - "VLESS-Example"

  - name: "香港自動"
    type: url-test
    proxies:
      - "SS-Example"
      - "Trojan-Example"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

透過 Provider 動態引入節點

節點來自訂閱 Provider 時，策略群組可以使用 use 引用 Provider 名稱，不必把每個節點寫進 proxies。部分核心還支援 filter 與 exclude-filter 依名稱篩選。篩選通常使用正規表示式，字元範圍與括號必須正確轉義。訂閱命名不一致時，只靠「港」或「HK」可能漏掉節點，也可能誤選包含相同字元的說明項目。應先查看實際節點名稱，再建立篩選表達式。

proxy-groups:
  - name: "香港節點"
    type: select
    use:
      - provider-main
    filter: "(?i)香港|港|HK|Hong Kong"
    exclude-filter: "(?i)遊戲|剩餘|到期"

  - name: "故障切換"
    type: fallback
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 600

健康檢查與連線保持

Provider 的健康檢查與策略群組本身的 URL 測試可能同時存在。前者用於維護節點可用狀態，後者用於群組內選擇；重複且高頻的測試會產生不必要的請求。設計設定時應明確由哪一層負責檢查，並合理設定週期。切換策略群組不保證既有連線會立即遷移，瀏覽器連線池、QUIC 和長連線可能繼續使用舊出口。驗證切換結果時，可關閉原有連線、重新發起請求，必要時清除應用程式連線池，而不是只看介面選項。

規則引用的策略群組應長期存在。訂閱更新可以改變節點列表，但不應任意改變規則目標群組名稱。一個穩定結構通常包含總入口、自動群組、手動群組、直連與拒絕處理，再依業務增加串流媒體、即時通訊或開發服務群組。群組越多不代表分流越準確；只有確實被規則引用且用途清楚的群組才有維護價值。

06 · ROUTING

Clash 規則分流語法與優先順序

規則由上至下首次命中

rules 是有序列表。連線資訊符合某條規則後，核心會使用該條指定的策略，不再繼續檢查後面的普通規則。因此，具體規則應放在寬泛規則之前，兜底的 MATCH 必須位於末尾。例如先寫 DOMAIN-SUFFIX,example.com,DIRECT，再寫 MATCH,節點選擇，目標網域會直連；順序相反時，前面的 MATCH 會接收所有流量，後續規則永遠沒有機會執行。

一條典型規則由「規則類型、匹配內容、策略目標」組成，部分類型還可以附加參數。逗號是欄位分隔符，策略群組名稱必須與設定完全一致。規則列表中的每一行都要作為 YAML 字串項目出現。網域規則不應附帶協定標頭、路徑或連接埠；需要匹配 https://sub.example.com/path 時，應擷取主機名稱，並選擇完整網域、後綴或關鍵字規則。

網域、位址與程序規則

DOMAIN 精確匹配完整網域，DOMAIN-SUFFIX 匹配指定網域及其子網域，DOMAIN-KEYWORD 依網域中出現的關鍵字匹配。後綴規則通常比關鍵字規則更可控。關鍵字過短會擴大命中範圍，例如使用常見的兩個字母，可能誤傷無關網域。需要涵蓋某項服務時，先收集實際請求網域，再決定精確規則與後綴規則的組合。

IP-CIDR 與 IP-CIDR6 依位址段匹配。網域連線是否進入位址規則，取決於解析流程和 no-resolve 參數。對不希望觸發額外 DNS 解析的位址規則，可在支援的語法中使用 no-resolve。GEOIP 依位址歸屬資料庫分類，結果受資料庫來源與更新狀態影響，不應視為業務歸屬的絕對判斷。PROCESS-NAME、PROCESS-PATH 等程序規則依賴作業系統與用戶端權限，在行動裝置、沙盒環境或 TUN 實作中的支援程度可能不同。

rules:
  - DOMAIN,api.example.com,節點選擇
  - DOMAIN-SUFFIX,example.net,節點選擇
  - DOMAIN-KEYWORD,cdn-example,節點選擇
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

規則集合與邏輯組合

大型規則不適合全部寫在主設定中，可以透過 RULE-SET 引用規則 Provider。規則集合只保存匹配條件，主設定負責指定策略目標，讓同一份集合在不同裝置上選擇不同出口。使用時要確認 Provider 的 behavior 與檔案內容一致：domain 適合網域項目，ipcidr 適合位址段，classical 支援完整經典規則。類型不匹配時，檔案可能成功下載，卻無法按預期解析。

部分核心支援 AND、OR、NOT 等邏輯規則。它們適合表達「某個程序存取某個網域」之類的組合條件，但可讀性和跨用戶端相容性低於基礎規則。只有基礎類型無法準確描述需求時才應引入，並在旁邊記錄用途。規則複雜度增加後，命中日誌比肉眼推斷更可靠。

rules:
  - RULE-SET,private,DIRECT
  - RULE-SET,applications,DIRECT
  - RULE-SET,streaming,媒體服務
  - RULE-SET,global,節點選擇
  - GEOIP,CN,DIRECT
  - MATCH,節點選擇

規則未命中的定位方法

先從連線日誌取得實際網域、目標位址、程序和命中的規則，再回到設定檢查。瀏覽器網址列中的主網域不代表頁面只存取這一項，腳本、圖片、驗證和 API 可能分布在多個網域。若日誌只顯示 IP，需要檢查 DNS 是否由 Clash 接管，或應用程式是否直接使用位址連線。若預期規則位於 MATCH 後面，移動順序即可解釋問題；若規則目標群組不存在，則需要修正引用。

規則分流的目標是穩定、可解釋，而不是越多越好。區域網路與保留位址通常優先直連，明確的業務規則居中，地區位址規則靠後，MATCH 負責兜底。每次新增規則後應驗證正向命中與反向影響：目標服務是否前往預期群組，無關服務是否被過寬條件帶走。出現連線代理後仍無法存取網頁的綜合問題時，可按逐項排查清單檢查系統代理、連接埠、節點、DNS 與規則。

07 · EXTERNAL SOURCES

Proxy Provider 與規則集合

Provider 解決什麼問題

proxy-providers 將外部節點來源與主設定分離。主設定保留策略群組和規則結構，Provider 定期更新節點清單。這樣可以在訂閱變更時維持穩定的策略群組名稱，也方便讓多個自動群組引用同一份節點來源。Provider 名稱是內部引用鍵，應保持穩定；更換訂閱位址不需要同時修改所有策略群組，只需更新對應的 Provider 定義。

常見 type 包括 http 與 file。HTTP 類型透過 URL 取得，檔案類型讀取本機路徑。path 指定快取或本機檔案位置，多個 Provider 不應寫入同一個路徑。interval 控制遠端更新週期，設定過短會頻繁請求，設定過長則無法及時接收上游調整。若用戶端有自己的訂閱更新排程，還要確認它是否會覆蓋核心欄位。

proxy-providers:
  provider-main:
    type: http
    url: "https://subscription.example/config.yaml"
    path: ./providers/provider-main.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "訂閱節點"
    type: select
    use:
      - provider-main

Provider 檔案格式與健康檢查

代理 Provider 回傳的內容應符合核心要求，通常包含以 proxies 為鍵的節點列表，而不是完整的主設定。把一般訂閱連結、Base64 節點列表或完整設定直接當成 Provider 檔案，不一定能被目前核心識別。格式轉換應在可信且可控的環節完成，並檢查節點欄位是否在轉換過程中遺失。關於訂閱格式差異，可繼續閱讀Clash 訂閱與其他連結格式如何互相轉換。

health-check 定期驗證 Provider 內的節點。測試 URL 與週期的選擇原則和自動策略群組相同。健康檢查失敗不一定表示訂閱下載失敗：前者是節點測試，後者是 Provider 檔案取得。日誌中應區分 HTTP 更新狀態、檔案解析狀態和節點測試結果。若更新後節點數量為零，先查看快取檔案是否實際寫入，再核對格式與篩選表達式。

rule-providers 的行為類型

規則 Provider 透過 behavior 宣告內容類型。domain 檔案通常保存網域或網域集合，ipcidr 保存 IPv4 與 IPv6 位址段，classical 保存帶類型的完整規則。format 可用於區分 YAML、文字或核心支援的二進位格式。引用時，主規則使用 Provider 名稱並指定策略群組，例如 RULE-SET,private,DIRECT。策略不會固化在 Provider 檔案中，這正是外部規則可以重複使用的原因。

rule-providers:
  private:
    type: http
    behavior: domain
    format: yaml
    url: "https://rules.example/private.yaml"
    path: ./rules/private.yaml
    interval: 86400

  local-network:
    type: file
    behavior: ipcidr
    format: yaml
    path: ./rules/local-network.yaml

rules:
  - RULE-SET,private,DIRECT
  - RULE-SET,local-network,DIRECT,no-resolve
  - MATCH,節點選擇

更新失敗、快取與回退

Provider 更新失敗時，核心通常會嘗試繼續使用既有快取，但具體行為取決於用戶端與快取是否完整。首次載入時沒有快取，遠端位址無法存取會直接導致對應節點或規則缺失；曾成功運作過的裝置則可能繼續使用舊檔案。排錯時要記錄「從未成功下載」還是「之前可用、目前更新失敗」，兩者的處理路徑不同。

遠端規則與節點來源應使用穩定的 HTTPS 位址。URL 中的查詢參數可能包含訂閱識別資訊，不適合寫入公開日誌、截圖或共用設定。需要分享設定結構時，應替換位址和驗證內容，但保留欄位層級。路徑也要考慮用戶端工作目錄：相對路徑由核心執行目錄解析，不一定相對於使用者看到的訂閱檔案。遇到找不到檔案時，查看日誌提供的絕對路徑，比反覆修改 ./ 更有效。

多個 Provider 合併後，節點仍可能重名。策略群組篩選只看最終名稱，無法區分同名節點來自哪個來源。可以由用戶端為不同 Provider 覆寫並加上前綴，或在訂閱管理階段統一命名。更系統化的多設定管理方法可參考Profile 結構入門與多設定管理。

08 · MAINTENANCE

設定覆寫、合併與系統排錯

為什麼需要覆寫層

訂閱設定會在更新時被上游內容取代，直接編輯訂閱正文容易遺失本機修改。覆寫層用於將穩定的本機設定與遠端設定分開，例如連接埠、DNS、策略群組補充和規則前置。不同用戶端對覆寫的稱呼可能是 Override、Mixin、Merge、擴充腳本或設定增強，合併語意也不完全相同。使用前必須確認它採用物件遞迴合併、陣列取代、陣列追加還是腳本處理。

映射欄位通常可以依鍵覆蓋，例如只修改 dns.enable 而保留其他 DNS 子項；陣列欄位則更容易產生差異。若 rules 被整體取代，原訂閱規則會消失；若採用追加，本機規則可能被放在 MATCH 後面而永遠不會命中。策略群組和節點也屬於列表，依名稱合併還是依位置合併會直接影響結果。因此，完成覆寫後必須查看最終設定，而不是只確認覆寫文字的語法正確。

# 範例：概念性覆寫內容，實際合併方式由用戶端決定
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip

rules:
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - DOMAIN-SUFFIX,example.net,節點選擇
  - MATCH,節點選擇

規則前置、追加與刪除

本機規則通常需要放在訂閱規則之前，尤其是要覆蓋寬泛規則時。支援 prepend 與 append 的用戶端，應把精確例外放在 prepend，把真正的補充兜底放在 append。若用戶端只支援取代整個陣列，就要明確承擔後續規則維護。刪除某個遠端規則通常不能靠增加一條相反規則「消除」，只能在它之前增加更精確的規則，或使用用戶端提供的過濾腳本。

清空欄位時要使用正確類型。清空列表一般寫 []，清空映射一般寫 {}，刪除鍵則取決於覆寫實作。把欄位寫成 null 可能代表刪除，也可能把空值傳給核心並觸發類型錯誤。對於不熟悉的合併器，先用一個不重要的小欄位測試，比較合併前後結果，再處理完整規則與策略群組。

從語法到網路的四層檢查

第一層是 YAML 解析。檢查縮排、冒號、列表符號、引號與欄位類型。此層失敗時，用戶端通常會回報行號，但實際原因可能位於上一行，例如引號未閉合。第二層是設定引用。檢查策略群組是否引用存在的節點或 Provider，規則目標是否存在，Provider 路徑是否衝突。第三層是執行時監聽。檢查代理連接埠、控制連接埠、DNS 連接埠與 TUN 是否成功啟動。第四層才是網路行為，包括節點握手、DNS 上游、規則命中和應用程式是否使用系統代理。

最小化設定定位法

複雜設定出現問題時，可以複製一份本機測試設定，只保留一個已知節點、一個 select 策略群組、一條 MATCH 規則和必要的連接埠欄位。先驗證代理鏈路，再逐步加入 DNS、Provider 與規則集合。每加入一部分就重新載入並測試，故障首次出現的位置就是主要調查範圍。這種方法比同時切換多個節點、DNS 與運作模式慢一些，但結果可重複，也能避免問題偶然恢復後無法解釋原因。

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

proxies:
  - name: "Test-Node"
    type: ss
    server: 203.0.113.30
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "TEST"
    type: select
    proxies:
      - "Test-Node"
      - DIRECT

rules:
  - MATCH,TEST

測試完成後，再恢復一般日誌層級，並把驗證過的修改放回穩定覆寫層。若問題只發生在某個平台，還要考慮系統代理實作、權限、TUN 驅動程式和應用程式網路堆疊差異。Windows 的完整安裝與系統代理問題可參考Windows 安裝 Clash 完整流程；一般問題則可在疑難解答中依基礎認知、安裝設定、使用技巧和故障排查分類繼續定位。

維護一份可長期更新的設定

穩定設定應將上游資料與本機意圖分開：訂閱或 Provider 管理節點，主設定管理策略群組與規則，覆寫層保存裝置差異。為策略群組使用穩定名稱，為自訂規則記錄原因，避免重複定義連接埠和 DNS。訂閱更新後檢查最終設定中的節點數量、策略群組引用和 MATCH 位置；用戶端升級後則重點檢查欄位相容性與覆寫合併結果。

需要遷移裝置時，不要只複製單一 YAML。還應記錄 Provider 快取是否可重新下載、用戶端是否儲存策略選擇、系統代理與 TUN 權限如何設定。設定檔描述的是核心行為，作業系統授權和用戶端介面狀態並不完全包含其中。依照這個界線維護，發生問題時才能判斷應修改 YAML、用戶端設定還是系統網路。