Clash First-Run Setup Guide: System Proxy, Ports, TUN Mode & Common Errors

Before You Install: Check Your System Architecture, Client & Core

The goal of your first setup is to establish a connection path you can verify: an app sends a request, the local proxy port receives it, the core selects a direct or proxied route based on its rules, and the proxy connection reaches the destination. Opening the installer only confirms that the interface launched. A downloaded subscription, a running core, and an app using the proxy are three separate things to verify.

Choose the right build, then check core compatibility

• Windows: Go to Settings → System → About and check your device specifications. Most Intel and AMD PCs use an x64 build; on Windows on ARM, choose the client’s ARM64 build if available.
• macOS: Open the Apple menu → About This Mac to check your chip. Use the arm64 build for Apple silicon and the x64 build for Intel Macs. If a Universal build is available, follow the release notes.
• Linux: Run uname -m. The output x86_64 usually corresponds to amd64/x64, while aarch64 corresponds to arm64. Also check the package format and supported distributions.
• Android: Choose the APK architecture specified in the client’s release notes. The app’s VPN service routes device traffic; it is not the same as manually configuring an HTTP proxy in a desktop operating system.
• iOS: Connect through a client that supports the relevant configuration format. Don’t assume every iOS client can import a full desktop Clash YAML file; check the subscription format before importing it.

The Clash client handles subscription management, controls, and status display. The Clash or Clash Meta (mihomo) core parses the configuration and routes traffic. Support for newer protocols and configuration fields depends on the core actually running and its version. If an import reports an unsupported proxy type, check the client’s About or core information page and verify the configuration requirements before changing the system proxy repeatedly.

Importing a subscription: download it, then enable the configuration

A subscription link is usually a URL containing access credentials. It may return a complete YAML configuration or just a list of nodes. A full configuration typically includes proxies or proxy-providers, proxy-groups, and rules. A node-only list needs a client template to add proxy groups and rules. These formats aren’t interchangeable in every import workflow.

1. Open the client’s Profiles or Subscriptions page, choose the URL import option, and paste the complete link from your provider. Labels vary by client, so use the configuration management page in your current version.
2. Download or update the subscription, then check the last-updated time and any error messages. For HTTP 401 or 403 errors, check the link credentials, account status, and provider access restrictions. For a 404, first make sure the URL hasn’t expired and was copied in full.
3. Select the imported configuration and confirm it’s enabled, then open the proxy groups page. A completed download doesn’t mean the core has switched to that configuration.
4. Choose an available node in a select group that’s actually referenced by your rules. A URL-test group may choose a member automatically; a manual selection group requires you to pick one. Make sure it hasn’t been left on DIRECT.
5. Check the core logs for configuration parsing errors. YAML indentation uses spaces; don’t use tabs, and don’t assume a file is valid just because an editor can open it.

Keep subscription updates separate from local changes

Edits made directly to a downloaded subscription file may be overwritten the next time it updates. For fixed ports, DNS, or rule changes, use the client’s supported override, merge, or extension features where possible. Keep a note of what you changed and where, then check the effective configuration after updates. When sharing an error, redact subscription URLs, node passwords, and controller secrets; include only the fields and error lines needed to diagnose the issue.

System proxy and mixed port: match the address and port

A desktop system proxy directs apps that honor the system proxy settings to a local proxy port. It won’t automatically route traffic from every app through Clash. For an initial test, start with the system proxy and confirm that browser requests reach the core. Then configure games, command-line tools, and other apps that ignore system proxy settings.

Example local proxy address: 127.0.0.1:7890

These basic fields are for reference only; they aren’t a complete configuration that can connect to a node. mixed-port accepts both HTTP proxy and SOCKS5 connections. 7890 is an example—the effective value is the one in the client’s active configuration. Some clients override the file’s port with their GUI settings.

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

Where to check system proxy settings

• Windows 11: Go to Settings → Network & internet → Proxy → Manual proxy setup. If the client manages the system proxy, turn on its proxy switch and check that the address and port here match the local listener. Don’t leave an unknown script configuration enabled at the same time.
• macOS: Go to System Settings → Network → your current network service → Details → Proxies. Check the address and port for the web proxy, secure web proxy, or SOCKS proxy. After quitting the client, confirm that the settings have been restored.
• Linux: Desktop network proxy settings and terminal environment variables work independently. After setting a desktop proxy, command-line tools may still need explicit options or environment variables such as HTTP_PROXY and HTTPS_PROXY. Check each tool’s documentation.

Test the connection: separate port, rule, and node issues

Change only one thing at a time while testing. First confirm the port is reachable, then check which rule matches, and finally troubleshoot the remote node. A client’s node latency test usually measures the time to reach a specific test address—not download speed—and doesn’t guarantee access to every site.

Use an explicit proxy request to rule out system settings

In Windows PowerShell, use curl.exe to avoid environments where curl is interpreted as a different command. On macOS and Linux, use curl. The command below requests a test webpage through the example port and waits up to 15 seconds. Replace it with the port your client is actually listening on.

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

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

• Can’t connect to the local port: Check whether the core is running, whether the port matches, and whether the logs show a listener error. The request hasn’t reached the proxy layer, so switching remote nodes usually won’t help.
• Received an HTTP response header: This confirms that the request reached the proxy entry point and completed the destination request. In rule mode, however, the destination may still have been routed directly. Check the connection log to confirm the outbound route.
• Request timed out: Check whether the domain appears in the connection log, which rule matched, and which node was selected. If there’s no log entry, troubleshoot how the app connects to the proxy. If there is one, check DNS, node connectivity, and the destination service.

Use rule mode as your everyday starting point

mode: rule matches connections against the configured rules in order, usually with MATCH as the final catch-all. Global mode can help briefly test whether a rule assigns a destination to the wrong policy, but it won’t fix a broken node or an invalid subscription format. Switch back to rule mode after testing, then check the rule name, policy group, and final node in the connection log. A webpage loading doesn’t by itself prove that traffic went through a proxy.

TUN mode: check permissions, routes, and DNS in order

TUN mode uses a virtual network interface and routing to capture traffic, making it useful for apps that ignore system proxy settings. It’s a different way to connect traffic, not a guarantee that every connection goes through a remote node. Once traffic reaches the core, rules still decide whether to use DIRECT, a proxy group, or another action.

Test the regular proxy before enabling TUN

1. First confirm that explicit proxy requests work and the node is reachable. If the regular proxy path isn’t working, fix the subscription, port, or node before adding TUN as another variable.
2. Check whether the client provides a service mode or permission setup option. A Windows client may require an installed background service or administrator permissions; macOS may require approval for a helper component; Linux often requires elevated permissions or network management capabilities.
3. After enabling TUN, check the virtual interface, routes, and core logs. If you see a permissions error, follow the client’s installation documentation to authorize its service. Avoid running unrelated programs with elevated privileges long-term.
4. Temporarily disable traffic routing in other VPNs, then test websites, the target app, and local network resources. Two VPNs changing the default route or DNS at the same time can send requests through the wrong interface.

In a mihomo configuration, tun.enable controls TUN, auto-route relates to automatic routing, and dns-hijack can capture specified DNS traffic. Support depends on the platform, core version, and client overrides. Don’t assume that pasting in a TUN configuration is enough to configure routes, DNS, and permissions.

Troubleshoot DNS separately from rule-based routing

If domain lookups fail while other connections still respond, start by checking DNS logs and the current resolver settings. A browser’s secure DNS, an app’s built-in resolver, and system DNS may take different paths. Capturing regular DNS requests doesn’t mean all encrypted DNS is captured. In fake-ip mode, an app may receive an address from a virtual IP pool; this is how the core maps domains, and you shouldn’t add that address to your hosts file.

If printers, NAS devices, or company intranet resources are unreachable, check LAN direct rules, route exclusions, and internal DNS instead of switching everything to global proxy mode. On Android, the VPN permission prompt allows the app to create a VPN interface. Typically, only one VPN service can run per user profile, so enabling another VPN app may replace or disconnect the current one.

Common startup errors: troubleshoot by layer

The operating system blocks the installation

If Windows shows a SmartScreen or security software warning, first verify the download source, publisher information, and that the installer supports your system. Managed devices may have application execution policies; ask your administrator about approval. If macOS shows a developer verification warning, verify the source, then check System Settings → Privacy & Security for an option to allow the app. If the system says the app will damage your computer or that the file is corrupted, stop and recheck the source and release notes—don’t treat every warning as the same issue.

address already in use: local port is occupied

This error means the core can’t bind to an address or port. First quit any duplicate client instances, then check which process is using the port. On Windows, run the command below to check what’s listening on 7890, then match the PID to a process in Task Manager’s Details tab. Don’t terminate an unknown system process just because it’s using the port.

netstat -ano | findstr ":7890"

On macOS, use lsof -nP -iTCP:7890 -sTCP:LISTEN; on Linux, use ss -lntp to check listening sockets. If you switch to another port, update the system proxy too. A controller port conflict and a traffic listener conflict are separate issues and should be handled separately.

Certificate errors: check the clock, domain, and trust chain first

Standard HTTP CONNECT or SOCKS5 forwarding usually doesn’t require installing a root certificate in your browser. For an “expired certificate,” “certificate name mismatch,” or TLS handshake error, first check the system date and time zone, the domain you’re visiting, and the certificate issuer. Then check whether you’re on a network that requires sign-in through a web page. Corporate networks may use managed TLS inspection; follow your organization’s certificate deployment process.

Internet access still fails after quitting the client

First turn off the system proxy and confirm that any manually configured proxy address has been cleared. Then check for leftover TUN routes, VPN services, or traffic routing from another client. Clients usually try to restore these settings on exit, but a crash may leave them in place. If you’re managing the computer remotely, prepare a backup connection before changing the default route so you don’t disconnect your own session.

Initial setup checklist

After confirming a working connection, enable everyday features such as launch at startup and automatic subscription updates. Keep a record of key settings so you can quickly tell configuration changes from network issues after an update or when switching networks.

• The subscription shows a recent successful update, the intended configuration is selected, and the logs show no parsing errors that prevent the core from starting.
• Record the client name, core version, and actual mixed-port. Make sure the system proxy address and port match.
• An explicit proxy request receives a response, and the connection log shows which rule matched, which policy group was used, and the final outbound route.
• Test apps that need TUN separately, and confirm that local network devices and intranet services remain accessible as expected.
• After quitting the client, regular internet access works again. After restarting, the proxy switch and service status are as expected.
• After updating the subscription, check the override configuration. Store credentials securely in backups, and never post a full subscription link on a public support forum.

Continue troubleshooting in this order: configuration validity → core listening status → app proxy connection → rule match → node reachability. See the glossary for terminology, and the technical reference for rule and core configuration details.