Clash Setup
for Every Platform

Getting started: clients vs. configurations

The client runs the app; the subscription supplies connection details

There isn’t one Clash installer that works on every device. The client is the app you interact with; the core reads the configuration, matches rules, and routes connections. mihomo is a widely used core in the Clash ecosystem. Clash.Meta evolved into mihomo, but older clients may not support newer fields. Before downloading, check your operating system, processor architecture, and whether the client is actively maintained. Then confirm that your subscription provider supports its configuration format. A filename containing “Clash” doesn’t guarantee compatibility.

For a first install, consider Clash Plus; choose another client based on your platform and preferences. Installing an app doesn’t provide working nodes. A subscription is usually a URL containing personal access credentials that returns configuration data such as nodes, policy groups, and rules. Make sure you have a client subscription URL—not an account sign-in page or a web share link. A URL opening in your browser doesn’t mean a client can parse it.

Record your system setup and connection prerequisites

Check the device clock, available storage, and basic network access. A badly misconfigured clock can prevent secure connections from being verified. If the network requires a sign-in page, complete that first. Company- or school-managed devices may restrict app installs, VPNs, or network extensions; don’t bypass those controls by disabling management policies. Check the processor architecture in system information rather than guessing from the computer’s appearance or phone brand. On mobile, also check for another active VPN, packet-capture tool, or filtering app that uses a local VPN connection.

Record four baseline details: whether direct access works, whether you’re on Wi-Fi or mobile data, whether a manual proxy is already configured, and whether you need access to printers or LAN servers. This makes it easier to tell whether a problem existed before setup or was caused by a new setting. Don’t enable system proxy, TUN, custom DNS, and global mode all at once. Start with the simplest working setup, then add features one at a time.

Understand the limits of modes and configuration files

Rule mode selects an outbound route for each request according to the rules in your configuration; it doesn’t send every request through a proxy. Global mode sends connections normally governed by the mode setting to the global policy, but it still doesn’t route traffic at the system level. Direct mode temporarily bypasses proxy routes. For most first-time setups, start with rule mode and select a node in the policy group actually referenced by your rules. Changing an unused group won’t affect the route for current requests.

YAML uses indentation to structure data. The example below shows a few common fields; it isn’t a complete configuration with nodes. When merging fields, add them to the corresponding section of your existing configuration. Don’t define the same key twice at the same level or use tabs for indentation. If the client provides UI controls for these settings, use them first to avoid conflicts between generated and manually edited configuration.

mode: rule
log-level: info
allow-lan: false
ipv6: false

Find all installation options on the download page. Migrating from an older client? First read how to back up and migrate after support ends. Keep the original configuration and confirm the new client works before removing the old app. Run only one traffic-routing client at a time during migration to avoid conflicts over routes or proxy ports.

Windows: installation, system proxy, and TUN

Choose an installer and complete the first launch

Start with Clash Plus in the Windows downloads, then compare Clash Verge Rev, FlClash, and Clash Nyanpasu if needed. Clash for Windows is discontinued and archived; it’s not recommended for a new setup. Open Settings → System → About to check your system type, then confirm the download page lists your architecture. If compatibility isn’t specified, don’t assume an installer for another architecture is supported.

Close any older proxy client before installing. A standard installation and one that requires administrator privileges for a service are not the same: opening the app doesn’t mean the background service required for TUN is ready. If a security warning appears, check the file’s source and app details. Don’t disable system protection globally just to dismiss the warning. If an organization’s policy blocks installation, contact your device administrator. After installation, open the app but leave launch at startup disabled for now so you can isolate any setup issues.

Import a subscription and confirm which configuration is active

On the configuration or subscription page, choose import from URL, enter a recognizable name, paste the full subscription URL, and save. Remove any leading or trailing spaces introduced when copying, but don’t edit the query parameters. Wait for the download and parsing to finish, then select the configuration. Some clients separate “save subscription” from “enable configuration.” Seeing a new entry in the list doesn’t mean the core is using it.

Open the policy groups, select rule mode, and check that the groups contain selectable nodes. If only DIRECT is available or a group is empty, check the subscription format and parsing logs instead of repeatedly toggling the system proxy. After a node passes its test, use a browser to visit a site that actually needs that route. A successful test only confirms connectivity to that test destination at that moment; it doesn’t guarantee every site, protocol, or sign-in flow will work.

Start with the system proxy; enable TUN if needed

The system proxy is a good first test for browsers and other common apps. When enabled, the client usually sets the system proxy address to the local loopback address; use the port shown in the client. The command below applies only if the client’s mixed port is actually 7890. It makes one request using an explicitly specified proxy. Don’t change a working port just to copy the example.

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

If the command works but a particular app doesn’t, check whether that app uses the system proxy or has its own proxy settings. TUN routes traffic through a virtual network interface and can help with apps that ignore the system proxy. When enabling it, follow the client’s instructions to install a service or grant permissions, then check logs for interface or route errors. Running the entire app as administrator is not a lasting fix for every permissions issue.

Fix port conflicts, resume issues, and leftover settings

If startup reports that a port is in use, check whether an older client is still running in the system tray or background. Also check developer proxies, container tools, and similar software. Don’t terminate unfamiliar system processes. If you need to change the port, update and verify it in the client, manual proxy settings, and terminal environment variables. The system proxy and WinHTTP proxy are separate; some background programs use their own connection settings entirely.

Waking from sleep, switching Wi-Fi networks, or connecting to a work VPN can change routes and DNS settings. Try turning traffic routing off and back on, then check whether service returns. If the issue recurs, save logs from the affected time. Before quitting the client, turn off the system proxy. After a crash, check system proxy settings for a leftover loopback address. If the client is closed but your browser still points to a local port, no pages may load.

Set the app to launch at startup only after the setup works, then restart once to confirm the background service, active configuration, and policy groups are restored. Before enabling “Allow LAN,” understand the listening address, inbound firewall rules, and authentication settings. Leave it off if only the local device needs access. For individual issues, check the FAQ rather than reinstalling the entire setup because one app misbehaves.

macOS: check chip architecture and network permissions

Download the right build and install the app

Open About This Mac to check whether your device has Apple silicon or an Intel processor, then choose the matching installer in the macOS downloads. Start with Clash Plus, or compare Clash Verge Rev and FlClash. ClashX Meta is discontinued; it may be useful for understanding an existing setup, but isn’t a good default for a new installation. Compatibility layers may let apps built for another architecture run, but their helper services and network features may still differ.

When installing from a disk image, copy the app to Applications as prompted, then launch it from there. Don’t run it indefinitely from the mounted installer. Installing it this way helps keep updates, helper paths, and login items consistent. If macOS displays a security warning, check the download source and signing information, then follow the system’s permitted steps. Don’t run commands found online that disable security checks for the entire computer.

Import a subscription and verify the simplest connection first

On the client’s configuration page, add a subscription URL, save it, and wait for parsing to finish. Enable the configuration, check that policy groups are present, select rule mode, and choose a route. If your provider offers separate formats for general use, mihomo, or other clients, choose the one compatible with your core. Importing a file doesn’t mean every extended field took effect; check logs for unsupported-field warnings.

Test the system proxy first. On macOS, proxy settings are associated with network services, and Wi-Fi and Ethernet may have separate settings. After switching networks, if the client shows the proxy as enabled but the browser has no connection entries, check proxy settings for the active network service. Browser extensions, developer tools, and terminal apps may also have their own proxy settings. One app’s results don’t represent the whole computer.

Network extensions, helper services, and TUN permissions

If you need TUN, grant permissions as prompted by the client. Implementations may use a privileged helper, a system network extension, or another mechanism; don’t expect every client to show the same prompts. You’ll usually confirm authorization in a privacy, security, or network section of System Settings. After the first authorization, return to the client and enable the feature again. Check the core logs; a dismissed system prompt alone doesn’t mean traffic is being routed.

If the toggle switches itself off, check whether the helper service installed successfully, whether macOS is still waiting for authorization, and whether an older client is using the same resources. Reinstalling repeatedly while keeping old services and settings often changes nothing. Quit the old app normally, then disable its service using the method it provides. Don’t manually delete unfamiliar system directories or network devices.

scutil --proxy
scutil --dns
route -n get default

These three read-only commands show proxy, DNS, and default-route settings so you can compare them before and after enabling a feature. Seeing a resolver in the output doesn’t mean every lookup uses it; the system may choose a route based on the network interface, domain, and priority. Hide personal network details before sharing command output. To troubleshoot DNS, use client logs and test the actual domain rather than drawing conclusions from a single address.

Handle LAN access, sleep, and network changes

If a printer, file share, or local development service stops working with TUN enabled, first identify whether the destination uses a loopback address, a private address, or a name discovered on the LAN. Direct-routing rules for private addresses solve only some cases; multicast discovery, link-local names, and virtual machine networks may require client-specific exclusions. Don’t route an entire LAN subnet through an external proxy, or leave global mode on just to reach a printer.

After waking your Mac and reconnecting, existing sessions may no longer work. Wait for the network to return, then reconnect the client tunnel. If DNS keeps using results from the previous network, try toggling traffic routing and check for a change. Take extra care when switching among a phone hotspot, work network, and home network, especially if a sign-in page or another VPN is involved. Confirm the underlying network works before troubleshooting the proxy, or an upstream outage may look like a broken configuration.

When moving to another Mac, import the subscription again first, then restore only the necessary overrides and rules. Don’t copy helper services, absolute paths, or old network interface names wholesale. Test browsers, terminal tools, and frequently used apps before enabling launch at login. Confirm that the system proxy is restored properly when you quit the client.

Android: VpnService permission and background operation

Check architecture and existing apps before installing

Start with Clash Plus in the Android downloads, or choose Clash Meta for Android, FlClash, or Surfboard based on your needs. Client support for configuration formats varies, especially in Surfboard; don’t assume it can import any mihomo YAML as-is. Check your subscription provider’s format guidance first. Use the architecture supported by your system: a 64-bit processor doesn’t necessarily mean the OS runs only 64-bit apps.

When installing an app downloaded outside the store, Android may ask you to allow installs from the browser or file manager you used. Grant permission only to that source for this installation, then turn it off afterward if you prefer. If an update reports a signature mismatch, don’t uninstall the existing app immediately. Export your subscription and overrides, and check whether both installers come from the same maintainer. Uninstalling usually deletes data stored in the app’s private directory.

Import a subscription and grant system VPN permission

On the configuration page, create a subscription from a URL, save it, wait for the download to finish, then select it as the active configuration. Open the policy groups, confirm that nodes are available, and select rule mode. When you first connect, Android displays a VPN connection request. VpnService is a system API that lets the client create a local virtual tunnel to receive traffic. Seeing a VPN icon doesn’t mean traffic is necessarily going through a remote server.

Check the app name in the permission dialog before authorizing it. If you deny the request, the client may still show configurations and nodes but won’t be able to route traffic from other apps; reconnect to trigger the request again. If Android never displays the prompt, check for another VPN, a work-profile VPN, or device-management restrictions. Android generally doesn’t let two regular apps use the same user VPN tunnel at once.

Rules, per-app routing, and always-on VPN

Keep rule mode enabled and test with a browser before changing per-app routing. Per-app settings may either include only selected apps or exclude selected apps—read the option carefully before choosing. Excluded apps may not appear in core logs, and changing nodes won’t route their traffic. If payments, LAN device controls, or work apps have issues, test them one at a time rather than excluding many apps at once.

Android’s “Always-on VPN” keeps the selected VPN app associated with the system. “Block connections without VPN” may block network access whenever the tunnel isn’t established. These are separate settings. First confirm that the client reconnects after a reboot and network change, then consider enabling the blocking option. Otherwise, an expired subscription, restricted app, or startup failure could leave your phone temporarily without network access.

Disconnects after screen lock? Check battery restrictions first

If the connection drops when the screen locks and returns when it wakes, start with the app’s battery settings. Allow background activity or exempt the client from battery optimization. Some manufacturers also require permission to autostart and for the app to stay in the background task manager. Menu names vary by device; the goal is to keep the VPN service running while the screen is locked. Follow the client’s guidance for notification permission and persistent notifications, but enabling notifications alone doesn’t exempt the app from battery restrictions.

Don’t judge the fix by running a speed test with the screen on once. Connect, lock the screen for a while, then unlock it and check the client’s service status and disconnect time. Test Wi-Fi and mobile data separately. Data Saver, background data restrictions, and manufacturer battery modes can all affect the result. For device-specific steps, follow this guide to VpnService permissions and battery optimization exemptions.

DNS, hotspot sharing, and switching clients

Android Private DNS, secure DNS in your browser, and the client’s DNS settings may all be active at once. If domain lookups fail, note each layer’s settings and change one at a time. Don’t disable everything just because it mentions DNS. Find out which app made the request, whether it entered the VPN, and which resolver handled it. The node server’s hostname also needs to resolve; if it doesn’t, no rule can establish the connection.

Turning on your phone’s hotspot doesn’t automatically share the phone’s VPN route with connected devices. Forwarding and permission behavior varies by system; “Allow LAN” isn’t a one-tap way to proxy hotspot traffic. When switching clients, recheck per-app routing, battery settings, and VPN permission—these usually aren’t included in a YAML file. Test screen lock, reboot, and network switching before disabling or removing the old client.

iOS: App Store installation, configuration compatibility, and VPN

Install Clash Plus from the App Store

Clash Plus is the recommended option for iOS. Get it from the iOS downloads or open Clash Plus on the App Store directly. The official website is clashplus.io. Before installing, check the system requirements listed in the store and compare them with your device. Don’t assume the feature list for a desktop client applies to iPhone.

When you first open the app, find the configuration import and connection screens; leave advanced settings alone for now. iOS apps generally use a system network extension to create a VPN tunnel. System authorization and subscription details are separate: permission to create a tunnel doesn’t provide nodes, and importing a subscription doesn’t mean iOS has allowed the app to route network traffic. Complete and verify both steps.

Check configuration compatibility, not just the URL name

Paste the subscription URL into an import option supported by the client, save it, and select the resulting configuration. If the app supports file imports, check the file type and supported fields too. Configurations across the Clash ecosystem aren’t fully standardized between implementations. Core extensions, rule providers, local file paths, and scripts can all differ. YAML that loads on desktop may need changes on a phone, or you may need a compatible format from your subscription provider.

If an import fails, first determine whether the error is a download failure or a parsing failure. For download errors, check that the URL is valid, the network doesn’t require sign-in, and the address wasn’t truncated when copied. For parsing errors, confirm the response is a configuration rather than a sign-in page or error message. Don’t post the full subscription URL in a public forum. When asking for help, include the error type and field name, but hide URL parameters, node passwords, and account identifiers.

Allow VPN configuration and choose an outbound route

When you first connect, iOS may ask to add a VPN configuration and confirm using your device passcode or biometrics. Afterward, return to the app to check its connection status and verify that the VPN entry in Settings belongs to the app you’re using. An app-created VPN configuration is not the same as a device management profile. Importing a regular subscription shouldn’t require installing an untrusted management profile or granting device-wide management access for an ordinary proxy connection.

Start with rule mode, if the app supports it, and select a node in a policy group that’s actually in use. If a page opens but a particular app can’t connect, check for differences in routing before changing all network settings. Some iOS apps keep existing connections open; after changing policies, you may need to reopen the app or reconnect to use the new route. Distinguish a cached page from a genuinely new request when testing.

Test screen lock and network switching separately

On iOS, the VPN network extension and the app’s foreground interface have different lifecycles; Android’s background-locking tips don’t apply. Don’t repeatedly swipe the app away to test whether it stays connected. Return to the Home Screen normally, lock the device, then check what happens when it reconnects. Low Power Mode, network changes, and system resource conditions can all affect recovery. Check whether the connection needs to be re-established, not whether the app still appears in the app switcher.

Switching from Wi-Fi to mobile data may interrupt existing connections and require a reconnect. If the problem occurs on just one Wi-Fi network, check its sign-in page and access restrictions first. If another VPN, device management policy, or system privacy network feature is active, note its current state and disable items one at a time to test for conflicts. Don’t blame every issue on the node, or reset all network settings at once and lose a useful point of comparison.

Update subscriptions and migrate without losing a recovery path

Before updating a subscription, keep any local rules or client-supported configuration backups. After the update, check that policy group names and selections are unchanged. If a node is removed or a group is renamed, your previous selection may no longer work. Using one subscription on a phone and computer is also subject to your provider’s device and concurrency limits. Being able to import the same URL doesn’t mean unlimited devices can connect at once.

On a new phone, reinstall the app, import the subscription again, and grant permission; don’t assume a system backup restores VPN status completely. Test browser access, frequently used apps, screen lock, and mobile data before clearing the old device’s configuration. For client-specific differences, check the mobile Clash client comparison to confirm supported features. Don’t assume another app’s instructions match the interface you’re using.

Linux: desktop proxy settings and standalone core deployment

Choose between a desktop client and a standalone core

The Linux downloads include graphical clients such as Clash Verge Rev and FlClash for desktop environments. The standalone mihomo core is better suited to servers, routers, or setups where you manage the service yourself. Check your distribution, package format, and processor architecture before choosing an installer. Debian-based and RPM-based distributions aren’t interchangeable just because package extensions look similar; desktop dependencies can differ too.

For desktop use, install the matching client with your package manager where possible to keep track of dependencies and removal. Import a subscription URL in the configuration UI, enable it, then check policy groups and rule mode. Don’t run the entire graphical app as root to work around permissions. Install any privileged service needed for TUN according to the client’s documentation; UI permissions and network interface permissions are separate.

Configure system proxy and terminal separately

Desktop environments such as GNOME and KDE have their own proxy settings, but not every app uses them. Command-line tools often rely on environment variables or separate configuration files, while containers have their own network namespaces. It’s common for the system proxy to be enabled while terminal traffic goes direct; that doesn’t necessarily mean the core is broken. Test the listening port with an explicitly proxied request, then check the settings of the specific program.

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

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1

unset http_proxy https_proxy no_proxy

The examples above assume a mixed port of 7890; use the value from your actual configuration. Environment variables affect only processes that inherit them, so already-running apps won’t change automatically. Support for uppercase and lowercase variable names varies by tool. These commands set the variables only for the current shell. Once verified, decide whether to add them to your shell startup file. Don’t set proxy variables system-wide or maintenance commands may fail whenever the client isn’t running.

Test the standalone core in the foreground before running it as a service

Before deploying the standalone core, prepare the executable and complete configuration in directories with clearly defined permissions. This example assumes the program is installed at /usr/local/bin/mihomo and the configuration is at /etc/mihomo/config.yaml. Check the configuration syntax, then launch it in the foreground and confirm that subscription references, local rule files, and listening ports work. A successful syntax check only means the configuration can be parsed; it doesn’t guarantee reachable nodes or correct routing.

/usr/local/bin/mihomo -t -d /etc/mihomo -f /etc/mihomo/config.yaml
/usr/local/bin/mihomo -d /etc/mihomo -f /etc/mihomo/config.yaml

Once it works in the foreground, use the service manager for your distribution. A systemd service should specify the executable path, configuration directory, run user, restart policy, and how to view logs. A regular local proxy can run with minimal permissions; TUN requires additional permission design to create network interfaces and update routes. Don’t copy service files from untrusted sources or put subscription credentials in startup arguments readable by other users.

TUN, DNS, and container network boundaries

Before enabling TUN, check that the system provides a TUN device and that the service account has the required permissions. Automatic routing can conflict with another VPN, policy routing, container bridges, or remote administration. On a remote server, keep a recovery option available. First make sure the new route won’t disrupt your current SSH session, then consider making it persistent. Don’t test full-traffic routing in your only remote session and immediately restart the service.

DNS may be managed by NetworkManager, systemd-resolved, or another component. Don’t assume /etc/resolv.conf is an ordinary file you can edit permanently; it may be a symlink or generated by a service. Check how DNS is currently managed before deciding how the client receives queries, where upstream lookups go, and how node hostnames are resolved. In a container, a loopback address points to the container itself, not automatically to the host proxy.

Back up the current binary and configuration before updating the core. After the update, run a test command, restart the service, and check its startup logs. For field compatibility issues, see how the Clash, Meta, and mihomo cores differ instead of deleting every field that triggers an error. Deployment is complete only after local requests, DNS, remote administration, and recovery after reboot all work.

Configuration FAQ: troubleshoot by layer, not by reinstalling

Tell subscription download errors from configuration parsing errors

First identify where the failure occurs. Connection timeouts, DNS resolution failures, and server rejections are subscription retrieval issues. Indentation, field-type, and missing-reference errors point to configuration parsing. If a subscription URL returns a webpage, the client may try to parse it as YAML, making the reported error location misleading. Confirm that the URL works and returns the expected format before changing indentation based on the first error line.

If a previously working setup fails after an update, keep the last working configuration and compare what changed. The subscription may have changed group names, rule providers, or protocol fields that your older core doesn’t support. Use the client’s configuration test and logs to decide whether to update the client or switch to a compatible subscription. Third-party online converters can access your subscription contents. Understand what you’d be sharing before using one; don’t hand a private URL to an unknown service just to fix an import error.

Node test passes, but websites won’t load

Troubleshoot in this order: app → traffic routing → rule → policy group → node → destination. If the client shows no connection entry, check the system proxy, VPN permission, and app exclusions. If there is an entry but it uses DIRECT, check which rule matched. If it matched the expected group but selected the wrong node, check the group selection. If the outbound route is correct but the request still fails, check DNS, the handshake, and restrictions at the destination. Change one thing at a time so you can tell what helped.

Global mode can briefly help identify a rules problem, but it isn’t a general fix. Restore the previous mode after testing. A node’s latency comes from a particular test request and depends on the test destination, timeout, and network conditions; it isn’t a reliable download-speed ranking. Repeated tests can also drain a phone’s battery. Before configuring automatic selection, understand the differences among url-test, fallback, and load-balance, then follow this policy group configuration guide.

Why aren’t my custom rules taking effect?

Rules are generally matched from top to bottom, so put specific rules before broad fallbacks. Policy names must match existing groups exactly, including spaces and capitalization. This partial example illustrates the order: send private addresses direct, send specified domains direct, then use “Manual Select.” The referenced policy group must already exist; copying the rules alone won’t create it.

rules:
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,Manual Select

If your client uses subscription overrides, rule preludes, or merged configuration, edit the persistent override rather than the downloaded cache, or the next subscription update will overwrite your changes. If a rule looks right but doesn’t match, check whether the request uses a domain name or IP address, whether the connection was already open before the change, and whether the client is showing the source file or the final active configuration. Checking the final configuration is more useful than repeatedly refreshing the subscription.

DNS failures, IPv6, and LAN issues

DNS translates domain names into addresses; successful resolution doesn’t guarantee a connection. First distinguish the node server’s hostname from the destination website’s hostname. If the former can’t resolve, the proxy route can’t be established at all. With Fake-IP, the client may return an address used for internal mapping. That isn’t necessarily an error, but the connection must continue through the same routing chain. For compatibility issues, exclude specific domains only after understanding the configuration; don’t swap out an entire address range at random.

Check the entire IPv6 path: whether the system has an address, DNS returns the relevant records, the client captures the traffic, and the node supports IPv6 egress. Disabling a setting can help narrow down an issue, but it doesn’t mean IPv6 should be disabled on every network. For LAN problems, check routes and direct rules first, then discovery protocols and name resolution. Don’t lump proxy, certificate, and LAN discovery failures together as the same “can’t connect” issue.

What to include in a backup, rollback, or support request

A reliable backup should include the subscription source, local overrides, required rule files, and notes on client settings; protect sensitive data separately. To roll back, restore the most recent working setup and reproduce changes one at a time. Don’t change the client, subscription, and DNS all at once. When asking for help, include the operating system, client name, traffic-routing method, steps leading to the error, and redacted logs. Raise log verbosity temporarily if needed, then restore normal logging once you’ve identified the issue to avoid recording unnecessary browsing details.

If you’ve narrowed the issue down to one setting, check the FAQ. For terminology, see the glossary. To build a working connection from scratch in order, return to the quick-start guide. The principle behind this manual is simple: preserve a working state, then test one layer at a time. Once you know where a request stops, there’s no need to keep uninstalling and reinstalling.