Clash Installation and Setup Guide for All Platforms

General preparation before installation

Identify the platform, architecture, and client type first

Clash is not a single installer. It is a toolchain made up of a proxy core, a graphical client, configuration files, and routing data. Most desktop and mobile users need a graphical client; servers, software routers, and container environments may run the Mihomo core directly. The graphical client handles subscription management, policy switching, log viewing, and system permissions, while the core parses configuration, listens on local ports, matches rules, and forwards connections. Distinguishing these two types of software before downloading helps prevent installing a command-line-only core as if it were a desktop application.

Platform identification does not stop at Windows, macOS, or Linux; you also need to confirm the processor architecture. Most standard Windows PCs use x64, while devices with processors such as Qualcomm ARM chips require ARM64. Apple Silicon Macs use macOS ARM64 packages, and Intel Macs use x64 packages. Android packages commonly come in arm64, arm, and universal variants. Recent devices generally use arm64; choose universal if you are unsure. On Linux, check the package format as well: Debian, Ubuntu, and derivatives usually use deb, while Fedora and openSUSE commonly use rpm.

Prepare a subscription URL and a stable network

The client itself does not include usable proxy nodes. Before the first setup, obtain a Clash- or Mihomo-compatible subscription URL generated by your service provider, or a complete YAML configuration file. Subscription URLs usually contain access credentials, so protect them like passwords—do not include them in screenshots, public logs, shell history, or public code repositories. If the provider offers several formats, choose one explicitly labeled Clash, Mihomo, or Meta. Whether a generic share link can be imported depends on the client's built-in format conversion support.

Before importing, use your current network to confirm that the subscription URL is reachable. If the browser cannot open it, the client will usually be unable to update it either. An authenticated subscription may return YAML text instead of a webpage, which is normal. A login page, HTML error page, or blank response indicates a problem with the URL, permissions, or network. Company, campus, and public networks may restrict certain connections, so complete the initial installation on a stable home network or mobile hotspot before testing on the target network.

Understand configurations, subscriptions, and overrides

A subscription is the source of a remote configuration; the configuration file is what the client actually loads; an override changes local fields without modifying the remote subscription. Many graphical clients cache subscriptions, so a successful import does not mean every startup fetches the remote URL in real time—the update button usually triggers a fresh request. Changes made directly to cached subscription YAML may be overwritten at the next update. For persistent port, DNS, or routing changes, use the client's override, merge-configuration, or scripting features, and export the original configuration before editing.

A minimal configuration needs at least a listening port, proxy nodes or proxy providers, policy groups, and rules. These fields reference one another: rules point to policy groups, and policy groups select specific nodes. Any mismatch in spelling can make loading fail. If you plan to maintain YAML manually, read Understanding the Clash Configuration File Structure first. YAML uses spaces for indentation; tabs cannot be mixed in, and items under the same list must use consistent indentation.

Record a recoverable baseline

Before installation, record the system's existing proxy settings, DNS settings, and VPN software state. On Windows, check “Settings → Network & Internet → Proxy”; on macOS, check “Details → Proxies” for the active network service; on mobile devices, confirm whether another VPN configuration is already present. Running Clash alongside another VPN, network filter, packet-capture tool, parental-control service, or corporate security product can cause conflicts over routing tables, virtual adapters, or system proxy settings. During initial troubleshooting, keep only one network-intercepting tool enabled, then restore other software one item at a time once the connection is stable.

Downloads are centralized on the client page. Clash Plus is the recommended graphical client for Windows, macOS, Android, and iOS. On the Linux desktop, consider Clash Verge Rev or FlClash; for servers and routers, consider the Mihomo core. The discontinued Clash for Windows and ClashX Meta are suitable only for migrating existing environments or maintaining compatibility with legacy configurations, not for new long-term deployments.

Windows download, installation, and system integration

Download the installer and complete the first launch

Windows users should choose Clash Plus first, or select Clash Verge Rev, FlClash, or Clash Nyanpasu based on interface preferences. In the Windows download section, confirm the device architecture before downloading the full installer. Almost all Intel and AMD PCs use x64. Choose ARM only when the system information explicitly reports ARM64. Keep the default installation path where possible, and avoid placing the program in a cloud-synced folder, temporary directory, or directory with restrictive permissions.

If Windows displays a User Account Control prompt during installation, verify the source before allowing it. On first launch, Windows Firewall may ask whether the client can communicate. Grant access as appropriate for trusted networks; declining usually does not prevent local access to the proxy through the loopback address, but LAN sharing, external control, and some TUN features may be restricted. After installation, open the main client window. Do not enable startup at login immediately—first confirm that the configuration and traffic-interception method work correctly.

Import a subscription and verify configuration status

On the configuration or subscription page, choose import from URL, paste the subscription URL, and save it. After the client finishes fetching it, you should see the configuration name, policy groups, and node list. If only an empty configuration appears or the import button does nothing, inspect the logs for HTTP status, timeouts, certificate errors, and YAML parsing details. When importing a local file, select the complete YAML file rather than an HTML page saved by the browser. After the configuration loads successfully, set it as active and choose a policy on the proxy-group page.

For the first test, select a specific node in the main policy group instead of immediately using auto-select or load balancing. This removes health checks and policy switching as sources of uncertainty. Clients often provide latency tests, but those results reflect only the test endpoint and do not guarantee that every website will work. After testing, open the logs and confirm that ordinary web requests produce rule matches and connection records.

Enabling system proxy and understanding ports

Windows system proxy works well for browsers, chat applications, and most desktop software that follows WinINET or system proxy settings. When you enable “System Proxy” in the client, Windows generally points HTTP and HTTPS traffic to a local listening address. A common address is 127.0.0.1; the port comes from mixed-port, port, or the client settings. System proxy is only a pointer to a local port—the Clash core still performs the actual rule matching.

If the browser works but command-line tools fail, the problem is often that the program does not read the Windows system proxy rather than an issue with the node. PowerShell, Git, package managers, and developer tools may need proxy environment variables or application-specific settings. Conversely, a browser extension with its own proxy can bypass system settings. During troubleshooting, disable browser proxy extensions first, then verify that the system proxy address matches the port the client is actually listening on.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
curl.exe https://example.com

Remove-Item Env:HTTP_PROXY
Remove-Item Env:HTTPS_PROXY

The PowerShell setting above applies only to the current terminal session, and the port must be replaced with the mixed proxy port shown by the client. Session-level variables are safer for short tests because they stop affecting other programs when the window closes. To configure Git separately, use Git's own settings and remove them when no longer needed, so commands do not continue pointing to a local port after the client has closed.

TUN mode, service mode, and permissions

Applications that ignore system proxy settings, some store apps, and programs that need UDP handling can use TUN mode. TUN creates a virtual network interface and changes routes, so it usually requires administrator privileges or a service component. Some clients offer “service mode,” allowing a background service to handle privileged operations instead of requesting administrator approval at every launch. After installing the service, restart the client, verify that the service is healthy, and then enable TUN. If the virtual adapter cannot be created, check for other VPNs, virtual-machine network components, or older network-filter drivers.

Enabling TUN does not mean every connection must use the proxy. Rule mode still decides whether traffic is direct, proxied, or blocked based on domains, IPs, processes, or rule sets. If a LAN printer, NAS, or remote desktop becomes inaccessible, check private-address rules and route exclusions instead of switching straight to global mode. Common private ranges should remain direct; corporate environments may use custom internal ranges that need additional direct rules.

Startup, sleep recovery, and shutdown order

Enable startup at login only after subscription updates, system proxy, and TUN all work correctly. If the client offers separate options such as “Start silently,” “Enable system proxy after startup,” or “Enable TUN after startup,” turn them on in stages. First let the client start without automatically taking over traffic and observe one reboot; then enable automatic proxying. This prevents a brief post-login outage when the system points traffic to a local port before the service is ready.

After Windows wakes from sleep or switches networks, old connections and DNS caches may remain. If access does not return, disable system proxy or TUN, wait for the client to refresh its network state, and then enable it again. Before exiting, use the client's exit command so it can restore system proxy settings. Force-ending the process in Task Manager may leave the proxy address behind. If all webpages stop working after the client exits, open the system proxy settings, disable the manual proxy, then restart the client.

macOS installation, permissions, and network extensions

Choose an Apple Silicon or Intel package

On macOS, first identify the processor architecture. Open the Apple menu in the top-left corner and choose “About This Mac.” If the chip is an Apple M-series processor, choose an Apple Silicon or ARM64 package; if the processor is Intel, choose an x64 package. Clash Plus is recommended, with Clash Verge Rev and FlClash also available. The download entry is in the macOS client section. With the wrong architecture, the app may not launch or may rely on translation with additional compatibility issues.

A common installation method is to open the disk image, drag the app to the “Applications” folder, and launch it from there. Do not run it permanently from the disk image: the mounted path can change, making login items, updates, and permission records unreliable. If macOS blocks the first launch, open “System Settings → Privacy & Security,” verify the app name, and allow it. Avoid moving the app repeatedly; macOS treats different paths as different authorization targets.

Import a subscription and grant required permissions

Add the remote subscription on the client's configuration page, update it, and set it as the active configuration. Then choose a node in the policy group and verify the connection through logs or a webpage. The system may request an administrator password when proxying, TUN, or a network extension is enabled, and may ask to approve a VPN configuration. These dialogs come from the operating system; after approving them, return to the client and confirm the switch state rather than relying only on the dialog disappearing.

If the client provides a menu bar icon, use it for quick changes to system proxy and mode, but complete complex configuration in the main window. A missing menu bar icon does not necessarily mean the process has exited; macOS may have hidden it or the app may be running only in the background. Use Activity Monitor to verify the process instead of launching multiple instances. Multiple instances listening on the same port will cause the later core to report that the port is already in use.

System proxy and separate network services

macOS stores proxy settings per network service, so Wi-Fi, Ethernet, and Personal Hotspot may each have separate configurations. When the client enables system proxy, it usually modifies the active service, but switching networks may restore another proxy state. If Wi-Fi works but Ethernet does not, check the active service under “System Settings → Network” instead of only restarting the client. A corporate configuration profile may also lock proxy settings; ordinary applications cannot override it and must follow the device-management policy.

System proxy mainly affects applications that follow CFNetwork or system network settings. Terminal tools such as curl, SSH, Homebrew, and some developer tools do not automatically use the proxy configured in a graphical interface. You can temporarily export environment variables in the current terminal to test:

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
curl -I https://example.com

unset HTTP_PROXY
unset HTTPS_PROXY

The port must match the client's current mixed port. If terminal tests succeed but a graphical app fails, check whether the app uses a separate network extension, has cached old DNS data, or explicitly disables system proxy. If the graphical app works but the terminal fails, first check environment variables, shell startup files, and the application's own proxy settings.

TUN, DNS, and conflicting network extensions

TUN is useful when more applications and UDP traffic need to be intercepted. Enabling it installs or invokes a network extension and changes system routes. macOS may also be running a firewall, content filter, corporate VPN, virtual-machine bridge, or another proxy, and their processing order can affect connectivity. Before enabling TUN for the first time, temporarily quit other traffic-interception tools and check “System Settings → Network → VPN & Filters” for duplicate configurations.

If TUN can reach IP addresses but cannot resolve domains, inspect DNS requests in the client logs and confirm that the configured DNS servers are reachable on the current network. If LAN names depend on a router or internal corporate DNS, sending every query to public DNS can break internal name resolution. Add a separate nameserver-policy for internal domains, or let those domains and private addresses use local resolution.

Login items, exit behavior, and post-upgrade checks

For startup at login, use the client's own option and verify it under “System Settings → General → Login Items.” Do not add the same startup item through multiple tools, or two instances may launch. If a network extension stops working after a system upgrade, first check that the app permissions and background items are still allowed, then reinstall the service component if necessary. Deleting the app does not always clear system proxy settings, so disable system proxy and TUN and exit normally from the client before removing it.

Android installation, VPN permissions, and background operation

Choose a package and complete installation

On Android, Clash Plus is the preferred choice; Clash Meta for Android, FlClash, and Surfboard are also available. In the Android download section, choose a package that matches the device architecture. Most recent phones and tablets use arm64; older devices may use arm. Choose universal if you cannot confirm the architecture, though the file is usually larger. A mismatched architecture may produce an immediate installation error or cause the app to fail at startup.

When downloading an app package through a browser, Android may require “Allow from this source” for the current browser or file manager. This permission only allows that specific app to start installations; it does not permanently allow every source. Turn it off after installation if desired. If Android reports a conflict with an existing app, the usual causes are a different signature or the same package name. Export the old client's configuration before deciding whether to uninstall it, so subscriptions and overrides are not lost together.

Import a subscription and create the VPN connection

After opening the client, import the subscription by URL on the configuration page and select it after the update completes. On the proxy or policy page, assign a node to the main policy group. When you tap Start on the home screen, Android displays a VPN connection request; approve it, and a VPN indicator usually appears in the status bar. This permission creates a local virtual network interface that sends app traffic into the Clash core. It does not mean a usable node has been selected; access still depends on the configuration, policy, and DNS.

If the connection stops immediately after you tap Start, check the client logs first. Common causes include a configuration parse failure, a local port conflict, VPN permission held by another app, or background-start restrictions. Android generally permits only one conventional VPN connection at a time. Other VPNs, ad blockers, corporate security clients, and some firewalls may replace or conflict with Clash. Disable other VPNs during testing and authorize the connection again.

Per-app proxying, bypass rules, and local networks

Android clients typically support per-app proxying: you can proxy only selected apps or exclude selected apps from the VPN. Proxy-only mode is useful when you know exactly which apps need interception; bypass mode is better when most apps should be covered except banking, LAN, or corporate apps. System components call one another, and an app may use the system downloader, WebView, or an external browser. A list that is too narrow can therefore leave the main interface working while login or downloads fail.

To reach routers, casting devices, printers, and NAS systems, allow LAN access and keep private addresses on a direct route. Some Android versions offer “Block connections without VPN.” When enabled, the system drops all traffic that does not enter the VPN, which can conflict with per-app bypass rules or LAN access. If problems appear only after enabling this option, turn it off to verify the cause, then adjust Clash routing and bypass rules.

Battery optimization and background persistence

Mobile operating systems restrict apps when the screen is off, the battery is low, or the app has been in the background for a long time. The usual symptom is a connection that works immediately after launch, breaks after the screen has been locked, and returns when the client is reopened. In battery settings, set the client to unrestricted and allow background activity; also allow autostart in the manufacturer's startup manager. Settings differ by brand, but the principle is the same: the client process and VPN service must not be killed when the screen turns off.

Continuous TUN/VPN operation consumes some additional battery, depending on network quality, DNS requests, health-check frequency, and the number of active connections. Do not enable multiple duplicate scheduled updates or high-frequency latency checks just to keep the app alive. Set a reasonable subscription update interval, and avoid probing large numbers of nodes too often. When battery use is abnormal, check Android's battery statistics and the client logs to determine whether sustained network activity or repeated VPN restarts are responsible.

Mobile data, Wi-Fi, and Private DNS

Switching from Wi-Fi to mobile data breaks existing TCP and UDP connections, so the client must rebuild its tunnels. If connectivity does not return after a short wait, stop and restart the VPN instead of repeatedly importing the subscription. Android's Private DNS uses encrypted DNS, and its processing order can differ from Clash DNS interception. If some domains fail to resolve, temporarily set Private DNS to Automatic for comparison, then decide whether the system or Clash should handle DNS based on the configuration.

iOS installation, VPN configuration, and on-demand connections

Install Clash Plus from the App Store

iPhone and iPad use Clash Plus. The download page provides an App Store entry and lists the official site clashplus.io for verifying app details. After installation, open the app, read the system permission explanation, and go to the configuration page. Network interception on iOS relies on Network Extension. The first time the app starts proxying, it requests permission to add a VPN configuration and asks you to confirm with the device passcode, Face ID, or Touch ID.

The VPN status in system settings indicates whether the network extension has been established; it does not guarantee that the configured nodes work. After installation, complete these steps in order: import the subscription, select the configuration, choose a policy-group node, and test the connection. If you only approve the VPN without loading a valid configuration, the app may disconnect immediately or remain connected without a usable policy.

Import subscriptions and update configurations

On the configuration page, choose Add via URL and paste a Clash- or Mihomo-compatible subscription URL. After a successful update, confirm that the configuration contains policy groups and rules, then set it as active. iOS may show a privacy prompt when the clipboard is accessed; this is normal when pasting a subscription URL. There is no need to keep the URL on the clipboard afterward. If tapping a subscription link in Safari opens the app, verify which app opened and check the configuration name to avoid importing the same subscription twice.

When a subscription update fails, first open the same URL in Safari. If Safari also cannot access it, check the network, URL validity, and service status. If Safari works but the app fails, check for escaped characters in the URL, required request headers, and the status code in the client logs. Export important overrides before updating an existing configuration because a remote update may replace generated nodes and policy groups.

Policy modes, LAN access, and cellular networks

For the first connection, use rule mode and select a specific node for the main policy group. Global mode sends many services and local connections that should be direct through one policy, so it is not suitable for long-term troubleshooting. In rule mode, domains and addresses are matched in order, and unmatched traffic is handled by the final rule. To reach home devices, ensure private addresses, LAN domains, and Bonjour-related traffic are not accidentally proxied.

After switching from Wi-Fi to cellular data, the system rebuilds the underlying connection. The network extension usually recovers automatically, but long-lived connections may need to be reopened by the app. If the status bar still shows VPN while the network is unavailable, stop the connection in Clash Plus, wait for the VPN indicator to disappear, and start it again. Repeatedly toggling Airplane Mode can hide the real issue and makes it harder to distinguish a network switch from a DNS or node problem.

On-demand connections and background limits

On-demand connections can establish a VPN automatically when the network changes and are suitable once the configuration is stable. Do not enable them immediately during initial installation: a bad configuration may reconnect automatically after every network change, making troubleshooting harder. First test Wi-Fi, cellular data, lock, and wake manually, then enable on-demand rules if needed. If home Wi-Fi, work Wi-Fi, and mobile data need different treatment, define the network conditions explicitly instead of relying on one broad rule.

iOS background behavior is managed by the system, and keeping the app open cannot prevent every disconnection. Stability mainly depends on the network extension, system resources, configuration complexity, and network changes. Frequent health checks increase background activity, while complex scripts and oversized rule sets lengthen configuration load times. When the system terminates a connection, reduce unnecessary probing first and check the logs for memory, configuration parsing, or network-change events.

Interaction with other VPN configurations

A device can store multiple VPN configurations, but usually only one primary tunnel is active at a time. Device management, content filters, DNS apps, and other proxy tools may compete for network-extension resources. If Clash Plus cannot start, open “Settings → General → VPN & Device Management” and inspect the current configuration, but do not delete corporate management profiles casually. On a personal device, disable other VPNs for comparison; on a managed device, follow the organization's policy.

Linux desktop, command line, and service deployment

Choose the right package format for a desktop client

Linux desktop users can choose Clash Verge Rev or FlClash. Debian, Ubuntu, Linux Mint, and derivatives generally use deb packages; Fedora, Rocky Linux, and openSUSE environments typically use rpm when supported by the distribution. Some clients may also offer a standalone format. Before opening the Linux download section, run uname -m to confirm the architecture. Output x86_64 generally means AMD64, while aarch64 means ARM64.

uname -m
cat /etc/os-release

sudo apt install ./clash-client-amd64.deb
# When using an rpm-based distribution, install the rpm file with the corresponding package manager

Replace the filename in the example with the file you actually downloaded. Installing a local package through the package manager handles desktop entries and dependencies more reliably than extracting and copying files directly. If no menu icon appears after installation, launch the client once from a terminal and inspect the error output. Wayland and X11 can differ in tray icons, permission prompts, and autostart behavior. An invisible tray icon does not prove that the core is not running; check the process, ports, and logs together.

Import configurations and configure the desktop system proxy

The graphical client's subscription workflow is similar across desktop platforms: add a remote URL, update the configuration, set it as active, choose a policy, and enable system proxy. Linux does not have one universal system-proxy interface. GNOME, KDE, browsers, terminals, and background services may each read different settings. The desktop toggle mainly affects apps that follow the desktop environment's proxy configuration; command-line programs and systemd services usually do not read it automatically.

For terminal testing, set environment variables temporarily. Defining both uppercase and lowercase names improves compatibility with more tools, but confirm each program's behavior before making a permanent change. Do not place proxy variables in the global environment for every user; when the client is not running, many commands will fail because they point to a dead local port.

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY=$http_proxy
export HTTPS_PROXY=$https_proxy

curl -I https://example.com

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY

SSH does not automatically use Clash just because HTTP proxy variables are set. Git HTTPS remotes may read environment variables, while SSH remotes need a separate ProxyCommand or TUN routing. Package managers may also have their own proxy configuration files. Troubleshoot one application at a time; a working browser does not prove that every Linux process is being intercepted.

TUN permissions, routing, and DNS

Linux TUN requires access to /dev/net/tun and permission to modify routes, policy routing, or firewall rules. A graphical client may use an authorization helper, while a command-line core needs appropriate capabilities or must be started by a controlled service. Running the entire desktop client as root indefinitely is not ideal. Prefer the client's service mode or grant the core only the minimum permissions it needs.

Containers, virtual machines, Docker bridges, and local Kubernetes create additional networks. With automatic routing enabled, failing to exclude these ranges correctly can break container-to-host access, image pulls, or cluster-internal traffic. Record ip route before enabling TUN and compare the routing table if problems appear. Configure LAN ranges, container networks, and VPN-specific networks for direct access or exclusion according to the environment.

ip route
ip rule
ss -lntup | grep -E '7890|9090'
resolvectl status

Different distributions may use systemd-resolved, NetworkManager, traditional resolv.conf, or another DNS manager. Clash DNS interception must work with the current resolution chain. If /etc/resolv.conf points to a local stub and Clash sends queries back to that same address, a loop may result. Persistent DNS timeouts, rising CPU usage, or repeated requests in the logs indicate that you should verify whether the upstream nameserver ultimately points to a reachable, real DNS server.

Running the Mihomo core as a service

A server or router without a desktop environment can run the Mihomo core directly. The configuration directory should contain the main configuration and required routing data, and the service user must be able to read them. Before starting, use the core's configuration-check capability to verify that the YAML parses, then hand it over to systemd. Define an explicit working directory, configuration path, restart policy, and log output instead of launching from a temporary directory.

mihomo -t -d /etc/mihomo
mihomo -d /etc/mihomo

When deploying as a service, do not expose control and proxy ports to every network interface by default. For local-only use, bind them to the loopback address. If LAN access is required, configure allow-lan, the listen address, firewall rules, and authentication for the control interface. Any remotely exposed control interface should restrict source addresses and use an access secret. After changing the configuration, validate it before reloading the service, and keep the previous known-good configuration for quick rollback.

Differences between autostart and graphical sessions

Desktop-client autostart usually depends on the user's graphical session, while a systemd service runs during system boot. Do not start the same core instance through both methods, or they will compete for the port and configuration directory. For desktop-only proxying, use the client's login startup option. To provide stable service for the whole host or LAN, use a separate core service and let the graphical interface act only as a controller. Stop the service and back up the configuration before upgrading; after the upgrade, test compatibility in the foreground before restoring autostart.

System proxy, rule mode, global mode, and TUN

What each of the four concepts does

System proxy, TUN, rule mode, and global mode operate at different layers. System proxy and TUN determine “which traffic enters Clash,” while rule mode and global mode determine “how that traffic is handled.” System proxy uses the operating system's proxy settings to direct proxy-aware apps to a local listening port. TUN uses a virtual network interface and routes to intercept more connections. Once traffic reaches the core, rule mode chooses direct, proxy, or blocked handling from the rule list; global mode sends most connections to one selected policy.

Understanding these two layers prevents common misdiagnoses. If the browser produces no traffic logs, the connection may not have entered Clash, so check system proxy or TUN. If logs show a connection but the result is unexpected, check rules, policy groups, and nodes. Switching to global mode can change only traffic that has already entered the core; it cannot suddenly intercept a program that ignores system proxy settings.

Why rules are matched in order

Clash rules are generally checked from top to bottom. Matching stops at the first applicable rule, so specific rules should come before broad ones, with MATCH as the final fallback. Domain rules, rule sets, IP ranges, and process rules can coexist, but whether DNS is resolved and whether IP matching is skipped affects both performance and results. When a website uses the wrong policy, take its domain, destination address, and matched rule from the logs and trace them back through the configuration instead of blindly adding duplicates.

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

In the example, the more specific domain-suffix rule appears before the keyword rule, private addresses are explicitly sent direct, and MATCH ultimately hands traffic to the PROXY policy group. In an actual configuration, the policy-group name must exactly match the definition under proxy-groups. no-resolve means that matching this IP rule does not trigger an additional domain resolution; it does not disable the entire DNS module.

A policy group is not the same as a node list

A node describes connection parameters, while a policy group chooses among multiple nodes or other policies. A select group is chosen manually; a url-test group chooses based on test results; a fallback group switches according to availability; and a load-balance group distributes connections by algorithm. For daily troubleshooting, fix one node in a select group first because automatic policies can change results as health checks run. Once the fixed node is stable, verify that the automatic group's test URL, interval, and tolerance are sensible.

Policy groups can reference other policy groups. A common structure has business rules pointing to groups such as “International,” “Streaming,” or “Downloads”; those groups reference regional groups, which ultimately select nodes. With deep nesting, the choice shown in the interface may not be the final node. Trace the reference chain layer by layer and confirm that every group has a usable exit. For the relationship between projects and cores, see How Projects Relate Across the Clash Open-Source Ecosystem.

DNS interception, Fake IP, and real addresses

The DNS module does more than translate domains into addresses; it may also participate in rule decisions and traffic mapping. Fake IP mode returns reserved addresses first, then the core restores the original domain through its mapping. This improves rule matching and reduces opportunities for applications to bypass the proxy themselves. Some apps that rely on LAN discovery, hard-coded DNS, special validation, or the returned address itself may not work with Fake IP. Add them to a filter list or compare with redir-host mode.

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

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

This snippet demonstrates the field structure; it does not include nodes, policy groups, or rules and is therefore not a complete, independently usable configuration. The listen address is restricted to the local machine, making it suitable for learning the fields. In real deployments, choose upstream DNS according to reachability, privacy requirements, and internal name resolution rather than copying it mechanically. If the network does not support IPv6 but the configuration prefers IPv6 results, a domain may resolve while connections time out; check the system network, DNS responses, and Clash IPv6 settings together.

Choosing an everyday operating mode

For a desktop work environment, start with rule mode plus system proxy: the scope is clear and exit recovery is simple. When command-line tools, UDP, or proxy-unaware apps need to be handled, use rule mode plus TUN. Mobile devices generally intercept traffic through the system VPN interface, which is effectively similar to TUN, while rules still determine the exit. Global mode is useful for checking whether a node can establish a connection, but it is not the final solution to every problem.

Configuration maintenance and common troubleshooting

First identify the layer where the failure occurs

Effective troubleshooting narrows the scope layer by layer. First check whether the client is running, the core has started, and a port is listening. Next check whether traffic is entering Clash. Then verify that the expected rule and policy are matched, followed by node connectivity. Finally investigate restrictions involving the target website, DNS, or application protocol. Do not replace the client, subscription, DNS, and mode all at once when a webpage fails; even if it recovers, you will not know the real cause.

Check whether the client home page shows an active configuration, then inspect the logs. With no access records at all, focus on system proxy, TUN, VPN permissions, and application-specific proxy settings. If records exist but the wrong rule is shown, check rule order and policy groups. If the correct node is matched but the connection times out, test other nodes and another network. Only when one domain fails should you investigate DNS, domain rules, and the target service.

Subscription update failures and configuration load failures

Subscription updates usually fail because of a network error, an HTTP error, or a content-parsing error. A timeout or connection refusal means the URL is unreachable; an authentication or permission error requires checking the subscription status; HTML instead of YAML commonly indicates a login page, gateway interception, or an erroneous redirect. A browser's ability to open the URL does not guarantee identical request conditions in the client, but it can rule out spelling and basic network issues. When copying the URL, avoid leading or trailing spaces, line breaks, and escape characters inserted by chat applications.

Configuration parse errors usually include a line number or field name in the logs. Common YAML problems include incorrect indentation, a missing space after a colon, duplicate keys, misplaced list markers, and references to nonexistent policy groups. When an error appears, inspect upward from the reported line because the actual indentation mistake may be several lines earlier. Restore the most recent working configuration first, then add changes back in small increments.

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

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

In this structure, PROXY referenced by rules matches the policy-group name. If you rename it, update the rules as well. Names containing special characters can be quoted in YAML, but every reference must still match exactly. For a systematic explanation of the fields, read Understanding the Configuration File Structure.

Port conflicts and a core that will not start

After starting, the core listens on mixed-proxy, HTTP, SOCKS, DNS, or control ports. If another Clash instance, an old process, or another proxy already uses one of these ports, the new instance will fail to start. On Windows, inspect listening ports in Resource Monitor or from the command line; on macOS and Linux, use lsof or ss. Identify the process before stopping it—never terminate an unfamiliar system service blindly. Close the old client or assign the current configuration an unused port.

# macOS
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux
ss -lntp | grep 7890

If no port conflict exists but the core still will not start, check configuration-file permissions, the working directory, the presence of routing databases, and whether the core path used by the client is valid. Security software quarantining the core, service-permission changes after a system upgrade, and moving the app can produce the same symptom. When the graphical interface shows only “Startup failed,” open detailed logs or launch the client from a terminal to capture the complete error.

Browser works, but the terminal or an app does not

A working browser shows that the node and at least one proxy entry are usable, but it does not prove that the terminal is intercepted. Terminal programs may ignore system proxy settings and need environment variables or application-level configuration. Games and some store apps may use UDP or direct sockets and require TUN. The browser may also have an independent proxy extension, meaning it might not be using Clash's system proxy at all. Compare the logs to confirm that each test request appears.

Check the terminal startup files for stale proxy variables. If they still point to a closed client's port, commands will continue to fail. On Windows, inspect PowerShell environment variables; on macOS and Linux, inspect shell configuration files and the current session. Git, npm, and package managers may also store their own proxy settings. For a detailed decision path, see Troubleshooting an Ineffective System Proxy.

IP addresses work, but domains fail

This symptom usually points to DNS. First check whether Clash DNS is enabled, whether its listening port is available, and whether upstream servers are reachable. In TUN mode, also verify that DNS hijacking works and that system queries are not looping. If only internal domains fail, public DNS does not know the organization's or home's internal records; preserve local resolution for those domains. If only certain apps fail, check Fake IP compatibility and filter rules.

Clearing the system DNS cache only removes old records; it cannot fix an incorrect upstream server or rule. Do not treat repeated cache flushing as the main solution. For comparison, temporarily disable Clash DNS and let the system handle resolution. If that immediately works, inspect enhanced-mode, nameserver, fallback, nameserver-policy, and IPv6 one by one. If it still fails, investigate the system network or router DNS.

The LAN or entire network breaks after enabling TUN

Disable TUN first and confirm whether system-proxy mode works. If connectivity returns, the node and basic configuration are probably usable, and the problem is concentrated in routing, the virtual adapter, DNS, or permissions. Check for other VPNs, virtual machines, container networks, and corporate filters. Private addresses should go direct, and special internal ranges should be excluded. On Windows, focus on service mode and virtual adapters; on macOS, check VPN and filters; on Linux, check the routing table, policy routing, and firewall.

If the system still cannot connect after TUN fails, exit the client normally, then check for leftover routes, system proxy settings, and DNS changes. On mobile, stop the VPN and wait for the system indicator to disappear before reconnecting. On desktop systems, do not delete the virtual adapter as a first step: the client service may recreate it, and deleting another program's adapter can make the problem worse. Disable the feature in the client first, then remove the corresponding service component.

Existing selections disappear after a subscription update

A subscription provider may change node names, policy groups, or rule structure. The client's saved choices are usually matched by name, so a renamed item falls back to the default. A local override can also stop working if it references an old group name. After updating, check that the policy group still exists, then inspect the override logs. Do not manually edit the subscription cache for long-term changes; the next update will overwrite them.

When migrating clients, back up the subscription URL, local configuration, override scripts, and user selections separately. Clients differ in how they implement configuration directories, scripting, and policy persistence, so copying the entire old program directory is not enough. For legacy-client migration steps, see Preserving Configurations and Choosing Alternatives After a Client Is Discontinued.

Create a maintainable configuration update process

Keep a recent known-good configuration backup and limit local changes to a scope you can explain. Before updating a subscription, record the current policies and important overrides. Afterward, verify that the configuration loads, then test DNS, direct-access sites, proxied sites, and the LAN. Update routing databases separately from the client so the source of a problem is easier to identify. For GeoIP and GeoSite purposes, references, and loading issues, see How to Use GeoIP and GeoSite.

During troubleshooting, set logging to a level that records connections and rule matches; restore the normal level afterward to avoid generating large volumes of files. Before sharing logs, remove subscription URLs, control secrets, node credentials, and personal domain records. If you need to continue investigating but cannot classify the issue, use FAQ to search by fundamentals, installation and configuration, usage tips, and troubleshooting.

The core troubleshooting logic is the same on every platform: confirm that the software and configuration are running, confirm that traffic is entering, inspect rules, policies, and nodes, and handle DNS and platform permissions last. Preserving evidence and reducing variables in this order is more likely to produce a stable result than repeatedly reinstalling. If you need to choose another client or package, return to the Clash client download page and repeat the authorization and traffic-interception steps in the section for your platform.