Clash YAML Configuration Field Reference

YAML Structure Overview

A configuration file describes how connections are handled; it is not a list of parameters to combine arbitrarily. Core fields determine how the service listens, DNS handles name resolution, proxies provide outbound connections, proxy groups organize outbound choices, and rules route connections to the appropriate policy. When reading a file, identify these top-level sections first, then follow references between names. A file can parse successfully and still fail to load or connect if a rule references a nonexistent group or a proxy group references the wrong node name.

Mappings, Lists, and Indentation

YAML mappings use keys and values, list items begin with a hyphen, and indentation with spaces indicates nesting. Use two spaces consistently and avoid tabs. Add one space after a colon and align sibling fields. The configuration below uses only the built-in direct policy. It illustrates the top-level structure but does not provide a remote proxy; it can help confirm that a configuration loads, but should not be mistaken for a subscription containing nodes.

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

proxies: []

proxy-groups:
  - name: Proxy Selection
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Proxy Selection

Here, proxies: [] means an empty list. It is not the same as a missing field or an empty string. proxy-groups is a list, and each item is a mapping; the group's proxies is a list of names. Although the same field name appears at the top level and inside a group, its meaning differs by context. When editing, check the field's nesting level rather than searching for a word and replacing every occurrence.

Quote text containing a hash, colon, or special character, especially passwords, subscription URLs, and identifiers that look like numbers. In some positions, an unquoted hash starts a comment; double quotes can also trigger backslash escaping. Single quotes work for ordinary text. If the text itself contains a single quote, YAML represents it with two consecutive single quotes. Use true or false for boolean values and integers for ports; do not mechanically convert every value to a string.

Files, Profiles, and Runtime Configuration

A profile in a GUI client is often just an input source. The client may also add listening ports, a control interface, TUN settings, and user overrides before generating the runtime configuration passed to the kernel. Differences between the original subscription and the runtime file do not necessarily mean that the import failed. To find out why a field is not taking effect, first identify the active profile, then check the runtime configuration preview or relevant client logs.

A mapping should not define the same key more than once at the same level. For example, writing one dns section and then another at the end of the file is not a reliable way to append settings. Different parsers may reject duplicate keys or keep only one section. Put the required child fields in a single mapping to express the intended configuration clearly. Appending lists and recursively merging mappings are behaviors of a client or script, not universal features of the YAML format itself.

Save files as UTF-8 and keep a copy that starts successfully. If an error occurs, restoring that copy and narrowing the change is usually easier than repeatedly reinstalling the client. In environments that support command-line testing, use the command below to check the configuration. The executable and configuration paths must match your local directories. A successful test means the kernel accepts the configuration; it does not guarantee that remote nodes, DNS, or network permissions are working.

mihomo -t -f ./config.yaml

Original Clash, mihomo, and different GUI clients do not support exactly the same fields. Before copying an example, check which kernel the client actually uses rather than inferring it from the app name. For an overview of how the GUI and kernel work together, see The Clash Open-Source Ecosystem and Client Landscape. This handbook focuses on dependencies between configuration fields.

Core Fields and Traffic Handling

Core fields determine how traffic reaches the kernel and how the kernel handles connections. Listening ports, the system proxy, and TUN are related but distinct concepts: a port is a local entry point provided by the kernel, the system proxy setting tells applications where that entry point is, and TUN receives packets that match routing conditions through a virtual network interface. Configuring a listening port alone does not mean the system is sending application traffic to it.

Listening Ports and Access Scope

Port numbers are not fixed guarantees; the values in examples are simply common choices. If another local process already uses a port, the kernel may be unable to listen on it. Check the address and port in the logs first, then change the conflicting setting. If the client manages the system proxy, confirm that it updates the system setting to the new port as well. Changing a number in the subscription while the client still points to the old entry can leave the kernel running normally while the browser cannot connect.

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

The bind address controls which local interface a service listens on. For local use only, keep the entry point within the loopback scope. To share it with devices on the local network, evaluate the bind address, LAN access, and firewall rules together. The controller interface manages the kernel; it is not the proxy port that a browser should use. Before exposing it to other devices, configure access credentials and restrict its network scope. Do not confuse it with the proxy entry just because both use ports.

Rule, Global, and Direct Modes

rule mode uses the rule list to select a policy; global mode sends connections to the global policy; direct mode handles traffic without a proxy. Choosing a mode does not replace checking node connectivity. Global mode also does not mean that every application is being routed through the kernel. If an application does not use the system proxy, switching to global mode usually will not change its traffic path. Confirm how the application is routed before evaluating the result.

TUN Mode and Platform Permissions

TUN can handle applications that do not read system proxy settings, but it involves a virtual interface, system routes, and runtime permissions. Different clients may create the interface through a service process, administrator authorization, or a platform network extension. Do not apply permission steps for one platform directly to another. The example below shows common mihomo field relationships. If the GUI client already manages these fields, use its settings page to avoid conflicts when it generates the configuration.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

auto-route configures related routes automatically, auto-detect-interface identifies the outbound interface, and dns-hijack helps receive matching DNS requests. These options are not guarantees for every network environment: other VPNs, virtual machine adapters, enterprise networking software, or manual routes can change the path. If local network resources become unreachable after enabling TUN, check routes and exclusions rather than masking the issue by disabling all DNS settings.

The system proxy and TUN can be enabled together, but for troubleshooting, start with one clear traffic-handling method. First confirm that the browser can connect through the local entry point, then enable TUN and test other applications. If a problem appears only after enabling it, focus on permissions, interfaces, and route changes. Record the current settings before restoring them, especially whether the client automatically restores the system proxy; otherwise, the system may still point to a port that is no longer listening after the app exits.

App container access on Windows, VPN authorization on Android, and background services on desktop systems are platform-level traffic-handling issues, not YAML syntax errors. Use the Quick Start for platform-specific steps, then consult the Help Center for problems. When choosing a client, first review the Clash Plus platform options in the Download Center, then confirm that it supports the traffic-handling features you need.

DNS Resolution

A DNS configuration should answer three questions: who sends queries to the kernel, which upstream resolver the kernel uses, and which network path carries the query. Changing a set of DNS addresses does not automatically control encrypted DNS built into a browser, the system cache, or other network services. To analyze DNS leaks, first determine which requests the kernel is expected to handle, then verify the traffic-handling method and logs. Do not draw conclusions from the region shown on a single test page.

Listening, Upstreams, and Bootstrap Resolution

enable controls the kernel's DNS module, listen sets its listening address, and nameserver specifies the upstream for ordinary queries. If an upstream address is a domain name, the kernel must resolve that name first. default-nameserver can provide this bootstrap resolution. The bootstrap resolver must be reachable on the current network; otherwise, a circular dependency can stall the connection before the encrypted upstream is reached.

dns:
  enable: true
  listen: 127.0.0.1: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://cloudflare-dns.com/dns-query
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - localhost

This example illustrates the field structure; it does not mean the listed public resolvers are suitable for every network. Port 1053 also does not automatically become the system DNS server. The client must intercept DNS or another explicit forwarding mechanism must be configured. If the desktop system resolver cannot use a non-standard port, do not simply copy this listening address into its settings. Verify that queries are arriving through kernel logs and application results.

fake-ip and Real Address Responses

In fake-ip mode, the kernel returns a mapped address to the application and keeps the mapping between that address and the domain. When the connection enters the kernel, it can use that mapping to match domain rules. This preserves the domain information needed for routing; it does not actually change the destination server to an address in the mapping range. If an application receives a mapped address but connects directly without going through the kernel, the request may fail. Check that the DNS response path and connection-handling path work together.

fake-ip-filter excludes selected domains from mapped-address responses. Local network services, device discovery that requires real addresses, or applications with compatibility issues may need targeted exclusions. Do not expand the filter to all domains just to handle one domain; doing so changes how other rules receive domain information. After adding a filter, clear relevant caches or restart affected applications so old mappings do not conflict with new responses.

With real-address responses, applications receive actual IP addresses. Whether domain rules can still be used depends on what information the kernel has and how the connection enters it. IP rules may trigger additional lookups, and domain sniffing cannot recover names from every protocol. When comparing the two modes, observe actual rule matches, application behavior, and logs. Avoid generalizing that one mode is always faster or the other is always safer.

Upstream Selection and Query Paths by Domain

nameserver-policy can assign an upstream to specific domains, such as sending internal domains to the resolver on the local network. This selects a DNS server; it does not choose the proxy egress for the eventual application connection. Business traffic is still handled by rules and proxy groups. If you use respect-rules to route DNS connections according to rules, also consider how proxy server domains are resolved. Avoid a dependency where resolving the proxy itself requires a proxy that is not yet available.

dns:
  enable: true
  nameserver:
    - https://cloudflare-dns.com/dns-query
  nameserver-policy:
    '+.example.com':
      - 192.168.1.1

The local network address here illustrates the idea of sending queries to a resolver on the current network; replace it with an address that actually works. If internal company domains are sent to a public resolver, records may not be found. Conversely, sending all external domains to an internal resolver may be affected by that network's policies. When using domain suffix policies, check the match scope by testing one specific domain before expanding the rule.

Start troubleshooting by comparing a domain with its IP address. If the IP is reachable but the domain is not, check DNS logs first. If only one application has a problem, check its own resolution settings. If a node's domain cannot be resolved, fix the bootstrap and node resolution paths first. Retry with a new connection after making changes, and clear system or application caches if needed. See Node Timeouts and Connection Failure Troubleshooting for a more complete sequence.

Proxy Fields

A proxy node defines the protocol parameters needed to connect to a remote service. These are distinct from the node name, region label, and latency test result: the name is used for reference and identification, while the protocol, address, port, authentication, and transport settings determine connection behavior. Obtain the complete parameters from the service provider before configuring a node. Do not infer the protocol from a server address or assume that field names from another client mean the same thing in YAML.

Common Fields and Protocol-Specific Fields

Common fields include name, type, server, and port. The name must exactly match references in proxy groups, so keep it unique and recognizable. type determines which fields that follow are valid. server can be a domain or IP address. port is the remote service's port, not the local listening port. Reversing these two port concepts can make logs show a connection failure rather than a YAML parsing error.

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

This snippet shows the field structure for a Shadowsocks node. The example domain and password cannot be used for a real connection. cipher and the password must match the server; do not change the algorithm name unilaterally in the name of “improving security.” Port 443 does not automatically mean HTTPS or TLS. Determine whether a protocol uses encryption or obfuscation from its protocol and transport fields, not just the port number.

TLS, SNI, and Transport Parameters

For protocols that use TLS, check the relationship between the server name and certificate. The connection address, TLS SNI, WebSocket Host, and path can have different roles. Even if the server deployment happens to use the same domain for each, the fields are not interchangeable. Some protocols use servername, while others use different fields. Follow the configuration structure for the specific protocol instead of creating a supposedly universal parameter list that may not be recognized.

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

For certificate errors, first check the system time, domain, certificate chain, and server settings instead of immediately skipping verification. Disabling verification changes the connection's identity checks; it does not fix an incorrect SNI. If the provider requires a special certificate or transport parameters, confirm the source of those instructions and configure the relevant protocol accordingly. Protocol-specific fields vary widely. This handbook provides a way to check them rather than cramming every protocol's parameters into one example.

Node Definitions and Connectivity

udp: true only allows the corresponding capability in the configuration; it cannot give a server UDP support if the server does not have it. Applications may also be affected by the system proxy type, TUN traffic handling, the network provider, and firewall restrictions. If web pages work but voice or games do not, test TCP and UDP paths separately. A successful HTTP test does not mean every transport type is ready to use.

After adding a node to the file, a proxy group or rule must reference it for it to be used. Adding an entry under proxies does not automatically switch the current egress to that node. When checking the connections page, look at the matched rule, the proxy group it passes through, and the final node. If the rule still selects direct access, do not suspect the new node's password first. If the policy points to the node but the handshake fails, then check the address, authentication, and protocol parameters.

Subscriptions usually contain access credentials, and screenshots or logs may expose complete node addresses. When sharing troubleshooting details, include only necessary fields and hide passwords and sensitive parts of subscription URLs. When comparing a raw link, YAML, and another configuration format, check whether each protocol is fully represented. “Successful conversion” does not mean every capability was preserved. See Subscription Format Comparison and Conversion for related differences.

Proxy Groups

Proxy groups sit between rules and nodes. Rules usually do not need to hard-code a remote node; they can point to a group with a stable purpose, and the group decides which egress to use. This keeps rules unchanged when subscriptions are updated or nodes are switched. When designing groups, define the selection logic and references first instead of stacking up many region-named layers. Each additional nesting level should solve a clear selection problem.

Manual Selection, Automatic Testing, and Failover

select provides manual selection and works well as a user-facing entry point. url-test selects an egress based on a test to a specified URL. fallback selects the first available candidate in order. load-balance distributes connections according to the configured strategy. These types serve different purposes. A low test latency does not necessarily mean the best experience for a particular service, and failover does not combine the bandwidth of multiple nodes.

proxy-groups:
  - name: Proxy Selection
    type: select
    proxies:
      - Auto Select
      - DIRECT

  - name: Auto Select
    type: url-test
    use:
      - Main Subscription
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

This snippet depends on the Main Subscription provider defined later. use references a set of remote nodes; proxies references specific nodes, built-in policies, or other proxy groups. They are not interchangeable just because both display names. You can order top-level sections to suit your reading preferences, but every reference must exist in the final configuration. Keep spaces, symbols, and capitalization in names consistent.

url is the test target, interval is the check interval, and tolerance can reduce frequent switches caused by small test differences. The example values illustrate units and relationships only. If the target is restricted on the current network or for some nodes, the results may reflect the target's reachability more than the overall quality of a node. A failed test to one site does not prove that the server is completely unavailable.

Candidate Scope and Stable Names

When a subscription has many nodes, supported filter fields can narrow the candidate set. Filters often match names and depend on the provider's naming conventions. If region names, symbols, or labels change, an expression that once worked may return no nodes. After changing a filter, inspect the group's actual members rather than checking only whether the YAML passes a test. Regular expressions require attention to both YAML quoting and the expression's own escaping rules.

A configuration should not contain multiple groups or nodes with the same name but different meanings. To keep rules stable over time, give business groups clear names such as “Work Services” or “Media Services,” then let the egress groups below them handle node selection. That way, changing node sources does not require rewriting many rules. If every service ultimately uses the same egress, however, one entry group is usually enough; there is no need to add duplicate structures for visual categorization.

Nesting, Caching, and Switch Verification

Groups can reference other groups, but they must not form a loop—for example, Group A references Group B, which in turn references Group A. For complex references, start with the rule target and map the actual egress path one level at a time until it reaches a node or built-in policy. If a path leads back to a group it has already passed through, restructure it. Relying on a kernel error to discover a loop makes maintenance difficult, especially when multiple override files add group members separately.

A client may remember a manual selection, and profile.store-selected can save related state. Saving state does not guarantee that a selection will be restored correctly after a rename: if the old name is gone, the client or kernel may revert to a default candidate. After updating a subscription, check that the current selection still points to the intended egress. This is especially important when independent groups are used for specific services, so a changed selection is not mistaken for a rule-order problem.

Switching policies mainly affects new connections; existing long-lived connections may continue using the previous egress. To verify a change, refresh the app session or establish a new connection, then check the actual path on the connections page. Before closing existing connections, consider the effect on downloads, calls, and other ongoing tasks. See Client Proxy, Profile, and Connection Pages for the locations of relevant controls.

Rule Syntax

Rules are evaluated from top to bottom, and the first match determines the handling policy. When maintaining a rule list, order is often more important than quantity: place specific exceptions before broad rules and the final catch-all at the end. A rule target can be a proxy group, node, or built-in policy, but it must exist in the current runtime configuration. A rule can be syntactically correct and still never produce the expected result if an earlier broad rule catches the connection first.

Domains, Addresses, and Catch-All Rules

rules:
  - DOMAIN,login.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Proxy Selection
  - DOMAIN-KEYWORD,example,Proxy Selection
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,Proxy Selection

DOMAIN matches a complete domain and is useful for handling one host separately. DOMAIN-SUFFIX matches a domain and its subdomains. DOMAIN-KEYWORD matches a keyword in the domain and has a broader scope, so use it carefully. The example sends the login domain direct before handling the rest of the domain suffix. If the suffix rule came first, the login domain would not reach the specific exception later in the list.

IP-CIDR matches a destination within a network range and is commonly used for local network addresses and fixed service addresses. no-resolve means this rule will not actively trigger a domain lookup to make a match. It does not disable DNS globally or skip comparison when the destination IP is already available. It can reduce unnecessary lookups, but if a configuration depends on DNS to match an address rule, account for the resulting limits.

MATCH is the final catch-all for connections not matched earlier. If it is at the top of the list, most later rules will never be reached. The catch-all should express a clear default path rather than treating “uncategorized” as an error. Start with a small, verifiable set of rules and one catch-all, confirm how matches work, and then add larger rule sets. This avoids changing traffic entry, DNS, nodes, and rules all at once.

Process Rules and Platform Differences

Process rules can route traffic by application, but only if the platform, permissions, and traffic-handling path allow the kernel to identify the process. A connection forwarded from another device may not be associated with an app on that remote device. Some platforms' network interfaces also do not provide the same information. A process rule that works on one computer should not be assumed to work on a phone or router.

Domain rules also depend on available information. If an app connects directly to an IP, uses its own resolution process, or enters the kernel through a forwarding method, the connection record may not contain the expected domain. Adding more domain suffix rules may not help; check DNS handling and connection metadata first. Sniffing can recover names in some cases, but protocol and encryption limits mean it should not replace a clear DNS and routing design.

Rule Providers and Actual Matches

RULE-SET references a collection defined in rule-providers. It can be used for domain sets, IP address sets, or classical rules, but the resource format must match the provider's behavior type. Loading a complete configuration file as a domain list, or placing rules with policy targets into a resource that accepts only domains, will cause format problems. The next section covers resource definitions and loading methods.

To troubleshoot incorrect routing, choose one stable and specific target, establish a new connection, and check the matched rule name and policy chain. If the target matches an unintended earlier rule, narrow that rule or change its order. If the correct rule matches but the connection still fails, check the final node and DNS result. This separates “wrong egress” from “unavailable egress” and prevents node problems from being misdiagnosed as rule syntax errors.

Large rule sets change as upstream sources are updated. Keep a small number of local exceptions and define where they are inserted. Do not make temporary edits to remote rule resources and expect them to survive an update. Rules that must remain in place belong in a separate override or local resource; check the final order after subscription updates. For common misunderstandings about modes and rules, see the Help Center.

Subscriptions and Remote Resources

Subscriptions do not all return the same kind of file. Some URLs return a complete Clash configuration, some return only a set of nodes, and others return encoded text containing node share links. A GUI client may offer subscription conversion or preprocessing, but the kernel's proxy-providers does not automatically recognize every format as usable nodes. Check the response structure first, then decide whether to import a complete configuration through the client or load a remote node resource through the kernel.

Proxy Providers

proxy-providers:
  Main Subscription:
    type: http
    url: 'https://subscription.example.com/nodes.yaml'
    path: ./providers/main.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

proxy-groups:
  - name: Proxy Selection
    type: select
    use:
      - Main Subscription

rules:
  - MATCH,Proxy Selection

type: http means the resource is retrieved from a remote URL, url is its address, path is the local cache location, and interval is the update interval. The example URL is for illustration only; replace it with a subscription that actually returns a compatible node collection. The cache path is usually related to the kernel's working directory, not necessarily the directory containing the subscription file. Writable paths can also differ between desktop and mobile clients.

A proxy provider resource usually contains a top-level proxies list, not a complete configuration with ports, DNS, and rules. The example below shows the shape of a resource and still uses parameters that cannot establish a real connection. If a subscription returns a web page, login prompt, or error message, a successful HTTP request will not produce usable nodes. Check the client logs for the response content type and parsing errors.

proxies:
  - name: Subscription Example Node
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: 'your-password'
    udp: true

Update intervals and health-check intervals serve different purposes. The first retrieves changes to node definitions; the second tests the availability of existing nodes. Shortening the health-check interval does not make new nodes appear sooner in a subscription. Frequent checks also increase network requests when there are many nodes. Set these values according to how often the resource changes, device battery constraints, and actual selection needs rather than making every interval very short.

Rule Providers

rule-providers:
  Business Domains:
    type: http
    behavior: domain
    format: yaml
    url: 'https://rules.example.com/business.yaml'
    path: ./rules/business.yaml
    interval: 86400

rules:
  - RULE-SET,Business Domains,Proxy Selection
  - MATCH,DIRECT

behavior determines how the resource is interpreted. Common values such as domain, ipcidr, and classical correspond to different content. format specifies the file encoding format; do not guess from the file extension alone. YAML resources with domain behavior usually wrap entries in payload. Classical rule resources can express more rule types, but they must still follow the required format and must not contain top-level fields from a complete configuration.

payload:
  - '+.example.com'
  - api.example.net

Resource names and cache paths should each be unique. If two providers share a local file, one update may overwrite the other's content. The resource may appear to load successfully while containing rules from the wrong set. After changing a resource type or format, also check whether an old cache is still being used. Do not clear the entire client data directory. Use the logs to locate the specific cache file and keep a recoverable copy.

Update Failures, Bootstrap Dependencies, and Privacy

When a remote resource update fails, the kernel may continue using an existing cache or fail to load if no file is available on first run. Check the logs to determine what happened. If fetching a subscription requires a proxy that can only be obtained from that same subscription, startup has a dependency loop. Provide a reachable update path or a separate bootstrap egress instead of repeatedly clicking update and expecting a node that does not yet exist to download the resource.

Subscription URLs often carry access credentials and should not be placed in public repositories or public conversion services. Before converting a format, find out what content the conversion service can access and then check whether the output preserves protocol, transport, and group information. For multi-device use, distinguish between “syncing the same subscription URL” and “syncing the entire runtime configuration.” The latter may bring listening, routing, and path settings that are unsuitable for another platform.

For use across devices, a stable approach is to share node sources and business rules while leaving platform-specific settings to each client. See Trade-Offs When Sharing Configuration Between a Computer and Phone for options involving private repositories, subscription URLs, and override files. Check the final runtime result using the methods in the next section to verify the resource merge order.

Overrides, Merging, and Validation

Overrides separate local settings that should persist from subscription content that is updated regularly. For example, a subscription can provide nodes and basic policies, while local overrides handle LAN exceptions, business rules, or platform-specific traffic settings. An override is not a universal top-level YAML field; it is a process performed by the client when generating the configuration. Features called “merge,” “override,” or “script” can run at different stages and handle lists differently in different clients.

Confirm the Merge Rules First

Understand mapping merges and list merges separately. Scalar fields are usually replaced by later values. Nested mappings may be merged recursively or replaced as a whole, while lists may be appended, prepended, or replaced outright. If a client preserves existing DNS child fields, do not assume it will also preserve the existing rule list. Read the client's documentation and inspect its preview before making changes; judge behavior by the final result, not the feature name.

# Base configuration snippet
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://cloudflare-dns.com/dns-query

# Fields to add
# Apply these through a merge method supported by the client; do not paste a duplicate dns key.
# dns:
#   fake-ip-filter:
#     - '*.lan'

If a client replaces the entire dns section, submitting only fake-ip-filter may remove the original upstream settings. If it merges recursively, list handling still depends on the implementation. A safe approach is to test one low-risk field first and inspect the complete DNS section in the runtime configuration before applying the intended changes. Keep separate copies of the base configuration and override file during testing.

Prepending Rules and Renaming References

Local rules often need to go before remote rules, especially when a subscription already includes a catch-all. If the client simply appends the local list, the new rules will land after MATCH. They will never match even though the syntax is valid. Use a prepend operation supported by the client or control the insertion point in a script. After editing, inspect the beginning and end of the final rule list instead of checking only the override editor.

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

This shows the desired final order; it is not a universal override instruction for every client. If a local rule references “Proxy Selection” and a subscription update renames or removes that group, the reference will still fail. You can maintain a stable local group name and connect it to the node collection provided by the subscription, or check references after each update. A name once shown in the interface is not proof that it still exists in the current runtime configuration.

Minimal Changes and Layered Validation

Change one layer at a time: first confirm that the file parses, then check name references, listening and traffic handling, and finally business routing. If DNS, TUN, node protocols, and rule order all change at once, you will not know which change fixed the problem—even if it disappears temporarily. Record the purpose, fields changed, and test target for each change to reduce repeated troubleshooting after future subscription updates.

1. Save the current working configuration and note the active profile and key settings.
2. Check YAML indentation, duplicate keys, data types, and name references.
3. Inspect the generated runtime configuration to confirm local fields were not overwritten.
4. Establish a new test connection and check the rule, proxy group, and final node.
5. Update the subscription and reload it to confirm local settings are still applied as intended.

Test at least one direct path and one proxied path. Testing only whether a web page opens may miss a situation where all traffic is incorrectly sent direct or through a proxy. DNS changes also require checking that domain resolution and connections are consistent. TUN changes require checking local network access, other VPNs, and behavior after waking from sleep. A configuration test command checks syntax and some semantics; real network testing must be performed separately.

When moving a configuration between platforms, remove local file paths, interface names, control ports, and platform-specific traffic settings. Share node sources and routing intent, not every runtime detail from one device. For GUI clients such as Clash Plus, use the appropriate platform option in the Download Center to establish a base environment, then migrate configuration as needed. This avoids introducing installation and field compatibility problems at the same time.

The end goal is a configuration whose relationships are clear: each remote resource has a known source, each group name has a stable purpose, each exception has a corresponding test target, and each merge can be inspected. If you are new to the process, return to the Quick Start to establish a working connection. If the configuration loads but problems remain, consult the Help Center or a connection troubleshooting article and work through traffic entry, resolution, rules, and egress in order.