Clash Configuration File Reference

01 / YAML STRUCTURE

YAML structure overview

What makes up a configuration file

A Clash configuration file is a YAML mapping. Top-level keys define listening ports, operating mode, DNS behavior, proxy nodes, proxy groups, rules, and external providers. When the core reads the file, it parses the YAML syntax first, checks field types and references, and then builds the runtime links between proxies, groups, and rules. Valid syntax only means the YAML can be read; it does not mean every node will connect or every group reference is complete. Troubleshooting therefore requires four separate checks: text syntax, field structure, name references, and network connectivity.

Common top-level sections include mixed-port, allow-lan, mode, log-level, external-controller, dns, proxies, proxy-groups, rules, proxy-providers, and rule-providers. Not every configuration needs all of them. When the client UI manages the system proxy, it may generate the port and controller address; when a subscription provider generates the configuration, nodes and proxy groups are usually updated with the subscription. The key point in a hand-written configuration is to distinguish core runtime settings from fields that may be replaced during a subscription refresh.

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

external-controller: 127.0.0.1:9090

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query

proxies:
  - name: Example-Trojan
    type: trojan
    server: proxy.example.com
    port: 443
    password: "your-password"
    sni: proxy.example.com

proxy-groups:
  - name: Node Selection
    type: select
    proxies:
      - Example-Trojan
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,Node Selection
  - MATCH,Node Selection

The example shows the smallest complete relationship loop: the rule sends the request to “Node Selection,” and the proxy group then sends it to a specific node or DIRECT. The target name at the end of a rule must exactly match the proxy group name, and node names in the group must match entries under proxies. Name comparisons generally distinguish characters, spaces, and full-width versus half-width forms. “Node Selection” and “Node Selection ” look similar but are different names. When renaming anything, update every reference.

Indentation, sequences, and scalars

YAML uses indentation to express nesting. Two spaces are recommended; tabs should not be used. Items beginning with a hyphen form a sequence, such as each node under proxies and each rule under rules. Keep a space after colons. Quoting strings that contain colons, hash marks, brackets, or leading or trailing spaces helps avoid ambiguity. Passwords, UUIDs, domains, and node names should generally be treated as strings; ports, intervals, and concurrency counts are usually numbers; switches use true or false.

When it is not inside quotes, a hash mark starts a comment. For example, password: abc#123 may treat only abc as the value; the correct form is password: "abc#123". Boolean values should also use explicit true and false rather than words that different YAML parsers may interpret inconsistently. Commas in a node name do not directly corrupt the node object, but using that name in comma-separated rules or shorthand fields can create parsing ambiguity. Keep node and proxy group names short, unique, and free of control characters.

Parse order and reference checks

The order in which fields are written mainly serves readability. Top-level sections do not need a fixed order, but the order of rules affects execution. Nodes may appear before proxy groups, and groups may appear before rules; the core resolves references after parsing the complete configuration. When an error says a proxy cannot be found or a group does not exist, copy the reported name and compare it character by character with the definition, then check whether the name is supplied dynamically by a Provider. If a Provider has not loaded successfully, groups that depend on it may temporarily be empty.

Test the complete configuration file rather than validating only a YAML fragment. A fragment can pass syntax checks and still have the wrong nesting when placed back in the original file. When the client reports an invalid configuration, keep a copy of the original and remove recently added sections block by block to locate the error by binary search. If the problem began after a subscription update, see Subscription URLs and Configuration Import to confirm whether you imported a subscription URL, a complete YAML file, or content containing only node information.

02 / GENERAL FIELDS

Common fields: ports, modes, and the control interface

Choosing listening ports

port is for HTTP proxies, socks-port is for SOCKS5 proxies, and mixed-port accepts both HTTP and SOCKS5 requests on one port. A desktop client usually needs only one mixed-port; applications can then use 127.0.0.1 and the selected port as the proxy address. A listening port is a local entry point, not the port of a remote node. The port inside a node object is the remote server port. The names are the same, but their levels and purposes differ.

A listening port cannot duplicate a port already occupied by another program. If startup logs show “address already in use,” “bind failed,” or similar messages, close any leftover process first or change the local listening port to an unused value. If the client UI writes port settings automatically, use the final runtime configuration generated by the UI as the source of truth. Editing only the original subscription file while the client later applies a local override can leave the running port different from the file.

allow-lan and bind addresses

allow-lan controls whether devices on the local network can use this machine's proxy. With false, it normally serves local connections only; with true, you must also consider bind-address, the operating system firewall, and the current network type to determine whether other devices can connect. Enable LAN proxy sharing only on a controlled network, and define clear access boundaries for the control interface and proxy entry point. On public networks, do not expose the controller or proxy port to untrusted devices.

mixed-port: 7890
allow-lan: true
bind-address: 0.0.0.0
authentication:
  - "device-user:your-password"

Authentication in the example applies to the proxy entry point. The exact support for authentication fields depends on the client and core in use. If only local access is needed, keeping allow-lan: false is the most straightforward option. If a LAN device cannot connect, check the machine's LAN address, the port's listening scope, inbound firewall rules, whether both devices are on the same network, and whether the mobile device has the wrong proxy type.

Three commonly used mode values

mode: rule matches rules from top to bottom and is the standard mode for everyday use. mode: global sends connections to a global proxy group, which is useful for temporarily checking whether a node works but bypasses fine-grained routing. mode: direct connects directly and helps determine whether the proxy path is causing a problem. During troubleshooting, switch modes briefly for comparison, then return to the intended mode; do not use global mode as a permanent substitute for fixing missing rules.

The mode only determines how traffic enters the policy system. It does not automatically fix DNS resolution, a disabled system proxy, a TUN interface that has not taken over traffic, or applications that bypass the proxy. If a browser works but a command-line tool does not, the browser may be following the system proxy while the command-line program ignores it. Set an HTTP or SOCKS5 proxy explicitly for the program, or use a correctly configured TUN mode.

Logs, IPv6, and the controller

Common log-level values include silent, error, warning, info, and debug. info is usually enough for normal operation. Temporarily switch to debug when investigating configuration or connection issues, then switch back to avoid excessive log noise. When reading logs, find the earliest error rather than focusing only on the last line; many later connection failures may be cascading effects of an initial DNS or configuration error.

ipv6 controls whether IPv6-related network behavior is enabled in the core. Enabling it blindly when the network lacks a stable IPv6 route can produce usable DNS results but an unusable connection path. The DNS section also has an independent dns.ipv6 setting that controls whether AAAA records are returned. Set top-level IPv6 and DNS IPv6 according to the actual network conditions rather than changing only one of them.

external-controller is the control interface used by the client UI to communicate with the core, commonly written as 127.0.0.1:9090. Binding it to the loopback address limits access to the local machine. If secret is set, the controlling client must provide the matching credential. The controller port and proxy port serve different purposes; never point system proxy settings at the controller port. Graphical clients usually manage these fields automatically, so confirm whether the client overwrites them at startup before editing them manually.

03 / DNS PIPELINE

DNS configuration and resolution paths

What the DNS module handles

The DNS section determines which resolver handles domains, which transport is used, whether Fake IP addresses are returned, and whether DNS requests themselves go direct or through the proxy. When a browser reports a connection failure, check the node path and DNS path separately: a node can connect without the domain resolving correctly, and DNS can return an address without making that address reachable through the selected path. The goal of DNS configuration is to keep the resolution source, routing rules, and actual connection exit aligned.

dns.enable turns on the core DNS module. It is usually needed with TUN, Fake IP, or any setup where the system resolver must not fall out of sync with proxy routing. listen specifies the DNS service's listening address, such as 0.0.0.0:1053. A desktop GUI may handle DNS internally without requiring direct access to this port; routers and gateways often forward LAN devices' DNS requests here. When listening on a LAN address, also consider firewall rules and the access scope.

dns:
  enable: true
  listen: 0.0.0.0: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://1.1.1.1/dns-query
  proxy-server-nameserver:
    - https://1.1.1.1/dns-query
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query

default-nameserver and nameserver

default-nameserver is mainly used to resolve the hostnames of encrypted DNS servers and provide basic resolution before upstream connections are established. It should usually contain directly reachable IP-based DNS servers rather than only DoH addresses that themselves require hostname resolution; otherwise the setup can create a dependency loop. nameserver lists the main upstream resolvers and may use ordinary UDP DNS, DoT, or DoH. Choose upstreams based on local reachability and routing paths, not on protocol complexity alone.

proxy-server-nameserver resolves proxy server hostnames. If a node's server is a domain, the core must resolve it before connecting to the node; incorrectly making this step depend on a proxy that has not been established creates a startup loop. Providing a separate, directly reachable resolver for proxy servers reduces this risk. Using an IP for the node server avoids resolution, but address changes can no longer be updated automatically through DNS.

nameserver-policy assigns upstream resolvers by domain or geosite category. It answers “which DNS servers should query this class of domain?” rather than “which proxy should the final connection use?” The connection exit is still determined by rules. DNS policies and traffic rules may use similar domain sets, but they operate at different stages. Whenever one is changed, confirm that the other still matches the intended behavior.

Fake IP and Redir Host

enhanced-mode: fake-ip returns mapped addresses from a reserved range for domains. When an application connects to one of these addresses, the core restores the original domain from the mapping and then applies rules and proxy routing. This preserves domain context and avoids losing routing information when an application resolves the real address through the system first. Use a dedicated reserved range for fake-ip-range; do not overlap it with the current LAN, VPN, or other virtual-network subnets.

Some LAN services, device discovery, time synchronization, gaming platforms, and applications that require real address results do not work well with Fake IP and can be added to fake-ip-filter. A filter that is too broad sends many domains back to real resolution and weakens Fake IP consistency; one that is too narrow can prevent LAN services from being discovered or cause applications to reject reserved addresses. Add entries individually based on logs and the actual domains instead of copying an oversized list from an unknown source.

redir-host returns the real resolved address and continues matching during connection setup. It works well with some traditional transparent proxy environments, but domain context may be insufficient on certain paths. Before choosing an enhanced mode, determine whether the client uses TUN, a system proxy, or router-based transparent proxying, then verify compatibility with the actual applications. After switching modes, clear the operating system and browser DNS caches; otherwise old results may affect testing.

DNS troubleshooting order

First confirm that the core DNS module has started and that the logs contain no port-conflict or configuration-parse errors. Next, query an ordinary domain directly and check whether it returns a result; in Fake IP mode, a reserved address is expected. Then test whether the node server hostname resolves through proxy-server-nameserver. After that, check which rule matched the target domain and which proxy group handled the connection. Finally, verify that the operating system is not still sending DNS requests through another interface.

DNS leaks usually concern which resolution requests bypass the expected path. Seeing different DNS services return different results does not by itself identify the cause. A browser may have its own secure DNS, the system may retain another network interface, and an application may issue DoH requests independently. During troubleshooting, standardize the DNS paths used by the browser, system, and core before restoring optional features one by one. In a TUN setup, also confirm that DNS hijacking covers both UDP and TCP queries.

04 / PROXY DEFINITIONS

Proxy node fields

Common structure of a node object

proxies is a sequence of node objects. Each object needs at least a unique name, protocol type, server server, and remote port; authentication and transport fields depend on the protocol. A node name is only a local reference label and does not change server parameters. For easier group and rule maintenance, names should indicate region or purpose while remaining stable. If a subscription changes names on every refresh, direct references in hand-maintained groups can break.

server can be a domain or an IP address. A domain makes server migration easier but depends on DNS; an IP avoids one lookup but must be updated when the address changes. udp indicates whether the node is allowed to handle UDP traffic, but actual support also depends on the protocol, server, and network path. Turning on a UDP option in the client cannot give UDP capability to a server that does not support it.

Shadowsocks and Trojan examples

proxies:
  - name: Example-SS
    type: ss
    server: ss.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

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

The Shadowsocks cipher must match the server, and the password should be treated as a string. Different encryption methods have different key requirements; changing only the client label is not enough. Trojan commonly connects over TLS, with sni specifying the server name sent during the TLS handshake; it should generally be the domain required by the server. skip-cert-verify: false enables normal certificate verification. If the certificate name does not match, first check the server domain, SNI, system time, and server certificate configuration rather than disabling verification as a long-term fix.

VMess and VLESS identity and transport fields

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

  - name: Example-VLESS
    type: vless
    server: vless.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000000
    network: tcp
    tls: true
    servername: vless.example.com
    udp: true

uuid is an authentication identifier and must use the standard format and match the server. The example UUID is for illustrating structure only and cannot be used as a real connection parameter. Fill VMess fields such as alterId and cipher with the values supplied by the server. VLESS transport and flow-control fields depend on the server setup; client support for a field does not mean adding it manually will make the server compatible.

network describes the transport form, such as TCP, WebSocket, or gRPC. With WebSocket, ws-opts.path and the Host header must match the server's reverse-proxy configuration. With gRPC, verify the service name. TLS parameters including servername, SNI, ALPN, and fingerprint fields are part of the handshake; any mismatch with the server entry point can appear as an immediate disconnect after connection establishment.

Do not copy protocol fields between nodes wholesale

There is no complete node-field table that applies to every protocol. Fields with the same name may also have different constraints across core versions or protocol implementations. The safest source is the parameter set supplied by the server or subscription generator, organized according to the structure supported by the current core. Copying an entire set of TLS, WebSocket, or plugin parameters from another node can leave fields present but semantically incompatible. The parser may accept them while the connection still fails.

Subscription links are normally maintained by the provider. Users generally need to change node names, proxy group organization, and routing rules rather than low-level protocol fields. If every node becomes unavailable after importing a subscription, check subscription validity, system time, DNS, and the local network first. If only one node fails, compare that node's server, port, authentication, and transport settings. For node selection methods, see Evaluating Latency, Region, Multipliers, and Protocols.

Limits of node availability and latency tests

A latency test usually requests a test URL and records the completion time. It reflects one route at one moment, not the quality of access to every website. A timeout may result from an unreachable node, a blocked test address, DNS failure, or an incorrect proxy group reference. Low latency does not guarantee better bandwidth, stability, or access to a target region. Choose nodes using repeated tests, the actual target sites, and sustained connection behavior.

If a node object loads successfully but does not appear in a proxy group, the group may not reference it, or a Provider filter may exclude it. When a subscription changes node names, references in a static proxies list can also stop working. For long-term maintenance, use proxy-providers with use and organize nodes with stable filters instead of repeating large name lists across multiple groups.

05 / POLICY GROUPS

Proxy group fields and selection logic

Proxy groups are the layer between rules and nodes

proxy-groups organizes nodes, built-in actions, and other proxy groups into selectable exits. Rules generally point to a stable group such as “Node Selection,” “Streaming,” or “Downloads,” rather than to a node name that may change. When subscription nodes change, only the group members need updating instead of every rule. Groups can be nested, but avoid circular references: if A references B and B references A, the configuration cannot form a valid exit path.

Common built-in targets include DIRECT, REJECT, and other actions supported by the compatible core. DIRECT connects without a proxy, while REJECT denies the request. A rule target can be a proxy group, a specific node, or a built-in action. For maintainability, have rules point to proxy groups except in a few fixed cases, and let the group determine the actual exit.

select, url-test, fallback, and load-balance

select is the easiest to understand: member order controls the display order, and the client saves the current choice. url-test requests a specified URL at regular intervals and selects automatically based on the results. interval controls the check interval, while tolerance reduces frequent switching when results are close. Checks that run too often create extra node requests; intervals that are too long fail to reflect path changes promptly. The test URL should be stable, return a small response, and represent the expected network path.

fallback keeps members in priority order and selects the next available member when the current one fails, making it suitable for clear primary-and-backup setups. load-balance distributes connections among multiple nodes, with the exact behavior determined by fields such as strategy. It does not split one download across multiple nodes and cannot exceed the bandwidth limits of a single node or the target server. When a session must keep a stable exit, choose a strategy that preserves consistency.

proxy-groups:
  - name: Node Selection
    type: select
    proxies:
      - Automatic Selection
      - Failover
      - DIRECT

  - name: Automatic Selection
    type: url-test
    proxies:
      - Example-SS
      - Example-Trojan
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: Failover
    type: fallback
    proxies:
      - Example-Trojan
      - Example-SS
    url: https://www.gstatic.com/generate_204
    interval: 300

Nested proxy groups and service layers

A clear hierarchy usually contains “main entry — region or automatic selection — specific nodes.” For example, rules send ordinary proxy traffic to “Node Selection”; that group contains “Automatic Selection,” “Failover,” and several regional groups, while each regional group contains its corresponding nodes. Users can then rely on an automatic policy or pin a region manually. Avoid excessive nesting, which makes both the selection path and troubleshooting longer.

Service groups express exit requirements rather than simply copying node lists. For example, “Streaming” can reference regional groups, “Development Services” can reference the main selection group, and “Direct Services” can contain only DIRECT. When several service groups reference one regional group, node maintenance stays centralized. Repeating dozens of nodes in every service group makes membership differences and omissions likely after subscription updates.

Provider members and filtering

A proxy group can use use to reference one or more proxy-providers and obtain members dynamically from external node sets. Some cores also support filters such as filter and exclude-filter. Filters usually use regular expressions, so validate them against a small number of names first. A region keyword may also appear in plan descriptions, multiplier markers, or unrelated node names; expressions that are too broad include unwanted entries, while those that are too strict can produce an empty group.

proxy-groups:
  - Hong Kong Nodes
    type: url-test
    use:
      - subscription-main
    filter: "(?i)香港|HK|Hong Kong"
    url: https://www.gstatic.com/generate_204
    interval: 300

  - name: Node Selection
    type: select
    proxies:
      - Hong Kong Nodes
      - DIRECT
    use:
      - subscription-main

When both proxies and use are present, the group combines static and Provider members according to the core's supported behavior. If the UI shows many duplicate nodes, check whether the same node is both written statically and imported from a Provider. If an automatic group is empty, first check that the Provider downloaded successfully, then inspect the filter expression, and finally verify that Provider node names match expectations.

06 / RULE ENGINE

Rule syntax and matching order

Top to bottom; stop at the first match

rules is an ordered sequence. When a connection arrives, the core checks entries from the top and sends the request to the policy specified by the first matching rule; later entries are not checked. Put specific rules before broad ones and keep the fallback rule last. Placing MATCH in the middle prevents all later rules from running. Likewise, putting a broad domain-suffix rule before an exact domain can hide the special handling below it.

Most rules use a comma-separated structure: rule type, match value, and target policy; some also accept extra parameters. For example, DOMAIN-SUFFIX,example.com,Node Selection sends example.com and its subdomains to “Node Selection.” The target name must exist. A comma in a name breaks the delimiter structure, so avoid commas in proxy group names.

rules:
  - DOMAIN,api.example.com,Node Selection
  - DOMAIN-SUFFIX,example.com,Node Selection
  - DOMAIN-KEYWORD,example,Node Selection
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

Differences between domain rules

DOMAIN matches only the complete domain and suits a specific API host or single service requiring a special exit. DOMAIN-SUFFIX matches the specified domain and its subdomains, making it useful for routing an entire site. DOMAIN-KEYWORD can match whenever a keyword appears in the domain, providing broader coverage but also a greater risk of false matches. When an exact domain is available, do not use a broad keyword just to save a few lines of configuration.

Domain matching depends on the core having domain information during connection setup. HTTP requests through a system proxy, TLS connections with SNI, and Fake IP mappings usually preserve domain context; a pure IP connection can match only IP-based rules. If an application resolves a domain itself and connects directly to the IP, domain rules may not match. When logs show only a destination IP, check whether DNS is handled by the core and whether the application bypasses the system proxy.

IP, GEOIP, and no-resolve

IP-CIDR is for IPv4 networks, while IP-CIDR6 is for IPv6 networks. LAN, loopback, and link-local addresses should generally connect directly rather than through a remote proxy. The CIDR prefix length determines the range; getting it wrong by one bit can expand the range far beyond what was intended. Before changing a network rule, confirm which network contains the target address instead of adding an overly broad range based on one lookup result.

no-resolve means the IP rule will not actively trigger DNS resolution during matching. It is useful when the destination IP is already known and an extra domain lookup is undesirable. If the rule needs DNS resolution to obtain an IP, adding no-resolve changes the matching conditions. This parameter is not a general performance switch; use it according to the rule type and current connection context.

GEOIP classifies addresses using an IP database. It matches address geolocation, not domain categories. The database must be updated with the core's resources, and category boundaries may vary. For stable control of a specific service, domain rules or a maintained rule set are usually more direct; GEOIP works best as a broad condition near the fallback end of the list.

Process, port, and network-type rules

Compatible cores may provide extended rules for process names, process paths, destination ports, inbound types, and more. Process rules depend on operating-system permissions and the core's ability to obtain process information; mobile platforms, containers, and some sandboxed applications may not expose complete data. Process names can also change after updates, so confirm what is actually recognized in the runtime logs.

Port rules suit scenarios with a clearly defined protocol range, but one port can carry different services, so routing by port alone can be too broad. Network-type rules distinguish TCP from UDP and are useful for specific UDP applications or local services that should connect directly. Document the purpose of complex rules and keep their number under control; being able to understand why a rule exists six months later matters more than making the configuration as short as possible.

Where to insert custom rules

Whether a custom rule takes effect depends on its position in the final rule list. A precise rule intended to override subscription defaults should come before the corresponding broad rule; local direct-connect networks should come before the proxy fallback; MATCH should always be last. Many clients offer “prepend rules,” “append rules,” or script overrides. Prepending suits high-priority exceptions; appending suits additions not covered by the subscription that will not be caught early by an existing fallback.

When validating rules, do not inspect only the configuration text; check rule-hit information in the runtime logs. Visit a clearly defined target, then confirm its domain or IP, matched rule type, target proxy group, and final node. If the log shows an earlier rule matched, adjust the order or narrow that rule's scope. For more common questions, continue in Frequently Asked Questions under “Tips” and “Troubleshooting.”

07 / PROVIDERS

Proxy Providers and Rule Providers

Why split external content into Providers

Providers separate frequently updated nodes or rule sets from the main configuration. proxy-providers supplies node objects for groups to reference through use; rule-providers supplies rule content for RULE-SET. The main configuration defines the runtime framework and policy relationships, while Providers handle external data updates. This avoids replacing the entire main configuration whenever nodes or rules change.

A Provider is not a proxy group. After a node Provider downloads successfully, a proxy group must still reference it; after a rule Provider downloads successfully, rules must still use RULE-SET to assign its target policy. Defining a Provider without referencing it does not change traffic automatically. Conversely, a rule that references a missing or failed Provider cannot match its collection.

proxy-providers structure

proxy-providers:
  subscription-main:
    type: http
    url: "https://subscription.example.com/api/client?token=xxxx"
    path: ./providers/subscription-main.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

proxy-groups:
  - name: Automatic Selection
    type: url-test
    use:
      - subscription-main
    url: https://www.gstatic.com/generate_204
    interval: 300

  - name: Node Selection
    type: select
    proxies:
      - Automatic Selection
      - DIRECT
    use:
      - subscription-main

type: http means content is fetched from a remote address, url is the subscription address, path is the local cache path, and interval is the update interval. The path should be inside a configuration directory that the client can write to. Multiple Providers should not share one cache file, or updates may overwrite one another. A subscription URL is an access credential; keep it in the client configuration and controlled backups, not in public documents or screenshots.

health-check tests the availability of nodes in a Provider. It is related to but not identical to the group's own url-test: the Provider health check maintains node status, while the group test selects members. The test address, interval, and network environment affect results. With many nodes, avoid very short intervals that generate dense request traffic.

behavior in rule-providers

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

  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    url: "https://rules.example.com/private-network.yaml"
    path: ./rules/private-network.yaml
    interval: 86400

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,private-network,DIRECT,no-resolve
  - MATCH,Node Selection

behavior describes the content type of a rule set. domain is for domain entries, ipcidr is for address ranges, and classical can carry the classic format with rule types. Provider content must match its behavior. Putting a complete DOMAIN-SUFFIX,example.com entry into a collection that accepts only domain payloads, or placing a plain network range in an incompatible format, causes loading errors or ineffective entries.

For domain behavior, the YAML payload is usually written as a payload sequence, with the exact entry format defined by the core. The classical format retains complete rule types. Choose behavior based on the actual format supplied by the rule source rather than the filename alone. If a remote address returns a webpage, login page, or error message, the content is not a valid rule file even when the HTTP request succeeds.

Provider updates and caching

When a remote update fails, the core may continue using the local cache, so “it still works” does not mean the Provider completed this refresh. Logs should distinguish download failure, parse failure, write failure, and successful cache reads. For download failures, check the network, URL, and access permissions; for parse failures, inspect the returned format; for write failures, check directory permissions and the path. If the cache is corrupted, back up the configuration, remove the relevant cache, and let the client fetch it again.

Update intervals are specified in seconds. Node subscriptions and rule sets do not need the same schedule: nodes may change frequently, while stable rule sets can update less often. Whether the client updates immediately at startup and how it retries failures depends on the core and GUI. Do not use an extremely short interval as a substitute for troubleshooting; repeated failures only generate more requests and logs.

Organizing multiple Providers

When using multiple subscriptions, give each Provider a unique name, cache path, and health check. Groups can reference sources directly or filter by name before combining them by region. Source names are useful for subscription management, while regional groups are useful for daily selection; do not mix them in one naming layer. For example, use “subscription-main” for a Provider and “Hong Kong Nodes” or “Automatic Selection” for groups to make the UI clearer.

Rule Providers should also be split by purpose, such as private networks, development services, media services, and blocklists. Splitting too finely creates many remote requests and complicated ordering; splitting too broadly makes different policies difficult to assign. Use “does this need an independent update schedule, policy, or priority?” as the criterion. Multiple RULE-SET entries still follow the top-to-bottom first-match logic.

08 / OVERRIDE AND MERGE

Overrides, merges, and configuration maintenance

Identify the configuration layers first

The final runtime configuration in a graphical client usually combines several sources: the original subscription, client-generated defaults, UI settings, local override files, script results, and runtime fields. The subscription YAML shown to the user may not be what the core ultimately loads. When a change has no effect, first find “runtime configuration,” “configuration preview,” or log output in the client and identify which layer supplied the final value.

Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu, and other clients may use different names and execution orders for override interfaces; mobile clients may expose only some fields. On desktop and mobile, prefer the override entry points provided by the client instead of editing subscription-managed cache files directly. Subscription caches are usually rebuilt during refresh, so manual edits are easily overwritten.

Merge differences between mappings, sequences, and scalars

YAML top-level values can be mappings, sequences, or scalars. dns is a mapping with nested keys; rules, proxies, and proxy-groups are usually sequences; mode and mixed-port are scalars. Override systems may handle these three types differently. Scalars are usually replaced directly, mappings may be merged recursively by key, and sequences may be replaced wholesale, prepended, appended, or handled by name.

This distinction determines whether an override is safe. If you only want to add one rule but the override mechanism replaces rules wholesale, you will lose every subscription rule. If you only want to change dns.enhanced-mode but the system performs a shallow replacement, the entire dns mapping may be reduced to one field. Before operating, check how the client defines merge, prepend, append, and override; do not assume every client uses the same algorithm.

Rule merges must handle MATCH

The most common problem with rule overrides is the fallback position. Subscription rules usually already end with MATCH; simply appending local rules means they will never run. The usual solution is to insert high-priority local rules before the subscription rules, or temporarily remove the trailing MATCH in a script, insert the additional rules, and then restore it. The final list should contain one clearly defined fallback target.

# Prepend rules example
rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,dev.example.com,Node Selection

# The final configuration should continue with the subscription rules and end with one MATCH
# - RULE-SET,...
# - GEOIP,...
# - MATCH,Node Selection

Prepended rules should be as precise as possible. Adding a broad DOMAIN-KEYWORD, large CIDR range, or regional rule at the very top can cut off more specific subscription policies. After each new rule, validate at least one target that should match and one neighboring target that should not, and inspect the actual match in the logs.

Merging proxy group and node names

Merging proxy group sequences cannot be judged by object position alone. Some tools find and modify an existing group by name, while others simply append the new object. Appending a group with the same name may produce a duplicate-name error or cause the client preprocessor to keep one unpredictably. To modify members of an existing group, use the client's explicit name-based override method; if unsupported, generating the complete target group sequence is more predictable.

Node lists can also contain duplicate-name conflicts. If a subscription already has “Hong Kong 01” and a local node uses the same name, references cannot clearly distinguish the source. Give self-built nodes a stable prefix such as “LOCAL-” or a purpose label. When Provider filters depend on names, also confirm that the prefix will not be accidentally selected by a regional regular expression.

Keep DNS overrides' dependencies intact

When changing DNS, do not focus only on nameserver. A DoH upstream written as a domain requires a working default-nameserver; a node server written as a domain requires checking proxy-server-nameserver; Fake IP also requires retaining its address range and filters. A shallow override that appears to replace only the upstream address can accidentally remove these dependencies.

A safer method is to export the final DNS section, copy it into a locally maintained version, and modify and validate it as a whole. Use a minimal subkey override only after confirming that the client performs recursive merges. After changing the DNS design, reload the configuration, clear caches, and test both the node hostname and an ordinary target domain; do not treat a client message saying “configuration successful” as the only completion criterion.

Build a recoverable change workflow

Handle one topic at a time: change DNS first, then proxy groups, and finally rules. Before editing, keep the currently working configuration. After editing, perform five checks: syntax loading, Provider updates, proxy group membership, rule matches, and actual access. Replacing several sections at once makes it difficult to identify which layer caused an error.

Use comments in the configuration to record the purpose, source, and dependencies of a change, such as “must come before subscription rules,” “requires Provider subscription-main,” or “direct connection for LAN addresses only.” Comments should not contain subscription credentials or node passwords. For long-term maintenance, comparing structural changes is more useful than comparing raw lines because subscriptions may reorder or rename nodes.

If startup problems appear after a subscription update, switch back to the saved working configuration first and confirm that the client and core can start. Then compare top-level fields, proxy group names, and rule targets between the old and new configurations. If the client exits immediately, shows no window, or crashes after an update, see Client Startup Crash Troubleshooting. When the first-connection checks need to be repeated, return to Getting Started and verify the subscription, node, system proxy, and connection status step by step.

Final configuration checklist

Before loading, check YAML indentation, spaces after colons, quotes, and sequence nesting; after loading, check that ports are listening, DNS has started, and Providers returned valid content. Then confirm that every rule target has a corresponding proxy group, every group has at least one valid member, nested groups contain no cycles, and the final rule list has one MATCH at the end. Finally, test a direct domain, a proxied domain, a LAN address, the node server hostname, and an application that requires UDP.

Passing one configuration test does not mean every network environment will behave the same way. After switching between Wi-Fi, mobile data, a corporate network, or IPv6, DNS reachability, MTU, firewall behavior, and system proxy handling may change. Keep the same configuration and change one environmental variable at a time to determine whether the issue comes from the configuration or the network. If another client is needed, see the Download Center for Windows, macOS, Android, iOS, and Linux options; most users should start with Clash Plus and import the same subscription for comparison testing.