First-Time Clash Setup: Installation Checklist for Windows, macOS, Android & iOS

Setup order: import your subscription before routing traffic

For your first run, follow this order: install the client → import and enable a profile → choose a policy → route traffic through the client → test the connection. Get one connection working before adjusting TUN, DNS, or startup settings. That way, if something goes wrong, you’ll know which step to check.

Clash is a common name for a proxy core and its related client ecosystem, not a single installer available on every platform. Clash Meta later adopted the name mihomo, and graphical clients built around it may have different settings screens. Subscription compatibility depends on the core and configuration format in use—not just the app’s name.

1. Check your operating system and processor: Windows downloads vary between x64 and ARM64, while macOS builds target Intel or Apple Silicon. Android packages may also be architecture-specific, such as arm64-v8a.
2. Get a compatible subscription: You’ll need a Clash or mihomo configuration URL from your service provider. A node list, webpage URL, or link designed for another client may not import directly.
3. Quit other proxy or VPN apps for now: This prevents two clients from changing system proxy settings, virtual adapters, or routes at the same time.
4. Note your current network settings: Make sure ordinary websites load before you start, and write down any manually configured proxy settings on your computer.

Importing subscriptions and choosing policies: a loaded profile isn’t necessarily active

In the client, find the Subscription, Configuration, or Profiles page and choose URL import. Paste the full URL and download the profile. Menu labels vary between clients, so the steps below describe what to do rather than a button path for one specific app.

After importing, check these four things

• Did the download succeed? The profile list should show a name, update time, or available entries—not just an error message.
• Is the profile active? Some clients require you to select Enable after importing. Seeing a new profile card doesn’t mean the core has switched to it.
• Does the policy group have usable options? Open the main policy group on the Proxy or Proxies page and select a node manually. Don’t accidentally choose DIRECT or REJECT.
• Is the mode set to Rule? Rule mode is a good place to start: it follows the configuration’s rules to decide whether traffic goes direct or through a proxy. Global mode can help with a quick comparison test; Direct mode doesn’t route traffic through proxy nodes.

If the import fails with a YAML parsing error, first check whether the subscription actually returned a configuration. An expired URL may return a login page, while a missing URL parameter can make the server return the wrong content. Don’t try deleting indentation at random: YAML uses indentation to define structure, and changing it can cause more errors.

If the client reports an unsupported proxy type or configuration field, check which core it uses and ask your provider for a compatible format. Don’t remove protocol, encryption, or TLS settings just to make the profile import. Loading a configuration and connecting to a node are two different things.

Windows and macOS: check the system proxy before trying TUN

On desktop, start by enabling System Proxy in the client and testing your browser. This setting usually points the system’s HTTP/HTTPS proxy to a local listening port, but it won’t route every app through the proxy. Apps that ignore the system proxy may still connect directly.

Check the local address and port together

A common mixed port is 7890, but clients may use a different one. Check the current app screen or active configuration. For example, if the client listens on 127.0.0.1:7890 while the system proxy still points to an old app at 127.0.0.1:7897, your browser may report a proxy connection error. A mixed port accepts both HTTP and SOCKS5 connections; it doesn’t automatically sync with system settings.

On macOS, changing network settings or installing a helper may require administrator authentication. Installing a Windows service or setting up a TUN virtual adapter may also require elevated permissions. Check the app name and source before approving a request. You usually don’t need to run the entire client as an administrator just to test the desktop system proxy.

TUN isn’t a required step after installation

TUN routes traffic through a virtual network interface, which can help with apps that ignore the system proxy. It also adds more variables, including routes, DNS, and permissions. Turn it on only after a regular browser test works, and change one setting at a time. If you lose access to local devices, a company network, or another VPN, turn TUN off to compare before adding more DNS settings.

Android and iOS: handle VPN permissions and background limits separately

Android: allow the VPN connection, then check background reliability

Android clients typically use the system VPN interface to route traffic. The first time you tap Start, Android asks to set up a VPN connection. After you approve it, a VPN icon usually appears in the status bar. That icon only confirms the VPN interface is active; it doesn’t mean the subscription is valid or a proxy node is connected.

1. Import and enable the profile, select a node in the policy group, then start the connection.
2. If Android says another VPN is already active, disconnect it first. On a typical personal device, only one service using the system VPN interface can run for a user at a time.
3. Lock your phone for about five minutes, then reopen a webpage to check whether the connection still works. This is a quick reliability check, not a battery-life test.
4. Only if the connection drops in the background, check background restrictions under Settings → Apps → [client] → Battery. Some manufacturers also offer separate Autostart or app-lock settings.

Android 13 and later may also ask for notification permission. This is separate from VPN permission: a persistent notification helps you see connection status, but granting notification access doesn’t establish a proxy connection. Avoid enabling every keep-alive option right away; first see whether the default settings are stable.

iOS: check the app’s supported formats and network extension features

Don’t assume every proxy app on iOS is the same Clash client. Apps vary in which subscription formats, rule syntax, and policy group features they support. Before importing, check the app’s documentation to see whether it supports Clash configurations directly or requires a format from your service provider.

The first time you connect, you’ll usually need to allow the app to add a VPN configuration. Check Settings → General → VPN & Device Management, but verify the app’s connection status and the system VPN status together. School- or work-managed devices may block VPN configuration. If you see a management policy warning, contact your device administrator instead of installing an unknown profile to bypass the restriction.

Port conflicts and certificate warnings: troubleshoot by error type

Port already in use: identify the process instead of killing an unfamiliar service

If the logs show address already in use or a port binding error, another process is probably listening on that port. Quit any old clients or duplicate processes first, then check the port. The commands below use 7890 as an example; replace it with the port your client is using.

On Windows, run this in Command Prompt:

netstat -ano | findstr :7890

Find the LISTENING entry for the local address; the last column shows the PID. Then find that PID in Task Manager under Details. On macOS, run this in Terminal:

lsof -nP -iTCP:7890 -sTCP:LISTEN

If the process using the port needs to keep running, change the proxy client’s mixed port to an unused one, such as 7891, then reapply the system proxy settings. Update the port in any browsers, terminals, or other apps you configured manually, too. Changing the configuration file alone won’t update an old system proxy address.

Tell app-signing issues, website certificate warnings, and node TLS errors apart

• Can’t verify the app developer: This is an installation source or system-signing issue. Check the project’s release channel for system requirements and the correct download. Don’t disable your system’s security protections.
• Your browser says the website’s certificate is invalid: Check your system date and time zone, the website domain, and whether you’re on public Wi-Fi that requires a sign-in. Don’t proceed to sensitive pages anyway.
• The logs show a TLS certificate verification failure: Check the server name in the node settings, the certificate’s validity period, and your system clock, then contact your service provider. Don’t treat skipping certificate verification as a routine fix.

Test the connection: check nodes, rules, and traffic routing separately

A latency test showing a number doesn’t prove that browsing works. A response only confirms that one probe succeeded; rules, DNS, account status, or exit-node restrictions may still prevent a website from loading. Check in the order below so you don’t change too many variables at once.

1. Check the core logs: Look for configuration load failures, port binding errors, or repeated restarts.
2. Check the connection records: Open a website that should use the proxy and see whether a connection to its domain appears. If there’s no record, first check whether the system proxy, VPN, or TUN is routing that app’s traffic.
3. Check the matched policy: Make sure the connection uses the expected policy group instead of accidentally matching DIRECT. If the record shows a rejection, check whether a blocking rule matched.
4. Test one other node: Keep the profile and rules unchanged and switch only the node. If the connection works, investigate the original node instead of reinstalling the client.
5. Try Global briefly if needed: If Global works but Rule doesn’t, focus on the rules and policy group selection. Switch back to Rule mode after testing. Global mode doesn’t expand which apps are routed through the system proxy.

It’s common for a browser to work while terminal apps don’t, because they may be routed differently. Many command-line tools don’t automatically use the desktop system proxy. Once you’ve confirmed 7890 is the current HTTP or mixed port, test with an explicit proxy request:

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

On Windows, use curl.exe to avoid a same-name alias in some PowerShell environments. This command only checks whether the specified request can use the local proxy; it doesn’t prove that every app is routed through it. Check the HTTP status returned by the website alongside the connection logs.

After setup: keep the configuration minimal and check before quitting

Once the connection works, you can consider subscription auto-updates, startup launch, and TUN. Subscription updates may overwrite manual edits. For changes you need to keep, use the client’s override or merge feature where available, and follow its documentation.

• Save the details you’ll need: Note the client name, app version, core version, listening port, and routing method so you can check them later.
• Check the LAN access setting: If you only use the proxy on this device, leave Allow LAN disabled. There’s no need to expose the proxy port to other devices on your network.
• Quit normally once: Turn off the system proxy before quitting the app, then check that your regular connection works again. Force-quitting may leave the system pointed at a local port that’s no longer listening.
• Test again after a restart: Check that the profile is still active, whether the VPN needs to reconnect, and whether the port has changed. Don’t rely on the tray icon alone.

When something goes wrong, check these five layers separately: can the profile load, can the core start, is traffic being routed through it, is the right policy applied, and can the node connect? When asking for help, share your OS and client versions plus a redacted error excerpt. Remove subscription tokens, node passwords, and other sensitive details. For more setup steps, see the Getting Started guide; for specific settings, see Advanced Setup.