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,节点选择

规则未命中的定位方法

先从连接日志获取实际域名、目标地址、进程和命中的规则，再回到配置检查。浏览器地址栏中的主域名不代表页面只访问这一项，脚本、图片、认证和接口可能分布在多个域名。若日志只显示 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、客户端设置还是系统网络。