Clash Setup for Every Platform
Installation & Configuration Guide

01 · Before You Start

Know the difference between the client, core, and subscription

A Clash client manages configurations, modes, connection logs, and system integration. The core parses rules and establishes connections. A subscription comes from your configuration provider and typically includes nodes, proxy groups, and rules. Installing a client does not provide working nodes, and importing a subscription does not automatically route system traffic through the client. Troubleshoot these components separately: first make sure the configuration loads, then check that the selected outbound works, and finally confirm that apps are sending traffic to the client.

We recommend Clash Plus on supported platforms; choose another client based on your operating system and preferences. mihomo is one actively developed core in the Clash ecosystem, but that does not mean every client supports the same fields. Configuration parsers, core versions, and interface features can differ between mobile and desktop clients. Before moving a configuration to another device, check its format with your provider and confirm that the target client supports its protocols, rule types, and DNS options.

Check your system architecture and download source

Open your device’s system information or About page and note the operating system, processor architecture, and available storage. Desktop systems commonly use x64 or ARM64; Macs also differ between Intel and Apple Silicon. Linux packages vary by distribution. Don’t choose an installer based only on your computer’s brand. Visit the client downloads page to find the right platform. Check the selected client’s release notes for minimum system requirements rather than assuming another client has the same requirements.

Before installing, quit any existing proxy software and note your current system proxy, DNS, and VPN settings. On managed work devices, policies may lock these settings, so check what you’re allowed to change first. Export existing configurations to a private local folder and keep a backup you can restore. Never post screenshots, configuration files, or QR codes containing subscription URLs in public forums. Subscription URLs often contain access credentials; if one is exposed, generate a replacement through your provider.

Identify the configuration source and traffic-routing method

Remote subscriptions are convenient for updates; local YAML files are useful for fixed configurations. A Base64-encoded list of nodes is not necessarily a complete Clash configuration. If an import reports missing fields, check the format instead of deleting the lines that triggered the error. Use a conversion tool only if you trust its source and understand how it handles your data. For a comparison of the three formats, see Subscription URLs, YAML, and Base64: Format Guide.

A system proxy advertises a proxy address to apps; it does not force every process to use it. TUN routes traffic through a virtual interface and usually requires additional permissions. It can also conflict with other VPNs. For your first setup, use the client’s recommended defaults and verify that they work before adding more options. Change one setting at a time and note when you make each change; otherwise, it’s difficult to tell whether the problem is with a node, DNS resolution, or routing.

Set up a repeatable connection test

Choose one reliable site that should connect directly and another that should use a specific outbound. For each, record whether the domain resolves, the page loads, and the connection log shows the expected rule. Start in Rule mode and manually select a working outbound in the relevant proxy group so automatic selection doesn’t hide problems. Browser cache, existing connections, and app-specific proxies can affect results. After changing settings, start a new connection and test again; one page refresh doesn’t prove all network traffic is working.

A client does not change the access policies of the services you connect to. Follow local laws, workplace network policies, and service terms. If you’re ready to connect and just need the essentials, go to the quick-start guide. If you’re troubleshooting permissions, background operation, or routing on a particular platform, jump to the relevant section below, then follow the final section to verify your setup.

02 · Windows Installation and Proxy Setup

Choose an installer and launch the client for the first time

Check your system type in Settings > System information, then visit the Windows downloads. We recommend Clash Plus. If you need a different interface or workflow, consider Clash Verge Rev, FlClash, or Clash Nyanpasu. Clash for Windows is discontinued and should be considered an archived option, not a workaround for compatibility issues on newer systems. Check the download listing to confirm that the installer supports your architecture.

For an installer, follow the setup wizard and choose an installation folder. For a portable version, extract it to a fixed folder your account can write to; don’t run it directly from the archive. On first launch, use a standard user account and confirm that the app opens and can write to its configuration folder. If Windows warns about the app’s source or security, verify where you downloaded it and read the warning details. Don’t disable system-wide protections just to install an app. On a managed computer, ask an administrator whether installation is allowed.

Import a subscription and select an outbound

Find the remote import option under Configuration, Subscriptions, or Profiles. Paste the full subscription URL and submit it. Once the import succeeds, you should see a selectable configuration—not just the URL left in the input field. Select it and check that its proxy groups appear. If the list is empty, check the configuration load log. Some clients download and activate configurations as separate steps, so after an update, make sure the updated configuration is active rather than continuing to use an older file.

Set the outbound mode to Rule and select a node in the proxy group you need. A latency test measures the response to a specific probe target; it doesn’t prove that every protocol or site will work. For your first test, check both real-world access and the connection log. If a subscription download fails, retry on a network that can connect directly. Check whether the service has expired or the URL redirects to a login page. Don’t save a web page as YAML and try importing it.

Check the mixed port and system proxy

Check the listening port in the client settings. 7890 is a common example for a mixed port, but your client may use another value. A mixed port typically accepts both HTTP and SOCKS connections; set the system proxy using the method provided by your client. After enabling it, open Windows Network & Internet settings and confirm that the manual proxy points to your local machine. Don’t enter a remote node’s server address as the system proxy address—they serve different purposes.

Get-NetTCPConnection -State Listen -LocalPort 7890 |
  Select-Object LocalAddress, LocalPort, OwningProcess

The PowerShell command above checks for a listening port. No results may mean the core hasn’t started or the client is using a different port. If another process is using the port, identify it before choosing whether to close an old client or change the port. Never terminate an unfamiliar system process. If you change the port, update any manual proxy settings in other apps too. Editing a configuration file without reloading it won’t necessarily change the port the running client is listening on.

TUN, UWP, and firewall permissions

If your browser works but some apps aren’t using the proxy, first check whether they follow the system proxy settings. If you need TUN, install the service or grant administrator permissions as prompted by the client, then enable the virtual interface. Installing a service and running the client as administrator every day are different things; a client with its service installed may not need elevation on every launch. After enabling TUN, check the routes and logs. If the network stops working, turn off TUN to restore your baseline rather than layering on other VPN or acceleration software.

Some UWP apps are restricted from accessing loopback addresses, even when the local proxy works. Use the client’s loopback management option if available, and add exceptions only for apps that need them. Don’t remove restrictions for every app or mistake a loopback issue for a rule problem. System policies govern these settings; on managed devices, don’t try to bypass permission failures by repeatedly elevating privileges. First check whether the same destination works in a standard browser.

When the firewall asks about network access, choose a scope that matches how you use the client. Local use does not require inbound access on every public network. For LAN sharing, separately check the listening address, authentication, and trusted network range. If the client crashes or the system wakes from sleep with the client closed but the system proxy still pointing to a local port, turn off the leftover proxy in Windows settings and restart the client. Then review the rule log. For more first-launch checks, see the Mixed Port, Mode, and System Proxy Checklist.

03 · macOS Installation and Permissions

Identify your processor and move the app to Applications

Check your chip in Apple menu > About This Mac. If separate builds are available for Apple Silicon and Intel, choose the matching installer, then visit the macOS downloads. We recommend Clash Plus; Clash Verge Rev and FlClash are also options. ClashX Meta is discontinued. Archived builds may not support current macOS versions or features like actively maintained clients do, so don’t assume it’s supported just because the name looks familiar.

Open the downloaded disk image and drag the app to your Applications folder. Launch it from there, rather than running it from the disk image, to avoid update and permission issues caused by a changing app location. If macOS blocks the first launch, verify the download source and review the specific notice under Privacy & Security. Don’t run commands that remove security attributes from every app or disable system-wide protections to bypass a single app’s launch warning.

Understand extensions, helper services, and Keychain

macOS clients may integrate with the network using the system proxy, a privileged helper service, or a network extension. Their permission prompts vary by implementation. Respond to the prompts your client actually displays: if it asks to add a VPN configuration or network extension, verify the app name; if it asks for a helper-service password, check the dialog’s source. Not seeing a particular prompt doesn’t mean something is missing—don’t search for a setting that your client doesn’t use.

Some permissions must be explicitly allowed in System Settings before you can retry in the client; macOS may also require a restart. Save your work first, follow the prompt, and then check the extension status. Keychain prompts usually relate to saving or reading credentials. Enter the password for the specified system Keychain, not your subscription service password. If a feature doesn’t work after you deny access, check the app’s instructions and Keychain access permissions rather than deleting all Keychain items.

Import a subscription and use the menu bar

Open the client’s configuration manager, add a remote subscription, and enable the downloaded configuration. To use a local YAML file, import it or open the configuration folder from the client. Make sure the file doesn’t have an unintended double extension. Once it loads, check the proxy groups, then choose Rule mode and an outbound from the menu bar. A menu bar icon only shows that the interface is running; also check the core, active configuration, and system proxy.

For your first test, use the system proxy. Open a new browser window, visit a test site, and check which rule the connection matches. Some command-line tools don’t use the graphical system proxy, so a failed terminal request doesn’t necessarily mean the client is broken. You can specify the proxy for a single command to check whether the local endpoint is reachable. Replace the port below with the one your client actually uses; the command won’t permanently change your terminal environment.

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

TUN and network changes

If an app doesn’t follow the system proxy, consider the TUN or network-extension option supported by your client. Before enabling it, quit other VPNs and confirm that the necessary permissions are granted. After creating a virtual interface, check DNS and outbound routing too; a connection indicator alone doesn’t prove that all traffic follows the intended rules. Test work intranet services, printers, and local development servers separately. If needed, configure direct access for the relevant network ranges instead of copying a large, untrusted route-exclusion list.

Switching from Wi-Fi to Ethernet, joining a hotspot, or waking from sleep can change which network service the system proxy applies to. If the browser suddenly stops working, first check whether the current network can connect directly, then check the client’s listening port and proxy toggle. When multiple proxy tools are running, the one launched last may overwrite settings set by another. Let only one client manage system traffic at a time; disable network takeover in other tools and test them one by one.

Before quitting, turn off the system proxy or disconnect the tunnel to avoid leaving a proxy address pointing to your machine after an unexpected exit. To uninstall, use the app’s own option to remove any helper service it installed, then check for related VPNs or extensions in System Settings. Don’t manually delete files based on another client’s instructions; similar apps can use different identifiers. For recovery after denying permissions, see macOS Network Extension and Keychain Permissions and follow the prompts that apply to your setup.

04 · Android Installation and Background Operation

Choose an architecture and grant installation permission

Visit the Android downloads. We recommend Clash Plus, followed by Clash Meta for Android, FlClash, and Surfboard. Most newer devices use ARM64, but check the processor and app requirements on older devices or custom Android builds. The downloads page indicates whether a universal package is available. Surfboard has its own configuration format; don’t assume it can import any Clash YAML. Ask your configuration provider for a format supported by your target client.

When installing an APK, Android may ask you to allow the browser or file manager to install unknown apps. This permission applies to that specific source app and can be turned off after installation. If parsing fails, first check that the download completed and that the package matches your Android version and architecture. A signature conflict during an update usually means the installed app came from a different source or build. Don’t uninstall it immediately: export your configuration and make sure you can restore your account details and local settings before deciding how to migrate.

Import a configuration and approve the VPN request

Open subscription management, add the remote URL, wait for the download, and select the configuration. To import a local file, grant access through Android’s file picker. Files in another app’s private folder may not be accessible; save a copy to a folder you control first. A subscription name appearing in the list doesn’t mean its contents are valid. Check that nodes or proxy groups loaded, and review the download response and configuration parsing log if you see errors.

When you tap Start, Android will usually show a VPN connection request. Make sure it comes from the client you just installed, then approve it. Here, VPN refers to Android’s local traffic-routing interface; it does not automatically connect your device to a remote VPN server. The nodes and rules in your configuration determine the final outbound. Once connected, you’ll usually see a status in the status bar or VPN settings, but the icon alone doesn’t prove that a site is reachable.

App filtering, rule mode, and DNS

Mobile clients often let you choose which apps use the tunnel. First check whether the list uses an allowlist or blocklist: an allowlist routes only the selected apps, while a blocklist bypasses the selected apps. Reconnect after changing this setting; some apps may need to be fully closed and reopened. If an app doesn’t appear in the connection log, check the app filter before changing nodes or disabling all routing rules.

Apps routed through the tunnel are usually still subject to rules based on domains, addresses, or rule sets. App filtering and rule-based routing are separate layers; allowing an app through the filter does not mean all its connections will go direct. For local device discovery, casting, or home services, also check LAN bypass and DNS settings. Android Private DNS and in-app secure DNS can change the resolution path. Note the original settings, test any changes temporarily, and decide afterward whether they need to be adjusted.

Battery management and network changes

If the connection drops when the screen turns off, check battery optimization, background activity, auto-start, and notification permissions first. Settings names vary by manufacturer, so look in the system app details for the client rather than relaxing restrictions for every app. Allowing background activity can increase battery use; first confirm that Android is actually stopping the client. If only mobile data drops, check whether background data is restricted for the app and whether your plan or network limits connections.

Switching between Wi-Fi and mobile data creates a new underlying connection, so existing connections may stop working. After the network comes back, see whether the client reconnects automatically; if not, disconnect and restart the VPN. Avoid rapidly switching between several modes, which can mix intentional disconnects with actual failures in the logs. If Android’s Always-on VPN or Block connections without VPN is enabled, the device may refuse network access when the client stops. Review and manage these settings in the system VPN page.

Usually, only one app at a time can use the system VPN interface for a user. A local firewall, ad blocker, or another VPN may take over the interface, so identify conflicts before connecting. School- or work-managed devices may also prohibit user-added VPNs; follow the applicable policy. For LAN sharing, a working connection on your phone isn’t enough to confirm that hotspot traffic enters the tunnel. Support depends on Android and the client—don’t assume it works automatically.

After setup, test access with the app in the foreground, after leaving the screen off for a while, and after switching networks. Check the outbound shown in the logs each time. When you’re done, disconnect in the client and confirm that the system VPN indicator disappears. If a subscription update succeeds but the proxy groups don’t change, check the active configuration and local overrides. You may have updated a different subscription, rather than the core failing to load new nodes.

05 · iOS Installation and Connection Setup

Install Clash Plus from the App Store

We recommend Clash Plus for iPhone and iPad. Visit the iOS downloads or install it from the App Store. The official site is clashplus.io. Before installing, check the current system requirements and app details in the store. Availability depends on your account and device; don’t apply installers or system requirements from other platforms to iOS.

After installing, open the app and locate its subscription, proxy, and connection screens before importing anything. Avoid importing multiple configurations with the same name, so you can tell which one is active. If you already use another proxy app, note its configuration and the system VPN status before disconnecting it. iOS manages app sandboxes and background network extensions differently; don’t look for desktop-style persistent processes, listening services, or driver installers.

Add a subscription or local configuration

Add a remote URL from the configuration or subscription screen, paste the full link, then save and update it. When importing from a QR code, check the camera permission and the source of the displayed content; scanning a code is only an input method and doesn’t make the URL trustworthy. To import a local file, select the actual YAML file in the system file picker. If it’s still in cloud storage and hasn’t been downloaded, wait for it to become available and try again rather than mistaking a read error for invalid syntax.

After importing, confirm that the configuration is valid and that its proxy groups and outbound options appear, then set it as active. Some providers supply only a list of nodes, which may require the client’s own rule template. A full configuration may include its own rules and DNS settings. These are different approaches; follow the client’s import prompts. If fields are unsupported, ask for a compatible configuration instead of repeatedly deleting unknown fields and potentially changing the provider’s routing logic.

Approve the VPN configuration and verify routing

On the first connection, iOS may ask to add a VPN configuration and confirm with your device passcode or biometric authentication. Verify which app initiated the request before approving it. Approval lets the app create a network tunnel; it doesn’t guarantee that the subscription or nodes work. Return to the client, start the connection, choose Rule mode, and select an outbound in the proxy group. Verify the matching rule using a new request and the connection log; don’t rely on the VPN icon in the status bar alone.

iOS clients usually route traffic through a system network extension. Unlike desktop clients, they don’t require users to enter a local system proxy address for every app. Whether your client offers a separate proxy, LAN, or other traffic-routing option depends on its features. Start with the default settings to establish a baseline. Check bypass and DNS options only when you’ve identified an app compatibility or LAN access problem, and avoid changing multiple network settings at once.

Background operation, on-demand connections, and network changes

After you return to the Home Screen, the app interface and its network extension don’t share the same running state. If the app temporarily shows no connection history, the tunnel may still be active; check the system VPN status and try accessing a site. Force-quitting the app can interfere with recovery and isn’t the recommended way to disconnect. Use the app’s connection toggle, then check System Settings to confirm that the connection status has updated.

With on-demand connections enabled, iOS may start the VPN again when its conditions are met, making it look like a manual disconnect didn’t stick. Check the client’s on-demand rules and the system VPN configuration instead of repeatedly deleting the app. Work-managed devices may restrict personal VPNs, and organization profiles can override network behavior. Don’t remove management profiles you don’t recognize. Confirm what they do and follow your organization’s instructions to avoid disrupting work accounts or certificates.

When switching from home Wi-Fi to mobile data, existing connections may need to be re-established. First make sure mobile data is enabled for the app, then check whether the current outbound is reachable. If only a LAN service fails, test the device’s address on the same network and check whether a rule is sending the connection through the proxy. Other system privacy features and in-app secure DNS can also affect results. Note each setting as you troubleshoot and make temporary comparisons; don’t assume a feature must be permanently disabled.

If a subscription update fails, check the service status and response first, then try a manual update once on a network that can connect directly. Web access during a connection doesn’t mean subscription downloads follow the same route. Background updates also depend on the client and iOS scheduling, so don’t assume they run at a fixed time. Before migrating devices, securely retain the subscription source and any necessary settings. Import and test them on the new device before removing the old configuration.

06 · Linux Clients and Core Setup

Choose between a desktop client and a command-line core

For Linux desktops, check the Linux downloads for Clash Verge Rev and FlClash; Clash Verge Rev is our recommendation. Choose a package that matches your distribution, processor architecture, and package manager. Debian-based systems commonly use deb packages, while some distributions use rpm, but the file extension alone doesn’t guarantee that all dependencies are compatible. Server and router users can consider the mihomo core. A command-line core does not include a desktop interface for subscription management or system proxy settings.

Install the downloaded package using your distribution’s software installer or package manager, and review any dependency warnings. Don’t mix package sources from different distributions to satisfy dependencies, or run unknown scripts in a privileged shell. After launching a desktop client, confirm that it can write to its configuration directory and start the core. A missing tray icon may be due to desktop environment integration, not an exited app; check its window and logs to find out.

Import a subscription and configure the desktop proxy

In a graphical client, add a subscription, download and enable the configuration, then choose Rule mode and an outbound. Some desktop environments have separate HTTP, HTTPS, and SOCKS proxy fields; enter the ports and protocols provided by the client. A mixed port can accept multiple types of connection, but that doesn’t mean you can swap protocol settings arbitrarily. Browsers may have their own proxy settings, and command-line programs may only read environment variables, so test them separately.

curl -I --proxy http://127.0.0.1:7890 https://example.com
ss -lntp 'sport = :7890'

The first command tests an explicitly specified HTTP proxy; the second checks for a local TCP listener. Use your actual port. Process details may be restricted by your current permissions. If the proxy test succeeds but a desktop app fails, check the desktop proxy or the app’s own settings. If the local connection is refused, troubleshoot core startup and the port first. There’s no point repeatedly changing remote nodes before a local service is listening—the request hasn’t reached the outbound stage yet.

Check and start the command-line core

With mihomo, keep the executable and private configuration in clearly named directories, and use their actual filenames. The account running it must be able to read the configuration and write to its data directory. Since configurations contain subscription and node information, don’t give other accounts unnecessary read access. Check the syntax, then start the core in the foreground and review its output. The commands below assume the current directory contains an executable named mihomo and a complete config.yaml.

./mihomo -t -d . -f ./config.yaml
./mihomo -d . -f ./config.yaml

A successful syntax check only means the configuration can be parsed; it doesn’t prove that nodes are reachable, rule resources are present, or ports are available. Once the core runs successfully in the foreground, consider running it as a service. Don’t hide startup arguments, working directory, and permission issues in a background service before checking them. For systemd, use actual absolute paths for the executable, configuration, and data directory, and make sure the service account can access the required files. After changing a service unit, reload the manager configuration.

TUN permissions, DNS, and remote recovery

TUN requires a virtual interface, routing, and network administration permissions. Enabling a setting in the configuration alone isn’t enough. First make sure the system provides a TUN device, then use the service or permission method recommended by your client. Running in a container also requires device access and network namespace configuration; a working host does not guarantee that TUN works inside the container. Don’t grant every program network administration privileges indefinitely, or run your entire desktop session as root without understanding why.

DNS may be managed by NetworkManager, systemd-resolved, desktop settings, or the client. Find out which component handles resolution before changing anything; system services may immediately overwrite manual edits. With Fake-IP enabled, check that DNS queries are actually passing through the core. Changing the enhanced mode while DNS bypasses the core can make rule logs differ from actual traffic. For internal domain names, preserve the appropriate local resolution path.

Before enabling automatic routes on a remote server, keep your management connection and an out-of-band recovery method available. Define which traffic—such as SSH, LAN access, and connections to upstream nodes—must bypass the tunnel. A bad route can send the management session or the proxy’s own connection back into the tunnel. After setup, test the local proxy, target outbound, and remote management connection before enabling startup on boot. If the network stays down after stopping the service, check leftover routes, desktop proxy settings, and environment variables. Don’t assume deleting the executable will restore the original state.

07 · Configuration and Common Issues

Start with a minimal configuration to understand the fields

Troubleshoot in this order: configuration loading, local listening, system routing, DNS, rules, and target outbound. Change one variable at a time and record when you changed it and what happened; otherwise, even a successful fix won’t tell you which change worked. The YAML below demonstrates fields and indentation. It includes only direct-connection rules, with no proxy nodes, and is not a complete subscription configuration. Use it in a separate test configuration to learn the structure; don’t overwrite the subscription you’re using.

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

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT

YAML uses spaces for indentation, not tabs. Keep keys at the same level aligned; the dash before a list item is part of the syntax. A complete proxy configuration also needs valid outbounds or proxy groups, and each rule’s target name must exist and match. A subscription update may regenerate the entire file, overwriting direct edits. For persistent changes, prefer an override, merge, or extension mechanism explicitly supported by the client, and verify the merged result.

Troubleshoot subscription downloads separately from resource updates

If a subscription update fails, first check that the URL is complete, hasn’t expired, and returns a valid configuration. Contact your provider about authentication failures. For timeouts, check the download path and network; a web page response often means a login redirect or server error. GeoIP, GeoSite, and rule-set downloads are separate resource requests. A successful subscription update doesn’t guarantee that these resources downloaded. Find the failed resource in the logs and check its path, permissions, or network access instead of blaming the node by default.

DNS, Fake-IP, and rule order

If a domain fails to resolve, identify whether the system, app, or core is handling DNS. Fake-IP assigns a virtual address to a domain; seeing one doesn’t mean the real server address is wrong. What matters is whether subsequent connections still pass through the core, which can recover the domain name. An app that bypasses the tunnel may not work with a virtual address, so check the traffic-routing scope and app filters. For details, see Fake-IP vs. Redir-Host: A DNS Mode Comparison.

Rules are usually evaluated in order, and the first matching rule wins. A broad rule placed too early can override more specific rules that follow. MATCH is the fallback; don’t change it without understanding the rules above it. A site may connect to multiple domains, so if the main page loads but its resources don’t, inspect each connection. GeoIP relies on IP address data, and some rule options affect whether DNS resolution is triggered. Rule text alone doesn’t tell you whether all traffic will be routed by location as expected.

Latency, timeouts, and recovery steps

A successful node latency test doesn’t guarantee that your target will work; a failure may simply mean the probe address is unreachable. When you see a timeout, identify where it occurs: connecting to the local port, reaching the remote node, or accessing the destination from that node. Check the logs at the same time and compare with another known-working outbound. Temporarily increasing log detail can provide clues; restore the usual level once you’ve found the issue. Remove addresses, account details, and access records before sharing logs. For more examples, see Clash Runtime Log Errors Explained.

If every app fails, check the listener and traffic routing first. If just one app fails, check its own proxy settings, loopback access, app filters, and cache. If only one site fails, check its rules and target outbound. Once things work, record the settings you’ll need to reproduce them, including the actual port, active configuration name, and required permissions—but never store real subscription credentials. For other quick answers, see the FAQ; for definitions, see the Glossary. A setting with the same name can behave differently across platforms.