Clash Setup Guide
for Every Platform

Before you begin: configuration sources and traffic routing

Know the difference between the client, core and subscription

The client provides the interface for managing configurations, starting the core, setting up a proxy and viewing connections. The core parses protocols, matches rules and forwards traffic. A subscription is a source of configuration and may include nodes, policy groups, rules and DNS settings. Installing a client does not give you a working proxy endpoint. Before you start, get a valid subscription URL from your provider or a YAML file compatible with your chosen core.

This guide uses Clash Plus as its starting point for client selection. Other clients may use different button labels, but most organize their features around configuration, proxies, connections and settings. Being able to import a configuration does not mean every client supports all of its fields. Check the target core’s supported features, especially for protocol extensions, rule providers and scripts. If parsing fails, start with the field name and line number in the error.

Prepare your subscription and system details

A subscription URL may contain access credentials, so protect it like a password. Never post the full link on a public forum, in a screenshot or on an unfamiliar online conversion site. When asking for help, share only the error type, client name, operating system and network environment. If the link is exposed, ask your provider to reset it. Deleting the local record cannot revoke access someone else has already obtained.

Before installing, check your operating system version, processor architecture and available storage. On desktop, distinguish x64 from ARM64; on Mac, check whether you have Intel or Apple silicon; on Android, confirm that your device supports the ARM64 package. Back up existing configurations and custom rules before switching clients. During testing, quit other proxy or VPN software to prevent conflicts over system proxy settings, virtual network interfaces or DNS.

Choose a traffic routing method

System proxy and TUN are ways to capture traffic; rule-based, global and direct modes determine how that traffic is routed. They operate at different layers. With TUN enabled, you can still use rule mode, and traffic matched as DIRECT may pass through the core before leaving directly. When troubleshooting, check separately whether traffic enters the client and which route it takes afterward. A toggle’s name alone does not prove that a connection is being proxied.

Build a minimal working setup

For your first connection, do just four things: import a subscription, select the configuration, choose an available node and start the service. On desktop, try the system proxy first; on mobile, approve the VPN request. Keep the subscription’s DNS and rules for now, and don’t add overrides, app exclusions or LAN sharing at the same time. Once it works, note the network, node and routing method. Change one setting at a time so you can tell what made a difference.

Test one site that should connect directly and another that should use a proxy, then check the policy in the connection log. A page loading proves only that this request worked; it does not prove that every app, domain or UDP connection will work. Keep only the information you need. Logs may contain domain names, subscription URLs and local paths, so redact sensitive details before sharing them.

Windows: installation and system proxy

Choose an installer and launch the client for the first time

Visit the Windows downloads section and start by checking out Clash Plus. You can also choose Clash Verge Rev, FlClash or Clash Nyanpasu. Clash for Windows is no longer maintained; its archived download is best treated as a reference when migrating an old setup, not as the default for a new installation. Don’t copy an old client’s folder over another app’s installation—configuration files and interface databases may not be compatible.

Open Settings and go to System → About to check your system type, then choose the matching package available on the downloads page. Quit any existing proxy processes before installing. Run the installer and follow its prompts to choose a location. If Windows asks to allow network access on first launch, verify the app’s source and location before granting permission as needed. Closing the window may leave the app running in the notification area; to troubleshoot a busy port, quit it fully from the tray menu.

Import a subscription and select its configuration

Open the configuration or subscription page, add a remote profile and paste the subscription URL from your provider. Wait for it to download and parse, then select or enable it once its name appears. In some clients, “added” means only that the profile was saved to the list—not that the core has loaded it. You should see policy groups on the proxy page. If the list is empty, first check that the right profile is selected and that the subscription returns Clash-compatible content.

Open a policy group and choose a specific node for your first test. An automatic selection group may rely on connectivity checks, which can take time after import; don’t assume all nodes have failed just because the results aren’t ready yet. Save custom rules before updating a subscription, since an update may replace the remote profile. For local settings you need to keep, use the client’s override or extension feature rather than editing cached files directly.

Enable the system proxy and check the listening port

Start the core, then turn on System Proxy. This usually sets Windows to use the client’s loopback address and port. Reconnect your browser before testing; existing tabs may reuse old connections. If a browser extension also manages a proxy, disable its proxy controls first to avoid sending requests elsewhere. Apps with their own proxy settings usually won’t follow the system toggle automatically.

The mixed-port example below accepts both HTTP and SOCKS proxy connections. It shows only how to listen locally; it contains no nodes and is not a complete subscription. Use the port in the client’s active configuration. If the interface uses a different value, don’t edit your subscription just to match the example. A loopback listener accepts connections only from the same device, making it a good starting point for testing the basic connection path.

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

Once you’ve confirmed the port, use the command below in PowerShell to test the HTTP proxy directly. The command specifies a proxy explicitly, so it doesn’t depend on the system proxy toggle. If it works but the browser doesn’t, check the browser and system settings first. If it can’t connect to the local port, check whether the core is running and listening on the right address before changing nodes. A successful request still needs to be checked against the connection log to confirm its actual route.

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

TUN, service permissions and restoring settings on exit

Consider TUN only when you need to capture traffic from apps that ignore the system proxy. Some clients require a service component or administrator permissions for initial setup; follow that client’s prompts. After enabling it, check the virtual network interface and connection log. If the whole system suddenly stops resolving domains, disable TUN to restore your baseline, then check DNS, route conflicts and security software. Avoid changing several network settings at once.

You don’t need to disable the Windows Firewall altogether for everyday use. If security software blocks the client, add rules only for programs whose source you’ve verified and the network access they actually need. Routes may stop working after the computer wakes from sleep, switches Wi-Fi networks or connects to a company VPN; try stopping and restarting the core first. For automatic startup, make sure manual startup is stable before enabling launch at login and automatic proxy mode, so a problem doesn’t start with every boot.

Turn off the system proxy before quitting the client. If the app crashes, check Settings → Network & Internet → Proxy for a leftover manual proxy setting. Apps that follow the proxy may lose access to the internet if the client has stopped but Windows still points to its local port. LAN sharing also requires the right listening address and inbound firewall rules. See the mixed port and LAN sharing guide; simply turning on a “allow LAN” option isn’t enough.

macOS: processor architecture and network permissions

Choose a client for your Mac’s processor

Open the Apple menu and select About This Mac to check whether it lists a chip or an Intel processor. Then visit the macOS downloads section and choose the matching package. Clash Plus is a good place to start; Clash Verge Rev and FlClash are also options. ClashX Meta is no longer maintained. If you’re migrating, back up your subscription and rules first; an old app still launching doesn’t mean it can handle newer configuration formats.

Open the downloaded disk image and drag the app into Applications, then launch it from there. Don’t keep running the copy inside the disk image; updates, permissions and startup settings may otherwise point to different locations. If macOS blocks the app, verify where you downloaded it, then check the specific warning under System Settings → Privacy & Security. Don’t run commands from unknown sources to disable system security features in bulk.

Import a remote profile and confirm it loads

Open the configuration page, add a remote subscription, enter a name and paste its URL. After saving, wait for parsing to finish, then make it the active profile. To import a file, use the file picker to open the YAML and check whether the client copies it or continues to reference its original path. If you later clear the Downloads folder, a profile that still points there may fail to reload. Store files you need to keep in a stable location.

Check that policy groups appear, then manually choose a test node. A successful profile update confirms only that the subscription request and parsing worked—it does not prove that the node can connect. Check node availability before enabling traffic routing. If the subscription opens in a browser but fails in the client, check whether they use different proxy paths and whether the system clock is correct. Never expose the full subscription URL on a public page.

Understand the system proxy for the active network service

When you enable the system proxy, macOS usually changes the HTTP, HTTPS or SOCKS proxy settings for the active network service. Wi-Fi and Ethernet may be separate services, so check again after switching networks. Some terminal tools use only environment variables, while other apps have their own proxy settings. It’s possible for a browser to work while a terminal tool fails; first find out which proxy method the app uses.

Use the read-only command below to check the current system proxy settings, including whether they’re enabled and whether the address and port match the client. This shows the system configuration; it doesn’t guarantee that every app follows it. If the address belongs to a client that has already quit, turn the system proxy off and back on in the current client. If that doesn’t help, check each proxy setting for the active network service.

scutil --proxy

Temporarily specifying a proxy for a single terminal command is easier to troubleshoot than changing your global shell configuration. The command below affects only that invocation; make sure its port matches the client’s current setting. If you’ve set proxy variables in a shell startup file, check for stale values too. Closing the GUI client won’t remove them, so tools may keep trying to connect to a local port that is no longer listening.

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

Resolve TUN permissions and network changes

TUN may require the client to install a helper service, authorize a network interface or approve a system extension. Follow the prompts for the client you’re using; don’t install service components from other clients as a workaround. If there’s no traffic after authorization, check the logs for permission, interface or route creation errors. These occur before a node connection is attempted, so changing subscriptions usually won’t help.

A company VPN, another network filter or a virtual machine can cause route priority or DNS conflicts. Test with just one traffic-routing tool enabled, then restore other components one at a time to find the cause. On a company-managed device, follow its existing network policies; don’t delete managed settings to force TUN on. Proxy settings also don’t override every system security or access restriction.

After a Mac wakes from sleep or switches from Ethernet to Wi-Fi, stop and restart the client, then check the proxy for the active network service. Before uninstalling, turn off the system proxy and TUN, then remove any helper service as the client’s instructions specify. Dragging the app to the Trash alone may leave settings pointing to a local port. If your browser can’t connect after uninstalling, check for leftover system proxy settings before resetting the entire network configuration.

Android: VPN permissions and per-app routing

APK installation, updates and configuration migration

Visit the Android downloads section. Start by checking out Clash Plus; Clash Meta for Android, FlClash and Surfboard are also options. Surfboard’s configuration format isn’t fully compatible with Clash YAML, so you can’t assume the same YAML file will work in every client. If your provider supplies only a Clash subscription, choose a client that explicitly supports that format to avoid discovering a mismatch after installation.

When installing an APK, Android may ask you to allow your browser or file manager to install apps. Verify the file source and grant permission only to the installer you’re actually using. If the installer reports a conflict with an existing app, check the package name, signature and source. Back up your configuration before deciding whether to migrate; don’t immediately uninstall an app that still works. APKs signed by different developers usually can’t be installed over one another, and clearing data won’t fix a signature mismatch.

Import a URL and start the VPN service

In a Clash for Android-style interface, open Configuration → New Configuration → Import from URL. Enter a recognizable name and paste the subscription URL. Wait for the update to finish, then select the entry in the configuration list. To import a file, use the system file picker to select the YAML. Downloading a file to your phone doesn’t load it automatically—you still need to import and select it.

Return to the home screen and tap Start. The first time, Android will show a VPN connection request; check the app name and approve it. A VPN icon in the status bar confirms that the VPN interface is up, but doesn’t guarantee that the remote node is reachable. Next, open the proxy page, confirm Rule mode, select a test node, then browse to a site and check the connection log to verify the full route from app to endpoint.

On Android, a regular app can usually be the active VPN service for only one user at a time. If starting the client disconnects another VPN, that’s a system limitation, not necessarily a client bug. Other tools that use Android’s local VPN can conflict too. Work and personal profiles may have separate network policies, so an app in one profile may not be controlled by the client in another. Check which profiles the device management policy covers.

Access control determines which apps use the proxy

Open Access Control or per-app routing in Settings and check whether it’s set to “proxy selected apps only” or “bypass selected apps.” Choosing the same app in each mode has opposite effects. For initial troubleshooting, restore the baseline where all apps use the VPN, then exclude apps one at a time. If the browser works but an app has no connection log entries, check the app list and its profile before blaming the node.

“Bypass private networks” usually affects routing to LAN addresses, which can help with routers, printers and local devices. Check it against your configuration rules; it doesn’t let other devices use your phone as a proxy. “Allow apps to bypass” is a separate feature at the Android VPN layer, and its behavior depends on the client. Read what each setting does before changing it so you don’t confuse options that operate at different layers.

DNS interception and background activity

DNS interception usually routes DNS requests entering the VPN to the core, but it can’t guarantee control over encrypted DNS connections that an app creates itself. A browser’s Secure DNS setting or Android’s Private DNS may send lookups along a different path than expected. Note your current settings, then temporarily restore the system defaults for comparison. Don’t change the node, DNS mode and rules all at once, or you won’t know which change helped.

If connections drop when the screen turns off, check whether battery settings restrict the client’s background activity, then look for the manufacturer’s autostart or background app controls. Names vary across Android versions; adjust this client only rather than disabling power saving for the whole device. Check whether the issue happens only with the screen off, whether reopening the client restores the connection and whether the logs show a process restart. This helps distinguish background app termination from a network change.

Enable Always-on VPN and “Block connections without VPN” only after the connection is stable. The latter blocks network access while the client is stopped or reconnecting, which can make the phone appear completely offline. If LAN access stops working, check for conflicts between the system’s blocking policy and app exclusions. To recover, adjust the VPN settings in Android first, then change the client’s internal rules.

Devices connected to your phone’s hotspot won’t necessarily share the phone’s VPN connection. Hotspot routing, system permissions and proxy listening are separate issues. To share a proxy, configure the device’s LAN address and port, and restrict which devices can reach it. When you’re done, disable the listener if you no longer need it; don’t leave a local proxy port exposed to untrusted networks.

iOS: installation, import and network extensions

Install Clash Plus from the App Store

For iPhone and iPad, Clash Plus is the recommended option. Install it from the Clash Plus App Store page, and visit clashplus.io for product information. Check the current App Store listing for system requirements. Whether you can install the app depends on device compatibility and the store content available to your account—not just the device model.

You can also check the entry in this site’s iOS downloads section first. On first launch, review the app’s configuration and connection screens so you know which client you’re using. The client loads configurations and forwards traffic; you’ll need to obtain a subscription separately. Installing an app doesn’t give you a working node, and network permission requests are separate from purchasing a subscription or authorizing an account.

Import a subscription and handle format differences

Add a remote profile from the client’s configuration or subscription screen and paste the URL from your provider. Wait for the download and parsing to finish. Button names may change as the app updates; look for the action to add a remote subscription. After importing, check that policy groups and nodes appear, then select the profile. If you see only an empty entry, check whether the download succeeded before repeatedly changing VPN permissions in Settings.

When copying a link on a phone, it’s easy to include spaces, explanatory text or a line break. Check the URL locally to make sure it’s complete; don’t upload it to a third-party tool for testing. If it opens a login page, account notice or regular webpage, the client can’t use it as YAML. If your provider offers multiple formats, choose one explicitly supported by your client or its core; a URL’s file extension alone doesn’t establish compatibility.

To import a file, select the actual configuration file in the system file picker and make sure it’s downloaded to your device, not just listed as a cloud placeholder. Whether the client keeps referencing an external file depends on its implementation. Remote rules and node providers may also fetch additional resources. If policy groups are still incomplete after importing the main profile, check whether those resources can be downloaded and reached.

Confirm the VPN configuration and rule mode

The first time you connect, iOS will ask to add a VPN configuration. Check which app is making the request and approve it as prompted; complete device authentication if required. Return to the client and start the connection, then check its VPN status in Settings. iOS uses a network extension for traffic routing. You don’t need to follow Windows administrator-service installation steps or look for a TUN toggle with the same name as the desktop version.

For your first connection, choose Rule mode and explicitly select a node in the policy group. Global mode can help briefly compare results, but it doesn’t replace troubleshooting your rules. If a site works only in Global mode, its rule assignment, direct route or policy group selection may differ. Check which rule matched the request; that’s more useful than leaving Global mode on indefinitely.

Understand app coverage, DNS and on-demand connections

Don’t assume an iOS client offers the same per-app selection list as Android. iOS limits app-level controls on regular devices; available features depend on the client and the device’s management status. To send a category of sites directly, start with domain rules and policy groups. A single app name may not tell you which domains and system services it uses.

DNS can be affected by the configuration, client overrides, system network settings and other network extensions. Some privacy relay and filtering features may also change the network path you observe. Check which components are active before removing system settings. Temporarily test with only the current proxy client, then restore other features one at a time to identify the layer causing a conflict and keep a record of the original settings.

On-demand connection starts the network extension automatically when the client’s conditions are met. Enable it only after manual connections are stable and the subscription updates successfully; specify which networks should trigger a connection. If the VPN stays connected after you close the app window, the extension may simply still be running. To stop it, use the client’s connection toggle or disconnect it in VPN Settings.

Handle network changes and back up configurations

When switching from Wi-Fi to cellular, an existing connection may stop working. Wait for it to reconnect, then test with a new request. On hotel or airport Wi-Fi that requires a web login, complete the network sign-in first; a proxy can’t replace network access authentication. If only one Wi-Fi network fails, compare it with cellular, then check local DNS, network restrictions and node reachability instead of deleting every subscription.

Before switching devices, note the subscription source, policy group selection and any essential overrides. Don’t assume every configuration will migrate fully with a system backup. Exported files may contain node credentials, so keep them somewhere protected. If an update causes problems, check whether the policy group changed and whether remote rules finished loading before rolling back. An old file may no longer work if your provider has retired its nodes.

Linux: desktop clients and core operation

Choose between a desktop and server setup

Linux desktop users can visit the Linux downloads section and start with the recommended Clash Verge Rev; FlClash is another option. For servers, routers and command-line environments, see Mihomo in the downloads page’s core section. A GUI client typically manages the core, configuration and service permissions. Running the core directly means handling its directories, startup, logs and traffic routing yourself, with different maintenance requirements.

Before installing, check your distribution, processor architecture and package format. Debian-based systems usually use deb packages; RPM-based systems need an rpm package actually offered on the downloads page. Renaming a file extension doesn’t make a package compatible. Desktop apps may depend on a display server and system libraries, so they’re not suited to headless servers. If a shared library is missing, check distribution compatibility instead of downloading random files into system directories.

Verify a regular proxy connection after installation

Install the app with your system’s package manager, then launch it from the application menu. If installing from the command line, review the package manager’s list of dependencies and changes first. Add a remote subscription on the configuration page, select it after the update finishes, then choose a node in a policy group. For the first test, run the GUI as a regular user. Grant system permissions only for steps that explicitly require them, such as installing a service or creating a network interface.

The proxy settings interface differs between GNOME, KDE and other desktops, and apps vary in whether they use those settings. A browser may follow the desktop system proxy; terminal tools often need explicit arguments or environment variables. An enabled system proxy doesn’t mean package managers, containers and background services are using it. First confirm that the local port is reachable with a request that specifies the proxy, then set up each app as needed.

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

To use an HTTP proxy with several tools in your current terminal session, you can temporarily set the variables below. Not every tool follows them, and some tools have their own settings. Don’t add them to every user’s startup files before verifying that they work. Unset the variables when you’re done so the terminal doesn’t keep sending requests to a port that stops listening when the client closes.

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

# Unset proxy variables for this session
unset http_proxy https_proxy

Directory boundaries when running Mihomo directly

For a standalone core, first prepare an executable that matches your architecture and install it somewhere on your system’s executable path. The startup command below assumes the system can find a program named mihomo and that a complete config.yaml is in the user’s configuration directory. Check the configuration with a test command, then start it in the foreground and review the logs. Passing syntax checks proves only that the configuration can be read—not that nodes, DNS or remote rule resources are reachable.

mkdir -p "$HOME/.config/mihomo"
mihomo -t -d "$HOME/.config/mihomo"
mihomo -d "$HOME/.config/mihomo"

Directory arguments determine where the core looks for configuration and some runtime data. If it starts from a terminal but fails as a system service, common causes include a different user, working directory, file permissions or environment variables. A service doesn’t automatically inherit proxy variables from an interactive shell. Confirm which configuration path the service actually reads, then check access to subscriptions, rule files and log directories. Avoid repeatedly overwriting different files as a troubleshooting method.

TUN, DNS and container networking

TUN requires permission to create a virtual interface and change routes. GUI clients usually provide a service mode or helper component; follow that client’s installation process. For a standalone core, configure permissions in line with your distribution’s service manager, rather than running the entire desktop app with unnecessary privileges. If the system can’t open the TUN device, check OS support and runtime permissions. This has nothing to do with whether a remote node works.

DNS on Linux may be managed by NetworkManager, systemd-resolved or another component. A DNS listening port in your configuration doesn’t automatically direct every app to use it; you also need the right system resolver path or TUN DNS interception settings. Before changing resolver settings, find out which service manages them—network services may regenerate files you edit by hand. Prefer an integration supported by your client, and keep a record of the original settings so you can restore them.

Inside a container, loopback points to the container itself, not the host. If the proxy runs on the host, 127.0.0.1 inside the container usually won’t reach it. If access across network namespaces is necessary, choose a reachable address, listening scope and access restrictions carefully. Don’t expose the proxy and control interface on every network interface for convenience. Background services also have their own environment settings; test each one separately instead of assuming desktop results apply.

Set up startup on boot only after foreground testing works, then check service status and logs after a reboot. When stopping the service, also restore system proxy, routing and DNS settings, and confirm that direct access still works. If you manage a server remotely, keep the current session and a recovery method available before changing the default route, so you don’t cut off your own management connection. Most desktop users don’t need to maintain a full core service by hand; a GUI client is usually easier to manage.

Common setup issues: troubleshoot by following the connection path

For subscription failures, separate download problems from parsing errors

An “update failed” error can happen while requesting the URL, establishing a connection, receiving content or parsing YAML. First check whether the error is a timeout, certificate issue, permission denial or a field or syntax error. For network errors, check the current network, system clock and request path. For parsing errors, inspect the returned content and format compatibility. Changing DNS won’t fix missing indentation, and rewriting YAML won’t revive an expired link.

A link may behave differently in a browser and the client because the browser uses an existing proxy, saved login session or different request details. A link opening in a browser alone doesn’t prove the client is at fault. If updates rely on the current proxy while the active configuration is already broken, the client may be unable to recover itself. Configure the download path using the options the client supports. For specific cases, see how to troubleshoot expired subscriptions and parse errors.

Rule order and override scope

Rules are generally checked in order; the first match uses its corresponding policy, and the final MATCH rule catches connections that haven’t matched anything else. The example below is a snippet, not a complete working subscription. Replace PROXY with a policy group that actually exists in your configuration; a mismatched group name may prevent the configuration from loading. Domain rules need domain information, so connections made directly to an IP may not match domain entries as expected.

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

A client override may replace an entire section or merge fields; don’t assume how it works based only on YAML indentation. After remote rules, custom rules and interface settings are combined, check the final runtime configuration or the rule actually matched in the connection log. If custom content disappears after a subscription update, you may have edited a file managed by the remote profile. Put persistent rules in a local extension point the client explicitly supports, and back them up.

Troubleshoot DNS, Fake-IP and ports separately

Fake-IP assigns virtual addresses to some domains, which the core later maps back to their domains. These are not real node addresses. If an app has compatibility issues, first check whether its DNS requests reach the core, then see whether the app has cached an old result. Don’t put cached virtual addresses into long-term IP rules. After changing DNS mode, start a new connection and, if needed, clear the app’s DNS cache before comparing results.

The behavior of nameserver, fallback and filtering conditions depends on the full DNS configuration; adding several public DNS addresses at random isn’t an optimization. In particular, avoid relying on an upstream DNS server to resolve a proxy server’s hostname if that connection already depends on the proxy—this can create a resolution loop. For a field-by-field explanation, see the DNS fields and interception guide. Keep a working copy of your configuration before testing changes.

LAN sharing and the control interface

A mixed port accepts app proxy traffic; the control interface manages the core. They serve different purposes. To share a proxy with another device, listen on a reachable address, enable LAN access and configure firewall rules for the appropriate range. You don’t need to open the control interface. The other device should use the LAN address of the device running the client, not its own loopback address. Check that the network is trusted and turn off the listener when you no longer need to share it.

Keep only essential details and make troubleshooting reproducible

During testing, note the operating system, client, routing method, affected app and time of failure, then change just one condition. A successful node check doesn’t mean every protocol, site and UDP connection works; a page loading doesn’t mean background apps work either. Check in order whether traffic enters the client, whether the right rule matches and whether the endpoint is reachable. Then change the relevant layer instead of cycling through unrelated settings.