Clash for Every Platform: Installation and Configuration Guide

General preparation and client selection

Understand the difference between the client, core, and subscription

Everyday Clash use involves three separate components. The client is the graphical interface with windows, menus, and switches; it handles configuration imports, proxy mode changes, and system permissions. A core such as Mihomo parses the configuration, creates connections, and applies routing rules. A subscription is a configuration endpoint generated by a service provider and usually contains proxy nodes, proxy groups, rules, and DNS settings. Installing a client does not create a usable subscription, and a subscription alone cannot replace a local client. When troubleshooting, identify the affected layer first instead of repeatedly reinstalling everything.

The downloads page lists clients by platform. For everyday desktop and mobile use, Clash Plus is the primary choice. Windows and macOS also offer Clash Verge Rev and FlClash; Windows additionally has Clash Nyanpasu and the discontinued Clash for Windows, while macOS has the discontinued ClashX Meta. Android options include Clash Meta for Android, FlClash, and Surfboard. Linux users mainly choose Clash Verge Rev or FlClash. Servers, software routers, and users who need to orchestrate services directly can download the Mihomo core. A graphical client and a standalone core use different configuration workflows, so do not treat a core archive as a desktop installer.

Confirm system architecture and installation permissions

Before downloading, confirm your operating system version and processor architecture. Most Windows PCs with Intel or AMD processors use x64; Windows on ARM devices need ARM64. Macs with Apple silicon should use an Apple Silicon or ARM64 build, while older Intel Macs need x64. Android packages may be split into arm64, arm, and universal builds; most recent phones and tablets use arm64, while the universal build is the safest choice when you are unsure. On Linux, package format matters as well as architecture: Debian, Ubuntu, and derivatives generally use deb, while Fedora and Rocky Linux use rpm. A compressed core archive requires manual service setup.

Installing a client and enabling traffic routing may both trigger system permission prompts. On desktop systems, the system proxy usually only changes network settings; TUN mode creates a virtual network interface and generally requires administrator privileges. Android and iOS show a VPN authorization prompt, which is the system interface for routing local traffic and does not mean a traditional corporate VPN has been connected. If authorization is denied, the client may still show the configuration as loaded, but application traffic will not pass through the proxy. Return to system settings to restore VPN, network extension, or background permissions instead of importing the subscription again.

Keep the minimum recovery conditions

Before making changes, keep a copy of the last known-good configuration, record the subscription endpoint, and make sure the device clock, time zone, and network connection are correct. Clock drift can break HTTPS certificate validation and appear as failed subscription updates, browser certificate errors, or node handshake failures. Public Wi-Fi may require browser-based sign-in; enabling a global proxy before authentication can prevent the captive portal from appearing. The safest order is to disable the system proxy and TUN, confirm ordinary network access, then import the configuration and enable features one at a time.

For a first setup, change as few variables as possible: keep the default rule mode, import one confirmed working subscription, enable the system proxy, and test a browser. Enable TUN, override DNS, or add custom rules only when needed. Do not change the proxy mode, DNS, port, and rule file at the same time, or it will be difficult to identify the cause of a failure. See the Clash guide for a quick workflow; the following sections explain platform-specific installation details and recovery paths.

Windows: installation, system proxy, and TUN

Download and complete the initial installation

Choose a client from the Windows downloads section. Most computers with Intel or AMD processors should use the x64 installer. Exit any older client before installing to prevent an existing process from holding the mixed port or virtual adapter. If you are migrating from Clash for Windows, do not simply install another client over it. First record the subscription URL, custom rules, and bypass list, then disable the old client’s system proxy and exit it before installing Clash Plus, Clash Verge Rev, FlClash, or Clash Nyanpasu. Client data directories and field extensions are not fully interchangeable, so copying the entire old directory may also bring along stale caches and helper services.

If the installer is blocked, confirm that the file came from the corresponding download link on this site and that its extension is complete, then review the publisher and source in the Windows security prompt. Enterprise- or school-managed devices may restrict driver installation, service creation, or proxy changes; an administrator must handle those restrictions. Portable builds can usually run after extraction, but a TUN service may still require administrator privileges. Use a normal local directory where possible and avoid folders controlled by sync software, which can lock files during configuration updates.

Import a subscription and activate the configuration

Open the client and go to Configuration, Subscriptions, or Profiles. Choose the option to add a URL, paste the complete subscription address, and run an update. A successful download does not mean the configuration is active; you usually must select the newly added profile to make it current. Then open the proxy groups and choose a node for groups that require manual selection, or keep the automatic strategy. If the page shows a profile name but no proxy groups, check the update result and logs. A login page, HTML error page, or empty response cannot be parsed as a YAML configuration.

Do not set the subscription update interval too low. Each update fetches the configuration again, and some clients also reload the core; frequent refreshes do not improve node quality and may trigger server-side limits. Use the interval recommended by the provider and update manually only when an immediate sync is needed. For network, link, and server-side checks, continue with Troubleshooting failed Clash subscription updates.

When the system proxy applies

When “System Proxy” is enabled, the client points Windows HTTP and HTTPS proxy settings to a local listening port. Browsers and desktop apps that honor system proxy settings connect automatically; apps with their own network stack, some Store apps, games, and command-line tools may ignore it. That does not necessarily mean the node is broken—the program may simply not be handing traffic to Clash. A browser works while one particular app connects directly is a typical sign.

An unexpected shutdown or forced exit after enabling the system proxy can leave Windows pointing at a local port. The symptom is that all web access fails after the client closes. Reopen the client and disable the system proxy normally, or go to Windows “Network & Internet — Proxy” and turn off the manual proxy. Do not let multiple proxy tools manage the system proxy at once. The last one started may overwrite the address, while an inconsistent exit order can restore an old value.

TUN mode and virtual adapters

TUN mode receives more types of traffic through a virtual adapter, making it useful for apps that ignore the system proxy. The first time you enable it, allow the client to install or start the required service and approve the administrator prompt. Start by testing with the default route and DNS settings; do not immediately add a third-party accelerator, virtual machine bridge, packet-capture driver, or another VPN. Multiple network filter drivers commonly cause DNS failures, unreachable LAN devices, or loss of connectivity after sleep and wake.

If TUN fails to start, exit the client, run it once as administrator, and check whether the service was created successfully. Then make sure virtual adapters created by Hyper-V, WSL, Docker, or security software are not forcing the default route. If TUN works but a LAN printer or NAS becomes unreachable, keep local subnets direct and check whether strict routing is enabled. Common private address ranges include 192.168.0.0/16, 10.0.0.0/8, and 172.16.0.0/12, but actual rules should match the current LAN configuration.

rules:
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,PROXY

After configuring Windows, test a regular browser, an app that needs TUN, and LAN access in that order. Keep the system proxy enabled only when it is sufficient; enable TUN when UDP, Store apps, or games genuinely need full traffic capture. This reduces conflicts between the virtual adapter and Windows security policies and makes it easier to return to ordinary networking during troubleshooting.

macOS: installation, network extensions, and permissions

Choose the build for your chip

Open the macOS downloads section and check the chip in “About This Mac.” Devices with Apple M-series chips should use an Apple Silicon or ARM64 build; Intel Macs should use x64. Clash Plus is the recommended choice, with Clash Verge Rev and FlClash also available. ClashX Meta is discontinued and is best treated as a migration reference for existing setups rather than a choice for new devices. After downloading, drag the app into Applications and launch it from there so macOS can correctly retain permissions and update state.

If macOS blocks the first launch, open “System Settings — Privacy & Security,” review the recently blocked app, and allow it after confirming its source. Do not remove all system security attributes or permanently disable protection to bypass a one-time prompt. Running an app directly from Downloads or a read-only disk image can prevent helper services and network extensions from installing correctly. Copy it to Applications, quit any older instance, and launch it again.

Subscriptions, the menu bar, and the active profile

macOS clients typically provide both a main window and a menu bar entry. To import a subscription, open Profiles, Configuration, or Subscriptions, create a profile from a URL, and update it. Select the updated profile and confirm the strategy in the proxy groups. A menu bar icon shows runtime status but does not prove that the system proxy is enabled; check the client switch and macOS network settings separately. If multiple clients remain installed, ensure only one launches at login and only one manages the system proxy.

Configuration data may be stored in the user Library directory. When migrating to another Mac, re-import the subscription first and move only rule override files that you explicitly created. Copying every cache file can bring along an old core path, stale helper-service state, and obsolete network interface names. If the subscription includes provider-specific fields, the client’s normal import workflow is usually more reliable than assembling the configuration by hand.

System proxy and network services

After enabling the system proxy, the client changes the Web Proxy and Secure Web Proxy settings for the current network service. When a Mac switches from Wi-Fi to Ethernet, a phone hotspot, or a new network location, the new service may have separate proxy settings and must be checked again. If Safari and other apps cannot connect after the client exits, open “System Settings — Network — Current Connection — Details — Proxies” and check whether the HTTP, HTTPS, or SOCKS proxy still points to the local address. Normally disabling the client’s system proxy switch cleans up these values automatically.

Some command-line programs do not read the system proxy configured through the macOS graphical interface. To temporarily route terminal commands through a local proxy, set environment variables in the current terminal session. The port must match the client’s actual mixed-port or HTTP port. Unset the variables afterward so future commands do not connect to a closed local port.

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

# Clean up after finishing in the current terminal
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

TUN, network extensions, and helper services

When TUN is enabled for the first time, macOS may request an administrator password and ask to add a VPN configuration, network extension, or helper tool. Allow the requested permissions in the system dialogs. If the switch immediately turns itself off, check the extensions in “Privacy & Security” and “Network — VPN & Filters,” then fully quit and reopen the client. After an upgrade or client change, an old helper service may prevent the new one from installing. Use the old client’s service removal function first, then install the new client instead of manually deleting unknown system directories.

If AirDrop, printers, LAN shares, or development devices become unreachable after TUN is enabled, LAN traffic is often being captured incorrectly. First test whether disabling TUN while keeping only the system proxy restores access. If it does, check direct rules for private subnets, automatic route detection, and the DNS hijacking scope. iCloud Private Relay, other VPNs, content filters, and enterprise security software can also affect the path. During troubleshooting, keep only one Clash traffic-capture method enabled.

On macOS, the priority is not repeated reinstallation but keeping the app architecture, current network service, and network extensions in sync. If browsers work but terminal commands do not, check environment variables. If the system proxy works but a specific app does not, consider TUN. If the LAN fails after TUN is enabled, narrow the issue by checking rules and route scope.

Android: installation, VPN authorization, and background operation

Choose a package and allow installation

The Android downloads section offers Clash Plus, Clash Meta for Android, FlClash, and Surfboard. Most recent devices use arm64 packages; older devices may need arm. If you are unsure, use the universal build provided by the client. Open the downloaded APK with the system installer. Android manages “Install unknown apps” permissions by source, so grant temporary permission only to the browser or file manager you are using. Disable that source’s permission after installation; there is no need to enable it for every app.

If Android reports a package-parsing failure, confirm that the file finished downloading, still has the APK extension, and matches the Android version and processor architecture. A signature-mismatch warning usually means a same-name app signed by another source is already installed. Record or export the subscription and custom rules, uninstall the old app, and reinstall it; an overwrite cannot bridge a signature difference. Some manufacturer builds hide installation confirmation below the security-scan page, so read the full system prompt before continuing.

Import a subscription and start the connection

After opening the client, use the Configuration or Subscriptions page to import from a URL, paste the subscription address, and update. Select the imported profile, confirm the strategy in the proxy groups, return to the home screen, and tap Start. Android then shows a system dialog to create a VPN connection; you must allow it. This permission routes device traffic to the local Clash service. If denied, the app may load the configuration but cannot establish a system-wide connection. A key or VPN indicator in the status bar usually means the system tunnel is active.

When copying a subscription link from another app, make sure it does not include leading or trailing spaces, line breaks, or text added by a chat app. If no proxy groups appear after updating, check the HTTP status, parse errors, and configuration path in the logs. Opening the subscription URL in a browser and seeing a login page does not prove that the client can fetch the configuration; some links require special request parameters or have expired. For persistent failures, follow the subscription update troubleshooting workflow.

Per-app routing and bypass settings

Android’s VPN interface can capture traffic from most apps. Clients generally offer either “proxy only selected apps” or “bypass selected apps.” The first is useful when only a few apps should use Clash; the second keeps banking, LAN control, or incompatible apps on a direct connection. The logic is opposite in the two modes. After changing it, stop and restart the connection so the system rebuilds the app scope. System components, work profiles, and cloned apps may use different package names and require separate settings in each user space.

Per-app routing only determines whether traffic enters Clash. Once inside, it still matches the rule mode, proxy groups, and DNS settings. An app included in the VPN can still connect directly if its traffic matches DIRECT; that does not necessarily mean app routing failed. Check the process, domain, matched rule, and final strategy in the connection log. Confirm which layer handled the traffic before changing rules.

Battery optimization, background limits, and network changes

Android manufacturers often impose additional restrictions on background apps. If the connection drops after locking the screen, disappears after clearing recent tasks, or fails to recover after switching between Wi-Fi and mobile data, add the client to the battery-optimization allowlist and permit background activity, autostart, and required foreground-service notifications. The persistent notification keeps the foreground service recognized by the system; disabling its notification channel can undermine long-term stability. Settings names vary by brand, but the goal is to remove power-saving freezes and background network restrictions.

If connectivity briefly fails after switching from Wi-Fi to mobile data, wait for the system network transition to finish, then stop and start the connection once. If only one Wi-Fi network is affected, check for captive-portal authentication, Private DNS, and IPv6 routing differences. Pause Clash, complete public-network authentication, and start it afterward. If Android’s “Always-on VPN” or “Block connections without VPN” is enabled, stopping the client will block all traffic. Check both options while troubleshooting ordinary network access.

Android troubleshooting revolves around four states: whether the profile is active, whether VPN authorization is allowed, whether the target app is included, and whether the system preserves the background service. Confirm them in that order to locate most cases where the interface looks normal but apps cannot connect. There is usually no need to repeatedly clear app data.

iOS and iPadOS: installation, VPN configuration, and on-demand connections

Install the client from the App Store

iPhone and iPad users can open the Clash Plus App Store page from the iOS downloads section; the official website is clashplus.io. After installation, open the app, approve the required network-configuration request, and then add a subscription. iOS manages system network extensions centrally. When the client starts a connection, it requests permission to add a VPN configuration and may require confirmation with the device passcode, Face ID, or Touch ID. Once approved, the configuration appears in the VPN list in Settings.

If the Install button is unavailable, check the device OS version, App Store account status, Screen Time restrictions, and mobile-device-management policies. Organization-managed devices may prohibit users from adding VPN configurations. The client can install but still lack permission to capture traffic. Reinstalling cannot bypass device-management rules; the administrator must change the policy.

Import a subscription and choose a strategy

Open the Configuration or Subscriptions page, add the provider’s URL, update it, and select the new profile. Return to the strategy page and confirm that commonly used proxy groups contain available choices before starting the connection. If the update succeeds but the strategy list is empty, check that the profile is actually active and that the subscription contains proxy groups. iOS sharing can pass a link to the app, but long subscription URLs are safer to copy and paste directly to avoid truncated parameters.

Rule mode suits most situations: rules in the configuration decide whether traffic connects directly or through a proxy. Global mode sends most matching traffic to the selected global proxy group and is useful for short diagnostic tests, but it should not be the permanent answer to every problem. Direct mode pauses proxy logic, although the system VPN icon may remain because the local network extension is still running. Do not judge proxy use from the status-bar icon alone; check the client’s current mode, connection records, and matched strategy.

Conflicts with other VPN configurations and network tools

iOS generally allows only one primary VPN tunnel to capture traffic at a time. If the device also has a corporate VPN, another proxy client, a content filter, or security software, a later connection may replace the earlier one or reclaim traffic through on-demand rules. If Clash connects and immediately disconnects, open “Settings — General — VPN & Device Management — VPN” to see which configuration is actually active, temporarily disable other on-demand connections, and try again.

If the VPN configuration was not removed before deleting an app, an old name may remain in the system list. It usually no longer works but can complicate troubleshooting. When migrating clients, stop the connection, confirm in the system VPN settings that the old profile is disabled, and then add the configuration in the new client. Do not enable on-demand connections for multiple proxy clients, or they may repeatedly compete when Wi-Fi, cellular data, or device unlock state changes.

On-demand connections, LAN access, and cellular data

On-demand connections automatically restore the tunnel after network changes and are useful for long-term operation, but enable them only after manual connections are stable. If a Wi-Fi network requires browser authentication, an automatic connection may prevent the portal from loading. Disable on-demand and the current VPN, complete Wi-Fi authentication, and then restore them. Casting, printers, smart-home devices, and file sharing on a home LAN need direct access to private subnets. If discovery fails, check whether LAN domains or private addresses are being sent through the proxy by mistake.

The client needs cellular-data permission to update subscriptions and connect over mobile networks. If Wi-Fi works but cellular data does not, confirm the client’s permission in cellular settings and then check whether the provider’s nodes support the current carrier network. Low Data Mode and Low Power Mode may reduce background updates but should not normally make a foreground connection completely unavailable. If the issue occurs only in the background, check Background App Refresh and on-demand connections instead of changing node rules.

DNS and connection records

DNS in an iOS network extension is usually handled by the active configuration. If a page says the server cannot be found while a known IP responds, check DNS first. Restore the subscription’s default configuration and temporarily disable extra encrypted-DNS profiles or content filters installed in the system. If the issue disappears, re-enable custom settings one at a time. For isolated domain failures, inspect whether the request was created, which rule matched, and whether the result entered fallback in the connection records. For configuration-level DNS settings, see the “Subscriptions and configuration” section and Clash DNS configuration explained.

iOS does not require manual local proxy-port settings. The main controls are the active profile, system VPN authorization, on-demand connections, and other network extensions. When something fails, first check in Settings which VPN is truly active, then review the mode and logs in the client. Looking only at the connection button on the app’s home screen can hide a replacement by another configuration.

Linux: GUI clients, desktop proxy settings, and core services

Install a graphical client

Desktop Linux users can choose Clash Verge Rev or FlClash from the Linux downloads section. Debian, Ubuntu, Linux Mint, and similar systems generally use deb packages; Fedora, Rocky Linux, openSUSE, and similar systems use rpm when available. Confirm the system architecture first—most desktop computers are amd64. When installing a local deb, let the package manager resolve dependencies instead of invoking only a low-level extraction command.

sudo apt install ./client-package.deb

# Install on rpm-based distributions with the system package manager
sudo dnf install ./client-package.rpm

The filename above only represents the package in the current directory; enter the actual downloaded filename in the terminal. Once the GUI client starts, importing a subscription works much like on Windows and macOS: add a URL on the configuration page, update it, select the active profile, and enable the system proxy or TUN. Tray support differs between Wayland and X11. A missing tray icon does not prove that the core is not running; check the main window, process list, and logs together.

The desktop environment’s system proxy

Desktop environments such as GNOME and KDE can store HTTP, HTTPS, and SOCKS proxy settings, but applications do not all read them the same way. Browsers usually follow the desktop proxy; terminal commands, containers, Snap, and Flatpak apps may use separate environments. After the client enables the system proxy, test with a browser first. If terminal commands still bypass it, set HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY for the current shell, using a port that matches the client’s listening configuration. Do not write temporary proxy variables into the global environment of every system service, or software updates and background tasks will keep using a dead port after the client stops.

If apps still use a proxy after the desktop proxy switch is disabled, check shell startup files, Git configuration, package-manager configuration, and desktop network settings for old values. Linux proxy state is often spread across several locations, and a client can only restore the settings it changed. Open a new terminal to inspect environment variables so an older session does not preserve stale values.

TUN permissions and routing

Linux TUN requires access to /dev/net/tun and permission to modify routes and firewall rules. GUI clients typically perform these operations through a privileged helper service. If the switch fails, check the logs for permission errors, a missing device, or failed nftables/iptables commands. Containers, minimal distributions, and restricted virtual machines may not have a TUN device; the host must provide it. Do not run the desktop as root long-term. Grant only the minimum permissions through the client’s supported service-installation method.

If LAN devices, container bridges, or virtual machines become unreachable after TUN starts, check direct subnets and automatic routing. Docker commonly creates bridge networks such as 172.17.0.0/16, which may overlap with remote networks or private-subnet rules in the configuration. Use the actual output of ip route to determine the bypass scope rather than copying routes from another machine. Firewall tools may overwrite client rules after a reboot; if the issue appears only after restarting, inspect service startup order.

Run the Mihomo core directly

Servers, software routers, and headless systems can run the Mihomo core directly. Download the file matching the architecture, place the executable in a managed directory, prepare a configuration file, and run a configuration check first. The configuration should include at least a listening port, proxies or proxy providers, proxy groups, and rules. If the subscription provider supplies complete YAML, save it as a configuration file. If it supplies only a proxy list, you must add proxy groups and rules yourself. Run the service in the foreground first to confirm that the configuration parses, then hand it over to a service manager.

mkdir -p ~/.config/mihomo
cp config.yaml ~/.config/mihomo/config.yaml
mihomo -t -d ~/.config/mihomo
mihomo -d ~/.config/mihomo

Use -t to validate the configuration before starting the core. Before listening on a LAN address, understand the implications of allow-lan, the bind address, and the firewall. For local-only use, keep the loopback address so the exposure is smaller. To serve LAN devices, open the required port and restrict it to trusted subnets. The control interface should not be exposed to untrusted networks either. Define an explicit working directory, configuration directory, and restart policy in the service manager so the process does not exit when an interactive shell ends.

Subscriptions, proxy modes, rules, and DNS

Subscription import and configuration updates

A subscription URL is a remote configuration endpoint. When the client updates it, content is downloaded and written to the local configuration directory. A successful update normally has three stages: the network request returns valid content, the YAML parses successfully, and the profile becomes active. Even when the interface says “Download complete,” confirm that proxy groups and rules are present. First distinguish request errors from parse errors: timeouts and connection refusals are network-layer issues; 404 and 403 commonly involve the link or authorization; HTML responses and indentation errors are content-layer issues.

Do not refresh the same subscription at high frequency from multiple clients. When moving to another device, you can add the subscription again, but check the provider’s limits on device count and update frequency. A client’s automatic update interval controls configuration fetching; it is not automatic node testing and does not replace proxy-group selection. Local edits may be overwritten by the next remote update. Use the client’s override, script, or merge features for persistent rules instead of editing cache files directly.

Rule, global, and direct modes

Rule mode evaluates rules from top to bottom, and the first match determines the target strategy. Domain rules usually match while the domain is still available; IP rules may require DNS resolution first. Rule order therefore matters: put specific rules before broad ones and use MATCH for traffic that matches nothing else. Global mode bypasses most rule selection and sends traffic to the global proxy group, which helps determine whether rules or the node are responsible. Direct mode tests the underlying network. After diagnosis, return to rule mode so LAN traffic, system updates, and other traffic that should be direct are not routed through the proxy indefinitely.

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

rules:
  - DOMAIN-SUFFIX,example.org,DIRECT
  - DOMAIN-KEYWORD,example,PROXY
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,PROXY

DOMAIN-SUFFIX matches a specified domain and its subdomains, while DOMAIN-KEYWORD has a broader scope and should be used carefully. IP-CIDR matches an address range; combined with no-resolve, it avoids triggering extra DNS resolution just to evaluate an IP rule. MATCH is the catch-all rule and should be placed at the end of the rule list. Strategy names must exactly match proxy-group names; differences in capitalization or spaces can make the configuration fail to load.

Proxy groups and automatic selection

A proxy group determines which node or downstream strategy handles a rule. Common group types include manual selection, latency testing, failover, and load balancing. An automatic test only describes the response from its test address at that moment; it does not represent the quality of every site or protocol. When a specific service fails, switch nodes in the proxy group and use the logs to evaluate the result instead of relying only on ranking. If an upstream group references another group, the final path may contain several selection layers, so expand each layer during troubleshooting.

Node names, proxy-group names, and rule strategies are controlled by the subscription maintainer. A client can provide a selection interface but cannot repair a group name that does not exist in the subscription. For errors such as “proxy group not found,” check that rule references match the current subscription, especially when a local override still points to an old group name. If the subscription stops loading after an update but works when the local override is disabled, the remote group names have probably changed.

DNS, Fake-IP, and fallback

Clash’s DNS module determines which resolver handles domains and supplies domain and IP information for rule matching. Fake-IP mode returns a mapped address for a domain; when an app connects to that address, the core uses the original domain to apply rules. This preserves domain information, but some LAN discovery, games, and apps that require real addresses may not support it and need Fake-IP filters or direct rules. Redir-host follows a more traditional resolution path with different compatibility characteristics. After switching modes, clear system and app DNS caches before testing again.

nameserver is the primary resolver. fallback can provide another set of results under specific conditions, while fallback-filter determines when those results are used. Do not simply pile up many DNS servers. The more parallel sources there are, the harder it is to distinguish poisoning, timeouts, and routing issues. Start with the subscription defaults, confirm that the proxy chain works, and then adjust for the network and use case. See nameserver, fallback, and DNS hijacking explained for syntax and hijacking scope.

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 1.1.1.1
    - 8.8.8.8
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

Ports, LAN access, and log levels

mixed-port accepts both HTTP and SOCKS connections, making it convenient for apps configured manually on the same device. After enabling allow-lan, the bind address and system firewall determine which devices can connect. For local-only use, leaving it disabled is simpler. The info log level is sufficient for everyday use; debug records more diagnostic detail and is useful briefly, but increases log volume. Restore info after troubleshooting and save the key error lines rather than only capturing the words “connection failed.”

Common configuration issues and layered troubleshooting

Establish a repeatable diagnostic order

The most effective way to troubleshoot Clash is not to keep switching settings but to validate each layer. First check the base network: with the system proxy and TUN disabled, can the device reach the local network and ordinary websites? Next check the configuration: did the subscription update, is the active profile selected, and does the proxy group contain usable options? Then check the core for syntax, port, permission, or DNS errors in the logs. Next check traffic capture: does the target app honor the system proxy, or is it included through TUN, Android VPN, or an iOS network extension? Only then investigate nodes and rules.

Change only one condition per test and record the result before and after. For example, if a browser fails in rule mode, switch to global mode while keeping the same node. If global mode works, the node and capture path are probably sound and the rules are the likely issue. If global mode still fails, change the node; if that restores access, inspect the original node. If every node fails, check DNS, subscription status, and the local network. This turns “nothing opens” into testable branches.

The client says it is running, but websites will not open

First confirm that the system proxy address and the client’s listening port match. If mixed-port was changed while the system still points to the old value, the browser will connect to a nonexistent local service. Then inspect the client’s connection records. No new connection means traffic never entered Clash; check the system proxy, the browser’s independent proxy, TUN permissions, or the mobile VPN. A connection with a DNS error points to DNS troubleshooting. A connection that matches a proxy group but times out during the handshake calls for testing another node.

After an abnormal exit, the system may retain proxy settings. On Windows, turn off the manual proxy in system settings; on macOS, clear the proxy settings for the current network service; on Linux, check both the desktop proxy and environment variables. On Android and iOS, check whether the system VPN still points to a stopped profile. Restore ordinary networking, then open the client normally and enable traffic capture again instead of layering new settings on top of stale state.

Subscription update fails or returns empty content

For a timeout, first test whether the current network can reach the subscription service. If updates work only when the proxy is enabled, run the update while an existing working profile is active. A 404 usually means the path is no longer valid; a 403 may involve authorization, access limits, or request requirements, which the provider must confirm. If the response is empty or cannot be parsed, check whether it is actually webpage text. Do not use an account-center URL as a subscription URL, and do not remove parameters from a long link manually.

If automatic updates fail but manual updates work, check background permissions, the update interval, and device sleep state. Mobile power-saving policies can block background requests, while desktop startup may occur before the network is ready. Automatic updates are a convenience feature; if the current local profile still works, do not delete it after one background failure. See Failed subscription updates and automatic update settings for the full workflow.

DNS leaks, resolution failures, and certificate errors

DNS issues often appear as inaccessible domains, different results for the same site on different networks, or rules failing to match by domain. Restore the subscription’s default DNS first, disable extra Private DNS, encrypted-DNS settings, and browser-specific DNS, then test again. If the issue is resolved, re-enable custom settings one at a time. With TUN enabled, also confirm that the DNS hijacking scope and port are not occupied by another program. Seeing a mapped address in Fake-IP mode is expected behavior and is not, by itself, evidence of a leak.

When a browser reports an invalid certificate, do not immediately blame the rules. Check the system date and time zone, then test the same site with Clash disabled. If the error remains, the cause is more likely the system clock, the site certificate, network authentication, or local security software. If it appears only with a particular node, switch nodes and check for connection hijacking. Packet-capture tools, local HTTPS filtering, and enterprise certificates can also alter the certificate chain. See HTTPS certificate errors and their relationship to proxies for detailed diagnosis.

TUN fails to start or cuts off the network

On desktop systems, check administrator permissions, helper services, and virtual adapters first. On Windows, inspect old proxy-tool services and security-software blocks; on macOS, inspect network extensions and VPN & Filters; on Linux, inspect the TUN device, routes, and firewall tools. If enabling TUN cuts off all connectivity, disable TUN and keep the system proxy enabled to test the core and node. If the system proxy works, the basic proxy chain is healthy and the issue is concentrated in the virtual adapter, routing, or DNS hijacking.

When LAN access fails, check direct rules for private subnets. Docker, virtual machines, and remote-work networks may also use overlapping private ranges, so refine the routes based on actual conditions. If connectivity fails after sleep and wake, restart TUN before rebooting the entire device. If it happens after every sleep cycle, check background permissions, whether the helper service resumes with the system, and whether another network tool rewrites routes during wake.

Rules do not take effect and how to read logs

In rule mode, inspect the destination domain, matched rule, and final strategy in the connection records. Rules match from top to bottom. A broad DOMAIN-KEYWORD, GEOIP, or MATCH rule placed too early can prevent later specific rules from ever running. Apps that connect directly to an IP may not match domain rules; QUIC, IPv6, and apps with their own DNS can also take different paths. Confirm the actual request shape in the logs before choosing domain, IP-CIDR, process, or rule-set conditions.

Read log errors together with the surrounding context. Configuration parse errors usually identify a field or line number. A connection timeout means the request was sent but did not finish in time; connection refused means the destination explicitly rejected it or no local service is listening; no such host points to a resolution failure; permission denied calls for checking file, port, or network permissions first. Use Common Clash runtime log errors to map error types to next steps.

After troubleshooting, restore temporary debug logging, global mode, and test DNS to your everyday settings. Make sure only one client manages the system proxy or TUN, and remove unused startup items. A stable setup rarely needs frequent changes: keep one recoverable configuration, know where the subscription came from, and understand the active traffic-capture method to handle most cross-platform differences.