Clash Setup and Configuration
Windows, macOS, Android, iOS, and Linux

01 / PREPARE

General Preparation: Clients, Subscriptions, and Network Boundaries

Understand the difference between the client, core, and subscription

Before installing anything, clarify three concepts that are often confused. The client is the graphical interface you use to import configurations, switch policies, view logs, and control the system proxy. A core such as Mihomo parses the configuration, matches rules, and establishes proxy connections. A subscription is the configuration endpoint provided by a service, usually containing nodes, policy groups, rules, and an update URL. Installing a client does not automatically provide usable nodes, and downloading a core alone does not create a complete desktop interface. Choose a graphical client for ordinary desktops and mobile devices; servers, routers, and automated environments are better suited to running the core directly.

The download page lists software by platform, with Clash Plus shown first for each platform. Windows users can also choose Clash Verge Rev, FlClash, Clash Nyanpasu, or the archived Clash for Windows. macOS users can choose Clash Verge Rev, FlClash, or the archived ClashX Meta. Android users can choose Clash Meta for Android, FlClash, or Surfboard. Linux desktop users can choose Clash Verge Rev or FlClash. Menu names vary slightly between clients, but the workflow is broadly the same: import a subscription, select the configuration, test a node, choose a policy, enable the proxy, and verify the exit connection.

Record the required details and confirm the system architecture

Before downloading, confirm the operating system version and processor architecture. Windows commonly uses x64, while some newer devices use ARM64. Macs with Apple silicon should use an Apple Silicon or ARM build; older Intel Macs should use x64. Android packages may be available for arm64, arm, or universal architectures. Linux users may also need to distinguish Debian-based packages, RPM-based packages, and standalone compressed binaries. With the wrong architecture, an installer may refuse to run or report a format error at startup. If unsure, check About This PC or About This Mac, or use a system command instead of judging by the device’s appearance.

# Windows PowerShell
$env:PROCESSOR_ARCHITECTURE

# macOS
uname -m

# Linux
uname -m
cat /etc/os-release

Also prepare a valid subscription URL, any required login details, and a network that can reach the subscription endpoint. Subscription URLs often contain authentication parameters and should be protected like passwords; do not include them in public screenshots, support posts, or shared logs. If the provider offers a QR code, mobile devices can scan it; desktop clients usually accept a URL pasted from the clipboard. When you receive a local YAML file, use Import Local Configuration rather than Subscription URL, because a local file cannot update automatically from a remote source.

Establish a baseline before installation

Before enabling a proxy, verify that the device clock, browser access, and DNS resolution are working normally. An incorrect system time can cause TLS failures. Existing VPNs, corporate security software, virtual adapters, and other proxy tools may occupy ports or alter routing. Temporarily exit similar network tools, record the existing system proxy settings, and then install the Clash client. If a connection fails, this makes it easier to determine whether the cause is the original network, client takeover, or subscription content instead of troubleshooting several variables at once.

Choosing Between System Proxy and TUN

A system proxy mainly affects browsers and desktop applications that follow the operating system’s proxy settings. It is simple to configure, has a predictable scope, and is the best starting point for a first connection. TUN creates a virtual network interface and captures more traffic at the routing layer, including traffic from applications that ignore system proxy settings, some command-line tools, and games. It requires higher privileges and is more likely to conflict with other VPNs, virtual machines, container networks, or security software. These are not speed settings; they are different ways to capture traffic. Without a specific need, start with the system proxy. Consider TUN only when an application bypasses the system proxy.

02 / WINDOWS

Windows Setup and Configuration: System Proxy, Service Mode, and TUN

Download and complete the initial installation

Windows users can choose Clash Plus from the Windows downloads section, or select Clash Verge Rev, FlClash, or Clash Nyanpasu as needed. Clash for Windows is no longer maintained and is provided only as an archived option for compatibility with older configurations; it is not recommended for long-term use in a new environment. Before downloading, open Settings → System → About to check the system type. Most desktop PCs use x64. If Windows displays a security confirmation, verify the filename and download source, then continue through the normal app installation process.

After installation, launch the client normally once so it can create its configuration directory and basic settings. If the interface does not open, do not immediately enable compatibility mode or reinstall repeatedly. First check Task Manager for an existing process with the same name, exit any background process, and launch the client again. Portable and installed versions may use different data directories. When migrating, do not copy only the executable; use the client’s configuration-directory entry point to locate profiles, logs, and related data.

Import the subscription and activate the configuration

Open the client’s subscription, configuration, or Profiles page, paste the subscription URL into the input field, and start the import. A successful import usually shows a configuration name, update time, and policy groups. Seeing a configuration card does not mean it is active; click the configuration or set it as the current one. Then open the proxy or Proxies page and run a latency test on candidate nodes. A failed latency test does not necessarily mean the subscription should be deleted, because ICMP, TCP probes, and real web connections may use different paths. Select a node and verify it with an actual request.

When a subscription update fails, first check whether the endpoint is still reachable in a browser. If the browser can open it but the client reports an error, check for missing trailing parameters, accidental spaces, and whether the client is incorrectly using the current proxy to update the subscription. Some clients offer a direct-connection update or update-proxy option; test it while the basic network is available. Remote configuration updates can overwrite provider-supplied nodes and rules, so check whether the client supports overrides before making manual changes.

Enable the system proxy and choose a mode

Rule mode is recommended for the first connection. Select an available node or policy group, then turn on the System Proxy switch. The client writes the proxy settings to Windows; the local address is commonly the loopback address, while the port is determined by the current configuration or client settings. Browsers usually detect the new settings immediately, but some running applications need to be restarted. Global mode sends most requests through the selected policy and is useful for briefly checking whether rules are routing incorrectly. Direct mode temporarily bypasses the proxy. After troubleshooting, return to rule mode instead of expanding the proxy scope permanently.

If the system proxy switch appears enabled but the browser still connects directly, open Settings → Network & Internet → Proxy and check whether the manual proxy was written correctly. Also make sure that corporate policies or other software are not immediately overwriting it. Do not enable system proxy controls in multiple clients at the same time; they compete for the same system settings. If the client exits unexpectedly and web access stops completely, Windows may still be pointing to a local port that is no longer listening. Turn off the manual proxy to restore basic connectivity.

Service mode and TUN permissions

TUN on Windows usually requires administrator privileges or a background service installed by the client. Service mode allows the core or network component to run with controlled permissions; it is not a node service. After the service is installed and TUN is enabled, Windows creates a virtual network adapter and adds the required routes. Security software may ask for permission the first time; allow the client to communicate on the network types it needs. If service installation fails, exit older client versions, make sure no stale service with the same name remains, and run the client’s built-in service installation action as administrator.

Windows-specific troubleshooting

Store apps, command-line programs, and some games do not necessarily follow the system proxy. If a regular browser connects but one application does not, first determine whether that application reads WinINET or system proxy settings. If it does not, consider TUN rather than changing subscription rules. If only devices on the local network cannot reach the proxy on this computer, check Allow LAN connections, Windows Firewall inbound rules, and the listening address. Opening a LAN listener allows devices on the same network to connect to that port, so enable it only when necessary.

For HTTPS certificate errors, first check the Windows date and time zone, the browser’s certificate details, and whether packet-capture or filtering software is running. See HTTPS Certificate Error Troubleshooting for additional guidance. The proxy protocol itself generally does not require users to install certificates from random web pages. If the issue occurs in only one browser, clear that browser’s proxy extensions and network policies before treating it as a system-wide problem.

03 / MACOS

macOS Setup and Configuration: Chip Architecture, System Extensions, and Proxy Permissions

Choose an Apple Silicon or Intel build

macOS users can start with Clash Plus or choose Clash Verge Rev or FlClash. ClashX Meta is no longer maintained and is mainly useful for compatibility with existing setups. Open the Apple menu in the top-left corner and choose About This Mac. If the chip is an Apple M-series model, choose an Apple Silicon or ARM build; if it says Intel, choose an x64 build. You can also run uname -m in Terminal: arm64 indicates Apple silicon, while x86_64 indicates Intel.

After downloading, drag the app to the Applications folder and launch it from there. Running it long-term from a disk image or the Downloads folder can make updates, permission records, and data paths unreliable. macOS performs a security check the first time it opens an app downloaded from the internet; locate the app in Finder and follow the system prompt. Do not lower system security globally just to bypass the prompt. Apple silicon can run an incorrectly selected x64 build through its compatibility layer, but network extensions, performance, and helper components may differ. Prefer a build that matches the hardware.

Import subscriptions and use the menu bar

After launching, open the Profiles, configuration, or subscription page, paste the subscription URL, save it, and select the imported configuration. macOS clients often provide both a main window and a menu bar entry, with system proxy, operating mode, and current policy available from the menu bar icon. After importing, confirm that the current configuration name has changed, then choose a node in the policy group. If the menu bar icon remains after closing the main window, the client is usually still running in the background. To quit completely, use the Quit command in the menu rather than clicking the window’s close button.

When a subscription contains multiple policy groups, start with Node Selection or a similarly named manual-selection group, then check whether automatic-selection and failover groups reference the correct nodes. Rules ultimately target policy-group names, not necessarily individual servers. If a website behaves unexpectedly, inspect the matched rule and policy in the connection log instead of repeatedly switching the node shown on the home screen.

Writing and restoring the system proxy

When system proxy is enabled, the client changes the web proxy settings for the current network service. macOS maintains separate configurations for Wi-Fi, wired networks, and other services, so confirm that the new service is being managed after switching networks. Open System Settings → Network → the current network → Details → Proxies to view web and secure web proxy states. Normally, the client should manage these fields. Do not let the client write one set of ports while manually entering another.

If Safari and other applications lose network access after the client crashes, exit any leftover processes first, then remove the obsolete local proxy from the system network proxy page. You can also use a command to inspect a specific network service, but service names vary by language and user changes. List the names first, then query the desired one:

networksetup -listallnetworkservices
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"

curl, package managers, and development tools in Terminal do not necessarily read the graphical system proxy consistently. Some tools use the HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY environment variables, while others have their own proxy settings. If graphical apps work but terminal commands connect directly, first check the tool’s proxy behavior. Consider TUN when more processes need coverage, but do not use environment variables and TUN as permanent overlapping solutions without documenting where each setting comes from.

TUN, network extensions, and system authorization

When TUN is enabled, macOS may request an administrator password, VPN configuration approval, or permission for a network extension. Complete the authorization from the system prompt; it generally needs to be done only once. You can then check the status in VPN and network-related system settings. With TUN active, the client receives routed traffic through a virtual interface, so Docker Desktop, virtual machines, corporate VPNs, network filters, and local development subnets may be affected. If an intranet or LAN service becomes unreachable, check that private addresses remain direct in the rules and that automatic TUN routing has not overridden a dedicated route.

DNS and connection problems after sleep

macOS maintains a system DNS cache, and browsers may use their own secure DNS. After changing the Clash DNS configuration, if old results are still being used, fully quit the browser and reconnect to the network. Flush the system cache only after confirming that caching is the cause. If a node tests successfully but web pages fail after waking from sleep, common causes include a virtual interface that did not recover, a system proxy still pointing to an old process, or a changed upstream DNS address. Follow this sequence: disable traffic takeover, confirm direct access, restart the client, and re-enable takeover. This helps identify the failing layer.

04 / ANDROID

Android Setup and Configuration: VPN Authorization, Background Operation, and App Routing

Install the client and complete the initial authorization

Android users can start with Clash Plus or choose Clash Meta for Android, FlClash, or Surfboard. Select an arm64, arm, or universal build that matches the device architecture. Most recent mainstream devices use arm64, but the Android version alone is not enough to determine this. A device-information app or system hardware details can provide the correct ABI. If installation fails, check that the file downloaded completely, that the architecture matches, and that the current browser or file manager is allowed to install apps.

When the client starts for the first time and you enable a connection, Android displays a VPN connection request. This grants the local virtual network interface permission to pass app traffic to the client. After approval, a VPN indicator usually appears in the status bar. Android generally allows only one conventional VPN connection at a time, so a corporate VPN, another proxy client, or Always-on VPN may compete with Clash. If a connection cannot be established, check the current VPN owner in system settings instead of repeatedly tapping Start.

Import subscriptions by URL, file, or QR code

On the configuration page, paste a subscription URL, select a local configuration file, or use the QR-code entry point. A QR code may contain a complete subscription URL, so protect the imported configuration in the same way. After a remote subscription imports successfully, select it and wait for the core to load. If YAML parsing fails, the remote server may have returned a login page, error page, or incompatible content rather than configuration data. Open the subscription endpoint in a browser first to confirm that the response is actually configuration data.

Mobile data and Wi-Fi may use different IPv6, DNS, and access policies. If an update fails on one network but works on another, test the subscription endpoint and node connection separately instead of assuming the client is broken. Some subscriptions require regular updates. Use the explicit manual update action on the configuration page and check the update time and error message. If node names change after an update, a manually selected policy may revert to its default, so review the policy group again.

Rule mode, global mode, and app routing

Android should also start with rule mode. Select a node, start the VPN, and verify the exit connection in a browser. Global mode is useful for briefly checking whether a rule is causing a direct connection; return to rule mode afterward. App routing lets you choose which apps use the proxy and which bypass it, but clients may use opposite semantics: proxy only selected apps or exclude selected apps. Confirm the active mode before saving so that apps requiring the proxy are not accidentally added to the bypass list.

App routing determines only whether traffic enters the client. Once inside, the traffic still matches domain, IP, and policy rules. If an app accesses public APIs, LAN devices, and push services at the same time, proxying the entire app can cause login problems. A safer approach is to let the app use rule mode first, then add specific domain rules based on the connection log. Banking, payment, LAN control, and carrier services often depend more heavily on the local network; choose direct rules according to actual access requirements.

Background restrictions and system-reclaimed connections

Android manufacturers often impose battery restrictions on background apps. If the VPN indicator disappears, notifications are cleared, or the connection needs to be restarted after the screen has been locked for a few minutes, check battery optimization, background activity, auto-start, and notification permissions for the client. Setting the app to Unrestricted may improve its ability to remain active, but it can increase battery use. Adjust only the options required by the device. The persistent notification is part of the foreground-service status; disabling notifications may affect how the system manages the service.

When switching from Wi-Fi to mobile data, the original connection’s source address and route change. The client usually rebuilds the connection automatically, but some long-lived connections still require the app to reconnect. If only one or two apps become stuck after switching networks, force-stop those apps and reopen them. If all traffic fails, restart the client connection. Frequent automatic disconnects also warrant checking battery saver, data saver, and the manufacturer’s sleeping-app list.

Private DNS, IPv6, and hotspot sharing

Android Private DNS uses encrypted resolution and may create a second resolution path alongside the client’s DNS interception or fake-ip setup. If domain resolution fails, or the browser works while other apps do not, temporarily set Private DNS to Automatic for comparison. After confirming a conflict, decide whether to keep system Private DNS or let Clash handle resolution consistently. IPv6 should likewise be enabled or disabled based on node, carrier, and configuration support; simply turning it off is not a long-term fix. Use logs to determine whether failed requests used IPv4 or IPv6.

When sharing a phone’s hotspot, downstream traffic does not necessarily pass through the Android device’s VPN automatically. Hotspot traffic capture depends on the system implementation, client capabilities, and device permissions. If other devices need a proxy, the clearer approach is to allow LAN connections in the client and have downstream devices enter the phone’s LAN address and proxy port manually, limiting this to trusted networks. Without a specific sharing requirement, keep LAN listening disabled to reduce exposure.

05 / IOS

iOS Setup and Configuration: App Store, VPN Configuration, and On-Demand Connections

Get the app from the App Store and review system permissions

iPhone and iPad users can get Clash Plus from the App Store. When establishing the first connection, iOS asks to add a VPN configuration and completes authorization with the device passcode, biometric authentication, or a system confirmation. Only after authorization can the client create a local network tunnel and process traffic. The permission is managed by iOS and can be reviewed under Settings → General → VPN & Device Management or the VPN settings for the current iOS version. On school- or company-managed devices, policy may restrict adding VPN configurations; check the device policy first.

iOS allows only one primary VPN configuration to be active at a time. Other VPNs, enterprise security clients, content filters, or Private Relay-like features may alter the actual path. If the connection drops immediately after you tap Connect, check the system VPN page for conflicting configurations, then read the client’s error message. Resetting all network settings also affects Wi-Fi and other configurations, so it should not be the first troubleshooting step.

Import a subscription and select the active configuration

Open the configuration or subscription entry in the client, paste the URL provided by the service, or scan a QR code. If the link was copied from a chat app, check for line breaks, leading or trailing spaces, or truncated query parameters. After importing, select the configuration and choose a node on the policy page. Some clients load the configuration automatically after import, but they do not automatically choose every manual policy group for you. Before connecting for the first time, check at least the primary node group and the final fallback policy.

When importing YAML from the Files app, the file may be stored in iCloud Drive or local storage. If it has not finished downloading from the cloud, the client may be unable to read it. Confirm that it opens in Files before sharing or importing it. Remote subscriptions and local files update differently: a remote subscription can request new data from its upstream source, while a local file must be re-imported after editing. Do not edit node fields generated by a subscription directly; the next update will usually overwrite those changes.

Connecting, rule mode, and on-demand startup

After selecting a configuration and node, enable the connection. The status bar or Control Center will show the VPN status. First use Safari to visit a familiar site, then check other apps. Rule mode decides whether traffic connects directly or through the proxy according to the configuration rules. Global mode can help briefly isolate a rule problem, while Direct mode verifies the underlying network without a proxy. If Safari works but one app fails, check whether that app’s domains matched a reject rule, direct route, or unsuitable policy group instead of merely switching servers.

On-demand connections can start the VPN automatically when the network changes, but conditions that are too broad keep it connected on every Wi-Fi and mobile network; conditions that are too narrow may fail to trigger after a network switch. During initial setup, connect manually first and confirm that the subscription, node, and DNS work. Then configure on-demand rules. If the VPN should be disabled on a trusted home network, add an exception based on the network identifier and periodically verify that it still matches after the router is renamed.

iOS network changes and background behavior

iOS manages background activity according to battery level, network state, and system scheduling. An established VPN tunnel is maintained by the system network extension, which is not the same as an ordinary app remaining in the foreground. If the connection drops frequently after the screen locks, check the stop reason in the client log, Low Power Mode, and recent network changes. Switching between mobile data and Wi-Fi can interrupt existing TCP connections because the source address changes; reopening the affected app usually creates a new connection.

Some Wi-Fi networks require web-based authentication first. If the VPN starts automatically on such a network, the login page may not appear. Temporarily disconnect the client, open any non-encrypted web page to trigger authentication, complete the login, and reconnect. Hotels, airports, and public networks may also restrict particular protocols. If a node works on mobile data but all nodes fail on public Wi-Fi, investigate network restrictions instead of repeatedly deleting the configuration.

DNS, LAN access, and push services

iOS apps may access LAN devices, system push services, and region-specific endpoints. Rules should keep private addresses and local domains direct so that network storage, printers, and smart devices are not sent through a remote proxy. The first time an app accesses the LAN, iOS may request Local Network permission. If denied, the client may still reach the internet while LAN discovery and sharing fail. Review the permission again in the system privacy settings.

If notifications are delayed while web access works, check the policy matched by push-related connections, node stability, and system notification settings. Do not switch to global mode solely because push is unreliable; global mode changes the exit path for more applications. For DNS issues, compare the same domain in Safari, inside the app, and on different networks. For guidance on resolution exits and fake-ip behavior, see Detecting and Fixing Clash DNS Leaks.

06 / LINUX

Linux Setup and Configuration: Desktop Clients, Core Services, and Permissions

Choosing between a desktop client and a standalone core

Linux desktop users can choose Clash Verge Rev or FlClash from the Linux downloads section. They provide subscription management, policy switching, and log views for everyday desktop use. Servers, software routers, and headless devices can run the Mihomo core directly, but you must manage configuration files, startup arguments, permissions, and the service lifecycle yourself. Do not run both approaches while listening on the same ports, or startup failures and traffic reaching the wrong process may result.

The package must match the distribution. Debian, Ubuntu, and derivatives generally use deb packages; RPM-based distributions use rpm packages; standalone archives require manually placing the executable and managing dependencies. Confirm the processor architecture with uname -m: x86_64 corresponds to AMD64 and aarch64 to ARM64. Router devices may also use ARMv7 or MIPS variants. A common error after choosing the wrong build is cannot execute binary file.

System proxy in desktop environments

GNOME, KDE, and other desktop environments store system proxy settings differently, so a client’s System Proxy switch may not cover every environment. After enabling it, check the desktop network settings to ensure HTTP, HTTPS, and SOCKS proxies point to the client’s listening port. Browsers may read the desktop proxy or use their own settings, while terminal programs often rely on environment variables. If a graphical app works but a command-line tool fails, first determine which proxy settings that tool reads.

# Applies only to the current terminal session; the port must match the client’s actual listening port
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891

# Restore after testing
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

When both uppercase and lowercase forms of a variable exist, tools may read them in different orders. Do not place temporary test variables in every shell startup file, or package managers and development tools will continue pointing to a dead port after the client closes. For persistent settings, create separate enable and disable scripts and document where the port value comes from.

Run Mihomo as a service

A standalone core usually uses -d to specify the configuration directory and -f to specify the configuration file. Before the first run, verify file permissions and the working directory, especially under systemd, where the service user’s home directory, relative paths, and interactive terminal differ. Use a dedicated directory for configuration and runtime data, and grant the service user only the required read and write permissions. Do not run every function permanently with maximum privileges; only operations such as creating a TUN interface or writing routes need additional capabilities.

# Test the configuration in the foreground, then hand it to the service manager after confirming that the logs contain no parsing errors
mihomo -d /etc/mihomo -f /etc/mihomo/config.yaml

# Check the listening port
ss -lntup | grep -E '7890|7891|9090'

A systemd service should define an explicit start command, restart policy, and working directory. After updating the configuration, validate it in the foreground or with a standalone command before restarting the service; otherwise a bad configuration may cause a restart loop. View logs through the service manager or write them to a file according to the client settings. If the control interface must listen on the LAN, configure access control and restrict the source in the firewall. For local administration only, listening on the loopback address is safer.

TUN, routing, and DNS permissions

Linux TUN requires /dev/net/tun to exist and the process to have permission to create interfaces and modify routes. In containers, restricted VPS environments, and some NAS systems, the device may not be mapped, so creation can fail even as administrator. After enabling automatic routing, check the default route, policy-routing tables, and firewall rules. Ensure that local networks, remote administration endpoints, and the proxy server’s own traffic do not re-enter TUN and create a loop.

DNS interception depends on firewall and routing capabilities. Different systems may use nftables, iptables, systemd-resolved, or NetworkManager. Do not let multiple components repeatedly rewrite /etc/resolv.conf. If the system uses systemd-resolved, use its interface to confirm the actual upstream server; if NetworkManager manages DNS, adjust the connection profile there. Record the current DNS state before making changes, and confirm that system resolution recovers after the client is stopped.

Common Linux startup and permission issues

If a graphical client will not start, run it from a terminal to see missing-library, display-server, or sandbox messages. Tray support may differ between Wayland and X11. After closing the window, confirm whether the process remains in the background. If the core reports that a port is already in use, use ss or lsof to identify the process instead of changing every port; browsers, environment variables, and LAN devices may still reference the old value. If the configuration directory is read-only, fix its owner and permissions rather than making the entire directory writable by every user.

07 / CONFIGURATION

General Configuration and Rule-Based Routing: Ports, DNS, Policy Groups, and TUN

Understand the configuration execution order

A Clash configuration typically includes listeners, proxy nodes, proxy groups, rule providers, rules, DNS, and TUN. Node definitions describe connection parameters, policy groups decide how to choose among nodes or other policies, and rules send requests to a policy group. Troubleshoot in this order: DNS resolution → rule matching → policy-group selection → node connection. A node with normal latency does not prove that the DNS and rule paths are correct; likewise, a request matching a proxy rule does not guarantee that the selected node works.

YAML uses indentation to express hierarchy. Use spaces and keep indentation consistent at the same level. Add a space after colons, and quote text containing special characters when necessary. Node passwords, subscription parameters, and control-interface secrets are sensitive; remove them before sharing logs or configuration snippets. When a subscription file is maintained upstream, direct edits to its body may disappear after an update. Prefer the client’s override, script extension, or local-rule merge features.

Listening ports and LAN access

mixed-port accepts HTTP and SOCKS requests on the same port, which is convenient for ordinary desktop use. Setting port and socks-port separately makes protocol-specific management easier. allow-lan controls whether LAN devices can connect to the listening port; when disabled, the port is generally available only locally. For sharing, also check bind-address, the system firewall, and router isolation settings. LAN proxying has no automatic discovery, so downstream devices still need the LAN address and port of the device running Clash.

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

external-controller: 127.0.0.1:9090

The external control interface lets graphical clients or management tools read status; it is not a regular proxy port. For local administration only, bind it to the loopback address. If remote management is genuinely required, configure access control and restrict the source in the firewall instead of exposing control capabilities to an untrusted network. After changing ports, update system proxy settings, browser extensions, terminal environment variables, and LAN devices together.

Rule mode and matching priority

Rules are usually evaluated from top to bottom, and the first match determines the policy. A final fallback rule handles requests not covered earlier. Domain rules suit stable site ranges, IP rules depend on resolution results, and process rules are limited by the platform and permissions. An overly broad rule near the top can hide more precise rules below it. For example, a rule for an entire top-level domain may prevent a later direct rule for one subdomain from ever matching.

rules:
  - DOMAIN-SUFFIX,example.org,PROXY
  - DOMAIN,printer.lan,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,FINAL

The PROXY and FINAL names in the example must correspond to policy groups that actually exist. no-resolve prevents an extra domain lookup when matching an IP range and is useful for private-address rules. A real configuration should also include loopback, link-local, and other networks that need direct access. For a complete explanation of domain, IP, and process rule syntax and ordering, see Clash Custom Rule Syntax and Priority.

How policy groups choose a route

A manual-selection group lets you choose a node. An URL-test group selects according to probe results. A fallback group switches through its choices in order when the current option is unavailable. A load-balancing group distributes connections according to its configured strategy. Automated test results reflect only the specified test URL and the moment of probing; they do not represent the real experience on every website. Frequent probes also increase battery use and network requests on mobile devices, so choose an interval that fits the use case.

Policy groups can reference other policy groups, creating layers such as region selection → automatic selection → specific node. Changing the outermost policy does not determine the exit by itself; the inner result still matters. When troubleshooting an unexpected exit, expand the current selection layer by layer and check which node the connection log ultimately used. Renaming a policy group can break rule references. If an update causes logs to report a missing policy, check whether the upstream provider renamed the group.

DNS fake-ip and redir-host

fake-ip mode returns reserved addresses for domains and maintains the domain mapping in the core, preserving domain information for later connections and generally enabling more complete rule matching. Some LAN devices, games, time synchronization services, and applications that require real IP addresses may not work well with fake-ip; add those domains to the filter list so they receive real addresses. redir-host follows a more traditional resolution path, but may lose domain context in some traffic-capture scenarios. Choose based on application compatibility and logs rather than treating either mode as universally faster.

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

The public resolver addresses in examples are for illustrating structure only. Choose actual resolvers based on the network, privacy requirements, and reachability. If encrypted DNS is enabled, the bootstrap DNS used to resolve the resolver’s hostname must also work; otherwise a dependency loop can occur. A browser’s own secure DNS may bypass the system resolution path. When checking DNS egress, compare browser settings, system queries, and client logs separately.

Key TUN configuration options

TUN centers on the virtual interface, automatic routing, and DNS takeover. Field support varies between core versions and clients, so follow the configuration generated or documented by the current client. With auto-route enabled, the core writes routes. strict-route enforces stronger routing constraints but is more likely to affect LANs, virtual machines, and multi-interface systems. Mobile clients usually manage these options through their interface; do not modify both interface switches and the underlying YAML unless you understand how they are merged.

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

Confirm that the system proxy path works before enabling TUN, then test TUN separately. If enabling it breaks the network, turn TUN off immediately and verify direct access, then check permissions, the default route, DNS interception, and other VPNs. For the scope of virtual-adapter traffic capture and platform permission differences, see Clash TUN Mode and System-Wide Traffic Capture.

08 / TROUBLESHOOTING

Common Configuration Issues: Troubleshooting Subscriptions, Nodes, DNS, and Routing

Establish a layered troubleshooting order

Troubleshoot Clash from the outside in. Layer one is the basic network: with system proxy and TUN disabled, can the device reach the local network and subscription endpoint? Layer two is client status: did the configuration load, is the core running, and is the port listening? Layer three is the node connection: can the target be reached, and are the authentication and protocol parameters valid? Layer four is rules and policies: which rule matched, which policy group was used, and which node was ultimately selected? Layer five is DNS and system routing: is resolution following the expected path, and are the virtual interface and default route conflicting?

Change one variable at a time and record the result. Repeatedly switching nodes, modes, DNS, and TUN changes several layers at once; even if connectivity returns, the real cause remains unclear. Keep three comparison results: direct access with takeover disabled, rule mode with system proxy, and rule mode with TUN. These comparisons quickly show whether the issue is in the basic network, application proxying, or route takeover.

Subscription import fails or no nodes appear after import

When subscription import fails, open the endpoint in a browser and confirm that it does not redirect to a login page, error page, or CAPTCHA. Check that the URL is complete, has not expired, was not truncated by a chat app, and that the device time is correct. An HTTP status error in the client log usually points first to subscription access. A YAML parsing error means you should confirm that the response is actually a compatible configuration. Saving an HTML page and renaming it to YAML does not convert its format.

If the import succeeds but no nodes appear, the configuration may contain only rules, nodes may be loaded later by a provider, or the upstream response may be empty. Inspect proxies, proxy-providers, and the client log, and confirm that the provider URL is reachable. If nodes exist but a policy group is empty, check whether its filter expression excludes every node and whether the referenced names match the provider. If the issue began after a remote update, compare the policy-group structure with the last working configuration.

Node tests fail but web access sometimes works

Latency tests usually visit a preset URL and are affected by the test address, DNS, node exit, and restrictions at the destination. A failed test does not necessarily mean every connection fails, and a successful test does not guarantee that a specific service works. Select the node, access the real target, and inspect the connection log. If all nodes fail at once, suspect subscription parameters, the basic network, system time, or the client core. If only a few nodes fail, investigate those nodes individually.

If the same node works on mobile data but not on Wi-Fi, the network path or DNS behavior differs. Compare the target server’s resolution results, IPv4 and IPv6 reachability, and whether the public network restricts the relevant protocol. Do not rapidly repeat node tests in an attempt to restore connectivity; this increases concurrent requests and may trigger upstream limits.

The system proxy causes a complete loss of connectivity

First confirm that the client core is still running and listening on the port entered in the system proxy settings. If the client has exited but the system retains a manual proxy, every application that follows the system proxy will connect to a nonexistent local service. Turn off the system proxy or clear the manual address in system settings to restore access. If the port is listening, switch to Direct mode. If Direct works but rule mode does not, focus on rules and policies. If Direct also fails, check the port type, authentication settings, and local firewall.

If the browser works but command-line tools do not, check whether those tools read the system proxy or environment variables. For a single failing application, check whether it bypasses the proxy, uses QUIC, pins its own DNS, or requires TUN. An application that ignores the system proxy does not mean the entire client is broken.

LAN or all network access fails after enabling TUN

Turn off TUN immediately, confirm that basic connectivity returns, and check whether the virtual interface was removed and the default route restored. If LAN access fails, inspect direct rules for private addresses, automatic-route exclusions, and multi-interface priorities. If all network access fails, focus on administrator permissions, the TUN device, DNS interception, and conflicts with other VPNs. On Linux, also check the firewall and policy routing. On Windows, check service mode and the virtual adapter. On macOS and mobile devices, check the system VPN configuration.

TUN failures on a remote server are more dangerous because an incorrect route can cut off administration. Preserve a direct route for the management source in advance, and use a console or backup session for recovery. When running inside a container, confirm that the host mapped the TUN device and granted the required network capabilities. Without those conditions, use an explicit proxy port instead of forcing TUN.

Domain resolution errors, abnormal DNS egress, or fake-ip conflicts

Compare the same domain in a browser, a system query tool, and the client log. If the browser differs, check its secure DNS. If system resolution works but an app fails, check the app’s cache and independent resolver settings. If every query fails, verify that Clash DNS is enabled, that the upstream is reachable, and that bootstrap DNS is not creating a loop. A fake-ip address in system query results is not automatically an error; it may be normal enhanced-mode behavior. The key question is whether the core correctly restores the original domain for the subsequent connection.

If LAN domains, printers, casting, or some games are incompatible with fake-ip, add the specific domains to the filter list and keep private addresses direct. Do not filter every domain, or fake-ip loses its main purpose. After editing the configuration, make the application resolve again; restart the affected app if necessary instead of merely refreshing the page.

HTTPS certificate errors and system time

If several websites simultaneously report that a certificate is not yet valid, has expired, or has an unusual issuer, first check the system date, time zone, and automatic time synchronization. If only one browser is affected, check its extensions, independent proxy, and certificate cache. If the issue appears only after enabling a network-filtering tool, disable intermediary components one layer at a time to identify which layer changed the connection. Do not overlook a public Wi-Fi login page, which may redirect requests to an authentication portal and produce a hostname mismatch.

The certificate details for the target domain, issuer, and validity period help distinguish clock errors, network authentication, and intermediary interference. For the complete process, see Troubleshooting Proxy Chains, System Time, and Certificate Trust.

Reading logs and recovery strategy

During troubleshooting, the info log level is usually sufficient; use debug only briefly because it generates a large amount of data. Focus on configuration parsing errors, DNS queries, matched rules, policy groups, connection targets, and low-level network errors. Remove subscription URLs, node credentials, device addresses, and browsing records before sharing logs. timeout means the operation timed out but does not identify whether DNS, routing, or the server caused it. connection refused means the destination rejected the connection or no process is listening. no such host points more strongly to resolution failure. permission denied indicates a permissions issue.

If repeated changes leave the state unclear, export necessary local rules and settings, disable system proxy and TUN, quit the client, confirm that direct access works again, then restart and import only one known-good configuration. Do not delete all application data at the start; logs, old configurations, and setting differences are valuable evidence. To rebuild a basic connection quickly, follow the Quick Start path. To switch clients or download an installer again, use the all-platform downloads page and choose a version matching the system and architecture.