Complete Clash Setup Guide for All Platforms

Getting Started: Clients, Subscriptions, and Configuration Basics

Understand the Difference Between the Client, Core, and Connection Service

The Clash ecosystem includes graphical clients, proxy cores, and configuration formats. A graphical client imports subscriptions, selects outbound proxies, and requests system permissions; the core parses configuration, matches rules, and establishes connections. mihomo is a commonly used core, but that does not mean every client supports the same fields. Subscription protocols, the bundled core's capabilities, and configuration conversion must all be compatible. Pay particular attention to newer transport options and DNS fields.

Installing a client does not give you a working connection. Before you begin, get a subscription link from a trusted service provider, or a local YAML file containing outbound proxy definitions. Check the permitted usage, expiration, and device limits. Start with Clash Plus from the client downloads page. If you need a different interface or deployment method, compare options such as Clash Verge Rev and FlClash for your platform. Avoid running multiple proxy cores at the same time.

Check Your Device Architecture and Record Your Network Settings

Before downloading, note your operating system, processor architecture, and installation permissions. On desktop, distinguish x64 from ARM64; on macOS, check whether you have an Intel or Apple Silicon processor. On Android, choose a package that matches the instruction sets supported by your device. An architecture mismatch usually prevents an app from installing or launching; it is not a subscription issue. Before installation, record any existing VPNs, manual proxy settings, corporate network software, and custom DNS so you can restore them if new settings overwrite them.

Keep a copy of your working configuration and client overrides. Subscription URLs may contain account identifiers, so redact the full address in screenshots, support tickets, and public repositories. Exported local YAML files may also include passwords. For multi-device sync, keep provider-managed subscriptions separate from your own overrides. Direct edits to generated subscription files may be lost on the next update. See the multi-device configuration sync guide for a better way to manage them.

Understand What System Proxy and TUN Route

System proxy provides a local HTTP or SOCKS endpoint for apps that follow the operating system's proxy settings. It does not guarantee that every game, command-line tool, or UDP flow will use that endpoint. TUN routes traffic through a virtual network interface and usually requires a service component or system authorization. They solve different problems: establish a verifiable baseline with system proxy first, then enable TUN if your apps require it. This is easier to troubleshoot than turning on every option at once.

The common fields below work with typical mihomo configurations. The mixed port accepts both HTTP and SOCKS connections; when bound to a loopback address, it is available only on the local device. This example has no outbound proxy, so it is for comparing settings only—not for testing proxy access. If the client generates the port or listening address through its interface, check the final values in the running configuration, not just the subscription file.

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

What to Check After Importing a Subscription

After adding a link, update the subscription and then set the new configuration as active. Make sure the expected proxy groups appear, open the relevant group, and select an actual outbound proxy. An “Auto Select” group also needs at least one working member. A successful download only means the configuration was retrieved; it does not prove that a proxy can connect. If the download fails, check the system clock, confirm the URL is complete, and see whether your provider requires a specific subscription format. Use the client's import feature where possible, and avoid sending links through arbitrary third-party converters.

Next, use rule mode to test a request that should go through a proxy. Check the connection log for the matched rule and final outbound proxy. Test a request that should connect directly as well. Change one variable at a time and record the results. A page loading in your browser does not mean every app is routed, and a changed exit IP alone does not confirm that DNS is working as intended. Verify the request, rule, and DNS resolution paths.

Windows: Installation, System Proxy, and TUN Service

Choose the Right Installer and Launch the Client

Check your system type in Windows Settings under System Information, then choose a package that matches the architecture and system requirements listed on the download page. Clash Plus is a good starting point; you can also choose Clash Verge Rev, FlClash, or Clash Nyanpasu to suit your workflow. Clash for Windows is no longer maintained. It may help when identifying legacy configurations or planning a migration, but menu locations in old tutorials may not match current clients. Before installing a new client, exit the old one and turn off its system proxy.

If the installer requests elevated privileges, first verify where it came from and what it wants to do. The regular graphical app and a background service that requires administrator access are separate components; you do not need to run the interface as administrator every time. After the first launch, check that the core starts normally. If the window opens but pages such as Configuration or Logs keep reporting connection errors, check the local core process and controller connection before reinstalling Windows or repeatedly changing subscriptions.

Import a Configuration and Set Up a System Proxy Baseline

Open the Subscription or Configuration page, paste the complete URL, and download it. Give the configuration a recognizable name, then select it as the active configuration after updating. Open the Proxies page, choose a group, and select an actual outbound proxy. Then return to Settings and enable the system proxy. If your browser has a fixed proxy configured or uses a proxy-switching extension, temporarily set it to use the system settings; otherwise, the client's system proxy toggle may not affect it.

Keep rule mode enabled for testing. Open the connection log and check the destination domain, matched rule, and outbound route instead of relying on the tray icon. To test the local HTTP endpoint explicitly, run the command below in PowerShell. It uses curl.exe to avoid differences in how PowerShell environments interpret the shorter command. A successful request confirms only that the specified endpoint works; it does not mean other apps automatically follow the system proxy.

curl.exe --proxy http://127.0.0.1:7890 --head https://example.com
Get-NetTCPConnection -LocalPort 7890 -State Listen

Install the TUN Service Only If You Need It

Use TUN if a target app ignores the system proxy or needs more of its traffic routed. Some clients require you to install a service component before enabling TUN. Service installation, service status, and TUN status are three separate things. After granting permission, check the virtual network adapter, routes, and initialization messages in the logs. If TUN fails to start, restore the system proxy baseline, inspect the specific error, and then check permissions, drivers, or service status. Don't keep clicking Install without checking the result.

TUN may compete for routes with other VPNs, virtual machines, container networks, or corporate security software. For troubleshooting, leave only one traffic-routing tool enabled at a time and note which software you turned off. Avoid changing the default route on a remote desktop or managed work device, as this could disconnect your management session. If company policy blocks service installation, follow your organization's device requirements; disabling all security software is not a general fix.

Troubleshoot Ports, Leftover Proxy Settings, and Permissions

If the log reports a port conflict, use the listener query above to identify the process, then find out which application it belongs to. Don't terminate an unknown system process. You can close duplicate client instances or choose an unused port in the client settings. If you change the port, update manual proxy settings in your browser, terminal, and code editor as well. If the configuration and interface overrides disagree, use the core's actual listening value.

If your browser loses internet access after the client exits, Windows may still be configured to use a manual proxy at a local port where the core is no longer listening. Open the Proxy page in Windows Network settings, check whether manual proxy is still enabled, and restore the settings for your network. If only one app has a problem, check its own proxy settings, background processes, and cached connections. One failing app does not prove that TUN or the subscription is broken.

Before upgrading, back up your subscription list, override files, and essential settings. After the upgrade, check the service status and startup behavior. If the connection drops after waking from sleep or switching Wi-Fi networks, reconnect the client and check for route changes before restarting the service. For a detailed walkthrough and common errors, see the complete guide to installing Clash Verge Rev on Windows. Menu names may differ in other clients.

macOS: Chip Architecture, Network Permissions, and Proxy Recovery

Choose and Install a Client for Your Mac

Open About This Mac to check your chip or processor, then choose a matching installer from the macOS downloads section. Clash Plus is a good starting point; you can also use Clash Verge Rev or FlClash. ClashX Meta is no longer maintained, so check core-specific fields when migrating an old configuration. Don't judge architecture by the app icon or file size alone. An app that launches through translation is not necessarily the best build for your Mac.

Follow the installer's instructions to move the app into Applications, then launch it from there. Avoid running it long-term from a disk image or temporary downloads folder. If macOS warns about the app's source or permissions, verify the download and app details, then follow the system's normal authorization steps. Disabling system security entirely is not an installation step. After the first launch, make sure the menu bar, configuration, and log views all open before importing a subscription.

Import a Subscription and Confirm the Active Network Service

Add the remote subscription from the client's configuration manager, update it, and set it as active. Select an outbound proxy in the proxy group. If the client has several configurations, name them so you can tell their provider and purpose apart. Leave TUN off at first; enable the system proxy and test with a browser. If the configuration download fails, check the link, system clock, and network connection. A URL that displays text in a browser may still use a format the client cannot read.

macOS proxy settings are tied to network services. Wi-Fi, Ethernet, and other interfaces may each have their own settings, so check again after switching interfaces. If the client says the system proxy is enabled but requests don't appear in the connection log, confirm which network service is active and whether the app uses the system proxy. Browser extensions, development tools, and command-line environments may have their own proxy settings. The menu bar status alone cannot tell you how every request is routed.

scutil --proxy
curl --proxy http://127.0.0.1:7890 --head https://example.com
lsof -nP -iTCP:7890 -sTCP:LISTEN

The commands above show the current proxy settings, explicitly test the local HTTP endpoint, and identify the process listening on a port. Terminal apps generally don't inherit the graphical system proxy automatically, so a browser working while a terminal fails is not contradictory. To proxy a specific command, use its own proxy option where available. If you use environment variables, remember they affect only the current terminal and its child processes—not the whole system.

TUN Authorization and Background Components

Use the client's TUN feature if you need to route apps that don't follow the system proxy. Depending on the client, it may use a privileged helper, background service, or system networking feature; permission prompts vary. Read each system prompt and confirm which app is requesting access. After authorizing, check that the client reports successful initialization. If a background component cannot run, switching outbound proxies repeatedly won't help. Check the service or network authorization first.

TUN may conflict with route rules from an existing VPN, content filter, virtual network, or company-managed configuration. Record the current setup, then disable nonessential routing components one at a time to compare results. When connecting to a work network remotely, check requirements for internal domains and private subnets. Routing all traffic through a proxy may make internal resources unreachable. Manage required routes and DNS rules explicitly rather than relying on launch order.

Recovering from Sleep, Keychain Access, and Uninstalling

Waking your Mac, switching Wi-Fi networks, or connecting a dock can change the network interface state. If traffic stops after waking, check that the active configuration is still enabled and the proxy is listening, then reconnect. If domains fail but direct IP connections work, investigate DNS resolution before changing multiple DNS options. Clients may store subscription credentials and system permissions in different places. Before moving to a new Mac, use the client's supported export method and store the files securely.

Before uninstalling, turn off the system proxy and TUN, then quit the client. If it provides an option to remove its background service, follow those instructions. Dragging the app to the Trash may not remove proxy settings or background components it installed. If your network behaves oddly afterward, check the proxy settings for the active network service, remove any local proxy address, and restore the settings you recorded before installation. Redact subscription URLs and outbound credentials from diagnostic logs; don't publish the entire configuration directory.

Android: Installation Sources, VPN Routing, and Background Operation

Choose the Right Architecture and Grant Installation Permission

Choose a client from the Android downloads section. Clash Plus is a good starting point; other options include Clash Meta for Android, FlClash, and Surfboard. Their configuration support is not identical, so don't assume a full YAML file for one core will work everywhere. Check which clients and subscription formats your provider supports before installing, to avoid finding out later that the protocol or rules cannot be parsed.

The installation package must match your device's architecture. Most newer phones use ARM64, but check what your device actually supports; older devices may need a different build. If Android asks whether your file manager or browser can install apps, grant permission only to the source you are using and revoke it after installation if you prefer. If you see “App not installed,” check system requirements, available storage, architecture, and the signature of any existing app. Not every installation error is a network problem.

Import a Subscription and Select the Right Configuration

Open the Subscription or Configuration page, add a remote configuration, and paste the link. When the download finishes, confirm the configuration is selected—not just listed. Choose an outbound proxy in its group, then return to the home screen and start the connection. Some clients treat subscription updates and selecting the active configuration as separate actions. Updating a different configuration won't change the one currently in use, so check both its name and the latest update result while troubleshooting.

If the import produces an empty list or field errors, check the format supplied by your provider, subscription expiration, and the protocols supported by the client. Don't delete unrecognized fields just to make the configuration save; those fields may define transport behavior or authentication. Clients such as Surfboard require a supported configuration format. If your provider offers multiple subscription links, choosing the right format is more effective than repeatedly importing an incompatible one.

How Android VPN Routing Works

Android clients usually route app traffic through the system VPN feature. The first time you connect, Android asks for permission to create a local VPN interface. This does not mean all traffic has reached a proxy outbound; the actual route still depends on your rules. A VPN icon in the system UI indicates the interface state, but to confirm traffic uses the selected outbound proxy, check the client's connection log, destination domain, and exit IP.

Android generally allows only one standard VPN app to route traffic for a user at a time. Ad blockers, security tools, company VPNs, and other proxy clients may already be using that feature. If the client won't start, check the system VPN page and close competing connections you don't need. Don't apply desktop instructions to turn on a “system proxy” on your phone: per-app routing, VPN routing, and Wi-Fi manual proxy settings are separate Android features.

Per-App Routing, Private DNS, and Battery Settings

With an allowlist, apps not on the list may bypass the client entirely. With a bypass list, apps on the list may connect directly. Before testing, check which mode is active and whether the target app is on the correct side of the list. If a browser works but another app fails, the problem may be a rule—or the app may not be routed through the client at all. After changing the list, reconnect as directed by the client so you don't keep using a stale interface state.

Android Private DNS, browser Secure DNS, and client DNS can create multiple resolution paths. If a specific domain fails, record the current settings and compare them one at a time. Don't change Private DNS and switch proxies together without keeping track of the results. Some clients can route DNS through the VPN, but support depends on the implementation. For checks on fake-ip and DNS routing, see DNS leak testing and prevention.

If the connection drops when the screen locks, check whether Android limits background activity, battery use, or auto-start for the client. Menu names vary by device, so use the app's battery management settings and change only what's necessary. Before enabling “Always-on VPN” or “Block connections without VPN,” understand how they work: the latter can temporarily cut off internet access if the client fails to start. First make sure the VPN interface connects reliably.

Before upgrading, keep your subscription URL and local overrides, and check whether you need to export app-specific settings. Moving to another client usually won't preserve per-app lists or battery permissions, so review them again. Before uninstalling, stop the connection and check the system VPN settings. Redact subscription links, outbound addresses, and account details in screenshots; share only the relevant time range from connection logs.

iOS: Clash Plus, Subscription Import, and Network Extensions

Install from the App Store and Verify Your Configuration Source

For iOS, choose Clash Plus from the Clash Plus page on the App Store. Product information is available at clashplus.io. Before installing, check the compatibility requirements and app details shown in the store against your device. Desktop executables and Android packages are not iOS installation files. You'll still need to provide a valid subscription after installing the client.

Your connection service provider manages the subscription; installing an app from the store does not grant subscription access. Check that the link is still valid, your account allows the current device, and the subscription uses a supported format. Subscription links often contain access credentials, so don't post them in shared notes, public screenshots, or forums. To report an import error to your provider, share the client name and redacted error text—not the full link.

Import, Update, and Activate a Configuration

Open the client's configuration or subscription manager, add the remote link, and wait for the download to finish. If your provider gives you a QR code, confirm that it contains a subscription URL supported by the client—not an account sign-in page or regular website. After importing, check that the configuration and proxy groups appear, set it as active, and choose an outbound proxy. Seeing a subscription name does not prove that it is enabled or that its proxy group has working members.

If the subscription update fails, first check the device clock, network connection, and whether the link is complete. Copying a URL can omit query parameters or add spaces and line breaks, so copy it again from a trusted source. If an older configuration still works, keep it while troubleshooting; don't delete everything without a backup. If you use local rules or client overrides, check whether they survive subscription updates to avoid unexpected routing changes.

Allow the VPN Configuration and Verify the Outbound Route

When you first connect, iOS may ask to add a VPN configuration. Confirm that the request comes from the client you're using, authorize it through the system prompt, then return to the app to check the connection status. iOS routes traffic through a network extension; there is no Windows-style system proxy switch to find. A VPN indicator in the status bar or Control Center shows the system connection state, but check the client's configuration, proxy group, and connection log to see where requests actually go.

In rule mode, test a request that should use a proxy, then one that should connect directly. An app may show updated content from its cache or an existing connection, so start a fresh request when testing. Changing the selected proxy group may not move existing connections to a new outbound immediately. If needed, use the client's connection management features or restart the target app. Don't judge a setting by an old page that may still be displaying cached content.

Wi-Fi, Cellular, and Other Network Features

Test the connection separately on Wi-Fi and cellular to distinguish local network restrictions from configuration problems. If it fails only on a particular Wi-Fi network, complete its sign-in or captive portal and confirm the device can connect with the VPN off. Public networks may require sign-in before you can access external services. Until that step is complete, subscription updates and proxy connections may both fail; trying different rule groups won't help.

If you already have a company VPN, an on-demand connection profile, or another network extension, check how they interact before troubleshooting to avoid multiple tools repeatedly taking over the connection. Organization-managed devices may have network settings controlled by policy; follow your administrator's requirements. Privacy features, browser settings, and client routing can also affect test results. Record each setting, change one factor at a time, then restore the privacy and work settings you need.

Background Limits, Updates, and Network Recovery

Don't treat iOS background behavior like a desktop process. Whether the app's interface continues running in the background is separate from whether its network extension stays connected. If connections keep dropping, check the system VPN status, client error logs, device storage, and configuration size. Don't assume that a slow interface after importing many duplicate rules means the outbound proxy is broken. Brief reconnects after switching mobile networks are also different from a tunnel that cannot establish at all.

Before updating the app or iOS, save your subscription source and important local rules, and check the client's backup options. To restore network access, stop the connection in the client first, then check the VPN status in Settings. Avoid resetting all network settings as a first step; that can also remove saved Wi-Fi networks and other information. If you still can't connect after the client is fully disconnected, check network sign-in, device policies, and the carrier network.

Linux: Distributions, Desktop Proxy, and Service Deployment

Choose Between a Desktop Client and a Core Deployment

For Linux desktops, choose Clash Verge Rev from the download page, or use FlClash. Server and router users can run the mihomo core directly. A graphical client and a core service are different deployment options; don't run both on the same port. Decide whether you need a tray interface, desktop system proxy, and interactive subscription management before choosing a graphical client or maintaining the configuration directory, service permissions, and logs yourself.

Before installing, check your distribution, processor architecture, and package format in the system information. Debian-based distributions generally use the matching DEB package; distributions using RPM package management need a compatible RPM package. Dependencies and desktop support still depend on the client's documentation. The same file extension does not guarantee compatibility across distributions. If installation reports missing dependencies, use your distribution's package manager to investigate. Don't copy library files from another system into system directories.

uname -m
cat /etc/os-release
ss -lntp 'sport = :7890'

Desktop Client: Subscriptions and System Proxy

After installation, launch the client from your desktop, import a subscription, set it as active, and select an outbound proxy group. Enable the system proxy and check your desktop environment's network proxy settings. Desktops, sandboxed apps, and browsers vary in how they read system proxy settings; terminal programs generally don't inherit them automatically. First verify the core with an explicit proxy request, then check how each target app connects. One app failing does not mean the core is stopped.

The command below uses environment variables to set an HTTP proxy for the current command. It affects only that command and its execution environment. For ongoing use, follow the application's documentation and consider which addresses should bypass the proxy. Don't put proxy settings in global environment files for every user without a clear reason; package managers and background jobs may keep trying to use a local endpoint after the core stops.

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

TUN, Routing, and Least Privilege

Linux TUN routing usually requires a virtual network interface and route permissions. If the graphical client provides a service setup option, use that process rather than granting excessive permissions to the entire app directory. Confirm the service starts before enabling TUN, then check the logs for interface creation and route configuration. Don't run the entire desktop app as root just to work around a permission issue with one helper component.

Take extra care with automatic routing on remote servers. Keep a separate management path available before enabling it, and confirm how SSH, private subnets, and the local gateway will be reached. Changing the default route can disconnect your current session. Configure TUN's automatic routing, interface detection, and DNS hijacking for your actual network topology. Container, bridge, and multi-NIC setups are not interchangeable with a single-NIC laptop. For router deployments, see an overview of running mihomo as a sidecar router.

Check Core Configuration and Service Directories

If you run the core directly, first prepare a complete configuration with outbound proxies, proxy groups, and rules, then check its syntax. The commands below assume mihomo is installed on your system path and the configuration file is in the current user's configuration directory. Adjust the path to match your deployment. A successful check means the configuration can be parsed; it does not confirm that every outbound proxy connects or that rule providers have updated successfully.

mihomo -t -f "$HOME/.config/mihomo/config.yaml"
mihomo -d "$HOME/.config/mihomo"

The configuration directory may contain rule provider files, caches, and databases in addition to the main configuration. When interactive and service runs use different users, their read and write permissions may differ. This can result in a manual launch succeeding while the service fails. Check the service's user, working directory, configuration path, and directory permissions. Read logs through the entry point for your deployment rather than allowing the service to restart repeatedly while discarding its error output.

Firewall, LAN Access, and Updates

If the local proxy works but LAN devices cannot connect, check the listening address, allow-lan, and firewall rules separately. Giving another device the port number alone is not enough. LAN access expands the exposed entry points, so restrict it to trusted subnets and add authentication where needed. The controller and proxy endpoints serve different purposes. Never expose the controller to untrusted networks or disable all firewall rules just to make remote management easier.

Before updating the client or core, back up the configuration and service definitions. Stop the old process before launching the new one. Whether a desktop session ending stops the client is different from whether a system service keeps running; configure it for your deployment. Before uninstalling, restore the desktop proxy settings, stop services, and remove any extra routes. Leftover environment variables or startup tasks can still cause failed requests after the program files are gone.

Common Configuration Questions: Troubleshooting Ports, DNS, and Rules

Keep Test Conditions Consistent Before Changing Settings

Troubleshoot in this order: is the app routed, which rule handles the request, can the outbound proxy connect, and is DNS resolving correctly? Use one target app, one domain, and one outbound proxy. Record the system proxy or TUN status, then check the connection log. Don't switch proxies, change DNS and ports, and reinstall the client all at once. Even if the connection comes back, you won't know why—and the next failure will be just as hard to diagnose.

The fields below show what common options do—and what they don't. A client may override values from the subscription through its interface, so check the final running configuration when troubleshooting. A DNS listening port and a mixed proxy port serve different purposes; similar numbers don't make them interchangeable. Before exposing a local endpoint, decide who needs access and from which network rather than binding it to every address by default.

Choose the Troubleshooting Path That Matches the Symptoms

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Subscription Outbound
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

Maintain Configurations You Can Roll Back

Once you've identified the problem, put necessary changes in a client-supported override or merged configuration instead of editing downloaded subscription files. Keep a minimal working configuration as your baseline. After adding rules, check the syntax and test both proxied and direct routes. When asking for help, share only relevant redacted snippets, error line numbers, and reproduction steps. Never attach a full configuration, account URL, or local management secret publicly.