Clash Configuration File
YAML & Field Reference

1. YAML Structure & Configuration Loading

Top-Level Fields: Distinguish Maps from Lists

A Clash configuration is typically a YAML mapping. mixed-port and mode are scalar fields, dns is a nested mapping, and proxies, proxy-groups, and rules are lists. Identify these structures before reviewing individual settings to avoid nesting errors, such as putting proxies under a group or rules under DNS.

Indentation defines hierarchy. Use two spaces consistently and avoid tabs. List items start with a hyphen followed by a space, and fields within an item must line up. An editor can make misaligned characters look aligned, so turn on whitespace display after pasting a configuration. Full-width Chinese punctuation can also break parsing: use ASCII colons after field names and commas in rules.

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

proxies: []

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

rules:
  - MATCH,Proxy

This skeleton shows how the references fit together, but it only provides a direct connection path: the final rule points to Proxy, whose only member is DIRECT. It is useful for checking the basic structure, but it does not create proxy nodes. To use it in practice, add nodes from your provider or load them through a provider. Do not mistake a structural example for a working subscription.

Strings, Booleans & Duplicate Keys

Ports are generally integers, and switches use true or false. You can quote names, passwords, and strings containing special characters, especially values with a colon followed by a space, a hash mark, or text that looks like a Boolean. Double-quoted strings interpret some escape sequences, so take care with backslashes. If you're unsure, compare against the original value from your provider rather than changing characters at random.

Comments begin with a hash outside a string. They can document why a change was made, but do not affect the core configuration. Do not declare the same top-level key twice—for example, one dns near the top and another dns at the end of the file. Parsers may report an error or keep only one copy. Put the required subfields in a single object instead of relying on a later entry to override an earlier one.

A YAML parser accepting a file only confirms that its syntax is valid; it doesn't mean the current core supports every field. A misspelled field may have no effect, and a valid proxy group may reference a node that doesn't exist. Check in three stages: can the file be parsed, does the core accept it, and does traffic take the expected path? Confusing these stages can lead you to mistake a broken reference for a network problem.

Configuration Sources & Test Order

The original subscription, your local edits, the result after overrides, and the configuration running in the core may all be different files. Before troubleshooting, confirm which Profile is active and whether the client applies merges or scripts. Seeing a change saved in the UI doesn't mean the running core has reloaded it. Use the client's reload action if needed, then check the logs.

If you run mihomo directly, use the command below to check a specific file. In a GUI client, start with its configuration checker, runtime logs, or error messages. Make sure the config path points to the file you're testing, not another file with the same name in a different directory. Test before enabling it, and don't overwrite your only working configuration—you'll need it for comparison if anything goes wrong.

mihomo -t -f ./config.yaml

Change one layer at a time: load the basic structure, add proxies, configure groups, then adjust rules and DNS. If something breaks, reverting to the last working file makes the cause easier to find than changing dozens of fields at once. For naming and switching between multiple configurations, see Profile and Local Configuration Management.

2. Ports, Modes & Common Settings

Listening Ports: Choose the Right Entry Protocol

port provides an HTTP proxy entry, socks-port provides a SOCKS entry, and mixed-port accepts both HTTP and SOCKS traffic on the same port. For typical desktop use, one clearly configured entry is usually enough. The port number isn't a performance setting; choosing a higher number won't make connections faster. Check that the port is available and that the app is pointing to the right address and port.

The snippet below listens only on the local machine, which works well with a client's system proxy feature. If the client manages ports itself, edits to subscription fields may be overridden by its UI settings. For a port conflict, first close any duplicate client instances and check background services, then choose another port. Don't have multiple programs listen on the same address and port.

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

Run Modes: Separate Traffic Capture from Outbound Selection

mode: rule selects a policy based on the rules list; global uses the global policy; direct sends traffic directly by default. The mode controls connections that have already entered the core; it doesn't route every app through the core automatically. System proxy settings, in-app proxy settings, and TUN are traffic entry methods. Switching run modes can't replace configuring an entry point.

For example, if a browser uses the proxy but a command-line tool connects directly, first check whether the tool reads the system proxy or needs proxy environment variables. If a connection appears in the client panel but uses the wrong policy, check the mode, rules, and proxy groups. Confirm that traffic reaches the core before troubleshooting outbound selection; this quickly narrows down the cause.

Sharing with devices on your LAN requires checking allow-lan, the listen address, the OS firewall, and the proxy settings on each device. Enabling the switch alone doesn't guarantee other devices can connect. If sharing is necessary, restrict access to trusted networks and configure appropriate authentication. Don't expose the proxy entry or controller interface to the public internet just to avoid troubleshooting.

Logs, Persistence & Controller

log-level is commonly set to info. For temporary troubleshooting, raise it to debug, then restore the previous level when you're done. Detailed logs may include domain names, connection targets, and paths, so remove sensitive information before sharing them. A single warning doesn't necessarily mean the client is broken; consider when it appeared, which connection it affected, and whether the issue can be reproduced consistently.

profile.store-selected saves proxy group selections, but whether they are restored as expected also depends on how the client switches configurations. If a group or proxy is renamed, the saved selection may no longer match and the group can fall back to its default. Check whether a subscription update changed the name before reinstalling the client. Keeping important group names stable makes long-term maintenance easier.

profile:
  store-selected: true

external-controller is a management API, not a proxy port for browsing websites. Most users don't need to expose it to get online. If you need to connect a dashboard, use a localhost address or a controlled network and configure authentication as required by the client. Entering the controller port as a system proxy usually results in a connection failure or protocol mismatch.

The top-level ipv6 setting and the field with the same name under DNS do different things: the former controls IPv6 use by the core, while the latter affects how DNS handles AAAA queries. Neither is an OS network adapter switch. IPv6 support can vary between your home network, proxy exit, and destination service. Save the original values and test changes one at a time instead of attributing every issue to IPv6.

3. Proxy Fields & Protocol Compatibility

Core Fields: Names Are References

Each entry under proxies describes a specific outbound proxy. Start with name, type, server, and port, then check authentication and transport settings. The name is used to reference the proxy in groups; it isn't the server's domain name. Renaming a proxy to a region won't change its exit location. Check provider details and actual connection results for information about region and routing.

Give each proxy a unique name, avoid names that duplicate a group, and don't use built-in policy names such as DIRECT or REJECT. If you copy a proxy and change only its address, forgetting to rename it can make references ambiguous or cause a configuration error. When a provider renames proxies often, groups that reference individual names can break; consider using a provider and filtering its members in the group instead.

proxies:
  - name: Example-SS
    type: ss
    server: proxy.example.com
    port: 443
    cipher: chacha20-ietf-poly1305
    password: "your-password"
    udp: true

The Shadowsocks snippet above illustrates how the fields relate; replace the address and password with the values supplied by your provider. cipher specifies the encryption method and must match the server. Don't substitute another method just because its name looks similar. A server port doesn't necessarily correspond to a familiar web service; setting it to port 443 doesn't automatically make the proxy use HTTPS or let you open it directly in a browser.

Authentication & Transport: Check Each Protocol as a Set

Authentication fields vary by protocol. Shadowsocks uses a password and cipher, Trojan uses a password and relies on the corresponding TLS settings, and VMess and VLESS commonly use a user ID. Don't copy field names across protocols. If authentication fails, check the original subscription or provider documentation for the protocol, credentials, and extra parameters rather than randomly adding fields found online.

Some protocols also specify a transport, path, Host header, and TLS settings. These must match the server configuration as a set: a WebSocket path isn't necessarily the site's home page, and the HTTP Host header doesn't have to match the connection address. A server opening in a browser doesn't confirm that proxy authentication is correct; browsing tests only some of the network requirements.

servername is generally the TLS server name for protocols that use it. It can differ from server, but only when that matches the server configuration—not just because another domain is reachable. For certificate errors, check the device clock, server name, and certificate chain. Don't use skip-cert-verify as a general fix, since it bypasses an important server identity check.

UDP, DNS Resolution & Proxy Selection

udp: true indicates that the proxy supports relevant UDP forwarding, but it doesn't guarantee that the entry point, server, and full route support it. Check separately whether the app sends UDP, the system proxy can capture it, the protocol supports it, and the server allows it. Websites working normally doesn't mean voice chat, games, or other real-time apps will work too.

When server is a domain name, the core must resolve it to an address before it can connect to the proxy. This happens before the core accesses the destination website. If DNS is configured to query through that same proxy before the connection is established, it can create a dependency loop. If all proxies fail to connect, first check whether their server names resolve before assuming an individual route is at fault.

A successful latency test means the test request completed at that time; it doesn't prove that every destination or transport works. Choose proxies based on stability, the destination service's region, traffic costs, and how you plan to use them. For a detailed comparison process, see How to Choose a Proxy Node; for limitations of test metrics, see Latency Tests vs. Real-World Performance.

When building a configuration, you don't need to add every protocol at once. Start with one proxy whose settings are complete and verified, use a manual selection group to test the connection, then add automatic testing or backup routes. If you need another client, choose an OS version on the download page. Consider Clash Plus and confirm that its current core supports the protocols you need.

4. Proxy Group Fields & Selection Logic

select: Centralize Manual Selection

proxy-groups combines proxies, other groups, and built-in policies into outbound entries that rules can reference. Keep rule targets stable and adjust proxies within groups to avoid editing the same rules repeatedly. The most common type, select, lets users choose a member. It's useful for manual switching and as a single entry point between an automatic group and direct connections.

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

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

This example depends on the Main proxy provider defined later; without that provider, pasting this snippet on its own leaves an unresolved reference. Proxy is the main entry point, where you can choose between an automatic group and a direct connection. Use descriptive group names, such as General, Work, or Media, to make troubleshooting easier than names made up of cryptic symbols.

proxies lists specific proxy or group names, while use imports a proxy provider. They refer to different things, so don't enter a provider name as if it were a regular proxy. Every group member must exist in the configuration, and references must not form a cycle. A group containing another group that points back to it doesn't create a fallback route; it creates an invalid structure.

Automatic Groups: Understand the Test Conditions

url-test selects a member based on test results. url is the test URL, interval is the test interval (usually in seconds), and tolerance reduces unnecessary switching due to small differences. Choose a stable URL that responds quickly and reflects basic reachability. Don't use a page that contains account information or requires a login.

Automatic testing isn't continuous download speed testing. Results depend on the test server's location, DNS resolution, connection reuse, and current route conditions. A proxy that reaches the test URL quickly may still perform poorly with your work services. If the selected member changes frequently, check route stability and test conditions, then adjust tolerance moderately. Shortening the interval just to get more current-looking numbers isn't a reliable fix.

fallback selects an available route based on member order, making it useful when you have a clear primary and backup. Keep in mind that a primary route may pass the test URL while failing to reach a particular service, so the check can still mark it as available. Fallback can reduce the impact of some outages, but it can't replace service-specific rules and reachability checks. Avoid group names that imply a route is guaranteed to work.

load-balance distributes connections among members according to its policy; it doesn't split a single download across multiple proxies to combine their bandwidth. Services that depend on a stable login session or exit IP may trigger extra verification if the IP changes frequently. Without a specific need, a manual or test group is easier to understand and makes a more reproducible starting configuration.

Filtering & Persistence: Avoid Empty Groups

When importing proxies from a provider, use filters to limit group membership. Filters typically use regular expressions to match proxy names, not actual locations. If a provider changes its naming, punctuation, or language, a filter can return no results. Before relying on a group, check its actual members in the client. A regular expression that looks reasonable doesn't prove the group is usable.

Keep proxy group nesting manageable. A main entry point connected to a service group, which then selects a specific proxy, is usually enough. Wrapping several automatic groups inside one another adds complexity. To troubleshoot, follow the path from the rule target to the current group selection, then through any nested groups to the final proxy. Looking only at the top-level group can hide a nested group still set to direct.

A selection that changes after a subscription refresh may be caused by a removed proxy, a renamed proxy, a rebuilt group, or the client's persistence behavior. First confirm that the original member still exists, then check profile.store-selected and whether the client reset the selection. You can maintain stable business groups in a local override, but make sure their referenced members still exist after subscription updates.

If one group behaves unexpectedly while others work, temporarily add the same proxy to a simple manual group and compare. If the proxy works there, the issue is likely with filtering, health checks, or group references. This separates proxy failures from group scheduling logic, so you don't have to rewrite every policy in the subscription to fix one group.

5. Rule Syntax & Matching Order

Top to Bottom: Put Specific Rules First

rules is an ordered list, usually evaluated from top to bottom. Once a rule matches, its policy is used. Rules aren't combined and voted on, so specific exceptions must come before broader rules. If a custom rule doesn't seem to work, first check whether a broader rule above it already matches the connection instead of immediately changing the rule type.

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

In this example, Proxy must be a defined group or proxy. The final policy field in a rule isn't a free-form note; its spelling, capitalization, and spacing must exactly match the configured name. An editor that changes punctuation or invisible spaces copied into the field can also break the reference. If you rename a group, check all rules and other group references that use it.

Domain Rules vs. IP Rules

DOMAIN matches an exact domain, making it suitable for a single endpoint. DOMAIN-SUFFIX matches the domain and its subdomains, which works for a group of domains belonging to the same service. DOMAIN-KEYWORD matches a keyword and can capture unrelated destinations. Prefer explicit rules when possible to make matches easier to understand and maintain.

IP-CIDR and IP-CIDR6 match address ranges. For connections with a domain name, the core may need to resolve it before evaluating a rule that requires the destination IP. no-resolve means the core won't resolve a domain solely for this IP rule; it doesn't disable DNS for the entire connection. If the connection already has a destination IP, it may still match the rule.

GEOIP uses an IP database to determine geographic assignment. Results depend on the database's contents and update status; they don't identify where a website operator is based or precisely describe each CDN routing decision. Before using these rules, confirm that the core can access the required data. If DNS returns addresses in different regions, traffic may take different routes because of the resolution result, not because the rule stopped working at random.

MATCH is a catch-all rule and usually belongs at the end. If it appears earlier, later rules won't get a chance to match. DIRECT means connect directly, REJECT means block, and other names usually point to a proxy or group. Don't move all service-specific exceptions below the catch-all just to shorten the configuration; those rules may be present but will never be reached.

Rule Providers & Process-Matching Limits

Long domain lists can live in a rule provider and be referenced with RULE-SET. Keep the main configuration's business logic and ordering clear, while the external list maintains the individual entries. Rule sets still run at the point where they appear in the list. Even an accurate list won't be evaluated if an earlier catch-all has already matched the connection.

Process rules depend on the platform, process detection capabilities, and traffic capture method. A desktop client may recognize a process name that a router cannot, because the router sees connections from other devices. Mobile operating systems may also restrict access to process information. When moving a configuration across platforms, check these capability limits first; process rules aren't a universal substitute for domain rules.

Domain rules require the core to obtain domain information. Direct IP connections, DNS queries that bypass the core, or some encrypted DNS paths can affect matching. Sniffing has limitations and can't recover domains from every protocol. If connections show only an IP address, check DNS and the entry path before adding IP rules. Don't blindly broaden keyword matches.

To verify a rule, find a new connection in the connection panel and check the matched rule type, match details, policy chain, and final proxy. Existing long-lived connections may not select a new outbound route after a change, so close the app's connection and retry if needed. If you're still stuck, use the symptoms in Troubleshooting to guide the next checks. Keeping records of one successful and one failed connection is more useful than simply saying a rule doesn't work.

6. Subscriptions, Proxy Providers & Rule Providers

A Full Subscription Is Not a Proxy List

A remote Profile in a client is usually a complete configuration that can include ports, DNS, proxies, groups, and rules. proxy-providers imports a collection of proxies into a main configuration. Both can be updated from a URL, but they serve different purposes. Pasting a full configuration URL where a proxy provider format is expected may download content that the core can't parse.

Check the format supplied by your provider before choosing an import method. For first-time setup, use the client's subscription import feature to create a complete Profile. Split out proxies into a provider only when you need to maintain the main configuration yourself. For the steps in the client, see How to Import a Subscription; for format conversion limits, see Subscription Conversion.

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

The example URL doesn't provide working proxies. A typical HTTP proxy provider returns YAML with a top-level proxies list; a webpage, login page, or error message won't work. path sets the local cache location, usually relative to the core's working directory, though client path restrictions may apply. Give each provider its own cache file to prevent them from overwriting one another.

Update Interval vs. Health Checks

The provider's interval controls how often the proxy list is fetched. The same field in a health check controls how often existing proxies are tested. These settings do different things: one refreshes proxy information, the other checks reachability. Increasing the health-check frequency won't make subscription updates arrive sooner; it may simply increase requests and drain mobile device batteries.

When an update fails, check the retrieval path step by step: is the URL expired, does it require renewed authorization, can the current network reach it, what does the server return, and does the content have the right YAML structure? If the URL opens in a browser, make sure it isn't showing an account page. Don't post a full subscription URL publicly; its query parameters may contain usable access credentials.

If the local cache is still valid, a failed remote update may not immediately affect existing proxies. However, cache behavior and restart handling vary by client, so don't rely on this as a guarantee. Keep the working configuration while troubleshooting; don't delete both the cache and the old Profile at once. For more error categories, see Subscription Update Failures and Auto-Refresh Intervals.

Rule Providers: Match the Format to the Behavior

rule-providers stores match conditions, not proxy nodes. behavior specifies whether the contents are domains, IP addresses, or classic rules; format describes the file format. Both must match the actual file. A .yaml extension alone doesn't guarantee the contents use the same behavior. Set the outbound policy where you reference the provider with RULE-SET, so the same list can be used with different routes.

rule-providers:
  Work:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/work.yaml

rules:
  - RULE-SET,Work,Proxy
  - MATCH,DIRECT

The rules above illustrate ordering; merge them into the existing list instead of declaring a second list at the end of the file. If the list uses domain behavior, its file can follow the structure below. Before saving, check that the client can read the relative path. On mobile clients that don't expose the working directory, the built-in local rules or override feature may be a better fit.

payload:
  - "+.github.com"
  - "example.com"

Splitting out providers also splits maintenance responsibilities: the main configuration manages groups and ordering, proxy sources provide route details, and rule sources define match scope. Make local changes at the layer responsible for that content. Don't put custom domains only in a cache file that a remote refresh will replace, or they may disappear during the next update.

For configurations with multiple sources, keep a note of each provider's purpose, format, and the groups that reference it. After adding a source, check that it loaded, confirm its members appear in the group, then test a connection. This separates download failures, format errors, empty filters, and unusable proxies instead of blaming every issue on the subscription URL.

7. DNS, Fake-IP & TUN

DNS: Map the Resolution Dependencies

dns controls the core's own DNS resolution, but only requests that enter this resolution path are affected. A browser may use built-in encrypted DNS, an app may specify its own resolver, or the OS may serve a cached result. Adding an upstream address to the config doesn't mean every program will use it immediately. Before troubleshooting, find out where the query originates and which resolver ultimately answers it.

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

This snippet shows common field relationships; it isn't a one-size-fits-all setup. listen creates a DNS listening endpoint, but the system won't automatically send DNS queries to it. Listening on a high-numbered local port also doesn't make the router provide DNS to other devices. Check the client's traffic capture capabilities, system settings, and local permissions separately.

default-nameserver is commonly used to resolve the hostnames of DNS upstreams, nameserver provides the general query path, and proxy-server-nameserver can specify a resolver for proxy server hostnames. Understanding these roles matters more than stacking lots of public DNS servers. Queries needed before a proxy connects must have an independent resolution path, or they may depend on the very connection that hasn't been established yet.

Fake-IP: A Mapped Address Isn't the Final Destination

fake-ip assigns a mapped address to a domain. The core uses that mapping to recover the destination domain and handle the connection. An address from the configured mapping range isn't necessarily evidence of a DNS error. The connection must also reach a core that can recognize the mapping. If the query goes through the core but the connection bypasses it, the app may try to reach a mapped address that isn't routable on a regular network.

Use fake-ip-filter to exclude specific domains from this mapping. LAN device discovery and some apps that need real addresses may require exceptions, but avoid starting with an overly broad filter. Broad exclusions provide less domain information for matching. Identify the specific domain causing trouble, add the smallest necessary exception, then test the affected app again.

After changing DNS modes, old cache entries and existing connections can make it look as if nothing changed. Restart the target app, then clear its cache using the method provided by the OS or client. Don't change upstreams, mapping mode, sniffing, and rules all at once, or it'll be hard to tell which change helped or broke the connection. For local network names, also check the router and local DNS setup.

TUN: Traffic Capture Still Requires Routes & Permissions

TUN uses a virtual network interface to capture traffic, including from some apps that ignore the system proxy. It doesn't replace rules or proxies, and it won't work automatically in every environment. Desktop systems may require a service or elevated permissions; mobile systems use network extension APIs; routers involve gateway and forwarding routes. Follow the current client UI for platform-specific setup.

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

This snippet covers common desktop fields; confirm platform support before applying it. auto-route configures routes needed for traffic capture, and auto-detect-interface identifies the outbound interface. Multiple network adapters, virtual machines, other VPNs, and container networks can interfere with automatic detection. If the network goes down, disable TUN first to restore a baseline, then check the system routes and interface selection.

dns-hijack handles matching ordinary DNS traffic; it doesn't automatically detect and rewrite every encrypted DNS query over HTTPS. If a browser uses its own encrypted DNS path, check whether that behavior fits your routing requirements. If TUN and the system proxy are both enabled, understand how the client prevents its own traffic from looping back through the proxy. Don't layer on extra capture rules without knowing where they come from.

A useful troubleshooting order is to test the direct connection, then the regular proxy entry, then enable TUN, and finally check DNS and domain rules. If the problem occurs only with TUN, focus on permissions, routes, interfaces, and conflicts with other network software. If only one domain fails, check its resolution and rules. This staged approach is more likely to produce a clear answer than rewriting the entire DNS section at the start.

8. Overrides, Merging & Reversible Changes

Separate the Original Subscription from the Running Configuration

A remote subscription refresh usually regenerates or replaces configuration content. Rules added directly to the subscription may work only until the next update. Put long-term changes to ports, traffic routing, or DNS in an override, merge, or script feature supported by the client. Check which Profiles the feature affects before choosing where to make the change, so a global edit doesn't unexpectedly affect another configuration.

Clients don't all define merging the same way. Mappings may merge recursively; lists may be replaced as a whole or support prepending and appending; scripts may also modify the result after merging. Don't assume that features labeled “override” behave identically. The most reliable approach is to test a small change and inspect the final configuration, rather than assuming it took effect because the input appears in a text box.

rules:
  - DOMAIN-SUFFIX,example.com,Proxy
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

For example, to route work domains through a specific group, the goal is to place those rules before broader rules—not just append them to the end of the file. If the override only supports appending and the subscription already has MATCH, the new rules may never match. Use a prepend option or an explicit rule insertion feature, then verify the rules' position in the final configuration.

Cross-Field References: Recheck After Merging

When adding a proxy group, check that every referenced proxy, provider, and other group exists. Keeping a local group name doesn't guarantee its members will remain available; a remote subscription may rename proxies or providers. For long-term business rules, point to a stable local group, then have that group reference a clearly defined source. This reduces direct coupling between rules and remote proxy names.

When overriding DNS, check whether you're replacing a single subfield or rebuilding the entire object. If you only meant to change upstreams but also lose the listen address, mapping mode, or filter list, connection behavior may change in other ways. Record the existing fields before editing and compare the final result afterward. Don't paste a full DNS block from another configuration if you intend to change just one setting.

Check path fields again as well. The relative directories used by the original subscription, the client's override files, and the core's working directory may all differ. When moving a configuration to another device, file providers and cache paths may stop working. If a file can't be found, check the working directory and the locations the client is allowed to access. Don't mask a path problem by loosening directory permissions at random.

Verify the Full Cycle: Save, Load, Connect, Revert

Keep a short note for every change: which field you edited, which connection it should affect, what target you used to test it, and which file to restore if it fails. The note doesn't need to be elaborate; it just needs to make sense a week later. Clearly label temporary troubleshooting switches and restore them when you're done, so debug logs, DNS exceptions, or temporary direct routes don't become permanent by accident.

Use the same four-step process each time: back up the current working configuration, run syntax and core checks, apply it and inspect the load logs, then test a new connection and check which rule it matches. Successful loading is only one step; verify the actual service too. Conversely, a website opening temporarily doesn't prove the new rule worked—it may still be using an existing long-lived connection.

Keep other conditions constant while testing. Use the same destination, entry point, and proxy, and compare just one variable before and after the change. If you refresh the subscription, switch proxies, change modes, and enable TUN all at once, you won't know which change caused the result. A stable configuration makes each change explainable; adding more fields doesn't.

Plan for rollback as part of normal maintenance. Keep the latest working Profile, its override content, and any necessary client settings. After restoring them, reload the configuration and make sure the system proxy or TUN is back to its previous state. Store backups containing proxy and subscription details securely. When asking for help, share only the relevant, redacted snippets and error messages.

The guiding principle is to give every field a clear owner: subscriptions manage proxy sources, local overrides manage personal requirements, groups organize outbound routes, rules select them, and DNS and traffic entry ensure connections follow the right path. For first-time setup, start with the quick-start guide. Expand one section at a time as needed; there's no need to enable everything at once.