Clash First-Run Setup: System Proxy, Mixed Port, and Startup Issues

First launch: Check your config, core, and outbound connection

A Clash client window opening doesn’t mean your proxy connection is working. The full path includes the client loading a config, the core listening on a local port, the app sending traffic to the core, and a rule selecting a working outbound. Check each step in that order during initial setup. Don’t enable the system proxy, TUN, and several network tools all at once, then guess at the cause by refreshing a page.

This guide focuses on desktop Clash clients, including those using the Clash Meta (mihomo) core, and notes key differences on Android and iOS. Menu labels vary by client. System proxy settings, rule modes, and virtual network interfaces operate at different levels, so don’t assume desktop controls work the same way on a phone.

1. Load a config: Import a compatible config from your provider on the client’s subscription or config page. Once the update succeeds, set it as the active config. Seeing a file in the list doesn’t mean it’s enabled.
2. Check the core logs: Look for YAML parsing errors, references to missing proxy groups, or port binding failures. If errors keep appearing, fix the config before changing system network settings.
3. Choose a rule mode: For your first run, keep the rule mode specified by the config. Global mode simply routes connections through the global policy; it won’t fix incorrect node settings.
4. Check proxy groups: If a group requires manual selection, choose an available node. If DIRECT is selected, matching traffic will still connect directly. A successful latency test only confirms that the test target is reachable; it doesn’t guarantee access to every site.

System proxy: Which apps use the local port

On desktop, the “system proxy” setting typically changes the operating system’s proxy settings to direct apps that honor them to a local address, such as 127.0.0.1:7890. It doesn’t capture all network traffic. Some games, command-line tools, browsers with their own proxy settings, and certain UDP traffic won’t automatically use this setting.

Windows: Check the proxy address, not just the tray icon

In Windows 11, open Settings → Network & internet → Proxy and check that the address and port under Manual proxy setup match the client. Clients may configure the system proxy in different ways, so follow the client’s documentation and check the settings currently in effect. The system proxy used by regular desktop apps is also separate from WinHTTP settings. Don’t change WinHTTP just to troubleshoot a browser.

macOS: Check the network service you’re using

On macOS, go to System Settings → Network → your current network service → Details → Proxies. Check whether the web proxy, secure web proxy, or SOCKS proxy still points to an old port. Wi-Fi and Ethernet may have different settings. If a problem starts after switching networks, check the current network service rather than the Wi-Fi service you used before.

Linux: Check desktop and terminal settings separately

Desktop proxy settings on Linux vary by desktop environment and application. Terminal programs usually need explicit proxy options or environment variables, so a browser using the proxy doesn’t mean the terminal is connected too. The commands below test HTTP and SOCKS5 through the same mixed port:

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

socks5h sends the target hostname to the proxy for resolution. A response from the target site means this request completed at least the connection and response steps. Timeouts, proxy authentication errors, and TLS errors need to be diagnosed separately. This test doesn’t prove that all apps are using the proxy or that local DNS settings are correct.

mixed-port: 7890 is common, but not required

mixed-port serves HTTP and SOCKS proxy traffic on the same listening port. It’s a local entry point, not a remote node port or the core’s control API port. Configs commonly use 7890, but clients and configs may use other values. Check the active config and runtime logs.

Find out which process is using a port

If the logs show address already in use or a binding failure, check which process is listening. Another proxy client, a leftover core process, or a development server could be using the same port. Replace 7890 in the commands below with the port from the error:

# Windows: Run in Command Prompt; the last column shows the PID
netstat -ano | findstr :7890

# macOS: Show TCP listening processes
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux: Show TCP listeners and process details
ss -ltnp 'sport = :7890'

Windows output may include connections with a matching remote port. Check the local address column and the LISTENING state. On Linux, you may need elevated permissions to see process names. Once you identify the process, close the conflicting app normally rather than killing a process just because you found its PID.

If you switch to 17890, update your apps too

If you need to work around a conflict, you can change the mixed port to 17890. The example below only shows the fields to check; it isn’t a complete config with nodes and rules:

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

After making the change, reload the config and confirm the new port is listening. Then turn the client’s system proxy off and back on. Update the proxy settings in any browser, terminal, or download app you configured manually. Some GUI clients override subscription port values with their own settings. Change the client settings or a supported override config; otherwise, a subscription update may restore the old value.

TUN and permissions: Get the regular proxy working first

TUN mode uses a virtual network interface and routes to capture traffic from apps that don’t follow system proxy settings. It isn’t a “more advanced, so you must enable it” option. For a first desktop setup, test the node and local port with an explicit proxy request. Enable TUN only if needed, so node issues and routing problems don’t get mixed up.

• Windows: Creating a virtual network adapter and adding routes typically require elevated permissions. The client may handle this through a service. If service installation fails, check the logs. Don’t run every program as an administrator all the time.
• macOS: Changing system proxy settings, using a helper service, or installing a network extension may trigger different permission prompts. Only approve requests from a trusted source that match the action you’re taking. If the client won’t start, check the status of its helper service.
• Linux: Creating a TUN device and changing routes require network privileges, which may be provided through a service or capability settings. Follow the instructions for your client. A working desktop proxy doesn’t mean TUN has the permissions it needs.
• Android: Many clients use Android’s VPN interface to route traffic. Approve the VPN connection request. This differs from the system HTTP proxy setting on desktop, and another VPN app may already be using the system VPN service.
• iOS: Use a client that supports the required config and approve its VPN configuration. Desktop Clash installers won’t work on iOS. Check config format and feature support for your specific client.

If LAN devices, your company intranet, or another VPN stops working after you enable TUN, turn TUN off first and see if things recover. Then check route exclusions and DNS settings. Don’t copy an unfamiliar DNS config wholesale: intranet names, router hostnames, and public domains may need different resolution paths. For more on traffic routing, see the Technical Reference.

Startup: Launching the client, running the core, and restoring the proxy are separate things

“Launch at startup” usually means starting the client after you sign in. It doesn’t necessarily provide a proxy before login, or guarantee that the right config loads, the system proxy is restored, or TUN is enabled. To verify startup, fully quit the client and sign in again or restart the computer. Don’t rely on the setting simply appearing enabled.

1. Enable client startup: Turn on the relevant option in the client’s startup settings, and make sure the program is in the location where you plan to keep it. Don’t run it from a temporary extraction folder, disk image, or install directory you’re about to delete.
2. Check startup apps: In Windows 11, go to Settings → Apps → Startup. On macOS, check System Settings → General → Login Items & Extensions. On Linux, check startup applications or the relevant service for your desktop environment.
3. Check the actual state after startup: Make sure the intended config is still selected, proxy groups have the expected selections, the correct port is listening, and the system proxy or TUN is enabled as configured in the client.
4. Wait for the network before troubleshooting subscription updates: After sign-in, Wi-Fi, captive portal authentication, or a company network may not be ready yet. An automatic update failing at this point doesn’t mean your existing local config is unusable. Check the network, then retry the update manually.

On mobile, check background and battery settings too

Android background restrictions may stop the proxy service after the screen locks. If it works at first but disconnects later, check whether the client still shows as running, the system VPN is still connected, and battery management is restricting background activity. Adjust settings only for apps that need it; there’s no need to disable every battery-saving feature on your device. Automatic connection behavior on iOS depends on the client and system support, so don’t expect it to work exactly like desktop startup.

First-install troubleshooting: From local listening to app traffic

Narrow down the issue one layer at a time, changing only one variable per test. Use this checklist when nodes appear to be working but an app can’t reach the internet:

The client’s connection log can help narrow things down further. If the target request doesn’t appear at all, check how traffic is routed to the client. If it appears but matches DIRECT, check the rules and proxy group. If it reaches the proxy outbound but times out, check node connectivity and the target site. You can temporarily increase the log level for troubleshooting, then restore your usual level to avoid generating excessive logs.