Clash Configuration File
Field Reference

01 · DOCUMENT MODEL

YAML structure and configuration load order

Top-level fields are not execution steps

Clash configuration files are commonly named config.yaml and consist of a set of top-level keys. Common sections include ports, operating mode, DNS, proxies, proxy groups, rules, and external Providers. Their order in the file mainly helps readers; it does not mean the core executes them strictly line by line. The parser reads the complete YAML first, builds a configuration object, and then validates proxy group references, rule targets, and Provider definitions. Therefore, placing rules before proxies may not trigger an immediate error, but it makes manual review much harder. A practical order is “basic runtime settings → DNS → proxies → proxy groups → Providers → rules.”

YAML uses indentation to express parent-child relationships; tabs cannot replace spaces. Items at the same level must use the same indentation width, typically two spaces. List items begin with a hyphen, and objects following the hyphen must still follow the indentation rules. Most strings do not need quotes, but quoting is safer when a value contains a colon, hash, braces, leading or trailing spaces, or a word that could be parsed as a boolean. For example, writing a node name as "HK: Premium" prevents the colon from being interpreted as a key-value separator; passwords containing # should also be quoted, otherwise everything after the hash may be treated as a comment.

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: "Node selection"
    type: select
    proxies:
      - "Example-SS"
      - DIRECT

rules:
  - MATCH,Node selection

Scalars, lists, and mappings

mode: rule is a scalar; the entries under rules form a list; and the key-value pairs under dns form a mapping. Configuration errors often come from mixing these three structures. For example, nameserver expects a list, so some cores will reject a single string without a hyphen; proxy-groups is a list of objects, and every group needs its own name and type. When you see “invalid field type,” check more than spelling: confirm whether the value should be a string, number, boolean, list, or object.

In YAML, true and false should not be quoted because booleans and strings have different meanings. Ports are normally written as numbers. Domains, node names, regular expressions, and passwords are best treated as strings. Empty values also require care: a key with no value is not the same as an empty list. To explicitly clear a field, an override system may require [] or {}, depending on the target field type.

References and the final configuration

Proxy groups reference nodes or other groups by name, and rules reference group names at the end of each rule. Names must match exactly: spaces, capitalization, and full-width punctuation are all part of the name. If a rule says DOMAIN-SUFFIX,example.com,Outside China but the group is actually named “International nodes,” the core cannot infer that they are equivalent. Subscription updates can also rename nodes and leave manually written proxy groups without valid targets.

The configuration shown by a GUI client may not be what the core ultimately reads. The original subscription may pass through global overrides, scripts, proxy group generation, and compatibility conversions before becoming the runtime configuration. During troubleshooting, look first for “View final configuration,” “Runtime configuration,” or the load path in the logs instead of checking only the subscription editor. If the client offers syntax validation, fix parsing errors first, then inspect rules and network behavior; one indentation error can prevent the entire file from loading, making later network tests meaningless.

02 · RUNTIME

Ports, operating modes, and common fields

How inbound ports are divided

port is the HTTP proxy port, socks-port is the SOCKS5 proxy port, and mixed-port accepts both HTTP and SOCKS5 requests on one port. Desktop clients usually need only the mixed port, allowing the system proxy and command-line tools to share one entry point. Do not assign the same port to multiple fields, and avoid conflicts with other proxy software, development servers, or another running Clash instance. During a port conflict, the client may still show that the configuration was imported, while the logs report a listener failure and the system proxy points to a non-working endpoint.

redir-port, tproxy-port, and TUN inbound traffic are intended for transparent proxying and are mainly managed by routers, Linux gateways, or the client itself. Typical macOS and Windows users do not need to enable every port manually for “broader coverage.” System proxy mode handles applications that follow the system proxy settings; TUN mode uses a virtual network interface to capture a wider range of traffic. A client can configure either mode according to platform capabilities, but port fields alone cannot replace a TUN driver or routing configuration.

allow-lan and bind scope

allow-lan: true permits LAN access, but whether another device can actually connect also depends on bind-address, the operating system firewall, network interfaces, and router isolation policies. If the proxy is for local use only, leaving it disabled keeps the exposure easier to control. When sharing is necessary, verify that the current network is trusted and protect external control interfaces with authentication. Proxy inbounds and the control interface are separate services: opening a proxy port does not mean the control API should also be exposed to the LAN.

external-controller defines an external control interface, such as 127.0.0.1:9090. A GUI panel uses it to read connections, switch policies, and reload configuration. When bound to the loopback address, it is accessible only from the local machine; before binding to all interfaces, understand how secret provides authentication and check the firewall. If the panel starts but cannot display nodes or connections, first verify that the control address is not already in use, the control port entered in the client matches, and the authentication value is correct.

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"

Operating mode, logging, and IPv6

Common values for mode are rule, global, and direct. Rule mode matches rules from top to bottom; global mode sends traffic through the global policy; direct mode bypasses the proxy. Rule mode should be the everyday default. Global mode is useful for temporarily determining whether a problem lies in the rules or the node, while direct mode helps confirm whether the application’s own network access works. Treating global mode as a permanent setting bypasses fine-grained routing and can hide errors in the rules.

log-level controls the amount of detail in logs. info is suitable for normal operation; when investigating rule matches, DNS, or handshake failures, temporarily switch to debug. Detailed logs can grow quickly and may include requested domains and node names, so restore the normal level after troubleshooting. ipv6 controls whether the core enables related resolution and connection capabilities, but it is not a standalone network repair switch; the local network, DNS responses, proxy nodes, and rules must all support IPv6. If IPv6 routing is unstable, disable it for a comparison test before deciding whether to keep the change.

After editing the configuration, distinguish among “saved successfully,” “reloaded successfully,” and “traffic is now using the new configuration.” Some clients save text without reloading it immediately; others retain the previous working configuration when syntax errors occur. The most reliable confirmation is to review the reload log, verify the current mode and ports, and make a recognizable request to observe its rule match. If the port setup is still unclear, check the system proxy and port issues in Troubleshooting one by one.

03 · NAME RESOLUTION

Clash DNS, Fake-IP, and the resolution path

Where the DNS module fits

With Clash DNS enabled, resolution is no longer simply the operating system sending a query to one server. The core can select upstreams according to rules, cache results, and, in Fake-IP mode, maintain mappings between domains and reserved addresses. This helps separate three kinds of problems: an unreachable upstream DNS server, a domain resolving to an unsuitable address, and an application bypassing Clash to send encrypted DNS directly. If proxy connections work but pages do not load, do not immediately blame the node; check the DNS listener, the system DNS target, and the rule path together.

dns.enable controls whether the module is enabled, while listen specifies its address and port. Desktop GUI clients may take over system DNS automatically, so manually changing the listening port can conflict with the client’s management logic. An explicit listen address is more commonly needed on routers or LAN services. If binding to a LAN interface, make sure the port is not occupied by the system resolver and restrict the reachable scope.

Fake-IP and Redir-Host

enhanced-mode: fake-ip first returns a reserved address to the application. Clash then restores the original domain from its mapping and applies the rules. This preserves domain information, enables timely rule matching, and avoids waiting for a real address before forwarding. The trade-off is that some applications relying on real addresses, LAN discovery, or special protocols may be incompatible; exclude them with fake-ip-filter. redir-host follows a more traditional real-address resolution path. Its compatibility trade-offs differ, while domain recognition and connection timing are more affected by system caches and resolution order.

fake-ip-range specifies the reserved address range. In most cases, keep the client or core default; do not overlap it with real local subnets, VPN address pools, or enterprise routes. If a LAN domain returns a reserved address, first add that domain to the filter list instead of arbitrarily replacing the entire range. Keep filters as precise as possible: use the complete domain for one host, and a supported wildcard form when subdomains must be covered. Clear application and system DNS caches after making changes.

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

How the three upstream fields work together

default-nameserver is mainly used to resolve the hostnames of encrypted DNS upstreams, so it should normally contain directly reachable IP addresses. If every entry is a hostname, you can create a loop: the client must resolve the DNS server’s hostname before it has a usable resolver. nameserver lists the main upstreams and can contain regular UDP, DoT, or DoH endpoints. proxy-server-nameserver resolves proxy node hostnames, preventing node resolution from depending on the proxy chain. This matters less when node servers are IP addresses and is critical when they are hostnames.

nameserver-policy assigns different upstreams by domain, which is useful for corporate intranet domains, regional resolution, or services requiring separate handling. It answers “which resolver handles the query,” not “which proxy group handles the final connection.” Traffic routing is still controlled by rules. Do not mix up DNS policy syntax with proxy rule syntax, and do not judge whether the proxy is working solely from the resolved address.

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

Troubleshoot DNS along the chain

First confirm that Clash DNS is actually listening. Next confirm that system or TUN traffic is sent to that listener. Then identify which upstream handled the query, and only afterward inspect connection rules. Changing only the browser cache or repeatedly switching nodes will not locate a DNS-layer problem. If the logs show an upstream timeout, test whether that upstream is directly reachable on the current network. If the domain resolves but the connection fails, continue with rule matches, IPv4 versus IPv6 selection, and node availability. If only one application is affected, also consider its built-in DoH, QUIC, or caching behavior.

04 · OUTBOUND

Proxy fields and protocol parameters

Fields shared by all nodes

proxies is a list of proxy node objects. Each object includes at least a unique name, protocol type, server server, and port port; the remaining fields depend on the protocol. A node name is an internal reference key, not merely a UI label. Duplicate names make proxy group references ambiguous, and a duplicate between subscription and local nodes may be overwritten during merging. Names should convey region, route, or purpose, but should not include status information that changes frequently.

server can be an IP address or hostname. With a hostname, the node-resolution chain described earlier must work. The port is the remote service port, not the local mixed-port. Confusing these is a common manual-entry mistake. The protocol fields must match the server configuration; changing encryption or transport settings is not a way to “auto-detect” them. Authentication failures, TLS handshake failures, and network timeouts occur at different stages, so use the logs to tell them apart.

Shadowsocks and VMess examples

For Shadowsocks nodes, focus on the cipher and password. cipher must be supported by the core and match the server. Always quote passwords to prevent special characters from being interpreted by YAML. If the server uses a plugin, provide the plugin name and options as well; copying only the server, port, and password is not enough. Plugin parameters are usually mapping objects, and incorrect nesting can leave the plugin unloaded or the node unusable.

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

In addition to identity fields, VMess may include TLS, WebSocket, HTTP, or gRPC transport settings. servername is used for TLS SNI, while the WebSocket Host belongs to the HTTP request headers. They may be identical, but they have different meanings. Keep the leading slash in the path and make it match the server entry point. Older configurations may contain legacy compatibility fields; before importing into a newer core, use the provider’s current parameters rather than assembling fields from another protocol template.

Trojan, VLESS, and TLS fields

Trojan normally uses password authentication over TLS; VLESS uses a UUID and can be combined with different transports and flow controls. The most common TLS-node failures come from a mismatch among the server address, certificate name, and SNI. skip-cert-verify changes certificate verification and should not be a permanent fix. If certificate validation fails, first check the device time, server certificate, domain, and servername. Temporarily changing verification is appropriate only when you clearly understand the certificate used in the test environment and record the reason.

  - 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, interfaces, and dialing behavior

udp: true means the node permits UDP forwarding, but the server, protocol, client mode, and local network must also support it. Adding this field cannot give a UDP-incompatible route that capability. For games, voice, or DNS, use the logs to confirm whether traffic is using UDP and check that the node selected by the proxy group supports it. Some configurations also provide interface-name, routing-mark, or dialing-related fields. These are better suited to multi-interface and gateway environments; desktop users should not copy them without knowing the interface name.

A node passing a latency test only means that a request to a specific test URL could be established at that moment; it does not mean every protocol and site will work. The test address, TLS path, packet loss, and bandwidth all affect the result. Continue with How to interpret Clash latency test numbers, then compare real access with the logs. If you need another client for comparison, this site recommends Clash Plus first for each platform and also lists Clash Verge Rev, FlClash, Clash Nyanpasu, and ClashX Meta as alternatives.

05 · POLICY

Proxy group fields and selection logic

select: explicit manual selection

Proxy groups organize nodes, built-in actions, and other groups into exits that rules can reference. select is the most direct type: the user chooses an item manually in the client, and the selection is usually persisted by the client. It suits a main entry point, regional selection, or services that need a fixed route. The group’s proxies list references existing nodes or groups by name and may also contain built-in actions such as DIRECT and REJECT. Every referenced object must exist in the final configuration.

Proxy groups can be nested; for example, “Node selection” can reference “Hong Kong auto,” “Japan auto,” and “Manual selection.” Nesting reduces repeated rules, but deep hierarchies make troubleshooting harder. To determine where a connection ultimately goes, start with the rule target and expand each group layer until you reach a specific node or built-in action. Names should describe purpose. Do not give several groups the same name, such as “Auto selection,” when their test scopes differ.

url-test, fallback, and load-balance

url-test periodically requests a specified URL and selects a qualifying node based on the results. interval sets the test period, while tolerance reduces frequent switching when latencies are close. Testing too often increases requests and battery use; testing too rarely fails to reflect route changes promptly. Choose a stable URL with a small response body that represents real outbound connectivity. Avoid pages requiring login, complex redirects, or heavily region-restricted access.

fallback emphasizes availability order: when the current node fails, it moves to the next available item. load-balance distributes connections across multiple nodes according to a policy and suits cases where session consistency requirements are understood. Services such as login, payments, or long-lived connections that need a stable source address are not good candidates for arbitrary load balancing. The results from an automatic group are not a ranking of real browsing speed; they apply only to the test URL and network conditions at that time.

proxy-groups:
  - name: "Node selection"
    type: select
    proxies:
      - "Hong Kong auto"
      - "Manual selection"
      - DIRECT

  - name: "Manual selection"
    type: select
    proxies:
      - "SS-Example"
      - "Trojan-Example"
      - "VLESS-Example"

  - name: "Hong Kong auto"
    type: url-test
    proxies:
      - "SS-Example"
      - "Trojan-Example"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

Dynamically importing nodes through a Provider

When nodes come from a subscription Provider, a proxy group can use use to reference the Provider name instead of listing every node in proxies. Some cores also support filter and exclude-filter to select nodes by name. These filters usually use regular expressions, so character ranges and parentheses must be escaped correctly. When subscription naming is inconsistent, filtering only for “港” or “HK” may miss nodes or select description entries containing the same characters. Inspect the actual node names first, then build the filter expression.

proxy-groups:
  - name: "Hong Kong nodes"
    type: select
    use:
      - provider-main
    filter: "(?i)香港|港|HK|Hong Kong"
    exclude-filter: "(?i)游戏|剩余|到期"

  - name: "Failover"
    type: fallback
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 600

Health checks and connection persistence

A Provider’s health checks and a proxy group’s own URL tests may run at the same time. The former maintains node availability status; the latter selects within the group. Redundant high-frequency tests create unnecessary requests. Make it clear which layer owns health checks and set reasonable intervals. Switching a proxy group does not guarantee that existing connections move immediately; browser connection pools, QUIC, and long-lived connections may continue using the old exit. To verify a switch, close the old connections and make a new request, clearing the application connection pool if necessary instead of checking only the UI selection.

The proxy groups referenced by rules should remain stable over time. A subscription update can change the node list, but it should not arbitrarily rename the groups targeted by rules. A durable structure often includes a main entry point, automatic and manual groups, direct access, and rejection handling, with additional groups for streaming, messaging, or development services as needed. More groups do not automatically mean better routing; only groups that are clearly useful and actually referenced by rules are worth maintaining.

06 · ROUTING

Clash traffic rules: syntax and priority

Rules use the first match from top to bottom

rules is an ordered list. Once connection information satisfies a rule, the core uses that rule’s policy and stops checking subsequent ordinary rules. Specific rules should therefore come before broad rules, and the catch-all MATCH must be last. For example, placing DOMAIN-SUFFIX,example.com,DIRECT before MATCH,Node selection sends the domain directly; reversing the order lets the earlier MATCH catch all traffic, so the later rule never runs.

A typical rule consists of “rule type, match value, policy target,” with optional parameters for some types. Commas separate fields, and the proxy group name must match the configuration exactly. Every line in the rule list must appear as a YAML string item. Domain rules should not include a scheme, path, or port; to match https://sub.example.com/path, extract the hostname and choose an exact-domain, suffix, or keyword rule.

Domain, address, and process rules

DOMAIN matches a complete domain exactly, DOMAIN-SUFFIX matches the specified domain and its subdomains, and DOMAIN-KEYWORD matches a keyword appearing in the domain. Suffix rules are generally easier to control than keyword rules. A keyword that is too short can broaden matches; a common two-letter string may affect unrelated domains. To cover a service, collect its actual request domains first, then decide how to combine exact and suffix rules.

IP-CIDR and IP-CIDR6 match address ranges. Whether a domain connection enters an address rule depends on the resolution path and the no-resolve parameter. For address rules that should not trigger extra DNS resolution, use no-resolve where supported. GEOIP classifies addresses using a geolocation database, so results depend on its source and update status and should not be treated as an absolute statement of business location. Process rules such as PROCESS-NAME and PROCESS-PATH depend on operating-system support and client permissions, which may vary on mobile devices, in sandboxes, or with TUN implementations.

rules:
  - DOMAIN,api.example.com,Node selection
  - DOMAIN-SUFFIX,example.net,Node selection
  - DOMAIN-KEYWORD,cdn-example,Node selection
  - 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,Node selection

Rule sets and logical combinations

Large rule lists do not belong entirely in the main configuration; use RULE-SET to reference a rule Provider. A rule set stores match conditions while the main configuration assigns the policy target, allowing the same set to use different exits on different devices. Confirm that the Provider’s behavior matches its file contents: domain suits domain entries, ipcidr suits address ranges, and classical supports complete classic rules. A type mismatch may let the file download successfully while preventing the expected parsing.

Some cores support logical rules such as AND, OR, and NOT. They can express combined conditions such as “a process accesses a particular domain,” but they are less readable and less portable across clients than basic rules. Introduce them only when basic types cannot accurately describe the requirement, and document their purpose nearby. As rule complexity grows, match information in the logs is more reliable than visual inference.

rules:
  - RULE-SET,private,DIRECT
  - RULE-SET,applications,DIRECT
  - RULE-SET,streaming,Media services
  - RULE-SET,global,Node selection
  - GEOIP,CN,DIRECT
  - MATCH,Node selection

How to locate an unmatched rule

Start with the connection logs to obtain the actual domain, destination address, process, and matched rule, then return to the configuration. The main domain in a browser address bar does not mean the page contacts only that host; scripts, images, authentication, and APIs may use several domains. If the logs show only an IP address, check whether Clash controls DNS or whether the application connects directly by address. If the expected rule appears after MATCH, moving it earlier explains the issue; if its target group does not exist, fix the reference.

The goal of traffic routing is stability and explainability, not the largest possible rule list. LAN and reserved addresses usually go direct first, specific service rules come next, regional address rules later, and MATCH provides the fallback. After adding a rule, verify both the intended match and unintended effects: does the target service use the expected group, and are unrelated services captured by an overly broad condition? For the combined problem of a connected proxy with no web access, use the step-by-step troubleshooting checklist to check the system proxy, ports, node, DNS, and rules.

07 · EXTERNAL SOURCES

Proxy Provider and rule sets

What a Provider solves

proxy-providers separates external node sources from the main configuration. The main file keeps the proxy group and rule structure, while the Provider updates the node list on a schedule. This preserves stable group names as subscriptions change and lets several automatic groups reference the same node source. A Provider name is an internal reference key and should remain stable; changing the subscription URL does not require editing every proxy group, only the relevant Provider definition.

Common type values include http and file. HTTP Providers fetch content from a URL; file Providers read a local path. path specifies the cache or local file location, and multiple Providers should not use the same path. interval controls the remote update period: a value that is too short causes frequent requests, while one that is too long delays upstream changes. If the client has its own subscription scheduler, confirm whether it overrides the core field.

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: "Subscription nodes"
    type: select
    use:
      - provider-main

Provider file formats and health checks

A proxy Provider’s response must match the core’s requirements and usually contains a node list under the proxies key rather than a complete main configuration. A regular subscription URL, a Base64 node list, or a complete configuration cannot necessarily be used directly as a Provider file. Perform format conversion in a trusted, controlled step and check that node fields were not lost. For differences between subscription formats, see How to convert between Clash subscriptions and other link formats.

health-check periodically validates nodes in a Provider. The principles for choosing its test URL and interval are the same as for automatic proxy groups. A failed health check does not necessarily mean the subscription download failed: the former tests nodes, while the latter fetches the Provider file. Logs should distinguish HTTP update status, file parsing status, and node test results. If an update leaves zero nodes, first check whether the cache file was written, then verify the format and filter expression.

rule-providers behavior types

Rule Providers declare their content type with behavior. A domain file usually stores domains or domain sets, ipcidr stores IPv4 and IPv6 ranges, and classical stores complete rules with types. format can distinguish YAML, text, or a core-supported binary format. When referenced, the main rules use the Provider name and specify a proxy group, such as RULE-SET,private,DIRECT. The policy is not embedded in the Provider file, which is why external rule sets can be reused.

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,Node selection

Update failures, caching, and fallback

When a Provider update fails, the core will usually try to keep using its existing cache, but the exact behavior depends on the client and whether the cache is complete. Without a cache on first load, an unreachable remote URL directly leaves the related nodes or rules unavailable; a device that has run successfully before may continue using the old file. During troubleshooting, record whether it “has never downloaded successfully” or was “previously usable but failed to update now”; the two cases require different approaches.

Remote rules and node sources should use stable HTTPS URLs. Query parameters in a URL may contain subscription identifiers and should not be included in public logs, screenshots, or shared configurations. When sharing a configuration structure, replace the URL and credentials but retain the field hierarchy. Also consider the client’s working directory: relative paths are resolved from the core’s runtime directory, not necessarily from the subscription file shown to the user. When a file cannot be found, the absolute path in the logs is more useful than repeatedly editing ./.

Even after multiple Providers are merged, duplicate node names can remain. Proxy group filters see only the final names and cannot tell which source a duplicate came from. A client override can add a different prefix for each Provider, or names can be standardized during subscription management. For a more systematic approach to managing multiple configurations, see Profile structure basics and multi-configuration management.

08 · MAINTENANCE

Configuration overrides, merging, and system troubleshooting

Why use an override layer

Subscription content is replaced by upstream data during updates, so editing the subscription body directly can erase local changes. An override layer separates stable local settings from remote configuration, such as ports, DNS, additional proxy groups, and rules that must come first. Different clients may call this Override, Mixin, Merge, an extension script, or configuration enhancement, and their merge semantics are not identical. Before using one, confirm whether it performs recursive object merging, array replacement, array appending, or script processing.

Mapping fields can usually be overridden by key, such as changing only dns.enable while keeping the other DNS entries; array fields are more likely to behave differently. If rules is replaced as a whole, the original subscription rules disappear; if local rules are appended, they may end up after MATCH and never match. Proxy groups and nodes are also lists, and merging by name versus position directly changes the result. After applying an override, inspect the final configuration rather than merely confirming that the override text has valid syntax.

# Example: conceptual override content; the actual merge behavior is determined by the client
mode: rule
log-level: info

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

rules:
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - DOMAIN-SUFFIX,example.net,Node selection
  - MATCH,Node selection

Prepending, appending, and removing rules

Local rules usually need to appear before subscription rules, especially when they must override broad rules. Clients that support prepend and append should put precise exceptions in prepend and genuine fallback additions in append. If the client supports only replacing the entire array, you must take responsibility for maintaining subsequent rules. Removing a remote rule usually cannot be achieved by adding an opposite rule; add a more precise rule before it or use a filtering script provided by the client.

Use the correct type when clearing a field. Clear a list with [], a mapping with {}, while deleting a key depends on the override implementation. Writing null may mean deletion, or it may pass an empty value to the core and trigger a type error. If the merger is unfamiliar, test one unimportant field first, compare the results before and after merging, and only then handle the complete rules and proxy groups.

Four layers of checks, from syntax to network

The first layer is YAML parsing: check indentation, colons, list markers, quotes, and field types. When this layer fails, the client usually reports a line number, but the real cause may be on the previous line, such as an unclosed quote. The second layer is configuration references: verify that proxy groups reference existing nodes or Providers, rule targets exist, and Provider paths do not conflict. The third layer is runtime listeners: check that the proxy, control, DNS, and TUN ports started successfully. Only at the fourth layer should you investigate network behavior, including node handshakes, DNS upstreams, rule matches, and whether the application follows the system proxy.

Minimal configuration isolation

When a complex configuration breaks, copy a local test configuration and keep only one known-good node, one select proxy group, one MATCH rule, and the required port fields. Verify the proxy path first, then add DNS, Providers, and rule sets step by step. Reload and test after each addition; the point where the failure first appears defines the main investigation scope. This is somewhat slower than switching several nodes, DNS settings, and modes at once, but the result is repeatable and avoids leaving the cause unexplained after an accidental recovery.

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

After testing, restore the normal log level and move verified changes into a stable override layer. If the problem occurs only on one platform, also consider differences in system proxy implementation, permissions, TUN drivers, and application network stacks. For complete Windows installation and system proxy guidance, see The complete guide to installing Clash on Windows; for general issues, continue in Troubleshooting by category: fundamentals, installation and configuration, usage tips, and troubleshooting.

Maintaining a configuration that can evolve

A stable configuration separates upstream data from local intent: subscriptions or Providers manage nodes, the main configuration manages proxy groups and rules, and the override layer stores device-specific differences. Use stable names for proxy groups, document the reason for custom rules, and avoid defining ports and DNS repeatedly. After a subscription update, check the final node count, proxy group references, and MATCH position; after a client upgrade, focus on field compatibility and override merge results.

When migrating to another device, do not copy only one YAML file. Also record whether Provider caches can be downloaded again, whether the client persists proxy selections, and how system proxy and TUN permissions are configured. The configuration file describes core behavior, but operating-system permissions and client UI state are not fully included. Maintaining this boundary helps you determine whether a problem belongs in the YAML, client settings, or system network.