Clash from Beginner to Advanced: Installation, Subscriptions, Rules & TUN

Core concepts: distinguish the client, core, and configuration

Clash is not a single installer

“Clash” usually refers to an ecosystem of clients and cores built around rule-based proxying, not one fixed application interface. Users interact with graphical clients such as Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu, Clash Meta for Android, or ClashX Meta. The core is what actually establishes proxy connections, parses configuration, and matches rules. Most current clients are built around the mihomo core, while the interface presents its capabilities through switches, lists, and status pages.

This relationship matters. A client that will not open, a subscription that will not update, and a rule that has no effect are often problems at different layers. Check the client first when the interface crashes; inspect core logs and configuration for protocol or rule behavior; check the subscription source when content is incomplete. Treating all three as one problem often leads to repeated reinstalls without addressing the cause.

What happens along a connection path

After an application starts a network request, the traffic must first enter Clash. The system proxy routes applications that honor the operating system’s proxy settings; TUN mode creates a virtual network interface to receive a broader range of traffic at the network layer. The core then identifies details such as the destination domain, destination IP, port, and process, and matches them against the configuration rules from top to bottom. The result points to a policy group, which selects a specific node, a direct connection, or a rejected request.

Domain requests also pass through DNS. DNS does more than turn domain names into IP addresses: it affects whether rules can see the original domain, whether DNS pollution occurs, and how IPv4 and IPv6 connections are selected. A typical path is: application request → system proxy or TUN takeover → DNS resolves the address or creates a domain mapping → rule matching → policy group selects an egress → node establishes the connection. Most settings in the following chapters adjust one part of this path.

Subscriptions, configuration files, and nodes

A subscription link is the entry point for retrieving configuration content. After a client requests it, the server may return complete YAML or an encoded list of nodes. A full configuration usually includes proxy nodes, policy groups, rules, DNS, and other core parameters; a node-only subscription needs a client template or conversion service to supply policy groups and rules. A node is only a connection egress and cannot replace a complete configuration.

Locally saved configuration files are usually written in YAML. YAML is indentation-sensitive: use spaces for nesting and do not mix in tabs. Fields at the same level must use consistent indentation, and list items begin with a hyphen. Many “configuration parse errors” are not protocol incompatibilities but missing spaces after colons, incorrect indentation, duplicate fields, or unquoted special characters. Keep a copy of the original file before editing; it is safer than trying to reconstruct it from memory.

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

proxies:
  - name: "Example Node"
    type: socks5
    server: 192.0.2.10
    port: 1080

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

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

Common control-panel statuses

“System Proxy” means the client is changing the operating system’s proxy settings, but it does not mean every program will honor them. “TUN” means virtual-interface takeover is enabled, but routing, DNS, and permissions still need to be verified. “Rule” is rule mode, routing connections according to rules; “Global” is Global mode, usually sending requests to one policy group; “Direct” attempts a direct connection. These are separate dimensions, not mutually exclusive choices. For example, System Proxy and Rule mode can be enabled together, as can TUN and Rule mode.

You do not need to understand every field at once. Remember: the client provides the controls, the core executes them, the configuration describes behavior, the subscription updates the configuration, and rules choose the egress. Every new feature can be placed into one of these five roles. That makes unfamiliar clients easier to navigate even when their interface labels differ.

Choose a client by platform and workflow

Start with a graphical client or the core directly?

Most desktop and mobile users should start with a graphical client. It handles configuration storage, the system proxy, startup, subscription updates, policy-group switching, and log viewing, making the status easier to inspect when something goes wrong. Running the mihomo core directly is better suited to servers, routers, containers, or users who manage service processes themselves. This approach requires manual configuration, listening ports, startup arguments, and service supervision, along with your own permission and log-rotation setup.

The download page is organized by Windows, macOS, Android, iOS, Linux, and core packages. Clash Plus is the recommended starting point on major platforms for users who want a consistent workflow and direct subscription imports. Clash Verge Rev, FlClash, and Clash Nyanpasu provide desktop interfaces; Clash Meta for Android and Surfboard target Android; ClashX Meta is an archived macOS client that is no longer maintained; Clash for Windows is also discontinued and should only be used for viewing legacy configurations or migrating data.

Choosing between Windows and macOS

Windows users should first confirm the system architecture. Most ordinary PCs use x64, while ARM Windows devices need packages for the matching architecture. An installer can create shortcuts and handle removal; an archive is easier to keep in a self-contained directory, but updates and file associations may require manual work. If Windows Firewall prompts you on first launch, allow private-network access only if appropriate. Enable LAN access separately only when devices on your local network need to connect to this machine’s proxy port.

macOS users need to distinguish Apple Silicon from Intel. Apple Silicon packages are for devices with M-series chips, while Intel packages target older x86_64 hardware. The wrong architecture may prevent startup or run through a compatibility layer with additional issues. When a client first changes the system proxy, creates a network extension, or enables TUN, macOS may request administrator approval. That is normal for writing network settings. To verify a subscription first, leave TUN off and use the system proxy for the initial connection.

On mobile, function count is not the priority

Android clients usually take over traffic through the system VPN interface. After installation, allow the client to establish a VPN connection, then review the manufacturer’s battery-optimization, background-activity, and autostart settings. If the connection disappears after the app stays in the background for a few minutes, check power-saving policies before changing nodes. Per-app proxying controls which apps enter the tunnel, but “include” and “exclude” modes mean opposite things across clients, so read the description carefully before saving.

iOS and iPadOS also use the system VPN configuration. The first connection displays a system authorization prompt; the tunnel cannot be created until it is approved. When a mobile device switches between Wi-Fi and cellular service, a brief reconnect is normal as the network path changes. If it never recovers, disconnect and reconnect, then check whether the subscription’s nodes are available. Mobile devices have limited resources, so avoid loading very large rule sets and numerous configuration copies at the start.

What to do with discontinued clients

Discontinued does not mean an existing configuration will stop working immediately, but future OS updates, protocol changes, and security issues may no longer be supported. Clash for Windows and ClashX Meta are useful for migrating legacy environments, not as long-term choices for new installations. During migration, locate or export the old configuration directory and record your usual policy-group selections, then import the subscription again in the new client. Do not copy an entire old application directory over the new one; their data structures and settings may differ.

There is no need to chase the client with the most settings. Reliable subscription updates, working system-proxy or TUN support, and accessible logs cover most needs. For a specific installer, open the download center and choose the platform tab. Confirm the platform and architecture before downloading the matching file to avoid problems that are really just package mismatches.

Installation and first launch: get the basic path working first

Prepare the old environment before installing

You can keep multiple clients on one device, but do not let them modify the system proxy or create TUN interfaces at the same time. Before installing a new client, disable the system proxy and TUN in the old one, then quit it completely. On Windows, confirm that the manual proxy is off in system network settings; on macOS, check the HTTP, HTTPS, and SOCKS fields for the current network service; on mobile, confirm that the old VPN is disconnected. This prevents clients from competing for ports and repeatedly overwriting system settings.

If you are migrating an old configuration, copy the configuration directory or export the YAML first. Preserve the subscription URL, custom rules, policy-group preferences, and DNS changes—not caches, logs, or temporary databases. A subscription URL is personal usage information and should not appear in public screenshots, forums, or repositories. After backing up, choose the platform-specific installer from the download center.

Windows installation and first checks

Once the Windows installer finishes downloading, follow the wizard to choose an installation location and launch the client. If Windows asks to install a network component or requests administrator permission, first confirm that you are operating on the client you just downloaded. After launch, do not enable every switch immediately. Find the “Configuration” or “Subscription” page and confirm that it loads, then check the mixed port, system proxy, and TUN status in Settings.

A common local mixed port is 7890, but it does not have to be fixed at that value. Any unused port works as long as applications using manual proxy settings point to the same port. If the log reports “address already in use,” the listening port is occupied. Quit other proxy programs or change mixed-port to a free port. After changing the port, update the proxy address in browser extensions, development tools, and command-line environments as well.

netstat -ano | findstr :7890

curl.exe -x http://127.0.0.1:7890 https://example.com/

The first command checks whether a process on Windows is using port 7890; the second explicitly sends a request through the local HTTP proxy. The test address only confirms that the proxy port accepts connections—it does not prove that a business website is reachable. If curl cannot connect to 127.0.0.1, check whether the client core is running before investigating the remote node.

macOS installation and system authorization

After downloading on macOS, move the app to the “Applications” folder and launch it from there. The first run may show a source confirmation or permission prompt; complete it through the security settings provided by the system. When changing the system proxy, the client may request administrator approval. Enabling TUN or a network extension may also require permission to add a VPN configuration. Return to the client afterward and confirm that the switch actually shows enabled; a dismissed prompt alone is not proof of success.

If another proxy client is already shown in the menu bar, quit the old program first. If the system proxy appears enabled but the browser is unaffected, open “System Settings → Network → Current Network → Details → Proxies” and verify that the address is 127.0.0.1 and the port matches the client. Before quitting the client, turn off the system proxy so it can clean up its settings. If an abnormal exit leaves proxy settings behind, remove them manually in network settings.

First launch on Android, iOS, and Linux

After installing on Android, grant the permission required to establish a VPN connection. If “Always-on VPN” is enabled and assigned to another app, change that setting first or the new client may not take over. Some systems restrict background networking and battery use; if the connection works until the screen locks, add the client to the list allowed to run in the background. During initial testing, disable complex per-app rules, confirm that all apps work, and only then add exclusions gradually.

After installing Clash Plus from the App Store on iOS or iPadOS, allow it to add a VPN configuration on the first connection. A VPN indicator in the status bar only means that the tunnel exists; it does not mean every node in the subscription works. Return to the client to inspect connection logs and test with an ordinary webpage. If cellular data works but Wi-Fi does not, check the current Wi-Fi DNS, captive portal, and routing restrictions.

The installation method for a Linux graphical client depends on the package type and distribution. Debian, Ubuntu, and derivatives can install deb packages; other distributions should use a compatible package format. If the tray icon is missing after installation, that does not necessarily mean the core is stopped—check the application window and process list. When running the mihomo core directly, specify the configuration directory and test the configuration first.

mihomo -t -d ./clash-config
mihomo -d ./clash-config

-t checks whether the configuration parses, while -d specifies the directory containing the configuration file and runtime data. Testing before startup separates YAML errors from network errors. For long-running services, use the system service manager for autostart, crash recovery, and log rotation instead of leaving a terminal window in the foreground.

Minimum acceptance checks after first launch

After installation, check in a fixed order: the client interface opens normally; the core reports that it is running; the local port is listening; at least one takeover method—system proxy or VPN/TUN—is selected; policy groups appear after importing the configuration; and a usable node produces connection logs. Do not use access to one website as the only test, because the site itself, DNS, rules, and node egress can all affect the result.

If the basic path is not working, do not adjust Fake-IP, rule sets, or scripts yet. Default settings make problems easier to isolate. For common download and installation questions, see the download FAQ; for the shortest setup path, return to the setup guide.

Importing a subscription: from link to working configuration

Confirm what the subscription returns first

Subscription links are usually generated by a service provider and may contain identifying parameters, so store them like account information. Do not put the full URL in public screenshots, synced browser notes, or public repositories. Before importing, confirm that the link is still valid and that the provider explicitly supports Clash or mihomo format. A link opening in a browser does not guarantee that the client can parse it; downloaded text is not necessarily complete YAML.

A complete configuration should include at least proxy nodes and policy groups; common fields include proxies, proxy-groups, and rules. If the response is only an encoded string, the client may need to recognize it as a generic subscription and convert it to a Clash configuration. If a remote service performs the conversion, remember that it will read the subscription URL. Prefer a format explicitly supported by the provider; every layer you remove is one fewer place for failure.

Add a subscription in the client

The entry may be called “Subscriptions,” “Configurations,” “Profiles,” or “Remote Configurations,” but the workflow is similar: create a remote configuration, paste the link, give it a recognizable name, save it, and trigger an update. After a successful update, select it as the active configuration, then choose an egress on the policy-group page. Adding a link to the list without switching to that configuration is a common first-use mistake.

Name configurations by purpose, such as “Daily subscription” or “Backup configuration”; do not put access credentials in the name. Avoid overly short update intervals. Subscription content rarely changes minute by minute, so frequent refreshes only add requests and may trigger server-side limits. Update daily or as the provider recommends, and refresh manually when you need changes immediately.

Troubleshoot update failures by response stage

“Unable to connect” usually means no valid response was received; check the current network, DNS, system time, and whether the URL is complete. “Request denied” or HTTP authentication errors usually indicate an expired link, missing parameters, or access restrictions. “Parse failed” means content was received but does not match the client’s expectations; common causes include an HTML page, an encoded subscription, invalid YAML indentation, or unsupported fields. If the update succeeds but no nodes appear, check whether the subscription contains nodes and whether filtering rules removed them all.

During troubleshooting, paste the link into the browser address bar on the current device only to inspect the response type; do not forward it. If it redirects to a login page, error page, or CAPTCHA, the client cannot parse it as configuration. If the browser downloads a file, inspect its opening fields in a text editor. Complete YAML usually shows keys and indentation; web content often starts with HTML tags; an encoded subscription may be one uninterrupted line of characters.

Some services return different formats based on the request’s User-Agent. If the client offers a subscription User-Agent setting, use the value required by the provider rather than randomly trying disguises. For more on subscription parsing, caching, and format-conversion issues, read How to troubleshoot an invalid Clash subscription link.

How local edits interact with remote updates

A remote subscription update usually rewrites the configuration, so rules added directly to subscription-generated YAML may disappear at the next update. For lasting changes, use the client’s override, merge, or script features. If the client lacks them, keep a separate local configuration and establish a clear update process. Do not let a remote configuration update automatically while treating it as a permanent hand-edited file.

Merge behavior usually involves prepending, appending, or overriding fields. Rules are ordered, so custom rules that should take priority belong before general rules; single-value fields such as DNS, ports, and modes are usually replaced by the value written later. Override syntax differs between clients. Recheck it when migrating instead of assuming an old script will work unchanged.

prepend-rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - DOMAIN,api.example.net,PROXY

append-rules:
  - MATCH,PROXY

The structure above expresses the idea of putting specific rules first while keeping a final fallback. Actual field names depend on the client’s override feature. In a standard Clash configuration, place rules in the rules list and keep only one final fallback. Of multiple MATCH entries, only the first one encountered has an effect.

What subscription conversion is for

Subscription conversion mainly turns a node list into a client-readable configuration or applies rule and policy-group templates. It cannot revive expired nodes or improve connection quality by itself. Conversion may change node names, policy groups, and rules, so save the old configuration first. If the result suddenly contains fewer nodes, check template filters, protocol support, and node-name regular expressions instead of focusing only on whether the link opens.

After importing, select a specific node in Rule mode, enable the system proxy, and watch the logs. Confirm basic connectivity before enabling automatic selection, complex rules, or TUN. Separating the checks makes it clear whether the issue comes from subscription content, policy selection, or the takeover method.

Proxy modes: choosing between Rule, Global, and Direct

Rule mode is best for everyday use

Rule mode evaluates requests against the configured rules one by one and sends them to the appropriate policy group. Common outcomes include PROXY, DIRECT, REJECT, and custom policy groups. Its benefit is not automatic speed; it lets different traffic use different egresses: local services can go direct, domains requiring a proxy can use a proxy group, and ads or known-invalid requests can be rejected. With sensible rules, you do not need to toggle the entire client repeatedly.

Rules are matched from top to bottom, and matching stops at the first hit. Specific rules must therefore come before broad rules. For example, a single-domain rule should precede a wider domain-suffix or rule-set match; LAN and reserved addresses usually come before the final proxy fallback. A final MATCH rule provides a destination for connections not recognized earlier.

Global mode is for temporary verification

Global mode usually sends all traffic captured by the client to a global policy group, where you select a node or egress. It helps determine whether rules are the cause of a problem. If a site fails in Rule mode but works immediately in Global mode, the node and takeover path are probably functional; check domain rules, IP rules, and DNS next instead of reinstalling the client.

Global mode does not mean every packet on the device automatically enters the proxy. Capture still depends on the system proxy or TUN. Switching to Global without enabling a takeover method leaves many applications connecting directly. Conversely, TUN with Direct mode still sends traffic through the core but may process it as a direct connection. Treat the mode and takeover method as separate settings.

Direct mode is for quick bypasses

Direct mode attempts to connect traffic directly. Use it temporarily to disable proxy decisions, compare direct and proxied paths, or troubleshoot the local network while keeping the client running. It does not necessarily mean the client has fully exited: the local port may still listen, and TUN may continue capturing traffic before sending it direct. To fully restore the original network state, disable the system proxy and TUN, then quit the client.

Some clients also offer extension modes such as Script, whose behavior depends on the script implementation. Beginners should not use script mode as the default because script errors, runtime conditions, and return values add more troubleshooting layers. When standard rules can express the logic clearly, use them first.

Policy groups are the actual egress after mode selection

Rules usually point to policy groups rather than hard-coding a node. A select group is chosen manually; url-test selects candidates based on test results; fallback tries available nodes in order; load-balance distributes connections across nodes according to its strategy. Each group solves a different problem, so do not judge it solely by the word “automatic” in its name.

Automatic tests use a specified test URL and interval, so they only reflect connectivity to that address. A good test result does not mean every service will behave the same way. Node location, routing, target-site restrictions, and connection reuse all affect real-world performance. For everyday use, keep one manual selection group and one automatic test group: use the automatic group for ordinary browsing and switch to the manual group when a specific service acts up.

proxy-groups:
  - name: "Manual selection"
    type: select
    proxies:
      - "Node A"
      - "Node B"
      - DIRECT

  - name: "Automatic selection"
    type: url-test
    proxies:
      - "Node A"
      - "Node B"
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 80

interval is the test interval in seconds; setting it too low creates extra requests. tolerance prevents frequent switching when nodes differ only slightly. The test URL should return a stable, lightweight response. If the current network cannot reach it, an automatic group may mark every node as unhealthy; choose a test address suitable for the environment.

How to verify a mode switch

Pin a known-working node, enable the system proxy or TUN, and test Rule and Global separately. If both fail, check local listening, node connectivity, and DNS. If Global works but Rule fails, inspect the matched rule and policy group in the logs. If the browser works but the command line does not, check whether the command-line program reads the system proxy; use explicit proxy parameters or TUN when necessary.

Do not identify the current mode only by the color of a home-page button. Matched rules and egress names in the logs are more reliable. A complete record should include the destination domain or IP, matched rule, policy group, and final node. With these four details, “an app cannot connect” becomes a sequence of checks rather than a reason to toggle every switch.

Rule-based routing and DNS: send requests to the right egress

Rule types and matching order

Domain rules are the easiest to read. DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a suffix and its subdomains, and DOMAIN-KEYWORD matches keywords in the domain. IP rules inspect the destination address and commonly include IP-CIDR, IP-CIDR6, and geographic database rules. Process rules can route by program name or path, but support and permission requirements vary by operating system. Rule sets move large collections into separate files for easier updates and reuse.

The broader a rule is, the later it should appear. If DOMAIN-SUFFIX,example.com,PROXY comes first and DOMAIN,internal.example.com,DIRECT comes later, the internal domain matches the suffix rule and never reaches the direct rule. Put specific exceptions before general rules. Finish with MATCH as a fallback so requests do not remain without a clear destination.

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

no-resolve means the IP rule will not trigger an additional domain lookup in order to obtain an IP. It suits connections where the destination IP is already known or where IP-rule matching should not initiate resolution. Do not add it mechanically to every IP rule; if matching depends on a domain-resolution result, resolution must remain enabled.

Rule sets, GeoIP, and GeoSite

Rule sets store domains, IP ranges, or classical rules in separate resources, while the main configuration references them through RULE-SET. This lets you update rules independently instead of replacing the entire subscription. Confirm that the rule-set behavior matches its contents: domain type is for domain behavior, ipcidr type is for network ranges, and classical type can contain complete rule lines. A wrong type can cause loading failures or prevent matches.

GeoIP classifies IP addresses using a geographic database, while GeoSite classifies domain collections. Both depend on local databases; stale databases can miss new domains or misclassify addresses. If the configuration parses but routing gradually becomes inaccurate, check the database update time and download source. See the GeoIP and GeoSite database update guide for the update process.

Why DNS affects rules

When an app accesses a domain, it may resolve it itself and then send an IP connection through the proxy, or pass the domain directly to the proxy. In the first case, the core may see only an IP, making domain rules difficult to apply. In the second, it can preserve the domain and route by domain rules. System proxies, SOCKS, TUN, browser secure DNS, and in-app resolvers can all change this path.

DNS settings typically cover the listener, IPv6, enhanced mode, the default resolver, and primary nameservers. The default resolver looks up the hostnames of other DNS servers and should be reachable directly from the current network. Otherwise you can create a loop where the DNS server requires the proxy while the proxy node’s hostname must be resolved first. Primary nameservers handle ordinary queries; choose UDP, TCP, DoH, or DoT services according to the network environment.

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

This configuration illustrates field relationships and should not be copied blindly into every network. Listening on 0.0.0.0 means every local interface may be able to reach the port; on an untrusted network, use a firewall or bind locally instead. Disabling IPv6 prevents Clash DNS from returning IPv6 results, but whether the system or other apps still initiate IPv6 requests depends on the takeover method and operating-system network.

Fake-IP versus Redir-Host

Fake-IP mode first returns a reserved address to the application while the core maintains a mapping between that address and the original domain. When the app connects to the reserved address, the core still knows the domain, allowing earlier domain-rule matching and reducing some repeated lookups. The reserved address is not the website’s real address; it is used only by the local mapping process. For the details and filtering options, read Clash Fake-IP mode explained.

Some LAN discovery, printer, gaming, time-sync, and real-IP-dependent apps do not work well with Fake-IP and can be added to fake-ip-filter. Avoid adding many broad domains at once, as that weakens Fake-IP’s domain-mapping advantage. When one app fails, confirm its domain in the logs, add the smallest necessary filter, and test again.

Redir-Host is closer to resolving the real address first and then handling the connection. It can work better with programs that depend on real DNS results, but may rely more heavily on DNS-path quality. Neither mode is universally better. For everyday desktop use, keep the client default initially; if LAN discovery fails, a particular app cannot log in, or domain rules disappear, use the logs to decide whether to change it.

How to troubleshoot unmatched rules

First, check whether the connection log shows a domain or only an IP. If it shows only an IP, domain rules may not match; inspect the app’s resolver, TUN sniffing, and DNS takeover. Second, confirm that the target rule appears before broader rules. Third, verify that the policy-group name matches exactly, including case, spaces, and symbols. Fourth, check that the rule set downloaded successfully and uses the correct behavior type. Only then investigate databases and caches.

After editing, reload the configuration and create a new connection for testing. Existing connections may reuse the old egress, and refreshing a page does not always create a new connection. Close the relevant app, clear connection records, or wait for the connection to end before testing again. Do not change rule order, DNS mode, and TUN parameters simultaneously; even if the issue disappears, you will not know which change fixed it.

TUN mode: capture traffic that ignores the system proxy

When TUN is needed

The system proxy works only for programs that actively read the operating system’s proxy settings. Browsers usually support this well, but command-line tools, game launchers, some desktop apps, containers, and software with custom network stacks may ignore it. TUN mode creates a virtual network interface and uses system routes to send a broader range of IP traffic into the core, making it suitable for applications outside system-proxy coverage.

TUN is not a switch that must be enabled because it is “more advanced.” If you only use a browser and apps that honor the system proxy, the simpler system-proxy setup is easier to troubleshoot. Enable TUN when you have identified an uncaptured program or need unified handling for UDP, command-line tools, and multiple apps. It adds virtual interfaces, routing, DNS hijacking, and permission layers, and can conflict with other VPNs, virtual machines, and security software when misconfigured.

Understanding the core parameters

enable controls whether TUN is enabled; stack determines how packets are handled between user space and the system network stack, with common values including system, gVisor, and mixed, subject to support in the current core and client; auto-route automatically writes routes; auto-detect-interface attempts to identify the default egress interface; dns-hijack sends specified DNS requests to Clash. Graphical client switches usually generate or overwrite these fields.

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

mixed is generally intended to accommodate different traffic paths, but not every device needs it. If the client provides a stack option, start with its default. strict-route applies stricter limits against route leaks and may affect LANs, hotspots, or virtual networks on some systems. Leave it off during initial setup to simplify verification, then test it after basic traffic works.

Enabling TUN on desktop systems

Disable TUN in other VPNs and old clients, leaving only the current client running. Import a configuration already verified in system-proxy mode, pin a working node, and then enable TUN. Approve the administrator prompt and watch for confirmation that the core is running, the virtual interface was created, and routes were written. You can temporarily disable the system proxy and test with a command-line tool that normally ignores it to confirm that traffic is actually entering through TUN.

If Windows loses all connectivity after TUN is enabled, turn TUN off first and check for leftover virtual interfaces, third-party VPNs, Hyper-V, or network filters from security software. Restart the client and restore automatic routing before trying again. On macOS, check network-extension or VPN-configuration authorization; a denied permission may cause the switch to turn itself off. Linux needs permission to create the TUN device and modify routes, and the service must be able to read the configuration and write to its runtime directory.

curl https://example.com/
curl --noproxy "*" https://example.com/

With TUN correctly capturing traffic, the second command can still enter TUN even when curl is told not to use traditional proxy environment variables. This helps distinguish “the program read an HTTP proxy” from “the virtual interface captured the traffic.” Check the Clash logs for the corresponding connection as well; do not infer the result from the webpage alone.

Combining DNS hijacking with Fake-IP

After TUN captures IP traffic, the core may see only resolved IPs if DNS is still sent directly by the app to a LAN resolver, affecting domain rules and Fake-IP mappings. dns-hijack sends common DNS requests to Clash DNS. Modern browsers and some apps may use encrypted DNS, which ordinary port-53 hijacking cannot read. Disable their independent secure DNS or ensure those connections are handled correctly by the rules.

If LAN domains stop resolving after DNS hijacking is enabled, check whether local names must be handled by the router’s DNS and configure nameserver-policy or an appropriate fallback path. Printers, NAS devices, and corporate domains often exist only in DNS for a specific network, where public resolvers cannot answer them. Send those domains to the correct local resolver instead of routing every DNS request direct.

LAN, virtual machines, and containers

After TUN rewrites routes, LAN access may pass through the core. Keep direct rules for private network ranges and account for local IPv6 addresses. To let other devices use this machine’s proxy, separately enable allow-lan, listen on an appropriate interface, and configure the firewall; this is different from local TUN takeover. Do not expose the proxy port to every network merely to capture traffic on the host.

Virtual machines and containers have their own virtual interfaces and network ranges. Automatic TUN routing can override or conflict with routes used by Docker, virtual-machine bridges, WSL, or corporate VPNs. If the problem occurs only inside a virtual environment, compare route tables before and after enabling TUN and identify which interface owns the target range. Add the virtual range to excluded routes or direct rules when necessary instead of disabling all routing rules.

A fixed troubleshooting order for TUN failures

First confirm that the same node works in system-proxy mode to rule out the node. Then verify that the TUN switch stays on and the virtual interface exists. Check automatic routing and default-interface detection next. Then inspect DNS takeover and whether requests appear in the logs. Finally check other VPNs, security software, virtual interfaces, and the firewall. Change one variable at a time and create a new connection after each change.

When the system proxy works but TUN does not, you usually do not need to re-import the subscription. Focus on permissions, routes, DNS, and network conflicts. For a fuller explanation of operation, stack choices, and platform differences, read How to enable Clash TUN mode.

Everyday maintenance and an advanced path: keep configurations recoverable

Establish a steady maintenance routine

A normally running Clash setup does not need constant adjustment. Check only whether subscriptions update, common policy groups have usable nodes, rule sets and geographic databases are outdated, and key settings remain after client updates. Update subscriptions daily or as the provider recommends, and update rule sets and databases according to how often they change. Excessive automatic testing and subscription refreshes add requests and can make node selection change constantly.

If settings revert to defaults after the client starts, check whether you switched configurations, are using a portable directory, or lack write access to the configuration directory. If a system update removes TUN permissions, recheck network-extension or virtual-interface authorization. After sleep and wake, wait for the network interface to return before reconnecting the core; if recovery fails every time, inspect default-interface detection and the client’s background behavior.

What is worth backing up

Prioritize subscription URL lists, custom rules, override scripts, DNS changes, and separate local configurations. Cache databases, temporary connection records, and ordinary runtime logs usually do not need long-term retention. Backup files may contain subscription parameters, node credentials, and LAN addresses, so store them in a controlled location and never upload them directly to a public repository.

For multiple devices, centrally distributing the subscription link is easiest to maintain, but device-specific settings should not be forced into one shared configuration. Desktop TUN stack settings, Android per-app proxy rules, and macOS network extensions differ by platform. Share nodes and baseline rules across devices, while keeping system-specific fields in a local override layer. For trade-offs among subscriptions, WebDAV, and manual exports, see Comparing Clash configuration-sync options across devices.

How to read logs

Log levels usually include silent, error, warning, info, and debug. Keep info for everyday use; switch to debug temporarily for a short investigation, then restore it after reproducing the issue to prevent rapid growth. Start by locating the exact time of the failure, then check the destination domain or IP, matched rule, policy group, final egress, and error type. Do not pick one random error from a large log and treat it as the conclusion.

A connection timeout usually means the request was sent but did not complete in time; possible causes include the node, routing, target service, or network restrictions. A refused connection means the destination explicitly rejected it. A DNS error means name resolution failed. A TLS error may involve the system clock, certificate chain, domain mismatch, or an intermediate network. A configuration parse error leads back to the YAML line and field. The failed layer determines what to inspect next.

General troubleshooting tree: start with the smallest scope

If every site fails, start with the client core, local port, takeover method, and node. If only one site fails, check the matched rule, DNS, node egress, and the site’s own restrictions. If only one app fails, confirm whether it reads the system proxy and whether it uses independent DNS or QUIC. If only TUN fails, check permissions, routes, and conflicts. If only subscription updates fail, do not change proxy rules; inspect the link response and format directly.

If direct access does not return after disabling the system proxy, check for leftover OS proxy settings, environment variables, or an independent browser proxy. If problems remain after disabling TUN, check whether the virtual interface and routes were removed; a normal system restart may be needed to rebuild the network stack. Avoid “one-click network repair” scripts from unknown sources: they may reset DNS, the firewall, and network interfaces at once, destroying useful evidence.

# View common proxy environment variables on macOS and Linux
env | grep -i proxy

# Temporarily remove proxy variables from the current terminal session
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxy

# Test the local proxy port
curl -x http://127.0.0.1:7890 https://example.com/

Environment variables affect only programs that read them and the current session. A graphical client changing the system proxy does not automatically remove variables set manually in a terminal. Conversely, setting HTTPS_PROXY in a terminal does not mean other desktop apps will use it. Knowing how each application is captured is an important habit for stable long-term use.

Upgrading the client and migrating configuration

Read the client’s release notes before upgrading and check for changes to the configuration directory, core fields, or network extensions. Export key configuration first, then quit the old version normally and install the new one. After upgrading, verify that the configuration loads, subscriptions update, and system-proxy and TUN permissions remain before restoring complex overrides. Do not also change the subscription, rule template, and DNS configuration on upgrade day; stacked changes are difficult to trace.

When migrating from discontinued Clash for Windows or ClashX Meta, re-import the remote subscription instead of copying the entire database. Move hand-written rules separately and reconfirm policy-group selections. A new client using the mihomo core may expose more extension fields, but confirm legacy-field compatibility with a configuration test and logs.

Moving from everyday use to advanced configuration

After basic connectivity works, advance in dependency order. Stage one is reading connection logs and rule order well enough to explain why a request uses a particular egress. Stage two is mastering policy groups so manual selection, automatic testing, and fallback recovery each have a clear role. Stage three is understanding DNS, Fake-IP, and rule sets to improve domain recognition and routing accuracy. Only then move deeper into TUN, process rules, LAN sharing, and multi-device synchronization.

Server and router users also need to learn service management, configuration-directory permissions, log rotation, listening addresses, and firewalls. Exposing a control interface or proxy port expands the attack surface, so restrict control ports to trusted interfaces and enable appropriate authentication. Turn on LAN access only when necessary and use the system firewall to limit sources.

To tell whether you really understand Clash, do not measure the length of the configuration. Ask four questions: How does traffic enter the core? Which rule did this request match? Which policy group does that rule target? Which egress did the group ultimately choose? Once you can trace that path, changing clients, platforms, or configuration no longer means starting from scratch.

What to read next

If you have not completed your first connection, return to the setup guide and follow the steps. To change clients or confirm your system architecture, visit the download center. For unfamiliar abbreviations and fields, open the terms guide. Subscription parsing, TUN, Fake-IP, database updates, and multi-device synchronization each have dedicated technical notes; follow the one relevant to your current issue instead of reading every advanced setting at once.

The principles of a stable configuration are simple: get it working before routing; read the logs before changing parameters; change one variable at a time; and keep a recoverable version before editing. With this order, Clash may have many settings, but every issue maps to a clear stage instead of becoming a tangled mess.