Clash YAML Configuration Reference

1. YAML Structure and Configuration Loading

Know the Difference Between Source and Runtime Files

A Clash configuration is more than a list of proxies. Its top level typically includes listening ports, proxy mode, DNS, proxies, proxy groups, and rules. After importing a subscription, a client may save the remote content, apply local settings, and then generate the runtime file used by the core. That means the subscription text shown in an editor may differ from what the core is currently reading. When troubleshooting, note the selected configuration and find the client’s view of the active runtime config. This helps avoid repeatedly restarting after editing a file that isn’t in use.

Keep the original subscription for server-maintained proxies and groups, and use local extensions for personal rules. Separating them reduces the risk of overwriting your changes during updates. If the client doesn’t clearly show what an extension applies to, test with an easy-to-observe rule and confirm whether it affects only the current subscription. Don’t infer what’s loaded from a filename alone: the selected item in the interface, load results in the logs, and the rules recorded for actual requests should all agree.

Indentation, Types, and References

YAML uses indentation to express hierarchy. Use two spaces consistently and don’t mix in tabs. A space after a colon separates a key from its value, and a hyphen marks a list item. Keep properties aligned across objects in the same list. Ports are usually integers, and boolean values should be lowercase. Quoting a boolean turns it into a string, which can cause type errors in some fields. Proxy and group names are reference identifiers: capitalization, spaces, and punctuation all matter, and near matches aren’t corrected automatically.

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

proxies: []

proxy-groups:
  - name: Egress
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Egress

The example above is a basic, direct-only configuration for checking parsing and references; it does not provide a proxy exit. An empty proxy list is valid, and the group references the built-in DIRECT. When adding proxies, define them under proxies first, then add their names to a proxy group. Rules reference a group to form a chain from request to rule, rule to policy, and policy to egress. Understanding this chain matters more than copying a large set of complex fields all at once.

Quoting and Duplicate Keys

Quote passwords, names with special characters, and strings that could be interpreted as another type. Take extra care with parsing when a string contains a colon followed by a space, a comment marker, or a line break. To include a single quote inside a single-quoted string, write it twice. Double-quoted strings support escapes, so handle backslashes accordingly. Don’t use typographic quotes from formatted web pages as YAML quotes. Comments explain content but don’t change a field’s meaning or replace a required parameter.

Don’t define dns, rules, or proxy-groups more than once at the same level. Some parsers reject duplicate keys; others may keep the last value, making the result unpredictable. Pasting together two examples that each have a dns key does not merge their DNS settings. Keep one parent key and move the required child fields under it. The same applies to lists: add rules to the existing rules list instead of creating another top-level key with the same name.

If you can access the core’s command line, use the test command below. Adjust the executable name and configuration path to match your device. If the desktop client has a configuration check, use that instead. Passing a syntax check only means the file was accepted; it doesn’t prove that a remote proxy is reachable or that the policy behaves as intended. After startup, check listening ports, rule matches, and egress selection. For more on reading logs, see How to troubleshoot runtime logs.

mihomo -t -f config.yaml

2. Ports, Proxy Modes, and Common Fields

Listening Ports Only Accept Requests

port is the HTTP proxy listening port, socks-port is the SOCKS listening port, and mixed-port accepts both HTTP and SOCKS requests on the same port. These are entry points for apps connecting to the local core, not ports on remote proxies. An app’s requests enter the core only after you set its local address and mixed-port; the proxy fields determine how the core connects to remote servers. For a first setup, one mixed port is usually enough. Add separate ports only when you have a clear need for them.

Port conflicts usually happen when two clients run at once, an old core hasn’t exited, or another program is already listening on the same address. If you see an address-in-use error, close duplicate processes before deciding whether to change the port. After changing it, update manual browser proxy settings, terminal environment variables, and settings on LAN devices too. A client reporting successful startup doesn’t mean every app is using the new port. Check each app’s proxy entry point rather than relying on the client’s status toggle alone.

mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false

Rule, Global, and Direct Modes

mode: rule selects an egress according to the order of rules; mode: global sends traffic to the global policy; mode: direct connects directly. Global mode applies only to traffic that has entered the core—it doesn’t automatically take over every app. A program that ignores the system proxy may continue connecting directly even in global mode. To see whether a mode is working, first confirm the request appears in the connection log, then check its egress. For interface steps to switch modes, see Proxy modes.

Global mode is useful for a quick check of whether routing rules are causing a problem, but it isn’t a fix-all for network issues. If rule mode fails but global mode works, check the matched rule and selected group first. If both fail, look at proxy parameters, network reachability, and the DNS resolution path. Direct mode also doesn’t clear the OS proxy settings automatically. An app may still connect to the local listening port before the core sends traffic directly, so make sure the system proxy is restored correctly before shutting down the core.

Listening Addresses and the Management Interface

Understand allow-lan and bind-address together. The first controls whether LAN access is allowed; the second limits which address the core listens on. For local use only, bind to a loopback address. If you need to share access, open it only as required by your network interface, firewall, and authentication settings. Binding to all interfaces doesn’t guarantee that external devices can connect; routing and system security rules also matter. Don’t expose the service to the public internet just to troubleshoot a phone connection.

The proxy entry point and the external-controller management interface serve different purposes. The management interface controls configuration, policies, and connection status; don’t enter it as a browser proxy port. Clients often generate its address and credentials themselves, and manual changes can disconnect the interface. Most desktop users don’t need to expose the management interface just to copy an example. For remote management, plan access restrictions separately rather than reusing the trust boundaries of the proxy listener.

info is usually sufficient for everyday use with log-level. Temporarily switch to debug to investigate an issue, reproduce it once, then switch back. Logs may contain visited domains, proxy names, and local paths; remove personal information before sharing them. If common fields revert every time the client starts, check whether the client’s settings page manages the same options. If so, change them there instead of repeatedly editing a generated file. For differences between browser and terminal behavior, see Troubleshooting system proxy issues by app.

3. Proxy Fields and External Proxy Collections

Fields Shared by Proxy Objects

proxies is a list of proxy objects. Each usually has name, type, server, and port. name is referenced by proxy groups; type determines the protocol and how the remaining fields are interpreted; server is the remote address; and port is the remote service port. Authentication, encryption, and transport fields vary by protocol. You can’t simply change type to another protocol and expect the original parameters to work. Even if the client parses the object, that doesn’t mean the remote server provides the corresponding service.

Keep the proxy parameters from your subscription intact, especially TLS, transport, and protocol-specific fields. Some share links can be converted into proxy objects by a client, but the result is still limited by the core’s supported features. Clients with similar names or interfaces don’t necessarily bundle the same core. Browse the download center when choosing a client; Clash Plus is a good option to consider. Before migrating an existing configuration, use the client comparison to check platform support and configuration compatibility.

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

proxy-groups:
  - name: Egress
    type: select
    proxies:
      - Example Egress
      - DIRECT

The example shows how a Shadowsocks proxy is referenced by a proxy group. The domain and password are illustrative and must be replaced with the service’s actual parameters. cipher must match the server; a more complex value isn’t necessarily better. udp allows the proxy to handle applicable UDP traffic, but it can’t add UDP support to a service that doesn’t provide it. If you change a proxy name, update every proxy group that references it or reference validation may fail.

TLS and Transport Settings Aren’t Optional Tweaks

For protocols that use TLS, server, servername, and certificate verification each have a distinct role. server determines the connection target; servername is typically used for the server name indication during the TLS handshake and for checking the certificate name. They may be the same or different depending on the deployment, so use the values provided by the service. If a connection fails, don’t start by disabling certificate verification. Check the device clock, server name, certificate validity, and network path first so you don’t mask a deployment issue.

The WebSocket path, request headers, and other transport parameters must also match the remote server. A correct server address won’t prevent a handshake failure if the path or headers are missing. Troubleshoot from the bottom up: can the domain resolve, can the target port be reached, does TLS succeed, does protocol authentication pass, and only then, do the rules and destination. If the logs clearly show an authentication failure, stop changing DNS or rule order and check the proxy parameters and account status.

Manage External Proxies with proxy-providers

proxy-providers keep proxy collections separate from the main file. They’re useful when proxies need regular updates but rules and groups should stay stable. Provider content must use a proxy collection format supported by the core; it isn’t an arbitrary web page and isn’t necessarily a complete client subscription. In the main configuration, a group references a provider by name using use. Don’t add the provider name to proxies as if it were a regular proxy. These lists serve different reference purposes and shouldn’t be mixed.

proxy-providers:
  Local proxies:
    type: file
    path: ./providers/local.yaml
    health-check:
      enable: false

proxy-groups:
  - name: Egress
    type: select
    use:
      - Local proxies
    proxies:
      - DIRECT

A local file can use the structure below. Resolve relative paths based on the actual configuration directory and how the client runs; don’t assume they’re relative to the desktop shortcut’s directory. First confirm the file is being read, then check whether the proxies appear. Remote providers also involve update intervals, caches, and request routing. If an update fails, check the download request and whether the old cache is usable separately instead of immediately deleting the whole configuration.

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

A subscription URL may contain account authorization details, so treat it like a credential. When sharing a configuration, check the remote provider URL and request headers as well as passwords. If a service changes proxy names after an update, manually written references to individual proxies may break. Groups that use a provider are generally better able to track changes in the collection. When choosing proxies, consider the use case, region, and traffic policies—not just test results. See How to choose proxies for more guidance.

4. Proxy Group Types and References

Proxy Groups Decide Where Traffic Goes

Proxy groups separate rule references from individual proxies. Rules point to a stable group name, and the group selects a proxy or another group. This usually lets you replace proxies without rewriting every rule. Keep group and proxy names unique and easy to recognize to avoid confusion. When designing groups, map a one-way path for requests: a rule leads to a use-case group, that group leads to a selection group, and the selection group ends at a proxy or DIRECT. Every path needs an endpoint; none should loop back to itself.

select lets you choose manually; url-test chooses automatically based on test results; fallback checks candidates in order for availability; and load-balance distributes connections according to its policy. These group types solve different problems—they aren’t performance tiers. For login sessions that need a stable egress, frequent automatic switching may trigger reauthentication. For general browsing, automatic selection can reduce manual work. Choose a type based on the use case instead of putting every proxy into the same kind of automatic group.

proxy-groups:
  - name: Egress
    type: select
    proxies:
      - Auto Select
      - DIRECT

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

rules:
  - MATCH,Egress

This snippet depends on the local proxy provider from the previous section. url is the target to probe, interval is the interval in seconds, and tolerance is the latency tolerance in milliseconds used for automatic switching. Choose a probe target that represents the intended use and can be accessed consistently. The example address isn’t an external page resource and won’t be loaded by this page’s browser. A successful probe only shows that the test path works; it doesn’t prove that all websites, video services, or UDP apps will work.

Limits of Auto-Selection and Failover

url-test generally favors the candidate that performs best under test conditions, while fallback prioritizes order and availability. If you want a fixed primary egress with a backup used only when it fails, fallback is a better fit than simply chasing lower test times. A failed test could also result from a blocked probe target, a temporary DNS issue, or network jitter; it doesn’t necessarily mean the proxy is completely down. Test with the actual service first, then consider changing the probe target or allowing more time for observation.

load-balance won’t combine multiple routes into a single download connection, nor can it guarantee that every connection uses the same public IP address. Distribution strategies handle destinations and connections differently, so confirm that changing egress is acceptable before using one. Apps involving account risk checks, payments, or long sessions are usually better suited to a fixed selection. Even with load balancing, each connection’s speed depends on the proxy it uses, the remote service, and the local network. The number of proxies in a group isn’t the same as combined bandwidth.

Names, Cycles, and Persistent Selections

A group can reference another group, but the references must not form a cycle. For example, if a use-case group references an egress group that points back to the use-case group, there’s no actual egress endpoint. Before adding another group layer, make sure it has a distinct purpose. Too much nesting can look fine in the interface but make it difficult to see which proxy is ultimately used. When troubleshooting, follow the current selection one group at a time until you reach a proxy, DIRECT, or REJECT, then confirm it against the connection log.

Clients may remember a manual selection and restore the last item in a group after reloading the configuration. Reordering candidates in YAML therefore doesn’t necessarily change the current egress. If the new configuration has loaded but egress hasn’t changed, check the group’s current selection and whether selections persist instead of repeatedly reordering proxies. To reset a selection, use the client’s controls if possible. Avoid deleting the entire configuration directory, which could also remove subscriptions and local rules.

5. DNS Settings and How Fake-IP Works

First, Find Out Where the App Sends DNS Queries

DNS settings determine how the core resolves domains, but apps may not use the core’s DNS. The system resolver, browser Secure DNS, app-specific resolution, and TUN interception can all be in play. If you suspect a Clash DNS leak, first identify which requests bypass the intended entry point, then adjust the settings. Changing nameserver to an encrypted address doesn’t prove that every DNS query on the device goes through a proxy. Encryption protects DNS traffic in transit; proxy egress and request interception are separate concerns.

dns.enable turns on the core’s DNS service, listen sets its listening address, and nameserver specifies regular upstream resolvers. default-nameserver is typically used to resolve domain names in upstream DNS addresses, providing basic resolution during startup. proxy-server-nameserver can specify a separate resolution path for proxy server domains. Distinguish between resolving the target website and resolving the proxy server: if the latter depends on a proxy that isn’t connected yet, startup can get stuck in a loop, with the proxy hostname failing to resolve.

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"
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5

This snippet explains field hierarchy; it isn’t suitable for every network. Upstream addresses must be reachable on the current network. After switching networks, test resolution latency and results again. A port listening on a loopback address doesn’t automatically become the system’s DNS resolver; the client, TUN, or system settings must direct queries to it. If a computer only has the system HTTP proxy enabled while a SOCKS app resolves domains locally, they may use different DNS paths.

Fake-IP and Real Address Mapping

Fake-IP returns a synthetic address to the app and records the original domain in the core. When the connection re-enters the core, the mapping can restore the domain for rule matching instead of treating the synthetic address as a public destination. It isn’t another set of real results from public DNS and shouldn’t be forwarded to the internet by a router. For the configuration to work, DNS resolution and the connection must pass through the same processing chain that recognizes the mapping.

Some LAN discovery, device management, or real-address-dependent apps may not work well with synthetic addresses. Use fake-ip-filter to exclude specific domains as needed. An excluded domain usually gets a normal DNS result, but that doesn’t add a direct-connection rule; rules still determine the final egress. Don’t exclude every domain to fix one app’s compatibility issue, or you’ll lose the domain-mapping benefits of this mode. Start with a specific suffix, clear old caches, and check the scope of the change.

Per-Domain Upstreams and DNS Egress

nameserver-policy can select DNS upstreams by domain. This is useful when corporate intranet domains, LAN suffixes, and public domains need different resolvers. The example uses an illustrative internal DNS address; only use it if it’s a resolver on your network. Even a correct policy will time out if the upstream isn’t reachable through the routing path. Don’t permanently apply an upstream that’s reachable only on an office network to every network environment.

dns:
  nameserver-policy:
    "+.corp.example.com":
      - 192.168.1.1

Settings such as respect-rules affect whether connections to DNS upstreams follow routing rules. Before enabling them, understand the dependencies and configure separate resolution for proxy server hostnames. If all DNS requests must go through a proxy, but the proxy’s hostname itself can only be resolved through that same DNS path, startup will stall. Per-domain DNS and proxy routing are separate sets of rules. Don’t assume a domain’s later connections will use the same egress just because it uses a particular upstream resolver.

After changing DNS, close existing connections, clear client and system caches, and restart apps with built-in caches if needed before making a complete test request. Record the app’s resolution method, the type of address returned, and the matched connection rule. Test IPv6 separately too: disabling core-related options doesn’t stop other system entry points from sending IPv6 requests. If the issue persists, narrow it down using the network troubleshooting steps in Frequently Asked Questions. Don’t disable several security and DNS settings at once.

6. Rule Syntax, Rule Sets, and Match Order

Rules Run Top to Bottom; the First Match Wins

rules is an ordered list, not a collection that’s automatically sorted by specificity. The first matching rule determines egress, and subsequent rules don’t process that request. Put specific domains before broad regional rules, and use MATCH as the final fallback. Any exception added below an earlier catch-all rule won’t take effect. When a website uses the wrong egress, read the matched rule in the connection details and inspect rules above it rather than just searching for the line you expected to match.

A common rule has a type, a match value, and a policy; MATCH needs only a policy. The policy can be a proxy name, group name, or built-in action, but it must exist and be usable. For business rules, use stable group names instead of proxy names that may change often. DOMAIN matches a full domain, DOMAIN-SUFFIX matches a suffix and its subdomains, and DOMAIN-KEYWORD matches a keyword. Keyword matches are broad and shouldn’t replace suffix matching when clear boundaries matter.

rules:
  - DOMAIN,login.example.com,Egress
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Egress

The example depends on a proxy group named Egress. The first line handles a specific login domain, the second handles the sample suffix, and the third handles connections to addresses in the specified subnet. GEOIP uses local geolocation data to determine the destination address’s region; it doesn’t refer to the visitor’s location. The last line catches requests that haven’t matched earlier rules. In a real configuration, account for other private address ranges used on your network too; the single range in the example isn’t a complete list of LAN addresses.

Resolution Timing and no-resolve

Domain rules need the core to have domain information. If an app submits only an address and there’s no usable mapping or other source of domain information, domain rules alone may not match. IP rules can trigger resolution when processing a domain destination. no-resolve means not to resolve a domain just for this rule; it doesn’t prohibit every DNS query associated with the request. If the request already has a destination address, address matching can still happen. If no address is available, the core continues to later rules.

REJECT is a reject action and DIRECT is a direct-connection action; neither is a proxy type. Temporarily rejecting an exact-domain rule can help confirm that rules are loaded, but restore the intended configuration afterward. Don’t diagnose issues with an overly broad keyword rejection rule, which could disrupt logins, updates, or resource domains. A webpage also makes more than one connection: the main site, static resources, and authentication services may use different policies. Check each request instead of treating the page title as representative of them all.

Rule Sets Separate What You Maintain

rule-providers manage external rule collections, unlike proxy-providers, which manage proxy collections. Choose the correct behavior for a rule set; common types are domain, ipcidr, and classical. The file content must match its behavior type. domain collections primarily contain domain patterns, ipcidr collections contain network ranges, and classical collections include rule types and match values. The main configuration assigns a policy when referencing a rule set, so the same collection can use different egress in different configurations.

rule-providers:
  Business domains:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/business.yaml

rules:
  - RULE-SET,business-domains,Egress
  - MATCH,DIRECT

The corresponding local rule set is shown below. Each payload line doesn’t include an egress policy because the main configuration specifies the policy where RULE-SET is referenced. A mismatch in file path, encoding, list indentation, or behavior can cause loading to fail. For remote rule sets, check whether the download succeeded, the cache was updated, and the content matches its declared format. A URL returning an error page doesn’t become a rule set just because its extension is YAML.

payload:
  - DOMAIN,login.example.com
  - DOMAIN-SUFFIX,example.org

When maintaining rules, address an observable issue before broadening coverage. Record the target domain, current match, intended policy, and reason for the change to avoid accumulating exceptions that override one another. Geolocation data, rule set caches, and the main configuration each have their own update cycles; changing one doesn’t refresh the others. If a rule file is correct but behavior never changes, check where overrides are applied in the runtime configuration, then see whether an old connection is still using its previous egress. Updating rules doesn’t usually move existing connections automatically.

7. TUN, System Proxy, and the Limits of DNS Interception

Choose the Entry Point Before Routing Traffic

The system proxy tells apps that follow system settings to send requests to a local proxy entry point. TUN uses a virtual network interface and routing to handle more network traffic. Both operate at the entry-point layer; neither changes proxy authentication parameters or automatically fixes incorrect rules. Command-line tools, games, and apps with their own network stacks may ignore the system proxy. If an app doesn’t appear in the client’s connection log, first check whether the entry point covers it. Consider TUN only if needed; repeatedly changing remote proxies won’t help.

What TUN can actually do depends on the operating system, permissions, client integration, and core implementation. Desktop clients may request permissions through a service component; mobile clients typically use the system’s VPN authorization to establish a network entry point. Missing permissions, a failed virtual interface, or a routing error can all happen before a proxy connection is attempted. The setup steps differ between clients such as Clash Plus, Clash Verge Rev, and FlClash; don’t copy a service installation procedure from one client to another.

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

This snippet shows common field relationships and isn’t guaranteed to run on every platform without changes. enable turns the feature on, stack selects the network stack implementation, auto-route attempts to configure routes, and auto-detect-interface attempts to identify the egress network interface. On systems with multiple adapters, virtual networks, corporate VPNs, or container bridges, automatic detection may not match your needs. Before changing the stack, check whether the logs show a specific error. Don’t treat switching stack as a default optimization when you can’t explain the problem.

DNS Hijacking Doesn’t Capture Every Resolver

dns-hijack sends matching DNS traffic into the core’s resolution flow. The example mainly targets traffic on the corresponding port for traditional DNS. Apps that connect to resolvers over encrypted protocols use a different traffic pattern; this setting alone won’t turn those requests into ordinary DNS queries. Check browser Secure DNS, app-specific resolution, and system resolution separately. To make an app follow a consistent DNS policy, adjust its resolution settings first and verify which path its requests actually take.

When using Fake-IP with TUN, make sure connections to synthetic addresses also enter the same core. If an app has cached a synthetic address and you then turn off TUN or switch to another configuration, the old address may no longer have a corresponding mapping, making some sites suddenly unreachable. Clear the relevant cache and reconnect before changing upstream DNS. Keep track of the order in which you restart the client, restore the configuration, and restart the app; otherwise, it’s hard to tell which action fixed the issue.

Routing Conflicts and LAN Access

Corporate VPNs, other proxy clients, virtual machine networks, and security software can all change routes. When multiple programs try to take over the default route, traffic may loop, use the wrong egress, or lose access to local services. Start troubleshooting with one network interception solution in place and disable other interception entry points before reproducing the issue. This doesn’t mean permanently uninstalling other tools. Once the setup works on its own, check whether the tools can coexist and configure exclusions or routing for networks that need direct access.

If you can’t access a LAN printer, network storage, or development service, check name resolution first, then the destination address and route. A direct rule for a domain won’t necessarily fix a system routing issue that sends traffic through the wrong interface. Conversely, a reachable route doesn’t guarantee that the domain resolves correctly. Test by name and by a known address to distinguish a DNS issue from a connection issue, then make the smallest necessary change. Don’t exclude all traffic from interception just to reach one internal service.

When remotely maintaining a server, don’t apply a desktop TUN configuration that takes over all routes without changes. Prepare console access or another recovery channel, verify that management connections remain available, and then enable features one at a time. For most users, choose a suitable platform from the desktop client downloads. A standalone core is better suited to people who can maintain the service, permissions, and network rules themselves. For first-install permission issues, see Initial setup across platforms.

8. Subscription Overrides, Merging, and Change Verification

Identify Who Owns Each Configuration Layer

Configuration sources can generally be split into remote subscriptions, local extensions, client-wide settings, and the final runtime file. Remote subscriptions provide server-published content; local extensions hold personal rules; client settings control listening, permissions, or network entry points; and the runtime file is the result after those sources are processed. The order and granularity of this processing vary between clients, so no particular override syntax is a YAML standard. When migrating clients, carry over the intent and actual fields, not just an extension file.

Direct edits to a subscription source file may be overwritten during the next update. Edits to the runtime file may be regenerated on reload or when switching configurations. A safer approach is to keep long-term customizations in an extension point the client explicitly supports and maintain a separate backup. If the client only supports a complete local configuration, manage updates yourself. Don’t assume a change will persist just because it took effect once; test at least one reload and one subscription update.

Merging Objects and Lists Are Different

Object fields may merge recursively by key or replace an entire section. Lists may be prepended, appended, replaced, or handled specially. For rules, an appended exception placed after MATCH is present in the text but can’t match; replacing the whole list may remove the subscription’s existing routing. For nameserver, appending an upstream may add parallel queries rather than replace the old upstream. Before using an extension, check how the client handles objects and lists separately.

# The goal is to put the exception before the existing rules,
# not to treat this snippet as override syntax for every client.
rules:
  - DOMAIN,dev.example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,Egress
  - MATCH,Egress

The example shows the desired final order. In practice, use the client’s supported mechanism for prepending rules, extensions, or scripts; don’t blindly paste this at the end of a subscription. In the runtime file, verify that there’s only one top-level rules key, the exception appears before the fallback, and the referenced group still exists. Also check which configuration the extension is bound to, so personal development rules aren’t unintentionally applied to another subscription or device.

Verify Subscription Updates and Manual Selections Separately

A successful subscription update only confirms that one update step completed; it doesn’t necessarily mean the active runtime configuration was regenerated and enabled. Some clients handle downloading, parsing, saving, and reloading separately, and a failure at any step can leave the old content in place. Check the logs for the update time, changes to the proxy collection, and the selected configuration, then confirm the core reloaded it. If an update fails, use the subscription FAQ to distinguish network, content format, and authorization issues.

When restoring a backup, account for selection state saved by the client too. Even if the file is restored exactly, a proxy group may still use the last manual selection, and DNS caches and existing connections may remain. For a repeatable test, keep the mode, group egress, request target, and app entry point fixed. Close old connections before sending another request if needed. Change one variable at a time and record the result to tell whether restoring the configuration really fixed the issue or the remote service simply came back online.

Complete a Change in Four Layers

Layer one: check syntax and types, including indentation, quotes, booleans, and duplicate keys. Layer two: check references—every group, proxy, and provider used by rules must exist, and there must be no cycles. Layer three: check runtime status: confirm the core loaded the new configuration, ports are listening, and DNS and TUN initialized without errors. Layer four: verify the actual use case by accessing a specific address from the target app and checking the matched rule and egress. Don’t skip ahead and make random edits if an earlier layer hasn’t passed.

Backups should include at least local rules, proxy group structure, and client-specific extensions—not just a proxy list. Store sensitive proxy parameters somewhere secure, and replace them with illustrative values when sharing. Before deleting old files, identify which are source files, caches, and client-generated files. Deleting a cache directory indiscriminately may prevent startup offline; deleting a source file may lose personal settings that haven’t been synced.

You should be able to answer three questions: which entry point receives the app’s request, which rule determines its egress, and which configuration layer owns that rule. If you can’t, return to a minimal base configuration and add features one at a time; that’s easier to troubleshoot than piling on more overrides. For a quick connection setup, follow the quick start guide. Look up terminology in the glossary, or investigate a specific error with the runtime log guide. Treat this reference as a lookup resource, not a checklist of features you must enable all at once.