Complete Clash Setup Guide for All Platforms

1. General preparation before installation

Know the difference between the client, core, and configuration file

Using Clash involves three parts. The graphical client displays configuration, switches policies, controls the system proxy, and manages updates; the core parses rules, establishes connections, and handles DNS and TUN traffic; the configuration file stores proxy endpoints, proxy groups, routing rules, ports, and DNS parameters. Most desktop and mobile clients bundle a compatible core, so typical users do not need to download Mihomo separately. Deploy the core directly only for servers, routers, containers, or environments where you need to manage the service process yourself.

A subscription URL is not generated automatically by the client either. It is usually provided by a network service provider, while the client only reads the URL and converts it into a local configuration. Public code repositories, official client websites, and this site's download page do not provide ready-to-use proxy subscriptions. Treat a subscription address as sensitive information: do not include it in screenshots, public support tickets, shared command histories, or publicly accessible code repositories. If you only have a YAML file, import it as a local configuration instead of converting it into a subscription URL first.

Choose a client that matches your device

For a first installation, start with a graphical client. On Windows, macOS, Android, and iOS, check Clash Plus first. Windows and macOS users can also choose Clash Verge Rev, FlClash, or Clash Nyanpasu based on interface preferences; Android users can choose Clash Meta for Android, FlClash, or Surfboard; Linux desktop users can choose Clash Verge Rev or FlClash. Clash for Windows and ClashX Meta are no longer maintained and are suitable only for legacy environments, not as starting points for new installations. All available options are listed on the client downloads page. Do not judge whether a current package is suitable solely by comparing its filename with an old tutorial.

Confirm the processor architecture before downloading. Most Windows devices use x64; Windows on ARM devices require a client build that explicitly supports the platform. Apple Silicon Macs use arm64, while older Intel Macs use x64. Android packages commonly come in arm64, arm, and universal builds. Most recent phones use arm64, but do not infer this from the brand alone. Linux requires checking both CPU architecture and package format: Debian and Ubuntu commonly use deb, Fedora-based distributions commonly use rpm, while archive packages require you to configure executable permissions and service management yourself.

Gather the information needed for installation

Before you begin, prepare a subscription URL or YAML file, device administrator permissions, a working network connection, and a browser for verifying the result. Company or school devices may have proxy, VPN, network extension, or certificate settings locked by management policies. In that case, a successful installation may still not be able to change the system network state. Do not repeatedly enable several similar clients. When two programs listen on the same port, write system proxy settings, or create TUN interfaces at the same time, startup failures, network loops, and broken connectivity after exit are common.

Default configurations often use mixed-port as a unified HTTP and SOCKS entry point. The port is defined by the configuration; 7890 is a common example, but the value shown in the client interface is authoritative. When entering a proxy manually in a browser or terminal, the host is usually the local loopback address 127.0.0.1, while the port must match the active configuration. Do not enter a subscription service's remote port as the system proxy, and do not use a LAN address as the default listening address unless other devices genuinely need to connect.

Understand Rule, Global, and Direct modes

Rule mode matches domains, IPs, processes, or rule sets from the configuration's rules in order and sends each connection to the designated proxy group. It is the default choice for everyday use. Global mode ignores routing rules and sends proxyable traffic to the global policy, making it useful for briefly checking whether rules are misclassifying traffic, but not for permanent use. Direct mode bypasses the proxy and is mainly useful for restoring basic connectivity or confirming whether the client is the source of a problem. Switching modes does not repair an invalid subscription or automatically replace an unavailable choice in a proxy group.

After importing a configuration, inspect the proxy groups first. Common group names include Proxy, Auto, Streaming, Final, and REJECT. A manual group requires selecting an available policy; an automatic test group updates its choice according to the configured test method; Final generally handles connections not matched by earlier rules; REJECT denies matching traffic. Names vary between subscriptions, so identify groups by their type and purpose rather than searching mechanically for fixed labels.

2. Windows download, installation, and system proxy setup

Download and install a graphical client

For a new Windows installation, choose Clash Plus from the Windows clients section. You can also use Clash Verge Rev, FlClash, or Clash Nyanpasu. Clash for Windows is no longer maintained and should be used only when legacy configuration compatibility or historical data migration is required. After downloading, run the installer. If User Account Control appears, verify the file source and the action you are about to authorize before proceeding. Prefer a normal local drive for the installation directory; avoid temporary folders, synced drives, and folders restricted by enterprise policies.

Some clients offer per-user and all-users installation. The former usually does not require persistent administrator privileges; the latter makes program files available to multiple accounts, while configuration data may still remain in separate user directories. If you plan to enable TUN, install a service, or configure startup, the client may request administrator privileges during the first operation. Traditional system proxy settings generally do not require always running as administrator. Forcing elevated execution over the long term can create extra problems with drag-and-drop, browser integration, and access to normal user directories, so it should not be treated as a universal fix.

Import a subscription and confirm that the configuration is active

Open the configuration or Profiles page and choose import from URL. Paste the complete subscription address into the field and start the download. A successful import does not mean the configuration is active: select the newly imported entry in the profile list so it becomes the current configuration. For a local YAML file, use the local file import option or place it in a configuration directory allowed by the client. Direct edits to the client's internal cache may be overwritten during subscription updates; use the client's override, merge, or scripting features for custom rules that must persist.

After activating the configuration, check the proxy mode, proxy groups, and port in that order. Rule mode is suitable for everyday use. Open a manual group such as Proxy and select a policy that actually exists in the subscription; if the configuration includes an Auto or url-test group, trigger an update once first. Do not treat a green status indicator as the only evidence of success; verify a real connection afterward. If the list is empty after downloading a configuration, the usual causes are the subscription response format, authorization status, or network access—not the system proxy switch.

When to use the system proxy and TUN

The Windows system proxy writes the local proxy address into system settings. Browsers and desktop applications that follow WinINET or system proxy settings use it automatically, but some games, command-line tools, Store apps, and software with its own networking stack may ignore it. After enabling it, you can see the local address and port in Windows proxy settings. The client usually restores the settings on normal exit; if it is force-terminated or Windows shuts down unexpectedly, a proxy entry pointing to a stopped port may remain, making every webpage appear inaccessible.

TUN mode uses a virtual network interface to intercept a broader range of IP traffic, making it suitable for applications that do not read system proxy settings. First-time activation may install a driver or system service and request administrator approval. After enabling it, check the routing table, DNS, and firewall, and do not run other software that creates a TUN or global VPN interface at the same time. Whether the system proxy and TUN can be enabled together depends on the client. For initial troubleshooting, keep only one interception method active, confirm stability, and then decide whether to combine them.

Command line, terminals, and developer tools

PowerShell, Command Prompt, Git, package managers, and language runtimes do not always read the Windows system proxy. When necessary, set environment variables for the current terminal session, replacing the port with the client's current mixed-port. Temporary variables affect only that terminal and its child processes and disappear when the window closes, making them suitable for testing. Before writing them to user-level environment variables, confirm they will not send offline development, LAN services, or container tools through the wrong path.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7890"

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

If you later disable the client, also remove persistent Git proxy settings; otherwise Git will continue trying to connect to the closed local port. Use git config --global --unset http.proxy and the corresponding HTTPS command to clear them. If the terminal works but the browser does not, check the system proxy, browser extensions, and security software first. If the browser works but the terminal does not, focus on environment variables, Git configuration, and the tool's own proxy fields.

Windows-specific failure cases

Port conflicts are a common cause of startup failures on Windows. If the client log says the address is already in use, first check for another Clash instance or a leftover process, then decide whether to stop it or change mixed-port. See the port conflict troubleshooting steps for a complete method. After changing the port, update the system proxy, browser manual proxy, terminal environment variables, and LAN devices as well.

If connectivity breaks after exit, first disable the Windows manual proxy, then check for leftover virtual adapters, proxy environment variables, or other VPNs. Do not immediately reset all network components, as that may also remove virtual switches, static DNS settings, and development-environment configuration. Confirm that the client process has ended, then restore settings layer by layer: system proxy, DNS, default route, and TUN service. If the problem occurs only after waking from sleep, restart the client core and rebuild TUN first; repeated reinstalls usually do not fix routing competition or security-policy issues.

3. macOS installation, network extensions, and proxy switching

Choose the installer for your processor architecture

Before downloading on macOS, open About This Mac and confirm the chip type. Apple Silicon uses arm64 builds, while Intel processors use x64 builds. For a new installation, choose Clash Plus from the macOS clients section, or use Clash Verge Rev or FlClash. ClashX Meta is no longer maintained and is mainly for migrating legacy environments. Choosing the wrong architecture can prevent startup, force use of a translation layer, or make auxiliary service installation fail. Do not judge compatibility solely by whether the filename contains macOS.

A common installation method is to open the disk image, drag the app into the Applications folder, and launch it from there the first time. Do not run it long-term from Downloads or directly from a mounted disk image, as automatic updates, login startup, and auxiliary service paths may become unreliable. If macOS blocks the app, verify its download source first, then check the related message under Privacy & Security. Do not lower global system security to solve authorization for a single app.

Import configuration and use the menu bar

Open Profiles or the configuration page to import a subscription by URL, or import a local YAML file. After downloading, explicitly select the configuration, then open the proxy page and choose Proxy, Auto, or another group defined by the configuration. macOS clients commonly stay in the menu bar; closing the main window does not necessarily stop the core. When troubleshooting port conflicts or leftover proxy settings, quit from the menu bar or confirm in Activity Monitor whether related processes are still running.

A subscription update fetches the remote content again. If the client supports automatic update intervals, set one that matches the provider's update method rather than polling too frequently. When remote configuration and local edits coexist, the next update may overwrite direct changes. Use an override configuration when adding routing rules, DNS settings, or scripts. Before exporting a configuration containing complete proxy information, verify the destination and its access permissions.

How the system proxy works

When the system proxy is enabled, the client changes the Web Proxy and Secure Web Proxy settings for the current network service. Safari and apps that follow system configuration usually apply the change immediately, but some command-line tools, sandboxed apps, and software that manages its own connections do not read these settings. After switching between Wi-Fi, Ethernet, a hotspot, or a newly added network service, confirm the proxy state again because macOS proxy settings are tied to a specific network service.

Use scutil --proxy to view the proxy information currently read by the system. This command only shows whether the settings were written; it does not prove that the local port accepts connections or that a proxy group has an available choice. If the proxy address remains after the client exits, reopen the client and close it normally so it can restore the settings, or disable the relevant proxy entries manually in Network settings. Do not let browser extensions, automatic proxy configuration files, and the client's system proxy overwrite one another.

scutil --proxy
networksetup -listallnetworkservices
lsof -nP -iTCP:7890 -sTCP:LISTEN

TUN, system extensions, and permissions

macOS TUN mode usually requires an auxiliary service, a virtual interface, or network extension permission. On first activation, macOS may request administrator credentials and confirmation under Privacy & Security. After granting permission, return to the client and confirm that the core actually started. If the toggle turns on briefly and then switches off, inspect the log for permission, routing, DNS, or interface-creation errors instead of repeatedly clicking it.

TUN can cover applications that ignore the system proxy, but it is also more likely to conflict with other VPNs, enterprise security clients, virtual machine networks, and container networks. During troubleshooting, quit other programs that create a default route or DNS proxy and keep only one traffic interception tool active. If a LAN printer, NAS, or development server becomes unreachable, check private-address direct rules and bypass routes instead of switching all traffic to Direct.

Terminal proxies and certificate boundaries

Terminal, Homebrew, Git, curl, and language package managers may require separate proxy settings. You can export HTTP, HTTPS, and ALL_PROXY in the current shell. If you use zsh and write the variables to a shell configuration file, also prepare a way to unset them. Persistent proxy variables can make the terminal show connection refused when the client is not running and may also affect local development servers.

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890

curl -I https://example.com

unset http_proxy https_proxy all_proxy

A standard Clash proxy does not require a custom root certificate for basic connectivity. Certificates are relevant only when you explicitly use HTTPS decryption, script debugging, or a particular toolchain. When TLS errors occur, check the system clock, DNS resolution, proxy policy, and the application's own certificate store first. Do not disable certificate verification as a long-term solution. Certificates and network extensions on company-managed devices may be controlled by management policies and should be handled by the device administrator.

4. Android installation, VPN permissions, and background operation

Choose a package and complete installation

On Android, choose Clash Plus from the Android clients section, or use Clash Meta for Android, FlClash, or Surfboard. Packages may be available for arm64, arm, and universal architectures. Most recent devices use arm64, but older devices, TV boxes, and emulators may differ. If you are unsure, use the universal build provided by the client. If Android reports a package parsing error, also check the architecture, OS version, download completeness, and whether the device allows installation from that source.

When installing through a browser or file manager, Android requires permission for the current source to install apps. You can revoke that permission after installation without affecting the client's operation. If the same package name is already installed with a different signature, Android may reject the upgrade. Export any configuration you need to keep, uninstall the old app, and reinstall it. Do not assume app data will always be restored after uninstalling, especially local overrides, scripts, and manually imported YAML files.

Import a subscription and create a local VPN

After opening the client, add the subscription URL on the configuration page, enter a recognizable name, and update it. When the update finishes, select the configuration as current, then choose a policy in the proxy group. On the first connection, Android displays a VPN connection request. This grants the app permission to create a local VPN interface. After approval, a VPN indicator usually appears in the status bar. The indicator only confirms that the interface exists; verify successful forwarding through a browser or the client log.

Android generally allows only one conventional VPN service to be active at a time. If another VPN, a managed work profile network, or an ad-blocking tool is already connected, the new connection may replace it or be rejected. Private DNS and Clash's internal DNS can also create separate resolution paths. If domains fail while direct IP access works, temporarily check Private DNS and review the configuration's nameserver, fallback, and fake-ip behavior.

Per-app routing and bypass settings

Mobile clients often let you choose which apps use the proxy, bypass it, or are proxied exclusively. This is useful for keeping banking, LAN control, casting, or VPN-sensitive apps on Direct, and for intercepting only browsers and communication tools. After changing the app list, rebuild the VPN interface to ensure the rules take effect. System apps may consist of multiple packages, so a desktop icon name alone may not cover every related process.

Rule mode still determines where a connection goes according to the configuration rules, while per-app routing decides at an earlier layer whether an app enters Clash at all. Do not confuse the two. When an app is set to bypass, its traffic never reaches domain rules, even if those rules explicitly specify a proxy. When troubleshooting one app, check the per-app routing list first, then rule matches and proxy groups, and finally whether the app uses QUIC, custom DNS, or certificate pinning.

Background restrictions and reclaimed connections

Android manufacturers often impose additional restrictions on background activity, battery use, and auto-start. Symptoms include lost connectivity after the screen has been locked, the VPN disappearing after recent tasks are cleared, or failure to recover after switching mobile networks. In system settings, allow the client to run in the background, disable aggressive battery optimization using the options provided by the device, and allow auto-start where necessary. Menu names vary by manufacturer, but the goal is to prevent the system from freezing the client process or restricting its VPN service.

Always-on VPN can let Android try to reconnect after network changes, but do not enable “Block connections without VPN” until the configuration has been proven stable. If the subscription expires, the client crashes, or the core fails to start, this option may leave the device completely offline. Test Wi-Fi, mobile data, sleep and wake, and reboot behavior first, then decide whether to enable strict mode. To restore connectivity temporarily, disconnect from the system VPN page rather than merely closing the client interface.

Hotspots, LAN, and IPv6

Whether devices connected to a phone's hotspot pass through Clash depends on the OS version, client capabilities, and forwarding implementation. A standard Android VPN generally covers only traffic from apps on the phone itself; do not assume that downstream hotspot devices are intercepted. If sharing is required, confirm that the client explicitly supports hotspot forwarding or LAN connections, then manually configure the phone's LAN address and proxy port on downstream devices. The app must also be allowed to listen on the LAN, and access risks on public networks should be considered.

Some mobile networks prefer IPv6. If the configuration provides only IPv4 DNS or the rules cover only IPv4, apps may behave inconsistently. Do not disable system IPv6 as a permanent workaround. Check the core's IPv6 setting, DNS responses, rule matches, and whether the proxy endpoint supports the connection. If logs show attempts stuck on an unreachable IPv6 address, adjust the configuration temporarily for diagnosis, then decide whether to enable dual-stack support based on the network environment.

Logs on Android are important for identifying the failure layer. Configuration parsing errors usually appear before the core starts; DNS errors show resolution failures or timeouts; policy issues show connection failures after a rule match; an excluded app may generate no corresponding request at all. Checking these four layers is more effective than repeatedly changing clients.

5. iOS installation, configuration import, and on-demand connections

Install Clash Plus from the App Store

On iPhone and iPad, open the Clash Plus App Store page from the iOS downloads section. The client's official website is clashplus.io. On first launch, iOS may ask to add a VPN configuration. This permission creates a Network Extension; it does not mean every connection is already proxied. After granting it, import a configuration, choose a policy, and start the connection.

Network interception on iOS is managed by a system extension rather than a desktop-style system proxy switch. A VPN indicator in the status bar or Control Center means the extension is connected. The extension may continue running after the app's main interface is closed; if you disconnect it from Settings, the in-app status should update as well. During troubleshooting, check both the app and the VPN status in Settings instead of relying on either interface alone.

Import subscriptions and local configurations

Add the subscription URL on the configuration page, update it, and select the resulting configuration. If you copied the URL from another app, check for extra spaces, line breaks, or truncation by a chat app at either end. To import YAML through the Files app, use the system share sheet to send it to Clash Plus, then confirm the result in the configuration list. If the file references external rule sets, those resources must also be downloaded on first load; successful import of the main YAML does not mean every rule resource is ready.

The proxy group selection logic is the same as on other platforms. Rule mode routes traffic by rules, manual groups require an actual policy, and automatic groups update according to their configured test method. Mobile network conditions change frequently, so a policy that works on Wi-Fi may not connect over cellular data. When only one network fails, keep the configuration unchanged and compare Wi-Fi and cellular logs rather than changing DNS, mode, and policy at the same time.

On-demand connections and network switching

On-demand connections can start the extension automatically according to the system's network state and are best suited to configurations that have already been verified as stable. Before enabling them, complete one full manual connection and test Wi-Fi, cellular data, and lock-screen recovery separately. Poorly configured on-demand rules may intercept traffic even on trusted LANs, affecting printers, casting, and home devices. If LAN access matters, keep private-address Direct rules and verify that local network permission is granted.

iOS may rebuild the network extension during network changes, low-battery conditions, or resource pressure. After a brief disconnection, wait for the extension to renegotiate before checking the app log. If it repeatedly remains stuck connecting, disconnect the VPN in Settings and restart it from the client. Avoid keeping multiple VPN configurations enabled on demand at the same time, as system selection behavior becomes difficult to predict.

DNS, QUIC, and application differences

Safari, native apps, and third-party browsers may use different connection strategies. Some apps prefer HTTP/3 or custom resolution, which can make the browser work while a specific app times out. DNS mode, rules, and UDP support in the configuration all affect the result. If disabling UDP makes an app work again, the issue may be in the UDP forwarding or QUIC path. This is a diagnostic clue, not a reason to permanently disable all UDP.

fake-ip mode returns a reserved address for a domain, then the core restores the domain and matches the rules. It usually improves routing consistency, but LAN discovery, some device-control apps, and special domains may need to be added to a filter list. redir-host is closer to real DNS responses and follows a different compatibility approach. Neither mode is universally correct; choose based on the configuration rules, LAN requirements, and logs. For a complete check of leaks and nameserver settings, see the DNS testing and configuration guide.

Battery use, background operation, and configuration maintenance

A network extension that continuously handles connections uses some battery, and actual usage is affected by rule count, DNS queries, log level, and network quality. Do not leave debug logging enabled permanently; use detailed logs briefly to reproduce an issue, then return to the normal level. If battery consumption suddenly increases, check for connection retries, DNS loops, or multiple automatic test groups running frequently instead of looking only at how long the VPN icon has been present.

Before updating a subscription, record the current proxy group selections. Some updates rebuild groups, and an old selection may return to the default when names change. If access suddenly fails after an update, check in order whether the configuration is active, whether the proxy groups still have selections, whether rule resources finished downloading, and whether the extension was re-established. Deleting and reinstalling the app also removes local overrides and historical logs, so do it only after backing up the configuration and completing basic troubleshooting.

Unlike desktop systems, iOS does not provide direct access to a complete routing table or listening-process list, so troubleshooting relies more on client logs and controlled comparisons. Change one condition at a time: switch the policy first, then the mode, then check DNS. If you rebuild the configuration and switch networks in the same step, even a successful recovery will not reveal the actual cause.

6. Linux desktop clients and core service deployment

Installation choices for desktop environments

On Linux desktop, choose Clash Verge Rev or FlClash from the Linux downloads section. Before installing, confirm the distribution, CPU architecture, and package format. Debian, Ubuntu, and derivatives generally use deb; Fedora and RHEL-based distributions commonly use rpm. Installing a local package through the package manager lets the system check dependencies at the same time. Extracting an executable archive requires you to handle the desktop entry, permissions, autostart, and updates yourself.

Desktop environments do not handle system proxies uniformly. GNOME, KDE, and lightweight desktops write proxy settings in different places; some apps read environment variables, some read desktop configuration, and some ignore both. Therefore, after a graphical client reports that the system proxy is enabled, verify the browser, terminal, and target app separately. Wayland or X11 usually does not determine proxy support directly, but it can affect tray icons, authorization dialogs, and desktop integration.

Import a configuration and verify the listening port

The graphical client's subscription workflow is the same as on other desktop platforms: add the URL, update it, select the configuration, choose a proxy group, and then enable the system proxy or TUN. When using the core, save the configuration in a permission-controlled directory and specify its path when starting from the command line. Run a configuration test before startup to avoid repeated service restarts. Parameters vary between Mihomo builds, so follow the current program's help output; common startup options are shown below.

mihomo -t -f /etc/mihomo/config.yaml
mihomo -d /etc/mihomo

ss -lntp | grep 7890
journalctl -u mihomo --no-pager -n 100

-t checks whether the configuration can be parsed, -f specifies a single configuration file, and -d specifies the working directory. The working directory may contain caches, rule sets, and databases, so the runtime user must have the required read and write permissions. Do not make the entire directory writable by everyone just to eliminate a permission error. Run the service under a dedicated low-privilege account, granting additional capabilities only when needed to create TUN interfaces, modify routes, or bind restricted resources.

systemd services and autostart

Servers and desktop hosts that run continuously can use systemd to manage the core. Start the service after the base network is available and retry after unexpected exits at a reasonable interval. Run a syntax check before reloading or restarting after a configuration update. The example below assumes that the binary and configuration directory are already prepared at the specified paths; adjust the actual username and paths for your environment.

[Unit]
Description=Mihomo proxy core
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
RestartSec=5
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

After saving the service unit, run systemctl daemon-reload, then start the service and inspect its logs. Enable autostart only after one manual run has remained stable. If the service enters a restart loop immediately, stop automatic retries and run the configuration test directly. Continuous restarts can quickly fill the logs and repeatedly modify routes. Keep the old binary and a configuration backup when upgrading so you can roll back if compatibility problems occur.

Environment variables, desktop proxies, and TUN

Terminal tools can use http_proxy, https_proxy, and all_proxy. When both uppercase and lowercase forms exist, different tools may read them differently. A systemd service on a server does not automatically inherit the user's shell configuration, so set these variables explicitly in the service unit or a dedicated environment file. For a single command that needs a proxy, put the variables before that command instead of affecting the entire system.

http_proxy=http://127.0.0.1:7890 \
https_proxy=http://127.0.0.1:7890 \
curl -I https://example.com

all_proxy=socks5://127.0.0.1:7890 git fetch

Linux TUN deployment involves virtual interfaces, policy routing, DNS, and firewall rules. The core needs access to /dev/net/tun and permission to create interfaces and modify network settings. Running inside a container also requires explicitly passing through the TUN device and network capabilities. Do not copy a command that flushes all rules without understanding the current nftables, iptables, or policy-routing setup, as it may interrupt remote access. For router and transparent-gateway scenarios, continue with the OpenWrt deployment overview.

Permissions, DNS, and container boundaries

Running as root indefinitely can bypass some permission issues, but it expands the risks posed by configuration scripts, external rules, and management interfaces. A better approach is to use a dedicated account and grant the minimum required permissions through capabilities or service management. If the management port is local-only, bind it to the loopback address. If LAN access is genuinely required, configure access controls and the host firewall together; do not expose it directly to the public internet.

systemd-resolved, NetworkManager, dnsmasq, and Clash DNS may compete for the local DNS port or forward requests to one another. Map the query path first: which component receives the application request, where the system stub forwards it, which address Clash listens on, and where the upstream nameserver is. When ports conflict, do not blindly disable the system resolver; adjust the listening address or forwarding relationship. Inside a container, 127.0.0.1 points to the container itself, not the host. A container application that needs the host proxy requires an explicit gateway address and listening scope.

7. General configuration files, DNS, rules, and TUN parameters

Configuration file basics

Clash configurations use YAML. Indentation expresses hierarchy, so do not mix tabs arbitrarily. Keep the correct spacing after key-name colons and use hyphens for list items. A configuration usually includes listening ports, operating mode, log level, proxy definitions, proxy groups, rule providers, DNS, and a final rule. Subscription-generated configurations can be long, but during troubleshooting first confirm that the top-level structure is valid, then inspect the specific proxy endpoint.

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info
ipv6: true

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - GEOIP,LAN,DIRECT
  - MATCH,Proxy

The example above illustrates syntax and does not contain a usable proxy definition. mixed-port accepts both HTTP and SOCKS connections; allow-lan controls whether other devices may connect; bind-address limits the listening address; mode selects Rule, Global, or Direct behavior; and log-level controls log detail. Any unused port is acceptable; it does not have to match the example. After changing the listening port, update every external proxy setting as well.

allow-lan and listening addresses

For local-only use, keep allow-lan: false and bind to the loopback address for clarity. If other devices on the same LAN need to use the proxy, enable LAN access and confirm that the client is actually listening on the LAN interface. On other devices, enter the LAN IP of the device running Clash and its mixed-port. The host firewall must allow the relevant port, but it should not be opened unconditionally on every network profile.

Allowing LAN connections does not automatically share traffic with other devices or configure a gateway. Downstream devices must manually use an HTTP/SOCKS proxy, or a gateway must perform transparent forwarding. When a mobile device leaves the current Wi-Fi network, its former LAN address is unreachable, so remove the manual proxy. Opening a listener on public Wi-Fi is not recommended; if it is unavoidable, at minimum restrict the source subnet and ensure the control interface is not exposed as well.

Rule order and proxy groups

Rules are matched from top to bottom, and the first match normally ends evaluation. Put more specific domain, process, and private-network rules before broad rules; MATCH is generally last. DOMAIN matches a full domain, DOMAIN-SUFFIX matches a domain suffix, DOMAIN-KEYWORD matches a keyword, and IP-CIDR matches an address range. IP rules may trigger DNS resolution; whether resolution is skipped depends on the syntax and core support.

A proxy group is not itself a proxy endpoint; it is a logic layer for selecting, testing, or falling back among multiple policies. A select group is chosen manually; url-test updates its selection using a test URL and interval; fallback usually switches according to availability; load-balance distributes connections according to the configured strategy. Test results reflect only the target and network conditions at that moment, not whether every website will work. Very short test intervals increase connections and battery use, so do not probe continuously just to refresh the interface.

proxy-groups:
  - name: Proxy
    type: select
    proxies:
      - Auto
      - DIRECT

  - name: Auto
    type: url-test
    proxies:
      - provider-a
      - provider-b
    url: https://www.gstatic.com/generate_204
    interval: 600

DNS modes and query paths

DNS configuration is not only about resolving domains; it must also keep resolution results, rule matching, and proxy connections consistent. fake-ip mode returns reserved addresses, records the domain mapping in the core, and restores the domain during connection handling. It is often suitable where consistent domain routing matters. redir-host returns real resolution results and is more transparent for some LAN and special applications, but it follows a different routing path. Before choosing, understand whether the client intercepts system DNS and where applications outside Clash send their queries.

nameserver contains regular upstream resolvers, fallback provides another resolution path, and default-nameserver is commonly used to resolve the domains of DoH or DoT upstreams themselves. If an upstream is specified by domain while basic resolution depends on that same upstream, startup dependencies may form a loop. A browser's secure DNS can also bypass the system path. When checking for DNS leaks, inspect the browser settings, system resolver, and Clash logs together rather than relying on a single webpage result.

TUN parameters and strict routing

Common TUN parameters include whether it is enabled, the stack implementation, auto-route, auto-detect-interface, and strict-route. Support varies by platform and core version, and the client interface may generate these fields for you. With auto-route enabled, the core adds the required routes; auto-detect-interface identifies the active exit interface when Wi-Fi, Ethernet, or mobile networks change; strict-route reduces bypasses but is more likely to conflict with virtual machines, containers, or LAN routing.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  strict-route: false
  dns-hijack:
    - any:53

Start with a conservative configuration on first activation. Enable only the necessary fields, confirm that the browser, terminal, LAN, and sleep/wake recovery work, and then adjust strict routing or DNS hijacking. If the system already has an enterprise VPN, virtual switch, container bridge, or multiple default routes, record the routing differences before and after activation. TUN is not a universal replacement when the system proxy fails: it changes the scope of traffic interception but cannot repair an invalid subscription, incorrect policies, or failed remote connections.

8. Configuration updates, connection failures, and recovery

Troubleshoot by layer and change one variable at a time

Troubleshoot in order: basic connectivity, client process, configuration loading, listening port, traffic interception, rule matching, policy connection, and DNS. First switch to Direct or fully exit the client to confirm that the device itself can connect. Then start the client without intercepting system traffic and check that the core runs normally. Next, perform one explicit test through the local proxy port. Only then enable the system proxy or TUN. This separates problems occurring before the core from those introduced by system-level interception.

Change one condition at a time. Do not update the subscription, switch clients, change DNS, enable TUN, and replace the policy simultaneously. If several actions happen together, even recovery will not reveal the cause. Start with info-level client logs; switch briefly to debug only when more detail is necessary. Before sharing logs, remove subscription URLs, authentication fields, proxy addresses, and device information.

Subscription update failures

When a subscription update fails, first check whether the URL is complete, expired, or copied with spaces, and whether the basic network can reach it. HTTP status errors usually come from authorization, rate limits, or server state; connection timeouts may involve DNS, the current proxy chain, or network blocking; a successful download followed by a parse error more likely means the response is not the expected YAML or conversion format. Do not treat repeatedly toggling the system proxy as the only remedy.

If the old configuration still works but the new one cannot update, keep the old configuration and request the subscription URL separately with a browser or curl to inspect the response type. Whether the update uses the current proxy or a direct connection depends on the client; if necessary, switch interception methods temporarily for comparison. When a configuration includes remote rule sets, the main subscription may succeed while resource downloads fail later. Use the log to distinguish the specific URL and resource type.

Startup failures and port conflicts

When the log says address already in use, a listening address or port is occupied. Common causes include two instances of the same client, an old core that did not exit, another proxy using the same port, or a system service starting another instance automatically. On Windows, use netstat and Task Manager; on macOS and Linux, use lsof or ss. Confirm what a process does before stopping it; do not terminate an unknown system process based only on its port number.

# Windows
netstat -ano | findstr :7890

# macOS
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux
ss -lntp | grep 7890

If you decide to change mixed-port, update the client interface, system proxy, environment variables, browser manual proxy, and LAN devices to the new value. If the client actually uses an override configuration, changing only the YAML may be overwritten again at startup. See how to troubleshoot port 7890 conflicts for detailed branches.

Connected, but webpages do not load

First check whether the proxy group has selected an actual policy rather than an empty group or unavailable parent group. Then inspect request logs: no log at all means traffic never entered the client; a rule match followed by connection failure points to the policy or remote endpoint; only domain resolution failures point first to DNS; browser certificate or protocol errors call for checking the system clock, QUIC, certificate stores, and intermediate networks. Switching to Global mode can show whether rules are involved, but it is not necessarily suitable for long-term use.

If only some websites fail, check which rule matched the domain and which final policy was selected. Rules run from top to bottom, so a broad rule earlier in the list may capture traffic intended for a more specific rule later. If only one app fails, check whether it ignores the system proxy, is excluded by per-app routing, or uses UDP or custom DNS. TUN can help verify the interception scope, but logs are still needed to confirm that the request actually entered.

DNS failures and leak checks

When domains fail but IP addresses work, the DNS path is usually the first suspect. Check the system DNS target, the Clash DNS listening port, nameserver reachability, browser secure DNS, and TUN DNS hijacking. Seeing a reserved address in fake-ip mode is not automatically an error; the key question is whether the core intercepts the connection and restores the original domain. If an app bypasses Clash and connects directly to a fake-ip address, it will fail; adjust the interception scope or filter rules.

Do not rely on a single webpage test to detect DNS leaks. Compare the resolution servers before and after enabling Clash, check the client log for the target queries, and use command-line tools to test the system's default resolver. Enterprise networks, mobile networks, and a browser's own encrypted DNS may create additional paths. For the complete procedure, see DNS leak testing and fake-ip configuration in practice.

LAN or virtual machines fail after enabling TUN

TUN changes route priority, while strict routing and DNS hijacking broaden its impact. When LAN access fails, confirm private-address Direct rules first, then check which interface carries the target subnet in the routing table. Virtual machines, Docker, WSL, and container platforms usually create private subnets of their own. If one overlaps with the physical LAN or proxy-reserved addresses, conflicts can occur. Do not use a single device IP as a permanent patch; identify the complete subnet and actual egress.

Disabling strict-route or pausing DNS hijacking can help identify the cause, but record which change restores connectivity. If the issue appears only after sleep, network switching, or VPN reconnection, auto-detect-interface may not have refreshed. Restarting the core or rebuilding TUN is usually more targeted than rebooting the entire device. Linux servers should also be checked for nftables, policy routing, and reverse-path filtering; Windows and macOS users should check other VPNs and security clients.

Build a reversible maintenance routine

Before updating the client or making major configuration changes, keep the currently working configuration, override files, and a record of key settings. Do not back up files containing sensitive subscriptions in public locations. After changes, verify configuration parsing, core startup, a single-port proxy, the system proxy or TUN, DNS, LAN access, and sleep/wake recovery separately. If any step fails, return to the most recent clearly working state instead of layering on more changes.

For a quick first-time setup, return to the Clash quick-start guide. To choose a different client, see the client comparison. Look up terms such as proxy groups, configuration files, fake-ip, and mixed-port in the glossary. A process built around clear download sources, layered configuration storage, one change at a time, and log-based troubleshooting is more reliable than memorizing the fixed location of a control in any particular client interface.