Clash Client First-Time Setup: Cross-Platform Configuration Guide and Common Pitfalls

Before You Install: Download Channels and Package Selection

There's no single "official client" in the Clash ecosystem — instead, a range of third-party GUI projects are built on top of the Clash core (most have now switched to the Clash Meta / mihomo core), with Clash Verge Rev, Clash Nyanpasu, FlClash, and various Clash for Windows forks among the most common. Before choosing a package, confirm three things: your system architecture (Windows is usually x64, with a few ARM64 devices; macOS needs to distinguish Apple Silicon from Intel; Android APKs should be checked for armeabi-v7a / arm64-v8a support), the minimum supported OS version (some clients have dropped support for older system versions), and whether you need a GUI or just the command-line core. Once the download finishes, don't just double-click and run — first check the version number in the installer filename against the version shown on the client's "About" page, to rule out a corrupted download.

If you previously installed an older version of a similar client, it's best to uninstall the old one before installing the new one, especially across major version jumps. Leftover config directories from the old version are usually not overwritten, so after reinstalling you'll still see your previously imported subscriptions — but if you run into UI glitches or rules that don't apply, clearing the config directory and re-importing the subscription is often faster than troubleshooting.

Windows: First-Time Install and System Proxy Setup

On Windows, installers are usually .exe or .msi files — just double-click and install to the default path; there's no need to check any "bundled components" options. The first prompt you'll typically see on first launch is a block from Windows Defender or third-party security software. This happens because the client isn't code-signed, which is normal — once you've confirmed the download source is trustworthy, just allow it through.

After opening the client, check the core status in the bottom-left corner or on the settings page to confirm the core started successfully (it should show as running, not failed or crash-looping).
Go to the "System Proxy" toggle and turn it on — Windows will automatically write the HTTP/HTTPS proxy address into the system network settings, so browsers and most apps will route through the client.
If you need apps that don't respect the system proxy setting (some games, some command-line tools) to also be routed through the proxy, consider enabling TUN mode. This step will prompt for administrator privileges — once granted, the client creates a virtual network adapter to take over all traffic.
Check "Launch at startup" and "Auto-connect on launch" in settings, so you don't need to manually turn on the proxy every time you restart your computer.

Note: TUN mode requires administrator privileges to create a virtual network adapter. If the client itself isn't running as administrator, the toggle will either fail to turn on or switch itself off shortly after. Right-click the client icon and choose "Run as administrator", or check "Request admin privileges on launch" in settings, to fix this.

Another often-overlooked step on Windows is firewall rules. The first time you enable TUN mode or the core opens a listening port, the system firewall will show a network access prompt — check both "Private networks" and "Public networks" under "Allow access", otherwise other devices on your local network may not be able to share the proxy through this machine.

macOS: Installation, Permissions, and Network Setup

On macOS, installers are usually .dmg files — drag the app into the "Applications" folder to finish installing. Since the client isn't signed by Apple, the first time you open it the system will show an "unidentified developer" warning or similar block. To resolve this, go to "System Settings → Privacy & Security", find the blocked-app notice, and click "Open Anyway" to confirm once — it won't be blocked on subsequent launches.

On first launch, the client will request "System Extension" or "Network Extension" permissions to take over traffic. You'll need to manually approve the extension in System Settings — after approving, you may need to restart the client, or even the whole system, before it takes effect.
Turn on "Set as system proxy" in the client's settings — macOS will write the proxy address into the proxy configuration of the currently active network service (Wi-Fi or Ethernet), and you can see the corresponding entry under "System Settings → Network → Details → Proxies".
If you want TUN mode to take over all traffic, you'll similarly need to click Allow in the network extension authorization prompt. Apple's review text for this permission tends to be long — just make sure it's the client you're using that's requesting it, and it's safe to approve.
Add the client to your login items so it connects automatically when the system starts, instead of having to open it manually every time.

macOS records system proxy settings separately per network service. If the proxy doesn't carry over after switching Wi-Fi networks, check whether you've connected to a new network service without the proxy config being rewritten. Most clients handle this automatically on reconnect, but with external adapters or virtual network setups you may occasionally need to manually toggle "System proxy" off and back on to refresh it.

Android: Installation and VPN Permissions

Most Android clients are distributed as APKs. Before installing, you need to allow "Install unknown apps" in system settings. The exact location of this permission varies slightly across manufacturer skins (MIUI, ColorOS, EMUI, etc.), but it's usually found under "Settings → App management → Special permissions".

After installation, connecting to a node for the first time will trigger a system-level VPN connection prompt. This is because traffic interception on Android is implemented through the system's VPNService interface — it doesn't mean a VPN tunnel is literally being established to an overseas server. Just tap "OK" to authorize.
Some custom Android skins add extra restrictions on background auto-start and battery optimization. It's best to enable both "Allow background activity" and "Remove battery optimization restrictions" on the app's details page — otherwise the system may forcibly kill the process after the client has been in the background for a while, silently dropping the proxy connection.
If you have other VPN-type apps installed on the device, keep in mind Android only allows one app to hold VPNService permission at a time — switching to and connecting through the Clash client will automatically override whichever app was previously active.

Note: some phone brands' "Power saving mode" or "Smart power saving" actively restrict non-system apps from staying resident in the background. Even after disabling battery optimization for the individual app, the system-wide power-saving policy may still periodically clear background connections. For always-on usage, it's worth also disabling the automatic management option in the system-level power-saving mode.

Subscription Import and Node Testing Across All Platforms

Regardless of platform, the core step of first-time setup is importing a subscription link. A subscription is essentially a remote config file URL — the client periodically requests it to pull the latest node list and rule set. To import one, paste the subscription link and a name on the config management page, then click update to download and parse it.

Make sure the subscription link is in a YAML config format Clash can recognize. If your provider only offers a Base64-encoded node list or a format meant for another client, convert it into standard Clash config first before importing — otherwise the client will report a parse failure, or the proxy list will be empty after import.
Once the subscription updates successfully, open the "Proxies" page to check whether groups and nodes display correctly. Groups are usually organized by country or route name, and opening a group reveals the specific node list.
Use the latency test feature on the panel (commonly labeled URL Test) to batch-test node speeds. A lower number doesn't guarantee a better real-world experience, but it's useful for quickly ruling out obviously broken nodes (timeouts, greyed-out/unavailable).
After picking a node with normal latency, open a browser and visit a website to verify the connection actually works — this confirms the proxy chain is functioning better than the panel numbers alone can.

Subscriptions usually have an update frequency limit — refreshing manually too often can trigger rate limiting from the provider. Most clients support setting an auto-update interval (e.g., refreshing once every 24 hours). Set this up once during initial configuration, and you won't need to manually worry about nodes going stale afterward.

First-Time Setup Checklist

To avoid missing anything, here's a checklist summarizing the key steps common to all platforms above — go through it item by item after your first install:

Check Item	Symptom	Fix
Core started properly	No websites load after connecting	Check the error message on the logs page, restart the client, or check the config file syntax
System proxy enabled	Browser still shows original IP	Check the system proxy toggle status, or switch to TUN mode to take over all traffic
All permissions granted	TUN mode won't turn on	Run as administrator on Windows; check system permission grants on macOS/Android
Subscription parsed successfully	Proxy page node list is empty	Check the subscription link format — make sure it's standard Clash YAML, not another format
Auto-start configured	Have to reconnect manually after every restart	Check the auto-start and auto-connect options in settings

Frequently Asked Questions

The system proxy is on, but some apps still aren't routed through it — what now?

System proxy settings only apply to apps that honor the system proxy rules. Some programs — especially games or command-line tools with their own network stack — bypass the system proxy and connect directly. In that case, enable TUN mode so the client takes over all traffic at the network layer, rather than just forwarding at the application layer.

The client says the core failed to start — where should I look first?

Start with the error message on the logs page. Common causes include syntax errors in the config file (indentation, misspelled field names), a listening port already in use by another program, or insufficient permissions on the core binary (some install methods require granting execute permission separately). Ruling these out one by one and restarting the client usually fixes it.

Why does the proxy disconnect after restarting my phone, requiring a manual reconnect?

This is usually caused by battery optimization or background restrictions — after a system restart, some manufacturer skins don't automatically restore the previous VPN session. It's best to enable "Launch at startup" in the client's settings, exclude the app from power-saving restrictions in system settings, and confirm you've enabled an option like "Remember last connected node".