Clash YAML
設定檔參考

通用欄位：連接埠、模式與控制介面

監聽連接埠如何分工

port 提供 HTTP 代理監聽，socks-port 提供 SOCKS5 監聽，mixed-port 則讓同一個連接埠同時接受 HTTP 與 SOCKS5。桌面圖形用戶端通常只需要一個 mixed-port，系統代理會自動指向它。若其他程式明確要求 SOCKS5 位址，可以單獨設定 socks-port。多個監聽連接埠不能使用同一個連接埠號，也不能與系統中的其他服務衝突。

redir-port 與 tproxy-port 主要用於 Linux 閘道器、路由器或透明代理，桌面使用者不應只為了「涵蓋更多流量」就任意開啟。TUN 模式有獨立的虛擬網卡與路由處理路徑，也不等於簡單增加一個監聽連接埠。需要比較兩種接管機制時，可閱讀TUN 模式與系統代理的差異，先確認流量從哪裡進入核心，再選擇相關欄位。

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"

profile:
  store-selected: true
  store-fake-ip: true

區域網路存取與繫結位址

allow-lan 決定其他裝置能否透過目前裝置的代理連接埠連線。設為 false 時適合單機使用；設為 true 後，還要檢查作業系統防火牆、監聽位址與區域網路隔離設定。開放區域網路存取並不會自動將手機或電視設定為代理，仍需在目標裝置中填入執行 Clash 的區域網路位址與監聽連接埠。位址變更會導致連線失效，因此長期分享時應為主機設定穩定的區域網路位址。

bind-address 用來限制監聽範圍。部分用戶端會依據「允許區域網路連線」開關自動產生此欄位，因此檔案中的值可能在啟動時被介面設定覆寫。疑難排解時應查看實際監聽位址：若只監聽 127.0.0.1，其他裝置無法存取；若監聽所有介面，則應確保控制介面與代理連接埠沒有直接暴露在不受信任的網路中。代理監聽與外部控制介面是兩套服務，不應混淆。

執行模式、記錄檔與狀態保存

mode: rule 會依 rules 由上而下比對，是日常設定的核心。global 會將流量交給全域策略，適合暫時驗證某個節點是否可用；direct 讓請求直接連線，適合確認問題是否由代理路徑引起。圖形用戶端的模式按鈕通常會在執行時切換狀態，不一定會寫回訂閱原始檔案。因此不要只看檔案中的 mode，也要查看用戶端目前的介面狀態。

log-level 常用 info，疑難排解時可暫時提高到 debug，完成後恢復，避免過多記錄干擾判斷。ipv6 控制核心是否處理 IPv6 相關能力，但不能修復本地網路本身缺少 IPv6 路由的問題。開啟後若出現連線等待，應檢查 DNS 是否回傳 IPv6 位址、系統是否有可用的 IPv6 出口，以及規則是否涵蓋對應位址。

external-controller 提供介面與核心通訊的控制位址，通常繫結本機迴路位址。secret 是控制介面的存取憑證，範例值必須替換。它不是代理節點密碼，也不會參與遠端連線。profile.store-selected 可保存策略組選擇，profile.store-fake-ip 可保存 Fake-IP 對映狀態。若訂閱更新後策略選擇總被重設，應同時檢查用戶端自己的持久化選項，而不是只修改 YAML。

代理節點欄位與代理提供者

節點物件的共同結構

proxies 是靜態節點清單，每個清單項目至少包含名稱、類型、伺服器位址與連接埠，再依協定補充驗證與傳輸欄位。name 是整份設定中的引用識別，策略組透過它找到節點。重複的節點名稱會導致選擇與覆寫結果不確定，因此訂閱合併後應檢查名稱是否唯一。server 可以是網域或 IP，port 必須與伺服器實際監聽一致。

協定類型決定可用欄位，不能將一種協定的參數機械式複製到另一種協定。加密方式、使用者識別、傳輸層、TLS 與伺服器名稱都必須與伺服器設定一致。用戶端能載入 YAML，只代表語法與欄位結構基本有效，不表示遠端驗證一定成功。記錄中的握手失敗、驗證失敗、連線遭拒與逾時分別指向不同階段，應依錯誤階段處理。

proxies:
  - name: "SS 示範節點"
    type: ss
    server: ss.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "Trojan 示範節點"
    type: trojan
    server: trojan.example.com
    port: 443
    password: "your-password"
    sni: service.example.com
    skip-cert-verify: false
    udp: true

  - name: "Hysteria2 示範節點"
    type: hysteria2
    server: hy2.example.com
    port: 443
    password: "your-password"
    sni: service.example.com
    skip-cert-verify: false

驗證、TLS 與傳輸欄位

Shadowsocks 節點常見欄位包括 cipher、password 與 udp。加密方法必須與伺服器相同，名稱相近也不能互換。Trojan 類節點依賴 TLS，除了密碼外也經常需要 sni。SNI 表示握手時使用的伺服器名稱，可能與連線位址相同，也可能由服務提供者指定。填寫錯誤時，TCP 連線可能成功，但 TLS 握手會失敗。

skip-cert-verify 控制憑證驗證。正常設定應保持 false，優先修正伺服器名稱、系統時間與憑證鏈問題。將它改為 true 只能用於確認憑證驗證是否為故障點，不應作為通用修復方式。系統時間偏差、受限網路攔截與錯誤的 SNI 都可能產生憑證相關錯誤。只看「連線失敗」四個字不足以判斷原因，必須結合記錄中的握手階段。

VMess、VLESS、TUIC、Hysteria2 等類型還可能包含使用者識別、網路類型、WebSocket 路徑、HTTP 標頭、流量控制或壅塞控制欄位。欄位集合會隨核心能力與伺服器部署方式變化。手動移轉節點時應以原始訂閱與目前核心文件為準，不要只憑另一個節點的外觀補上欄位。關於原版 Clash、Meta 與 mihomo 的名稱及相容關係，可閱讀核心版本選型說明。

proxy-providers 的按需載入

節點較多或需要遠端更新時，可以使用 proxy-providers。提供者是節點集合，策略組透過 use 引用它。常見類型為 HTTP 或本地檔案，遠端提供者包含位址、更新間隔、儲存路徑與健康檢查。儲存路徑應位於用戶端允許寫入的位置；容器或服務模式下還要確認目錄權限。遠端位址中的查詢參數可能包含存取憑證，不應寫入公開記錄或公開範例。

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

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

interval 是重新整理間隔，不代表每次啟動都一定會立即下載。用戶端還可能有自己的更新按鈕與快取策略。health-check 使用固定位址檢查節點可達性，結果用於介面顯示或自動策略選擇，但單一檢測位址不能代表所有網站都可存取。檢測失敗時，先確認測試位址在目前網路中可達，再判斷節點是否故障。

proxies 與 use 可以在同一策略組中同時出現：前者列出固定節點或內建動作，後者引入提供者集合。覆寫工具處理這兩類欄位時的行為可能不同，追加靜態節點不一定會自動加入提供者。訂閱更新後節點消失，通常應檢查遠端提供者是否重新整理成功、儲存路徑是否可寫，以及策略組是否仍引用正確的提供者名稱。

規則語法、比對順序與規則集

規則依由上而下的順序比對

rules 是有順序的清單。請求遇到第一條符合的規則後就會停止繼續檢查，因此具體規則應放在寬泛規則之前，末尾使用 MATCH 承接其餘流量。若將 MATCH 放在頂部，後續規則永遠不會生效。若先寫寬泛的網域後綴，再寫子網域的特殊規則，子網域也會被前一條規則提前接走。

規則通常由「類型、比對值、策略目標」組成，部分規則還可以附加參數。逗號是欄位分隔符，策略名稱必須存在於 proxy-groups 中，或使用 DIRECT、REJECT 等內建動作。規則行中的多餘空格可能成為值的一部分，手動編輯時應保持格式一致。

rules:
  - DOMAIN,api.example.com,節點選擇
  - DOMAIN-SUFFIX,example.com,節點選擇
  - DOMAIN-KEYWORD,example,節點選擇
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - PROCESS-NAME,example-app.exe,DIRECT
  - GEOIP,CN,DIRECT
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-domain,節點選擇
  - MATCH,節點選擇

網域、位址與程序規則

DOMAIN 只比對完整網域，適合單一主機；DOMAIN-SUFFIX 比對指定網域及其子網域，適合完整網站範圍；DOMAIN-KEYWORD 只要網域包含關鍵字就可能命中，涵蓋範圍最廣，也最容易誤傷。能使用完整網域時不要使用關鍵字，能使用明確後綴時不要寫過短的片段。

IP-CIDR 與 IP-CIDR6 依目標位址範圍比對。區域網路、容器網段與公司內網通常應優先直連，但位址範圍必須符合實際網路。no-resolve 表示比對時不為取得 IP 而額外解析網域，可避免不必要的 DNS 查詢。它不表示禁止已有 IP 流量，也不會改變應用程式自身已完成的解析。

PROCESS-NAME 與程序路徑類規則依賴平台能力、權限及接管方式。系統代理模式下，並非所有流量都能可靠取得程序資訊；行動平台也可能不支援相同的程序規則。跨平台設定應將網域與位址規則作為基礎，程序規則則作為特定裝置上的補充。出現桌面端命中而手機端未命中時，先檢查規則類型是否具備平台可攜性。

GEOIP 依 IP 資料庫分類，GEOSITE 或規則集則依網域集合分類，實際可用能力取決於核心與資料檔案。資料庫規則方便涵蓋大範圍目標，但分類資料有更新週期，不能取代明確的業務規則。需要強制某個網域使用指定策略時，應將精確規則放在資料庫規則之前。

rule-providers 管理大型規則集

大量規則適合放入 rule-providers。每個提供者需要名稱、類型、行為、來源、儲存路徑與更新間隔。behavior 決定內容格式：網域集合、IP 位址範圍或傳統規則行不能混用。提供者下載成功不代表已參與分流，還必須在 rules 中使用同名的 RULE-SET。

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

  service-domain:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/service-domain.yaml

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-domain,節點選擇
  - MATCH,節點選擇

domain 行為適合網域或網域後綴集合，ipcidr 適合位址範圍，classical 允許傳統規則表示式。遠端內容格式必須與宣告一致。若提供者檔案本身包含完整的 payload 結構，儲存後由核心依對應格式讀取；若將普通訂閱檔案誤當成規則集，設定會在解析階段報錯。

規則集重新整理失敗時，先查看網路請求狀態，再檢查儲存目錄權限與檔案格式。舊快取仍可能繼續運作，因此「目前仍可存取」不能證明更新成功。服務模式下，相對路徑以執行目錄或用戶端設定目錄為基準，不一定是 YAML 檔案所在的目錄。移轉裝置後規則提供者失效，路徑差異是常見原因。

驗證規則命中，不要只憑結果猜測

用戶端連線記錄通常會顯示目標網域、命中的規則與最後採用的策略。測試時應先清除瀏覽器既有連線或使用新的請求，否則重用連線可能會繼續沿用舊策略。修改規則後重新載入設定，再查看新連線是否命中新規則。只看網頁能否開啟，無法區分它使用直連還是代理。

自訂規則應從少量精確項目開始。先寫一條明確的網域規則，確認命中後，再逐步擴大到後綴或規則集。若新增規則導致大量網站異常，立即檢查是否使用了過短的關鍵字、過寬的位址範圍或過早出現的 MATCH。規則分流的核心不是數量，而是順序清楚、目標存在且範圍可解釋。

設定檢查、載入流程與故障分層

先檢查語法，再檢查網路

設定故障應依固定順序處理：檔案編碼與 YAML 語法、欄位結構與引用、監聽連接埠、DNS、節點連線、策略組、規則命中、應用程式接管。上一層尚未通過時，不要跳到下一層。語法錯誤會讓整份設定無法載入，節點錯誤只會影響對應連線，規則錯誤則可能讓流量走錯策略。釐清故障範圍，才能避免無目的地更換所有設定。

圖形用戶端通常提供設定檢查或重新載入按鈕。伺服器端與命令列環境可使用目前核心提供的測試參數，但具體可執行檔名稱與參數應以安裝包內的說明為準。檢查命令必須指向實際設定目錄；相對路徑錯誤時，可能測試了另一份同名檔案。看到「設定有效」後仍需觀察啟動記錄，因為連接埠佔用、目錄權限與網路連線屬於執行階段問題。

# 範例：先進入實際設定目錄，再呼叫目前核心的設定檢查參數
cd /path/to/clash-config
mihomo -t -d .

# 查看本機連接埠是否已被佔用時，可依作業系統使用對應工具
# Linux
ss -lntup

# Windows PowerShell
Get-NetTCPConnection -State Listen

解析錯誤的常見位置

錯誤訊息包含行號時，應同時查看該行與上方數行。YAML 解析器往往要到無法繼續理解時才報錯，真正問題可能是前一行漏了引號、冒號後缺少空格或清單縮排中斷。若提示映射鍵重複，搜尋同一層級的同名欄位；若提示型別不符，檢查原本應為清單的位置是否少了短橫線，或整數是否誤寫成物件。

從聊天軟體或富文字複製的內容可能包含全形冒號、彎引號、不換行空格與不可見字元。最穩妥的處理方式是在純文字編輯器中重新輸入問題行。中文策略組名稱可以正常使用，但標點應保持普通半形 YAML 分隔符。註解必須從井字號開始，並與有效值保持適當空格。

設定可以解析但提示目標不存在時，檢查節點名稱、提供者名稱、策略組名稱與規則集名稱。常見情況包括策略組引用了已被訂閱更新重新命名的節點、規則指向被覆寫刪除的組、RULE-SET 名稱與提供者鍵不一致。搜尋名稱時應包含引號內的完整文字，注意結尾空格與相似字元。

連接埠、系統代理與 TUN 的分支

用戶端顯示正在執行但應用程式無法連網，先確認監聽連接埠是否存在，再核對系統代理位址。若 YAML 的 mixed-port 已改為新值，而系統代理仍指向舊值，瀏覽器會立即連線失敗。若只有不遵循系統代理的應用程式無法接管，表示基礎代理可能正常，需要評估 TUN，而不是繼續修改節點協定。

開啟 TUN 後完全斷網，應檢查權限、虛擬網卡、路由、DNS 接管與其他網路軟體衝突。先關閉 TUN，確認系統代理路徑可以運作，再單獨處理 TUN。若關閉用戶端後仍無法上網，檢查系統代理是否仍開啟、虛擬網卡路由是否恢復。不要在同一項測試中同時啟用多個代理用戶端，它們可能爭用系統代理、連接埠與路由。

節點可用性與規則命中的驗證

節點測試失敗時，先區分 DNS 解析失敗、TCP 連線逾時、連線遭拒、TLS 握手失敗與驗證失敗。解析失敗檢查節點伺服器網域與 proxy-server-nameserver；逾時檢查網路與遠端位址；遭拒通常表示目標連接埠沒有接受連線；握手失敗檢查系統時間、SNI 與憑證；驗證失敗檢查密碼、使用者識別與協定欄位。不同錯誤不能用相同的修復方式處理。

節點測試成功但目標網站失敗時，查看連線記錄中的命中規則與策略。若命中 DIRECT，問題在規則順序或模式；若命中預期節點，繼續檢查目標網域解析、節點出口與網站端限制。暫時切換到全域模式可用於區分規則問題，但測試後應恢復規則模式。全域模式能存取並不代表原規則正確，只表示某個代理路徑可用。

建立最小可工作的設定

複雜設定無法定位問題時，可以從一個連接埠、一個節點、一個手動策略組與兩條規則開始。確認它能載入並連線後，再依序加入 DNS、自動策略、規則提供者與 TUN。每加入一層就保存可正常工作的副本。這個過程比在數千行訂閱中反覆猜測更快，也能明確了解用戶端與核心實際支援哪些欄位。

最小設定測試使用的節點必須確認資訊完整，測試網域也應保持穩定。若最小設定仍然失敗，問題多半不在規則集，而在節點、系統網路、權限或用戶端安裝。此時可回到使用文件核對初始化步驟，或閱讀訂閱、模式與連線狀態十問。需要重新安裝時，從下載中心選擇對應平台，桌面與行動平台都優先查看 Clash Plus。

完成疑難排解後，應將暫時的 debug 記錄、寬泛測試規則與憑證驗證變更恢復為正常設定。刪除不再使用的連接埠、重複策略組與失效提供者，並為自訂部分寫上簡短註解。設定的長期可維護性取決於每個模組都有清楚職責，而不是欄位數量。能夠說明每條規則為何存在、每個組引用誰、每個 DNS 解析器負責什麼，才是一份可以持續更新的設定。

從可執行設定繼續

尚未安裝用戶端時，先依平台取得安裝包；已完成安裝但不熟悉介面操作時，依快速入門流程匯入訂閱、選擇策略並驗證連線。

前往下載中心 查看使用文件