Clash First Install and Initial Setup: Cross-Platform Steps and Common Pitfalls

Before Installing: Tell the Client Apart from the Core

A Clash GUI client and its core are two separate layers. The client handles the interface, subscription management and the system proxy switch; the core parses the config, matches rules and forwards traffic. The original Clash core is no longer maintained, so mainstream clients now ship with the mihomo core (Clash Meta) built in — protocol support, rule types and TUN behaviour all follow mihomo.

Before picking a package, confirm two things: whether the client bundles its own core (if it does, there is no separate core file to download), and whether that core version supports the inbound mode you plan to use. Never run two proxy clients on the same machine — they fight over port 7890 and the system proxy settings, and the classic symptom is a switch that reads as on while traffic still bypasses the proxy.

The universal install order: install → authorize → import subscription → confirm mode

The interfaces differ from platform to platform, but the order is always the same. Follow the five steps below; if any step does not produce the expected result, stop and fix it before moving on.

Windows: service mode decides whether TUN needs elevation

Changing the system proxy only writes to the current user's registry, so normal rights are enough; TUN mode has to create a virtual adapter, which requires administrator rights. Most clients offer a Service Mode switch: install the system service once and later launches no longer need elevation. Skip it and the TUN toggle snaps straight back off, with permission-related errors in the core log.

macOS: get past Gatekeeper, then allow the privileged helper

After dragging the app from the dmg into Applications, the first launch may say it cannot be opened because the developer cannot be verified. Go to System Settings → Privacy & Security, find the blocked entry at the bottom of the page and click Open Anyway. When you enable TUN, the client asks you to install a privileged helper once (some versions use a system network extension instead); enter your password to confirm, then turn the matching item on under System Settings → General → Login Items & Extensions. Otherwise the switch reads as on while traffic still goes out directly.

Android and iOS: the VPN prompt appears once, background survival needs separate setup

Before sideloading the apk on Android, allow the install source under Settings → Apps → Special app access → Install unknown apps. The first time you tap Connect, the system VPN authorization dialog appears — tick the trust box and confirm. Then set the client to Unrestricted in battery settings; otherwise the system kills the process once the screen goes off and the connection drops every few minutes.

After installing from the App Store on iOS, the first connection triggers an Add VPN Configuration confirmation — approve it with your passcode or biometrics. If you decline, no VPN entry is created in Settings, the toggle snaps back immediately, and you should check Settings → General → VPN & Device Management for leftover entries.

Linux: root for the package, capabilities for TUN

For deb use sudo dpkg -i, for rpm use sudo rpm -ivh; for AppImage run chmod +x first. TUN mode needs to create a virtual adapter, and granting the binary network management capabilities is less hassle than launching as root every time:

sudo setcap cap_net_admin+ep /usr/local/bin/mihomo

Note that reinstalling or upgrading the binary wipes the capability, so you have to set it again; if you keep it running under systemd, you can also just specify root in the unit file.

Subscription import and mode confirmation

The import itself is just a short sequence: copy the subscription link → open the client's Subscriptions / Profiles page → create a new entry and paste the link → click Update. Once the config downloads, the nodes appear in the policy groups on the Proxies page.

When people get stuck here, it is usually one of these three cases:

• Truncated link. Subscription links are long and easy to copy short from a chat app. Check the end after pasting, or use the client's Import from Clipboard option instead.
• Update fails with a TLS or certificate error. Check that the system clock is accurate first — a large time offset makes certificate validation fail.
• Update succeeds but no nodes appear. Read the exact error in the core log; the usual cause is that the subscription returns a base64-encoded node list instead of Clash-format YAML.

Confirming the mode matters just as much. Clients usually offer Rule, Global and Direct; keep Rule for a first-time setup so the core matches top-down through the rules section. When you need to check whether a node itself works, switch to Global for one test, then switch back to Rule.

The block below shows the actual fields changed in the client GUI — use it to cross-check the values in effect:

mixed-port: 7890
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true

mixed-port accepts both HTTP and SOCKS5 requests, so a browser proxy extension only needs 127.0.0.1:7890; external-controller is the listen address for dashboards and external control — leave it at 127.0.0.1 and do not change it.

The three most common initial-setup pitfalls

Permissions: the TUN toggle flips back on its own

There are basically three causes — service mode not installed on Windows, the privileged helper or network extension not allowed in macOS System Settings, or CAP_NET_ADMIN missing on Linux. The check is straightforward: look in the core log for operation not permitted or a failed to configure TUN interface error.

Ports: 7890 already in use, or exposed to the LAN

Port 7890 is the one most likely to be taken — browser proxy extensions, older clients and packet capture tools can all hold it. Find the process holding it first:

# Windows
netstat -ano | findstr :7890

# macOS / Linux
lsof -i :7890

Take the PID and kill the process, or point mixed-port at a free port (7891, say) — and update the port in your browser and system proxy settings too, otherwise you end up with a new port while the browser still connects to the old one.

The other risk is exposure: with external-controller set to 0.0.0.0:9090 and no secret, anyone on the same LAN can read your config and switch nodes.

System proxy: no web page loads after the client exits

The system proxy is a setting written into the OS, and a force-killed or crashed client never gets to restore it — the browser keeps sending requests to port 7890 with nothing listening, so every site fails to load. Where to reset it by hand:

• Windows: Settings → Network & Internet → Proxy → turn off Use a proxy server.
• macOS: System Settings → Network → Details for the active network → Proxies → uncheck HTTP, HTTPS and SOCKS.

There is one more hidden conflict: a proxy manager extension in the browser with its own PAC rules enabled overrides the system proxy, so the client shows as connected while the browser bypasses it. Disable those extensions first, then test again.

First-time connectivity self-check: run through it in order

1. Read the core log. Entries showing DNS listening and rules loaded mean startup went fine; if there are error lines, fix those first.
2. Check node latency. Hit the latency test on the Proxies page — numbers mean both the subscription and the network are working; if everything times out, go back and confirm the subscription updated successfully.
3. Confirm the mode is Rule, then watch a live connection on the Connections page to see which rule it matched — you do not want all traffic falling through to the MATCH catch-all.
4. Test the port directly, bypassing the browser:

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

   A 200 status code means the path from the core to the node is fine and the problem lies with the system proxy or the browser.
5. Check DNS. With fake-ip enabled the default range is 198.18.0.1/16; if your LAN or corporate VPN uses the same range, some domains will resolve incorrectly and you need to switch to a non-conflicting range.
6. Finish with one comparison: turn the system proxy off, leave only TUN on, and visit the same site. If both methods work, your first install and initial setup are done.