Clash Setup
Guide for All Platforms

Know the Difference Between the Client and Proxy Core

Clash clients typically handle subscription management, proxy-group selection, log display and system network settings. The core reads the configuration, establishes connections and applies rules. mihomo is a standalone proxy core, not a graphical client. Even clients using similar cores may differ in how they merge configurations, manage privileged services and handle updates. When troubleshooting, note the client name, core details, OS architecture and traffic-routing mode. “Clash is broken” is not a useful diagnosis.

For desktop and mobile platforms, start with a compatible client from the downloads page. Clash Plus is our first recommendation for Windows, macOS, Android and iOS; Linux users can start with Clash Verge Rev. Choose another client if you need to support an older environment. Clash for Windows and ClashX Meta are archived projects that are no longer maintained, so they are not recommended for new deployments. Consider the interface, configuration compatibility and OS permission support together—similar names do not guarantee drop-in compatibility.

Check the Configuration Format Before Importing a Subscription

A subscription URL is a way to fetch a configuration, not a proxy node itself. Before importing, confirm that the provider supports your client or can return YAML that Clash or mihomo can read. A text file containing only node links is not the same as a complete configuration with proxy groups, rules and DNS settings. After importing, you should see a selectable configuration and proxy groups. If the client reports success but shows no nodes, check the response content, subscription status and format instead of repeatedly toggling the system proxy. A failed subscription request may simply mean the download endpoint is temporarily unreachable.

Subscription URLs often contain credentials. Never post them to public conversion sites, screenshots or repositories. If conversion is necessary, use an environment where you control data handling, and verify that the output retains your rules and proxy groups. Treat configuration backups as sensitive and store them securely. Before making changes, export a working copy and note the current proxy ports, DNS settings and proxy-group selection. Those details are more useful for recovery than a screenshot showing a successful connection.

Start with the System Proxy; Add TUN Only If Needed

The system proxy routes traffic from apps that honor the setting to a local proxy port. It usually does not cover every app and is not the same as a full-device tunnel. TUN uses a virtual network interface and routing to capture traffic, but coverage still depends on route exclusions, app behavior and permissions. For a first setup, verify the regular proxy path before enabling TUN. If the subscription itself is unavailable, changing the virtual adapter and DNS at the same time only adds variables and makes the cause harder to identify.

Rule, global and direct modes determine how the core selects an outbound route. System proxy and TUN determine how app traffic reaches the core; these are separate layers. Rule mode checks configuration rules in order. Global mode is useful for briefly testing whether an outbound route works, while direct mode does not necessarily disable a virtual interface. Record the mode before and after each change, and test one change at a time. If you already use a corporate VPN, another proxy client or network-filtering software, first confirm that it can be safely disabled to avoid route conflicts and local port collisions.

Establish a Repeatable Test Baseline

Before you start, check the system clock, direct internet access and available disk space. Make sure you can save the configuration and start the app. Choose an accessible HTTPS page and a service that actually requires a proxy, then record how each behaves before and after setup. A page loading in your browser does not mean terminal commands, games or update services are routed too. A latency test returning a result does not prove that account sign-in or large downloads work. For each test, check whether the request appears in the connection list, which rule matched and which outbound route was used. Check the logs for errors if needed.

Choose an Installer and Keep One Client Active

First, check your processor and system type under Settings > System > About, then choose a package from the Windows downloads section. Clash Plus is our first recommendation; Clash Verge Rev, FlClash and Clash Nyanpasu are alternatives. Clash for Windows is available only as an archived option. Do not confuse installer architecture with your browser's architecture. On ARM devices, confirm that the client, its core and any service components support your environment. An app launching under emulation does not mean its virtual network adapter will work too.

Quit other proxy clients before installation. Turn off their system proxy settings, then exit them from the system tray so old processes do not keep ports open. Follow the installer prompts to choose a location, and watch for security software alerts and OS permission requests on first launch. If installation is blocked, check the specific reason and file source rather than disabling all protection. Managed devices may restrict network services or virtual adapters; check your organization's policy instead of bypassing security controls.

Import a Subscription and Check the Local Port

In the configuration manager, choose the option to import from a URL, enter the subscription address and update it. Then explicitly make that configuration active. Some clients separate “add subscription” from “set as active”; adding it alone does not make the running core use the new file. Open the proxy groups, confirm at least one usable outbound option and review the configuration-load logs. If the client reports unsupported fields, check that the subscription uses the format expected by your core. Do not mistake a parsing error for a firewall blocking the connection.

Before enabling the system proxy, check the HTTP or mixed-proxy port the client actually listens on. The example below uses mixed port 7890; use it only if the client listens on that port, otherwise substitute the actual value. In PowerShell, call curl.exe explicitly to avoid confusion with a command alias of the same name. An explicit-proxy test checks only that command's request path; it does not change the network settings of other programs.

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

Once the explicit proxy works, enable the system proxy, visit a test page in your browser and check the connection list for the process, rule and outbound route. Windows user proxy settings, WinHTTP settings and app-specific proxy settings are not always synchronized. Terminal services and background tasks may not read the current user's settings at all. Do not change the system-wide service proxy just to route one program. First check for an app-specific proxy option or decide whether TUN is actually needed.

Enable Service Mode and TUN Only When Needed

TUN usually requires installing or starting a privileged service provided by the client. Make sure the permission prompt corresponds to the client you're using. After authorization, check the service status, enable TUN and verify that the virtual interface and routes are created. Running the entire GUI as administrator all the time is not a substitute for configuring the service correctly. If startup fails, handle permission errors, interface creation failures and route-add failures separately. First disable other tunneling tools, then reinstall the service using the client's repair option.

The Windows Firewall network profile you allow affects connections to your PC and local network. For local use only, there is no need to enable “Allow LAN,” and you should not open all inbound traffic on every network. If other devices need to connect, restrict the listening address, authentication and firewall source separately. UWP apps may be subject to loopback restrictions when using a local proxy. Use the client's loopback-exemption feature only after confirming that the restriction applies to the app; do not broaden access for every app.

Check After Sleep, Exit or Migration

After waking from sleep or switching Wi-Fi networks, check whether the client still has a running core and whether the subscription loaded correctly, then restart traffic routing. If internet access stops after you quit the client, check whether the system's manual proxy still points to a local port that is no longer open. Clear the stale proxy and test a direct connection; this is different from an expired subscription. Before moving to a new client, turn off the system proxy and TUN in the old one, quit it, then import your backup. Remove the old configuration only after confirming the new client runs independently. For Windows firewall, port-conflict and permission issues, see the Windows installation troubleshooting guide.

Identify Apple Silicon or Intel

Check the chip under About This Mac, then choose the matching installer. Apple Silicon generally uses ARM64; Intel uses x64. For a universal package, follow the supported platforms listed in the release notes. The macOS downloads section recommends Clash Plus and also lists Clash Verge Rev and FlClash. ClashX Meta is archived and no longer maintained. An older client launching successfully does not prove that it supports the latest network extensions, security features or permission flows. For long-term use, prefer a maintained option.

After opening the disk image, follow the prompts to move the app to Applications, then launch it from there rather than running it from the mounted image. If macOS blocks the first launch, verify the source and system alert, then use the normal approval flow in System Settings. Do not run commands that remove security attributes in bulk or disable system protection. For network extensions, background helpers or system permissions, check the requesting component's name and purpose. Importing a subscription does not require broad permissions unrelated to networking.

Load the Configuration and Check the Active Network Service

Import the subscription through the client, update it, set it as the active configuration and choose an outbound route in the proxy groups. Test an explicit proxy request before enabling the system proxy. On macOS, proxy settings belong to network services; Wi-Fi, Ethernet and USB adapters may each retain different settings. After connecting a dock or switching networks, check the network service currently in use rather than the Wi-Fi proxy page you changed last time. Users can rename network services, so do not assume the service name in a command example exists on your Mac.

Use the commands below to list network services and query HTTP and HTTPS proxy settings for a common Wi-Fi service. If the listed service is not named Wi-Fi, replace it with the actual name. The output shows only the proxy settings recorded by the system; it does not prove that a port is listening or that the target app honors those settings. The proxy address should match the client. For local use, it usually points to a loopback address—not the subscription server or a proxy node.

networksetup -listallnetworkservices
networksetup -getwebproxy "Wi-Fi"
networksetup -getsecurewebproxy "Wi-Fi"

TUN Permissions and Multiple Tunnels

A client's TUN implementation may rely on a helper service, virtual interface or network extension, and the authorization steps vary. Install the component as prompted by your client, then approve it in System Settings. After enabling TUN, check the logs for interface readiness and route creation rather than relying on the menu-bar icon. If authorization is requested on every launch, check that the component is installed in the expected location, not blocked by a management policy, and that the app is not still running from a temporary folder.

A corporate VPN, other network-filtering software or an existing tunnel may change the default route and DNS alongside TUN. If some domains become unreachable, temporarily disable additional tunnels where permitted and test with just one client. Do not delete unfamiliar virtual interfaces or system network profiles; they may belong to organization-managed software. If the tools must coexist, define which tunnel handles each destination subnet and confirm that DNS for internal domains remains reachable. Otherwise, proxy routing may cut off access to internal services.

Terminal Proxy Settings, Certificates & Wake from Sleep

Terminal programs usually do not use the system proxy just because the menu-bar icon says it is enabled. Use the command's proxy options or set proxy environment variables for the current terminal session. Remove them after testing so commands do not keep trying to connect to a closed local port after the client exits. HTTP, HTTPS and SOCKS options work differently, as do remote and local DNS resolution. For troubleshooting, test one clearly specified proxy protocol; do not stack environment variables, app settings and TUN at the same time, or the traffic path becomes difficult to identify.

Do not fix HTTPS certificate errors by disabling certificate validation. Check the system clock, destination site and any certificate-inspection policy on the network, then confirm that traffic decryption was not enabled unexpectedly in the client configuration. A regular proxy connection does not require installing a root certificate for every website. If only some addresses work after waking from sleep, reconnect to the network, restart traffic routing, then check DNS and routes. If problems persist after quitting the client, check for a stale proxy in the active network service. Keep your subscription and override configuration before updating, but do not manually copy old helper-component files into the new installation directory.

Install a Client That Matches Your Device

Choose a client from the Android downloads section. Clash Plus is our first recommendation; Clash Meta for Android, FlClash and Surfboard are alternatives depending on configuration compatibility. Most recent devices use ARM64, but check the architectures supported by your device. A 64-bit processor does not always tell you which software environments are available. If installation reports a conflict with an existing app, check the package name, signing source and installation channel. Keep a recoverable copy of your configuration before deciding whether to uninstall; packages signed differently cannot simply overwrite each other.

When installing from a browser or file manager, Android may ask you to allow app installations from that source. Grant permission only to the source you're using, then restore the restriction afterward if appropriate. If installation fails, distinguish an unsupported OS version, architecture mismatch, insufficient storage and signature conflict; downloading the same file repeatedly will not change any of these. On first launch, locate the configuration list, proxy groups, logs and connection toggle. Do not immediately enable every option, such as start on boot, always-on VPN and per-app routing.

Import a Subscription and Approve the VPN Connection

Add the subscription URL on the configuration screen, update it, select the configuration and confirm that it contains valid nodes and proxy groups. Clipboard access, file picking and QR-code import work differently in each Android client, so the menu labels may vary. If importing a link only shows a configuration name, check whether the content actually downloaded and whether parsing errors occurred. If the subscription fails on mobile data but works on Wi-Fi, first check the request path and provider restrictions rather than changing the app's routing list.

When you start a connection, Android usually asks you to approve a VPN connection request. Once approved, the client uses Android's VPN service to receive device traffic. This is not identical to every desktop TUN option. A VPN icon confirms that the service is running, but check the client's rules and connection records to verify the actual route. Normally, only one VPN service can be active for a user profile. If another tool also needs the VPN interface, whichever starts last may replace the first; decide which service should remain active.

Per-App Routing and Background Operation

Per-app settings usually mean either “only route selected apps” or “exclude selected apps.” Confirm which mode is active before changing the list. Adding a browser to the list may route only the browser rather than bypassing the proxy for it. Start with a minimal list containing one test app, save it, reconnect as required by the client and check the connection records. System components, work profiles and multi-user setups may have separate app lists; do not infer routing coverage from similar package names alone.

If the connection drops when the screen locks, check battery optimization, background activity restrictions and notification permissions first. Some Android builds manage auto-start separately from standard battery settings, so follow the options on your device. Grant only the background permissions the client needs; there is no need to relax restrictions for every related app. A persistent client notification does not guarantee that the core is still running. After unlocking, check the connection duration, logs and incoming requests to tell whether Android stopped the process or a network change triggered a reconnect.

Private DNS, Hotspots & Network Changes

Android Private DNS, browser secure DNS and client DNS may all be active, and they may use different paths. If the connection appears up but domains do not load, note the current Private DNS setting, temporarily switch to Automatic for comparison and check the client's DNS logs. Do not treat disabling one setting as a permanent fix; identify which resolution path is unreachable or inconsistent with the rules. Follow device-management requirements for DNS policies set by your employer or school.

Other devices connected to your phone's hotspot do not necessarily use the phone's VPN. Hotspot traffic forwarding depends on OS and client support; the fact that your phone uses a proxy proves nothing about connected devices. When switching from Wi-Fi to mobile data, existing connections may drop and DNS or routes may change. Test a new request rather than just refreshing an old page. If Always-on VPN or Block connections without VPN is enabled, Android may block all network access if the client fails to start. Check these settings and keep a recovery path before disabling or uninstalling the client.

Install Clash Plus and Find the Key Settings

Clash Plus is our first recommendation for iPhone and iPad. Install it from the Clash Plus page on the App Store; the product website is clashplus.io. You can also open the store from this site's iOS installation page. Check the store listing for OS requirements and device compatibility before installing. Feature names and available settings depend on the app version. Desktop client screenshots are not iOS instructions; the platforms use different permissions and network interfaces.

On first launch, locate configuration management, connection status, proxy policies and logs. If iOS asks for local network or notification access, decide based on how you plan to use the app; these permissions are separate from adding a VPN configuration. Importing a subscription does not route traffic by itself, and approving a VPN configuration does not mean the subscription works. Follow the sequence “install the app, load a configuration, approve the connection, verify a request” to separate interface, configuration and permission issues.

Use a Subscription Format the Client Supports

Copy the subscription URL, paste it into the app's add-configuration or import screen, update it and set it as the active configuration. Confirm that the provider explicitly supports the app's import format; not every subscription labeled Clash offers the same features. If the app supports file import, use the system file picker and check that you selected a readable text configuration, not a web page or error response. Seeing the app in the share sheet only means it can receive files—it does not guarantee the content is compatible.

After importing, confirm that the proxy groups offer an outbound route and the configuration is enabled before connecting. If an update reports an authentication failure, check that the URL is complete, the account is active and the provider allows the request. Do not start by deleting all local settings and reinstalling. Custom rules may be overwritten during updates, so use the client's persistent extension mechanism when available. If the app does not support a mihomo field, change the configuration output or choose a client with the required feature instead of copying desktop YAML as-is.

Approve the VPN Configuration and Verify the Route

When you start a connection, iOS may ask permission to add a VPN configuration and require device authentication. After approval, check the connection status in the app and, if needed, verify the active VPN in Settings. The app creates this tunnel using Apple's network-extension system; it is not a desktop-style “system proxy” toggle. A connected status only confirms the tunnel session. Test real requests and check client logs to verify that rules behave as expected and the destination accepts the selected outbound route.

Start by opening an accessible HTTPS page, then check the target app and see whether both appear in the client's connection list. If the page works but one app does not, check its cache, account restrictions, UDP requirements and independent DNS behavior. A VPN indicator does not prove that every connection uses the selected node; rules may send LAN traffic, specific domains or other destinations direct. After changing proxy policies, test with a new connection—existing long-lived connections may continue on their original route.

On-Demand Connections, LAN Access & System Boundaries

If the app offers on-demand connections, first confirm that manual connections are stable, then add trigger conditions. Switching frequently between VPN apps can change the active configuration; for troubleshooting, keep one known connection source. The manual HTTP proxy on a Wi-Fi network applies only to that network and traffic that honors the setting. It is separate from the app tunnel. Enabling both can result in double proxying or an attempt to use a stale LAN address. Record and test each setting separately rather than mixing the two.

If you cannot reach a printer, home server or other LAN device, check whether the client offers a LAN bypass and whether local network permissions allow the app to access it. System features such as iCloud Private Relay may also change some request paths. If appropriate, temporarily disable them for comparison and record the original setting so you can restore it. For managed devices or per-app VPN, ask the administrator about policy scope. Do not delete a managed profile in an attempt to restore ordinary proxy access.

After changing networks, updating iOS or restarting the device, check whether the app needs to reconnect manually, whether the subscription can still update and whether on-demand conditions match the current network. Before uninstalling, disconnect and review on-demand settings, then back up the subscription source and essential rules; files in the app sandbox may be deleted. If network problems persist after turning off the VPN, check the Wi-Fi manual proxy, DNS and device-management policies instead of repeatedly creating new VPN configurations. For certificate errors, check the clock, destination site and network certificate chain—never disable validation to hide the problem.

Choose an Installation Method for Your Distro and Architecture

For a Linux desktop, start with Clash Verge Rev or use FlClash. Check package formats in the Linux downloads section. Run uname -m to identify the architecture, then check which package manager your distribution uses. AMD64 and ARM64 are not interchangeable, nor are DEB and RPM packages. Desktop packages may also depend on your graphical session and runtime libraries. If the installer reports missing dependencies, resolve them through trusted distribution repositories rather than downloading individual shared libraries from unknown sources.

After installation, launch the app as a regular desktop user. Import a subscription, set it as the active configuration, then check the proxy groups and core logs. Installation privileges do not grant the network permissions the core may need; do not run the entire desktop app as root indefinitely. The desktop system proxy generally affects only apps that read the relevant settings. Terminals, containers, package managers and system services may use separate proxy settings. If an explicit proxy test works but a software updater does not, check that service's proxy options before concluding the core is broken.

Minimal Checks for Running mihomo Standalone

Server and router users can choose a matching build from the core downloads section. Extract it, rename it to match the actual filename and make it executable. Run the help command first to confirm that the binary supports your platform. Put the configuration in a separate directory, then validate it with the test option. Validation may need to fetch resources such as rule sets, so distinguish network errors from syntax errors. The commands below assume the binary is named mihomo in the current directory and the configuration is config.yaml. They do not install a system service.

uname -m
chmod u+x ./mihomo
./mihomo -h
./mihomo -t -f ./config.yaml
./mihomo -f ./config.yaml

This minimal baseline provides only a local direct proxy, so you can check port listening and app proxy options. It has no remote proxy node and cannot verify a remote outbound route. Use it to understand the local entry point, then load a trusted subscription. Do not append duplicate top-level keys to a working subscription file; duplicate keys may be rejected or overridden, making the effective configuration differ from what the file's order suggests.

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

TUN, Routing & DNS Permissions

On Linux, TUN requires the corresponding device and network permissions from the system. Restricted containers, shared hosts and minimal installations may not provide an accessible /dev/net/tun; editing YAML alone cannot add capabilities missing from the host. If the logs report insufficient permissions, check the runtime user, service restrictions and device visibility first. Do not grant broad permissions to every program. Limit authorization to the core process that needs it, and after upgrades, confirm that replacing the binary has not affected its capability settings.

Before enabling automatic routing, record the default route, remote-management path and existing firewall rules. Incorrect route capture on a remote server can disconnect SSH, so arrange console access or another recovery channel first. DNS may be managed by NetworkManager, systemd-resolved or another service. Identify the port the client's DNS listener uses and how system requests reach it. A DNS setting in the core does not mean every app uses it unless the system's resolution path changes. Conversely, do not overwrite a managed resolver file and expect the change to persist.

Services, Containers & LAN Boundaries

After verifying foreground operation, set up a background service using your distribution's service manager. Specify absolute paths for the executable and configuration, plus the working directory and runtime user. A service's relative paths often differ from those in an interactive shell, and rule sets and cache files need appropriate write access. If startup fails, check the service logs instead of repeatedly rebooting the machine. After stopping the service, confirm that automatically added routes and DNS settings are restored—especially that the machine can resolve domains and still be managed remotely.

Inside a container, the loopback address points to the container itself, not the host. Setting a host proxy to 127.0.0.1 usually will not let a bridged container reach it. If containers need a shared proxy, define a clear network endpoint, bind address and firewall scope, and consider authentication. Do not expose the proxy publicly by binding it to every interface. Router deployments also involve gateways, DNS distribution and transparent-proxy routing; a desktop configuration is not a drop-in solution. See the OpenWrt side-router deployment overview for topology and limitations. Most desktop users do not need a side router just to use a proxy.

Troubleshoot in Layers Before Changing Settings

Troubleshoot in this order: configuration load, core listening, traffic capture, rule matching, outbound connection and destination response. System proxy or TUN toggles cannot fix a YAML parsing error. Correct browser proxy settings cannot help if the core is not listening. Changing nodes will not help if the request never reaches the core. Find the earliest failing layer, preserve the exact error, timestamp and steps that triggered it, then change one variable at a time. Before asking for help, remove subscription credentials, node authentication details and sensitive connection history.

If import reports success but nothing works, check which configuration is active and whether the client merges overrides at startup. YAML uses spaces for indentation, not tabs; list nesting, spaces after colons and quoted strings can all affect parsing. Check that every proxy-group name referenced by a rule exists and matches exactly. If the provider renamed a group, custom rules may still point to the removed name. Fix the rule target rather than changing system DNS.

Rules Are Evaluated in Order; Put the Fallback Last

mihomo normally evaluates rules from top to bottom and uses the first match. Domain rules work well for service-specific routing; IP-range rules suit defined network ranges. MATCH catches connections that did not match earlier rules. The example below uses only built-in direct and reject policies to demonstrate ordering, not to provide a complete subscription. no-resolve prevents this IP rule from triggering a DNS lookup; it does not disable DNS globally. Add rules to an existing subscription through the client's extension mechanism, and make sure they appear before its fallback rule.

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - DOMAIN-SUFFIX,invalid,REJECT
  - MATCH,DIRECT

After a change, test a new connection and check which rule actually matched—not just whether the domain appears in the rules file. An app may connect to multiple domains, use cached addresses or reuse existing connections, so one page load can produce records with different policies. If a destination should use a proxy, set the rule target to a proxy group that actually exists in the configuration; do not paste in an arbitrary group name. For rule types, ordering and overrides, see Custom Rule Syntax and Priority.

Check DNS Settings Alongside the Request Path

DNS maps domain names to addresses; rules and routing determine where the connection goes next. Fake-IP mode uses synthetic addresses to preserve domain mappings, while Redir-Host generally returns resolved IP addresses to apps. They are not simply “fast” and “slow” alternatives. If a LAN service or device behaves unexpectedly with Fake-IP enabled, check domain exclusions and the actual traffic path before expanding the exclusion list. To assess DNS leaks, check where requests are sent; a test page's resolver name alone is not conclusive.

Browser encrypted DNS, Android Private DNS, the system resolver and the core resolver may all operate at once. For troubleshooting, test one clear resolution path, then restore other settings one by one. The encrypted DNS endpoint also needs a reachable connection path. A proxy dependency can create a startup loop: connecting to a node requires resolving its hostname, while the DNS request is routed through a node that is not connected yet. If rules depend on GeoIP or GeoSite, check that the databases downloaded successfully and that the fields match your core version. See the GeoIP and GeoSite update guide for details.

Separate Latency, Bandwidth and Connection Stability

Node latency tests mainly measure request time to a specified test endpoint under particular conditions; they do not measure real download bandwidth. A low-latency node may still perform poorly due to congestion, exit restrictions or destination-service policies. Record the target, time, network type and outbound route, and compare results under the same conditions. Avoid changing several settings in a row and keeping only one conclusion. For handshake and URL Test details, see Latency Tests vs. Real-World Speed. For other independent issues, visit the FAQ.

Undo changes in reverse order: turn off TUN or the app tunnel, disable the system proxy, then stop the core. Confirm that system DNS and the default route have returned to the expected state. Keep the last working configuration and a record of changes as your baseline for next time. If only one destination service fails while other proxied requests and direct connections work, check that service's account, certificates, region and protocol requirements instead of reinstalling the client. To review the main setup steps, return to the quick-start guide.