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

1. Before Installing: Check Your Platform, Architecture, and Config Source

Before installing a Clash client, check three things: your operating system, your device’s processor architecture, and whether you already have a working configuration. Installing the client gives you a local proxy interface; it does not create proxy nodes you can connect to. If you don’t have a config, repeatedly switching the system proxy or TUN mode usually won’t help.

Clash is a common name for the proxy core and its ecosystem; clients handle config management, node selection, and system settings. Clash Meta was later renamed mihomo and is one of the cores in this ecosystem. Different clients may use different cores, so a similar-looking interface doesn’t mean their config fields are interchangeable. Before importing a config, check the client’s About or core information and note both versions for troubleshooting.

2. First Launch: Grant Permissions for the Right Reasons

On first launch, make sure the interface opens correctly, then import your config, and enable the system proxy or virtual network adapter only if needed. On desktop, system proxy settings, core startup, and the TUN service require different permissions. Don’t assume every permission prompt means you need to grant administrator access.

Windows and macOS

• Windows: If TUN asks to install a service or requests administrator access, check the program path shown in the prompt first. Routine use shouldn’t require running the app as an administrator all the time. If Windows Security blocks a file, check the specific item under Virus & threat protection → Protection history; don’t disable real-time protection altogether.
• macOS: If macOS blocks the app from opening, first verify the download source and the OS versions supported by the product. For an app from a known source that you need to run, follow the prompts in System Settings → Privacy & Security. Don’t bypass the warning by disabling system security globally.
• Service permissions: Some clients use a helper service to configure routing. If service installation fails, check the client’s service status and logs. Being able to enable the system proxy doesn’t mean the service required for TUN is installed.

Android, iOS, and Linux

• Android: When you first connect, Android will usually ask to set up a VPN connection. Confirm that the request comes from the client you just installed. Disconnect other apps using Android’s VPN slot first, including some local firewalls and filtering tools.
• iOS: When connecting for the first time, follow the system prompt to add a VPN configuration and authenticate on your device. VPN permission and subscription import are separate steps: even after a subscription imports successfully, you still need to start the connection.
• Linux: A desktop client’s system proxy may depend on your desktop environment, while TUN usually needs additional permissions or a service. Set up services as documented by the product. Don’t recursively grant broad permissions to the entire client directory or assume you should run the whole interface as root.

On mobile, connections run through a system-approved VPN extension or service; the app doesn’t need to stay in the foreground. If Android disconnects after the screen locks, check background restrictions under Settings → Apps → the client → Battery. The exact labels vary by manufacturer. On iOS, check the VPN status and client connection logs; preventing background cleanup isn’t a substitute for troubleshooting the connection.

3. Import Your Config: Check It Before Connecting

1. Open the client’s Config or Subscription page and choose New, Add, or Import. Menu names vary by product; the goal is to create a config entry.
2. Paste a compatible subscription link from your provider or select a local YAML file. Don’t use the provider’s account management page URL as the subscription link.
3. Wait for the download and parsing to finish, then check the update time, node list, and proxy groups. Seeing a subscription entry name alone doesn’t mean the config is ready to use.
4. Set this config as the active one. If the client separates Download and Enable actions, make sure to enable it too.
5. Open the Proxy page, select a node from one of the config’s proxy groups, and test the connection.

If a subscription update fails, identify the stage where the error occurs. A download timeout is a retrieval issue. A login page, CAPTCHA, or error page in the response points to a response-content issue. YAML line numbers or invalid field types indicate a config parsing problem. Don’t assume every failure means the node is down.

When editing YAML locally, use spaces for indentation and don’t mix in tabs. Configs with proxy-providers or rule-providers may also need to download remote resources, so check that providers have finished loading even after the main config imports successfully. If an older core doesn’t recognize newer fields, check the config’s requirements against the core’s capabilities instead of deleting fields just to clear the error.

4. Initial Settings: Mixed Port, Routing Mode, and Local Listening

For an initial desktop setup, keep the path simple: confirm the active config works, start the core, choose a routing mode, check the local listening port, and then enable the system proxy. On Android and iOS, the client’s connect button usually starts the system VPN; you don’t need to copy the desktop system proxy setup.

Rule, Global, and Direct modes

Rule mode selects an outbound based on the match order in the current config. Global mode sends traffic handled by the core to the global selection group. Direct mode connects to the destination from your device. Global mode does not automatically route traffic from apps that don’t use the system proxy into the core. If a site won’t load, you can briefly switch modes to help identify a rule issue, then switch back. Don’t treat Global mode as a way to capture all system traffic.

What a minimal config snippet can—and can’t—do

The snippet below illustrates common mihomo fields only; it is not a complete internet access config and should not replace your subscription. Use the port actually set on your device. A graphical client may generate or override these fields.

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

127.0.0.1 is the local loopback address. The proxy port and controller port serve different purposes; don’t enter the controller address used to connect to the dashboard as your browser’s proxy server. Initial setup also doesn’t require exposing the controller to devices on your LAN.

5. Test in Order: Core, Explicit Proxy, Browser

Don’t rely on the tray icon or connection switch alone to decide whether it’s working. Follow the steps below and change only one condition at a time. First check the logs for config loading or listener errors, then confirm a node is selected, and finally compare an explicit proxy request with browser access.

Test the local port with a single request

These commands assume the mixed port is actually 7890. In Windows PowerShell, use curl.exe to avoid environments where curl resolves to a different command. On macOS and Linux, use curl. The command times out after 15 seconds and won’t change your system proxy settings.

# Windows PowerShell
curl.exe -I --proxy http://127.0.0.1:7890 --max-time 15 https://example.com

# macOS / Linux
curl -I --proxy http://127.0.0.1:7890 --max-time 15 https://example.com

• Connection refused: First check whether the core is running, whether the port is correct, and whether the client is listening on a different address.
• Only a CONNECT success message: The HTTP proxy tunnel may be established, but you still need to see the destination site’s response. This alone doesn’t confirm that the full HTTPS request succeeded.
• Response from the destination site: The request through the local proxy completed. A status such as 403 may reflect the site’s own policies and doesn’t mean every destination will be reachable.
• Timeout or TLS error: Check the node, DNS, system time, and destination site against the client logs. Don’t disable certificate verification.

If an explicit proxy request succeeds but the browser fails, check browser proxy extensions, custom proxy settings, and the system exception list. If the browser works but a direct terminal request fails, that doesn’t necessarily indicate a client problem: command-line tools often don’t use the desktop system proxy. You can pass the --proxy option to the command or configure proxy environment variables for tools that explicitly support them.

A latency test measures the client’s response time to a particular test address. It doesn’t measure download bandwidth or prove that every site is reachable. After confirming the selected item in the proxy group, check the Connections page or logs for the rule and outbound records to see which route the request actually took.

6. Common First-Install Problems: Diagnose by Symptom

Port already in use: only one process can listen on an address

If the logs show address already in use or a bind failure, first quit older proxy clients, duplicate core processes, and debug tools using the same port. On Windows, run netstat -ano | findstr :7890 to check local addresses, status, and PID; don’t mistake a connection that shows 7890 only as a remote address for a listening process. On macOS, run lsof -nP -iTCP:7890 -sTCP:LISTEN. On Linux, run ss -ltnp to check listening sockets; additional permissions may be needed to see process details.

Identify the process before stopping it; don’t terminate an unknown system process. If you switch to 7891, first make sure the new port is free, then update the system proxy, any custom browser proxy, and your test commands. Changing the client’s port alone leaves other apps pointing to the old address.

The interface opens, but the core won’t start

Check the logs to determine whether the issue is a missing executable, architecture mismatch, config parsing failure, or insufficient permissions. If security software quarantines the core, the interface may still open, so check both Protection history and the client’s core path. Only take action on the specific file after confirming its source, alert details, and product documentation. Don’t add the entire downloads folder to a permanent exclusions list.

Network drops or LAN becomes unreachable after enabling TUN

Turn off TUN first and restore the system proxy setup you already verified. Then check whether another VPN is running, whether the helper service is working, whether routes are overriding your company’s internal network, and whether DNS settings conflict with the current network. TUN affects routing and name resolution, so copying a tun: config block alone won’t make it suitable for every platform and network. On a managed work device, follow your organization’s policies; don’t force changes to managed routes for testing.

Browser still can’t connect after quitting the client

This usually means you should check for a leftover system proxy, not reinstall the browser. On Windows 11, check the manual proxy under Settings → Network & internet → Proxy. On macOS, check System Settings → Network → your current network → Details → Proxies. If the setting still points to a stopped local port, restore the settings you had before installation. Don’t remove organization-managed PAC or proxy settings without authorization.

7. Installation Checklist and Ongoing Maintenance

• Confirm that the installer matches your processor architecture, both the client and core start, and the logs show no recurring errors.
• Confirm that the active config is enabled, the proxy groups offer nodes to choose from, and subscription provider resources have loaded.
• Note the actual mixed port and current routing mode; don’t assume the example port in this guide is fixed for your device.
• On desktop, test one explicit proxy request and one browser visit. On mobile, check the system VPN status and open the destination page.
• After restarting your device, check that the client starts as expected and that the system proxy or VPN status matches whether the client is running.
• Keep a record of your proxy settings from before installation and a copy of your config. Confirm that your normal connection works again after disconnecting.

Once the connection works, decide whether to enable startup, automatic subscription updates, or TUN. Set the subscription update interval according to your provider’s requirements; refreshing every minute won’t fix connection problems. Before upgrading the client, note its version and current settings. After upgrading, verify config loading, port listening, and your usual apps before restoring complex rules or LAN sharing.

When asking for help, include your OS version, processor architecture, client and core versions, steps to reproduce, and logs from around the time the error occurred. Saying “explicit proxy works, but the browser doesn’t” is more useful than just “can’t connect.” Remove subscription credentials from logs and screenshots. For problems with a specific site, say whether it happens only in Rule mode.