Clash YAML
Configuration Reference

CHAPTER / 01

YAML Structure Overview and Parsing Order

Start at the top level, then verify references

A Clash configuration that loads successfully is not necessarily one that routes traffic correctly. The YAML parser first handles indentation, lists, and value types; the core then reads top-level fields and resolves references among nodes, proxy groups, rule providers, and rules. Check in that order: confirm the file is valid YAML, verify that every referenced name exists, and only then observe runtime behavior. Starting with a single rule often misses an upstream naming or indentation error.

Common top-level sections include listening ports, operating mode, log level, control interface, DNS, proxy nodes, proxy providers, proxy groups, rule providers, and rules. Field order usually does not change semantics, but consistent layout greatly reduces maintenance effort. Put basic listener fields first, larger node and provider sections in the middle, proxy groups after nodes, and rules last. This creates a natural reading order from raw materials to layout to the finished result.

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

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

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

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

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

The configuration above shows the complete reference chain: the rule sends a request to “Node Selection,” the proxy group references “Example Node,” and the node section supplies the connection parameters. An extra space, full-width character, or case difference in any name can break the reference. Chinese names are supported, but long-term maintenance requires exact consistency. If a name contains a colon, hash, comma, or leading or trailing spaces, quote it to prevent the parser from treating those characters as YAML syntax.

Indentation, Lists, and Data Types

YAML uses spaces to express hierarchy; tabs must not be used for indentation. Two spaces are recommended, with fields at the same level aligned exactly. Lines beginning with a hyphen are list items, and a node object after the hyphen can contain multiple keys. A common failure is indenting the proxies list under the wrong level in a proxy group, causing the core to treat it as an unknown field or to consider the group incomplete.

Boolean values should be written as true or false; ports are usually unquoted integers, while names and addresses are strings. Although some parsers accept legacy forms such as yes and on, they can behave differently across clients. For portable configurations, use explicit standard forms. Quote numeric passwords, identifiers beginning with zero, and text containing special characters to prevent automatic type inference.

Use a minimal configuration to isolate errors

When a subscription file contains thousands of lines, the most effective troubleshooting method is not repeatedly editing the original. Save a minimal copy containing one port, one node, one selection group, and two rules. If it loads, the basic fields and client environment are sound. Then add DNS, providers, and custom rules section by section to identify where the error enters. Add one logical area at a time, reload, and check the logs immediately so cause and effect remain clear.

CHAPTER / 02

Common Fields: Ports, Modes, and the Control Interface

Defining the role of each listening port

port listens for HTTP proxy requests, socks-port listens for SOCKS5 requests, and mixed-port accepts both on the same port. Graphical clients often prefer mixed-port because the system proxy and SOCKS5-capable applications can share one entry point. They do not all need to be enabled at once; if several are configured, make sure the ports are unique and are not occupied by browser debugging tools, local development servers, or another proxy process.

System proxy settings only direct the operating system's HTTP or SOCKS requests to a listening port; they do not automatically correct numeric values in the configuration. After changing mixed-port, check that the client's system proxy switch is using the new port. If a browser reports connection refused while the core logs show no requests, first verify the system proxy address and actual listening port rather than changing rules.

port: 7891
socks-port: 7892
mixed-port: 7890
redir-port: 7893
tproxy-port: 7894

allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false

redir-port and tproxy-port are mainly for Linux gateways, routers, and transparent proxy setups. They require operating-system forwarding rules; adding them to YAML alone will not route traffic into the core. Desktop users generally do not need to enable these ports manually. To handle more application traffic, configure TUN mode in a supported client instead. See the Linux section of the download page for Linux clients and core entry points.

LAN Access and Bind Addresses

allow-lan controls whether connections from devices other than the local machine are accepted. With false, the proxy is mainly available to the current device; with true, the reachable scope also depends on bind-address, the operating-system firewall, and the LAN address. Before enabling LAN listening, confirm the boundaries of the home or office network and avoid exposing the control interface to an untrusted network.

bind-address specifies the listening address. An asterisk means the core listens on available interfaces according to its rules, though the exact behavior also depends on the platform and client. For local-only use, keep the client's default setting. To proxy a phone through a computer, place both devices on the same LAN, enter the computer's LAN address and mixed-port in the phone's proxy settings, and allow the corresponding inbound firewall rule.

rule, global, and direct modes

mode: rule matches rules from top to bottom and is the most common mode for everyday use. global sends traffic to the global proxy group, which is useful for temporarily testing whether a node connects but bypasses the normal routing decisions. direct connects traffic directly and helps determine whether the proxy path is causing the problem. Use these modes briefly for comparison during troubleshooting, then restore rule mode.

Changing modes only changes where traffic decisions begin; it does not repair node parameters or DNS responses. If global mode also fails, continue checking the node, network, and system time. If global works but rule does not, the issue is more likely the rule order, target proxy group, or rule provider. Treating mode as a diagnostic switch produces clearer results than repeatedly rewriting node fields.

Logs and External Controllers

Common log-level values include silent, error, warning, info, and debug. Keep info for everyday use to make rule matches easy to observe. Temporarily use debug for complex investigations, then restore the normal level so detail does not bury important errors. The sequence “matched rule → selected policy → actual node” is a complete diagnostic trail; check each step in order.

external-controller lets a graphical interface communicate with the core, for example through a port bound to the local loopback address. Clients usually manage this field automatically, so do not change it casually without understanding how the interface connects. If the panel cannot read proxy groups while the proxy itself works, check the control address, port, and client settings before deleting proxy nodes.

CHAPTER / 03

DNS Fields, Enhanced Modes, and the Resolution Chain

The DNS section handles more than a single server address

Clash DNS configuration performs several jobs: it determines which resolvers receive queries, whether application DNS requests are intercepted, how domain information is retained for rule matching, and how node server names are resolved before a proxy connection is established. Replacing one nameserver line often cannot solve every issue because node server addresses, direct domains, and proxied domains may use different resolution stages.

dns.enable controls whether the built-in DNS module is enabled. listen specifies its address and port; graphical clients often manage these together with TUN or system settings. ipv6 determines whether the DNS module returns IPv6 results. It is related to the top-level ipv6 field but has a different role: the former affects resolution results, while the latter affects IPv6 use throughout the core. If the network has no reliable IPv6 path, unusable AAAA records can cause connection delays.

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 1.1.1.1
    - 8.8.8.8
  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  proxy-server-nameserver:
    - 1.1.1.1
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "time.*.com"

How default-nameserver and nameserver differ

nameserver is the primary resolver list. It can contain ordinary UDP addresses or encrypted DNS addresses supported by the core. When encrypted DNS is specified by hostname, the core must first resolve that service hostname to an IP during startup; default-nameserver normally handles this step. Therefore, use directly reachable IP addresses for default-nameserver rather than another hostname that itself requires resolution, which would create a circular dependency.

proxy-server-nameserver resolves the server hostname of a proxy node. When a node address is a hostname, the core needs its IP before establishing the proxy connection; this step cannot depend on a tunnel that does not exist yet. Resolver reachability varies by network. If every node times out but nodes using an IP address recover, check this field and the local network's DNS reachability first.

Some mihomo configurations also use nameserver-policy to send queries for selected domains to designated resolvers. This is useful when the same domain returns different results inside and outside a network, but the policy must remain easy to reason about. A large set of duplicate domain policies makes both DNS and rules responsible for routing, complicating diagnosis. Stabilize DNS resolution first, then use rules to control traffic destinations.

fake-ip and redir-host

fake-ip returns mapped addresses from a reserved pool to applications. The core retains the domain association, enabling domain rules and sniffing-based routing decisions. The address is not the website's real address. When an application connects to the fake address, the core looks up the mapping and establishes the actual connection. This mode generally suits modern desktop and mobile clients and reduces information loss caused by resolving before matching.

redir-host follows a more traditional resolution flow: the application receives the real result and then connects. Programs that depend on local network devices, LAN discovery, or unusual DNS behavior may be more compatible with this mode, but the core may have less domain context than with fake-ip. Neither mode is universally preferable; choose based on client defaults, TUN implementation, and application compatibility rather than mixing them casually across configuration fragments.

fake-ip-filter excludes domains that should not receive fake addresses. LAN devices, time synchronization, and some login or connectivity-check domains may require real results. Do not expand the filter without limit: adding many ordinary domains weakens fake-ip's domain-mapping advantage. Record the symptom behind each addition and retest after application or network changes.

CHAPTER / 04

Proxy Node Fields and Connection Parameters

Every node starts with four basic details

proxies is the local node list. Each item needs at least a name, type, server address, and port, followed by protocol-specific authentication, transport, and TLS fields. The node name is an internal reference identifier used by proxy groups; the server is the actual connection target; and the port is the remote service's listening port, entirely different from the local mixed-port. Confusing these two kinds of ports is one of the most common manual configuration errors.

Node parameters must correspond as a set to the server configuration. A mismatch in protocol, encryption, credentials, transport, hostname, or path can appear as a timeout or handshake failure. Changing proxy groups cannot repair an incorrect node. Start with the protocol's basic fields, then add TLS, WebSocket, or other transport options one layer at a time while watching which stage fails in the logs.

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

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

The addresses and credentials in the example illustrate structure only; real use requires a legitimate service configuration. udp indicates whether the node may carry UDP traffic, but support also depends on the protocol, server, and network path. Even when set to true, it will not provide usable UDP forwarding if the server lacks that capability. For problems with games, voice, or some DNS traffic, verify node capability and confirm that the proxy group actually selects that node.

TLS, SNI, and Certificate Verification

Protocols using TLS usually require the correct server name. sni sends the target hostname during the handshake. It need not match the server field used for the connection, but it must match the server certificate and deployment. When logs report a certificate name mismatch, check the SNI supplied by the service provider instead of disabling certificate verification first.

skip-cert-verify controls whether certificate verification is skipped. A stable configuration should keep false and correct device time, the certificate chain, SNI, or network interception issues. An incorrect system clock can make valid certificates appear not yet active or expired; a broken system root-certificate environment can also affect connections. Setting this field to true is suitable only for a short comparison test, not as a substitute for finding the cause.

Read transport fields as one object

WebSocket and similar transports commonly include a path and request headers. Slashes, case, and encoding in the path must match the server; the Host header may also control reverse-proxy routing. An indentation error can move fields out of the ws-opts object, causing the core to ignore them. For “TCP connected, then disconnected,” read the logs through the TLS handshake, HTTP upgrade, and application-protocol stages.

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

Different cores and protocols may use field names such as sni and servername; do not substitute them merely because their meanings seem similar. Before migrating to mihomo, check the fields supported by the current client. For core relationships and compatibility limits, see Differences between the mihomo core and original Clash.

Node Names, Duplicates, and Health Checks

Node names should be unique. If two nodes share a name, a proxy group may reference the wrong object and the client interface cannot distinguish them. Duplicate names from a subscription provider may return after an update, so add a prefix, suffix, or filter during the override stage. Names should describe region, route, or purpose; avoid putting live latency in a name because it quickly becomes inaccurate after updates.

A node appearing in the list only means the YAML was read; it does not prove that the connection works. Use the client's connectivity test, then verify with a real webpage or target application. The test address, DNS, node protocol, and target site may take different paths, so one result cannot cover every scenario. If all nodes fail simultaneously, check the local network, DNS, and system time first. Only when one node fails should you focus on that node's fields.

CHAPTER / 05

Proxy group types, references, and selection logic

Proxy groups are the layout desk between nodes and rules

proxy-groups does not create a new protocol connection. It organizes existing nodes or other proxy groups into logical units for selection, testing, or failover. The final column of a rule usually points to a proxy group, which then decides which node to use. Naming groups by purpose—such as “Node Selection,” “Streaming,” or “Direct Services”—is easier to read than stacking protocol names into group names.

A proxy group can reference nodes or other proxy groups defined earlier. Multiple layers help separate region selection from service routing, but excessive depth makes diagnosis harder. Two or three layers are usually enough: actual nodes or providers at the bottom, regional or test groups in the middle, and service policies at the top. When something fails, expand the rule target one level at a time until you reach the final node.

proxy-groups:
  - name: "Auto Select"
    type: url-test
    proxies:
      - "Node A"
      - "Node B"
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 80

  - name: "Node Selection"
    type: select
    proxies:
      - "Auto Select"
      - "Node A"
      - "Node B"
      - DIRECT

  - name: "Failover"
    type: fallback
    proxies:
      - "Node A"
      - "Node B"
    url: "https://www.gstatic.com/generate_204"
    interval: 300

The difference between select, url-test, and fallback

select lets the user choose one member manually. The result is stable and easy to explain, making it suitable as a top-level entry point. If the client saves the selection, it usually restores it after reloading the configuration, but a renamed or rebuilt group may return to its default. Put the preferred default member first to reduce unexpected routing on the first load.

url-test periodically requests a test URL and automatically selects a member based on the result. It measures connectivity and response time from the node to that target, not the actual speed of every website. interval controls the test interval; setting it too short adds background requests. tolerance reduces frequent switching when results are close. Automatic groups work well for daily selection, but important services should still be checked through real usage.

fallback uses available members in order and moves to the next when the current one fails, prioritizing stability over the lowest response time. The list order therefore matters; put the preferred route first. If the test URL is unreachable on the current network, every node may be marked unavailable. Use a stable target with a short response that is reachable within the same network scope as the nodes.

load-balance and connection continuity

load-balance distributes connections among members according to the core's support and group parameters. It does not combine multiple nodes into one download or guarantee random switching for every request. Services sensitive to login state or source address may not suit cross-node distribution, because a session using different exits can trigger reauthentication or disconnect.

Before choosing load balancing, confirm that the service allows its exit location to change. Web browsing and multi-connection downloads may benefit, while remote administration, payment logins, and long-lived connections need a stable path. Design proxy groups around business constraints rather than accumulating features. Without a specific requirement, select plus a single url-test group is usually clear enough.

Use use to import provider nodes

When nodes come from proxy-providers, a proxy group can use use to reference the entire provider instead of listing every node under proxies. Nodes added or removed by subscription updates then enter or leave the group automatically, which is better for long-term maintenance. proxies and use can be combined where the core supports it, but check the final membership for duplicates.

proxy-groups:
  - name: "Subscription Nodes"
    type: select
    use:
      - provider-main
    proxies:
      - DIRECT

  - name: "Auto Test"
    type: url-test
    use:
      - provider-main
    url: "https://www.gstatic.com/generate_204"
    interval: 600
    tolerance: 100

A rule targeting an empty proxy group cannot obtain a usable node. Common causes include a failed provider download, a filter that excludes every node, a misspelled provider name, or a group referencing a local node that does not exist. When the client shows an empty group, check provider status and the original node count first, then inspect filters instead of immediately changing rules.

CHAPTER / 06

Rule Syntax, Ordering, and Matching Boundaries

Rules run top to bottom, using the first match only

rules is an ordered list. In rule mode, the core checks requests from the first entry downward and immediately sends a match to its specified policy. It does not continue looking for a more specific rule. Put precise scopes before broad ones, exceptions before the general rules that would cover them, and the catch-all rule last. Identical rules in a different order can produce completely different behavior.

A rule usually consists of a rule type, match value, and target policy separated by English commas. The target can be a proxy group or a built-in action such as DIRECT or REJECT. Chinese full-width commas look similar but are not field separators. After copying rules, check punctuation, surrounding spaces, and target names, especially when copying from formatted documents that may introduce full-width characters.

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,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
  - PROCESS-NAME,example.exe,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

Domain rule precision

DOMAIN matches one exact domain and is useful for a single-host exception. DOMAIN-SUFFIX matches the specified domain and its subdomains, making it suitable for an entire site namespace. DOMAIN-KEYWORD can match any domain containing the text, so it has a wider scope and a higher risk of false positives. Prefer exact domains and suffixes; use keywords only when the target changes frequently according to a clear pattern.

For example, write DOMAIN,internal.example.com,DIRECT before DOMAIN-SUFFIX,example.com,Node Selection to keep the internal host direct. If the suffix rule comes first, the exact rule never runs. When a domain is routed incorrectly, find the actual request domain in the logs and search downward from the top for the first rule that could match it, rather than checking only whether the expected rule exists.

IP-CIDR and no-resolve

IP-CIDR matches target IPv4 addresses by network range; IPv6 uses the corresponding IPv6 rule type. The CIDR suffix specifies the network prefix length, and an overly broad range can cover many addresses. LAN ranges should usually be routed directly before proxy rules so routers, printers, and storage devices are not sent to a remote node.

no-resolve tells the core not to trigger an additional lookup for a domain-only request when evaluating the IP rule. It suits rules that only need to inspect an existing destination IP and can reduce unnecessary DNS queries. Whether to add it depends on the rule's purpose; if resolving the domain is required to obtain the target IP, do not add it mechanically. Understanding when resolution occurs matters more than copying a parameter.

Process Rules and Platform Differences

Process rules such as PROCESS-NAME and PROCESS-PATH depend on operating-system permissions, core capabilities, and how the client takes over traffic. Windows, macOS, Linux, and Android have different conditions for obtaining process information. A rule matching on one platform may not match on another. Under TUN mode, process recognition also depends on the client implementation and permission settings.

When a process rule fails, first confirm the process name or path visible to the core in debug logs, then write the rule using that actual value. Executable paths can change after updates; check case and extensions for the platform. For cross-platform configurations, domain rules are generally easier to keep consistent. Use process rules as platform-specific overrides rather than placing them in a subscription shared by every device.

GEOIP, Rule Sets, and the Catch-all

GEOIP matches according to the region associated with the destination IP in its database. Results depend on the database contents and update date. It works as a later, broad regional check, not as a replacement for explicit domain rules. Resolved addresses can change with network conditions and CDN routing, and one service may span several regions. Use more specific rule sets or domain rules for important traffic.

MATCH matches every request not previously matched and must be last. If it appears in the middle, all following rules become ineffective. Choose direct or proxy behavior for unmatched traffic according to the configuration's purpose: use direct for allowlisted proxying, or send it to a general selection group when proxy-by-default is intended. Make the group name clearly express the consequence.

rules:
  # Local and explicit exceptions
  - DOMAIN,printer.lan,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

  # Service rules
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,proxy-domain,Node Selection
  - RULE-SET,private-ip,DIRECT

  # Regional checks and final catch-all
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

For a complete review of custom rules, see Clash Custom Rule Syntax Explained. After editing, do not stop at confirming that the configuration loads. Test targets representing an exact domain, subdomain, IP, and catch-all case, and verify the matched rule and final policy in the logs.

CHAPTER / 07

Proxy Providers, Rule Providers, and Subscription Updates

proxy-providers manage updateable node sources

proxy-providers separates a remote or local node collection from the main configuration. The main file defines policy structure, while the provider supplies node content, allowing them to update on different schedules. Subscription updates then do not rewrite the entire rule set, and multiple groups can share the same nodes. When supported by the client, this layered structure is easier to maintain than expanding a large node list directly under proxies.

Each provider needs a unique name, type, source URL, cache path, and update interval. Remote providers commonly fetch YAML over HTTP, while path specifies the local cache location. Clients may resolve relative paths from different root directories. After migration, if files cannot be created or the cache stops updating, check the client's working directory and file permissions.

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

A provider's health check periodically tests its nodes, but it is separate from a proxy group's url-test. The former maintains node availability; the latter selects a member within a group. Setting both intervals too short creates duplicate requests, so schedule them according to node turnover and actual needs. When a subscription URL fails, the client may continue using its local cache; being connected now does not prove that remote updates still work.

rule-providers manage grouped rules

rule-providers stores large domain or network-range rule sets in separate files, while the main configuration references them with RULE-SET. Common behavior values include domain, ipcidr, and classical. Domain sets contain domain matches, ipcidr sets contain network ranges, and classical sets can contain traditional entries with rule types. The provider content must match its behavior; a successful download does not guarantee successful parsing.

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

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

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

Files using the domain behavior usually contain only domain entries and should not include a target policy; the policy is specified on the main configuration's RULE-SET line. Classical files may contain complete prefixes such as DOMAIN-SUFFIX. Confusing these formats can make a downloaded rule set appear to match nothing. Check provider status, parsed entry count, and the referenced name in the main rules together.

The boundary between subscription updates and local configuration

A Profile typically combines remote subscriptions and local configuration. Remote subscriptions are suited to changing node lists; local configuration is suited to device-specific ports, DNS, and rules. Direct edits to a generated subscription file may disappear on the next update, while copying every node locally sacrifices automatic updates. A safer approach is to keep the subscription as raw input and organize policy through client overrides or a separate main configuration.

When managing multiple Profiles, label each by purpose, such as “Desktop daily,” “Mobile network,” or “Rule testing,” instead of naming them only by import date. After switching profiles, confirm the active profile, system proxy status, and policy selection because clients may save state separately for each one. See Clash Profile Configuration Basics for importing, switching, and organizing profiles.

Layered troubleshooting for update failures

When a provider update fails, first distinguish a network error, HTTP status error, file-format error, or cache-write error. A network error means the address cannot be reached; an HTTP error means the remote server returned an unexpected status; a format error usually occurs after download during parsing; and a cache error concerns the path or permissions. The stage recorded in the logs is more useful than repeatedly clicking Update.

If a remote address requires a proxy, also confirm which network path the core uses to update the provider. At startup, policies may not yet be fully available, so relying on a proxy to obtain the core configuration can create a startup loop. Keep a basic configuration that can initialize directly, and ensure provider failure still leaves clear logs and a usable local cache.

CHAPTER / 08

Overrides, Merging, and Final Configuration Checks

The merged result is what actually takes effect

Many graphical clients apply overrides, scripts, or merged configuration on top of a remote subscription. User-edited fragments are only inputs; the core ultimately reads the client-processed result. If troubleshooting looks only at the original subscription or override file without checking the final configuration, fields may appear active when they are not. When the client can export the running configuration, inspect that export first and compare it section by section with the intended result.

Merging usually involves replacement, appending, and deletion. Scalar fields such as mixed-port often use the later value; mapping objects such as dns may merge by key or be replaced as a whole; lists such as rules and proxy-groups vary most. Some clients append, some merge by name, and others overwrite completely. Never assume one algorithm across clients; test a small sample before migrating a configuration.

# base.yaml
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1

rules:
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

# override.yaml
dns:
  ipv6: false

rules:
  - DOMAIN,internal.example.com,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

If a client deep-merges dns, the final result may retain enable, enhanced-mode, and nameserver while adding ipv6. With whole-section replacement, the final DNS section might contain only ipv6, so the configuration cannot work as expected. For rule lists, a precise exception appended at the end may be intercepted earlier by an existing GEOIP or MATCH rule. Decide explicitly whether to insert it before those rules or reorder the entire list.

Risks of merging proxy groups by name

Some override tools treat same-named proxy groups as one object and merge their members. This can add a local group to an existing “Node Selection” group, but it can also create duplicates or preserve unwanted fields. Other tools replace the old group entirely; if the override omits type, proxies, or use, the final group may be incomplete.

When handling a proxy group, make the override's intention explicit: does it replace the group entirely or only add members? If the client's semantics are unclear, use a new group name, verify that rules reference it correctly, and only then decide whether to take over the original group. Renaming also affects saved manual selections; if a selection suddenly returns to its default after an update, check whether the group name changed during merging.

Preserve rule-order intent in overrides

Local rules usually add device-specific direct routes, process rules, or service exceptions. They must appear before broad subscription rules, so simply appending them often has no effect. A stable layout divides rules into four sections: local exceptions, remote rule sets, regional checks, and the final catch-all. If the client offers pre-rule and post-rule entry points, put exceptions before the subscription and additional catch-alls after it, while keeping only one true final MATCH.

Rule deduplication cannot compare only complete lines. Two rules may overlap while targeting different policies, such as an exact-domain direct rule and a suffix proxy rule; both may be needed, with order expressing the exception. A deduplication script that keeps only the later entry can change the intended behavior. After changing rule-generation logic, choose representative domains and inspect the logs instead of comparing only line counts.

Checklist: From Parse Errors to Runtime Errors

The first layer is YAML syntax: check indentation, colons, hyphens, quotes, and data types. The second is structural references: check proxy group, node, proxy provider, and rule provider names. The third is resource loading: confirm remote files download successfully, the cache is writable, and the format matches the behavior. The fourth is the runtime environment: confirm ports are free, permissions are sufficient, and the system proxy or TUN points to the current core. Only then inspect request decisions: DNS results, rule matches, proxy-group selection, and the final node.

This layering prevents downstream changes from hiding upstream errors. Changing DNS will not fix a port conflict; adding rules will only send more traffic to an empty group; and switching to global mode will not fix incorrect node TLS parameters. Capture only log information relevant to the current layer, move on after it passes, and the fault domain will narrow step by step.

Build a reversible editing workflow

Before each change, keep the last known-good configuration and record the single problem being addressed. File names may include purpose and revision numbers, but do not keep same-named copies with different contents in multiple directories. After editing, first load-test the syntax, then test one direct destination, one proxied destination, one LAN destination, and one destination requiring a special rule. These four samples cover most configuration paths.

If behavior changes after a client update, compare the final configuration and core logs first instead of assuming the subscription changed. The client may have changed default DNS, the TUN stack, merge semantics, or the configuration directory. Explicitly place important fields in a local override and document their purpose to reduce uncertainty from changing defaults, while periodically removing exceptions that no longer have a clear reason to exist.

After checking the configuration, return to the connection-verification steps in the User Guide and complete the full flow from system proxy and policy selection to webpage access. If you switch graphical clients, note that Clash Plus, Clash Verge Rev, FlClash, and Clash Nyanpasu do not support exactly the same YAML fields. Confirm the core dependencies before migrating. See the Clash Download Center for recommended desktop and mobile entry points.

A reliable Clash YAML file is not the one with the most fields; it is the one where every field has a clear purpose, every reference is traceable, and every update produces an explainable result. Checking structure, common fields, DNS, nodes, proxy groups, rules, providers, and overrides in that order is like proofreading from individual characters to the full page: first verify each character, then the composition, and finally that the printed result matches expectations.