Clash Client First-Time Setup: Installation Guide for macOS, Windows, and Android

1. Setup order: start the core, then route traffic

For desktop clients, follow this order: choose an installer → launch the client → import a configuration → check local ports → enable the system proxy → verify the connection. First confirm that a browser can connect through the system proxy before considering TUN mode. Android typically routes traffic through the system VPN interface, so desktop system proxy steps do not apply.

Clash is a familiar name in the proxy and configuration ecosystem, but the client interface and the core that handles connections are separate components. mihomo is the core continued from Clash Meta. Support for configuration fields, service modes, and permissions varies by client. When troubleshooting an import error, note the client name and version as well as the core version; saying only “Clash is installed” is not enough.

1. Keep a record of your current network settings. Note any existing VPN, system proxy, and manual DNS settings so you can restore them if needed.
2. Run only one proxy client. Quit any older client, and avoid running another TUN or VPN during your first test.
3. Have a working configuration ready. Client installers usually do not include usable proxy nodes; obtain a subscription separately.
4. Change one setting at a time. Check the logs and connection records after each change so you can isolate issues instead of changing ports, DNS, and rules all at once.

2. Choose an installer: OS, processor, and core support

On macOS, Apple silicon devices can sometimes run Intel apps using Rosetta, but choosing a native build is preferable for a first installation to avoid an extra compatibility layer. For Windows on ARM, check whether the project offers a native installer rather than relying on “64” in the filename.

Go to the client downloads page and select your platform, then check the system requirements in the project’s release notes. Older Clash clients and current mihomo clients may differ in their support for newer protocols and configuration fields. A file importing successfully does not guarantee compatibility. To compare clients before installing, see the client selection guide.

3. macOS: app permissions, system proxy, and helper services

Move the app to Applications before launching

1. Open the downloaded disk image, drag the app into Applications, then launch it from the Applications folder instead of running it from the installer image.
2. If macOS says it cannot verify the developer, first confirm the file’s source and check the release notes. Then go to System Settings → Privacy & Security and look for Open Anyway. This option may not appear, depending on your macOS version and why the app was blocked.
3. After importing a configuration and confirming the core is running, enable System Proxy in the client.
4. Go to System Settings → Network → your current network connection → Details → Proxies and check the HTTP, HTTPS, or SOCKS entries. The address is usually 127.0.0.1; the port should match the client’s setting.

If macOS reports that the app is damaged, download an installer compatible with your system again and check the project’s instructions. Do not paste terminal commands from untrusted sources or disable system security protections just to launch an app. On company-managed Macs, device policies may block apps or network extensions; contact your administrator.

TUN permissions are separate from ordinary system proxy settings

Setting a system proxy typically does not require the same permissions as creating a TUN interface. To enable TUN, a client may ask to install a helper service, request an administrator password, or ask you to approve a network component; the exact process depends on the client. Verify the app’s identity in the permission prompt, then follow the project documentation. After installing a service, check the core logs—closing the password prompt does not confirm that TUN is routing traffic.

4. Windows and Android: proxy settings and VPN permissions

Windows: check the loopback address; don’t open up the entire firewall

After installing the client and importing a configuration, enable its system proxy. Then, in Windows 11, go to Settings → Network & internet → Proxy and check whether the manual proxy points to the active listening port. In Windows 10, the corresponding page is usually Settings → Network & Internet → Proxy. Some clients use an automatic configuration script, so check how traffic is actually routed instead of forcing a manual proxy setup.

• Use 127.0.0.1 as the loopback proxy address. Binding to 0.0.0.0 means listening on all IPv4 interfaces; do not use it as the browser’s proxy destination.
• When a firewall prompt appears, choose the network scope that matches your needs. If the proxy is for this device only, there is no need to expose it to your local network.
• If you need TUN or service mode, install the service or grant elevated permissions as directed by the client. Using a regular system proxy does not mean you must always run the client as an administrator.

Android: approve the VPN connection and check background behavior

When you start a proxy for the first time, Android usually shows a system VPN connection request. Verify the source and allow it; a VPN icon will typically appear in the status bar. That icon only confirms that the VPN interface is active—it does not mean the subscription node is working, the rules are correct, or the target service is reachable.

If another VPN, VPN-based firewall, or filtering app is running, stop it before testing; typically, only one active VPN service can run for a user at a time. If the connection drops when the screen locks, check Settings → Apps → the client → Battery for background restrictions; the exact path varies by device. Allow background activity if needed, and check the client’s app-routing settings to make sure the browser is not excluded from the proxy.

5. Import a configuration and check ports: confirm the core is running

In the client’s Configuration or Subscription page, choose to add a remote configuration, paste the Clash/mihomo subscription URL from your provider, download it, then select and enable it. A configuration name appearing in the list does not mean it is active. Check the logs for configuration parsing errors, unsupported protocols, or failed port bindings.

Subscription URLs often contain access credentials. Do not include them in public screenshots, support tickets, or command history. To import a local YAML file, use the client’s file import feature rather than editing the app’s installation directory. Subscription updates may overwrite remote configurations, so put local changes in the client’s supported override or merge settings.

A minimal example of common settings

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

This snippet explains a few fields; it has no nodes, proxy groups, or rules and cannot be used as a complete subscription. mixed-port accepts both HTTP and SOCKS proxy requests on the same port; allow-lan: false restricts access from the local network; mode: rule selects an outbound based on rules. A client may override these fields, so check the effective runtime settings and listening status.

If a port is in use, identify the process first

If the logs show address already in use or a bind failure, quit other proxy tools first. On macOS, run this read-only query in Terminal:

lsof -nP -iTCP:7890 -sTCP:LISTEN

On Windows, check the listening entries in Command Prompt, then use the PID in the output to identify the process in Task Manager. The filter below may also show related connections, so confirm the local address and listening status:

netstat -ano | findstr ":7890"

Once you identify the process using the port, quit the corresponding app normally, or change the new client’s mixed port to an unused value, such as 7891. After changing it, re-enable the system proxy so the operating system uses the new port. Do not terminate an unknown system process just because you see its PID.

6. System proxy vs. TUN: test one traffic-routing method first

A system proxy provides a proxy address to apps that honor it, so browsers are usually easy to test. Some command-line tools, games, and apps with their own network stack may ignore system proxy settings. TUN routes more IP traffic through a virtual network interface and involves routing, DNS, and permissions, which makes troubleshooting more involved.

• First desktop test: Keep TUN off, enable the system proxy, and use a browser to check a specific connection.
• Next test: If an app does not honor the system proxy, enable TUN and check the routing and DNS logs.
• Android: First check that the VPN is running, the app is included in the proxy scope, and the correct proxy group is selected.

System proxy and TUN are not inherently incompatible; many clients handle both at once. During initial setup, enabling just one primary routing method helps narrow down problems. TUN is not the same as global proxying: in rule mode, traffic is still routed directly, through a proxy, or blocked according to the rules.

7. Verify the connection: distinguish routing, rules, and node issues

Open the client’s Connections page, revisit a specific site, and check its domain, matched rule, and final outbound. A page loading by itself can be misleading: browser cache or a site that was already reachable directly may look like a successful proxy connection. A successful node latency test only confirms that test request; it does not verify the target service.

To separate browser settings from core issues, test by specifying the local HTTP proxy explicitly. Use the address and port from your current settings. The test domain below is an example; the result only confirms this individual request:

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

On Windows, use curl.exe to avoid differences caused by a same-named alias in some PowerShell environments. If an explicit proxy request succeeds but the browser fails, check browser extensions, custom proxy settings, and the system proxy reference first. If the connection is refused, check whether the local port is listening before switching remote nodes.

8. Checklist for a successful first run

1. Record the working setup. Note the client and core versions, configuration, mixed port, and routing method so you can compare them if an update causes problems.
2. Verify configuration updates. Update the subscription manually once and confirm it still parses, then set an automatic update interval based on your provider’s recommendations.
3. Enable startup options only if needed. On desktop, distinguish launching the app at startup from automatically routing traffic after launch. On Android, also account for background restrictions.
4. Keep local network access off. Enable it only if other devices need to use this device’s proxy, and consider authentication, the listening address, and firewall scope.
5. Test a clean shutdown. Turn off the system proxy or VPN before quitting the app, then confirm the browser can connect directly again.
6. Keep reproducible troubleshooting details. When asking for help, include your platform, versions, error time, and redacted logs. Hide subscription credentials, node passwords, and personal browsing records.

A first installation is complete when the configuration is enabled, the core is listening, requests from the target app appear in the connection list, the rules and outbound match expectations, and the network recovers after you quit. Once these checks pass, add custom rules, TUN, or more complex DNS policies; troubleshooting will be easier. For specific steps, see the installation and configuration guide. For permission or network issues, visit the help center.