Clash First-Run Setup: Permissions, Ports, and Subscription Import

Set up in order: start the core, then test the connection

After the first launch, make sure the client can start the core before importing a subscription, enabling a configuration, and selecting a node. Turn on the system proxy or TUN last. Don’t change ports, DNS, and routing rules all at once. Change one setting at a time so you can identify what fixed the issue.

The Clash GUI handles the interface and system integration; the core parses configurations and routes connections. With the mihomo core, a working interface doesn’t mean a configuration has loaded. Likewise, a configuration in the list isn’t necessarily the one currently running. Check the running status and startup logs before testing the network.

1. Check the installer architecture. Choose x64 or ARM64 for your device. macOS downloads also vary by processor architecture. The wrong build may fail to launch or rely on system translation.
2. Keep the initial network state unchanged. Quit other proxy clients and VPNs first to prevent multiple apps from changing the system proxy, virtual network adapters, or default route at the same time.
3. Make sure the core is running. Check the startup result in the client logs. Address configuration parsing errors, port binding failures, and permission errors first.
4. Import and enable a configuration. After updating the subscription, select the configuration you want to use and check that its nodes appear in the proxy groups.
5. Test one traffic-handling method at a time. On desktop, start with the system proxy. Test TUN only if you need to route traffic from apps that ignore proxy settings.

First launch on Windows: security prompts, service permissions, and firewall rules

Verify the source before proceeding past installation prompts

If Windows displays a security prompt, verify the installer’s source, the download page details, and the file properties first. Stop if you can’t confirm where it came from. On managed devices, leave installation policies and administrator access to your IT administrator. Don’t disable system protection just to launch the client.

On Windows 11, go to Settings → System → About to check your system type. If the interface opens but the core exits immediately after installation, check the logs first. Reinstalling the GUI usually won’t fix a YAML syntax error or a port conflict.

Service mode is not the same as the system proxy

• System proxy: Registers a local proxy address with the operating system. For everyday desktop use, you usually don’t need to run the client as an administrator.
• Service mode: Runs tasks that require elevated permissions through a background service. The exact scope depends on the client. Installing or repairing the service may trigger an administrator permission prompt.
• TUN mode: Creates a virtual network interface and configures routes, often requiring a service or administrator permissions. Having the service installed doesn’t mean TUN started successfully.

If the TUN logs report insufficient permissions, check the service status shown in the client first. If they report a failure to create a virtual interface or route, check whether another VPN is already handling network traffic. Don’t keep toggling the switch without checking the first error.

Allow firewall access only where needed

For local use, have the proxy listen on the loopback address; there’s no need to allow inbound LAN connections. If you want a phone to use your computer’s proxy, check Allowed apps or inbound rules under Windows Security → Firewall & network protection, and limit access to trusted networks. Firewall access and the client’s allow-lan setting are separate requirements; enabling one doesn’t enable the other.

macOS and Android: confirm traffic handling after granting permissions

macOS: finish installation before setting up helper services

If the installer asks you to drag the app into Applications, do that before launching it. If macOS blocks the app, verify its source, then review the relevant prompt under System Settings → Privacy & Security. Grant permission only to an app you’ve verified; don’t lower security settings globally. Prompts vary by macOS version and the app’s signing status.

If the client asks to install a helper tool or service, make sure the request comes from the client you just launched before entering administrator credentials. This permission is generally used for system network settings or TUN support. It isn’t a subscription login step, and a subscription URL should never require your device administrator password.

To troubleshoot the system proxy, go to System Settings → Network → your current connection → Details → Proxies. The HTTP and HTTPS proxy entries should point to the actual listening address and port. If an old automatic proxy configuration is also enabled, check whether it’s required by your work network before changing it.

Android: check VPN permission and background activity separately

Android clients typically route traffic through the system VPN interface. When Android prompts you to connect to a VPN for the first time, verify the app name before granting access. Root isn’t needed for most everyday setups. Desktop instructions for setting a system proxy don’t apply directly to Android clients.

1. Disconnect any other active VPN first. In a typical personal setup, only one VPN service can be active at a time.
2. Start the client and approve Android’s VPN prompt. Check that the system VPN status matches the connection status shown in the client.
3. If the VPN disconnects as soon as it starts, search for “VPN” in Android settings. Check whether another app has Always-on VPN enabled or is set to block connections without a VPN.
4. If traffic stops only after the screen locks, check the app’s battery and background activity settings. Menu names vary by device; don’t set every app to unrestricted battery use.

If a browser works but a particular app doesn’t, check the per-app proxy list. The app may be excluded, or the client may be set to proxy selected apps only. Don’t assume the subscription has expired.

Port conflicts: find the listener before changing mixed-port

If the logs show address already in use or a port binding failure, identify the process using the port first. Common causes include an old client that’s still running, a background service that hasn’t stopped, or another tool using the same port. Closing a window doesn’t always stop the background process.

This example uses 7890 to illustrate troubleshooting; it isn’t the default for every client. Check the actual port in the current settings or running configuration, then replace the number in the commands below.

Check local TCP listening ports

On Windows, run this in Command Prompt:

netstat -ano -p tcp | findstr LISTENING | findstr ":7890"

Check the local address and port in the results, then note the PID in the last column. In Task Manager, open the Details tab to identify the process. Don’t end an unfamiliar system process.

On macOS, run this in Terminal:

lsof -nP -iTCP:7890 -sTCP:LISTEN

If the process belongs to an old proxy client, quit that app normally first. If you decide to change ports, you could set the mixed port to 7897, but make sure the new port is available. Update any terminals, browsers, and other devices where you entered the proxy settings manually. For a system proxy managed by the client, enable it again and verify the settings.

Don’t confuse the mixed port with the controller port

Subscription import errors: check download, parsing, and activation separately

An “import failed” error can occur at three different stages: the client can’t retrieve the subscription, the core can’t parse its contents, or the imported configuration isn’t enabled. Identify the stage before deciding what to try next. Pasting the same URL repeatedly rarely reveals anything new.

Stage 1: Can the subscription URL retrieve content?

• Check what you copied. Copy the complete subscription URL, without leading or trailing spaces or line breaks. Don’t use an explanatory note, account dashboard URL, or single-node link in place of a full configuration subscription.
• Check the response status. 401 often indicates an authentication issue; 403 means the request was denied, so check the service’s guidance; 404 usually means you should verify the URL; and 429 means stop retrying and wait.
• Check the system clock. An incorrect date can cause HTTPS certificate validation to fail. Sync the system clock first; don’t bypass the problem by disabling certificate verification.
• Check how the subscription is fetched. If subscription updates are set to use the proxy before a working configuration is available, you can end up with a startup dependency. Check whether the client offers a direct-update option and test it on a network that allows access.

If the URL opens in a browser, that only confirms the browser’s network path works. The client may use different proxy settings, request headers, or network access. A login or error page isn’t a usable YAML configuration, even if the request reports success.

Stage 2: Does the response format match the core?

A single-node URI, a collection of nodes, and a complete Clash configuration are different types of content. Make sure the subscription service provides a format supported by your client. If the nodes use extensions supported by mihomo, verify that the client is actually running a compatible core; the GUI’s name alone isn’t enough.

For a YAML parsing error, note the line number and error type in the logs. Inconsistent indentation, incorrect field types, and unsupported protocols can all prevent a configuration from loading. Don’t delete fields at random. Back up the configuration, then check the supported features in the core protocol reference.

Stage 3: Did the imported configuration become active?

After a successful subscription update, check which configuration is marked as current, what the proxy groups contain, and the latest load log. Select a node manually and make sure the proxy group referenced by the rules exists before visiting the target site. If the logs report a missing proxy group, fix the group name or rule reference instead of changing DNS.

Test the connection: use three layers to pinpoint the issue

On desktop, first verify the local proxy endpoint, then the system proxy, and finally the rules. On Android, start with VPN status and per-app routing. A speed test only measures responses from a specific test target; it doesn’t confirm that the app you need can connect.

Stage 1: Test the local proxy endpoint directly

On desktop, use the following command to specify an HTTP proxy explicitly. The example port is 7890; replace the test URL with one you need to access and know is available. On Windows, use curl.exe; on macOS, use curl.

curl.exe --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 -I https://clash67.com/

If the connection is refused, check that the core is listening on the right port. If the connection is established but times out, check the node, target site, and rules. This test doesn’t depend on the system proxy toggle, but it is still affected by the core’s current mode and routing rules. One successful request doesn’t prove that every app or destination will work.

Stage 2: Check whether the app uses the system proxy

If an explicitly configured proxy works but your browser doesn’t, verify that the system proxy address is 127.0.0.1, the port matches, and the browser isn’t using its own proxy settings. Command-line tools don’t always read the system proxy. If needed, configure environment variables separately or use TUN when there’s a clear need.

Stage 3: Check which rule handles the connection

Find the target domain in the client’s connection list and check whether it matched a direct, proxy-group, or reject rule. If there’s no connection record, first check whether the traffic reached the client. If a record shows the wrong policy, review the rule order or proxy-group selection. Investigate DNS only when the logs point to a domain resolution failure; not every connection issue is a DNS issue.

If you need TUN, enable it separately and repeat the same test. TUN coverage still depends on routes, exclusions, per-app settings, and platform limitations; enabling it doesn’t guarantee that every connection will be routed through it. If something breaks, turn TUN off and return to the verified setup before making other changes.

Exit and recovery: keep a record of settings you can restore

After your initial setup, record the client and core versions, proxy port, active configuration name, and whether the system proxy and TUN are enabled. When asking for help, include your operating system version, the first relevant error, and steps to reproduce it. That’s more useful than simply saying “the internet isn’t working.”

• No internet after quitting: Check whether the system proxy still points to a local port that’s no longer active. If the client set it, restart the client, turn off the system proxy, then quit normally.
• Problems persist after turning off TUN: Check whether another VPN is still running and verify the system’s network status. If needed, save the logs, then restart the client or device. Don’t delete unfamiliar network interfaces.
• Issues after a subscription update: Compare the nodes, group names, and rule references before and after the update. Check whether local overrides still apply.
• Before changing DNS again: Save the current working configuration, then read the Getting Started guide to Fake-IP. Change one setting at a time.

Check four things before you’re done: the core is running, the right configuration is active, traffic is reaching the expected entry point, and connections are matching the expected rules. Once all four check out, add features such as launch at startup or LAN sharing; they’ll be easier to maintain.