Installing Clash Client for the First Time: Cross-Platform Setup Guide and Common Pitfalls

Confirm your client, system, and configuration before installing

“Clash” commonly refers to the rule-based proxy core, its configuration format, and a range of graphical clients. The original Clash core is no longer maintained; today’s desktop clients commonly use Clash Meta, also known as mihomo. Menu names vary between clients, but initial setup generally covers four areas: configuration files, proxy mode, system proxy, and TUN.

Check your operating system architecture before downloading. Windows 10 22H2 and Windows 11 devices typically use x64; Windows devices with Snapdragon or other ARM processors use arm64. Choose x64 or amd64 for Intel Macs, and arm64 for Apple M1, M2, M3, and M4 Macs. Linux also requires choosing between amd64 and arm64, as well as package formats such as deb, rpm, and AppImage.

What to prepare before the first launch

• An installer that matches your operating system and processor architecture.
• A working Clash configuration, usually a subscription URL or YAML file.
• Administrator privileges for installing the app, writing system proxy settings, or creating a virtual TUN interface.
• A basic internet connection for the initial subscription download and node test.

How installation differs across five platforms

Complete subscription import and configuration updates in order

After installation, do not enable TUN or change DNS and ports at the same time. Start by importing the configuration and confirming that the client can parse proxy nodes, proxy groups, and rules. If something goes wrong, this makes it easier to determine whether the problem lies with the subscription, the node, or system traffic interception.

Method 1: Import from a subscription URL

1. Copy the complete subscription URL and check that it starts with https://. Do not omit any trailing parameters.
2. Open the “Configuration” or “Profiles” page in the client.
3. Choose “New Subscription,” “Import from URL,” or a similar option.
4. Paste the URL, give it a recognizable name, then download or save it.
5. Wait for the configuration list to show an update time, node count, or file size.
6. Select the newly imported configuration to make it active.

The exact path varies between graphical clients. A common desktop path is “Configuration” → “New” → “URL”; on Android, it is often “Configuration” → “+” in the top-right corner → “Import from URL.” If the interface offers both “Proxy Collections” and “Subscription,” choose the full configuration subscription for first-time setup. A standalone proxy collection usually lacks rules, DNS settings, and proxy-group definitions.

Method 2: Import a local YAML file

If you already have a .yaml or .yml file, choose it from “Configuration” → “Import Local File.” Do not resave YAML with a document editor; indentation, spaces after colons, and UTF-8 encoding can all affect parsing. A configuration’s top level usually includes proxies, proxy groups, and rules. mihomo extensions may also include rule-providers, tun, and dns.

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

proxies:
  - name: Example
    type: socks5
    server: 127.0.0.1
    port: 1080

proxy-groups:
  - name: Proxy
    type: select
    proxies:
      - Example
      - DIRECT

rules:
  - MATCH,Proxy

The snippet above illustrates structure only and cannot replace a real subscription. mixed-port: 7890 means HTTP and SOCKS inbound traffic share port 7890; use the port shown in the client’s active configuration. Some clients separate ports such as 7890 and 7891, while others may select an available port automatically.

Run these three checks after importing

• The configuration status should show success, not 404, timeout, parse failure, or empty content.
• The “Proxies” page should show proxy groups, with at least DIRECT and one selectable node available.
• Run a latency test manually. A result ranging from tens to hundreds of milliseconds only shows that the test connection is reachable; it does not mean every website will be accessible.

Choose between Rule, Global, and Direct modes

Once the configuration works, open the “Proxies” page and choose a mode. Rule, Global, and Direct generally mean rule-based routing, sending all traffic through one global proxy group, and bypassing proxies for all traffic. For first-time use, choose Rule mode, then select a node with a normal latency in the relevant proxy group.

Rule mode is best for everyday use

Rule mode determines where connections go based on domains, IP addresses, processes, or rule sets. For example, local network addresses can connect directly, selected domains can enter a proxy group, and all remaining traffic can be handled by a final MATCH rule. Rules are matched from top to bottom and stop at the first match, so specific rules should come before broad ones.

• Rule: Routes traffic according to the configured rules and is suitable for long-term use.
• Global: Sends all client-intercepted connections through the global proxy group and is useful for briefly diagnosing missed rules.
• Direct: Sends intercepted connections directly without proxy nodes and helps determine whether a node is causing the problem.

“Global mode” does not mean the client automatically intercepts all system traffic. Whether an app enters Clash still depends on the system proxy, the app’s own proxy settings, or TUN mode. Browsers that follow the system proxy are usually intercepted directly; some games, command-line programs, and apps with independent network stacks may bypass it.

Choose the proxy group first, then the node

Subscriptions often nest groups such as “Node Select,” “Auto,” and “Fallback.” A manual group requires you to choose a node; a URL-Test group selects one automatically based on a test URL and interval; a Fallback group generally uses the first available node in its list. If node latency looks normal but websites still fail to load, check whether the effective proxy group is still set to DIRECT.

Use connection logs to confirm the match

Most clients show the target domain, traffic volume, matched rule, and outbound path on the “Connections” page. Open a test page and watch for a new connection. If it shows DIRECT, a direct rule matched; if it shows “proxy group → node,” the proxy path is working. This is more useful for diagnosing routing issues than repeatedly switching nodes.

Enable the system proxy and verify the port

Once the rules and node are selected, enable the system proxy. Desktop clients usually provide a “System Proxy” switch; when enabled, the client writes the operating system’s HTTP and HTTPS proxy address as a local loopback address such as 127.0.0.1:7890. Before closing the client, exit it normally so the program can remove the system proxy settings.

Windows and macOS

On Windows, check the current proxy status under “Settings” → “Network & internet” → “Proxy.” After the client takes over, the manual proxy usually points to 127.0.0.1 and the current mixed port. If no websites open after quitting the client, return to this page, disable any leftover manual proxy, and restart the client.

On macOS, check the web proxy and secure web proxy under “System Settings” → “Network” → the current network → “Details” → “Proxies.” The system may request an administrator password the first time you make changes. Do not let two proxy clients write to these settings simultaneously; the app started later may overwrite the earlier address and port.

Linux desktops and environment variables

Desktop environments such as GNOME and KDE can use a system proxy, but terminal programs may not read desktop settings. To temporarily route command-line requests through the local mixed port, set environment variables in the current terminal:

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890

These variables affect only the current terminal and its child processes. The port must match the inbound port shown under the client’s “General Settings” or “External Control” page. A common controller port is 9090; it connects the client interface to the core and is not the proxy port to enter in a browser.

VPN interception on Android and iOS

Mobile operating systems usually intercept traffic through a local VPN interface rather than desktop-style system proxy settings. When Android makes its first connection request, approve it; a key or VPN indicator then appears in the status bar. iOS and iPadOS ask to add a VPN configuration and authenticate with the system. If permission is denied, other apps will not enter the proxy path even when the configuration and nodes work correctly.

Verify the setup in two steps

1. Keep Rule mode enabled, open the connection log, and visit a normal webpage. Confirm that a new connection appears with a matched rule.
2. Disable the system proxy or disconnect the mobile VPN, then revisit the page and compare whether new connections stop appearing in the log.

Do not rely only on whether the browser homepage opens. Browser and DNS caches, along with existing long-lived connections, can delay visible changes. Use a new private window or wait for old connections to close before visiting a domain you have not opened yet.

When to enable TUN mode

TUN mode creates a virtual network interface that sends more TCP, UDP, and DNS traffic into the mihomo core. It is useful for apps that ignore the system proxy, some game launchers, command-line tools, and situations requiring unified traffic interception. If your browser already works normally through the system proxy, TUN is not required for initial setup.

The right order before enabling it

1. First confirm that the subscription updates successfully and that the proxy group contains an available node.
2. Enable only the system proxy and verify that browser traffic is routed according to the rules.
3. Exit other VPNs, network accelerators, and similar proxy programs.
4. Install the background service under “Settings” → “Service Mode.”
5. Grant administrator, network extension, or VPN permissions when prompted.
6. After enabling TUN, check DNS, connection logs, and local network access again.

Windows clients often use service mode with administrator privileges to create a virtual network adapter; macOS requires approval for a network extension; Linux typically needs CAP_NET_ADMIN, root privileges, or a systemd-managed core. Android and iOS already intercept traffic through a VPN interface, so they generally do not offer the same desktop-style “TUN switch.”

What to do if TUN cuts off the internet

• Disable TUN first while keeping the Rule mode and configuration. Do not reset every setting at once.
• Check whether another VPN virtual adapter is still connected.
• Confirm that the client core is running and that the Connections page is not showing recurring permission errors.
• Check whether another program is using the DNS listening port; port 53 is a common source of conflicts.
• If the problem remains after restarting the client, restart the system to clear stale routes and virtual-interface state.

Permissions and installation blocks across five platforms

Windows: firewall, service mode, and port conflicts

When Windows Defender Firewall asks for permission on first launch, the right choice depends on your intended scope. If Clash is used only on this computer and allow-lan is false, there is no need to provide proxy access to devices on the local network. If the client cannot start the core, check Task Manager for an older instance, then run netstat -ano | findstr :7890 to see whether port 7890 is occupied.

If TUN still cannot be enabled after installing service mode, go to “Settings” → “Apps” → “Installed apps” to confirm the client version, then return to the client’s “Settings” → “Service Mode” and uninstall and reinstall the service. Do not simply delete a program directory that is still running, or the background service may retain an invalid path.

macOS: app verification and network extensions

After dragging the app from the DMG into “Applications,” launch it from there rather than running it long-term from the disk image. If macOS blocks it, open “System Settings” → “Privacy & Security” and review the relevant prompt, then verify the app source and downloaded file. After approving the network extension, its status appears in the menu bar or system network settings.

Linux: graphical sessions, tray support, and permissions

Install a deb package with sudo apt install ./package.deb; for rpm packages, use the package manager provided by your distribution. AppImage files usually need execute permission, for example chmod +x package.AppImage. Some lightweight desktops lack tray support, making the window difficult to reopen after closing. First confirm that the process is still running instead of launching multiple core instances.

Android: battery optimization and background operation

Android may restrict a VPN client after the screen is locked. Open “Settings” → “Apps” → the relevant client → “Battery,” then choose Allow background activity or Unrestricted, depending on the device. Names vary by manufacturer. If the connection drops after a few minutes and the client disappears from recent apps, check battery policies first rather than repeatedly changing subscriptions.

iOS and iPadOS: VPN configuration and on-demand connections

Approve the system VPN configuration on the first connection. If the VPN indicator briefly appears in the status bar and then disappears, return to the client and check configuration parsing, node handshakes, and DNS logs. Some compatible clients offer “On-Demand” connections that activate automatically based on Wi-Fi, cellular networks, or domains. During initial setup, connect manually first and add automation only after the basic path works.

Step-by-step troubleshooting order for common beginner issues

The configuration imported successfully, but no nodes appear

First verify that the imported content is actually Clash YAML. Some URLs return a webpage, login prompt, or another client’s format; the client may finish downloading without creating proxy groups. Check the update time, file size, and parse errors. If you use a subscription converter, confirm that the output format is Clash or Clash Meta rather than a generic list containing only individual URIs.

Latency tests pass, but the browser cannot open websites

1. Confirm that the system proxy or mobile VPN is enabled.
2. Check that the current mode is Rule, not Direct.
3. Verify that the main proxy group has an available node selected.
4. Open the “Connections” page and confirm which rule actually matched the request.
5. Temporarily switch to Global for testing. If Global works, the issue is usually in rule matching.
6. If Global also fails, check the node, DNS, system time, and local firewall.

Only some apps bypass the proxy

The app may ignore the system proxy, use UDP, or specify its own DNS. Verify the system proxy path with a browser first. If the browser works but the target app produces no connection log entries, test TUN. If the app appears in the log after TUN is enabled but still fails, inspect its protocol, destination port, and matched rule. Do not confuse “not intercepted” with “node unavailable.”

Devices on the local network cannot use the local proxy

Using 127.0.0.1 on the host allows access only from that host. If you need to provide a proxy to devices on the same local network, first understand the exposure, then enable “Allow LAN connections” and have the other device enter the LAN address of the device running Clash, such as 192.168.1.20:7890. Also check inbound firewall rules and disable this capability when finished.

The system cannot connect to the internet after quitting the client

The system proxy was usually left enabled. On Windows, go to “Settings” → “Network & internet” → “Proxy” and disable the manual proxy; on macOS, open “Details” → “Proxies” for the current network and clear the relevant entries; on Linux, unset HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY in the current terminal. If TUN was enabled, also confirm that its virtual interface and background service have stopped.

Recommended checklist after the first installation

Initial setup is complete only after all the items below are checked. If updates fail, rules behave unexpectedly, or a specific app cannot connect later, start troubleshooting with the most recently changed component instead of reinstalling the client.

• The client package matches the operating system architecture.
• The subscription updates manually, with a normal update time and content.
• The active configuration is enabled, and the Proxies page contains proxy groups and nodes.
• The mode is set to Rule, and the main proxy group has a selected node or an automatic test group.
• The system proxy or mobile VPN has the required permissions.
• When visiting a test page, the connection log shows the matched rule and outbound node.
• The automatic subscription update interval is set to a reasonable value, such as 1440 minutes.
• Enable TUN only when an app does not follow the system proxy, then verify DNS and routing separately.
• Know how to exit the client normally so system proxy settings are not left behind.

The key to a reliable first setup is changing one thing at a time: import the subscription, choose a rule mode and node, enable system interception, and configure TUN only if needed. Check the status and connection log after each step so any failure can be narrowed to a specific stage.