Clash setup guides for every platform

Before you begin: architecture, subscriptions, and traffic routing

Know the difference between the client, core, and configuration

The client provides the interface, subscription management, system integration, and permission requests. The mihomo core parses configuration, establishes connections, and applies rules. Similar-looking interfaces don't guarantee the same configuration support: a Clash config may contain fields supported only by a particular core. Check the subscription provider's compatibility notes before importing it. ClashX is a macOS client, not a generic name for Windows, mobile, or Linux installers. An app built for one platform won't run on another.

A complete configuration typically includes proxies or proxy providers, proxy groups, rules, and DNS settings. A subscription URL is simply the entry point for retrieving that data; its suffix alone doesn't tell you the format. A link opening in a browser doesn't mean it returns parseable YAML. Login pages, expiration notices, and web errors can all cause import failures. Treat subscription URLs as private credentials—never post them in public comments, online conversion tools, or unredacted screenshots.

Check your system architecture and existing network settings

On Windows, check Settings → System → About for the system type; on macOS, check About This Mac for the chip; on Linux, run uname -m. Apple Silicon and Intel require different installers, and Linux packages must match your distribution. Android packages also vary by architecture, such as ARM64 and ARM; follow the download page's guidance. A successful download doesn't mean the file suits your device. If installation fails, check the architecture before downloading again.

Before you start, note your existing proxy, VPN, DNS, and network-filter settings. Company-managed devices may enforce proxies or certificates; if you lack permission, contact your administrator instead of repeatedly overriding system settings. For initial troubleshooting, run only one client that takes over network traffic. Multiple apps can otherwise modify the system proxy or default route at the same time. If you need your work VPN, confirm that it can coexist before choosing a test order.

Establish a repeatable first-connection process

Install the client and launch it once before importing a subscription. Confirm that the configuration is selected and its policy groups have available members. Then choose rule mode, select a specific proxy, and enable the system proxy or mobile connection. Check the logs and interface after each step; don't change ports, DNS, routes, and rules all at once. If the first test fails, leave the configuration unchanged and identify whether the issue is subscription retrieval, core startup, local listening, or the outbound connection.

Test at least two destinations: one expected to connect directly and one that needs a proxy. A browser can be a convenient test, but check the connection list to confirm which policy actually matched. Cached pages, reused connections, and browser secure DNS can make a single page load misleading. Once the baseline tests pass, enable automatic updates, launch at startup, or TUN one at a time so you have a clear rollback point if something breaks. When moving to another device, keep a copy of the original config and a record of custom rules.

Windows: install, system proxy, and TUN

Choose an installer and launch the client for the first time

For Windows, start with Clash Plus. To compare desktop features, also consider Clash Verge Rev, FlClash, and Clash Nyanpasu. Clash for Windows is discontinued and archived, so it isn't recommended for a new setup. Choose the installer that matches your system type on the Windows downloads page. Save your configuration before replacing an old client to avoid losing subscriptions or local rules during migration.

Read permission prompts when running the installer, then launch the client as a standard user. The interface may open even if the core can't start because of a port conflict, invalid config, or security policy; check the core logs to confirm. If you need a service component or virtual network interface, use the client's installation option to request administrator access. Routine use doesn't require running everything as an administrator. Organization-managed devices may block network services; this isn't caused by your subscription.

Import a subscription and confirm it's selected

Add a remote configuration from the Config, Subscription, or similar section, paste the full URL, and update it. When the configuration appears, make it active and select a specific proxy in a policy group. Adding a subscription without switching to it may leave the old file in use. If a policy group is empty, check the subscription response and parse logs; toggling the system proxy won't fix invalid configuration data.

When migrating from Clash for Windows, you can keep your subscription URL and custom rules, but don't overwrite the new client's entire application data directory. Old interface preferences, service paths, and extension scripts may not be portable. Import the original subscription into the new client and verify a basic connection before restoring overrides one at a time. For legacy scripts or core-specific fields, follow the new client's configuration checks.

Test the system proxy before troubleshooting app-specific behavior

Keep rule mode selected and turn on the client's system proxy. In Windows Settings → Network & internet → Proxy, check the manual proxy address and port; they should usually point to a local listening address. Once a browser connects, test developer tools and other apps. Some apps have their own proxy settings, while certain background services use WinHTTP settings. Enabling the desktop system proxy won't automatically reroute them.

You can test the local entry point explicitly from the command line. This command checks only the local HTTP proxy connection; configuration rules determine whether the destination uses a proxy. In PowerShell, curl.exe avoids parameter differences caused by the command alias in older environments. If your client listens on a port other than 7890, update the command to match.

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

If the connection is refused, first check that the client is running, the port matches, and the listener started successfully. If the local connection works but the remote request times out, check the policy group, proxy, and DNS. Some UWP apps have loopback restrictions; check whether the client provides a way to manage them. Don't routinely grant access to every app. Configure only the apps that need it, and note the changes so you can undo them.

TUN, startup, and restoring settings on exit

Consider TUN for games, apps with their own network stack, or apps that ignore the system proxy. Install the service as prompted by the client, enable enhanced mode, and confirm that the virtual interface and routes are created. If TUN already handles the apps you need, there's no benefit to stacking additional proxy tools. If local printing, LAN services, or your work network stop working, check private-subnet exclusions and existing VPN routes.

Launching at startup and starting the core are separate tasks. Seeing the interface after login doesn't mean the service is ready; a running service doesn't mean the subscription loaded or the proxy was restored. Check each step in order after a restart. Turn off the system proxy before quitting. If a crash leaves web access broken, open the system proxy settings, clear any leftover values, and test a direct connection. For more startup help, see startup troubleshooting; for client comparisons, see the Windows client comparison.

macOS: chip architecture, network permissions, and menu bar

Choose a client for your chip and migrate your configuration

For macOS, start with Clash Plus. Clash Verge Rev and FlClash are also options. ClashX Meta is discontinued; archived builds are for older environments with specific compatibility needs, not a basis for expecting ongoing feature support. Check About This Mac to see whether your device uses Apple silicon or Intel, then choose the matching architecture in the macOS downloads section. Don't rely on the model year alone—devices sold in the same year may use different chips.

Open the disk image, drag the app to Applications, and launch it from there rather than running a copy from the mounted image. Quit the old client normally before replacing it. If the system says the file is in use, check that the menu bar process has closed. If macOS shows a security warning on first launch, verify the file's source and follow the system's review process. Don't disable system-wide security to launch a single app.

Import a subscription and understand menu bar status

Add a subscription or import a local YAML file from the client's configuration section. Save and select the configuration, then check the active member in its policy groups. Rule, Global, and Direct in the menu bar usually indicate routing modes; a proxy name is a policy group selection. These aren't interchangeable. Even in rule mode, confirm that the policy group referenced by your rules has a valid member. Otherwise, the interface may look fine while traffic follows an unavailable outbound path.

When moving from ClashX or ClashX Meta to another client, import the subscription first, then migrate any rule snippets you maintain. Menu bar preferences, shortcuts, helper services, and local scripts belong to the app and shouldn't be copied over as a whole directory. Remote updates may overwrite direct edits, so keep custom rules in the client's supported override or merge mechanism. Check the effective configuration, not just the editor window.

System proxy, helper services, and network locations

After enabling the system proxy, check HTTP and HTTPS proxy settings under System Settings → Network → your active network service → Details → Proxies. Names may vary slightly between macOS versions. Check the Wi-Fi or Ethernet service you're currently using, not an inactive one in the list. Recheck the proxy after changing adapters, connecting a dock, or switching network locations.

You can inspect system proxy status in Terminal. The enabled flag, server, and port in the output should match the client. This command reads the status without changing system settings. If the proxy is enabled but the browser shows no connection records, check for a separate browser proxy extension or an exception list that bypasses localhost and specific domains.

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

The first time you enable TUN or a network helper service, macOS may ask you to authorize it and enter your administrator password. Initiate the action in the client and verify that the system prompt refers to the app you're using. If service installation fails, check the app path, system permissions, and logs. Don't repeatedly install the same service under multiple app copies. A menu bar icon doesn't confirm that the helper service is running; check the connection page and startup logs.

Waking from sleep, terminal tools, and local development

After a Mac wakes from sleep or switches from Wi-Fi to a hotspot, existing connections may no longer work. Try reloading the configuration or reconnecting before changing proxies. If the issue occurs only with TUN enabled, temporarily switch to the system proxy to distinguish a subscription issue from a virtual-interface routing problem. If direct connections still fail after quitting the client, check the current network service for leftover manual proxy settings and see whether another VPN is still connected.

Terminal tools don't usually inherit the graphical system proxy settings. If needed, set environment variables in the current terminal, test them temporarily, and only then decide whether to add them to your shell config. Add local development addresses to NO_PROXY to keep local services from going through the proxy; don't add broad domain patterns unless you understand the effect. Git, package managers, and containers may each have their own settings, so check them individually instead of repeatedly changing the system proxy.

Android: installation permissions, VPN interface, and background operation

Choose the right architecture and preserve app data

For Android, start with Clash Plus, followed by Clash Meta for Android, FlClash, or Surfboard. Clients differ in their support for subscription formats, rule syntax, and extension fields. Don't assume every client supports complex configurations written for mihomo. Check the Android installer notes for architecture and configuration compatibility before downloading and installing.

When installing an APK, Android may ask you to allow your browser or file manager to install unknown apps. Grant permission temporarily and only to the source you're using. If installation fails to parse, check that the file downloaded completely, matches your architecture, and meets the system requirements. If an update reports a signature mismatch, don't uninstall immediately. Export any available configuration and local rules, verify where the existing app came from, and then decide whether to migrate. Uninstalling usually removes app data too.

Import a subscription and authorize the VPN connection

Paste the subscription URL into the configuration section, download it, and select the resulting configuration. Some clients require you to add a profile and then update it separately; seeing a title doesn't confirm that proxies were retrieved. If import fails, first check whether the subscription service is reachable on your current network. If the URL requires a proxy, use a trusted alternative network or the provider's recommended import method. Never send a private URL to a public conversion service.

Select a policy group and proxy, then start the connection. Android will show a VPN authorization prompt. Confirm that it comes from the client you just installed, then allow it and check the system VPN indicator and the client's connection status. This interface routes traffic through the local client; it doesn't mean all traffic goes through a remote proxy. Rules may still send some connections directly. If startup fails, first check whether authorization was denied, then check whether another VPN, network filter, or firewall app is using the interface.

Per-app routing and Android network settings

To route only selected apps, use the client's app access controls and check whether the mode means “only selected apps” or “exclude selected apps.” These modes are opposites, so the same list can produce entirely different results. You may need to reconnect the VPN for changes to take effect; existing connections may not be rerouted immediately. Close and reopen the target app, then check connection records to confirm its traffic reaches the client.

Android Private DNS, browser secure DNS, and client DNS may all be active at once. If domain lookups fail, note the current settings and test them one at a time. Don't change multiple layers simultaneously. If connections by IP work but domains fail, focus on the DNS path. If all requests time out, also check the proxy and routes; a page failing to load doesn't by itself prove a DNS problem. Apps in a managed work profile may also follow separate policies.

Disconnects when locked, network changes, and battery settings

If the connection works in the foreground but drops when the screen locks, check battery optimization, background activity, and auto-start permissions. Manufacturers place these settings under Battery, App management, or Security; look for the relevant function. Allow the client the background access it needs, then test once with the screen locked. You don't need to disable battery limits for every app. Persistent notifications support foreground services on some systems; if hiding them makes the connection unstable, restore the default behavior and compare.

When switching from Wi-Fi to mobile data, existing connections may need to be reestablished. Even if the client says it's connected, test whether new requests succeed instead of relying on the icon. Stop and restart the connection, then test the same destination. If it fails only on one network, compare that network's DNS, IPv6, and access restrictions. A single proxy test result doesn't guarantee every app will work.

Typically, an Android phone can't have multiple regular VPN apps take over the same user's network at once. If there's a conflict with an ad blocker, firewall, or work VPN, choose which app should handle traffic based on its purpose rather than rapidly toggling between them. To share a proxy with a TV through a phone or computer, also check hotspot isolation, listening address, and firewall settings. Enabling the phone's VPN doesn't guarantee that hotspot clients will use it. For LAN sharing instructions, see mixed ports and LAN connections.

iOS: Clash Plus, importing configurations, and network extensions

Install from the App Store and verify your configuration source

For iPhone and iPad, start with Clash Plus. Install it from the Clash Plus page on the App Store. Product details are available at clashplus.io; the iOS download page links to the same destinations. Open the client after installation, read the system permission prompts, and then prepare to import a subscription. Never enter your Apple Account credentials or device passcode into a subscription provider's web form.

iOS clients may organize their interface differently from desktop clients and may support different network extensions and configuration formats. If you already have a desktop subscription, check whether the provider supports your iOS client, especially for scripts, external resources, and core-specific fields. Configurations with the same name may still be parsed differently. If the provider offers multiple formats, choose the one explicitly supported rather than trying unknown conversion links.

Import a configuration, choose a policy, and authorize the connection

Add a subscription URL from the client's configuration or subscription section. After updating, select the configuration and check the members in its policy groups. Choose a proxy manually for the initial test, then try policies such as automatic selection once it works. Automatic policies depend on the test URL, interval, and available candidates. A single test only reports a response from its test destination; it can't guarantee access to video services, work systems, or other apps.

When you first start a connection, iOS asks to add a VPN configuration. Follow the system prompts and complete device authentication. Once authorized, return to the client and confirm that the connection actually started. This VPN configuration lets a local network extension handle traffic; it isn't a subscription account and doesn't supply proxy details. If you accidentally delete the VPN configuration in Settings, start authorization again from the client rather than buying a new subscription or resetting all network settings.

For testing, open a destination in Safari that's expected to connect directly, then open one that needs a proxy. Check the connection or log details available in the client to confirm that the expected rules matched. A browser may show a cached page, and apps may reuse existing connections; send a new request after changing policies. The status bar VPN icon alone can't tell you whether a particular destination used the selected proxy.

Understand iOS restrictions and connection conflicts

iOS connections typically use a network extension; you don't need to copy the desktop workflow of enabling both a system proxy and TUN. Clients may use different terms, so follow the instructions in the app you're using. Manually setting an HTTP proxy for Wi-Fi is a separate method that applies only to traffic using that setting; it isn't a replacement for routing mobile data. For initial testing, use one clear traffic-routing method and avoid combining a manual Wi-Fi proxy with a network extension.

If the device has another VPN, content filter, or management profile, the connection may be replaced, blocked, or switched to another configuration when the network changes. Search for VPN in Settings and check which app owns the current connection. On a managed device, ask your administrator before removing a work profile. System-level privacy features, browser privacy settings, and in-app network options may also change the route; note each one's status while troubleshooting.

Network changes, updates, and battery usage

After switching from home Wi-Fi to cellular, test a new request before reconnecting. If the problem occurs only on hotel or public Wi-Fi, you may need to complete its captive-portal login first. Temporarily disconnect the client, sign in to the network, and reconnect to test. If the public Wi-Fi login page still won't open, restore any relevant manual proxy settings to their defaults instead of repeatedly switching subscription proxies.

Update subscriptions on a stable network, then confirm that the active policy group still has valid members. If a proxy was removed or renamed, your previous manual selection may no longer work. Don't delete a working old configuration just because an update failed. Keep the current connection and check the response format and service status. See subscription update troubleshooting for a detailed checklist; URL validity and YAML checks apply on mobile too.

A VPN indicator that stays visible doesn't by itself prove high battery use. Compare battery records under similar usage conditions and check for repeated connection failures, overly frequent tests, or excessive logging. Restore the client's default test frequency, turn off verbose logs if you don't need them, and observe the result. If LAN devices stop working, check local-subnet routing and app permissions. Don't route all traffic globally just to access one printer.

Linux: desktop clients and running mihomo with systemd

For desktop installation, check the package format and architecture

For Linux desktops, start with Clash Verge Rev; FlClash is another option. Choose a package for your distribution in the Linux downloads section. Debian and Ubuntu-based systems typically use DEB packages; distributions that use RPM need the corresponding package. Run uname -m to check the architecture, then verify which files the download page provides. Package format and processor architecture are separate requirements. Don't force an incompatible desktop package onto a server.

Use your distribution's package manager when possible to handle dependencies and make removal easier. After launching the client, import a subscription, select the active configuration and policy group, then enable the system proxy. GNOME, KDE, and terminal apps handle proxy settings differently; a working desktop browser doesn't mean the command line is configured. If you need TUN, follow the client's service and permission instructions. Don't run the entire desktop environment as root. On headless servers, run the core directly.

For headless setups, validate the configuration manually first

For servers and routers, choose a mihomo build for your architecture from the core downloads section. Extract it, install the executable as /usr/local/bin/mihomo, and prepare a dedicated configuration directory. The steps below assume the executable is already in place; don't copy the archive to the executable path. If your configuration uses relative paths for rule sets or proxy providers, make sure those resources are in the correct working directory.

Save your complete configuration as /etc/mihomo/config.yaml, restrict read permissions, and test it. Once it passes, start mihomo in the foreground and check the listener, DNS, and outbound logs. Keep the listener local by default; consider access from other devices only after verifying everything works. Running the core alone doesn't configure a proxy for terminals, browsers, or system services, which is why a server can show a healthy process while requests still go direct.

sudo install -d -m 700 /etc/mihomo
sudo chmod 600 /etc/mihomo/config.yaml
sudo /usr/local/bin/mihomo -t -d /etc/mihomo
sudo /usr/local/bin/mihomo -d /etc/mihomo

Run under a dedicated user and let systemd manage the service

After foreground testing, stop the process before configuring the service to avoid having two instances compete for the same port. The example below is for distributions that support systemd and the corresponding user-management commands. It provides a local proxy service, not TUN. Create a dedicated user and assign the directory to it. If the configuration directory needs write access, grant it only to this service user. Use the equivalent system-account setup on other distributions.

sudo useradd --system --home-dir /etc/mihomo --shell /usr/sbin/nologin mihomo
sudo chown -R mihomo:mihomo /etc/mihomo

Save the following as /etc/systemd/system/mihomo.service. The service uses a fixed configuration directory, restarts if the process fails, and waits for the network target. Reaching that target doesn't guarantee the subscription server is accessible; check remote resources separately. The example deliberately grants no network administration capabilities. If the configuration enables TUN, disable it or design a minimal permission set for your deployment.

[Unit]
Description=mihomo local proxy
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/etc/mihomo
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=5
UMask=0077
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
systemctl status mihomo --no-pager
journalctl -u mihomo -b --no-pager -n 80

Verify the listener, environment variables, and access boundaries

Use ss -lntp to check whether port 7890 is listening, then explicitly test a request through the proxy. If the service exits immediately after starting, first test the configuration, then check the logs for path permissions and port errors. If the service user can't read the config, fix ownership and directory permissions rather than making the file readable by every user. Test the configuration after an update, then run sudo systemctl restart mihomo to avoid interrupting the existing service with a syntax error.

curl -I --proxy http://127.0.0.1:7890 https://example.com
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1,::1

Environment variables apply only to the current shell and its child processes; they aren't passed automatically to a running systemd service. In a container, 127.0.0.1 points to the container itself, not the host. For access across containers or from a LAN, define the listening interface, allowed network, and firewall rules explicitly. Don't expose the external control interface directly to the public internet; use a protected management channel for remote access. See Linux desktop and headless deployment for the full setup.

Common configuration issues: ports, rules, DNS, and recovery

Mixed ports and LAN access

mixed-port accepts HTTP and SOCKS proxy requests on the same port. 7890 is a common default, not a fixed requirement. After changing the port, update the system proxy, terminal environment variables, app settings, and LAN devices to match. The snippet below shows basic settings for an existing configuration; it doesn't include proxies or policy groups and can't replace a complete subscription. If your client uses configuration overrides, make the change in the appropriate section and check the effective runtime value.

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

Keep LAN access off if you only need the proxy on this device. To share it with a phone or TV, enable LAN access and check the listening address, firewall, and device-isolation settings. The other device must use the computer's LAN address, not 127.0.0.1. Allow access only from trusted networks so the listener isn't exposed externally. allow-lan and the control-panel interface are separate settings: opening a proxy port doesn't mean you should also expose the control interface.

Rule order, overrides, and policy references

Rules are usually matched from top to bottom; the first matching rule determines where traffic goes. Put specific domain rules before the fallback rule, with MATCH generally at the end. The snippet below assumes the full configuration already contains a policy group named Proxy; capitalization and spelling must match. Reload the configuration after adding rules, then check the match record for a new connection. Existing connections may continue using the previous policy.

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - DOMAIN-KEYWORD,adservice,REJECT
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

If rules disappear after a subscription update, you probably edited the remote configuration directly. Use the client's supported override or merge mechanism, and confirm where the rules are inserted. YAML indentation uses spaces, not tabs. Quote strings with special characters such as colons correctly. The line reporting an error may not be the cause; a missing list marker or incorrect nesting on the previous line can also break parsing. Begin network troubleshooting only after the rule syntax and policy references pass validation.

Troubleshoot DNS and certificate errors separately

DNS determines how domain names resolve; routing rules determine where connections go. They are related but not interchangeable. For problems affecting only some domains, check logs for resolution failures, matched rules, and connection attempts. Fake-IP mode uses synthetic addresses for traffic identification, so a result that differs from public DNS isn't necessarily an error. After changing DNS mode, system or app caches may persist; reconnect before testing again.

For HTTPS certificate warnings, first check the system clock, destination domain, certificate issuer, and network filtering settings. Don't treat “ignore certificate errors” as a recovery step. If the issue occurs only with one proxy, stop using that proxy and test through a trusted route. If it also occurs on a direct connection, check the device and network. See how to troubleshoot HTTPS certificate errors. Repeatedly changing local ports won't fix a certificate issue.

Collect logs and restore settings in a safe order

When troubleshooting, note the system, client name, current mode, traffic-routing method, and time the error occurred. Keep the logs from that time period. Logs may contain domains, subscription URLs, and account details, so remove sensitive information before sharing. Reproduce the issue once, then change one variable at a time. Temporarily disable TUN while keeping the system proxy enabled to distinguish routing issues from proxy connectivity. An explicit proxy request can further confirm whether the local listener works.

To restore a direct connection, turn off the system proxy and TUN, quit the client normally, then check for leftover proxy, VPN, or manual DNS settings. Don't reset all network settings first; that can erase useful clues and work-related configuration. For more help, see subscription troubleshooting. If you simply want to set up a connection again, return to the Getting Started guide and follow the steps in order.