Clash User Guide: Installation and configuration for Windows, macOS, Android, iOS, and Linux

If you only need a basic connection once, start with the shorter Quick Start Guide. This page is designed for reference: each platform section starts with downloading and installation, then covers subscriptions, system proxy, TUN, permissions, and platform limits. For a specific issue, use the contents above to jump straight to the relevant section. Choose every client by platform from the Download Center; Clash Plus is the preferred choice for both desktop and mobile platforms. Check the current download-page list for other options and their maintenance status.

Understand the difference between the client, core, and configuration

Using Clash involves three separate components. The client provides the window, menus, switches, and subscription management. Cores such as mihomo handle listening ports, DNS resolution, rule matching, and connections. The configuration file stores proxy details, proxy groups, rules, DNS settings, and TUN parameters. Changing the client UI does not change the subscription; after importing the same compatible configuration, rule results are usually unchanged. Conversely, a client window can open normally while its core is stopped, in which case a system proxy setting will not forward traffic.

Subscription links are usually generated by the service provider. After retrieving a link, the client downloads a YAML configuration or converted configuration content. Successful import only means the format is readable; it does not guarantee that the proxy endpoints can connect. To reduce variables, keep the subscription's original rules during initial setup instead of immediately adding many custom rules, overriding DNS, or changing listening ports. Once the basic connection is stable, add personal settings one at a time so each change can be rolled back easily during troubleshooting.

Checks before importing a subscription

When copying a link, make sure it contains no leading or trailing spaces, line breaks, or punctuation added by a chat app. A link is a personal configuration credential and should not be posted publicly or shown in screenshots. If the provider offers both one-click import and a standard subscription URL, use the method explicitly supported by the client. Paste a standard URL into the “Subscriptions,” “Configuration,” or “Profiles” page. After importing, confirm that the configuration name, proxy groups, and rules appear, then set it as the active configuration. Saving a URL without enabling its configuration is one of the most common omissions after a fresh installation.

Choosing between system proxy and TUN

A system proxy works well for browsers, desktop messaging apps, and applications that actively read the operating system proxy settings. The client usually writes HTTP and SOCKS listening addresses; a common local address is 127.0.0.1, while the port is determined by mixed-port, port, or socks-port in the configuration. Its advantages are low permission requirements and a clear toggle. The limitation is that some games, command-line programs, store apps, and applications with their own network stack may ignore the system proxy.

TUN mode uses a virtual network interface to capture a broader range of system traffic. It is useful for programs that cannot read the system proxy and can handle more TCP, UDP, and DNS requests consistently. The trade-off is that it requires higher system privileges and may conflict with other VPNs, virtual machines, container networks, security software, or enterprise networking components. For a first setup, verify the system proxy before enabling TUN as needed instead of running multiple traffic-capture tools at once. On mobile devices, the VPN switch works more like TUN, and the system usually allows only one such network extension to be active.

Build a repeatable verification routine

Every platform can follow the same verification order: confirm that the client core is running; confirm that the intended configuration is selected; check whether the proxy mode is Rule, Global, or Direct; inspect the connection log to see which rule and proxy group handled the request; only then assess whether the proxy endpoint itself works. Checking only whether a webpage opens makes it difficult to tell whether the problem is DNS, rules, the endpoint, or system-level capture. Connection logs provide stronger evidence. For relevant error fields, see How to Locate Errors in Clash Logs.

On Windows, options include Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu, and the archived Clash for Windows. For a new setup, prefer a maintained client that supports mihomo. Before downloading, check the device architecture under “Settings → System → About”; most PCs use x64, while ARM is needed only on devices with an ARM processor. Installers and portable archives work differently: an installer creates a program directory and shortcuts, while a portable package should be fully extracted to a fixed directory before use. Do not launch it from an archive preview window.

Installation and first launch

Get the installer from the Windows download section, then quit any older Clash client so two programs do not compete for the same listening port. Complete the setup wizard and launch the client. If Windows shows a firewall prompt, allow only the network types actually needed for LAN sharing. For a single-device setup, keep the core bound to the local loopback address; there is no need to expose every network interface just to connect. If the app opens but the core fails to start, check whether an older client is still running in the system tray, then inspect port usage and core logs.

Do not place a portable version in a temporary download folder, a conflict-prone sync folder, or a location protected by strict permissions. Clients usually need to write configuration, cache, and log files to their data directory. A non-writable path can make imported configurations disappear, updates fail, or the app return to its initial state at every launch. After the first run, confirm the data-directory location in the client settings and back up long-term configurations somewhere you control.

Import a subscription and choose a policy

Open the “Configuration” or “Subscriptions” page, choose import from URL, paste the subscription address, and wait for the download to finish. When the new configuration appears, enable it or set it as current. Then open “Proxies” and set the mode to “Rule.” Rule mode checks the configuration from top to bottom and stops at the first match; the proxy group determines the actual outbound route. During initial testing, do not accidentally select “Direct,” and do not use “Global” long-term without understanding its effect. Rule mode can keep LAN traffic direct, send commonly used services in mainland China directly, and proxy specified destinations, making it the most practical default for everyday use.

For manually selected proxy groups, choose an available option explicitly. For URL-test, failover, or load-balancing groups, the configuration handles probing and switching. A displayed test result reflects only the connection to the specified test URL; it is not the same as download speed or the real experience across all websites. For the distinction, see How Proxy Latency Tests Work.

Enable the system proxy

Open “System Proxy” only after confirming that the core is running. This points Windows proxy settings to the client's local port. Visit a target website in a browser and check the client's connection page for the domain, matched rule, and proxy group. If the browser works but a command-line program does not, the subscription is usually not the problem; that program may simply ignore the Windows system proxy. Configure HTTP_PROXY, HTTPS_PROXY, or a SOCKS address for the program, or switch to TUN if needed.

set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890

curl https://example.com

The example above applies only to the current Command Prompt window. Replace the port with the client's actual mixed port. PowerShell, Git, package managers, and development tools may each have their own proxy settings; browser access does not mean every program follows automatically. During troubleshooting, check the tool's own configuration first, then decide whether environment variables or TUN are necessary.

TUN mode and permissions

If you need to capture traffic from games, store apps, UDP, or software that ignores the system proxy, disable other VPN tools, launch the client with administrator privileges, and enable TUN. The first activation may install a virtual adapter or network component. Afterwards, check whether the default route and DNS are being handled by the client. If the entire system loses connectivity, disable TUN first, then check virtual-machine bridges, container networks, accelerators, and network-filtering modules from security software. Avoid repeatedly switching several capture tools while the system is unstable; that makes the routing table and DNS state harder to diagnose.

Windows-specific issues

After waking from sleep, refresh the subscription status and restart the core before considering a client reinstall. An incorrect system clock can affect TLS connections, so automatic time synchronization should be working. For LAN sharing, enable “Allow LAN connections” in the configuration, bind the listener to an appropriate LAN address, and allow only the required port through the firewall. Other devices should use this computer's LAN address, not 127.0.0.1. Disable the shared entry when finished to avoid exposing a proxy port on an untrusted network.

Before downloading for macOS, check the chip architecture. Open “About This Mac” from the Apple menu. If it shows Apple silicon, choose an Apple Silicon or ARM build; if it shows an Intel processor, choose an x64 build. Available clients include Clash Plus, Clash Verge Rev, FlClash, and the archived ClashX Meta. For a new installation, prefer a maintained client and get the chip-matched file from the macOS download section. With the wrong architecture, the app may not open or may require an additional translation layer.

Installing the app and granting permissions

A common installation method is to open the disk image, drag the app into “Applications,” and launch it from there. Do not run it directly from the disk image long-term, because updates, helper components, and data directories may not be written correctly. If macOS asks for confirmation on first launch, verify the app source and download path, then follow the system's security procedure. System proxy, network-extension, and TUN changes may require administrator credentials because they modify system networking.

After launch, do not enable the system proxy and TUN at the same time. Import a subscription URL from the configuration page, wait for proxy groups and rules to load, set it as current, and choose Rule mode. If an import produces one configuration entry but no proxy groups, the downloaded content may be invalid, the converted subscription may be incompatible, or an old configuration may still be selected. Check the configuration timestamp and client logs instead of repeatedly clicking Update.

What the system proxy covers

The macOS system proxy writes HTTP, HTTPS, or SOCKS settings for the current network service. Browsers and most apps that use the system networking framework read these values, but terminal commands, some development tools, and apps with their own network stack may not. After enabling the system proxy, check “System Settings → Network → Current Network → Details → Proxies” to see whether the entries point to the local port. You generally should not edit these values manually; the client should restore them when the proxy is disabled.

When terminal tools need a proxy, set environment variables for the current session only. Use the client's actual mixed port; the settings disappear automatically when the terminal exits:

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

curl https://example.com

If Git, Homebrew, or another tool has saved a separate proxy address, check its internal configuration too. An old address may take priority over the current environment variables, causing the browser to work while the terminal still fails. Use env | grep -i proxy to inspect the current environment, then check whether the specific tool has saved additional parameters.

TUN, network extensions, and DNS

For apps that ignore the system proxy, use the client's TUN or network-extension mode. First activation usually requires system approval, and some clients install a helper service to adjust routes in the background. If the switch immediately turns off after approval, check network-extension permissions in System Settings, client logs, and the helper-service status. Enterprise devices may be restricted by configuration profiles; ordinary user permissions cannot override organizational policy, so follow the device-management requirements instead of reinstalling repeatedly.

When multiple VPNs, filters, content-inspection tools, or virtual adapters run on macOS, route priorities may compete. Symptoms include a connection that is established but carries no traffic, domains resolving to incorrect addresses, inaccessible LAN devices, or loss of connectivity after wake. First disable other network-capture tools and leave only Clash active; restart the core and check DNS; once it works alone, restore the other software one at a time. This identifies which layer is conflicting.

Sleep, network changes, and local services

When a Mac wakes from sleep or switches between Wi-Fi, Ethernet, and a phone hotspot, its local IP, default route, and DNS may change. If connections remain stuck in an old state, stop and start the core, and if necessary disable and re-enable the system proxy. For local development services, localhost, 127.0.0.1, and LAN ranges should normally be direct. If custom rules send them to a proxy too early, local pages, databases, or LAN devices become unreachable. Place LAN direct rules before general proxy rules.

If every webpage becomes unavailable after quitting the menu-bar client, the system proxy probably was not restored. Restart the client and disable the system proxy, or remove the corresponding entry from the current network service's proxy settings. If only one browser is affected, check its extensions or built-in proxy configuration. Do not save different local ports at both the system and application layers; an update can otherwise leave an obsolete value behind.

Android options include Clash Plus, Clash Meta for Android, FlClash, and Surfboard. Choose a client from the Android download section before installing. Packages may be separated into ARM64, ARM, or universal builds; most recent phones and tablets use ARM64, while older devices may need another architecture. If uncertain, choose the universal build offered on the download page or check the ABI with a system-information tool. An architecture mismatch usually produces an installation error rather than a subscription or network error.

Installation and VPN authorization

Open the downloaded file through Android's installation flow. The system may ask the current browser or file manager for one-time permission to install apps; you can disable that permission afterwards according to your security preferences. When the client first connects, Android displays a VPN connection request. After approval, a VPN indicator usually appears in the status bar. Android generally allows only one VPN service at a time, so another VPN, enterprise tunnel, firewall, or local filtering app may be stopped—or may prevent Clash from connecting.

Mobile platforms do not have the same global system-proxy switch as desktop systems. Clients usually create a virtual interface through the Android VPN API. A Connected status only confirms that the interface was created; also verify the active configuration, Rule mode, and proxy group. Add a subscription by URL from the configuration page, update it, and select that configuration. If downloading the subscription requires an existing network path, perform the initial import on a network where the URL is reachable before starting the proxy.

Per-app proxy and bypass settings

Android clients often support per-app routing, with options such as “Proxy selected apps only” and “Bypass selected apps.” These modes have opposite meanings, so recheck the list after switching. Proxying only a browser is useful for testing, but browser-launched external apps may then follow a different path. When bypassing banking, LAN-control, or VPN-sensitive apps, remember that they will use the current network directly. If “Always-on VPN” or “Block connections without VPN” is enabled, system policy can also affect bypass behavior.

Rule mode and per-app routing are two separate decisions. An app first determines whether its traffic enters the VPN; only then do Clash rules choose DIRECT, PROXY, or REJECT. Once an app is added to the bypass list, changing Clash domain rules will not affect it. When troubleshooting why a rule does not work, first confirm that the app's traffic appears in the client's connection log, then inspect rule order.

Background limits and battery policies

Some Android systems restrict VPN clients when the screen is locked, tasks are cleared, or battery saver is active. The connection may work immediately after launch, disappear after the phone is locked, and return when the app is reopened. In battery and background settings, allow the client to run continuously and exclude it from automatic cleanup. Menu names vary by manufacturer, but the goal is the same: keep the foreground VPN service alive, allow background networking, and prevent the process from being forcibly stopped when the screen turns off.

Automatic subscription updates also depend on background networking. If updates happen only when the app is open, check the update interval, background-data permission, and battery restrictions. Keeping the last known-good configuration is usually safer than deleting it and importing again after an update fails; deleting the only usable configuration may remove the network path needed to retrieve the subscription.

DNS, IPv6, and hotspot sharing

Android Private DNS, the client's built-in DNS, and the carrier's DNS may all participate in resolution. If only some domains fail, temporarily disable Private DNS for comparison, then check enhanced-mode, upstream resolvers, and Fake-IP exclusions in the configuration. Do not change IPv6, Private DNS, the TUN stack, and rules broadly at the same time, or it will be impossible to tell which change mattered. If some apps work while others time out on an IPv6 network, check whether the client captures IPv6 and whether the configuration has suitable rules.

Devices connected to a phone's hotspot do not necessarily use the phone's VPN automatically. Sharing depends on the Android implementation, client capabilities, and routing permissions; normal access on the phone does not prove that hotspot clients are routed the same way. For reliable sharing, install a client separately on each device or use a gateway solution that explicitly supports transparent proxying. If LAN access fails, also check that private address ranges remain direct.

On iPhone and iPad, open the Clash Plus App Store page from the iOS download section; the official client website is clashplus.io. When the first connection is established after installation, iOS asks to add a VPN configuration. After approval, the client can create its network extension. iOS normally keeps only one active VPN at a time, so an existing enterprise VPN, personal VPN, or content filter may replace it or be replaced by it.

Import a subscription and enable the configuration

Copy the subscription URL, then choose Add from URL on the client's configuration or subscription page. Make sure no ellipses, spaces, or line breaks from the chat app are included. Save and update it, confirm that proxy groups and rules appear, then set it as the active configuration. Some subscription links can open the client directly from Safari, but manual pasting makes it easier to verify the complete URL. If no configuration is added after the handoff, return to the app and import by URL, then check for format or network errors.

After starting the connection, begin with Rule mode. Open Safari for a test and watch the client's connection log. If a page does not use the expected policy, check which rule matched the domain instead of repeatedly switching proxy groups. Clash evaluates rules from top to bottom and stops at the first match; later rules cannot override an earlier result. For the differences between DOMAIN, IP-CIDR, GEOSITE, and MATCH, see Clash Custom Rules and Match Order.

On-demand connections and network changes

Clients that support on-demand connections can start the VPN automatically based on network conditions, such as cellular data or a specified Wi-Fi network. Before adding conditions, connect manually and verify that the configuration is stable, then add them gradually. Conditions that are too broad may capture traffic even on a home LAN, while conflicting conditions can cause repeated connect-disconnect cycles. To exclude a trusted Wi-Fi network, use the client's network exception rather than relying on manually switching it off each time.

When switching from Wi-Fi to cellular data, iOS rebuilds the underlying interface, so a brief pause in existing connections is normal. If service does not recover, stop and restart the client instead of deleting the VPN configuration. Airplane Mode, Low Data Mode, and system-level network restrictions can also affect background connections. First verify that the ordinary network works, then start the client so carrier or Wi-Fi problems are not mistaken for subscription issues.

DNS and LAN access

On iOS, a network extension may handle DNS requests, depending on the client and configuration. Fake-IP mode returns reserved addresses first, then restores domain names from its mappings during connection for rule matching. Devices, printers, casting services, and other apps that require real LAN resolution may need Fake-IP exclusions or direct DNS for local domains. Record the original settings before making changes, and add exceptions only for domains with confirmed issues.

When accessing a home router, network storage, or casting device, keep private address ranges and local domains direct. Common private ranges include 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. If an earlier general rule sends them through a proxy, local devices may time out. Re-establish the connection after changing rules so DNS mappings and existing sessions are refreshed.

Background behavior and system limits

iOS manages background tasks centrally, and closing the client UI does not necessarily stop an established VPN network extension. Use the system status bar, Control Center, and the client's connection state to determine whether it is still running. Conversely, swiping the app away from the app switcher may leave the network extension active. To stop it, disable the connection inside the client or disconnect it in the system VPN settings. This avoids mistaking a closed app for a stopped proxy.

If the connection switch turns off immediately, common causes include incomplete VPN authorization, another network extension taking over, a configuration that cannot start the core, or a temporarily unavailable network. Check authorization, other VPNs, the active configuration, and logs in that order. Do not delete every configuration first; startup errors in the log often identify DNS, rules, or configuration-format problems directly. For a fuller iOS walkthrough, see How to Import a Subscription on iPhone.

On Linux desktops, choose Clash Verge Rev or FlClash; servers, routers, and headless systems are better suited to running the mihomo core directly. Download distribution-supported packages from the Linux download section. Check both CPU architecture and package format: Debian, Ubuntu, and derivatives commonly use deb packages, while other distributions may use different package managers. Core archives may distinguish AMD64, ARM64, ARMv7, and MIPS; the wrong architecture will make the executable fail immediately.

Installing a desktop client

For a deb package, use the system software center or run the package-manager command in a terminal. Use the filename from the actual download:

sudo apt install ./clash-client-amd64.deb

After installation, launch the app from the application menu, import the subscription, and choose Rule mode. Linux desktop environments do not handle system proxies uniformly: GNOME, KDE, browsers, terminal tools, and sandboxed apps may read different settings. After the client reports that the system proxy is enabled, confirm the values in desktop network settings and test the browser and command line separately. Flatpak, containers, and remote development environments may use separate network namespaces and will not automatically inherit the host proxy.

Run mihomo directly

On a headless system, create a dedicated directory for mihomo and place the executable and config.yaml inside it. Grant execute permission, then use -d to specify the working directory. The following paths are only clear examples and can be adjusted for your system:

sudo mkdir -p /etc/mihomo
sudo cp mihomo /usr/local/bin/mihomo
sudo chmod +x /usr/local/bin/mihomo
sudo cp config.yaml /etc/mihomo/config.yaml

mihomo -d /etc/mihomo

Foreground execution is best for initial verification because configuration errors appear directly in the terminal. Once the configuration loads, ports listen, and rules and DNS work normally, hand it over to a service manager. Do not daemonize it immediately; otherwise a startup failure can be diagnosed only indirectly from logs. Rule sets, Geo data files, and relative paths referenced by the configuration are resolved from the working directory, so the runtime user must have read access.

Manage the service with systemd

For long-running use, create a systemd service. The service account needs permission to read the configuration and write cache files; enabling TUN also requires the appropriate network capabilities. A minimal service example follows:

[Unit]
Description=mihomo service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=3

[Install]
WantedBy=multi-user.target

Save it as a system service file, then reload the configuration and start the service. Use systemctl status to inspect its state and journalctl to inspect logs. When updating the core, stop the service, replace the file, and start it again so the running process and disk state do not diverge. Subscription updates should likewise generate a complete configuration and pass a syntax check before replacing the active file, preventing an error page or incomplete download from stopping the service.

Proxy environment variables and service scope

A desktop system proxy does not automatically apply to every Shell, SSH session, Docker build, or systemd service. For a temporary command, use environment variables:

export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export all_proxy="socks5h://127.0.0.1:7890"

socks5h sends domain-name resolution through the SOCKS server, reducing mismatches between local DNS and proxy rules. Before setting it permanently, define the scope: a Shell configuration affects that user's sessions; a systemd service environment affects only that service; configuring the Docker daemon affects image pulls. During troubleshooting, check whether variables still point to an old port and remember that case-sensitive variable names may coexist.

TUN, permissions, and firewalls

Linux TUN involves virtual interfaces, policy routing, DNS, and firewall rules. Running with elevated privileges is simple, but long-term deployments should grant only the required capabilities and restrict the service account. If the TUN interface cannot be created, check that the kernel provides the TUN device, the container allows access to it, and the service has network-management capabilities. If the interface exists but carries no traffic, inspect the routing table, policy rules, and firewall forwarding chains.

When exposing mixed-port to other devices on a server, do not bind it to every public interface by default. Bind it to a controlled LAN address and restrict the source with a firewall. Protect the control interface as well; never expose it directly to an untrusted network. For a single desktop, loopback binding is simplest. Enable allow-lan only when LAN sharing is explicitly needed, and verify the access scope.

Button labels vary between clients, but the core concepts remain the same. Understanding ports, modes, proxy groups, rules, DNS, and TUN lets you transfer experience from one platform to another. Subscription configurations usually contain the full structure, so save a copy before editing manually. When a client updates a subscription automatically, direct edits to generated files may be overwritten. For lasting customization, use the client's override, merge, or scripting features and confirm their execution order.

Basic listening and modes

mixed-port accepts HTTP and SOCKS requests on one port, simplifying application setup. allow-lan controls whether other devices can access the listening port; keep it disabled for single-device use. Common mode values are rule, global, and direct. Rule mode routes traffic according to rules; Global mode sends most traffic to a selected proxy group; Direct mode is useful as a temporary network comparison, not as a long-term state after routing rules have been configured.

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

profile:
  store-selected: true
  store-fake-ip: true

store-selected saves proxy-group selections so they do not need to be chosen again after a restart. store-fake-ip saves Fake-IP mappings and reduces mapping changes after restarts. Enable IPv6 according to the current network and subscription. Disabling it does not remove IPv6 from the entire system, and enabling it does not mean every proxy endpoint can carry IPv6 correctly. For dual-stack issues, use connection logs to determine which address family is actually in use.

Rule matching order

Rules are evaluated from top to bottom and stop at the first match. Exact domains generally belong before broader domain suffixes; LAN and required direct rules should come before general proxy rules; and ad-blocking reject rules should precede broad rules that could otherwise capture them. MATCH is the final fallback and normally belongs at the end of the list. The structure below shows a common order:

rules:
  - DOMAIN,router.local,DIRECT
  - DOMAIN-SUFFIX,example.org,PROXY
  - GEOSITE,category-ads-all,REJECT
  - GEOIP,LAN,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

In IP-based rules, no-resolve means not to trigger an additional domain lookup while evaluating the rule. Whether it is needed depends on the preceding domain rules and DNS design. Rule-set providers are also governed by order: even a correct rule set will not work if placed after an overly broad rule. After editing, use connection logs to see the actual match instead of inferring it from rule text.

DNS and Fake-IP

The DNS module controls domain resolution and affects whether domain rules have enough information to match. Fake-IP mode returns a reserved address for a domain; when an app connects to it, the core restores the domain from its mapping and routes the request. This preserves domain information and suits transparent capture. Compatibility issues are more common with LAN domains, device discovery, some games, and apps that require real addresses. Add specific entries to fake-ip-filter instead of disabling DNS capture everywhere.

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

The public resolvers in examples demonstrate standard syntax only. Real configurations should account for reachability from the current network and the subscription's recommendations. Encrypted DNS also requires bootstrap resolution for the resolver's own hostname; otherwise a loop occurs in which the hostname must be resolved before the resolver can be used. When DNS times out, determine whether the listening port is not being captured, the upstream is unreachable, bootstrap resolution failed, rules sent DNS traffic down the wrong path, or multiple system DNS components are overriding one another.

TUN parameters and automatic routing

TUN settings control the virtual interface and route capture. Supported stack options vary by operating system, so clients usually provide adapted defaults. For the first activation, avoid changing the interface name, MTU, DNS hijacking, and route scope all at once. Establish a connection with the client's defaults first, then use logs to address specific issues.

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

auto-route lets the core add required routes automatically, while auto-detect-interface identifies the current outbound interface. When a device has wired, wireless, virtual-machine, and container networks at once, automatic detection may choose the wrong interface; check the routing table. DNS hijacking sends ordinary port-53 requests to the core, but apps using independent encrypted protocols may bypass that port. Even with TUN enabled, retain direct rules for private addresses and essential system services.

Subscription updates and custom configuration

A subscription update retrieves the provider's configuration again. If the client supports overrides, put personal rules, DNS exceptions, and proxy-group changes in the override layer instead of editing generated files directly. After updating, check that the intended configuration remains selected, custom content was merged, and rule sets finished downloading. Do not set the update interval so short that it causes frequent requests, but do not leave updates disabled until the configuration is clearly stale. If an update fails, keep the last successful configuration and retry when the network recovers.

Group large custom rule sets by purpose and record why each was added. More rules do not necessarily work better; duplication and overlap make troubleshooting harder. After each addition, test a specific domain and confirm the match was not intercepted by an earlier rule. For a systematic explanation of rule fields, priority, and fallbacks, continue with Rule Syntax and Priority Explained.

When Clash cannot access the internet, the most effective approach is not to change the client, subscription, DNS, and mode all at once. Check the data path layer by layer: device network → client core → active configuration → system proxy or TUN → DNS → rules → proxy group → proxy endpoint → destination service. Verify only one layer at a time so conclusions remain reproducible. For shorter questions, browse Troubleshooting by category; this chapter focuses on a systematic order that works across platforms.

Step 1: Confirm basic connectivity with Clash disabled

Disable the system proxy, TUN, or mobile VPN, then use the current Wi-Fi, Ethernet, or cellular connection to visit an ordinary website directly. If direct access does not work, fix the router, carrier network, captive-portal login, or system network settings first. Public Wi-Fi often requires web authentication; enabling TUN too early may prevent the login page from appearing. Complete authentication before starting the client.

If connectivity still fails after quitting the client, check for a leftover system proxy. A desktop system may still point to a local port at 127.0.0.1 even though the client has exited, causing every app that reads the system proxy to fail. Restart the client and disable the proxy correctly, or remove it in the operating system network settings. On mobile, check the system VPN status and make sure another network extension is not still connected.

Step 2: Confirm that the core and configuration started

An open client window does not prove that the core is running. Check the status page and logs for configuration loading, listening ports, and startup errors. Common failures include an occupied port, invalid configuration syntax, missing rule-set files, a non-writable data directory, or insufficient TUN permissions. If a log says that an address is already in use, quit other proxy clients or identify the process using the same port. Do not change several ports without synchronizing the system proxy.

Confirm that the active configuration is the newly imported target, not a built-in example or an old file. A subscription entry can exist without being selected, leaving the core to load the previous configuration. If startup fails after an update, switch back to the last known-good configuration to determine whether the new content caused it. YAML is indentation-sensitive; use spaces, keep levels consistent, and avoid tabs or malformed colon structures when editing manually.

Step 3: Distinguish capture failure from endpoint failure

After enabling the system proxy, check whether browser requests appear in the connection log. No records at all means traffic has not entered the client; check whether the system proxy was written, whether the app reads it, and whether the listening ports match. If requests appear but time out, inspect the matched rule, proxy group, and endpoint. With TUN, no records means checking the virtual interface, routes, and permissions first; on mobile, check VPN authorization and the per-app list.

On the same device, compare two setups: disable TUN and test a browser with only the system proxy enabled; then disable the system proxy and test the same destination with only TUN enabled. If the system proxy works but TUN does not, the subscription and most rules are usually fine, so focus on TUN permissions, routing, and DNS. If TUN works but the system proxy does not, inspect system settings, application proxy behavior, and the local port.

Step 4: Check DNS and rule matches

If only domain access fails while a known IP address or the client's built-in connection test works, inspect DNS. Resolution timeouts in the logs may result from an unreachable upstream, failed bootstrap resolution, a port conflict, or DNS traffic not being captured. Temporarily return to the original subscription DNS settings to test whether a custom option is responsible. Do not change multiple resolvers, Fake-IP, Private DNS, and encrypted system DNS settings at once.

If the connection log shows DIRECT when PROXY was expected, inspect the exact matching rule. A broad DOMAIN-SUFFIX, GEOSITE, or regional rule may have matched first. If it shows REJECT, check whether an ad-blocking rule set captured the destination by mistake. If it falls through to MATCH, no more specific rule matched earlier. Reconnect after changing rules; existing long-lived connections will not automatically adopt the new policy.

Step 5: Assess subscription and proxy-endpoint status

If the configuration loads but every proxy request fails, update the subscription once and inspect the returned error. An abnormal HTTP status, empty content, or invalid format indicates a problem during subscription retrieval. After a successful update, compare different proxy-group choices, but do not treat client probe results as real-world speed. A test URL may be restricted by the target network or follow a different route from everyday websites.

If only one destination fails, check its domain rules, protocol support, and the destination service itself. If every destination times out while establishing a connection, the proxy endpoint or current network is more likely blocking traffic. timeout, connection refused, and DNS errors have different meanings and should not all be labeled “node failure.” Use Common Log Fields Explained to assess them individually.

Common symptoms at a glance

Collect enough information, but not too much

When describing an issue to a provider or community, include the operating system, client name, capture method, proxy mode, when the issue began, whether every destination fails, and the first relevant error in the logs. Do not write only “it doesn't work,” and do not paste the complete configuration. Hide subscription URLs, authentication fields, and proxy details. If the issue is reproducible, give the shortest steps, such as “The browser works with TUN off; with TUN on, the connection log is empty.” This is easier to diagnose than pages of unrelated logs.

The info log level is usually sufficient. Increase verbosity temporarily only when tracing complex rules or DNS behavior, then restore it to prevent rapid log growth. Once the issue is resolved, restore custom DNS, rule overrides, startup settings, and other network tools one at a time. Test the connection after each item so the final configuration remains understandable and reversible.

When to reset and when to reinstall

If the configuration is corrupted, the client data directory is not writable, or the settings structure became abnormal after an upgrade, export anything needed and try the client's reset function first. Reinstalling the program does not necessarily remove its data directory, so it is normal for the same issue to remain afterward. Conversely, deleting the data directory removes subscriptions, overrides, and proxy-group choices; keep recovery materials first. Reinstall only after confirming that the program files, helper service, or system component installation is damaged.

After troubleshooting, record the final cause, such as “an old client occupied the mixed port,” “Android background restrictions stopped the VPN,” or “an overly broad direct rule appeared before MATCH.” These notes are more valuable than saving many temporary settings. When moving to another platform, build the smallest working configuration using this handbook's shared logic first, then add platform-specific features to reduce repeated troubleshooting.