Clash First-Time Setup: Installation, Configuration, and Common Pitfalls

First-time setup: get your config working before routing traffic

A successful installation only means the client files are on your device—it doesn't mean the proxy is working. Desktop clients typically consist of a graphical interface and a proxy core: the interface manages subscriptions, proxy groups, and toggles, while the core parses the config, listens on ports, and forwards connections. Clash Meta is now maintained under the name mihomo, and supported protocols and fields vary between cores.

Follow these steps in order. Move on only after each step works. If something goes wrong, you'll know where to look instead of changing DNS, ports, and nodes all at once.

1. Check your device's architecture, install the matching client, and note the client version, core name, and core version.
2. Quit other apps that are routing network traffic, then make sure you can access regular websites.
3. Import a subscription or local YAML file, select the config, and check that the core starts.
4. Use Rule mode and select a node in the proxy group that handles the traffic you want to route.
5. On desktop, enable the system proxy. On Android, authorize the client to create a VPN connection.
6. Test browser access and review the connection logs. Configure TUN, background operation, and startup at login only after that.

Installer and permissions: check the requirements for your platform

Windows: don't assume every problem is a permissions issue

After installation, start the client as a standard user. If enabling only the system proxy results in a local port binding error, check for a port conflict instead of repeatedly choosing “Run as administrator.” The system proxy sets the proxy endpoint; it doesn't automatically route every app through it. Some games, command-line tools, and standalone network components bypass this setting.

macOS: distinguish security warnings from a damaged app

If macOS blocks the app, first verify the download source and installer architecture. If the source is trusted, check System Settings → Privacy & Security for an option to allow the app to open. Don't disable system security globally just to launch a client, and don't run Terminal commands from untrusted sources to “fix” it.

Android: handle VPN access and background permissions separately

VPN authorization controls how traffic is routed; battery optimization affects whether the app stays active in the background. If it works in the foreground but disconnects frequently when the screen is locked, go to Settings → Apps → the client → Battery and check background restrictions. Menu names vary by manufacturer. Keep the defaults for your first test, then relax restrictions if needed after confirming the connection is stable.

Importing a subscription or YAML file: check its contents, compatibility, and status

The client doesn't provide working nodes automatically. Subscription links usually come from your service account dashboard and may contain an access token, so treat them like passwords. Don't post the full URL in public forums, screenshots, or shared logs. Redact node credentials from screenshots before sending them, too.

1. Open the client's Config or Subscription page, then choose Import from URL or import a local file. The menu name varies by client.
2. Wait for the download to finish and check that the config appears in the list. If it fails, check the HTTP status, certificate, or network error before changing any rules.
3. Select the newly imported config to make it active. A successful import doesn't mean the config is in use.
4. Check the runtime logs. If you see YAML indentation errors, an unsupported protocol, or missing proxy groups, fix those first—then enable the system proxy.

A “config format error” doesn't always mean the YAML itself is wrong. An expired subscription may return a login page, some URLs may serve a format for another client, and others may provide only a node list instead of a complete config. If the file starts with <html>, check the subscription URL and account status rather than adding a few rules to the file.

If fields are incompatible, check which core is running

Protocols or extension fields supported by mihomo may not work with an older Clash core. Check the client's About page or core information, note the actual version, and consult the documentation for that version. Don't infer core capabilities from the installer filename, and don't delete unfamiliar fields just to make validation pass.

Port conflicts: check the local listener using 7890 as an example

Here's a sample local proxy listener. 7890 is an example port, not a fixed value for every client. mixed-port accepts both HTTP and SOCKS proxy connections. Check the actual port in the interface or effective config, and use that same value in test commands.

# Local listener fields only; not a complete subscription config
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

Don't replace your entire subscription file with this snippet—you'll lose the existing nodes, proxy groups, and rules. For local use, keep LAN access disabled. There's no need to open a router port or disable your system firewall for a local test.

Windows: find the process listening on the port

netstat -ano | findstr :7890
tasklist /FI "PID eq 1234"

The first command checks connection entries containing this port. Look for a line with a local address ending in :7890 and a state of LISTENING; the last column is the PID. In the second command, 1234 is an example—replace it with the actual PID. Identify the process, then quit it normally. Don't terminate system processes blindly.

macOS and Linux: check the same port

# macOS; also works on Linux after installing lsof
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux
ss -ltnp 'sport = :7890'

You may need extra permissions to view details for processes owned by other users. If an old client is still running in the background, quit that instance before restarting the current core. If you need to change the port—for example, to 7892—update manual proxy settings, browser extensions, and terminal environment variables as well. Changing only the config file leaves apps pointing to the old port.

Proxy modes and TUN: verify the rule-based route first

Start with Rule mode. It routes connections according to the order of rules in the config, sending them to a direct connection, rejecting them, or assigning them to a proxy group. Global mode sends traffic to the global proxy selection; it doesn't automatically pick a working node. Direct mode doesn't disconnect the client—it changes how traffic is handled.

Open the proxy groups and check the current selection. For example, if the final rule points to a group named Proxy, make sure that group resolves to a working node. Don't rely on the latency of a different test group. A latency value only shows that a specific test target was reachable at that moment; it doesn't guarantee access to every site, protocol, or regional service.

• Desktop browser test: Enable the system proxy, temporarily disable browser extensions that set their own proxy, and visit a site that requires proxy access.
• Terminal test: Specify the proxy explicitly so a terminal that ignores the system proxy isn't mistaken for a client failure.
• Connection logs: Check the destination domain, matched rule, proxy group, and final node in the client to confirm the request followed the expected route.

# Windows PowerShell; call curl.exe explicitly
curl.exe -I --proxy http://127.0.0.1:7890 https://example.com/

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

This command tests a single HTTP request to the specified destination. A response from the site means the request completed; if the connection is refused, check the listening port first. For long timeouts, review the node and destination alongside the logs. A reachable example URL doesn't guarantee other sites will work, so test the services you actually need.

Enable TUN only after everything else works

TUN routes traffic through a virtual network interface when that traffic is routed to it, making it useful for apps that ignore the system proxy. Actual coverage also depends on routes, exclusions, and DNS settings, so don't assume it captures all traffic. On Windows, macOS, and Linux, TUN usually requires a service, driver, or system network permissions. Android VPN access is managed through system authorization.

Enable TUN only after the basic connection works and you have a specific need to route additional apps. If intranet domains, a corporate VPN, or LAN devices stop working, turn TUN off and compare, then check routes and DNS one at a time. Don't change DNS, enable Fake-IP, and modify multiple routing options all at once. See the YAML guide to DNS settings and the Fake-IP guide for details.

Startup and reboot checks: verify the interface, core, and proxy status

Launching the interface at startup, starting the proxy core, and enabling the system proxy automatically are usually three separate settings. Once manual startup is stable, enable the relevant options in the client. On Windows, check Settings → Apps → Startup. On macOS, check System Settings → General → Login Items & Extensions. Menu names vary by OS version.

Android startup and background restrictions depend on the client and system. If you need a persistent connection, first check that it still works with the screen locked, then decide whether to adjust battery restrictions. “Always-on VPN” and “Block connections without VPN” are separate system options. The latter blocks network access when the VPN is unavailable, so understand the impact before enabling it.

Check each setting after the first reboot

1. Make sure the client and core are running and the expected subscription is still active.
2. Confirm the listening port hasn't changed and that Rule mode and the proxy group selection are still correct.
3. On desktop, check that the system proxy or TUN has resumed as expected. On Android, check the VPN connection status.
4. Test regular websites, the services you need, and LAN resources separately. Don't rely on the tray icon alone.
5. Exit the client normally and confirm the desktop system proxy is off. If you lose internet access afterward, check for leftover proxy settings.

On Windows, go to Settings → Network & Internet → Proxy and check whether it's still set to a local port. On macOS, go to System Settings → Network → your current connection → Details → Proxies. Note the original settings before changing them. On managed devices in particular, don't overwrite your organization's proxy settings.

After completing these checks, add routing rules or adjust DNS. For subscription issues, see subscription FAQs. To learn how the modes differ, see the proxy mode guide. Change one setting at a time and keep a working config you can restore.