Clash First-Time Installation and Setup: Cross-Platform Essentials and Common Pitfalls

Confirm the Client, Core, and Installer

When first-time setup fails, the problem is often not the node but choosing the wrong file at the start. Clash is a general term for a proxy rules system and core; on desktop and mobile, you actually use a graphical client. The most common core today is Clash Meta, also known as mihomo. The client manages subscriptions, proxy groups, system proxy settings, and logs, while the core handles protocol connections, rule matching, DNS, and traffic forwarding.

Before downloading, confirm three details: operating system, processor architecture, and installer format. On Windows 10 22H2 and Windows 11, standard Intel and AMD PCs usually use x64; Windows on ARM devices use arm64. Apple Silicon Macs—M1, M2, M3, and M4—should use arm64 or universal when available; older Intel Macs use x64. If an Android app offers multiple architectures, most recent phones use arm64-v8a.

What to Do When the System Blocks Installation

• Windows: If Microsoft Defender SmartScreen shows a protection warning, first verify that the file came from the project's release page or this site's download center. Once the source is confirmed, select “More info” in the warning and continue. If an administrator policy blocks installation on a work computer, contact the device administrator; repeatedly running the installer will not bypass the policy.
• macOS: After dragging the app into “Applications,” if macOS blocks the first launch, open “System Settings” → “Privacy & Security” and confirm the launch in the security warning section. Do not leave Gatekeeper disabled.
• Android: Android may ask you to allow the browser or file manager to install unknown apps. This permission applies only to the current installation source. After installation, disable it under “Settings” → “Apps” → “Special app access.”
• Linux: An AppImage needs execute permission after downloading. Enable it in the file properties, or run chmod +x filename.AppImage. Debian and Ubuntu use .deb packages; Fedora and RHEL-based distributions typically use .rpm packages.
• iOS: Get a proxy client compatible with mihomo or Clash configuration formats through the App Store. Menu names vary by client, but the first connection always requires approval for the system VPN configuration.

Verify the Subscription Link Before Importing

A subscription link is not an ordinary homepage URL. It usually contains an account identifier and returns a YAML configuration or node list. Do not omit query parameters when copying it, and do not mistake a preview redirect generated by a chat app for the actual subscription URL. Treat the link like an access credential—never post it in screenshots, forums, or public code repositories.

The typical desktop path is “Profiles” → “Import from URL” → paste the subscription URL → “Import.” On Android, the common path is “Profiles” → the plus icon in the top-right corner → “Import from URL.” Compatible iOS clients usually add remote resources from “Profiles” or “Subscriptions.” Menu labels vary by client version, but the core action is to create a remote configuration rather than manually add a single proxy node.

What to Expect After Importing

1. A new subscription name appears in the profile list with a recent update time.
2. After switching to “Proxies,” you can see the proxy groups and nodes.
3. The configuration contains fields such as proxies, proxy-groups, and rules, or equivalent content generated by a subscription converter.
4. The selected profile is enabled, not merely downloaded to the local list.

mixed-port: 7890
mode: rule
allow-lan: false

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Auto Select
      - DIRECT

The YAML above only illustrates the field hierarchy. Actual ports, proxy group names, and nodes come from the configuration. Do not overwrite an existing configuration just to match a tutorial, especially by deleting proxy-groups or rules generated by the subscription. YAML is indentation-sensitive; tabs, a missing space, or duplicate keys can all cause loading failures.

Troubleshooting Subscription Import Errors

• 401 or 403: The link credentials have expired, the account is in an abnormal state, or the server restricts access. Return to the subscription provider and generate a new URL.
• 404: The URL path is incomplete, or the old subscription endpoint has been removed. Check that the copied text starts with https:// and includes all parameters.
• Request timed out: Close Clash first, then use the current direct connection to check in a browser whether the subscription domain is reachable. If needed, switch to a phone hotspot to distinguish a local network issue from a server-side problem.
• Download succeeded but parsing failed: The response may be an HTML error page, a Base64 node list, or a configuration format incompatible with the current client. Check whether the response begins with HTML, then confirm which subscription types the client supports.
• Profile exists but contains no nodes: Check whether the subscription has expired, whether the traffic quota is exhausted, and whether the newly imported profile is actually enabled.

Choose a Mode and Your First Working Node

After importing the subscription, set the mode to “Rule” or rule. Rule mode matches domains, IPs, processes, and other conditions from top to bottom, then sends requests to the corresponding proxy group. Global mode routes most requests through one selected proxy and is useful for temporary comparison tests; Direct mode bypasses the proxy. For first-time setup, avoid leaving Global mode enabled because it can hide problems in proxy groups and rules.

Do Not Judge Nodes by Latency Alone

On the “Proxies” page, find the main proxy group. Common names include “Node Select,” “PROXY,” and “Manual Select.” Choose a node that returns a latency result, then open a webpage to verify it. An 80 ms latency does not guarantee fast downloads; a latency test only shows that the probe address was reachable at that moment. Repeated results of 3000 ms, 5000 ms, or Timeout are a reason to check the node or network connection first.

1. Run one latency test for each of three nodes in the same region.
2. Prefer a node with stable latency and results on two consecutive tests.
3. Open a website that requires a proxy and check whether a new request appears in the connection log.
4. If the page fails, switch to a second node and test again; do not change DNS immediately.
5. If all nodes time out at the same time, check the subscription, system clock, and direct network connection.

An incorrect system clock can cause TLS certificate verification to fail. On Windows, open “Settings” → “Time & language” → “Date & time” and enable automatic time setting; on macOS, go to “System Settings” → “General” → “Date & Time.” Phones should also use automatic date, time, and time zone settings. After correcting the clock, fully quit the client and reconnect.

Do Not Randomly Enable System Proxy and TUN Together

A working node does not mean that application traffic is entering Clash. The client needs at least one traffic interception method: system proxy or TUN. For first-time setup, start with the system proxy because it has a shorter path and is easier to troubleshoot. Desktop clients on Windows and macOS usually provide a “System Proxy” switch; once enabled, browsers and apps that support system proxy settings connect through the local listening port.

How to Check the System Proxy Correctly

Common configurations use 127.0.0.1:7890 as the mixed-port, which accepts both HTTP and SOCKS traffic; some older configurations use 7890 and 7891 separately. Always follow the port shown in the current configuration and client interface. If the configuration uses 7897 while the system proxy still points to 7890, the client may be running normally but webpages will not connect.

• On Windows, check the current proxy status under “Settings” → “Network & Internet” → “Proxy.”
• On macOS, check it under “System Settings” → “Network” → current network → “Details” → “Proxies.”
• If the browser has a separate proxy extension installed, disable it first so its port does not override the system proxy.
• allow-lan: false only affects access from other devices on the local network; it does not prevent this device from connecting to 127.0.0.1.

When to Use TUN

TUN creates a virtual network interface and intercepts traffic from apps that ignore system proxy settings, some command-line tools, and games. Enabling TUN in a desktop client may require service mode or administrator privileges. In common desktop clients, install service mode under “Settings” → “System Settings” first, then enable TUN. Android and iOS establish the virtual interface through system VPN authorization.

During initial troubleshooting, do not enable the system proxy, TUN, a browser extension, and another VPN at the same time. Close other traffic interception tools first and test webpages with only the system proxy enabled. If an app still connects directly, disable the system proxy and test TUN on its own. Using both methods is not always a conflict, but it makes routing, DNS, and bypass-rule diagnosis more difficult.

First-Time Permission Checks Across Five Platforms

Windows: Service Mode and Leftover Proxy Settings

A standard system proxy usually does not require administrator privileges, but TUN and startup features may depend on service mode. If service installation fails, quit the older client first, then check Task Manager for any remaining core processes. After an abnormal exit, Windows may retain manual proxy settings, leaving the browser completely offline even though Clash is closed. Go to “Settings” → “Network & Internet” → “Proxy,” disable the stale manual proxy, reopen the client, and enable the system proxy again.

macOS: Network Extensions and Login Items

The first time you enable TUN or a network extension on macOS, the system displays an authorization prompt. After approval, you may need to enter the device password or use Touch ID. If nothing happens, check the notice under “System Settings” → “Privacy & Security,” as well as the network extension status under “System Settings” → “General” → “Login Items & Extensions.” Avoid repeatedly installing multiple similar clients; their network extensions may compete for control permissions.

Android: VPN Authorization and Battery Restrictions

Android displays a VPN connection request when you tap Start; this system permission is required to create the TUN interface. Usually, only one VPN app can be connected at a time. If the proxy stops after the screen has been locked for a few minutes, open “Settings” → “Apps” → current client → “Battery” and allow unrestricted background activity. Menu names vary slightly by manufacturer. A key or VPN icon in the status bar confirms that the interface exists, but node availability still depends on the connection log.

iOS and iPadOS: VPN Configuration and On-Demand Connections

When you first start a compatible client, iOS requests permission to add a VPN configuration. After approval, view it under “Settings” → “General” → “VPN & Device Management” → “VPN.” If another VPN, enterprise networking tool, or filter is active, disconnect it before testing. On-demand connections start automatically based on network conditions; for initial troubleshooting, temporarily disable the automation, connect manually, and watch the client log.

Linux: Desktop Proxy Settings and Environment Variables

Linux desktop environments do not all support system proxy settings consistently. Even after enabling a system proxy in GNOME or KDE, terminal programs may not inherit it automatically. Set HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY as needed for each program, using the same port as the client's listening port. To intercept more applications, confirm the required permissions before using TUN, and check for conflicts involving the firewall, routing table, and NetworkManager.

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

A Fixed Troubleshooting Order When the Proxy Still Does Not Work

Do not randomly switch a dozen settings. Follow the traffic path from the profile to the exit, checking one layer at a time. Change only one variable per step and refresh the same test page after each change.

1. Confirm the profile is enabled: The selected profile should be the newly imported subscription, not the client’s built-in example.
2. Confirm the node connects: The main proxy group must not be set to a failed node or accidentally set to DIRECT.
3. Confirm the mode: Use Rule mode. Temporarily switch to Global mode for one test to determine whether the issue is with the node or the rules.
4. Confirm the listening port: Check the core log for a port conflict. If 7890 is occupied by another program, quit the old proxy tool and restart the client.
5. Confirm the traffic entry point: Enable only one of the system proxy or TUN, then refresh the webpage and check the connection log.
6. Confirm the matched rule: If the request matches DIRECT, check whether the rule sends that domain directly. If it matches a proxy group, check which node that group has actually selected.
7. Check DNS last: Only troubleshoot DNS when domain resolution fails, an IP works while its domain does not, or the log clearly reports a DNS error.

Use Logs to Distinguish Three Types of Failure

The browser’s Secure DNS can also change the resolution path. If ordinary websites open but a specific domain fails to resolve, temporarily disable Secure DNS in the browser for a comparison test. Once the cause is clear, choose between system DNS, client DNS, or browser-configured DoH; do not change all three at once.

First-Time Setup Completion Checklist

The initial configuration is stable only after completing the items below. If a problem appears later, use the same checklist to determine whether the subscription changed, a node failed, or another app modified the system settings.

• The installer matches the current system and processor architecture, and the client starts normally.
• The subscription imports successfully, the profile list shows a recent update time, and the Proxies page displays proxy groups.
• The mode is set to Rule, and the main proxy group has a clearly selected working node.
• At least one of the system proxy or TUN is working, with no second VPN intercepting traffic at the same time.
• When you refresh the test page, the connection log shows the domain, matched rule, proxy group, and node.
• Closing the client also disables the system proxy, preventing a stale setting from pointing to an inactive local port.
• You know where to update the subscription, but have not configured an excessively frequent automatic update interval.
• The subscription URL does not appear in public screenshots, browser sharing history, or public documents.