Clash Setup for Every Platform
Installation & Configuration Guide

Before You Begin

Getting Ready: Clients, Architectures & Configuration Sources

Understand the Client, Core & Subscription

The Clash ecosystem includes graphical clients, a core that handles network traffic, and configuration files that define proxies and rules. The client provides features such as importing configurations, switching profiles, viewing logs, and managing permissions. The core handles connections, DNS resolution, and rule matching. A successful installation only means the app launches; it doesn’t guarantee a working proxy. Subscriptions are usually provided by a service provider, not by the client’s download page. Before you start, check where your configuration comes from, when it expires, which formats it supports, and whether it can be used on multiple devices.

For a graphical client, start with Clash Plus on Windows, macOS, Android, or iOS. On Linux, consider Clash Verge Rev or FlClash. Find installers for each platform in the Download Center. Similar product names don’t guarantee identical configuration support, especially for newer protocols, rule fields, and scripts. Before switching clients, keep a copy of your current configuration and check which fields the new core supports. Don’t rely on the file extension alone to judge compatibility.

Check Your OS and Processor Architecture

On desktop, check your OS version and processor type first. In Windows, open Settings → System → About and check System type; on macOS, select About This Mac from the Apple menu to identify your chip. On Linux, use the commands below to check the architecture. Android packages may also be split into ARM64, ARM, and universal builds, so a failed install doesn’t automatically mean the file is corrupt. Even with the right architecture, check the client’s minimum system requirements. Switching to another build for the same architecture won’t fix missing components on an older OS.

uname -m
# x86_64: usually AMD64 / x64
# aarch64: usually ARM64

Note your network environment too: are you on a campus or corporate network, do you need to sign in through a web portal first, and are other proxies or VPNs already running? Complete any network sign-in before enabling traffic routing. Multiple clients can overwrite each other’s system proxy settings or virtual network routes. Start with just one client, then change one setting at a time so you can tell what affected the result.

Keep a Backup You Can Restore

Before importing a link, make sure it comes from a trusted source and treat it as sensitive. It may contain account details or access credentials, so don’t include it in public screenshots, shared logs, or online conversion tools. For file imports, keep a copy of the original YAML. If the client supports exporting its settings, save a backup of those too. Subscription data and local client settings are often stored separately, so copying the YAML alone may not preserve startup behavior, service mode, or interface preferences when you migrate.

Give the configuration a recognizable local name and note how it was imported, when it last updated successfully, and which core it uses. Then check the mixed port, outbound mode, and traffic-routing method. First, verify access in a browser that follows the system proxy; only then consider TUN, LAN sharing, or advanced DNS settings. Enabling everything before the basic connection works makes configuration, permission, and network issues harder to distinguish.

Before installing, check that the system clock is correct, there’s enough disk space, and you know where to find the logs. Certificate errors can result from an incorrect system time; a port startup failure often points to a listener conflict. For first-time permissions and common errors, see the cross-platform first-run checklist. Before reinstalling, note the exact error and when it occurs.

Windows

Windows: Installation, System Proxy & Service Permissions

Choose an Installer and Launch the Client

Go to the Windows downloads and start with Clash Plus. To compare interfaces and configuration management, also consider Clash Verge Rev, FlClash, or Clash Nyanpasu. Clash for Windows is archived and no longer maintained, so it’s not a good default for a new device. Before downloading, check your system type and the package requirements; not every Windows device has the same processor architecture.

Follow the installer prompts to choose a location. On first launch, confirm that the client opens and the core runs normally. If security software blocks it, check which file was blocked, where it came from, and why; follow your organization’s or device’s security policy rather than disabling all protection. Portable and installed versions may store data in different locations. Before migrating, use the client’s Open Config Folder option or its equivalent instead of deleting files based on paths for another product.

Import a Subscription and Check the Active Configuration

In the Config, Subscription, or equivalent section, add a remote configuration with a local name and subscription URL, save it, and update it. Then select and apply the configuration; seeing an entry in the list doesn’t mean the core has loaded it. Check the proxies or policy groups for the expected content. If only DIRECT appears, inspect the subscription response and parsing logs instead of repeatedly toggling the system proxy.

To import a local file, use the import option and select the YAML. If loading fails, check indentation, fields, and policy names near the reported line, then verify core compatibility. If you need local changes to a remote configuration, use the client’s override or merge feature; direct edits to cached files may be overwritten on the next update. Note the mixed port before testing. 7890 is a common example, but use the port the client is actually listening on.

Test the System Proxy Before Enabling TUN

Turn on System Proxy in the client, then check the address and port under Windows Settings → Network & Internet → Proxy. The local address is usually 127.0.0.1, and the port should match the client. If your browser has a proxy extension, decide which layer controls requests so the extension doesn’t override the system settings. In Rule mode, visit a site and check the connection log for the matched rule and outbound policy; don’t rely on the toggle alone.

Command-line tools may not use the system proxy. Set the variables below temporarily in a PowerShell session and test your tool. Only programs that support these environment variables will use them, and a tool’s own proxy options may take precedence. Closing the window ends the session-level settings. If you set user-level or system-level variables separately, clear them there; a temporary session test doesn’t show that proxy settings have been restored system-wide.

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

# Clear these session settings after testing
Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue

TUN is for programs that don’t follow the system proxy and requires the client to have the necessary permissions. If the client offers Service Mode or Install Service, follow its prompts first. Then enable TUN and check the logs. Installing the service, starting the core, and creating a virtual adapter are separate steps. If the service is running but TUN fails, check the driver, permissions, and routes instead of importing the subscription again. Corporate devices may restrict virtual adapters; follow your device management policy.

Sleep and Network Recovery, Port Conflicts & Cleanup

If connections fail after waking the computer or switching Wi-Fi networks, pause traffic routing, confirm the basic network works, then enable it again. To check for a port conflict, run Get-NetTCPConnection -LocalPort 7890 and use the process details to identify the listener. Don’t terminate an unfamiliar process. Close the old client first, or change the new client’s port and update every reference to it.

Startup at login and automatic connection are separate options; test the client manually before enabling either. If the browser works but the terminal doesn’t, follow the separate browser and terminal troubleshooting guide. If only one app fails, check whether it uses its own proxy, a specialized transport protocol, or app-specific network restrictions.

macOS

macOS: Chip Architecture, Helper Tools & Network Settings

Choose a Client for Your Mac

Check About This Mac to see whether your Mac has an Apple chip or an Intel processor, then choose the matching installer from the macOS downloads. Clash Plus is a good starting point; Clash Verge Rev and FlClash are other options. ClashX Meta is archived and no longer maintained. When migrating an old configuration, pay close attention to differences between its fields and those supported by the new core. Translation layers don’t replace checking system requirements, and native builds are usually easier to maintain.

If the download is a disk image, open it, move the app to Applications, then launch it from there rather than running it from the mounted image. If macOS says it can’t open the app, first verify the download source and the warning, then follow the system steps under Privacy & Security. Removing all security restrictions is not a general installation step. Organization-managed Macs may also restrict background items, network extensions, or administrator approval; check your device policy first.

Import the Configuration and Preserve Client Settings

Open the configuration manager, add a remote subscription by URL, update it, and set it as the active configuration. Check the logs to confirm it loaded, then choose an outbound in the policy group. Importing a file only adds the settings it contains; it may not include menu bar behavior, system proxy controls, or helper service status. When migrating from an old client, export its original file and local overrides first, then configure the new client one setting at a time. This avoids restoring background services from multiple products at once.

If custom rules disappear after a remote subscription update, check whether they were saved in the subscription cache or as a separate override. They have different update lifecycles. Before editing, use the client to open its active configuration folder and identify the file in use. Don’t assume a file in Downloads stays in sync with the client. If the configuration parses but the expected policy groups are missing, check the subscription type and selected profile instead of reinstalling the app.

Check the Proxy Settings for Your Active Network Service

After enabling the system proxy, go to System Settings → Network, select the Wi-Fi or Ethernet service you’re using, and check the proxy address under Details → Proxies. Each network service has its own settings, so recheck them when switching from Wi-Fi to Ethernet. A client may configure web proxy, secure web proxy, and SOCKS proxy separately. The available options depend on the product; make sure the address and port point to the running client.

Use the command below in Terminal to view the system proxy status. This only reads the settings; it doesn’t mean every command-line program will use them automatically. To diagnose a specific HTTP request, specify the local proxy explicitly. The example uses a reserved example domain to test the request path. A successful request doesn’t prove that every site and protocol works. Check the connection log to confirm the request reached the core.

scutil --proxy
curl --proxy http://127.0.0.1:7890 --head https://example.com

If websites load but command-line tools fail, check the tool’s own proxy settings, environment variables, and DNS behavior. If it supports SOCKS and needs to resolve domains through the proxy, choose the appropriate mode according to its documentation. Don’t enter an HTTP proxy address in every protocol setting. Treat certificate errors separately: check the system clock, certificate chain, and network interception. Don’t make skipping certificate verification a permanent setting.

TUN Permissions & Restoring Network Access

Before enabling TUN, install or authorize the helper service as prompted by the client. The helper performs system operations that need extra permissions; it doesn’t mean the GUI automatically has every network permission. If installation appears successful but the toggle immediately switches back off, check the service and core logs, along with system authorization status. Before switching clients, stop TUN in the old client to avoid overlapping routes and traffic-routing mechanisms.

Waking from sleep, switching network services, or starting and stopping another VPN can all change routes. For troubleshooting, turn off TUN and the system proxy, confirm direct access works, then restore just one routing method. If direct access works but all domains fail with routing enabled, check DNS and routes. If only one destination fails, check its rule and outbound. Don’t start by resetting the entire system network; you could lose static addresses and authentication settings required for work.

Set the client to launch at login only after everything else works, and confirm background items are allowed. If a system update changes permissions, check the permission settings again rather than repeatedly importing the same subscription. If platform settings look right but DNS errors persist, continue with the Configuration & Troubleshooting section and check the file, core, and rules in turn.

Android

Android: App Packages, VPN Permission & Background Activity

Choose the Right Build and Handle Install Restrictions

Choose a client from the Android downloads; Clash Plus is our first pick. Other options include Clash Meta for Android, FlClash, and Surfboard. Clients don’t all support the same subscription formats or rules, so don’t import one client’s full YAML into another without checking compatibility. Review format support first, then choose a package for your device architecture. If you’re unsure, see whether the product offers a universal build.

When installing an app from outside the Play Store, Android may ask you to allow installs from the current browser or file manager. Grant permission only to the source you’re using, and revoke it afterward if you prefer. If the package can’t be parsed, check system requirements, architecture, download completion, and available storage in that order. A signature conflict usually means the existing app was signed differently or came from another distribution source. Export your configuration and local settings before uninstalling it.

Import a Subscription and Switch the Active Configuration

Open Config or Subscription and add a link, or import a local YAML file using the file picker. Android’s file picker may give the client access only to the selected file, so later changes to the source file may not carry over. After saving, update it once, check the contents and policy groups, then set it as the active configuration. “Import successful” only confirms the import operation; check that the core can load it too.

A remote link that returns a webpage, sign-in page, or unsupported format can result in an empty configuration or a parse error. Check whether the subscription has expired, whether you chose the client-compatible URL, and whether the system clock is correct. Don’t post the full link in a public chat. Before sharing logs, remove subscription URLs, account identifiers, and node credentials. Keep only the error type, relevant fields, and essential context.

Understand the VPN Interface and Per-App Routing

When you start a connection, Android displays a VPN connection request. Confirm the client’s identity, grant permission, then check the system status bar and the app. The VPN interface is the system’s traffic-routing entry point; it doesn’t mean every connection must go through a remote proxy. Rules, policy groups, and per-app settings determine where traffic goes. In most cases, you don’t need to change the Wi-Fi proxy manually. That can create a second route alongside mobile network settings.

In the same Android user profile, regular VPN apps generally can’t use this interface at the same time. If you have a corporate VPN, firewall, or local filtering app, decide which one should handle traffic. Test the client’s startup and reconnect behavior before enabling Always-on VPN or Block connections without VPN. The latter can block network access when the client stops, which may look like a Wi-Fi failure.

Per-app routing usually works in one of two ways: route only selected apps, or route every app except those selected. Check what the list means before saving; a checkmark alone doesn’t tell you which behavior is active. For testing, send a request from an app you know is included, then check the log and matched rule. Work profiles, cloned apps, and separate user profiles may have their own restrictions, so settings in the main profile may not affect them.

Background Restrictions, Network Switching & Battery Use

If the connection drops when the screen locks, check battery optimization, background activity, and auto-start settings. Menu names vary by manufacturer, so use the options shown on the app’s details page. A foreground service notification usually keeps the app running and shows connection status; its persistent presence alone doesn’t indicate a problem. After setup, test with the screen on, with it locked, and while switching from Wi-Fi to mobile data. Note when the first failure occurs.

If only mobile data fails, check whether Android restricts the app’s mobile data, whether Data Saver is on, and whether the subscription’s outbound can connect on the current network. If the connection is established but some apps still fail, check per-app routing and DNS. For LAN access, check whether private addresses are going DIRECT as expected. Don’t force all traffic through one outbound to hide a routing problem; that can break access to local services.

If you share your phone’s connection, remember that its VPN may not route traffic for devices connected through its hotspot; behavior depends on the system and implementation. Don’t assume a computer automatically inherits the phone’s proxy. Test the request path on the computer itself. For an overview of Rule, Global, and Direct modes in the app, see 10 Common Questions About Clash.

iOS

iOS: App Store, Configuration Import & Network Extensions

Get Clash Plus from the App Store

Clash Plus is a good choice for iPhone and iPad. Find it in the iOS downloads or open Clash Plus on the App Store directly. The product website is clashplus.io. Before downloading, check the App Store listing for OS compatibility and supported devices. Once installed, open the app to confirm it works before importing a configuration. Downloading the app and getting a subscription are separate steps.

Check iOS configuration compatibility in layers. Support for a rule syntax doesn’t guarantee support for another client’s interface settings, scripts, or extension fields. If your provider offers multiple subscription URLs, choose the format specifically intended for your client. When migrating from an older device, note your policy group selections and custom rules. Check on the new device whether the system backup restored app data; seeing the app icon isn’t enough.

Importing Links, Files & QR Codes

To import a link, add a remote configuration in the configuration manager, paste and name the URL, save it, then update and apply it. Some import options read directly from the clipboard. If iOS asks for paste permission, allow it only if it matches the action you’re taking. Check the pasted link for spaces, line breaks, or extra characters added by a chat app. After updating, verify the proxies or policy groups rather than stopping at the subscription list.

To import a file, select the saved configuration in the Files app. If it’s in cloud storage, make sure it’s downloaded and opens before importing it. A file import usually makes a one-time copy; later edits to the original may not update the app. For ongoing updates, use a remote subscription where possible. If you manage a local file instead, know how to reimport and apply it after each change.

QR code scanning works with content supported by the client. A code may contain a subscription URL, a single proxy, or a product-specific import link; a successful scan doesn’t mean you’ve imported a full ruleset. Review the recognized content and import type before continuing, especially if you don’t know the source. Camera permission is needed only for scanning. You can configure the client with a link or file instead without changing other system permissions.

Grant VPN Permission and Verify Traffic Routing

On first connection, iOS asks you to allow a VPN configuration and may require device authentication. Return to the client and start the connection, then check the VPN status in Settings. The network extension routes traffic; it’s not the same as a desktop system proxy toggle. Loading the configuration, starting the system tunnel, and connecting to a remote outbound are three separate steps. A failure at any stage can prevent websites from loading.

Start in Rule mode, choose an available policy, visit a destination, and check the client logs. If DIRECT destinations work but destinations that need a proxy fail, check the policy group and remote connection. If all domains fail, check DNS, the network extension, and the underlying network. A connected status doesn’t prove every rule is correct, and the status bar isn’t a substitute for testing an actual request. If the app logs provide limited detail, note when the error occurred and which network you were using.

On-Demand Connections, Background Behavior & Network Conflicts

If the client supports on-demand connections, enable the feature only after manual connections are stable. Check each trigger and Wi-Fi exception to avoid routing requests before signing in to a captive portal. When joining hotel, campus, or public Wi-Fi, make sure the sign-in page loads first. If needed, disconnect temporarily, complete sign-in, then reconnect. Don’t mistake a captive portal issue for an expired subscription.

On iOS, the foreground app and network extension have separate lifecycles. Leaving the app doesn’t necessarily stop the network extension; seeing it in the app switcher doesn’t guarantee the tunnel is working either. Check the system VPN status and test an actual request rather than repeatedly reopening the app. Before starting another VPN or network filtering app, check whether it will replace the existing configuration. During troubleshooting, use only one traffic-routing service at a time.

If Wi-Fi works but cellular data doesn’t, check the app’s cellular data permission and any restrictions on the current network. If only one app fails, check its own network features and matched rules. For detailed import instructions, see Get a Clash Client and Import a Configuration on iPhone. Before changing devices or retiring a client, turn off automatic connection options and check Settings for VPN configurations you no longer need.

Linux

Linux: Distribution Packages, Desktop Proxy & Core

Graphical Clients and Package Formats

For a Linux desktop, start with Clash Verge Rev or FlClash and choose a package supported by your distribution. Debian- and Ubuntu-based systems typically use deb packages; Fedora and similar systems typically use rpm. Compatibility also depends on architecture, system libraries, and desktop environment, so the file extension alone isn’t enough. Before installation, check your distribution details and the output of uname -m against the package requirements.

Installing through the system package manager is usually easier for handling dependencies than unpacking a package manually. The command below changes to the package directory and uses APT to install a local deb file you select. Before running it, make sure the selected file comes from a trusted source. If dependencies fail, read the package manager output and distinguish repository issues, missing library versions, and architecture mismatches. Don’t force installation by ignoring dependencies; that can leave the app in an unmaintainable state.

cd ~/Downloads
read -r -p "Enter the name of the deb file in the current directory: " package_file
if [ -f "$package_file" ]; then
  sudo apt install "./$package_file"
else
  printf 'Specified file not found\n'
fi

Import a Subscription and Configure the Desktop Proxy

After installation, launch the client from the desktop, import a remote subscription or local configuration, select and apply it, then check the core logs. Desktop environments may manage the system proxy through the session bus, and GNOME, KDE, and lightweight window managers can behave differently. If the client’s system proxy toggle doesn’t take effect, check the actual value in the desktop network settings. A toggle showing On doesn’t mean every program is using it.

Browsers may follow the desktop proxy, while terminals, containers, and services often don’t. To diagnose a single request, run curl --proxy http://127.0.0.1:7890 --head https://example.com. If it works with the explicit proxy but not without it, check the target program’s proxy settings. Also note that 127.0.0.1 inside a container refers to the container itself, not the host; the desktop address won’t work there as-is.

TUN Permissions and Multiple Network Managers

TUN usually needs access to /dev/net/tun and permission to modify routes. A graphical client may use a helper service to request authorization. Use the permission management method provided by the product; don’t assume the entire GUI must run as root. The commands below can show whether the device and routes exist, but they’re for inspection only. Don’t delete routes, flush the firewall, or disable system DNS services unless you understand the consequences.

ls -l /dev/net/tun
ip route
resolvectl status
ss -lntp 'sport = :7890'

resolvectl applies only to systems that use the corresponding resolver service. If the command is missing, that doesn’t mean DNS is broken. NetworkManager, systemd-resolved, other VPNs, and the client’s own DNS module can all affect name resolution. If domains fail with TUN enabled, first check whether requests reach the core and which component handles DNS. Disabling every resolver service at once makes it harder to identify the cause.

Mihomo on Servers and Routers

For headless servers and routers, find the Mihomo core in the Download Center; this is separate from installing a GUI client. You’ll need to manage the process, configuration directory, logs, and permissions yourself. Along with the architecture, check runtime requirements. For routers, verify the architecture and floating-point support rather than choosing a file based only on the advertised processor family. Desktop users don’t need to deploy a service just to use rule-based routing.

Validate a configuration with mihomo -t -f config.yaml, provided the executable is in your PATH and the file is actually named that. If validation passes, run it in the foreground, inspect the logs, and confirm the listener and outbound work before handing it to a service manager. If the configuration references external rule sets, also check the working directory, file permissions, and download paths. A service environment may differ from an interactive shell.

For startup problems, distinguish between launching at desktop login and starting a system service. The first depends on a user session; the second may run before the network is ready. If manual startup works but the service fails, check the actual user, working directory, and logs instead of changing a subscription that already works. When retiring the client, also remove its environment variables, desktop proxy settings, and service entries so background processes don’t compete with the new client for ports.

Configuration & Troubleshooting

Common Configuration Issues: Fields, Rules, DNS & Connection Tests

Identify the Configuration Source and Active Settings

The subscription text shown in the client may not be the file the core ultimately reads. Remote configurations, local overrides, interface settings, and automatically generated fields may be merged before they take effect. If a change to the file has no effect, look for the client’s runtime configuration or core logs and confirm the active profile, load result, and final values. Don’t edit the original subscription, cached file, and interface settings at the same time; it’s hard to tell which value overrides another.

YAML is sensitive to indentation and data types. Use spaces, not tabs, and keep fields at the same level consistently indented. Determine which field a list item belongs to by looking at its parent structure. The reported line may only be where the parser stopped; the actual issue could be a quote, colon, or indentation on the previous line. Restore a last-known-good file, then reapply changes in small sections. For more response and formatting issues, see Subscription Update Failures and Configuration Parse Errors.

Rule Order and Outbound Modes

Rules are usually evaluated from top to bottom, and the matching rule selects a policy. Put specific domain rules before broad rules, with a final catch-all at the end. Every policy group referenced by a rule must exist, and its name must match. The direct-only diagnostic configuration below illustrates the structure; it contains no remote proxies, so every matching request connects directly. For real use, keep your provider’s proxies and policy groups, and merge rules according to the core documentation.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

Global mode is useful for a quick comparison, not as a replacement for correct rules. If Global mode works but Rule mode doesn’t, check the match log, policy group, and rule set before blaming client stability. Direct mode doesn’t turn off the system proxy: an app may still connect to the local listener before the core routes it directly. To test the underlying network, explicitly disable traffic routing rather than only switching the outbound mode to Direct.

DNS and TUN: What to Check

DNS resolves domain names to addresses; the proxy handles the connection that follows. They can operate at different points in the network path. With TUN enabled, routes and DNS resolution may change, so check the configuration’s DNS settings, the system resolver, and client overrides together. Don’t copy another device’s fake-IP range, exclusions, or upstream servers without checking compatibility. They must suit your network, core capabilities, and actual requirements; mismatches can cause some domains to fail.

Check in this order: confirm the underlying network works, verify the core is listening, then check whether the request arrives, DNS resolves, a rule matches, and the remote outbound connects. If a domain fails but a known IP address works, investigate DNS, but don’t rule out certificate errors or server-side domain routing. Browser encrypted DNS may also bypass the expected path. Note whether it’s enabled, and change one setting at a time when comparing results.

Latency, Speed Tests & Diagnosing Connection Failures

A node latency test reflects only a particular test target, protocol, and moment. A timeout doesn’t necessarily mean every service is unreachable, and a low number doesn’t guarantee faster large-file downloads. Check the test target and method, then verify with a request to the destination you actually need. If a policy group uses automatic selection, confirm which outbound is active rather than treating one result in the list as the route your traffic took.

Speed tests are affected by local bandwidth, Wi-Fi signal, remote rate limits, concurrent tasks, and the test site. For a fair comparison, keep the network, time, and target consistent, pause other bandwidth-heavy tasks, and note the outbound in use. Don’t switch clients, DNS, and rule mode during a single test. If only one app is slow, check its connection log and protocol before repeatedly refreshing every node.

If Clash can’t connect, first disable traffic routing to confirm direct access works. Then check that the active configuration loaded, the local listener is running, and the policy group has an available option. Next, identify whether the error is a DNS failure, timeout, authentication failure, or connection refusal. When asking for help, include the platform, client, routing method, exact error, and checks you’ve tried; remove sensitive information. Search the FAQ by symptom, or return to the Getting Started guide and repeat the basic connection checks.