Clash User Guide: From Core Concepts to Reliable Traffic Routing

Understanding Clash: Core, Client, and Proxy Path

Before installing anything, separate several names that are often confused. Clash can refer to a proxy configuration format as well as the client ecosystem built around it. The client provides the graphical interface, reads configuration, and accesses system capabilities; the component that performs DNS resolution, rule matching, and connection forwarding is called the core. Mihomo is the most common open-source core today, extending the configuration capabilities of Clash Meta. Clash Plus, Clash Verge Rev, FlClash, and Clash Nyanpasu are clients, not core names. The download page lists these clients by platform. Choose based on your operating system first, then compare interface and feature coverage.

A typical request passes through four stages. An application creates a destination domain or IP address, and the client decides whether to intercept it under the current configuration. The core then handles DNS and scans the rules in order for the first match. That rule sends the request to a proxy group, a direct policy, or a reject policy. Finally, a node establishes the connection to the destination server. A failure at any stage may look like “the webpage will not open,” but the troubleshooting method differs. If the wrong rule matches, changing nodes will not help. If DNS returns the wrong address, switching proxy groups alone cannot fix it. If the system never hands traffic to the client, the configuration itself may be perfectly valid.

Configuration Files and Runtime State Are Different

A YAML configuration file stores declarative settings such as ports, proxy nodes, proxy groups, rules, and DNS. After startup, the client loads these values into memory and builds runtime state based on the current mode, network interfaces, and permissions. Editing the file without reloading it may leave the interface using the old configuration. Conversely, temporarily switching nodes in the interface may not change the original subscription. This distinction helps determine whether “the file was not updated” or “the runtime state was not applied.” Reloading configuration, updating a subscription, and restarting the client are three separate actions, explained individually below.

The Complete Path from Request to Node

Take a browser request to a domain: the browser sends it to the operating system, where system proxy settings or the TUN interface determine whether it enters Clash; the core then resolves the destination according to the DNS mode and scans rules from top to bottom. If it matches DOMAIN-SUFFIX, the request is passed to the selected policy group, which chooses a proxy node through manual selection, fallback, or URL Test. After the node completes its protocol handshake, the request is sent to the destination. The reported “latency” may only measure TCP connection time to the test address, not the time required to load the entire webpage. For an explanation of speed-test metrics, see How Clash latency tests work.

Also distinguish a proxy client from a proxy service. The client executes local configuration; the subscription service provides node information and traffic service. They are separate organizations and do not share accounts. Obtain subscription URLs only from the service provider. The client links on this site are for downloading software; they do not generate nodes or provide subscriptions. Once these layers are clear, Chapter 2 explains how to choose a client based on your operating system and goals.

Choosing a Client: Match System Capabilities to Your Goals

Do not choose a client based only on its name or screenshots. Check three things: whether the system supports the interception method you need, whether the interface handles subscription and rule operations, and whether the core version supports the required protocols and DNS features. Desktop users typically need tray operation, system proxy support, configuration reloads, and logs. Mobile users must also consider background limits, battery policies, and system VPN permissions. Server and router users generally care more about command-line startup, configuration paths, and process supervision. The download page places Clash Plus first on each platform as a graphical entry point, but menu names may differ between clients.

How to Choose on Windows and macOS

Windows users can start with Clash Plus, Clash Verge Rev, FlClash, or Clash Nyanpasu. For traditional desktop controls and fewer options, choose a client with an easy-to-read interface. For more Mihomo settings, TUN, or rule debugging, choose one that exposes core logs and a complete configuration area. Clash for Windows is no longer maintained and is not recommended as the default for a new installation. Existing configurations can be migrated, but save the subscription URL and custom rules first. macOS options include Clash Plus, Clash Verge Rev, FlClash, and ClashX Meta. ClashX Meta is no longer maintained; keep it only for reading legacy configurations, not as the main entry point for a new setup.

Android and iOS Limitations

Android clients must capture traffic through the system VPN or VpnService, so the first launch displays a system authorization prompt. Clash Plus, Clash Meta for Android, FlClash, and Surfboard place their settings in different locations, but each requires the VPN switch to be running. Android battery-saving policies may suspend background processes, breaking the connection after the screen locks. If that happens, add the client to the system’s battery-optimization exceptions and check its background-data permission. Android setup also involves notification permission, the always-on VPN option, and local-network access. See Android VpnService and Battery Settings for details.

On iOS, system proxy access is centered on VPN configuration authorization, while obtaining and importing configurations are controlled by system screens. The download page provides a Clash Plus App Store link and identifies the official website as clashplus.io. On first launch, import the configuration, allow the system to add the VPN configuration, and then start the connection in the client. iOS manages background behavior, on-demand connections, and network switching together with the system. If cellular and Wi-Fi behave differently, test them separately.

Linux and the Mihomo Core

Linux desktop users can begin with Clash Verge Rev or FlClash. Servers, routers, and headless devices are better suited to running Mihomo directly. A core package provides only an executable or archive; it does not automatically create a systemd service, write configuration, or open ports. After installation, verify the architecture, file permissions, configuration directory, and listening address yourself. Exposing the management panel to the public internet increases risk. It should normally listen only on localhost and be managed through an SSH tunnel or the local network.

After choosing, do not install multiple clients and enable system proxy support in all of them. Competing for the same port or repeatedly rewriting system proxy settings creates difficult-to-diagnose state. For a first setup, keep only one client running. Once the connection, rules, and DNS are confirmed, migrate to another application if needed.

Installation and Initial Setup: Create a Safe, Reversible Environment

Before installing, note your operating system version, CPU architecture, and whether another VPN or proxy tool is active. On desktop systems, confirm that your account has installation privileges; on mobile systems, be ready to authorize the system VPN. Open the client page for your platform and choose a package according to its card. During first use, do not enable TUN or change DNS immediately. Let the client complete one ordinary system-proxy connection with minimal privileges first, so the scope of any later problem remains clear.

A Good Initial Order for Desktop Clients

After installation, launch the client and locate the area labeled Configuration, Profiles, Subscriptions, or something similar. Without a subscription, first confirm that the program opens, the core starts, and the logs show startup information; do not enter an address from an unknown source just for testing. After importing a configuration, check that nodes appear in proxy groups and that the rules area loads a rule count or rule file. Then open Settings and record the mixed, HTTP, SOCKS, and external-control ports. Default ports vary by client, so do not copy ports from another application.

System proxy settings affect only applications that honor them. Browsers, command-line tools, and some desktop programs may read one of the HTTP, HTTPS, or SOCKS settings, or ignore system proxy settings entirely. After enabling the system proxy, visit a known site in a browser, then test from the command line. If the browser works but the command line does not, first check whether the command-line tool needs separate environment variables instead of immediately enabling TUN.

A Good Initial Order for Mobile Clients

On first launch, an Android client requests permission to establish a VPN. The application name in the system dialog should match the client you installed. After authorization, return to the client, confirm that its status changes from stopped to running, and check for the VPN indicator in the notification bar. iOS requires permission to add a VPN configuration; after authorization, the VPN status in system settings changes. If the system reports an existing VPN, turn off the other VPN and authorize again to prevent two network extensions from running simultaneously.

Minimal Runtime Setup for the Mihomo Core on Linux

When running Mihomo directly on Linux, place the configuration file in a clearly defined directory and start it in the foreground to observe logs. After confirming that the configuration loads and ports listen normally, hand it over to systemd or another process manager. The command below shows a generic launch pattern; replace the path with the actual file location:

mkdir -p "$HOME/.config/mihomo"
cp config.yaml "$HOME/.config/mihomo/"
mihomo -d "$HOME/.config/mihomo"

In startup logs, focus on configuration parsing, DNS initialization, proxy-group loading, and port listening. If YAML indentation is invalid, the core usually fails during startup. If the configuration loads but nodes are unavailable, the error appears during an actual connection or health check. Do not confuse these two types of logs. Once foreground operation is stable, create the service file with a fixed working directory and user permissions.

Basic Configuration File Structure

The following snippet shows a readable minimal structure. Node content and fields supplied by the subscription service must follow the actual configuration. The names in this example only illustrate how references work:

mixed-port: 7890
mode: rule
allow-lan: false

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

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

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,PROXY

The password in this configuration is an example value and cannot be used for a real connection. Actual configurations may also include TLS, UDP, port multiplexing, and protocol-specific fields. Do not publish subscription contents, passwords, or management keys in public repositories, and do not expose a complete subscription URL in screenshots. After installation, continue to the next chapter and replace the example configuration with a real subscription.

Subscriptions and Nodes: Updating Configuration and Understanding Proxy Groups

A subscription is typically a URL generated by a service provider. The client accesses it to retrieve node and rule configuration. Updating a subscription does not “test a node”; it downloads and parses a new configuration, after which the client may show added nodes, expired nodes, or new proxy groups. Use the original URL supplied by the service provider. Do not paste it into an unknown conversion site or expose the complete link in public chats, screenshots, or support tickets. Subscription URLs often contain access credentials; if one leaks, reset or regenerate it through the service.

How to Check the First Import

Add the URL in the client’s subscription-management area, give it a recognizable name, and run an update. When it finishes, check the status message and update time, then open the configuration details to confirm that nodes, proxy groups, and rules are present. Do not rely only on “Update successful”: some URLs return an HTML error page, which a client may report as downloaded but cannot parse as valid configuration. If proxy groups are empty, check the response format, subscription validity, and parsing logs.

When a subscription update fails, narrow the scope in this order. First, verify that the URL is reachable on the current network. Second, check the system clock, since TLS certificate validation depends on accurate time. Third, determine whether the client needs an existing proxy to update. Fourth, inspect HTTP status codes and parsing errors in the logs. Fifth, remove extra spaces or line breaks at the end of the URL. If a browser opens the URL but the client fails, the browser may be using a proxy that the client has not established. If the client fails directly but succeeds through an existing proxy, select the correct update proxy in the subscription settings.

How Nodes, Proxy Groups, and Policies Relate

A node is a specific remote connection endpoint; a proxy group is a selector that organizes multiple nodes. The simplest select group lets the user choose manually. URL Test selects according to test results, fallback switches when the current node is unavailable, and load-balance distributes requests according to its strategy. Test results reflect only the test URL and moment of testing, not the complete browsing experience. Node region, line congestion, destination location, and protocol compatibility all affect results. Start with a select group to establish a controlled baseline, then try automatic selection after confirming that the rules work.

Subscription Updates and Local Changes

Many clients store subscription configuration and local overrides separately. Direct edits to a generated subscription file may be overwritten during the next update. A safer approach is to use the client’s Override, Merge, or Patch feature and keep custom proxy groups, rules, and DNS in a separate file. If the client has no override support, export a backup before editing and record where changes were made. To determine whether a change took effect, check the active configuration preview and logs, not only the file on disk.

Node selection should not focus only on the lowest latency. A stable, low-loss route is usually better for long-term use than a node that occasionally reports an exceptionally low number. Also consider traffic multipliers, exit region, UDP support, and restrictions imposed by the destination service. See How to Choose Clash Nodes to build your own selection notes. Once subscriptions update normally, move to proxy modes in the next chapter rather than misjudging rule behavior before the mode is clear.

Proxy Modes: How to Use Direct, Global, and Rule

The proxy mode determines how the core handles incoming requests. Direct connects requests straight to their destinations and is useful for checking the underlying network or isolating rule-related issues. Global sends most requests to one proxy group, making it useful for quickly testing whether a route can reach a destination, but unsuitable as a long-term fine-grained routing strategy. Rule matches rules from top to bottom and is the most common mode for everyday use. Switching modes does not change the nodes themselves or automatically fix DNS, system proxy, or TUN permission issues, so use logs and connection records to identify the cause.

Use Direct Mode to Establish a Baseline

When a webpage will not open, temporarily switch to Direct and see whether the destination connects normally. If Direct works but Rule fails, the issue may involve rules, the proxy node, or the proxy group. If Direct also fails, check the local network, DNS, destination status, or system firewall. Direct does not prove that the rules are correct because it bypasses the proxy path. Switch back to the previous mode after testing so requests do not bypass the intended routing policy.

Use Global Mode to Test a Node

Global mode sends requests to the selected proxy group and is useful for answering “can this group of nodes reach the destination?” If the destination works in Global but not Rule, inspect the matched rule and proxy-group reference first. If it still fails in Global, check the current node, protocol handshake, exit region, and remote response. Global may also proxy mainland-China websites, local-network addresses, or services that require a local IP, so use it only as a short diagnostic tool and restore Rule afterward.

What to Check in Rule Mode

The key to Rule mode is not the number of rules but their order and scope. A domain may satisfy several conditions, and the core normally uses the first matching rule. A common configuration handles LAN addresses, private IPs, and specific domains first, then advertising or regional lists, with MATCH as the final fallback. Without MATCH, unmatched requests may use a default policy and behave differently than expected. Confirm that the selected proxy-group name exactly matches the name referenced by the rule.

Client connection logs can usually show the requested domain, matched rule, and final policy. When access fails, clear or filter the connection log, open only one target page, and observe whether requests appear, what the rule field shows, and which node the policy group ultimately selected. A browser may request many domains at once, so a page opening does not mean every resource followed the same path. For application issues, also check whether the application uses QUIC, DoH, or its own proxy; such traffic may not appear like ordinary browser connections.

Where System Proxy Ends and TUN Begins

System proxy settings mainly capture TCP applications that follow the system configuration. TUN uses a virtual network interface to capture a broader range of system traffic. With TUN enabled, programs that bypass system proxy settings may enter the core, but permissions, routing, and DNS become more complex. First validate subscriptions, rules, and nodes in system-proxy mode. Enable TUN only when you have confirmed that an application ignoring the system proxy truly needs to be captured, as covered in Chapter 7.

Rule-Based Routing: From Match Order to Verifiable Policy Design

Rule-based routing sends different requests to direct, proxy, or other policy groups according to explicit conditions. More rules are not automatically better. Clear boundaries, stable order, and an explicit fallback matter most. Common types include DOMAIN for exact domains, DOMAIN-SUFFIX for suffix matches, DOMAIN-KEYWORD for keywords, IP-CIDR for IP addresses or ranges, and MATCH for requests not matched earlier. The policy name on the right side of a rule must exist in proxy-groups or among reserved policies; otherwise the rule may be present in the file but will not work as intended.

Differences Between Domain Rules

DOMAIN,api.example.com,PROXY matches only the specified exact domain. DOMAIN-SUFFIX,example.com,PROXY generally covers that domain and its subdomains. DOMAIN-KEYWORD,example,PROXY matches the keyword anywhere in a domain, giving it broader scope and a higher risk of false matches. When adding a rule for a service, prefer an exact-domain or suffix rule. Use a keyword rule only when the domain structure is complex and its scope is understood. Domains in rules should not include a protocol, path, or port; writing https://example.com/path will usually not produce the intended match.

Rule Order and LAN Exceptions

LAN and local addresses should normally appear near the top. This prevents requests to printers, router admin pages, and home servers from being sent through a remote node. A sample order is shown below:

rules:
  - DOMAIN-SUFFIX,lan,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

no-resolve prevents an IP rule from triggering an extra DNS lookup just to evaluate a domain, which is useful when matching an explicitly known IP range. It is not a switch that belongs on every rule; understand the current DNS mode and rule-engine behavior before using it. GEOIP relies on an IP database, so database update status affects results. When a site has clear domain and exit requirements, prefer a domain rule instead of relying entirely on regional matching.

Rule Sets and Local Overrides

Large domain lists are commonly loaded as rule-provider entries or rule sets. Rule sets simplify centralized maintenance, but debugging requires knowing where the actual match came from. After changing local rules, save the configuration and reload it. If a rule set comes from a remote URL, also confirm that it updated successfully. To make troubleshooting easier, keep a small set of personal exceptions at the top of a separate file, place general rule sets below it, and retain one explicit MATCH at the end. This quickly handles personal exceptions without modifying the upstream subscription.

How to Verify a Rule

Test one target domain at a time. Clear the connection log, visit the target, and inspect the connection details for the domain, resolved address, matched rule, and final policy. If there is no record, first check whether the application uses the system proxy or TUN. If a record exists but matches MATCH, check whether the rule file loaded and whether the order is correct. If the intended rule matches but the request still fails, the issue has moved beyond the rule layer to the proxy group, node, or remote response. Do not change three configuration points at once, or you will not know which change produced the result.

Rule-based routing is also affected by caching. A browser may cache DNS, connections, or redirects, while the client may retain connection state. After changing rules, close the target page, reload the configuration, and, if necessary, establish a new connection before observing new requests. For long-term maintenance, keep personal rules in separate snippets with dates and purpose notes, and periodically remove obsolete exceptions so the rule table does not become an inexplicable black box.

TUN and DNS: Handling Traffic Beyond System Proxy Coverage

TUN is a virtual network interface. When the system sends traffic into it, the Clash core can receive requests closer to the network layer, giving applications that ignore system proxy settings a chance to use the routing rules. TUN is not a “faster proxy mode,” nor does enabling it solve every network problem. It requires system permissions, routing settings, and compatible DNS handling. Running it alongside another VPN, virtual adapter, or enterprise security tool can also create route conflicts. Enable it only when ordinary system proxy mode cannot cover the target application.

Preparation Before Enabling TUN

Turn off other VPNs first and record whether the current network works normally. In the desktop client, locate TUN, Enhanced Mode, or virtual-adapter settings and confirm that the core supports the feature. Windows may request driver installation or administrator privileges; macOS may ask you to allow a network extension; Linux may require CAP_NET_ADMIN or root privileges. Mobile VPN interception is controlled by the system application layer and usually does not use the same TUN switch as desktop clients. Keep a way to disable TUN before enabling it, so you can recover the network after a reboot if necessary.

What DNS Mode Does

DNS does more than translate domains into IP addresses. Rules generally need to see the domain first, and DNS handling affects rule matching, Fake-IP mapping, LAN access, and protection against poisoned responses. Common approaches include redir-host and fake-ip. redir-host returns real resolved addresses and is straightforward for compatibility, but some results may be affected by the current network. fake-ip assigns a virtual address to each domain while the core preserves the domain in a mapping table, making domain matching possible during connection handling. Some LAN devices, applications with hard-coded IPs, and special authentication flows may not support it.

The sample configuration is shown below. Adjust the actual DNS servers to match your network environment and client support:

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
    - 1.1.1.1
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "+.local"

The Fake-IP address range must not conflict with the real LAN subnet, and the filter list should not be copied blindly. When accessing LAN hostnames, smart-home devices, or a corporate intranet, add the relevant domains to the filter range and confirm that LAN DNS remains reachable. If an application displays an IP address rather than a domain, Fake-IP may not be able to recover the original domain. Add that application to the filter or use a more suitable interception method.

Troubleshooting Order After Enabling TUN

After enabling it, test the LAN gateway first, an ordinary domain second, and a destination requiring a proxy last. If LAN access fails, check routes, Fake-IP filters, and the allow-LAN setting. If ordinary domains fail, check DNS logs, the virtual adapter, and system DNS. Only when the first two work should you investigate rules, proxy groups, and nodes. If all network access is lost, immediately disable TUN or exit the client, restore basic connectivity, and then inspect permissions and route logs. Do not keep adding configuration on top of a broken network.

DNS caching can also make a change appear ineffective. After modifying the configuration, reload it in the client, reconnect the network, and flush the DNS cache as required by the operating system. A browser’s built-in secure DNS may bypass system DNS, and an application’s own resolver may bypass the core. During troubleshooting, identify the resolution path used by the test tool. Once TUN and DNS are verified, do not keep adding options for complexity’s sake. A stable, explainable configuration is easier to maintain than one overloaded with features.

Daily Maintenance and Advanced Paths: Keep Configuration Explainable

Reliable Clash use depends less on frequent tweaking than on a regular review cycle. After each subscription update, confirm the update time, that nodes still exist, and that proxy-group references remain complete. After each client upgrade, review core logs and system proxy status. After changing rules or DNS, change one variable and run one target test. Treat the configuration as a maintained runtime file rather than a setting imported once and forgotten. This greatly reduces the uncertainty behind “it worked yesterday, but stopped today.”

Records Worth Keeping

At minimum, record the current client name, configuration source, proxy mode, mixed port, whether TUN is enabled, DNS mode, and custom rule files. Do not place the subscription URL directly in public documentation; record only its purpose and where it is managed on the service side. When a problem occurs, note the time, network type, target domain, matched rule in the connection log, and error message. This context is far more useful than simply saying “the internet does not work” when determining whether the subscription, rules, DNS, node, or system permissions changed.

Migration Steps for Updating the Client or Core

Before upgrading, export the current configuration or copy the local override files, and note custom rules and proxy-group names. After installing the new client, do not enable TUN immediately. Import the configuration and inspect the proxy groups, then enable the system proxy and test a browser, and only afterward restore TUN, DNS, and startup launch. Clients do not fully agree on supported fields, external-control interfaces, or override syntax. A configuration that imports successfully does not mean every option was applied. If startup errors appear, return to a minimal configuration and restore it section by section instead of copying the entire old directory over the new client.

A Decision Tree for Common Failures

If the client will not open, check the installer, permissions, and system logs first. If it opens but has no nodes, check subscription updates and configuration parsing. If nodes exist but every request fails, check proxy-group selection, the node handshake, and system time. If only some domains fail, check rule matches, DNS, and destination restrictions. If the browser works but one application does not, check whether that application honors system proxy settings. If enabling TUN breaks the entire network, disable TUN and check routes, permissions, and other VPNs. This sequence moves outward from the local program toward the remote service and avoids blaming every problem on the node.

The FAQ covers short questions such as failed subscription updates, system proxy settings, and configuration imports. When you need a definition, use the site’s client and configuration documentation to find the relevant chapter. Blog posts are suited to focused topics such as Fake-IP principles and iOS configuration imports, while this page is designed for repeatedly locating a section during setup. Each content type has a different purpose, so there is no need to reread the entire documentation from the beginning.

Taking Mihomo Configuration Further

After completing basic routing, study proxy-group strategies, rule-provider, script rules, external-control interfaces, and service-based operation in sequence. Advanced configuration should follow two principles: every new feature should have a clearly stated problem it solves, and every remote source should have a clearly identified maintainer. Do not enable large numbers of DNS options, scripts, and rule sets simply to copy someone else’s complete configuration. Complex setups have wider failure boundaries, and upstream changes may invalidate old fields. When reading a configuration, start with ports and mode, then DNS, followed by proxy groups and rules, and review experimental options last.

For servers and routers, plan Mihomo process permissions, configuration directories, and management interfaces separately. Bind the management interface only to trusted addresses, restrict configuration-file read access, check logs after service restarts, and retain the previous working core during upgrades. On desktop and mobile devices, focus on background permissions, preventing VPN conflicts, and removing expired subscriptions and obsolete rules. Across platforms, the core troubleshooting method is the same: confirm that traffic enters the core, confirm how DNS and rules handle it, then confirm that the policy group and node complete the connection.

The Clash workflow can now be summarized as a reliable path: choose a client that fits the system and install it with minimal privileges; import and verify a subscription; establish a routing baseline with Rule mode; verify rules through connection records; enable TUN and Fake-IP only when necessary; then update subscriptions, review logs, and back up custom configuration on a schedule. For a specific operation, return to the Quick Start and follow the main path. For the complete client list, visit the Clash Downloads page and choose your platform.