Cross-Platform Setup

Before You Begin: Setup and Configuration Basics

Check your operating system, processor architecture, and subscription before downloading a client. Find the architecture in your desktop system information; on a phone, check the OS version and device model. The client provides the interface, manages configuration, and routes network traffic; the core, such as mihomo, parses configuration and forwards connections. These are separate components. A successful installation doesn't mean the subscription works, and a successful import doesn't mean system traffic reaches the core. Verify each of these three steps separately.

Choose a Client and Subscription Format

For Windows, macOS, Android, and iOS, start with Clash Plus. On Linux, consider Clash Verge Rev or FlClash. Clients differ in where features are found and how they store configuration. This guide refers to features such as “configuration,” “proxy groups,” and “system proxy” rather than assuming buttons are in the same place in every app. Check whether a client is still maintained before downloading: Clash for Windows and ClashX Meta are archived, discontinued options and aren't recommended as defaults for new devices.

Have a subscription link or local configuration that you're authorized to use. Subscription URLs may contain account identifiers, so don't post them in public forums, screenshots, or online conversion tools. A complete Clash YAML file usually includes proxies, proxy groups, and rules; a file containing only proxy nodes may require a client template or a compatible format from your subscription provider. If you get a format error, first check that you downloaded configuration text—not a login page, access-denied message, or expiration notice. The file extension alone doesn't tell you what's inside.

Configuration, Modes, and Traffic Routing

After importing a configuration, select it and enable it. Then choose an exit in a proxy group; Rule is usually the best mode to start with. Rule routes traffic directly or through a proxy according to the rules. Global sends connections that reach the core through the global policy. Direct uses a direct connection. These modes control traffic after it reaches the core; they don't route every app's traffic into it. Switching to Global won't fix a disabled system proxy or provide the system permissions TUN requires.

Keep a Known-Good Baseline

For your first setup, enable just one traffic-routing method. Once it works, add other features one at a time. Note your existing system proxy settings, other VPNs, and client ports. Avoid changing DNS, TUN, rules, and subscriptions all at once; if something breaks, it will be hard to tell which change caused it. Use a copy of your configuration for experiments and keep the original subscription entry for everyday use. Automatic subscription updates may overwrite direct edits. For persistent changes, use the client's supported override, merge, or script settings, then confirm they're applied to the active configuration.

When setup is complete, visit one site that should use the proxy and one that should connect directly. In the connection view, check the destination domain, matched rule, and selected exit. A latency test is only a single probe; it doesn't prove that every type of traffic will work. For step-by-step instructions, return to importing a subscription. If a term is unclear, see how proxy groups work before continuing to your platform's section.

Windows Installation and Traffic Routing

Open the Windows client downloads, start with Clash Plus, and choose an installer that matches your device's architecture. Find the processor and system type under “Settings → System → About.” x64 and ARM64 aren't interchangeable. Even if an app launches through a compatibility layer, its network service components may not work. Quit any older client before installing, especially one still running in the system tray, to prevent two apps from competing for local ports or repeatedly changing your system proxy settings.

Install the Client and Check That the Core Is Running

Follow the installer, then launch the app from the Start menu. For a portable version, extract it to a permanent folder; don't run it from the archive preview or leave it in a temporary folder that may be deleted. After the first launch, check the status page or logs to make sure the core isn't repeatedly exiting. If the app window opens but the core fails to start, look for a path, port, or configuration error in the message. Repeatedly clicking Connect usually won't fix these issues.

Installing a network service is separate from launching the regular app interface. If the client asks to install a service, confirm the prompt comes from the app you're using, then grant the permission requested by Windows. On a work device without administrator access, try the system proxy first; don't bypass organizational policies to install a driver or service. If security software blocks the installer, check its event details and verify the blocked file and download source. Don't make disabling all protection part of your routine setup. Before upgrading, note your configuration directory and overrides so you don't mistake uninstall cleanup for a normal update.

Import a Subscription and Enable the System Proxy

On the configuration or subscriptions page, choose the option to import from a URL. Paste the full address, save it, and update the subscription. After it downloads, select the configuration and choose an available exit in a proxy group. To import a local YAML file, use the file import option—not the subscription URL field. A QR code is just another way to enter an address; verify where it came from. For a comparison of the three methods, see Importing by URL, QR Code, or Local YAML.

Keep Rule mode for now, turn on the system proxy in the client, then check Windows proxy settings to confirm the address points to your own device and the port matches the active configuration. A common local address is 127.0.0.1, but use the port shown in your client. Browser extensions may have their own proxy rules. While troubleshooting, disable extensions that also route traffic, close existing browser connections, and try again. Don't just check whether a webpage loads; find the corresponding request in the client's connection list.

TUN Permissions and Common Conflicts

Consider TUN when an app ignores the system proxy. Follow the client's instructions to install or enable its service, then confirm the virtual network interface and routes are in place. For an initial test, turn off the system proxy and use TUN as the only traffic-routing method. Once verified, combine methods only as recommended by the client. If all sites fail after enabling TUN, turn it off immediately and check for other VPNs, virtual machine network tools, or system-wide traffic filters. Whether the device can connect directly again is a useful way to distinguish a routing issue from an upstream node problem.

netstat -ano | findstr ":7890"
netsh winhttp show proxy

The first command checks whether the example port is in use. If it returns a result, check the listening state and process ID to identify the program. The second command shows WinHTTP proxy settings, which are separate from the current user's system proxy. So direct-access output alone doesn't prove the client's system proxy is broken. Don't change WinHTTP just to make the two settings match. Configure it only for apps that explicitly rely on it, and make a note of how to restore the original setting.

If your browser still reports a proxy connection error after quitting the client, check Windows proxy settings for a leftover local proxy. If the issue starts after waking from sleep or switching networks, reconnect first, check the client service, then restart traffic routing. Don't delete all your configuration. Keep the original logs and note when a request failed; this makes it easier to pinpoint whether the problem is the local port, DNS, rules, or proxy exit.

macOS Installation and Permissions

Choose Clash Plus from the macOS downloads and select an Apple Silicon or Intel installer based on the chip shown in “About This Mac.” Clash Verge Rev and FlClash are other client options; ClashX Meta is archived. Don't rely on an app icon or the word “Mac” in a filename to determine the architecture. Before switching clients, turn off the old app's system proxy and background services. Otherwise, the new app may launch normally while the old one still controls network settings.

Install in a Stable Location and Grant Permissions

Open the downloaded disk image, drag the app to the Applications folder, and launch it from there. Don't keep running it from the mounted image; after a restart or ejecting the image, login items and helper tools may no longer find it. If macOS warns about the download source, verify where you got the app and confirm its identity, then review the available options under “Privacy & Security.” Removing security attributes or disabling system protections isn't a general installation fix. Handle a clear permission prompt differently from a file of unknown origin.

Approving a helper service, network extension, or VPN configuration changes system settings. The prompt depends on how the client is implemented. Follow the app's current instructions, then check in the client that the service is ready; the disappearance of a system dialog isn't proof that it is. Managed devices may prevent users from approving network components; follow your organization's policy. If installation fails, note the exact system message, app path, and chip type. Reinstalling the same file usually won't resolve a permissions issue.

Import a Configuration and Check the Active Network Service

Add the subscription URL in configuration management, update and activate the entry, then select an exit in a proxy group. For the first test, use the system proxy to verify browser access and keep other VPNs off. macOS proxy settings apply to a specific network service. Wi-Fi, Ethernet, and a dock's network adapter may all be separate services. If the proxy stops working after switching networks, check the service currently in use—not just a Wi-Fi entry you configured earlier. If the client can set the system proxy automatically, confirm it changed the active service.

scutil --proxy
networksetup -listallnetworkservices

Use scutil --proxy to view system proxy information; the other command lists network service names. Check whether the proxy is enabled and whether its server and port match the client. Command-line tools may not read these system settings. If a browser works but a command doesn't, that doesn't by itself mean the node is at fault. Check which proxy methods the program supports, then use the appropriate environment variable or command-line option. Don't enter an HTTP proxy address in a field that doesn't support that protocol.

TUN, Waking from Sleep, and Keeping Configuration Changes

Enable TUN only when you need to route more apps, and approve the required service as prompted by the client. If startup logs report insufficient permissions, device creation failure, or a route setup error, fix that system-level issue instead of repeatedly replacing the subscription. After TUN starts, check that DNS follows the expected route; a virtual interface being present doesn't mean DNS is working correctly. Corporate VPNs, virtualization software, and other network extensions can all modify routes. During testing, keep only the components you need so you can identify the source of a conflict.

Distinguish the original subscription file from the runtime-generated configuration. The subscription file may be replaced when updated; the runtime file may be rebuilt at every launch. Direct edits to either one may not persist. Prefer the client's persistent override feature, then check the final configuration after applying it. Before upgrading, back up your subscription source, overrides, and any essential local rules. Treat subscription URLs as sensitive information, and don't sync the entire configuration directory to a public repository.

Before uninstalling or switching clients, turn off the system proxy and TUN, then quit the app. Moving it to the Trash may not remove approved network configurations or background helpers. Use the client's service removal option and check system network settings for leftovers. Restore a direct connection before starting the replacement client to prevent the two apps from overwriting each other's proxy state and to pinpoint when a new problem starts.

Android Installation and Background Operation

Start with Clash Plus in the Android downloads; you can also choose Clash Meta for Android, FlClash, or Surfboard based on configuration compatibility. Modern devices usually use ARM64, but check your device architecture and the installer requirements. Older devices may need a different architecture or a universal package; don't guess by trying random installers. If Android reports a conflict with an existing app, check the app name, source, and signing message. Back up your configuration before deciding whether to change the installation source.

Installation Permissions and Android's Local VPN

When you open an installer from a browser or file manager, Android may ask you to allow that source to install apps. Grant permission only to the source you're actually using, and restore the previous restriction after installation if appropriate. If installation fails, check free storage, OS compatibility, and whether you're trying to replace an app signed differently. Uninstalling can erase private app data, so don't make it your first step before backing up subscriptions and overrides. Save local YAML files to a folder you can identify so they aren't deleted when you clear downloads.

The first time you start the proxy service, Android asks to set up a VPN connection. This authorizes the app to create a local virtual network tunnel through the system; it doesn't mean your subscription provider has configured everything correctly. Other VPNs, some firewalls, and network-filtering apps may use the same system capability and generally can't run independently at the same time. If another app disconnects, check the current VPN status first. Don't mistake this for Clash being force-closed or an unstable node.

Activate a Subscription and Set App Coverage

Add a remote subscription in the configuration list, enter a name and the full URL, and update it. Once the update succeeds, activate the configuration and select an exit in a proxy group. When importing a QR code, confirm the result is the subscription URL you expect. Don't upload a screenshot that shows the full address when asking for help. If the import succeeds but no proxy groups appear, the subscription may contain only nodes or require a client template. Surfboard configuration isn't interchangeable with Clash YAML; check whether your provider supports the format before switching clients.

After connecting, test a browser request, then check the connection log. Mobile clients usually route traffic through Android's VPN service, so you don't need to follow desktop system HTTP proxy steps. If the client offers per-app proxying, check whether the option means “only selected apps” or “exclude selected apps”—they do opposite things. Choosing the wrong one can make the browser work while leaving no record for the app you're testing. After changing app coverage, fully close and reopen the target app so it creates a new connection; existing sessions may not switch immediately.

Battery Restrictions, Network Changes, and Auto-Start

If the connection drops when the screen locks and returns when it wakes, check the system's background, battery, and auto-start restrictions first. Settings vary by device manufacturer; look under the app's details and allow it to run in the background as needed. App locking, notification display, and battery optimization are separate controls. Enabling one doesn't mean the others are disabled. Don't loosen restrictions for every app; first confirm that Android is stopping the client in the background, then adjust only that app.

When switching from Wi-Fi to mobile data, existing connections may drop and apps may need to reconnect. If the problem occurs only on mobile data, check whether the app is blocked from using it, whether the subscription update needs the current network, and whether the node's protocol works on that network. Android Private DNS and the client's DNS settings may both affect lookups. If domains fail to resolve, note both settings and test one reversible change at a time instead of disabling every DNS feature.

When an app fails, first check whether it's included in the proxy scope and whether its domain appears in the connection log. If it does but uses the wrong exit, check the rules. If the exit is correct but the request still fails, then test the node, DNS, and the app's network requirements. Normal latency doesn't rule out restrictions on the app's traffic. Handle subscription update failures separately from proxy connection failures. See Subscription Update Failures and Automatic Refresh Settings for possible causes; don't repeatedly delete and recreate a working configuration.

iOS Installation and VPN Setup

For iOS, start with Clash Plus. Install it from the Clash Plus page on the App Store; product details are available at clashplus.io. Check the device requirements listed in the store and confirm there's enough storage before installing. Installing the app and enabling a network proxy are separate steps. On first launch, get familiar with configuration management and the connection controls. Don't repeatedly approve and remove system VPN configurations without a valid subscription.

Import a Subscription and Activate the Configuration

Get a subscription URL compatible with the client, then add it using the link option in configuration management. Check for spaces, line breaks, or punctuation added by a chat app before saving; keep any account parameters intact. After a successful update, select the configuration, check that the expected proxy groups appear, and choose an available exit. To import a YAML file, use the client's file picker or share option. You must still activate it after import; saving a file on your phone doesn't mean the client is using it.

Subscription URLs and individual proxy share links can use different formats. A single proxy node may not include complete rules or proxy groups, so don't assume every import option accepts interchangeable text. If your provider offers a link for a specific client, check which configuration format it provides. If a download fails, determine whether the URL is inaccessible, the content is incompatible, or the subscription has expired. Switching between Rule and Global won't change the file returned by the subscription server or fix a login page mistaken for configuration.

Approve the VPN and Verify the Actual Exit

When you connect for the first time, follow the system prompt to allow the VPN configuration and complete any device authentication. This lets the client create a system network tunnel; it doesn't guarantee every domain will use the proxy. Keep Rule mode, visit a test site, then check the connection log for the matched rule and exit. A VPN indicator or connected status in system settings only confirms the tunnel is up. A rule may still send traffic directly, and the selected node may fail to reach a particular destination.

If you're also using a work VPN, another proxy app, or a network filter, first check which configuration currently owns the connection. Disconnect it before starting Clash Plus to avoid misreading the system's current state. On-demand connection settings may also reactivate an old configuration after a network change; check the system VPN settings. Managed devices may restrict network changes. Follow device management requirements rather than deleting a management profile to restore a personal proxy.

Background Operation, DNS, and Local Network Access

On iOS, the network extension and app interface don't share the same running state. Leaving the app doesn't necessarily stop the proxy, and seeing it in the app switcher doesn't prove the connection is working. Check the current VPN status and newly generated connection logs. Don't rely on keeping the app open to prevent disconnections. Check for subscription update errors, an extension crash, or a network change. If iOS restricts the app's mobile data access, test that restriction against the client's actual behavior rather than repeatedly testing only on Wi-Fi.

If you can't reach a local device, printer, or service, check whether its address matches a proxy rule and whether the client offers a LAN bypass or routing option. Before adding a direct-connection rule, confirm where the subnet comes from; don't set an unfamiliar range to bypass the proxy wholesale. A domain may resolve correctly while the device remains unreachable due to local network permission, the destination port, or network isolation. Webpage access alone isn't enough to diagnose it. After each change, reconnect and check which rule actually matched.

Set the automatic update interval based on your subscription provider's requirements and the client's capabilities. Mobile operating systems schedule background tasks, so an interval doesn't guarantee a refresh at an exact time. Before heading out, update once manually and confirm the configuration still activates; keep a working entry before switching configurations. If an app still fails after connection, check in order: did a new request appear, did the right rule match, and is the exit usable? Don't jump straight to reinstalling. For a detailed traffic test, see First Connection and Proxy Verification.

Linux Desktop and Core Setup

For a Linux desktop, start with Clash Verge Rev and FlClash. For a server or router, see the mihomo core. A desktop client typically bundles configuration, a system tray, and service management. Running the core on its own means managing the configuration directory, process, logs, and traffic routing yourself. Don't mix files managed by a GUI client with manually deployed files in the same directory, and don't run two cores that listen on the same address and port.

Check the Architecture and Install Dependencies

Run uname -m to check the processor architecture, then choose the package format for your distribution. Debian and Ubuntu systems typically use deb packages; RPM-based distributions need the appropriate RPM package. The same package format doesn't guarantee the same runtime dependencies. Don't rename a file to make an unsupported architecture appear compatible. Install a local package through your distribution's package manager so missing dependencies are reported clearly. Resolve missing components from the current system's repositories instead of copying shared libraries from another distribution.

If a GUI app won't start, launch it from a terminal to see the error output. First distinguish a display environment or desktop integration problem from a core configuration issue. An SSH session usually lacks a full desktop, so desktop-client instructions may not apply. A server typically needs only the core and explicit per-app proxy settings. TUN is needed only if your traffic-routing requirements call for it; it's not a prerequisite for a successful deployment. Before installing a system service, set a stable run user and configuration path instead of relying on a temporary download directory.

Import into a GUI Client and Set Up the Desktop Proxy

Import and update the subscription in the desktop client, activate it, then select an exit in a proxy group. After enabling the system proxy, remember that GNOME, KDE, and individual apps may read proxy settings differently. A desktop toggle doesn't automatically configure every terminal app. First check whether the browser appears in the connection list, then configure command-line tools separately if needed. For apps that support standard environment variables, set a temporary proxy in the current shell and test it before deciding whether to make it permanent.

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

# Clear the temporary proxy settings for this shell
unset http_proxy https_proxy no_proxy

The example above assumes an HTTP or mixed proxy is listening on the example port. The HTTP URL in https_proxy specifies the protocol used to connect to the proxy; it doesn't downgrade the destination's HTTPS connection to plain HTTP. Programs vary in their support for variable names, capitalization, and SOCKS. Check the program's documentation. New terminals and already-running services won't inherit variables set later. Verify the browser, terminal, and system services separately; testing one doesn't prove the proxy works everywhere.

Standalone Core, Permissions, and Service Boundaries

To run mihomo on its own, extract the core for your architecture, create a dedicated configuration directory, and save the active configuration there as config.yaml. The commands below assume the executable is in the current directory and the configuration is in mihomo-config under your home directory. Check the syntax first, then run it in the foreground and watch the logs. Once the listener is working, consider a service manager. Passing syntax checks only means the configuration can be parsed; it doesn't prove that nodes, rule references, or remote resources are accessible.

chmod +x ./mihomo
./mihomo -t -d "$HOME/mihomo-config"
./mihomo -d "$HOME/mihomo-config"

If you plan to use a systemd service, specify stable absolute paths, a working directory, a run user, and a restart policy. A regular local proxy may not require administrator privileges; creating a TUN interface, changing routes, and taking over DNS may need additional permissions or capabilities. Don't run every graphical app as root just for convenience. If the service fails in the background, check its logs, especially permissions on the configuration directory and paths to resource files. A successful foreground launch doesn't mean the service user can read the same files.

After enabling TUN, check the default route, DNS management, and any other VPNs. NetworkManager, systemd-resolved, and the client may each manage part of the network. Manually overwriting resolver files can stop working after a reconnect. First find out which component manages DNS, then use its supported integration. Check the server firewall too: local proxy and control interfaces are generally intended for local use. Don't expose them to the public internet for convenience. After stopping the service, verify that routes and DNS have been restored before testing traffic routing again.

Configuration Checks and Troubleshooting

Start troubleshooting with one repeatable failed request. Note the destination domain, time, active configuration, and traffic-routing method, then check whether the connection reached the core. If there's no connection record, check the system proxy, app proxy, and TUN scope. If the request used the wrong exit, check rule order and proxy groups. If the exit was correct but the request failed, check the node, DNS, and destination service. If only subscription updates fail while the existing configuration still works, troubleshoot the subscription fetch separately; don't lump both issues together as “no internet.”

Port Settings and the Control Interface

mixed-port accepts both HTTP and SOCKS proxy requests; external-controller is the control interface, not a port for proxy traffic. Pointing a browser at the control interface will fail, and changing the proxy mode won't help. The snippet below is a simple example for troubleshooting; merge it into a complete configuration before use. It provides a direct connection only and contains no proxy nodes. The port numbers are examples. If a port is already in use, update the runtime configuration, system proxy, and app proxy to match.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

proxy-groups:
  - name: LOCAL
    type: select
    proxies:
      - DIRECT

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

The listening address and LAN access settings define security boundaries; they aren't performance options. For local use, keep the listener bound to loopback. To share a proxy with trusted devices, check the bind address, authentication, firewall, and network. Never expose the control interface on every network adapter just because the dashboard won't connect. If a port conflict occurs, identify the process first and check whether it's an old core. Then decide whether to stop it or use another port; don't kill an unknown system process.

Rule Order, DNS, and Fake-IP

Rules are generally matched in order. Put specific rules before broader fallback rules, with MATCH near the end. Every referenced proxy group must exist, with spelling and capitalization matching exactly. Having a node in a subscription doesn't mean a rule will use it. The final exit depends on the matched proxy group and its current selection. Reconnect the target app after changes; existing long-lived connections may keep using the old exit. For instructions, see setting up rule-based routing.

Fake-IP maps domains to reserved addresses, while rule matching still relies on domain information available to the core. Seeing an address that isn't a typical public IP doesn't by itself mean DNS failed. If you have a compatibility issue, add the affected domains to the appropriate filter configuration and confirm which filtering mode the core uses. Don't paste in a large list from an unknown source. System cache, browser DNS, and client DNS can each create a separate resolution path; change one at a time while troubleshooting. For details, see How Fake-IP DNS Mapping Works.

GeoIP Updates and Configuration Overrides

First determine whether the configuration uses a traditional GeoIP data file or geodata mode; each needs different resources and paths. Check the logs and active configuration to see whether an update in the interface replaces the data currently in use. Updating GeoIP won't fix every rule issue: domain rules may match first, rule sets may update on their own schedule, and some matching options affect whether DNS resolution occurs. If the database fails to load, check that the download completed and verify the directory permissions and configuration path instead of just restarting repeatedly.

Track resource updates separately from subscription updates. If a remote rule set fails to update, first check its access path and whether the cache is available; replacing the subscription may not change the rule set. Put custom rules that need to persist in the override settings, then review the final active configuration after updating the subscription. YAML uses spaces for indentation; preserve the structure of lists, keys, and nested values. Even when syntax checks pass, review the startup logs to confirm remote references and proxy groups loaded successfully.

If a change cuts off all network access, turn off the current traffic-routing method, restore a working direct connection, then revert the most recent change. For the full sequence, see the Connected but Can't Browse? Step-by-Step Troubleshooting Checklist. For general questions, visit Troubleshooting. Once connectivity is restored, test both a direct connection and a proxied destination to confirm the issue is actually resolved—not just hidden by browser cache or an existing connection.