Clash Configuration Fields

CHAPTER 01 / INPUT

YAML Structure Overview and Loading Relationships

A Clash configuration file is a YAML document. It is not a line-by-line script, but a collection of keys, lists, and objects parsed and then handed to the core. Top-level fields define listening ports, operating mode, DNS behavior, and the control interface; proxy nodes are placed in proxies or imported through proxy-providers; proxy groups reference nodes and other proxy groups by name; the rules list then sends domains, IPs, processes, or network types to a specified policy. When reading a configuration, first confirm that the object exists, then verify that every referenced name matches exactly, and finally check rule order. Focusing on one rule alone can easily hide the fact that its referenced proxy group was never loaded.

YAML uses indentation to express hierarchy. Two spaces are recommended consistently; do not use tabs. List items begin with a hyphen, followed by a space. Colons separate keys from values and should usually be followed by a space. Names containing colons, hash signs, brackets, or special boolean words should be quoted. Comments begin with # and are for explanation only; they are not passed to the core. A file can have valid indentation yet place a field at the wrong level, so the parser may not read it where expected. In other words, “the file opens” does not mean “the field is active.”

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

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query

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

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

rules:
  - DOMAIN-SUFFIX,example.org,Node Selection
  - MATCH,DIRECT

The minimal structure above shows the complete reference chain: “Node Selection” in rules must exactly match the name in proxy-groups; “Example Node” in the proxy group must likewise match a node name in proxies. Names are sensitive to characters, spaces, and full-width versus half-width punctuation. When copying a configuration fragment, copying rules without the proxy group—or the proxy group without its nodes—creates dangling references. Some clients warn during import, while others log errors only when starting the core, so checking client logs is essential.

Recommended Top-Level Field Order

The YAML specification does not require a fixed top-level order, but for maintainability, arrange fields as “runtime entry points, DNS, node sources, nodes, proxy groups, rule sources, rules.” This order roughly follows data dependencies: first determine how traffic enters the core, then how domains are resolved, then prepare usable exits, and finally perform matching. Subscription generators may use a different order; as long as indentation and references are correct, the result is usually unaffected. Keeping a stable order during manual maintenance reduces accidental deletions during merges and makes updates easier to compare.

A configuration imported from a subscription is usually saved by the client as a local copy. Editing that copy is convenient for testing, but the next subscription update may regenerate the file. Local rules that must persist should go into the client's supported override, merge, or script entry point rather than relying on a modified cache file. If the immediate goal is simply to establish the first connection, follow the quickstart workflow first to verify that the subscription works, then return here to adjust the structure. This separates an unavailable subscription from an incorrectly written custom field.

CHAPTER 02 / RUNTIME

Common Fields: Ports, Modes, LAN Access and the Control Interface

Common fields determine how the core receives application traffic and exposes management capabilities. Desktop clients typically manage these values through their GUI, but the configuration file remains the final reference. The most common entry point is mixed-port, which accepts HTTP and SOCKS5 proxy requests on one port and suits both system proxy settings and apps where a proxy address is entered manually. Older configurations may use port and socks-port separately. If multiple entry points are defined, make sure their port numbers do not overlap and are not occupied by another program.

mixed-port: 7890
redir-port: 7892
tproxy-port: 7893

allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

redir-port and tproxy-port are mainly used for transparent proxying, typically connected through routing rules, gateway scripts, or a dedicated client. A regular desktop system using only the system proxy does not need these fields enabled just for completeness. TUN mode has its own traffic entry point and routing process; adding a listening port alone cannot implement it. To compare the coverage of the system proxy and TUN, read TUN Mode vs. System Proxy, then choose the routing method based on whether the application honors the system proxy.

Operating Modes and Rule Behavior

Common values for mode are rule, global, and direct. Rule mode matches rules from top to bottom and is the normal day-to-day choice; global mode sends traffic to the global policy and is useful for temporarily testing whether a node works; direct mode bypasses proxy exits and helps isolate local network issues. Switching modes does not rewrite the rules; it only changes the decision entry point. During troubleshooting, briefly switch to global mode: if global mode works but rule mode fails, focus on rule matches and proxy groups; if global mode also fails, check the node, protocol parameters, and system routing state first.

allow-lan controls whether LAN devices can access the ports listening on this machine. After setting it to true, also consider bind-address, the operating system firewall, and the LAN address in use. An open listener means devices on the same network may send requests to that port, so enable it only when proxy sharing is explicitly needed and restrict access to the control interface. When the client is used locally, keeping false is easier to maintain. If the client GUI offers an “Allow LAN connections” switch, avoid setting it repeatedly across multiple override layers, or the displayed state may differ from the final configuration.

Control Interface and Configuration Storage

external-controller: 127.0.0.1:9090
secret: "your-dashboard-password"
external-ui: dashboard
profile:
  store-selected: true
  store-fake-ip: true

external-controller exposes a control API that GUI clients and dashboards can use to read proxy groups, switch nodes, or reload the configuration. For local management, binding it to 127.0.0.1 is sufficient. If it binds to every network interface, access control, firewall rules, and the actual environment must be considered together. secret authenticates the control interface; replace the example value with your own local value. external-ui points to a directory containing static dashboard files. It is not a proxy node source and does not change proxy rules.

profile.store-selected saves proxy group selections so the core can restore them after restarting. store-fake-ip saves Fake-IP mappings and reduces the impact of mapping changes after a restart. Whether the client takes control of these fields depends on its implementation; a GUI client may store state in its own database rather than in the same YAML file. When changes revert after a restart, first determine whether the field comes from the subscription, an override, or a client preference instead of repeatedly editing the same cache file.

log-level controls the level of log detail. Use info for normal operation; when investigating rule matches, DNS requests, or connection establishment, temporarily increase the detail level and restore it afterward so large logs do not obscure key errors. ipv6 determines whether core-related functions handle IPv6, but it cannot by itself provide a usable IPv6 route on the local network. If connections hang after enabling it, check the local network, DNS responses, and rule coverage separately rather than blaming a single switch.

CHAPTER 03 / RESOLUTION

DNS Fields: Upstream Resolution, Fake-IP and Fallback Rules

Clash's DNS module sits between domain requests and rule matching. It can receive DNS queries from the local system or from TUN-routed traffic, then choose upstream servers according to the configuration. The goal of DNS configuration is not to stack addresses indiscriminately, but to answer three questions: where queries enter, which upstreams handle them, and how results work with the rules. In system proxy mode, some applications may still use the system DNS directly; TUN mode with DNS hijacking usually provides broader coverage. If a browser works but other applications fail to resolve domains, first confirm whether those applications' DNS traffic reaches the core.

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

enable controls whether the built-in DNS is enabled, while listen specifies its listening address. Listening on 0.0.0.0 affects the LAN access scope and should be handled according to the actual network environment; for local use, a loopback address or client-managed setup is preferable. default-nameserver usually contains directly reachable IP addresses for basic tasks such as resolving the hostname of a DoH upstream. It is not the primary exit for all queries. Normal domain queries mainly go to nameserver; proxy server hostnames can be resolved separately through proxy-server-nameserver to avoid circular dependencies before a proxy connection is established.

How Fake-IP Differs from Redir-Host

enhanced-mode: fake-ip returns mapped addresses from a reserved range for domains. When an application later connects to such an address, the core restores the original domain from the mapping and then applies domain rules and proxy decisions. This preserves domain information and is useful for unified handling in TUN scenarios. fake-ip-range should use a dedicated reserved subnet, not an address range already used by the LAN. A mapped address is not the real address of a remote server, so seeing a reserved address in a packet capture tool is normal.

Some LAN device discovery, time synchronization, games, and applications that require real addresses do not work well with Fake-IP. Add the relevant domains to fake-ip-filter so they use real resolution. Keep exclusions as specific as possible and start with domains confirmed to be problematic. Do not add an overly broad top-level match, or domain rules become less transparent. For mapping details and exclusion scenarios, continue with How Clash Fake-IP Mode Works.

redir-host is closer to the traditional resolution flow: the core obtains the real IP before processing the connection. It is more intuitive for programs that depend on real addresses, but domain information may be lost during subsequent IP connections, making matching more dependent on resolution caches or sniffing. Neither mode is universally correct. Regular web browsing, full TUN routing, and extensive domain rules are often good candidates for testing Fake-IP first; when LAN services, specific games, or corporate intranet domains are involved, add exclusions individually instead of immediately changing the entire DNS architecture.

Fallback, Policies and Split DNS

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    domain:
      - "+.example.net"
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
    "geosite:geolocation-!cn":
      - https://1.1.1.1/dns-query

fallback and fallback-filter select backup results under specified conditions. Configuration requires understanding how the kernel used by the client handles concurrent queries, result filtering, and Geo data; entering backup addresses does not mean every failure will automatically retry in a fixed order. nameserver-policy can assign DNS servers by domain or rule set, which suits environments where external, internal, home, and work domains require different resolution paths. When a policy key references geosite, local Geo data must be readable or the match will not work as expected.

Common failures can be handled by symptom: if every domain fails while direct IP access works, focus on the listener and upstreams; if only proxy node hostnames fail, check proxy-server-nameserver and base resolution; if LAN names fail, check the search domain, hosts, and Fake-IP exclusions; if rule matches differ from expectations, check whether domain information is preserved and whether Geo data loaded. After changes, reload the configuration and inspect the logs. Do not change enhanced mode, upstream addresses, and TUN hijacking simultaneously, or it will be difficult to tell which change took effect.

CHAPTER 04 / ENDPOINTS

Proxy Node Fields: Names, Protocol Parameters and the Transport Layer

proxies is a list of proxy node objects. Each object needs at least a name, protocol type, server address, port, and the authentication parameters required by that protocol. A node name is not just for display; proxy groups reference it, so it must be unique. The server can be a hostname or IP address; when a hostname is used, DNS resolution must complete before the connection starts. The port must be the port actually listening on the server and must not be confused with the local proxy entry port. Subscription-generated node parameters are usually provided as a complete set, so manually changing one field can break negotiation between the server and client.

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

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

Shadowsocks nodes use cipher and password. The cipher must match the server, and spelling and capitalization must fall within the range supported by the core. Trojan nodes usually connect through TLS, with sni specifying the server name in the handshake. When skip-cert-verify is false, certificate verification is performed; keep verification enabled for normal public certificates. If the certificate name does not match the connection hostname, check the server configuration and subscription content first instead of treating disabled verification as a permanent fix.

VMess, WebSocket and TLS

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

VMess uuid, alterId, transport network, and TLS parameters must match the server. WebSocket settings belong under ws-opts; the path and Host header are part of transport negotiation. If these fields are indented outside the node object, YAML may still parse, but the core will not treat them as that node's WebSocket parameters. When using gRPC, HTTP, or another transport, use its corresponding options rather than leaving unrelated ws-opts in place and expecting automatic conversion.

TLS-related fields may use sni or servername in different protocol objects. Before copying a fragment, compare it with the fields supported by the current core instead of replacing names merely because they look similar. The server address, TLS server name, and HTTP Host may be identical, but they can serve different roles: the server address determines the connection target; SNI participates in the TLS handshake; the Host header is used by the application-layer transport. When troubleshooting a handshake failure, check all three layers separately rather than only testing whether the hostname resolves.

UDP, Interfaces and Chained Exits

udp: true means the node permits UDP, but actual usability also depends on the protocol, server, and local routing method. An application sending UDP does not mean the system proxy will automatically capture it; many system proxy settings mainly cover TCP. TUN or transparent proxying can handle UDP more uniformly, but still requires correct routing and DNS configuration. When games, voice calls, or QUIC connections fail, first confirm that the traffic reaches the core, then determine whether the node supports it. Do not draw conclusions from the boolean value in the node object alone.

Fields such as interface-name and routing-mark constrain the exit interface or work with system routing, mainly in multi-NIC, server, and router environments. A mistake can send a proxy connection back into the proxy entry point and create a loop. Chained proxies can use mechanisms such as dialer-proxy to specify a dialing exit, but the referenced node or proxy group must already exist, and mutual references must be avoided. For ordinary client configurations without a clear chaining requirement, these fields are best left out.

After importing a subscription, do not guess at protocol parameter changes. First run the configuration update provided by the client, then check whether the node names appear in the proxy groups. If the node list is empty, the problem usually lies in subscription fetching, format conversion, or provider loading; if nodes exist but connections fail, check protocol parameters, DNS, and system time. Compare client downloads and platform differences on the client download page; for discontinued clients, see the configuration migration steps.

CHAPTER 05 / POLICY

Proxy Group Fields: Manual Selection, Automatic Testing and Failover

proxy-groups organizes nodes, built-in exits, and other proxy groups into decision objects that rules can reference. Rules generally reference a proxy group name rather than a specific node, so subscription updates or node changes do not require every rule to be rewritten. Common built-in exits include DIRECT and REJECT. The former connects directly to the destination; the latter terminates matching traffic. Proxy group names must also be unique. If a name duplicates a node, reading and maintenance become difficult, so use purpose-driven names such as “Node Selection,” “Auto Select,” and “Failover.”

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Auto Select"
      - "Failover"
      - "Shadowsocks Example"
      - DIRECT

  - name: "Auto Select"
    type: url-test
    proxies:
      - "Shadowsocks Example"
      - "Trojan Example"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

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

Select, URL-Test and Fallback

select enables manual selection. It works well as a top-level entry point, allowing users to switch explicitly among an automatic group, a failover group, an individual node, and a direct connection. url-test checks candidates against a test URL and selects based on the results. The result reflects connectivity to that URL only; it does not represent every website, protocol, or time period. tolerance reduces frequent switching when candidate results are close. Its units and exact behavior are determined by the core implementation.

fallback selects available items in list order and switches to the next one when the current item is unavailable, making it suitable when exit priorities are clear. load-balance distributes connections across multiple candidates, but session consistency matters: logins, payments, and services tied to a fixed exit may not work well when the exit changes between connections. Automatic testing and load balancing are not cases where “more nodes is always better”; too many candidates increase checks and maintenance. Filter candidates by region, purpose, or protocol first, then build a manageable proxy group.

Using Proxy Providers to Populate Proxy Groups

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

proxy-groups:
  - name: "Provider Node"
    type: select
    use:
      - airport

proxy-providers stores a remote node collection in a local provider file. type: http means it updates from a URL, path specifies the local cache location, and interval sets the update interval. The example subscription URL uses an obvious test value; copy the real URL from your subscription service and avoid exposing it in public documentation or screenshots. health-check performs provider-level availability checks. It can coexist with a proxy group's own testing mechanism, but intervals that are too short create duplicate checks.

Proxy groups reference providers through use and static nodes or other groups through proxies. These sources can be combined where supported by the core, but maintenance should make each node's origin clear. When a subscription update changes node names, old names written directly in proxies may stop working; provider references are better suited to dynamic collections. For further filtering, supported cores may offer filter or exclusion expressions to build region groups from node names. Test expressions against a small set of names first, or naming changes may produce an empty group.

Proxy Group Dependency Direction

Proxy groups can reference other proxy groups, but dependencies must remain one-way. For example, “Node Selection” referencing “Auto Select” is reasonable; if “Auto Select” references “Node Selection” in return, a cycle is created. Design the policy layers from the bottom up: static nodes and providers at the base, regional filters and automatic tests in the middle, and purpose groups referenced by rules at the top. Media, work, and download groups can then reference top-level exits instead of making low-level test groups depend on business groups.

When interval is configured in seconds, set it according to actual needs rather than aiming for high frequency. Node subscription updates, health checks, and proxy group tests are three different operations: subscription updates change the candidate set; health checks determine whether nodes are reachable; proxy group tests choose among candidates. Trigger them manually and separately during troubleshooting, and observe which step fails. If the client GUI also offers an automatic update interval, confirm whether it updates the entire configuration or only a provider, avoiding duplicate scheduled requests.

CHAPTER 06 / MATCHING

Rule Syntax, Match Order and Rule Providers

rules is an ordered list. A connection is checked from the first rule downward; once a rule matches, its specified policy is used immediately and later rules are not processed for that connection. Rule position therefore matters as much as rule content. Specific domains, processes, or subnets usually belong near the top, broader Geo rules later, with MATCH as the final fallback. Placing a broad rule too early prevents more precise rules below it from ever matching.

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

DOMAIN matches a complete domain exactly; DOMAIN-SUFFIX matches the specified domain and its subdomains; DOMAIN-KEYWORD matches by keyword and has a wider scope, making it more likely to affect unrelated domains containing the same string. When an exact domain or suffix works, do not prefer a keyword rule. Domain rules depend on domain information being available during the connection. If an application connects directly to an IP, or DNS processing does not preserve the domain, matching may fall back to IP-based rules.

IP, Port, Process and Network Type

IP-CIDR is used for IPv4 subnets; IPv6 uses the corresponding IPv6 rule type. Reserved LAN addresses should usually be routed directly before GeoIP rules. no-resolve means the IP rule will not actively trigger domain resolution to obtain an IP, which can avoid extra queries and rule-stage loops, but suitability depends on the rule type and actual traffic. When using CIDR, verify the prefix length; an overly broad subnet may cover addresses you did not intend to match.

rules:
  - PROCESS-NAME,example-app.exe,DIRECT
  - DST-PORT,22,Node Selection
  - NETWORK,udp,Auto Select
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,Node Selection

Process rules depend on operating system permissions and client core capabilities, and platforms do not identify processes in exactly the same way. Windows commonly exposes executable names; macOS and Linux may provide process names or paths; mobile platforms generally cannot identify every app like a desktop system. Port rules show only the destination port and do not prove the traffic's purpose. Many services share ports, so port-only routing can be overly broad. NETWORK distinguishes TCP from UDP, but it is better used as a supplement for specific needs rather than replacing domain and IP rules.

Rule Provider and Behavior Types

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

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

rules:
  - RULE-SET,direct-domains,DIRECT
  - RULE-SET,private-networks,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

rule-providers splits large rule sets into separate files. behavior: domain means the content is interpreted as a domain-based payload, while ipcidr is for subnets; some cores also support more general rule-set behaviors. The behavior type must match the contents of the remote file. A domain list cannot be labeled as an IP subnet payload, and classic rule text cannot be treated as a plain domain payload. format describes the file format. When updates fail, check network access, file format, save path, and parsing logs together.

Rule provider update intervals are independent of subscription updates. Updating a node subscription does not guarantee that external rule sets have been refreshed, and refreshing rule sets does not change nodes. GeoIP, GeoSite, and external rule providers are separate data sources. When regional rules are outdated, confirm the data file location and update function used by the client instead of updating only the subscription. For Geo data loading issues, continue in the Help Center and search by symptom.

Building an Explainable Rule Order

A useful order is “local machine and LAN, precise manual rules, business rule sets, regional rules, final fallback.” Add comments before each section to document its source and purpose. A small number of manual rules are easier to inspect directly in the main configuration; use a rule provider when the list is large and needs independent updates. Do not mechanically concatenate rules from multiple sources and deploy them without review. Check for duplicates, conflicting policies, and overly broad keywords.

When testing rules, change only one section at a time. Add a precise domain rule near the top, reload, and visit the corresponding domain while confirming the match in the logs. Once the syntax and proxy group are verified, expand gradually to suffixes or rule providers. Switching directly to global mode tests only the node path; it does not prove that the rules are correct. After testing, restore rule mode and confirm that the final MATCH target is what you expect.

CHAPTER 07 / MAINTENANCE

Overrides, Merging, Automatic Updates and Configuration Troubleshooting

Subscription configurations change when remote content is updated, so local changes should live in a stable custom layer. Many clients offer overrides, merges, extension scripts, or configuration fragments, but array and object handling varies by client. Object fields can usually be overridden by key, such as changing mode to rule or adding subfields under dns; arrays may be replaced entirely, appended before or after existing items, or processed according to client-specific syntax. rules, proxies, and proxy-groups are all arrays, and replacing them incorrectly can erase the subscription's original content.

Configuration maintenance should distinguish four sources: the original remote subscription, the runtime configuration generated by the client, local override fragments, and the client's own preferences. The final state shown in the interface may be a combination of all four. During troubleshooting, find the client's “view runtime configuration” function or log output instead of opening only the downloaded subscription file. If custom rules disappear after an update, the changes were made in a remote copy or cache layer; if a GUI change does not alter the YAML, that setting may be stored in client preferences.

Object Overrides and Array Appends

# General override example; use the entry point supported by the client
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*.lan"
    - "*.local"

The object structure above expresses the desired final state, but it does not show how a particular client merges arrays. If fake-ip-filter uses replacement semantics, writing two entries replaces the subscription's original list; with append semantics, the original list is retained and two entries are added. Confirm the behavior in the client documentation or runtime configuration before using it. Rule arrays require particular attention to insertion position: local rules that must take priority need to appear before remote rules; appending them after MATCH has no effect because the traffic has already ended at the fallback rule.

Proxy groups have the same issue. To add a local group to “Node Selection,” do not copy and permanently maintain the entire remote proxy group list, because new groups added by a subscription update will not enter the copy automatically. A more reliable approach is to use the client's group-level override, script processing, or provider reference so that only the target group changes in the final configuration. If fine-grained merging is unsupported, reduce the scope of customization or move long-lived rules to an independent rule provider.

Three Layers of Automatic Updates

Automatic updates include at least three layers: the full subscription, proxy providers, and rule providers. A full subscription update is usually scheduled by the client and regenerates the complete configuration; proxy-providers.interval updates the node collection; rule-providers.interval updates the rule collection. These are not the same switch. If the subscription URL changes, refreshing only rule providers will not add new nodes; if rule sets are outdated, refreshing only the node subscription will not change rule data.

When setting intervals, consider how often the content changes and how the client runs. If a desktop client is closed for long periods, timers cannot run in the background, so check update times manually after restarting it. A successful update does not necessarily mean the runtime configuration was reloaded: some clients apply it automatically, while others require a manual switch or reload. A reliable sequence is: run the update, confirm the source status, reload the final configuration, check that proxy group selections remain, and then test access.

Troubleshooting from Parsing Errors to Connection Errors

The first layer is YAML parsing. Common messages include indentation errors, a missing space after a colon, an unclosed quote, an incorrect list level, and duplicate keys. Check several lines above and below the reported line, because the structural mistake may occur earlier. Quote values containing special characters when needed; replace curly quotes and full-width punctuation copied from web pages with standard YAML characters. After parsing succeeds, validate fields and types—for example, ports should be numbers and boolean values should be true or false.

The second layer is reference validation. Confirm that every rule target exists in a proxy group or built-in exit, that proxy group members exist in nodes, providers, or other groups, and that rule provider names match their RULE-SET references. Spaces in names are difficult to spot, so temporarily copy a name and search for it. The third layer is resource loading: check whether the subscription, proxy providers, rule providers, and Geo data are readable. A failed network update may leave an old cache that still allows the core to start, so check both timestamps and logs.

The fourth layer is connection establishment. For node timeouts, check server resolution, the destination port, the local network, and protocol parameters. For TLS handshake failures, check the system clock, server name, and certificate. If only UDP fails, check the routing method and node capability; if only specific domains fail, return to DNS and rule matching. The fifth layer is the system traffic entry point: browser settings, the system proxy, TUN routing, and the application's own proxy must match the current setup. A configuration file can be completely correct, yet access will not change if system traffic never reaches the core.

After making changes, keep a repeatable verification path: reload the configuration and confirm that the core starts; update providers and confirm that nodes and rule sets are readable; check proxy group selections; visit one domain that should connect directly and one that should use a proxy; then review the match results in the logs. If the issue still cannot be categorized, visit the Help Center and continue by category under installation and configuration, usage tips, or troubleshooting. To review the loading order of a complete YAML file, read YAML Configuration Structure Explained; to repeat the basic import process, return to the Quickstart Guide rather than adding more overrides before verifying that the subscription works.