Clash Setup Guide for Every Platform

For your first connection, follow the Quick Start to import a profile, choose a group, and verify the connection. If you already have a profile, are switching devices, or need to find out why traffic isn't going through the client, use this guide to find the relevant section. Steps are organized by download, installation, import, traffic routing, and verification.

Before you begin: apps, profiles, and traffic routing

Start with your device and what you need

Get a client from the downloads page for your operating system. For a first-time setup, start with Clash Plus if it's available for your platform. On Linux, consider Clash Verge Rev. When moving an existing profile, check that the new client supports its protocols, proxy groups, and rule sets—don't rely on the product name alone. If your current device has a stable setup, keep its client and profile until you've verified the new device, then switch your everyday use.

Before installing, list the apps you want to test. If only your browser and a few tools need a proxy, start with the system proxy or each app's own proxy settings. For apps that ignore proxy settings, consider desktop TUN or a mobile VPN. The same rules on two devices don't guarantee the same traffic coverage. Traffic must first reach the client; only then can rules send it direct, through a proxy, or block it. Requests that never reach the client won't appear in its logs.

Routing methodWhat to check firstCommon limitations
System proxyWhether the address and port set in the system match the clientApps may use their own proxy settings instead of the system proxy
Desktop TUNWhether the virtual interface, permissions, routes, and DNS are workingMay affect local networks, corporate VPNs, and virtual networks
Mobile VPNSystem permission, active connection, and app coverageVPNs compete for traffic control within the same user or profile

Know the difference between a subscription URL and a local profile

A remote subscription is a URL the client periodically fetches to get a profile. A local profile is a file already on your device. Before importing a remote URL, make sure the service provides a format your client can read. A node share link, a service dashboard, and a complete profile file are not interchangeable. A URL opening in a browser doesn't mean the client can parse its response: the browser may be signed in while the client only receives a login page.

Subscription URLs often contain account details, so treat them like passwords. Don't share the full URL in support tickets, screenshots, or shared documents. When moving a local profile, check the rule sets and resources referenced by proxy providers as well as the main file. Paths on a desktop usually won't exist on a phone, and cached files may only be last time's downloads. Start with an original profile that can be updated, then decide which custom changes to move to the new device.

Check downloading, loading, and connecting separately

After adding a profile, check that it appears in the list, then confirm it loads and is selected as the active profile. Some clients only add an entry on import without enabling it; others reload after a subscription update, which may also change your manually selected node. Check that the proxy group has an available member and that rule mode is selected, then enable the system proxy, TUN, or VPN. Don't turn on every setting before your first test.

For verification, choose one domain expected to go direct and one expected to use a proxy, then make a fresh request to each. If the client supports it, compare the destination, matched rule, and actual outbound in the connection log. Don't judge the entire rule set by whether your public IP changes: that only reflects the connection to the IP-check site. If neither request appears in the log, check traffic routing first. If one uses the wrong outbound, check its rule and proxy group.

Keep a working baseline you can restore

Before making changes, stop the client, confirm your current network can open familiar websites, and note whether a corporate proxy, custom DNS, or work VPN was already in use. If the baseline isn't working, restore the network first rather than trying multiple clients. On public Wi-Fi, complete the captive portal sign-in before enabling traffic routing; otherwise, the login page may not open, making the subscription or node look broken.

Windows: system proxy and TUN

Choose an installer and quit the old client

Get Clash Plus from the Windows downloads. If you’re switching clients, compare Clash Verge Rev, FlClash, and Clash Nyanpasu. Clash for Windows is discontinued and archived; use it to reference an existing setup, not for a new installation. Before downloading, open Settings in Windows, go to System → About, and check your system type against the architecture listed on the download page. On ARM64, don’t assume that a desktop app running through a compatibility layer can also install a virtual network adapter or service.

Before installing, turn off the system proxy and TUN in the old client, then quit it from the notification area. Closing the window often only hides the app. If two clients run at once, they may overwrite the same system proxy settings or compete for the same local port. After installation, launch the new client normally. You don't need to run it as administrator just to import a profile; approve system permission only when the client requests it for a network service.

Import a profile, then verify the system proxy

Open the client’s configuration manager, add a subscription or import a local configuration, and wait for it to finish parsing. Then select the imported configuration, switch to Rule mode, choose a proxy group member, and enable the system proxy. In Windows, go to Settings → Network & Internet → Proxy and check the current settings. If the client uses a manual proxy address, make sure the system address and port match the values shown in the client. If your organization’s device gets its proxy settings from a script, ask your administrator before changing them.

Open the target site in a browser that uses the system proxy by default, then compare the result with the client log. A working browser and a failing terminal don't necessarily mean the node is broken. Some command-line tools prioritize environment variables or their own proxy options; some services use WinHTTP. You can run the read-only command below to check the WinHTTP proxy. A direct connection there doesn't rule out the browser using a proxy. For browser and terminal checks, see Troubleshooting the system proxy by app.

netsh winhttp show proxy

To check a local listener, you can give a tool a proxy address without changing system settings. If the example at the end of this guide is loaded and uses its mixed port, run the command below. The example routes traffic direct, so an HTTP response only confirms the request reached the local listener; it doesn't prove a remote proxy node is working. With your own profile, use the port shown in the client.

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

Enable TUN only when needed

If the target app ignores the system proxy, first turn the system proxy off to test it separately, then enable TUN if your client supports it. Follow the client's steps to install or enable the service when prompted, then wait for the virtual interface and routes to be ready. Make a new connection and check the logs; don't judge the change using an old download or call that has been running for a while. If the network drops after enabling TUN, turn it off immediately, check whether regular connectivity returns, and then inspect service startup errors.

If your PC also runs a corporate VPN, virtual machines, or containers, check whether they can coexist without changing your organization's network policies. If external sites work but internal domains don't, test internal IP addresses and name resolution separately to see whether traffic routing or internal DNS is the issue. Don't reset the whole network just to switch modes. That removes useful differences, makes the problem harder to reproduce, and may break existing connections.

Troubleshoot sleep, port conflicts, and lingering processes

After waking from sleep, check that the client is still running and make a new request before treating an old connection timeout as a broken profile. If the system proxy still points to localhost after the client exits, the browser may lose connectivity. Turn off traffic routing in the client and restore the system proxy to its previous state; don't automatically switch a managed work device to direct access. If a port is already in use, quit the old client using it or change the port in your current client, then update any tools configured with the old address.

macOS: architecture, network services, and waking from sleep

Choose the right build for your chip and launch it once

Get Clash Plus from the macOS downloads. You can also choose Clash Verge Rev or FlClash based on configuration compatibility. ClashX Meta is no longer maintained, so keep a backup of your existing configuration before migrating. Open About This Mac from the Apple menu and check whether the hardware is listed as Apple silicon or Intel, then choose the matching architecture. An app launching through a compatibility layer doesn’t mean its networking components will work there too. Use a build for your architecture whenever one is available.

If the download is a disk image, open it, follow the instructions to move the app to Applications, eject the disk image, then launch the app from Applications. For a system installer, follow its installation steps. If macOS blocks the app from opening, verify where it came from and why it was blocked, then follow the system’s guidance rather than disabling security protections globally. When upgrading, fully quit the old app and keep your existing configuration. Otherwise, an old background process may keep running and make the new version appear broken.

Import a profile and check the active network service

In the client’s configuration manager, add a subscription or import a local file, then select it as the current configuration. If a migrated file references rule sets in other directories, fix those references before enabling traffic capture. Turn on Rule mode and the system proxy, then open System Settings → Network, select the service currently connected to the internet, and check its proxy settings under Details. Wi-Fi and Ethernet may have separate proxy settings. After connecting a dock, check which service is carrying traffic instead of checking Wi-Fi alone.

Open one expected-direct and one expected-proxy destination in a browser, then compare their matched rules in the log. If a terminal tool behaves differently, check its own environment variables and options before changing nodes. The read-only command below shows the current system proxy configuration. Its output tells you how the proxy is set, not whether a particular process uses it. Confirm traffic through the local listener with a new request.

scutil --proxy

Some networks use a proxy auto-configuration (PAC) script to decide which requests need a proxy. If both automatic configuration and a manual address are set, don't assume a single toggle tells you the final route. Note the original settings, keep anything required by your work network, and compare requests to different domains. If a managed configuration profile enforces the settings, ask your administrator instead of repeatedly overriding values that the system restores.

Isolate variables before enabling a virtual interface

If the target app ignores the system proxy, try TUN using the current client's implementation. Clients may use different network components, so follow the permissions and steps shown by your client and system rather than copying another app's instructions. Keep a working system-proxy setup as your baseline, turn it off, test TUN separately, and make a new connection in the target app. This confirms the new route works without an old browser proxy setting masking the problem.

If remote proxies work but local printers, file shares, or internal sites don't, test local IP addresses and internal domain names separately. If an IP address fails, check routes and subnets; if only the name fails, check which DNS resolver is used. A direct rule for a domain only controls the outbound route for traffic that has reached the client; it doesn't restore system service discovery. If you need the work network, turn off TUN and confirm the original network works before changing settings one by one.

Make a fresh connection after switching networks or waking your Mac

Switching from Wi-Fi to Ethernet or waking a laptop from sleep can invalidate existing sessions even if the menu bar icon looks unchanged. Make a fresh request and check whether the client receives it. If subscription updates also fail, check that the current network's sign-in is complete and the system clock is correct. If only an app that was already open is stuck, reconnect that app instead of changing DNS, switching nodes, and reinstalling the client all at once.

Before uninstalling or switching clients, turn off the system proxy and TUN, then quit the app. If you enabled a proxy on multiple network services, check each one to make sure it has been restored. Keeping a screenshot or written record of the previous settings is safer than turning off every proxy option after something breaks—especially on managed devices, where disabling a required proxy can also cut off network access.

Android: install an APK and route traffic with VpnService

Check architecture, installer source, and existing apps

Start with Clash Plus from the Android downloads. If you need to use an existing Clash Meta profile, compare compatibility with Clash Meta for Android and FlClash. Surfboard is also listed, but use a profile format it supports—don't just rename another client's profile and import it. Check the ABI supported by your device's operating system: a 64-bit processor doesn't guarantee the system can install 64-bit apps. If the client offers a universal build, follow the downloads page instructions.

When you open an APK from a browser or file manager, Android may ask you to allow app installs from that source. Grant permission only to the app you're using to open the APK, and revoke it after installation if you like. If installation fails, check the Android version, architecture, storage space, and device management restrictions. An app with the same package name but a different signing key can't be installed as an upgrade. Don't uninstall as a first step: you could lose subscription details and manual changes, so export a backup first.

Load a profile before granting VPN access

Add a subscription in the client's profile list, or import a profile stored on your device using the system file picker. After importing, return to the list and select the profile you want to use. Make sure the proxy group has an available member before connecting. When Android asks to set up a VPN connection, check the requesting app's name before approving. Once permitted, the client can create a local VPN interface through VpnService. This is separate from the remote proxies in your subscription: the system VPN indicator only means traffic routing has started, not that a proxy node is reachable.

The Wi-Fi Proxy setting on a phone usually applies only to the current Wi-Fi network and is separate from the VPN started by a client. When using VpnService, you don’t also need to set a local proxy for Wi-Fi. After enabling traffic capture, test the app you want to use—not just a browser. If the client lets you choose which apps use the VPN, check that the app isn’t excluded and is included in the allowed list. For work profile apps, check the settings in the corresponding profile.

Check for another VPN and always-on settings

Another VPN may already be controlling traffic capture in the same user or profile. If the connection stops as soon as you grant permission, open Android Settings, search for VPN, and check which app is connected and which is set as Always-on VPN. Work security tools, DNS apps, and local filtering apps may also use the VPN interface. If your device is managed, check your organization’s policy before disconnecting a work VPN.

If you enabled Block connections without VPN, Android may also block regular internet access when the client stops. First check who manages this setting and whether you’re allowed to change it to restore connectivity. This system-level setting differs from a rule that rejects traffic: the system setting blocks connections that don’t use the VPN, while the client’s rule handles requests that have already entered it. Confusing the two can leave you unable to browse even when there’s nothing in the client’s connection log.

Tell background interruptions, network changes, and subscription updates apart

If the connection drops with the screen locked, note what triggers it: screen off, clearing recent apps, low battery, or switching from Wi-Fi to mobile data. After unlocking, check the system VPN status, client notification, and new connection log. If it only fails when switching networks, test both networks first instead of disabling every battery restriction. If the system is stopping the client in the background, adjust only that client's background permissions using the settings available on your device. See VpnService permissions and battery optimization for common symptoms and settings.

Scheduled subscription updates and keeping a connection alive are separate features. If the client can still connect but doesn't update while the screen is locked, bring it to the foreground and refresh manually, then check the result. Only if manual refresh works should you investigate background task restrictions. If it fails manually too, check the subscription URL, network, and parsing errors instead. Run a brief test on both Wi-Fi and mobile data, and keep a working profile so you aren't relying on a remote update to restore your connection while out.

iOS: App Store installation, subscription import, and VPN status

Install from the platform link and check existing VPNs

Use the iOS downloads link to open the Clash Plus App Store page and install the app. Before installing, check the system requirements on the store page and whether family or organization management restricts app installs. If your phone already has a work VPN, note its name, purpose, and current status. Installing a client and adding a personal VPN are separate permissions; installation doesn't mean your organization allows changes to the device's network settings.

After opening the app for the first time, stay on the profile management screen. If this is your first client of this kind, you don't need to set an HTTP proxy for Wi-Fi just to route traffic from the browser or other apps. A Wi-Fi proxy applies to a specific network and apps that honor that setting; switching hotspots or using cellular data takes a different route. For everyday use, test with the system VPN created by the client so two proxy settings don't interfere with diagnosis.

Check that the subscription loaded, not just that its URL was saved

Add a subscription URL using the client's import option. If you use a profile saved in the Files app, make sure it's downloaded to your device and that the client can read it through the file picker. Profiles from desktop clients need extra attention: they may reference local rule-set paths, use protocols available on only one platform, or rely on configuration merge features. Seeing a profile name only means an entry was created. Select it and check that its rules and proxy groups appear to confirm the contents loaded.

If your subscription service offers multiple export formats, choose one supported by your client. Don't keep forwarding the URL from chat previews or screenshot an editor showing the address. If import fails, find out whether the problem occurred while fetching or parsing: for a fetch failure, check the URL, network, and service status; for a parse failure, check whether the response is a web page, uses the wrong format, or includes unsupported fields.

Add the system VPN and verify the active connection

After loading the configuration and choosing a policy group member, start the connection in the client. The first time you connect, iOS may ask to add a VPN configuration. Check which app is making the request and confirm as prompted. Then search for VPN in Settings and check that the active connection matches the client. On some systems, VPN settings are also under General in the device management section. If the client says it’s connected but the system status doesn’t match, stop the connection in the client and check whether another VPN is in control.

A VPN status of Connected only confirms that the connection was established at the system network layer. Make a fresh request in Safari and in the app you actually need, then check the selected outbound in the connection log if available. If only Safari behaves unexpectedly, note whether other privacy or filtering features are enabled on the current network and compare with another app. Don't declare everything broken based on a single IP-check page. The traffic managed by iOS and the requests visible to the client may not be identical.

Distinguish captive portals, cellular switching, and automatic connection

On hotel or campus Wi-Fi that requires browser sign-in, disconnect the VPN, complete the captive portal, and confirm regular web access before reconnecting. If subscriptions won't update over cellular, check that iOS allows the client to use cellular data, then test the same URL and profile. DNS and access conditions can differ between Wi-Fi and cellular, so an error on one network doesn't mean the profile is corrupted.

If the VPN reconnects automatically after you disconnect it, check whether on-demand connection is configured or a device management policy is restarting it. If you're allowed to change this, disable one automatic connection setting at a time and retest. Existing sessions may still use a route that stopped working after a network switch. Verify with a fresh web request, then check whether the original app needs to be reopened. Before returning to a work VPN, stop the personal connection and confirm the system shows the correct profile before opening work apps.

Linux: distribution packages, desktop proxies, and routing

Choose between a desktop client and a standalone core

On a Linux desktop, start with Clash Verge Rev in the Linux downloads, then compare with FlClash. Choose a package that matches your distribution's package system and the formats offered. Debian and Ubuntu generally use DEB; distributions that use RPM need a compatible RPM. Check your architecture and distribution with the command below before installing. AMD64 in a package usually corresponds to x86_64 on the system, and ARM64 usually corresponds to aarch64. A matching architecture doesn't guarantee all dependencies are present, so check the distribution requirements too.

uname -m
cat /etc/os-release

Install a local package with your distribution's software installer or package manager and let it report missing dependencies. Don't force installation across distributions just to bypass an error. The standalone Mihomo core is better suited to servers, routers, or headless environments; it won't configure desktop proxy settings or provide a desktop client's subscription manager. If you only need a profile for your current desktop session, choose a client first rather than registering a separate core service.

Import and select a profile as your desktop user

Launch the client normally from the app menu and add a remote URL or open a local file in its profile manager. Don't run the entire graphical app with elevated privileges to fix an import error. That can put the profile in a different user's home directory or prevent your regular user from writing to it later. After parsing, check the active profile and proxy groups. If a file is missing, check whether its referenced path belongs to another machine or user, then distinguish a failed remote rule-set download from a local file permission issue.

After enabling the system proxy, check the address in your desktop environment's network settings. GNOME, KDE, and other desktop environments differ in where proxy settings live and which apps receive them. Terminal processes don't necessarily inherit proxy variables when the desktop proxy is enabled. If the browser works but the terminal doesn't, try a temporary proxy option for the command before adding proxy settings to every login session. Containers and virtual machines have their own network boundaries; their loopback address isn't the host's local proxy.

Check TUN requirements one by one

If apps that ignore proxy settings need to use the client, turn off the desktop system proxy and test TUN separately. First confirm the current client supports it, then enable the required service and permissions as prompted. Use the read-only command below to inspect interfaces and routing policy after enabling it. Ideally, run it both before and after so you can compare whether an interface appeared and routes changed. The main routing table may not show policy routing, and an interface being present doesn't prove the target request is using it.

ip -brief link
ip rule show
ip route show table all

Software in a restricted environment may not have permission to access the TUN device or change routes. First identify whether the restriction comes from the system, a container, or the packaging method. Don't grant the entire client unrelated privileges. Take extra care on remote hosts: changing the default route can disconnect your management session. If you don't have local console access and a recovery path, use an app-level proxy until you can restore network access independently.

Check DNS paths and background instances

If an IP address is reachable but its domain name isn't, compare system DNS resolution with the resolution used by the target app. On systems using systemd-resolved, run resolvectl status to see DNS settings for each interface. On distributions without that service, use the network management tool in use. DNS in the profile isn't necessarily where every app gets its answers. Browser, VPN, system, and client DNS may each follow a different path; identify which one is failing before making changes.

Finally, check for an old command-line core or user service still running. Desktop startup entries and system services can launch separate processes, and closing a window doesn't always stop a background instance. If a local listener reports a port conflict, check whether the old instance is still needed for another task before stopping it or changing ports. To roll back, stop traffic routing the same way it was started, restore the desktop proxy settings, and test the regular network. Don't delete the entire profile directory first; you'll lose the evidence needed to compare before and after.

Configuration FAQ: updates, rules, and DNS

Subscription update failed. Should I delete the profile?

Keep any profile that's still working. Refresh manually once and note whether the error occurred during connection, server response, or local parsing. For a connection timeout, test on a network known to work. If the client lets you choose an outbound for update requests, check that a new device with no prior connection can still fetch the profile. For an authentication error, ask the subscription provider whether the URL has changed. If you receive a web page or empty response, don't try to fix it by changing the file extension; confirm that you got the right content.

If an update succeeds but the rules don't take effect, check which profile is selected, when it was updated, and whether the client reloaded it. Manual edits to subscription-generated content may be overwritten at the next update. For persistent custom rules, use an override method supported by your client. If it has none, keep a separate local copy and remember that it won't update with the subscription. For more symptoms, see the FAQ.

How can I tell if traffic reached the client but matched the wrong rule?

Make a fresh request to a known destination. If there's no connection log, check the entry point, port, or app coverage first. If the request appears but takes the wrong route, check the active mode and the first matched rule. Rules in rule mode are checked in order; a broad rule before a specific one can prevent the specific rule from ever matching. A matched rule only selects an outbound. If it points to a proxy group, check which member is actually selected.

Below is a minimal direct-connection test profile for mihomo. Save it as a separate local profile; don't overwrite your subscription. It listens on a loopback address and mixed port, uses a domain-suffix rule to reject example.org, and sends other requests direct through the final rule. If the port is in use, choose an available one and update your test tool. If the desktop client overrides local ports, use the value shown in its interface.

mixed-port: 7890
bind-address: "127.0.0.1"
allow-lan: false
mode: rule
log-level: info
rules:
  - DOMAIN-SUFFIX,example.org,REJECT
  - MATCH,DIRECT

Use the local proxy to visit example.org and example.com separately, then compare the rejection and direct-connection results. This test doesn't need a remote node; it only checks the entry point and rule order when a tool explicitly uses the local proxy. If both requests fail, confirm the test process is using the current listener. If both succeed, check for an old profile, global mode, or existing connection. Switch back to your original profile when you're done.

Fake-IP causes DNS issues. What should I check first?

First confirm that the app's DNS requests pass through the client. Fake-IP uses temporary mapped addresses to preserve domain names, then lets the client route connections according to its rules. Seeing a mapped address isn't itself a problem. Check whether the app received the address but its later connection bypassed the client, or whether a local service that needs a real address is using an unsuitable DNS path. Don't change every upstream DNS server just because you see a mapped address.

If only local network devices are affected, compare connecting by device IP address with connecting by device name, then check whether those domains need DNS exceptions. fake-ip-filter determines which queries skip this address-mapping method; nameserver-policy selects a DNS server for specific domains. Neither replaces traffic routing rules. After changing settings, test with a new request and account for cached results in the system and app. For details, see DNS routing tests and configuration.

Latency tests pass, so why can't the app connect?

A latency test only checks a node against a particular test destination. It doesn't prove that every destination, protocol, or app will work. First test the actual destination with the same node, then compare another node against the same destination, and finally compare the same app across networks. HTTPS working doesn't mean the UDP path needed by voice or real-time apps works. Connection logs, error types, and results with traffic routing disabled are more useful than repeatedly rerunning latency tests.

To restore your network, first turn off the traffic routing method you enabled and return to your original proxy and DNS settings. Once basic connectivity is back, load the last profile that worked. To keep troubleshooting, return to the Quick Start and repeat the steps for importing, choosing a group, connecting, and verifying. Record an observable result at each step; the first one that differs from before is where to focus next.