The Complete Clash Guide

Understand Clash Core Concepts and Traffic Flow First

The Client, Core, and Configuration File Are Different Layers

In everyday use, “Clash” often refers to three different things. First are graphical clients such as Clash Plus, Clash Verge Rev, FlClash, and Clash Nyanpasu. They handle configuration management, tray menus, system proxy switches, service installation, and log display. Second is the network core, with mihomo being common among current clients. The core listens on ports, evaluates rules, selects policies, establishes proxy connections, and handles DNS. Third is the YAML configuration file, which describes ports, nodes, proxy groups, rules, and DNS behavior.

These three layers must be evaluated separately. An interface opening only proves that the client process started. A running core means the local proxy port is listening. For a browser to reach a target website, system traffic must also enter that port, the rules must select a valid policy, the node must connect successfully, and DNS must resolve correctly. Many “Clash is running but there is no internet” problems occur in a layer after the core, not in the installer itself.

A configuration file is not the same as a subscription. A subscription URL is usually generated by a service provider; after the client requests it, the returned configuration is saved locally. A single-node link describes one server and does not inherently include complete proxy groups or routing rules. A local YAML file is already-formed configuration that can be imported directly, but whether it updates automatically depends on the client. For help identifying formats, see Subscription URLs, YAML Configurations, and Common Import Formats.

The Complete Path from an App Request to the Final Egress

Take a browser connecting to an HTTPS website. The domain must first resolve to an address. The browser then establishes a TCP or QUIC connection, and the system sends it to Clash through proxy settings or a virtual network interface. The core reads information such as the destination domain, address, port, and process, then evaluates rules from top to bottom. Once a rule matches, the request is handed to the corresponding proxy group. That group may select a node directly or reference another group, ultimately producing an action such as proxy, direct, or reject.

Troubleshoot in that same order: determine whether the app follows the system proxy or traffic is being handled by TUN; verify that a local listening port exists; check DNS resolution; confirm that the expected rule matched; verify that the proxy group selected a usable egress; and check whether the remote node can connect. Repeatedly changing nodes while skipping intermediate layers may hide the problem temporarily, but it will not fix an incorrect system proxy, DNS setup, or rule configuration.

Choose a Client and Install It on Each Platform

Choose by Platform and Traffic-Capture Requirements

A graphical client does not change the subscription itself; its main purpose is to simplify configuration management and system traffic capture. In our download list, Clash Plus is the recommended starting point for Windows, macOS, Android, and iOS, making it suitable for users who want a similar workflow across common platforms. Windows and macOS also support Clash Verge Rev and FlClash. Windows users can use Clash Nyanpasu, with an archived entry for the discontinued Clash for Windows. macOS also has the discontinued ClashX Meta. Android users can choose Clash Meta for Android, FlClash, or Surfboard. On Linux desktops, Clash Verge Rev and FlClash are available.

Do not choose based on appearance alone. Check whether your system architecture has a matching package, whether the client supports the required core, whether it can install a system service, and whether TUN capture, subscription updates, and logs are clearly managed. If you only need a browser and a few apps that follow system proxy settings, a regular system proxy is enough. If you need to capture command-line tools, game launchers, virtual-machine helpers, or apps that ignore system proxy settings, prioritize a client with reliable TUN support.

Server and router users often run the mihomo core directly, but this requires managing configuration files, process permissions, startup services, and log rotation yourself. Desktop users generally do not need to skip a graphical client merely to be “lighter,” because the ongoing maintenance cost is usually greater than the saved interface resources. See the Clash Client Downloads page for the complete package list, platform links, and maintenance status.

Installation Priorities for Windows, macOS, and Linux

Before installing on Windows, check whether an older proxy program is still running. If multiple programs listen on the same port, the new core may fail to start. If several programs take turns changing the system proxy, the interface may show it as enabled while the system actually points to another port. Exit the old client before installing the new one, and allow the app through the system security prompt on first launch. Using a system service or TUN usually also requires installing the service in the client and confirming system permissions. Successful service installation and enabled TUN are separate states and should not be confused.

After installing on macOS, complete any prompts about the app source or network extension permissions in System Settings. Apple Silicon and Intel require different packages, so choose based on the chip shown in About This Mac. The system proxy handles only connections that follow macOS proxy settings. Enhanced traffic capture may require adding a VPN configuration or authorizing a network extension. If authorization was denied, return to the Privacy & Security, Network, or VPN-related settings and confirm it again instead of repeatedly clicking the launch button.

Linux differences mainly come from distribution package formats, desktop environments, and permission models. Debian- and Ubuntu-based systems usually use deb packages; other distributions can use a compatible format provided by the client. If the interface starts but cannot capture traffic, check whether the desktop proxy was actually written, whether the current session loaded those settings, and whether the network permissions required by TUN are available. On servers, run the core with a dedicated service account that can access the configuration and log directories instead of keeping an interactive terminal process alive indefinitely.

Traffic Capture on Android and iOS

Android clients use VpnService to create a local VPN interface and pass device traffic to the core. The first connection displays a system VPN authorization dialog; traffic cannot be captured until it is approved. Disconnects after locking the screen or failures after switching networks are commonly caused by power-saving policies, background restrictions, or vendor cleanup mechanisms. Allow the client to run in the background and add it to the battery-optimization exceptions in system settings. The exact path varies by manufacturer; see Android VpnService, Background Operation, and Battery Settings.

iOS works through the system VPN configuration. After installing Clash Plus, the first activation requires confirmation to add a VPN configuration. The VPN icon in the status bar only indicates that the configuration is connected; actual access still depends on the subscription, policy, and node. When a mobile device switches from Wi-Fi to cellular data, existing connections are rebuilt and a brief interruption is normal. If service does not recover, stop the connection, wait until the system VPN state disappears completely, and start it again instead of repeatedly importing the same subscription.

Import Subscriptions and Understand the Basic Configuration Structure

Distinguish Subscription URLs, Node Links, and YAML Files

A subscription URL is usually an HTTPS URL that returns a Clash-compatible configuration or an encoded list of nodes. Its key benefit is updateability: after the provider changes nodes, policies, or rules, the client can fetch the latest content again. A local YAML file is a static snapshot, useful for backup, customization, or offline management, but it will not sync automatically when the original subscription changes. A single-node link contains only protocol, server, port, and authentication details; after import, you may still need to create proxy groups and rules manually.

Before importing, make sure the URL is complete, was not truncated by a chat app, and contains no leading or trailing spaces. Paste it into the client’s subscription or configuration import screen, not a browser search box. After a successful import, check the configuration name, update time, and proxy groups, then set it as the active configuration. A successful download without switching to the active configuration may leave the core using the previous file.

Import failures generally fall into three layers. Network errors include connection timeouts, DNS resolution failures, and certificate errors. Service errors include expired authorization, denied access, or an HTML response. Configuration errors include invalid YAML indentation, incorrect field types, and references to nonexistent proxy groups. If the client log shows an HTTP status problem, check the subscription itself first. If it identifies a parsing failure on a particular line, inspect the configuration instead of changing proxy nodes.

The Most Important Fields to Recognize in a Basic Configuration

A working configuration usually contains local listening parameters, proxy nodes, proxy groups, rules, and DNS settings. A graphical client may store some global fields in its own settings database, so an exported configuration may not include every interface toggle. The example below shows the basic structure without real server information; the proxy section is included only to illustrate field relationships.

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

proxies:
  - name: example-node
    type: socks5
    server: 192.0.2.10
    port: 1080
    username: demo-user
    password: "your-password"

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - example-node
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,PROXY
  - GEOIP,LAN,DIRECT
  - MATCH,PROXY

mixed-port allows the same local port to accept both HTTP and SOCKS connections, which is convenient when entering proxy settings manually. When the port listens only on the local machine, the usual address is 127.0.0.1. allow-lan controls whether other devices on the LAN can connect to this device’s proxy port; for local-only use, leaving it disabled is clearer. mode determines the overall matching mode, usually rule. log-level controls log detail. Keep it at info for normal use, raise it briefly for troubleshooting, and then restore it to avoid accumulating excessive logs.

proxies defines individual egresses, proxy-groups organizes multiple egresses into manually selectable or automatically tested policies, and rules sends traffic to those policies. Policy names referenced by rules must exactly match the group names, including capitalization and symbols. If you rename PROXY to something else, update every rule that references it or configuration validation will fail.

How Updates, Overwrites, and Local Changes Interact

A subscription update usually downloads remote content again and overwrites the cached copy, so direct edits to subscription-generated YAML may disappear on the next update. For customizations that must persist, prefer the client’s overwrite, merge, script-processing, or global-extension features. If the client offers none of these, copy the configuration and maintain it independently, while synchronizing node changes yourself.

Do not delete the original configuration immediately after an update fails. Keep the last working cache, verify that the subscription URL is still valid, and then try a manual refresh. If the updated configuration suddenly stops working, switch back to the old cache and compare changes in proxy groups, rules, and DNS. A well-designed client distinguishes the remote subscription, local cache, and active configuration; understanding these three states prevents deleting the only usable configuration.

Master System Proxy, Runtime Modes, and Connection Verification

The Difference Between System Proxy and Clash Runtime Status

After the client starts the core, local HTTP, SOCKS, or mixed proxy ports become available, but the operating system does not automatically send all traffic through them. The system proxy switch writes the local proxy address into Windows, macOS, or desktop network settings. Browsers and other programs that follow system proxy settings then connect to that port; programs that ignore them continue to connect directly. Therefore, “the core is running” and “the system proxy is enabled” are independent conditions.

When configuring an app manually, enter 127.0.0.1 as the server address and use the configured mixed-port, HTTP port, or SOCKS port. Do not enter the remote node port in a browser; the remote protocol may not be an HTTP proxy that browsers support. If the client changes its local port, the system proxy and any manual app settings must match.

Some command-line tools do not automatically read desktop system proxy settings and instead use environment variables. For a temporary test, set proxy variables in the current terminal. They usually disappear when the terminal closes, making this useful for checking whether a program can connect through the local port.

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890

curl -I https://example.com

In Windows PowerShell, set the relevant environment variables for the current session and clear them after closing the app. Before writing proxy variables permanently into the system environment, make sure the port will not change when the client switches configurations; otherwise tools that rely on those variables will keep trying to reach a nonexistent local port whenever the client is off.

What Rule, Global, and Direct Modes Are For

Rule mode evaluates configured rules from top to bottom and is the main mode for everyday use. It can send LAN traffic, common local services, or specified domains directly, pass destinations that need a proxy to a proxy group, and reject unwanted targets. Its behavior depends on rule quality and order. If one website uses the wrong egress, inspect the matching rule before switching the entire runtime mode.

Global mode generally sends all traffic entering the core to a selected proxy group and is useful for short comparison tests. If rule mode fails while global mode works, the node and basic path are probably fine; the issue is more likely in the rules, proxy-group references, or DNS mapping. Global mode does not automatically capture every system connection. Traffic that never enters a proxy port or TUN is still outside its reach.

Direct mode lets traffic entering the core access its destination without a proxy and is useful for determining whether the proxy egress is responsible for a failure. If direct mode also fails, check DNS, the system network, the target service, or the local firewall. Restore rule mode after troubleshooting so a temporary test state is not mistaken for a permanent configuration.

Close the Loop with Connection Records and Logs

A webpage loading successfully is not enough to verify correct routing. The client’s connection page can usually show the destination domain, address, rule chain, and final policy. After accessing a test target, check whether it appears in the connection list. No record suggests that traffic may not have entered the core. A record using the wrong policy points to a rule or proxy-group selection problem. A correct policy with a failed connection calls for checking the node, protocol handshake, and DNS logs.

Read logs around the first clear error rather than looking only at the last line. Port conflicts often occur while the core is starting, configuration reference errors while it is loading, and node timeouts while a connection is being established. A failure in the log may come from a background process rather than the browser under test, so clear the log or note the time, then perform one isolated test action.

Build Maintainable Rules, Proxy Groups, and DNS Configuration

Rules Match from Top to Bottom; Order Is Priority

The basic structure of a Clash rule is “type, match, target policy.” For example, DOMAIN-SUFFIX,example.com,PROXY sends a target whose domain ends in example.com to PROXY. IP-CIDR,192.168.0.0/16,DIRECT,no-resolve sends the specified address range directly without actively triggering domain resolution for that match. MATCH,PROXY catches all connections not matched earlier and is normally placed at the end of the rule list.

Because the core stops searching after the first matching rule, more specific exceptions must come before broader rules. If one subdomain should use a proxy while the rest of the parent domain connects directly, place the subdomain rule first and the domain-suffix rule second. Putting MATCH in the middle makes every following rule unreachable. When adjusting a large rule set, first determine whether the target belongs to a domain, address, or process rule, then check whether an earlier broad rule captures it.

rules:
  - DOMAIN,api.example.com,PROXY
  - DOMAIN-SUFFIX,example.com,DIRECT
  - DOMAIN-KEYWORD,media,MEDIA
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - GEOIP,LAN,DIRECT
  - MATCH,FINAL

DOMAIN matches a complete domain and is suitable for precise exceptions. DOMAIN-SUFFIX covers a parent domain and its subdomains and is commonly used. DOMAIN-KEYWORD has a broad scope and can catch similarly named domains, so use it carefully. IP-CIDR and IP-CIDR6 match destination addresses directly and suit LANs and defined network ranges. Process rules depend on the operating system and traffic-capture method; under system proxy mode, reliable process information may not always be available, so confirm it in connection records first.

A Proxy Group Handles Egress Decisions, Not Just a Node List

A proxy group is the decision layer between rules and individual nodes. A select group is chosen manually, making results stable and troubleshooting easier. url-test measures candidate nodes against a specified test URL at a defined interval and selects a qualifying result. fallback generally switches in availability order. load-balance distributes connections among candidates according to its strategy. Advanced parameters may be presented differently by different cores and clients, so follow the configuration validation result.

proxy-groups:
  - name: FINAL
    type: select
    proxies:
      - AUTO
      - MANUAL
      - DIRECT

  - name: MANUAL
    type: select
    use:
      - main-provider

  - name: AUTO
    type: url-test
    use:
      - main-provider
    url: https://www.gstatic.com/generate_204
    interval: 600
    tolerance: 80

Automatic testing reflects only the client’s connection to the test target, not the experience on every website. Network paths between the test URL, node egress, and target service can differ, while video, downloads, and web browsing have different requirements for bandwidth, jitter, and connection reuse. Use an automatic group as a baseline and keep a manual group for specific destinations or failover. Groups can reference one another, but avoid circular references.

When a subscription uses a provider to manage nodes, use references the provider name, not an individual node. When the provider adds nodes, updating it makes them available to related proxy groups. If a group lists fixed node names, new nodes will not appear automatically. Before editing, check whether the client offers a visual overwrite feature instead of modifying the remote subscription cache directly.

DNS Determines Which Destination Information the Core Can See

DNS problems often appear as long page loads, specific domains failing, rules matching an address instead of a domain, or a detected resolution path that differs from expectations. The Clash DNS module can handle resolution requests, send different domains to selected upstreams, and preserve domain information for rule matching. Common enhanced modes include fake-ip and redir-host. fake-ip first returns a reserved address, then restores the real domain during connection handling, usually preserving more complete domain matching. However, some LAN devices, special apps, and connectivity checks may need to be added to the filter list.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "+.stun.*.*"

The upstreams in examples are for syntax only. In practice, consider reachability from your network, resolution results, and privacy requirements. If the DNS listener is used only by the core or local machine, bind it to a local address. With TUN enabled, DNS hijacking commonly redirects system requests on port 53 into Clash DNS. If another DNS filter, encrypted DNS client, or security product also takes control, contention or loops can result.

When checking for DNS problems, first distinguish “the domain has no resolution result” from “an address was returned but the connection failed.” For the former, inspect DNS logs, upstream reachability, and the system cache. For the latter, inspect the matching rule, destination address, and node connection. After changing DNS, restart the core, clear caches as appropriate, and test with a domain you have not visited before. If you are concerned about the resolution path, review the relevant troubleshooting items in the FAQ and read the Clash DNS and Connection Problems answers.

Configure TUN Capture and Handle Permission and Routing Conflicts

What TUN Covers Beyond the System Proxy

System proxy capture depends on an app actively reading the operating system’s proxy settings. Browsers and most desktop apps support this, but command-line tools, some games, virtual-machine components, UDP apps, and programs with their own network stack may ignore it completely. TUN creates a virtual network interface and uses system routes to send connections into Clash, providing broader coverage for UDP and apps that are not proxy-aware.

TUN is not inherently faster than a system proxy. It adds virtual-interface, routing, DNS-hijacking, and protocol-conversion steps. Its advantage is broader capture, not a shorter network path. If you only need browser proxying, a system proxy is simpler. Enable TUN when apps bypass the proxy, UDP is required, or you want unified system traffic management. During troubleshooting, get the regular proxy working first, then add TUN so node issues can be separated from routing issues.

Understand Common TUN Parameters

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

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

stack specifies the network-stack implementation used by TUN. Common values include system, gvisor, and mixed, though available options depend on the core. system generally uses the operating system’s network capabilities, with compatibility and performance depending on the platform. gvisor handles more networking logic in user space and may provide clearer isolation in some environments. mixed combines approaches by protocol. Unless there is a clear problem, keep the client’s default choice instead of inferring performance from the name.

auto-route lets the core add the required routes automatically. auto-detect-interface attempts to identify the active network interface and is useful when switching between Wi-Fi and Ethernet. strict-route strengthens routing constraints to reduce bypasses, but may require additional tuning with virtual machines, containers, corporate VPNs, or unusual LAN routes. dns-hijack sends specified DNS requests into Clash DNS so apps cannot bypass routing through the system’s port 53 service.

Permission and Conflict Sources by Platform

On Windows, enabling TUN often depends on administrator permissions, a system service, or driver components. If the client reports that the service is not installed, install it in Settings and restart the core. If the virtual adapter cannot be created, check whether another VPN, network accelerator, or security product is managing routes or filter drivers. Do not enable two full-device VPN capture programs at once; they may repeatedly rewrite the default route and cause periodic disconnections.

macOS generally uses a system network extension or VPN configuration for traffic capture. Complete system authorization the first time you enable it. If leftover configuration prevents a new connection, disable the old VPN entry in Network settings and let the client create it again. Android and iOS use system VPN interfaces for capture; normally only one primary VPN configuration can be active at a time, so disconnect the current client before switching.

When running the core directly on Linux, you need permission to create a TUN device and modify routes. With systemd, grant the required network capabilities according to the distribution’s security model rather than relying on an administrator terminal that stays open. Containers also need explicit access to the TUN device and network-management permissions. If the host already has firewall rules, verify that routes and forwarding rules written by the core are not overwritten afterward.

The Boundary Between LANs, Virtual Machines, and Corporate VPNs

If printers, router administration pages, or NAS devices become unreachable after enabling TUN, LAN routing may have been captured. First confirm that private address ranges remain direct, including common IPv4 LAN ranges and IPv6 link-local addresses. Then check whether strict routing blocks a particular interface. A corporate VPN may send internal subnets through a dedicated interface; if Clash overrides that route, internal domains or office systems become unreachable. Identify which subnets must remain with the corporate VPN instead of simply disabling all routing.

Virtual machines and containers may access the network through separate bridges. Whether host TUN captures their traffic depends on routing, forwarding, and network mode; the host browser result is not enough. When conflicts occur, record route-table changes before and after enabling TUN, temporarily disable automatic routing for comparison, and then decide whether to exclude subnets or adjust interface priority.

Build a Routine for Maintenance, Migration, and Troubleshooting

Routine Updates Do Not Mean Updating Everything at Once

A Clash environment usually has four updateable components: the client application, proxy core, subscription configuration, and rule data. A client update may change the interface and system integration. A core update may affect protocols, rule syntax, or TUN behavior. A subscription update mainly changes nodes and provider configuration. A rule-set update changes routing results. Updating all of them together makes the source of a new problem difficult to identify.

A safer approach is to keep the last working configuration, update the subscription and verify it, then update the client or core. Before updating an important device, record the active configuration name, proxy mode, selected policy, listening port, DNS mode, and TUN status. If the client supports exporting settings, keep a backup, but remember that it may contain subscription URLs or authentication details. Store it securely rather than uploading it to a public repository or issue screenshot.

Set the subscription refresh interval according to how often it actually changes. Refreshing too frequently will not improve node quality and may create repeated failures during temporary network problems. If a proxy group is empty after an update, check whether the provider loaded successfully, whether node filters are too strict, and whether the subscription response format changed. Do not delete the old configuration and reimport it without a backup; the old cache is a valuable comparison point.

Troubleshoot Complete Loss of Internet Access by Layer

First check the basic system network: with system proxy and TUN disabled, does direct access work? If not, fix Wi-Fi, Ethernet, the gateway, or system DNS first. Second, start the Clash core without capturing system traffic and check for configuration parsing errors and port conflicts. Third, enable the system proxy, visit a test site in a browser, and watch the connection records. If there is no record, check the system proxy address. Once a record appears, inspect the matched policy and node error.

If every node times out, determine whether the subscription expired, the nodes are broadly unreachable, or the local network is blocking them. Switching to a direct policy in the same configuration can help test the local network. Trying nodes in different regions or using different protocols can help isolate a single-egress problem. If only one node fails, do not change the entire DNS and rule configuration. If all nodes immediately return authentication errors, check the subscription status and service authorization.

Handle HTTPS certificate errors separately from ordinary connection failures. Check the system date, time zone, and certificate chain first, then determine whether security software or an intermediary proxy is inspecting HTTPS. Ordinary Clash forwarding does not require installing a site certificate for standard HTTPS websites. For a detailed sequence, see Handling HTTPS Certificate Errors Behind a Proxy.

Troubleshoot Individual Websites or Apps by Symptom

When only one website fails, open the connection records first and confirm the domain, matched rule, and final policy. If the wrong rule matched, add or adjust a more specific domain rule. If the policy is correct but the connection fails, try another node in the same group. If the record shows an address but no domain, check DNS capture and fake-ip behavior. QUIC targets may also depend on UDP support; temporarily disabling browser QUIC can provide a comparison, but do not treat that test setting as a permanent conclusion.

If the browser works but command-line tools or other apps do not, the app probably does not follow the system proxy. Check whether it supports a manual HTTP or SOCKS proxy, then test with environment variables. For long-term unified capture, consider TUN. If only mobile apps disconnect after the screen locks, check background operation and battery restrictions. If only LAN resources are unreachable, check direct access for private ranges, TUN strict routing, and DNS handling of local domains.

If the system still cannot connect after disabling the proxy, the client may have exited abnormally while leaving system proxy settings behind. Open system network settings, verify the proxy address and switch, and disable any invalid manual proxy. If TUN was used, confirm that the virtual VPN is disconnected and the default route has been restored. Restarting the client and using its normal disable controls can restore system settings more reliably than terminating the process directly.

Collect Useful Logs Instead of a Full-Page Screenshot

Before reporting a problem, record the operating system, client name, current traffic-capture method, time the failure began, and the minimum reproduction steps. Keep only a short section of logs around the error, and redact subscription URLs, server addresses, usernames, and authentication fields. Screenshots should show the relevant status and error area, not the entire unrelated desktop. “Works with TUN off but fails with TUN on” or “global works but rule mode fails” is far more useful than simply saying “it doesn’t work.”

Find more short answers on the FAQ page, organized into core concepts, installation and configuration, usage tips, and troubleshooting. If the client’s proxy, configuration, and log pages are unfamiliar, read Clash Client Interface: A Quick Tour to locate the relevant status before following the troubleshooting path in this chapter.

Move from Stable Operation to Advanced Configuration and Long-Term Maintenance

Start with a Modular Configuration Mindset

The goal of advanced configuration is not to accumulate more rules, but to separate node sources, policy decisions, rule sources, DNS, and system capture into modules that can be tested independently. Nodes can be managed by a proxy provider, rules by a rule provider, while fixed proxy groups and global settings remain in the main configuration. Updating nodes then will not overwrite custom policies, and updating rules will not require copying an entire configuration again.

Before modularizing, give each proxy group a clear responsibility, such as “manual selection,” “automatic selection,” “media services,” “development services,” or “final egress.” Names should be stable and easy to identify in logs; avoid similar names distinguished only by symbols. Rules should reference responsibility-based groups rather than short-lived node names. When nodes change, update only the group members while leaving the rule layer intact.

Set reasonable update intervals for remote providers and keep a local cache. If a rule source is temporarily unreachable, the core can still start from the cached copy. If every critical component depends on a live download, a network failure at the wrong moment may prevent startup. External resource formats and behavior must match; domain collections, IP-range collections, and classical rule formats cannot be mixed arbitrarily.

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

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,FINAL

Example addresses are for demonstrating structure only. Before using remote rules, confirm their source, update method, and supported format. Bigger rule sets are not automatically better: overlapping entries increase the cost of understanding and troubleshooting, while incorrect categorization can proxy traffic that should be direct. Maintain a small set of exceptions relevant to your use case first, then choose general-purpose rule sources with clear boundaries.

Understand the Appropriate Scope of mihomo Extensions

mihomo extends the original Clash configuration model with more protocols, rule types, DNS capabilities, provider options, and TUN behavior. When migrating an old configuration, validate the basic fields and proxy groups first, then introduce new features gradually instead of combining fragments from multiple sources at once. Built-in core builds, default parameters, and overwrite mechanisms can differ between clients. A snippet that works in one client may not load in exactly the same way in another.

For a systematic look at compatibility, extended rules, and migration priorities, read mihomo Core Features and Differences from Original Clash. When learning, use the runtime configuration actually generated by the client as the reference. Settings saved by the interface may be merged into the subscription configuration at startup; the content ultimately passed to the core determines real behavior.

Create Verification and Rollback for Configuration Changes

Long-term maintenance should retain three files: a verified baseline that starts successfully, the configuration currently in use, and a test configuration under modification. After making changes, run the client’s configuration check before starting it. Replace the active configuration only after confirming that the core starts, the system proxy works, rules match correctly, DNS works, and TUN behaves as expected. Local version control can record text configuration differences, but authentication details and subscription URLs should never enter a public repository.

Record the purpose of every change, such as “send development domains through a selected policy,” “exclude the home LAN,” or “enable TUN for apps that ignore the system proxy.” If you cannot explain the purpose in one sentence, too many variables may have been changed together. When a regression appears, restore the previous state from your notes and split the change into smaller steps. Maintainability comes from stable names, clear responsibilities, and reversible steps, not from configuration length.

Recommended Advanced Learning Order

First, become comfortable with rule mode, manual proxy groups, and connection records, and learn to explain why a request used a particular egress. Next, study DOMAIN, IP-CIDR, RULE-SET, and providers to build a small amount of custom routing. Then understand the DNS request path, fake-ip, and domain sniffing so you can distinguish resolution problems from connection problems. After that, study TUN routing, LAN exclusions, IPv6, and coexistence with multiple VPNs. Only then explore automatic testing, load balancing, script overwrites, and complex rule sets.

After completing this path, you will not need to reinstall the client repeatedly when something goes wrong. You can locate the issue in order across app capture, core listening, DNS, rules, policy, and nodes. When switching clients, you can also distinguish subscription data from local settings and platform-specific behavior. If your immediate goal is a first connection, return to the Quick Start Guide. If you are choosing a different client, see the Clash Client Selection Guide and All-Platform Download Hub.